Skip to content

Commit 5c5bda5

Browse files
reidbarberreidbarber
authored
docs: improve S2 agent skill (adobe#9908)
* improve S2 agent skill * fix typo
1 parent 988c120 commit 5c5bda5

File tree

3 files changed

+380
-9
lines changed

3 files changed

+380
-9
lines changed

‎packages/dev/s2-docs/scripts/generateAgentSkills.mjs‎

Lines changed: 110 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,31 @@ const SKILLS = {
7575
}
7676
};
7777

78+
const CUSTOM_SKILL_CONTENT = {
79+
'react-spectrum-s2': {
80+
skillNotesMarkdown:
81+
'If the requirements do not clearly specify which React Spectrum component to use, consult the [Component Decision Tree](references/guides/component-decision-tree.md) before choosing a component.',
82+
embeddedMarkdownPaths: [
83+
path.join(
84+
REPO_ROOT,
85+
'packages/dev/s2-docs/skills/react-spectrum-s2/implementation-guidance.md'
86+
)
87+
],
88+
guideEntries: [
89+
{
90+
title: 'Component Decision Tree',
91+
path: 'component-decision-tree.md',
92+
sourcePath: path.join(
93+
REPO_ROOT,
94+
'packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md'
95+
),
96+
description:
97+
'How to choose the right S2 component when requirements do not name one explicitly.'
98+
}
99+
]
100+
}
101+
};
102+
78103
/**
79104
* Ensure markdown docs are generated
80105
*/
@@ -100,6 +125,45 @@ function getWellKnownRootForLibrary(sourceDir) {
100125
);
101126
}
102127

128+
function getCustomSkillContent(skillName) {
129+
return CUSTOM_SKILL_CONTENT[skillName] ?? null;
130+
}
131+
132+
function renderCustomMarkdown(markdownPath, replacements = {}) {
133+
let content = fs.readFileSync(markdownPath, 'utf8');
134+
for (const [token, value] of Object.entries(replacements)) {
135+
content = content.replaceAll(token, value);
136+
}
137+
return content.trim();
138+
}
139+
140+
function readCustomEmbeddedMarkdown(skillName, replacements = {}) {
141+
const customContent = getCustomSkillContent(skillName);
142+
if (!customContent?.embeddedMarkdownPaths?.length) {
143+
return '';
144+
}
145+
146+
return customContent.embeddedMarkdownPaths
147+
.flatMap((markdownPath) => {
148+
if (!fs.existsSync(markdownPath)) {
149+
console.warn(`Custom skill content not found at ${markdownPath}`);
150+
return [];
151+
}
152+
153+
return [renderCustomMarkdown(markdownPath, replacements)];
154+
})
155+
.filter(Boolean)
156+
.join('\n\n');
157+
}
158+
159+
function getCustomGuideEntries(skillName) {
160+
return getCustomSkillContent(skillName)?.guideEntries ?? [];
161+
}
162+
163+
function getCustomSkillNotesMarkdown(skillName) {
164+
return getCustomSkillContent(skillName)?.skillNotesMarkdown ?? '';
165+
}
166+
103167
/**
104168
* Parse llms.txt to get documentation entries
105169
*/
@@ -316,34 +380,48 @@ metadata:
316380
* Generate the SKILL.md content
317381
*/
318382
function generateDocsSkillMd(skillConfig, categories, isS2) {
383+
const customGuideEntries = getCustomGuideEntries(skillConfig.name);
384+
const customSkillNotesMarkdown = getCustomSkillNotesMarkdown(skillConfig.name);
385+
const embeddedCustomMarkdown = readCustomEmbeddedMarkdown(skillConfig.name, {
386+
'{{guidesBase}}': 'references/guides/',
387+
'{{componentsBase}}': 'references/components/'
388+
});
389+
319390
let content = generateFrontmatter(skillConfig);
320391

321392
if (isS2) {
322393
content += `# React Spectrum S2 (Spectrum 2)
323394
324395
React Spectrum S2 is Adobe's implementation of the Spectrum 2 design system in React. It provides a collection of accessible, adaptive, and high-quality UI components.
325-
326-
## Documentation Structure
327-
328-
The \`references/\` directory contains detailed documentation organized as follows:
329-
330396
`;
331397
} else {
332398
content += `# React Aria Components
333399
334400
React Aria Components is a library of unstyled, accessible UI components that you can style with any CSS solution. Built on top of React Aria hooks, it provides the accessibility and behavior without prescribing any visual design.
401+
`;
402+
}
403+
404+
if (customSkillNotesMarkdown) {
405+
content += `\n${customSkillNotesMarkdown}\n`;
406+
}
407+
408+
if (embeddedCustomMarkdown) {
409+
content += `\n${embeddedCustomMarkdown}\n\n`;
410+
}
335411

336-
## Documentation Structure
412+
content += `## Documentation Structure
337413
338414
The \`references/\` directory contains detailed documentation organized as follows:
339415
340416
`;
341-
}
342417

