diff --git a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs index aa7aecf2303..ac572c307a2 100644 --- a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs +++ b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs @@ -75,6 +75,31 @@ const SKILLS = { } }; +const CUSTOM_SKILL_CONTENT = { + 'react-spectrum-s2': { + skillNotesMarkdown: + '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.', + embeddedMarkdownPaths: [ + path.join( + REPO_ROOT, + 'packages/dev/s2-docs/skills/react-spectrum-s2/implementation-guidance.md' + ) + ], + guideEntries: [ + { + title: 'Component Decision Tree', + path: 'component-decision-tree.md', + sourcePath: path.join( + REPO_ROOT, + 'packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md' + ), + description: + 'How to choose the right S2 component when requirements do not name one explicitly.' + } + ] + } +}; + /** * Ensure markdown docs are generated */ @@ -100,6 +125,45 @@ function getWellKnownRootForLibrary(sourceDir) { ); } +function getCustomSkillContent(skillName) { + return CUSTOM_SKILL_CONTENT[skillName] ?? null; +} + +function renderCustomMarkdown(markdownPath, replacements = {}) { + let content = fs.readFileSync(markdownPath, 'utf8'); + for (const [token, value] of Object.entries(replacements)) { + content = content.replaceAll(token, value); + } + return content.trim(); +} + +function readCustomEmbeddedMarkdown(skillName, replacements = {}) { + const customContent = getCustomSkillContent(skillName); + if (!customContent?.embeddedMarkdownPaths?.length) { + return ''; + } + + return customContent.embeddedMarkdownPaths + .flatMap((markdownPath) => { + if (!fs.existsSync(markdownPath)) { + console.warn(`Custom skill content not found at ${markdownPath}`); + return []; + } + + return [renderCustomMarkdown(markdownPath, replacements)]; + }) + .filter(Boolean) + .join('\n\n'); +} + +function getCustomGuideEntries(skillName) { + return getCustomSkillContent(skillName)?.guideEntries ?? []; +} + +function getCustomSkillNotesMarkdown(skillName) { + return getCustomSkillContent(skillName)?.skillNotesMarkdown ?? ''; +} + /** * Parse llms.txt to get documentation entries */ @@ -316,34 +380,48 @@ metadata: * Generate the SKILL.md content */ function generateDocsSkillMd(skillConfig, categories, isS2) { + const customGuideEntries = getCustomGuideEntries(skillConfig.name); + const customSkillNotesMarkdown = getCustomSkillNotesMarkdown(skillConfig.name); + const embeddedCustomMarkdown = readCustomEmbeddedMarkdown(skillConfig.name, { + '{{guidesBase}}': 'references/guides/', + '{{componentsBase}}': 'references/components/' + }); + let content = generateFrontmatter(skillConfig); if (isS2) { content += `# React Spectrum S2 (Spectrum 2) 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. - -## Documentation Structure - -The \`references/\` directory contains detailed documentation organized as follows: - `; } else { content += `# React Aria Components 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. +`; + } + + if (customSkillNotesMarkdown) { + content += `\n${customSkillNotesMarkdown}\n`; + } + + if (embeddedCustomMarkdown) { + content += `\n${embeddedCustomMarkdown}\n\n`; + } -## Documentation Structure + content += `## Documentation Structure The \`references/\` directory contains detailed documentation organized as follows: `; - } // Add documentation sections - if (categories.guides.length > 0) { + if (customGuideEntries.length > 0 || categories.guides.length > 0) { content += `### Guides `; + for (const entry of customGuideEntries) { + content += `- [${entry.title}](references/guides/${entry.path})${entry.description ? `: ${entry.description}` : ''}\n`; + } for (const entry of categories.guides) { content += `- [${entry.title}](references/guides/${entry.path})${entry.description ? `: ${entry.description}` : ''}\n`; } @@ -524,10 +602,11 @@ Use these when you need more component-by-component or API-level detail: function copyDocsDocumentation(skillConfig, categories, skillDir) { const refsDir = path.join(skillDir, 'references'); const sourceDir = path.join(MARKDOWN_DOCS_DIST, skillConfig.sourceDir); + const customGuideEntries = getCustomGuideEntries(skillConfig.name); // Create subdirectories only if they have content const subdirs = [ - {name: 'guides', entries: categories.guides}, + {name: 'guides', entries: [...customGuideEntries, ...categories.guides]}, {name: 'components', entries: categories.components}, {name: 'interactions', entries: categories.interactions}, {name: 'utilities', entries: categories.utilities}, @@ -559,6 +638,28 @@ function copyDocsDocumentation(skillConfig, categories, skillDir) { }; // Copy guides + const customContent = getCustomSkillContent(skillConfig.name); + for (const entry of customGuideEntries) { + const sourcePath = + entry.sourcePath || + customContent?.embeddedMarkdownPaths?.find((markdownPath) => + markdownPath.endsWith(entry.path) + ); + if (!sourcePath || !fs.existsSync(sourcePath)) { + continue; + } + + const targetPath = path.join(refsDir, 'guides', entry.path); + fs.mkdirSync(path.dirname(targetPath), {recursive: true}); + fs.writeFileSync( + targetPath, + renderCustomMarkdown(sourcePath, { + '{{guidesBase}}': '', + '{{componentsBase}}': '../components/' + }) + '\n' + ); + } + for (const entry of categories.guides) { copyFile(entry, 'guides'); } diff --git a/packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md b/packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md new file mode 100644 index 00000000000..123400f9b7a --- /dev/null +++ b/packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md @@ -0,0 +1,117 @@ +## Component Decision Tree + +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: + +- Prefer an existing React Spectrum S2 component over a custom component. +- Match the interaction model first, then the visual treatment. +- Prefer the narrowest component that fits the requirement instead of a more general one. +- If two components could work, choose the more standard and accessible pattern. +- 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. + +### Actions and navigation + +- Use `Button` for primary or secondary calls to action and prominent actions. It can also navigate. +- Use `ActionButton` for lower-emphasis actions, toolbar actions, row actions, and compact icon-led actions. +- Use `LinkButton` when the element should navigate like a link but look like a button. +- Use `Link` for inline or standalone text navigation. +- Use `ButtonGroup` or `ActionButtonGroup` only to group related buttons. +- Use `ActionMenu` for a simple "more actions" ellipsis button that opens a menu. +- Use `Menu` when the menu itself is the pattern, especially if you need sections, submenus, selection, links, or a custom trigger arrangement. +- Use `ActionBar` for bulk actions within a collection component. + +### Choosing from options + +- Use `Switch` for turning a setting on or off. +- Use `Checkbox` for a single independent yes or no option. +- Use `CheckboxGroup` for multiple simple visible options where many may be selected. +- Use `RadioGroup` for a small visible mutually exclusive list. +- Use `SelectBoxGroup` when options should stay visible and need richer presentation such as illustrations, labels, or descriptions. +- Use `Picker` for selecting from a collapsible list of known options when typing to search is not important. +- Use `ComboBox` when the user should type to filter options, search a long list, or create an action from the current input. +- Use `SegmentedControl` for a small mutually exclusive view or mode switch. +- Use `ToggleButton` for a single pressed/unpressed control. +- Use `ToggleButtonGroup` for compact formatting-style or tool-style toggles, especially if multi-select may be needed. + +### Text and value input + +- Use `TextField` for single-line plain text input. +- Use `SearchField` for a search query with search-specific clear and submit behavior. +- Use `TextArea` for multi-line text. +- Use `NumberField` for precise numeric entry and stepping. +- Use `Slider` for adjusting one numeric value when direct manipulation is more important than exact typed entry. +- Use `RangeSlider` for adjusting a numeric range. +- Use `DateField` or `TimeField` when keyboard editing of a date or time is the main interaction. +- Use `DatePicker` or `DateRangePicker` when a popover calendar should help with choosing dates. +- Use `Calendar` or `RangeCalendar` when the calendar grid itself is needed without the input field or popover. +- Use `ColorField` to edit a hex color or channel value directly. +- Use `ColorSwatch` to display a chosen color. +- Use `ColorSwatchPicker` to choose from predefined colors. +- Use `ColorArea`, `ColorSlider`, and `ColorWheel` for direct color manipulation. + +### Collections and data views + +- Use `TableView` when users need rows and columns, dense comparison, sortable headers, cell-level content, editable cells, column resizing, or other tabular behaviors. +- Use `ListView` for a flat list of records where each row is the main unit and may include icons, thumbnails, descriptions, and row actions. +- Use `TreeView` when the hierarchy itself must stay visible and expandable in place. +- Use `CardView` for visually rich collections of objects, galleries, or asset browsers with selection and bulk actions. +- Use `TagGroup` for compact tags, tokens, or filters rather than general records. +- Use `TableView` with expandable rows only if the tabular columns still matter after hierarchy is introduced. +- Use `ListView` with `hasChildItems` and breadcrumbs for drill-in navigation when only one level is shown at a time. + +### `TableView` vs `ListView` vs `TreeView` vs `CardView` + +- Choose `TableView` if the user needs to compare fields across columns. +- Choose `ListView` if the user needs a simple vertical list of records with optional secondary content and actions. +- Choose `TreeView` if parent-child structure is the key mental model. +- Choose `CardView` if preview imagery, card layouts, or gallery browsing matter more than dense comparison. + +### Cards + +- Use `Card` for one summarized object, not for an entire selectable collection. +- Use `CardView` when many cards need keyboard navigation, selection, loading states, empty states, or bulk actions. +- Prefer `AssetCard` for files, images, folders, documents, or other assets. +- Prefer `UserCard` for people or profiles. +- Prefer `ProductCard` for products or offers with a clear call to action. +- Use `Card` with `CollectionCardPreview` for grouped assets or a preview collage. +- Use a preview-only `Card` for gallery tiles in a waterfall-style presentation. +- Use a custom `Card` only when the object is still clearly a card but the built-in layouts do not fit the content structure. + +### Structure and disclosure + +- Use `Tabs` when switching between peer sections of content and showing one panel at a time. +- Use `SegmentedControl` instead of `Tabs` when switching app modes or views rather than full content panels. +- Use `Disclosure` for one collapsible section. +- Use `Accordion` for a group of related collapsible sections. +- Use `Breadcrumbs` to show navigation depth or hierarchy location. +- Use `Divider` to separate adjacent groups of content. + +### Overlays, help, and feedback + +- Use `Tooltip` for a short description of a focusable element. Do not rely on it for essential content. +- Use `ContextualHelp` for additional explanation near content, especially for non-interactive or disabled UI. +- Use `Popover` for interactive contextual content anchored to a nearby trigger when a modal is unnecessary. +- Use `Dialog` for modal tasks or workflows. +- Use `AlertDialog` for confirmations, destructive actions, and critical messages that must be acknowledged. +- Use `FullscreenDialog` for complex workflows that need substantially more space. +- Use `CustomDialog` only when the standard dialog layouts do not fit. +- Use `InlineAlert` for a persistent non-modal message associated with content in the current view. +- Use `Toast` for temporary global feedback after an action. + +### Status, loading, media, and empty states + +- Use `Badge` for compact color-coded metadata. +- Use `StatusLight` for an object's current status. +- Use `ProgressBar` or `ProgressCircle` for task progress over time. +- Use `Meter` for a level or quantity within a known range when it is not task progress. +- Use `Skeleton` for loading placeholders. +- Use `Avatar` or `AvatarGroup` for people and participants. +- Use `Image` for images that need loading and error handling. +- Use `IllustratedMessage` for empty states or error pages. +- Use `DropZone` for drag-and-drop file or object upload targets. +- Use `Form` to provide layout, submission, and validation structure for grouped fields. + +### Last-resort custom components + +- 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. +- Build custom components with React Aria Components for behavior and accessibility, and the S2 `style` macro for Spectrum styling. +- Do not bypass an existing S2 component just to apply unsupported visual customization. diff --git a/packages/dev/s2-docs/skills/react-spectrum-s2/implementation-guidance.md b/packages/dev/s2-docs/skills/react-spectrum-s2/implementation-guidance.md new file mode 100644 index 00000000000..f770f84ba43 --- /dev/null +++ b/packages/dev/s2-docs/skills/react-spectrum-s2/implementation-guidance.md @@ -0,0 +1,153 @@ +## Styling + +Use React Spectrum S2 components and the S2 `style` macro as the default styling approach. + +- Import the `style` macro using the `{type: 'macro'}` import attribute: `import {style} from '@react-spectrum/s2/style' with {type: 'macro'};` +- Remember that the `style` macro runs at build time and returns class names. +- Avoid introducing Tailwind, `radix-ui`, `shadcn/ui`, or any other third-party design system components in S2 implementations. +- Prefer S2 components first, and use their `styles` prop only for the supported layout-style properties. +- For generic layouts (flex, grid, etc.), use native HTML elements with the `style` macro. +- For card-style layouts, use the S2 `Card` component instead of building something custom. +- IMPORTANT: Avoid using the `UNSAFE_style` and `UNSAFE_className` props. + +For React Spectrum components, the `styles` prop is intentionally limited. Supported properties are: + +- `margin`, `marginStart`, `marginEnd`, `marginTop`, `marginBottom`, `marginX`, `marginY` +- `width`, `minWidth`, `maxWidth` +- `flexGrow`, `flexShrink`, `flexBasis` +- `justifySelf`, `alignSelf`, `order` +- `gridArea`, `gridRow`, `gridRowStart`, `gridRowEnd`, `gridColumn`, `gridColumnStart`, `gridColumnEnd` +- `position`, `zIndex`, `top`, `bottom`, `inset`, `insetX`, `insetY`, `insetStart`, `insetEnd` +- `visibility` +- `height`, `minHeight`, `maxHeight` (only in specific components without an intrinsic height) + +Example: + +```tsx +import {style} from '@react-spectrum/s2/style' with {type: 'macro'}; +import {Button} from '@react-spectrum/s2'; + + +``` + +When styling native HTML elements or React Aria Components, use `className={style(...)}` instead of the limited `styles` prop. In those cases, you are not limited to the React Spectrum component property subset. + +Example: + +```tsx +import {style} from '@react-spectrum/s2/style' with {type: 'macro'}; +import {Checkbox} from 'react-aria-components'; + +
+

Preferences

+ +
+``` + +The `style` macro supports runtime conditions: + +```tsx +import {style} from '@react-spectrum/s2/style' with {type: 'macro'}; + +const styles = style({ + backgroundColor: { + variant: { + primary: 'accent', + secondary: 'neutral' + } + } +}); + +function MyComponent({variant}: {variant: 'primary' | 'secondary'}) { + return
+} +``` + +Boolean conditions starting with `is` or `allows` can be used directly without nesting: + +```tsx +const styles = style({ + backgroundColor: { + default: 'gray-100', + isSelected: 'gray-900', + allowsRemoving: 'gray-400' + } +}); + +
+``` + +Note: +- Base spacing values (for `margin`, `gap`, etc.): Use pixels following a 4px grid (`0`, `2`, `4`, `8`, `12`, `16`...) + +See [Styling]({{guidesBase}}styling.md) for the full guide and [Style Macro]({{guidesBase}}style-macro.md) for the full property and utility reference. + +If you encounter issues related to the `style` macro import, see the 'Framework setup' section of the [Getting started]({{guidesBase}}getting-started.md) guide. + +## Typography + +Avoid using `Text`/`Heading`/`Content` as standalone typography primitives. These should only be used inside specific React Spectrum components where they inherit the intended slots and default styles. + +- Use `Text`/`Heading`/`Content` inside components like cards, lists, pickers, menus, tabs, and other Spectrum composition APIs where `slot="label"`, `slot="description"`, or default/implicit Text slots are used. Component docs will have examples of these. +- For standalone headings, body copy, captions, and other page-level typography, use native HTML elements plus the `style` macro. + +Example: + +```tsx +import {style} from '@react-spectrum/s2/style' with {type: 'macro'}; + +
+

+ Project overview +

+

+ Review status, owners, and upcoming milestones. +

+

+ Last updated 2 hours ago +

+
+``` + +See [Style Macro]({{guidesBase}}style-macro.md) for the available typography tokens and related text styling options. + +## Icons + +Use React Spectrum's built-in icons and illustrations. + +- Import icons from `@react-spectrum/s2/icons/...` +- Import illustrations from `@react-spectrum/s2/illustrations/...` +- Avoid introducing third-party icon libraries such as `lucide-react`, `phosphor-icons`, or `heroicons` + +Commonly used icons include `AlertTriangle`, `Close`, `ChevronDown`, `Checkmark`, `Preview`, `CheckmarkCircle`, `Add`, `ChevronUp`, `Data`, `FileText`, `InfoCircle`, `OpenIn`, `Chat`, and `Code`. + +Example icon: + +```tsx +import AlertTriangle from '@react-spectrum/s2/icons/AlertTriangle'; + + +``` + +Example illustrations: + +```tsx +import DropToUpload from '@react-spectrum/s2/illustrations/gradient/generic1/DropToUpload'; + + +``` + +- Note that illustrations can be in a Gradient or Linear style. +- Gradient illustrations can include Generic 1 and Generic 2 variants. + +See [Icons]({{componentsBase}}icons.md) and [Illustrations]({{componentsBase}}illustrations.md) for the full catalogs and usage guidance.