343418
// Add documentation sections
344-
if (categories.guides.length > 0) {
419+
if (customGuideEntries.length > 0 || categories.guides.length > 0) {
345420
content += `### Guides
346421
`;
422+
for (const entry of customGuideEntries) {
423+
content += `- [${entry.title}](references/guides/${entry.path})${entry.description ? `: ${entry.description}` : ''}\n`;
424+
}
347425
for (const entry of categories.guides) {
348426
content += `- [${entry.title}](references/guides/${entry.path})${entry.description ? `: ${entry.description}` : ''}\n`;
349427
}
@@ -524,10 +602,11 @@ Use these when you need more component-by-component or API-level detail:
524602
function copyDocsDocumentation(skillConfig, categories, skillDir) {
525603
const refsDir = path.join(skillDir, 'references');
526604
const sourceDir = path.join(MARKDOWN_DOCS_DIST, skillConfig.sourceDir);
605+
const customGuideEntries = getCustomGuideEntries(skillConfig.name);
527606

528607
// Create subdirectories only if they have content
529608
const subdirs = [
530-
{name: 'guides', entries: categories.guides},
609+
{name: 'guides', entries: [...customGuideEntries, ...categories.guides]},
531610
{name: 'components', entries: categories.components},
532611
{name: 'interactions', entries: categories.interactions},
533612
{name: 'utilities', entries: categories.utilities},
@@ -559,6 +638,28 @@ function copyDocsDocumentation(skillConfig, categories, skillDir) {
559638
};
560639

561640
// Copy guides
641+
const customContent = getCustomSkillContent(skillConfig.name);
642+
for (const entry of customGuideEntries) {
643+
const sourcePath =
644+
entry.sourcePath ||
645+
customContent?.embeddedMarkdownPaths?.find((markdownPath) =>
646+
markdownPath.endsWith(entry.path)
647+
);
648+
if (!sourcePath || !fs.existsSync(sourcePath)) {
649+
continue;
650+
}
651+
652+
const targetPath = path.join(refsDir, 'guides', entry.path);
653+
fs.mkdirSync(path.dirname(targetPath), {recursive: true});
654+
fs.writeFileSync(
655+
targetPath,
656+
renderCustomMarkdown(sourcePath, {
657+
'{{guidesBase}}': '',
658+
'{{componentsBase}}': '../components/'
659+
}) + '\n'
660+
);
661+
}
662+
562663
for (const entry of categories.guides) {
563664
copyFile(entry, 'guides');
564665
}

‎packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
## Component Decision Tree
2+
3+
If the user does not specify which component they would like to use, choose one based on the requirements. Use the following as a guide:
4+
5+
- Prefer an existing React Spectrum S2 component over a custom component.
6+
- Match the interaction model first, then the visual treatment.
7+
- Prefer the narrowest component that fits the requirement instead of a more general one.
8+
- If two components could work, choose the more standard and accessible pattern.
9+
- Reach for React Aria Components plus the S2 `style` macro only as a last resort when no S2 component fits the behavior or layout, or if the user specifically asks for a custom component.
10+
11+
### Actions and navigation
12+
13+
- Use `Button` for primary or secondary calls to action and prominent actions. It can also navigate.
14+
- Use `ActionButton` for lower-emphasis actions, toolbar actions, row actions, and compact icon-led actions.
15+
- Use `LinkButton` when the element should navigate like a link but look like a button.
16+
- Use `Link` for inline or standalone text navigation.
17+
- Use `ButtonGroup` or `ActionButtonGroup` only to group related buttons.
18+
- Use `ActionMenu` for a simple "more actions" ellipsis button that opens a menu.
19+
- Use `Menu` when the menu itself is the pattern, especially if you need sections, submenus, selection, links, or a custom trigger arrangement.
20+
- Use `ActionBar` for bulk actions within a collection component.
21+
22+
### Choosing from options
23+
24+
- Use `Switch` for turning a setting on or off.
25+
- Use `Checkbox` for a single independent yes or no option.
26+
- Use `CheckboxGroup` for multiple simple visible options where many may be selected.
27+
- Use `RadioGroup` for a small visible mutually exclusive list.
28+
- Use `SelectBoxGroup` when options should stay visible and need richer presentation such as illustrations, labels, or descriptions.
29+
- Use `Picker` for selecting from a collapsible list of known options when typing to search is not important.
30+
- Use `ComboBox` when the user should type to filter options, search a long list, or create an action from the current input.
31+
- Use `SegmentedControl` for a small mutually exclusive view or mode switch.
32+
- Use `ToggleButton` for a single pressed/unpressed control.
33+
- Use `ToggleButtonGroup` for compact formatting-style or tool-style toggles, especially if multi-select may be needed.
34+
35+
### Text and value input
36+
37+
- Use `TextField` for single-line plain text input.
38+
- Use `SearchField` for a search query with search-specific clear and submit behavior.
39+
- Use `TextArea` for multi-line text.
40+
- Use `NumberField` for precise numeric entry and stepping.
41+
- Use `Slider` for adjusting one numeric value when direct manipulation is more important than exact typed entry.
42+
- Use `RangeSlider` for adjusting a numeric range.
43+
- Use `DateField` or `TimeField` when keyboard editing of a date or time is the main interaction.
44+
- Use `DatePicker` or `DateRangePicker` when a popover calendar should help with choosing dates.
45+
- Use `Calendar` or `RangeCalendar` when the calendar grid itself is needed without the input field or popover.
46+
- Use `ColorField` to edit a hex color or channel value directly.
47+
- Use `ColorSwatch` to display a chosen color.
48+
- Use `ColorSwatchPicker` to choose from predefined colors.
49+
- Use `ColorArea`, `ColorSlider`, and `ColorWheel` for direct color manipulation.
50+
51+
### Collections and data views
52+
53+
- Use `TableView` when users need rows and columns, dense comparison, sortable headers, cell-level content, editable cells, column resizing, or other tabular behaviors.
54+
- Use `ListView` for a flat list of records where each row is the main unit and may include icons, thumbnails, descriptions, and row actions.
55+
- Use `TreeView` when the hierarchy itself must stay visible and expandable in place.
56+
- Use `CardView` for visually rich collections of objects, galleries, or asset browsers with selection and bulk actions.
57+
- Use `TagGroup` for compact tags, tokens, or filters rather than general records.
58+
- Use `TableView` with expandable rows only if the tabular columns still matter after hierarchy is introduced.
59+
- Use `ListView` with `hasChildItems` and breadcrumbs for drill-in navigation when only one level is shown at a time.
60+
61+
### `TableView` vs `ListView` vs `TreeView` vs `CardView`
62+
63+
- Choose `TableView` if the user needs to compare fields across columns.
64+
- Choose `ListView` if the user needs a simple vertical list of records with optional secondary content and actions.
65+
- Choose `TreeView` if parent-child structure is the key mental model.
66+
- Choose `CardView` if preview imagery, card layouts, or gallery browsing matter more than dense comparison.
67+
68+
### Cards
69+
70+
- Use `Card` for one summarized object, not for an entire selectable collection.
71+
- Use `CardView` when many cards need keyboard navigation, selection, loading states, empty states, or bulk actions.
72+
- Prefer `AssetCard` for files, images, folders, documents, or other assets.
73+
- Prefer `UserCard` for people or profiles.
74+
- Prefer `ProductCard` for products or offers with a clear call to action.
75+
- Use `Card` with `CollectionCardPreview` for grouped assets or a preview collage.
76+
- Use a preview-only `Card` for gallery tiles in a waterfall-style presentation.
77+
- Use a custom `Card` only when the object is still clearly a card but the built-in layouts do not fit the content structure.
78+
79+
### Structure and disclosure
80+
81+
- Use `Tabs` when switching between peer sections of content and showing one panel at a time.
82+
- Use `SegmentedControl` instead of `Tabs` when switching app modes or views rather than full content panels.
83+
- Use `Disclosure` for one collapsible section.
84+
- Use `Accordion` for a group of related collapsible sections.
85+
- Use `Breadcrumbs` to show navigation depth or hierarchy location.
86+
- Use `Divider` to separate adjacent groups of content.
87+
88+
### Overlays, help, and feedback
89+
90+
- Use `Tooltip` for a short description of a focusable element. Do not rely on it for essential content.
91+
- Use `ContextualHelp` for additional explanation near content, especially for non-interactive or disabled UI.
92+
- Use `Popover` for interactive contextual content anchored to a nearby trigger when a modal is unnecessary.
93+
- Use `Dialog` for modal tasks or workflows.
94+
- Use `AlertDialog` for confirmations, destructive actions, and critical messages that must be acknowledged.
95+
- Use `FullscreenDialog` for complex workflows that need substantially more space.
96+
- Use `CustomDialog` only when the standard dialog layouts do not fit.
97+
- Use `InlineAlert` for a persistent non-modal message associated with content in the current view.
98+
- Use `Toast` for temporary global feedback after an action.
99+
100+
### Status, loading, media, and empty states
101+
102+
- Use `Badge` for compact color-coded metadata.
103+
- Use `StatusLight` for an object's current status.
104+
- Use `ProgressBar` or `ProgressCircle` for task progress over time.
105+
- Use `Meter` for a level or quantity within a known range when it is not task progress.
106+
- Use `Skeleton` for loading placeholders.
107+
- Use `Avatar` or `AvatarGroup` for people and participants.
108+
- Use `Image` for images that need loading and error handling.
109+
- Use `IllustratedMessage` for empty states or error pages.
110+
- Use `DropZone` for drag-and-drop file or object upload targets.
111+
- Use `Form` to provide layout, submission, and validation structure for grouped fields.
112+
113+
### Last-resort custom components
114+
115+
- Only create a custom component when no S2 component matches the required interaction pattern, or when the needed layout cannot be achieved by composing existing S2 components.
116+
- Build custom components with React Aria Components for behavior and accessibility, and the S2 `style` macro for Spectrum styling.
117+
- Do not bypass an existing S2 component just to apply unsupported visual customization.

0 commit comments

Comments
 (0)