diff --git a/.changeset/README.md b/.changeset/README.md index e5b6d8d6..2424ab89 100644 --- a/.changeset/README.md +++ b/.changeset/README.md @@ -6,3 +6,21 @@ find the full documentation for it [in our repository](https://github.com/change We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) + +## Publishing a new package (first release) + +Releases use GitHub Actions with **OIDC** and **provenance**. npm trusted publishing expects the package to already exist for the repo’s OIDC identity. For a **new** package that has never been published: + +1. **Set the package to a placeholder version** (e.g. `0.0.0`) in its `package.json`, and add `publishConfig`, `repository`, and `files` so it’s publish-ready. + +2. **Publish the placeholder once** to create the package on npm (this establishes the package and links it for OIDC): + ```bash + cd tools/ + npm login # if your token is expired + npm publish --provenance=false + ``` + Use your own npm auth for this one-time publish. **Provenance** only works in CI (GitHub Actions); locally you must pass `--provenance=false` or you’ll get “Automatic provenance generation not supported for provider: null”. After this, the package exists on npm and CI can publish future versions with OIDC and provenance. + +3. **Add a changeset** for the real first version (e.g. `1.0.0`), merge the release PR, and let the [Release workflow](.github/workflows/release.yml) run `pnpm release`. That publish will use OIDC and provenance. + +Do not skip the placeholder publish and go straight to a 1.0.0 changeset in CI if the package has never been published—CI may fail with permission or package-not-found errors. diff --git a/.changeset/s2-docs-mcp-initial-release.md b/.changeset/s2-docs-mcp-initial-release.md new file mode 100644 index 00000000..39e073e9 --- /dev/null +++ b/.changeset/s2-docs-mcp-initial-release.md @@ -0,0 +1,13 @@ +--- +"@adobe/s2-docs-mcp": major +--- + +Initial release of S2 Docs MCP server and Spectrum 2 documentation. + +This adds comprehensive Spectrum 2 documentation to the monorepo: +- **102 markdown pages** with YAML frontmatter scraped from s2.spectrum.corp.adobe.com +- **MCP server** (`@adobe/s2-docs-mcp`) providing AI assistants with structured access to + S2 component docs via tools: list-s2-components, get-s2-component, search-s2-docs, + find-s2-component-by-use-case, get-s2-stats +- **Transform scripts** (`tools/s2-docs-transformer`) for maintaining frontmatter and scraping + workflow diff --git a/.lintstagedrc.js b/.lintstagedrc.js index 587c13a9..3d1d72ef 100644 --- a/.lintstagedrc.js +++ b/.lintstagedrc.js @@ -8,14 +8,19 @@ export default { if (processableFiles.length === 0) return []; // Use -o flag (no path) to write back to same file return processableFiles.map( - (file) => `remark ${file} --use remark-gfm --use remark-github -o`, + (file) => + `remark ${file} --use remark-frontmatter --use remark-gfm --use remark-github -o`, ); }, "!**/pnpm-lock.yaml": [], "!**/package-lock.json": [], "!**/yarn.lock": [], ".changeset/*.md": (files) => { - // Only run changeset linter on changeset files - return files.map((file) => `pnpm changeset-lint check-file ${file}`); + // Only run changeset linter on actual changeset files, not README.md + const changesetFiles = files.filter((file) => !file.endsWith("README.md")); + if (changesetFiles.length === 0) return []; + return changesetFiles.map( + (file) => `pnpm changeset-lint check-file ${file}`, + ); }, }; diff --git a/README.md b/README.md index 45f2246e..024cde29 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Packages in this monorepo: * [Spectrum S2 Tokens Viewer](docs/s2-tokens-viewer/) an enhanced token viewer with component usage analysis for Spectrum 2 tokens. * [Spectrum Tokens Docs](docs/site/) a static site to show the component options API and other token data. * [Release Timeline Visualization](docs/release-timeline/) interactive charts showing release frequency and development activity patterns. Published as a [static site](https://opensource.adobe.com/spectrum-design-data/release-timeline/). +* [Spectrum 2 Documentation](docs/s2-docs/) comprehensive component guides and design principles from s2.spectrum.corp.adobe.com. ## Development Tools @@ -39,6 +40,7 @@ Packages in this monorepo: * [Transform Tokens JSON](tools/transform-tokens-json/) utilities for merging and transforming token data between formats. * [Token Manifest Builder](tools/token-manifest-builder/) generates manifest files for token distribution. * [Spectrum Design Data MCP](tools/spectrum-design-data-mcp/) Model Context Protocol server providing AI assistants with structured access to Spectrum design system data. +* [S2 Docs MCP](tools/s2-docs-mcp/) MCP server providing AI assistants with access to Spectrum 2 component documentation and design guidelines. ## Setup monorepo locally diff --git a/docs/s2-docs/INDEX.md b/docs/s2-docs/INDEX.md new file mode 100644 index 00000000..2b8430e0 --- /dev/null +++ b/docs/s2-docs/INDEX.md @@ -0,0 +1,166 @@ +# Spectrum 2 Documentation - Index + +> Complete offline archive. Last full update: 2026-02-12 +> Source: +> Part of the [Spectrum Design Data](https://github.com/adobe/spectrum-design-data) monorepo. + +**Total pages: 100** + +## Fundamentals (3) + +* [Home](fundamentals/home.md) +* [Introduction](fundamentals/introduction.md) +* [Principles](fundamentals/principles.md) + +## Designing with Spectrum 2 (25) + +### Core Concepts + +* [Attention hierarchy](designing/attention-hierarchy.md) + +### Color (3) + +* [Grays](designing/grays.md) +* [Colors](designing/colors.md) +* [Background layers](designing/background-layers.md) + +### Typography (2) + +* [Fundamentals](designing/typography-fundamentals.md) +* [Fonts](designing/fonts.md) + +### Layout & Styling + +* [Object styles](designing/object-styles.md) +* [Spacing](designing/spacing.md) +* [States](designing/states.md) +* [Containers](designing/containers.md) + +### App Frame (10) + +* [S2 App Frame](designing/s2-app-frame.md) +* [Overview](designing/app-frame-overview.md) +* [Header](designing/app-frame-header.md) +* [Side navigation](designing/app-frame-side-navigation.md) +* [Content area](designing/app-frame-content-area.md) +* [Creating bluelines](designing/app-frame-creating-bluelines.md) +* [Browsing context: Content area](designing/s2-app-frame-content-area-browsing-context.md) +* [Browsing context: Creating bluelines](designing/s2-app-frame-creating-bluelines-browsing-context.md) +* [Browsing context: Header](designing/s2-app-frame-header-browsing-context.md) +* [Browsing context: Side navigation](designing/s2-app-frame-side-navigation-browsing-context.md) + +### Visual Elements + +* [Brand](designing/brand.md) +* [Icons: Fundamentals](designing/icon-fundamentals.md) +* [Icons: Using icons](designing/using-icons.md) +* [Illustrations](designing/illustrations.md) +* [Motion](designing/motion.md) + +## Developing with Spectrum 2 (1) + +* [Developer overview](developing/developer-overview.md) + +## Support (2) + +* [FAQs](support/faqs.md) +* [Resources](support/resources.md) + +## Components (69) + +### Actions (9) + +* [Action bar](components/actions/action-bar.md) +* [Action button](components/actions/action-button.md) +* [Action group](components/actions/action-group.md) +* [Button](components/actions/button.md) +* [Button group](components/actions/button-group.md) +* [Close button](components/actions/close-button.md) +* [Link](components/actions/link.md) +* [List view](components/actions/list-view.md) +* [Menu](components/actions/menu.md) + +### Containers (5) + +* [Cards](components/containers/cards.md) +* [Divider](components/containers/divider.md) +* [Popover](components/containers/popover.md) +* [Standard panel](components/containers/standard-panel.md) +* [Table](components/containers/table.md) + +### Feedback (11) + +* [Alert banner](components/feedback/alert-banner.md) +* [Alert dialog](components/feedback/alert-dialog.md) +* [Coach indicator](components/feedback/coach-indicator.md) +* [Coach mark](components/feedback/coach-mark.md) +* [Contextual help](components/feedback/contextual-help.md) +* [Illustrated message](components/feedback/illustrated-message.md) +* [In-line alert](components/feedback/in-line-alert.md) +* [Standard dialog](components/feedback/standard-dialog.md) +* [Takeover dialog](components/feedback/takeover-dialog.md) +* [Toast](components/feedback/toast.md) +* [Tooltip](components/feedback/tooltip.md) + +### Inputs (31) + +* [Calendar](components/inputs/calendar.md) +* [Checkbox](components/inputs/checkbox.md) +* [Checkbox group](components/inputs/checkbox-group.md) +* [Color area](components/inputs/color-area.md) +* [Color handle](components/inputs/color-handle.md) +* [Color handle and loupe](components/inputs/color-handle-and-loupe.md) +* [Color slider](components/inputs/color-slider.md) +* [Color wheel](components/inputs/color-wheel.md) +* [Combo box](components/inputs/combo-box.md) +* [Date picker](components/inputs/date-picker.md) +* [Drop zone](components/inputs/drop-zone.md) +* [Field label](components/inputs/field-label.md) +* [Help text](components/inputs/help-text.md) +* [Number field](components/inputs/number-field.md) +* [Picker](components/inputs/picker.md) +* [Radio button](components/inputs/radio-button.md) +* [Radio group](components/inputs/radio-group.md) +* [Rating](components/inputs/rating.md) +* [Search field](components/inputs/search-field.md) +* [Segmented control](components/inputs/segmented-control.md) +* [Select box](components/inputs/select-box.md) +* [Slider](components/inputs/slider.md) +* [Swatch](components/inputs/swatch.md) +* [Swatch group](components/inputs/swatch-group.md) +* [Switch](components/inputs/switch.md) +* [Tag](components/inputs/tag.md) +* [Tag field](components/inputs/tag-field.md) +* [Tag group](components/inputs/tag-group.md) +* [Text area](components/inputs/text-area.md) +* [Text field](components/inputs/text-field.md) +* [Thumbnail](components/inputs/thumbnail.md) + +### Navigation (5) + +* [Accordion](components/navigation/accordion.md) +* [Breadcrumbs](components/navigation/breadcrumbs.md) +* [Side navigation](components/navigation/side-navigation.md) +* [Tabs](components/navigation/tabs.md) +* [Tree view](components/navigation/tree-view.md) + +### Status (8) + +* [Avatar](components/status/avatar.md) +* [Avatar group](components/status/avatar-group.md) +* [Badge](components/status/badge.md) +* [Meter](components/status/meter.md) +* [Progress bar](components/status/progress-bar.md) +* [Progress circle](components/status/progress-circle.md) +* [Status light](components/status/status-light.md) +* [Steplist](components/status/steplist.md) + +*** + +## Notes + +* All documentation is fully offline and accessible without VPN/authentication +* Content is current as of last update (2026-02-12); new pages may have placeholder content until scraped +* Some pages contain links to internal Adobe resources that still require authentication +* Screenshots and diagrams are referenced but not included in the markdown files +* For MCP setup and integration, see this project's [README](README.md). diff --git a/docs/s2-docs/README.md b/docs/s2-docs/README.md new file mode 100644 index 00000000..d3bc9eca --- /dev/null +++ b/docs/s2-docs/README.md @@ -0,0 +1,85 @@ +# Spectrum 2 Documentation + +Scraped documentation from Adobe's Spectrum 2 design system. + +## Overview + +This project contains 102 pages of S2 documentation with YAML frontmatter, including component guides, design principles, and development resources. + +## Structure + +* `components/` - 69 component docs (actions, containers, feedback, inputs, navigation, status) +* `designing/` - 25 design guidelines (color, typography, app frame, etc.) +* `fundamentals/` - 3 core pages (home, introduction, principles) +* `developing/` - 1 developer overview +* `support/` - 4 support pages (FAQs, contact, resources, quarterly recap) + +## Using with AI / Cursor + +You can give AI assistants access to this documentation in several ways: + +### MCP (recommended) + +Enable the **S2 Docs MCP** server so the AI can query docs via tools (search, get component, list by category). See [MCP Server Integration](#mcp-server-integration) below. + +### Cursor [**@Files**](https://github.com/Files) & Folders + +In Cursor chat, use **[**@Files**](https://github.com/Files) & Folders** and reference the `docs/s2-docs` folder (or a subfolder like `docs/s2-docs/components/actions`) to attach markdown files as context. The AI can then read the component guides and design guidelines directly. + +### Cursor [**@Docs**](https://github.com/Docs) + +If this documentation is published at a URL (e.g. GitHub Pages), you can add it to Cursor’s [@Docs](https://cursor.com/docs/context/mentions#docs): type **[**@Docs**](https://github.com/Docs)** in chat → **Add new doc** → paste the URL. Cursor will index the site for use in chat. Manage added docs under **Cursor Settings → Indexing & Docs**. + +## MCP Server Integration + +AI tools can query this documentation via the S2 Docs MCP server. + +### Setup + +```bash +# Install MCP server +cd ~/Spectrum/spectrum-design-data/tools/s2-docs-mcp +pnpm install + +# Configure in .cursor/mcp.json +{ + "mcpServers": { + "s2-docs": { + "command": "node", + "args": [ + "/Users/YOUR_USERNAME/Spectrum/spectrum-design-data/tools/s2-docs-mcp/src/cli.js" + ] + } + } +} +``` + +### Available Tools + +* `list-s2-components` - Browse components by category +* `get-s2-component` - Get full component documentation +* `search-s2-docs` - Search across all docs +* `find-s2-component-by-use-case` - Find components by use case +* `get-s2-stats` - Documentation coverage statistics + +See [tools/s2-docs-mcp](../../tools/s2-docs-mcp/README.md) for details. + +## Maintenance + +**Updating documentation:** + +```bash +# Re-run transform scripts to update frontmatter +cd ../../tools/s2-docs-transformer +pnpm run process-all + +# Regenerate component index +cd ../s2-docs-mcp +node src/batch-scraper.js index +``` + +**Scraping new content:** See the [s2-docs-transformer README](../../tools/s2-docs-transformer/README.md) for scraping and transformation tools. + +## License + +Apache-2.0 © Adobe diff --git a/docs/s2-docs/components/actions/action-bar.md b/docs/s2-docs/components/actions/action-bar.md new file mode 100644 index 00000000..db652337 --- /dev/null +++ b/docs/s2-docs/components/actions/action-bar.md @@ -0,0 +1,123 @@ +--- + +title: "Action bar" +source\_url: +last\_updated: 2026-02-02 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions + parent\_category: actions + +--- + +# Action bar + +Action bars provide access to actions for selected items. They support both single- and bulk-selection patterns when multiple operations can be performed at once. + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) | [CSS: Action bar](https://opensource.adobe.com/spectrum-css/?path=/docs/components-action-bar--docs) | +| Spectrum Web Components | [SWC: Action Bar](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/action-bar--docs\&globals=system:spectrum-two) | +| React Spectrum | [RSP: ActionBar](https://react-spectrum.adobe.com/s2/index.html?path=/docs/actionbar--docs) | + +## Anatomy + +* action bar + * close button + * label + * action group (quiet) + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------ | ------- | ------------- | ----------- | +| isEmphasized | boolean | false | | + +### isEmphasized + +An action bar is not emphasized by default. isEmphasized inverts the coloring of the action bar and is best used for when the bar needs to stand out from the rest of the UI, directing a user's focus to the actions. + +## States + +| State | Support status | +| -------------- | -------------- | +| Default | Supported | +| Hover | Not supported | +| Down | Not supported | +| Keyboard focus | Not supported | +| Disabled | Not supported | +| Selected | Not supported | +| Dragged | Not supported | +| Error | Not supported | + +## Behaviors + +### Action bar in Dark theme + +Action bar is split into a separate component for each color theme — light and dark. Since each is set to either light or dark mode in Figma, they do not switch automatically like the rest of the UI when placed in frames that are set to "auto" mode. + +In dark theme, the action bar also includes a 1px inner border to help it stand out against the background colors. + +### Action group variants (Icon-only, Label-only, Icon + label) + +At larger screen or section sizes, use an action group that shows a label and icon. For smaller screen or section sizes, use an icon-only action group. Place any overflow actions into a action menu at the end of the bar. + +### Action disabled behavior + +Individual actions can be disabled in an action bar which follow the isDisabled property of the action group. This disabled state shows that the action buttons within the group exist, but are not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action group may become available later. + +### Placement + +When a user selects items with relevant actions, an action bar appears at the bottom of the viewport. The bar should have margins of `spacing-200` (12 pixels on desktop scale) on the sides and bottom. + +### Safe zone + +Include a safe zone of at least `spacing-400` (24 pixels on desktop scale) between the item counter and the action group. + +### Motion and stickiness + +Action bars slide and fade in from the bottom of the page or section. They remain or "stick" there until a user either deselects the items or navigates away. + +## Usage guidelines + +### Don't add a drag bar + +An action bar appears when items in a list or grid view are selected, and it remains in place until items are deselected or a user navigates away. Action bars can not be moved or dragged. + +### Allow scrolling to view underlying content + +Action bars appear on top of content. Allow space for a user to still be able to view the content underneath, especially if they're taking actions on a table or a list of items and need to be able to scroll. + +### Don't use quick actions + +Instead of quick actions, use an action bar for both single and bulk selection patterns. An action bar is useful for when a user needs to perform actions on either a single or multiple items at the same time. It can be used on either a grid view or a table view. + +Don't use quick actions — a deprecated component — because it presents conflicting nested actions (for example, a whole asset card could open a detailed view). This makes targeting specific actions very difficult, especially on smaller screens or with the keyboard. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). diff --git a/docs/s2-docs/components/actions/action-button.md b/docs/s2-docs/components/actions/action-button.md new file mode 100644 index 00000000..0d41a757 --- /dev/null +++ b/docs/s2-docs/components/actions/action-button.md @@ -0,0 +1,189 @@ +--- + +title: "Action button" +source\_url: +last\_updated: 2026-02-01 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions +* action +* button +* interactive + related\_components: +* action-bar +* action-group + parent\_category: actions + +--- + +# Action button + +## Overview + +Action buttons perform tasks or mark selections. They're suited for task-based workflows where buttons don't need to draw attention. + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) | [CSS: Action button](https://opensource.adobe.com/spectrum-css/?path=/docs/components-action-button--docs) | +| Spectrum Web Components | [SWC: Action Button](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/action-button--docs\&globals=system:spectrum-two) | +| React Spectrum | [RSP: ActionButton](https://react-spectrum.adobe.com/s2/index.html?path=/docs/actionbutton--docs) | + +## Anatomy + +``` +action button + - icon + - label + - hold icon (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------------- | --------------------------------------- | ------------- | ----------------------------------------------------------------------- | +| label | string | – | | +| hideLabel | boolean | false | | +| icon | – | – | Icon must be present if the label is not defined. | +| size | xs / s / m / l / xl | m | | +| isQuiet | boolean | false | | +| isSelected | boolean | false | | +| isEmphasized | boolean | false | | +| staticColor | white / black | – | Static color must not be set for the default version of this component. | +| selectedTextColor | – | – | | +| hasHoldIcon | boolean | false | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus | default | | + +### isDisabled + +An action button in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later. + +### hasHoldIcon + +An action button can have a hold icon (a small corner triangle). This icon indicates that holding down the action button for a short amount of time can reveal a popover menu, which can be used, for example, to switch between related actions. + +### selectedTextColor + +The text color on the selected state of the over-background variant can be customized to match the background it's on. + +### staticColor + +When an action button needs to be placed on top of a color background or a visual, use the static color option. Static color action buttons are available in transparencies, or in solid black or solid white, and don't change shades or values depending upon the color theme. Use static black on light color or image backgrounds, and static white on dark color or image backgrounds, regardless of the color theme. + +Static color action buttons can appear in static white, regardless of color theme. The static color option allows for them to be placed on top of a custom background that is not part of a Spectrum color theme. + +### isEmphasized + +By default, action buttons are not emphasized. This is optimal for when an action button is not the core part of an interface, such as in application panels, where all the visual components are monochrome in order to direct focus to the content. + +The emphasized action button has a blue background for its selected state in order to provide a visual prominence. This is optimal for when the selection should call attention, such as within a tool bar. + +### isSelected + +An action button can have a selected state to allow for toggling — not only for taking a direct action. This can be used to disclose parts of an interface, such as for showing or hiding panels or to switch between views (for example, grid or list views). + +### isQuiet + +By default, action buttons have a visible background. This style works best in a dense array of controls where the background helps to separate action buttons from the surrounding container, or to give visibility to isolated buttons. + +Alternatively, quiet action buttons can have no visible background until they're interacted with. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read. + +### size + +Action buttons come in five different sizes: extra-small, small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page. + +### icon + +Use an icon only when necessary and when it has a strong association with the label text. + +### hideLabel + +The label can be hidden to create an icon-only action button. If the label is hidden, an icon is required, and the label will appear in a tooltip on hover. + +### label + +Action buttons should always have a label, unless they are only using an icon that is universally understood and accessible. They can have an optional icon, but it should not be used for decoration. + +## States + +| State | Support status | +| -------------- | -------------- | +| Default | Supported | +| Hover | Supported | +| Down | Supported | +| Keyboard focus | Supported | +| Disabled | Supported | +| Selected | Supported | +| Dragged | Not supported | +| Error | Not supported | + +## Behaviors + +### Text overflow + +When the action button text is too long for the available horizontal space, it truncates at the end. The full text should be revealed with a tooltip on hover. + +### Keyboard focus + +An action button can be navigated using a keyboard. The keyboard focus state takes the button's visual hover state and adds a blue ring to the button in focus. + +## Usage guidelines + +### Use tooltips + +Icon-only action buttons can be hard to identify. They should always show a tooltip upon hovering for a short period of time, displaying the name and possibly a keyboard shortcut. + +### Isolated action buttons + +If you have an icon-only or text-only isolated action button, use the standard style to make sure it's more easily identifiable as a button. + +### Only group related actions with a hold icon + +When using a hold icon to switch actions, only group the actions that are part of the same family. Don't group unrelated actions just for the sake of saving space. + +### Respect hold icon placement + +In left-to-right interfaces, the hold icon is always in the bottom right corner of the action button. It's a symbolic indicator that shows that a popover menu will appear on hold. Don't change the placement of the hold icon based on the design of the interface. + +### When to use static black and static white + +To ensure maximum contrast with the background, use static black for light backgrounds and images, and use static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast. + +### Selected state text color + +The text color on the selected state of the over-background variant can be customized to match the background it's on. Use the background color for selected text when the action button is on a solid color, and is dark enough to meet a 4.5:1 contrast ratio with a white background (or black background, for the static black variant). + +Use black text when the button is on top of an image, or if the background is too low-contrast to meet the 4.5:1 contrast ratio. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Action bar](/page/action-bar/) +* [Action group](/page/action-group/) diff --git a/docs/s2-docs/components/actions/action-group.md b/docs/s2-docs/components/actions/action-group.md new file mode 100644 index 00000000..c1b5327c --- /dev/null +++ b/docs/s2-docs/components/actions/action-group.md @@ -0,0 +1,122 @@ +--- + +title: "Action group" +source\_url: +last\_updated: 2026-02-02 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions + related\_components: +* action-button +* button + parent\_category: actions + +--- + +# Action group + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Action | [group](https://opensource.adobe.com/spectrum-css/?path=/docs/components-action-group--docs) | +| Spectrum Web Components SWC: Action | [Group](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/action-group--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [ActionButtonGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/actionbuttongroup--docs) | + +## Anatomy + +``` +action group +- action button 1 +- action button 2 +- action menu (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------------- | -------------------------------- | ------------- | --------------------------------------- | +| orientation | horizontal / vertical horizontal | – | | +| size | s / m / l / xl m | – | | +| density | regular / compact regular | – | | +| isJustified | boolean | false | | +| isQuiet | boolean | false | | +| isEmphasized | boolean | false | | +| enableSelection | boolean | false | | +| selectionMode | single / multiple single | Only | applicable if selection is enabled | +| allowsEmptySelection | boolean | false | Only applicable if selection is enabled | +| overflowMode | wrap / collapse wrap | – | | +| isDisabled | boolean | false | | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +An action group in a disabled state shows that the action buttons within the group exist, but are not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action group may become available later. + +When selection is enabled, an action group's selection behavior can be set to allow for an empty selection, or not. + +When selection is enabled, an action group can allow for single or multiple selection of action buttons. + +By default, selection is not enabled in an action group. This is used for action groups that offer direct actions, rather than toggling. + +Selection can be enabled for an action group to allow for toggling. This can be used to disclose parts of an interface (for example, showing or hiding panels) or to switch between views (for example, grid or list views). + +Like action buttons, action groups are not emphasized by default. This is optimal for when the action group is not the core part of an interface, such as in application panels, where all components are monochrome in order to direct focus to the content. + +The emphasized action group has a blue background for its selected state in order to provide a visual prominence that meets the accessible color contrast ratio. This is optimal for when the selection should call attention, such as within a tool bar. + +By default, an action group uses not-quiet action buttons. This style works best in a dense array of controls where the background helps to separate action buttons from the surrounding container, or to give visibility to isolated buttons. + +Alternatively, quiet action groups can have no visible background until they’re interacted with. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read. + +An action group can become justified. By default, it is not justified since the action button size depends on the label and/or icon inside each button. When an action group is justified, it takes up the entire available container width, divided equally for each action button that is inside the group. + +"Action groups come in two densities: regular and compact. The compact density retains the same font and icon sizes, but has tighter spacing. The action buttons also become connected for non-quiet action groups." + +"Action groups come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +An action group can be either horizontal or vertical in its orientation. By default, an action group is horizontal. The vertical option should be reserved for when horizontal space is limited. + +When there are more actions than the action group has horizontal space for, overflowMode collapse will use an Action menu to contain additional actions. This is used in the components like action bar or panels to show an array of actions to select from when horizontal space is limited. + +When multiple items can be selected at a time use an action group when taking actions or making choices from a list of options. Action group is the preferred competent to use when those actions are simple (1-2 words or icon only). If you are switching views or navigating to different content, a segmented control is the preferred component. + +Use the fully justified variant when using the vertical compact action group (both the quiet and not quiet options). This will ensure the buttons have the same width. + +## States + +## Behaviors + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Action button](/page/action-button/) +* [Button](/page/button/) diff --git a/docs/s2-docs/components/actions/button-group.md b/docs/s2-docs/components/actions/button-group.md new file mode 100644 index 00000000..f0a81325 --- /dev/null +++ b/docs/s2-docs/components/actions/button-group.md @@ -0,0 +1,111 @@ +--- + +title: "Button group" +source\_url: +last\_updated: 2026-02-02 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions +* action +* button +* interactive + related\_components: +* button +* close-button + parent\_category: actions + +--- + +# Button group + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Button | [group](https://opensource.adobe.com/spectrum-css/?path=/docs/components-button-group--docs) | +| Spectrum Web Components SWC: Button | [Group](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/button-group--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [ButtonGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/buttongroup--docs) | + +## Anatomy + +``` +button group +- button +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------ | -------------------------------- | ------------- | ----------- | +| orientation | horizontal / vertical horizontal | – | | +| size | s / m / l / xl m | – | | +| overflowMode | wrap / collapse wrap | – | | +| isDisabled | boolean | false | | + +## External links + +Button groups organize related buttons into a single group for presenting multiple, related actions. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A button group in a disabled state shows that the buttons within the group exist, but are not available in that circumstance. This state can be used to maintain layout continuity and to communicate that a button group may become available later. + +This option stacks button groups vertically when horizontal space is limited, placing the most important action at the bottom. + +"Button groups come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +A button group can be either horizontal or vertical in its orientation. By default, a button group is horizontal. Use vertical option when horizontal space is limited. + +When horizontal space is limited, button groups stack vertically. Buttons are stacked by the importance of the action, with the most critical or primary action at the bottom. + +Button groups are aligned contextually. In general, button groups are left-aligned to follow content such as a block of text. They are center-aligned in the context of an empty state. And, they should be right-aligned inside container components such as dialogs, popovers, or cards. + +The order of button priority should match the alignment of surrounding text. When text is left-aligned, buttons should be arranged so that the leftmost button is the most critical. When text is right- or center- aligned, the most critical action should be the furthest right. + +Not all buttons in a group require an icon, but buttons with icons should always be of a higher priority than ones without icons. If the most critical action in a group doesn’t have an icon, don’t use icons in the remaining lower-level actions. + +Instead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action. + +## States + +Instead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action. + +## Behaviors + +Instead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action. + +## Usage guidelines + +Instead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Button](/page/button/) +* [Close button](/page/close-button/) diff --git a/docs/s2-docs/components/actions/button.md b/docs/s2-docs/components/actions/button.md new file mode 100644 index 00000000..80cc9c34 --- /dev/null +++ b/docs/s2-docs/components/actions/button.md @@ -0,0 +1,205 @@ +--- + +title: "Button" +source\_url: +last\_updated: 2026-02-01 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions +* action +* button +* interactive + related\_components: +* action-group +* button-group +* progress-bar +* progress-circle + parent\_category: actions + +--- + +# Button + +## Overview + +Buttons enable actions or navigation between views. They come in multiple styles to support different levels of emphasis, and are commonly used to guide progression through a flow. + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) | [CSS: Button](https://opensource.adobe.com/spectrum-css/?path=/docs/components-button--docs) | +| Spectrum Web Components | [SWC: Button](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/button-accent-fill--docs\&globals=system:spectrum-two) | +| React Spectrum | [RSP: Button](https://react-spectrum.adobe.com/s2/index.html?path=/docs/button--docs) | + +## Anatomy + +``` +button + - label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | --------------------------------------- | ------------- | ----------------------------------------------------------------------- | +| label | string | – | | +| hideLabel | boolean | false | | +| icon | – | – | Icon must be present if the label is not defined. | +| variant | accent / negative / primary / secondary | accent | | +| staticColor | white / black | – | Static color must not be set for the default version of this component. | +| style | fill / outline | fill | | +| size | s / m / l / xl | m | | +| justified | boolean | false | | +| isPending | boolean | false | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus | default | | + +### isDisabled + +A button in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later. + +### isPending + +Buttons can indicate that a quick progress action is taking place (e.g., saving settings on a server). In this case, the label and optional icon disappear and a progress circle appears. The progress circle always shows an indeterminate progress. + +Use the pending state for a button sparingly. It should be reserved only for when the progress is supposed to be quick (taking 5 seconds or less), and when there is no better way to communicate as such. + +### justified + +A button can become justified. By default, it is not justified since the button size depends on the label and/or icon inside of each button. When a button is justified, it takes up the entire available container width. + +### size + +Buttons come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page. + +### style + +Buttons are available in either fill or outline styles. A button in the fill style has a solid background, since it's meant to be intentionally more prominent than a button in the outline style. + +An outline style button has a visible stroke and no background color, and should only be used for secondary actions. + +### staticColor + +When a button needs to be placed on top of a color background or a visual, use the static color option. Static color buttons are available in primary and secondary outline or fill styles, in black or white, and don't change shades or values depending upon the color theme. + +Use static black on light color or image backgrounds, and static white on dark color or image backgrounds, regardless of the color theme. + +Static color buttons can appear in static white or black, regardless of color theme. The static color option allows for these to be placed on top of a custom background that is not part of a Spectrum color theme while still providing optimal contrast. + +### variant + +The Button component includes four variants: Accent, Primary, Secondary, and Negative. Each variant represents a different level of emphasis, helping designers establish clear visual hierarchy and guide users toward appropriate actions. + +* The **accent button** communicates strong emphasis and is reserved for actions that are essential to an experience. Don't use more than 3 accent buttons in the same view. These give extra prominence to important actions and are meant to establish a clear hierarchy. +* The **primary button** is for medium emphasis. Use it in place of a call to action button when the action requires less prominence, or if there are multiple primary actions of the same importance in the same view. +* The **secondary button** is for low emphasis. It's paired with other button types to surface less prominent actions, and should never be the only button in a group. +* The **negative button** is for emphasizing actions that can be destructive or have negative consequences if taken. Use it sparingly. + +### label, hideLabel, and icon + +Buttons should always have a label, unless they are only using an icon that is universally understood and accessible. They can have an optional icon, but it should not be used for decoration. Use an icon only when necessary and when it has a strong association with the label text. + +The label can be hidden using the hideLabel option to create an icon-only button. If the label is hidden, an icon is required, and the label will appear in a tooltip. + +## States + +| State | Support status | +| -------------- | -------------- | +| Default | Supported | +| Hover | Supported | +| Down | Supported | +| Keyboard focus | Supported | +| Disabled | Supported | +| Selected | Not supported | +| Dragged | Not supported | +| Error | Not supported | + +## Behaviors + +### Keyboard focus + +A button can be navigated using a keyboard. The keyboard focus state takes the button's visual hover state and adds a blue ring to the button in focus. + +### Tooltip when the label is hidden + +When the button label is hidden, a tooltip is shown on hover that displays the label text and, if appropriate, a keyboard shortcut. + +### Flexible width + +The width of a button automatically adjusts to fit the label text. The padding on each side of the button is equal to half its height. + +### Minimum width + +Buttons have a minimum width of 2.25× the height of the button. This ensures that small buttons retain an identifiable shape. + +### Text overflow + +When the button text is too long for the horizontal space available, it wraps to form another line. + +### Cursor style + +Buttons use the default arrow cursor for all states, including hover and down. The only exception occurs on the web; if the button is using the href property it will display the pointer cursor instead. + +### Delay before pending state + +Some progress can be very quick. In order to avoid showing a progress circle for a fraction of a second, which results in an unpleasant flickering, there is a delay of 1 second before the pending state appears. During this delay, the button continues to visually respond to interactive events (e.g., hover), but additional clicks do not result in repeated submissions. + +## Usage guidelines + +### Use icons only when necessary + +Icons can be used in buttons when additional clarity is required and the icon is highly relevant to the action. Icons should not be used for decoration. + +### Don't override color + +Do not use custom colors for buttons. The colors of different button variations have been designed to be consistent and accessible. + +### When to use static black and static white + +To ensure maximum contrast with the background, use static black for light backgrounds and images, and use static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast. + +### Don't use the pending state for long progress + +The pending state should be reserved for indeterminate actions that are expected to take 5 seconds or less. For determinate or longer actions, use a [progress bar](/page/progress-bar/) or [progress circle](/page/progress-circle/) outside of the button. + +### Use a button group to show additional actions + +Instead of a single split button (now a deprecated component), use a [button group](/page/button-group/) to show any additional actions related to the most critical action. + +### Display a popover when featuring subsequent options + +In some instances, it's possible to have a call to action button display a popover (or tray) to feature subsequent options. These options should extend and parallel the action of the button. Do not include arbitrary or unrelated options. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Action group](/page/action-group/) +* [Button group](/page/button-group/) +* [Progress bar](/page/progress-bar/) +* [Progress circle](/page/progress-circle/) diff --git a/docs/s2-docs/components/actions/close-button.md b/docs/s2-docs/components/actions/close-button.md new file mode 100644 index 00000000..c5227b16 --- /dev/null +++ b/docs/s2-docs/components/actions/close-button.md @@ -0,0 +1,95 @@ +--- + +title: "Close button" +source\_url: +last\_updated: 2026-02-02 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions +* action +* button +* interactive + related\_components: +* button-group +* link + parent\_category: actions + +--- + +# Close button + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | --------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Close | [button](https://opensource.adobe.com/spectrum-css/?path=/docs/components-close-button--docs) | + +## Anatomy + +``` +close button +- Cross UI icon +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ----------------------------------------------- | ------------- | ----------------------------------------------------------------------- | +| size | s / m / l / xl m | – | | +| iconSize | string | – | | +| staticColor | white / black | – | Static color must not be set for the default version of this component. | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A close button in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later. + +Use this option when a close button needs to be placed on top of a color background or visual. Static color close buttons are available in black or white, regardless of color theme. + +Use static black on light color or image backgrounds, and static white on dark color or image backgrounds, regardless of color theme. Make sure that the background and the close button color meet the minimum color contrast ratio. + +"The icon inside of the close button comes in two options: regular and large. These scale up and down for each close button size. This is a cross UI icon, not a workflow icon or the letter “x.”" + +"Close buttons come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +A close button can be navigated using a keyboard. The keyboard focus state takes the close button’s visual hover state and adds a ring to the button in focus. + +## States + +## Behaviors + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Button group](/page/button-group/) +* [Link](/page/link/) diff --git a/docs/s2-docs/components/actions/link.md b/docs/s2-docs/components/actions/link.md new file mode 100644 index 00000000..2fd52d89 --- /dev/null +++ b/docs/s2-docs/components/actions/link.md @@ -0,0 +1,94 @@ +--- + +title: "Link" +source\_url: +last\_updated: 2026-02-02 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions + related\_components: +* close-button +* list-view + parent\_category: actions + +--- + +# Link + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ----------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Link](https://opensource.adobe.com/spectrum-css/?path=/docs/components-link--docs) | +| Spectrum Web Components SWC: | [Link](https://opensource.adobe.com/spectrum-css/?path=/docs/components-link--docs) | +| React Spectrum RSP: | [Link](https://react-spectrum.adobe.com/s2/index.html?path=/docs/link--docs) | + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ----------------------------------------------- | ------------- | ----------------------------------------------------------------------- | +| variant | primary / secondary primary | – | | +| isQuiet | boolean | false | | +| staticColor | white / black | – | Static color must not be set for the default version of this component. | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Links provide navigation to a different location. They can appear within a paragraph or as standalone text. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Use the static color option when a link needs to be placed on top of a color background or visual. Static color links are available in black or white, regardless of color theme. They can also be placed on top of a custom background that isn’t part of a Spectrum color theme. + +Use static black on light color or image backgrounds, and static white on dark color or image backgrounds, regardless of color theme. Make sure that the background and the link color meet the minimum color contrast ratio. + +All links can have a quiet style, without an underline. This style should only be used when the placement and context of the link is explicit enough that a visible underline isn’t necessary. + +"The variant property defines the visual style of a link and includes two options: primary and secondary." + +The primary variant is the default style and displays the link in Spectrum blue. It is intended to draw attention to the link and is suitable when the blue color complements the surrounding content without being overwhelming. + +The secondary variant uses the same gray color as the surrounding paragraph text. Its subdued appearance is ideal for scenarios where multiple links are present in a block of text and the primary variant would be too visually dominant. + +Links are for usage in body copy and are not appropriate in titles. Consider using a different component if you're looking for a larger or more prominent call to action, such as a button. + +Be mindful of link placement and language, and create experiences that are inclusive of users navigating with screen readers. Screen readers pull a list of links — only the link text, and not including other surrounding language — to determine the content of the page. + +People using screen readers may tab between links without getting the text in between, so very generic link wording like “learn more” or “click here” doesn’t communicate any context from elsewhere in the experience. Identify the target of each link directly in the link text to communicate context and set clear expectations about where the link will go. + +Quiet links are less accessible, so don't use them for links that are critical to an experience. Quiet links are commonly used in website footers, where there are several lists of links that are shortcuts to other pages. + +## States + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Close button](/page/close-button/) +* [List view](/page/list-view/) diff --git a/docs/s2-docs/components/actions/list-view.md b/docs/s2-docs/components/actions/list-view.md new file mode 100644 index 00000000..3f8c4f5f --- /dev/null +++ b/docs/s2-docs/components/actions/list-view.md @@ -0,0 +1,144 @@ +--- + +title: "List view" +source\_url: +last\_updated: 2026-02-02 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions + related\_components: +* link +* menu + parent\_category: actions + +--- + +# List view + +## Resources + +### Design + +* **Figma**: S2 Web + +## Anatomy + +``` +list view +- list view section header +- list item +- checkbox +- icon +- thumbnail +- label (required) +- description (optional) +- actions +- trailing icons (drill-in icon, link out icon) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------- | ------------------------------- | ------------- | ------------------------------------------------- | +| selectionMode | none / single / multiple single | Defines | how many items can be selected at once. | +| isQuiet | boolean | false | If true, the list view uses a quiet visual style. | +| items | array – An array of list view | items. | | + +## External links + +List views display content in a structured, scrollable list. They support sorting, organizing, and selecting multiple items at once. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A list view is a versatile component and can contain many items depending on the use case. These items can be icons, thumbnails, avatars, checkboxes, drag handles, action buttons, and more. + +By default a list view is not quiet. If true, the list view uses a quiet visual style meaning there is no background or borders to the component. + +The selection mode defines how many items can be selected at once. A list view can use single selection, multiple selection, or none. + +In the highlight selection style for touch interactions, tapping anywhere on the item will navigate to its contents. For mouse-based interactions, double-clicking anywhere on the item or single-clicking the navigation icon will do the same. + +In the checkbox selection style, clicking or tapping the label area or navigation icon of a list view item will navigate to its contents. + +Single-clicking or tapping anywhere on a list view item will select the item, except the label in checkbox selection style. For checkbox selection style, clicking the label will navigate to the item. + +In touch experiences, the list view default is navigation only with the highlight selection style. Users enter a selection mode by a touch and hold gesture on any list view item. + +Selection mode in touch uses the checkbox selection style and suppresses navigation. Users can exit selection mode by pressing the Escape key or deselecting all items. + +List view items can be dragged and dropped to reorder or restructure the list. + +Multiple items can be dragged at a time and shifted from one level of hierarchy to another. + +List views can also accept dropped items from outside the component, to modify the list. + +A list view item's label or description will truncate if the text is longer than the available horizontal space. Display the full label or description text in a tooltip on hover and focus states. + +When more than two actions are available for a list view item, the actions are nested within an action menu. + +List views work best for flat collections of items that share the same hierarchy level. + +Tree views are ideal for displaying nested or hierarchical relationships. + +## States + +In the checkbox selection style, clicking or tapping the label area or navigation icon of a list view item will navigate to its contents. + +List view items can be dragged and dropped to reorder or restructure the list. + +Multiple items can be dragged at a time and shifted from one level of hierarchy to another. + +List views can also accept dropped items from outside the component, to modify the list. + +When more than two actions are available for a list view item, the actions are nested within an action menu. + +List views work best for flat collections of items that share the same hierarchy level. + +Tree views are ideal for displaying nested or hierarchical relationships. + +## Behaviors + +In the checkbox selection style, clicking or tapping the label area or navigation icon of a list view item will navigate to its contents. + +List view items can be dragged and dropped to reorder or restructure the list. + +Multiple items can be dragged at a time and shifted from one level of hierarchy to another. + +List views can also accept dropped items from outside the component, to modify the list. + +When more than two actions are available for a list view item, the actions are nested within an action menu. + +List views work best for flat collections of items that share the same hierarchy level. + +Tree views are ideal for displaying nested or hierarchical relationships. + +## Usage guidelines + +List views work best for flat collections of items that share the same hierarchy level. + +Tree views are ideal for displaying nested or hierarchical relationships. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Link](/page/link/) +* [Menu](/page/menu/) diff --git a/docs/s2-docs/components/actions/menu.md b/docs/s2-docs/components/actions/menu.md new file mode 100644 index 00000000..bac1e907 --- /dev/null +++ b/docs/s2-docs/components/actions/menu.md @@ -0,0 +1,184 @@ +--- + +title: "Menu" +source\_url: +last\_updated: 2026-02-02 +category: components/actions +component\_type: action +status: published +tags: + +* components-actions +* navigation +* menu +* dropdown + related\_components: +* list-view +* cards + parent\_category: actions + +--- + +# Menu + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Menu](https://opensource.adobe.com/spectrum-css/?path=/docs/components-menu--docs) | +| Spectrum Web Components SWC: | \[Menu]\( | +| React Spectrum RSP: | [Menu](https://react-spectrum.adobe.com/s2/index.html?path=/docs/menu--docs) | + +## Anatomy + +``` +menu +- popover +- menu section header +- menu section description +- menu items +- icon +- label (required) +- description +- value +- switch +- checkbox +- thumbnail +- drill-in chevron +- link-out icon +- menu section divider +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------- | ----------------------------------------------- | ------------- | ----------- | +| container | popover / tray | – | | +| label | string | – | | +| icon | – – Icon must be present if the label is not | defined. | | +| description | string | – | | +| value | string | – | | +| size | s / m / l / xl m | – | | +| selectionMode | single / multiple / no selection | – | | +| selectionStyle | checkbox / switch | – | | +| sectionHeader | string | – | | +| isCollapsible | boolean | false | | +| isUnavailable | boolean | false | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A disabled menu item indicates that an option exists but isn’t available in the current context. This helps preserve layout consistency and signals that the action might be available later. + +An unavailable menu item signals that an option exists but isn’t accessible in the current scenario. This helps ensure the label remains visible and provides context about why the option is unavailable, or directions for how to make it available. + +Displays submenus in a collapsed, nested format within the parent menu container. Works with both popover and tray styles. When using a tray, set a fixed height to avoid disorienting shifts when items expand or collapse. + +Use a section header when a menu section requires a label or descriptor. Section headers are helpful when two or more sections differ in function or context, making it easier for users to understand the structure. + +When the selection option is enabled, the selection can be displayed using checkmarks, checkboxes or switches. Switches are more commonly used on mobile. + +A menu section has the options of single selection, multiple selection, or having no selection. By default, menu items have no selection, and perform an action on press. + +For single selection menu sections, menu items show a single checkmark to indicate the selected item. Multiple selection menu sections can display checkboxes or switches beside each menu item. + +"Menus come in four different sizes: small, medium, large, and extra-large. Medium is the default and most commonly used. Menu sizes should correspond to the size of the menu trigger component (like an action button), and any embedded components (like switches) should follow suit." + +Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page. + +A menu item can display a related value in the value area. Examples of values include the selected option from a submenu, a keyboard shortcut for the action, or other content that clarifies the menu item. + +Menu items can include description text to provide extra clarity beyond the label. Descriptions help users understand the action and make informed choices. + +Avoid cluttering items with repetitive details or promotional content. + +Menu items can include icons, but only when they add meaningful context — not just for decoration. Use icons when they have a strong, recognizable association with the label (like tool switching in a toolbar). + +A menu item must include a label that clearly communicates the action or option it represents. + +On desktop, menus are shown in a popover by default. On mobile, popovers can be used when appropriate. Submenus cascade in a separate popover by default. + +When a menu item includes a submenu, a drill-in chevron appears at the end of the item to indicate that additional options are available. + +When a menu item leads to a different context, such as a new page or dialog, a link-out icon appears at the end of the item to indicate that the user will navigate away from the current view. + +When a menu is displayed within popovers, a submenu will appear adjacent to the parent menu item in a separate popover. The submenu popover is aligned with an offset to horizontally overlap the parent menu and vertically align the first submenu item with the parent menu item. + +When a menu is shown in a popover, any submenu appears in a separate popover next to the parent item. The submenu popover is positioned to overlap the parent menu horizontally, with vertical alignment that matches the first submenu item to its parent. + +When a menu is shown in a tray, selecting a parent item with a submenu replaces the tray’s content with the submenu. A back button labeled with the parent item’s title appears at the top of the tray to let users return to the previous menu level. + +A menu item can be navigated using a keyboard. The keyboard focus state takes the menu item’s visual hover state and adds a focus ring around the item. + +When a menu item’s label or description are too long for the available horizontal space, they wrap to form another line. + +Dividers appear between sections when two or more sections are used within the same menu. + +In Windows high contrast mode, menu items should display with default text color. Selected items should have the background and text colors defined for selected text. + +Menus should be sized according to the component being used as the menu trigger. All submenus within the menu should also be using the same size as the menu trigger. + +Following Adobe’s UX writing style, write menu items in sentence case unless they contain words that are branded terms. + +Don’t end a menu command with an ellipsis (…) unless it requires additional input to complete the action, typically in a dialog. + +## States + +When a menu item includes a submenu, a drill-in chevron appears at the end of the item to indicate that additional options are available. + +When a menu item’s label or description are too long for the available horizontal space, they wrap to form another line. + +Dividers appear between sections when two or more sections are used within the same menu. + +Following Adobe’s UX writing style, write menu items in sentence case unless they contain words that are branded terms. + +Don’t end a menu command with an ellipsis (…) unless it requires additional input to complete the action, typically in a dialog. + +## Behaviors + +When a menu item includes a submenu, a drill-in chevron appears at the end of the item to indicate that additional options are available. + +When a menu item’s label or description are too long for the available horizontal space, they wrap to form another line. + +Dividers appear between sections when two or more sections are used within the same menu. + +Following Adobe’s UX writing style, write menu items in sentence case unless they contain words that are branded terms. + +Don’t end a menu command with an ellipsis (…) unless it requires additional input to complete the action, typically in a dialog. + +## Usage guidelines + +Following Adobe’s UX writing style, write menu items in sentence case unless they contain words that are branded terms. + +Don’t end a menu command with an ellipsis (…) unless it requires additional input to complete the action, typically in a dialog. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [List view](/page/list-view/) +* [Cards](/page/cards/) diff --git a/docs/s2-docs/components/containers/cards.md b/docs/s2-docs/components/containers/cards.md new file mode 100644 index 00000000..0d672d5a --- /dev/null +++ b/docs/s2-docs/components/containers/cards.md @@ -0,0 +1,131 @@ +--- + +title: "Cards" +source\_url: +last\_updated: 2026-02-02 +category: components/containers +component\_type: container +status: published +tags: + +* components-containers + related\_components: +* menu +* divider + parent\_category: containers + +--- + +# Cards + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Card](https://opensource.adobe.com/spectrum-css/?path=/docs/components-card--docs) | +| Spectrum Web Components SWC: | [Card](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/card--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [Card](https://react-spectrum.adobe.com/s2/index.html?path=/docs/card--docs) | + +## Anatomy + +``` +card +- container +- checkbox (optional) +- preview well +- preview (asset) +- metadata +- footer area +- title +- metadata +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------- | ---------------------------------------------------------------- | ------------- | ---------------------------------- | +| variant | asset / collection / flex / gallery / horizontal / product asset | Determines | which card layout variant is used. | + +## External links + +Cards group related content and actions into flexible containers for browsing. They preview key information and reveal more detail on interaction. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Card preview areas have a maximum image height aspect ratio of 3:4, and a minimum height aspect ratio of of 4:1. + +If the card has a fixed height, such as in a tile grid, long titles will be truncated. Use short titles to avoid this. In layouts with variable height, like a waterfall grid, titles will wrap to fit. + +Cards, by definition, should have some form of interaction such as viewing, editing, purchasing, etc. Some actions are exposed in buttons, and others simply occur by clicking the card. + +If a card only has an ability to be opened or viewed in more detail, do not include a button. Clicking anywhere on the card should perform that action. + +If a card has other interactive elements such as a hidden actions menu or an avatar, but no buttons, the whole card (outside of those elements) should be clickable. + +If there’s only one action (that’s not opening or viewing the card), use a button to communicate that action. If there are two or more available actions, and one of those actions is to open or view the card, use a button to communicate “View” or “Open,” instead of relying on clicking on the card. + +If a standard card has a footer with a button, only the button is clickable. If a card has a preview, clicking the preview will open that card. When a preview is purely decorative, it is not clickable. + +"When a group of cards are loading, they follow the ghost loading convention. There are 5 phases for ghost loading:" + +Cards are meant to just show a taste of the available information. Don’t overload cards with more information than necessary. + +Only standard cards can have a footer, and buttons can only appear inside a footer. + +Individual cards are not aligned to individual columns in the page's responsive column grid. Instead, groups of cards are aligned to the column grid in a layout region. + +If the preview is a video clip or other moving item, do not automatically play the clip or motion. Save the movement for either when a user hovers on the card or when they click on a play button. + +## Card types + +Card preview areas have a maximum image height aspect ratio of 3:4, and a minimum height aspect ratio of of 4:1. + +"When a group of cards are loading, they follow the ghost loading convention. There are 5 phases for ghost loading:" + +Cards are meant to just show a taste of the available information. Don’t overload cards with more information than necessary. + +Only standard cards can have a footer, and buttons can only appear inside a footer. + +## Behaviors + +Card preview areas have a maximum image height aspect ratio of 3:4, and a minimum height aspect ratio of of 4:1. + +"When a group of cards are loading, they follow the ghost loading convention. There are 5 phases for ghost loading:" + +Cards are meant to just show a taste of the available information. Don’t overload cards with more information than necessary. + +Only standard cards can have a footer, and buttons can only appear inside a footer. + +## Usage guidelines + +Cards are meant to just show a taste of the available information. Don’t overload cards with more information than necessary. + +Only standard cards can have a footer, and buttons can only appear inside a footer. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Menu](/page/menu/) +* [Divider](/page/divider/) diff --git a/docs/s2-docs/components/containers/divider.md b/docs/s2-docs/components/containers/divider.md new file mode 100644 index 00000000..88217487 --- /dev/null +++ b/docs/s2-docs/components/containers/divider.md @@ -0,0 +1,98 @@ +--- + +title: "Divider" +source\_url: +last\_updated: 2026-02-02 +category: components/containers +component\_type: container +status: published +tags: + +* components-containers + parent\_category: containers + +--- + +# Divider + +Dividers group or separate related content to clarify layout. They help establish rhythm, visual hierarchy, and structural boundaries. + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) | [CSS: Divider](https://opensource.adobe.com/spectrum-css/?path=/docs/components-divider--docs) | +| Spectrum Web Components | [SWC: Divider](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/divider--docs\&globals=system:spectrum-two) | +| React Spectrum | [RSP: Divider](https://react-spectrum.adobe.com/s2/index.html?path=/docs/divider--docs) | + +## Anatomy + +* divider + * heading + * divider + * description + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | --------------------- | ------------- | ----------- | +| size | s / m / l | s | | +| orientation | horizontal / vertical | horizontal | | + +### orientation + +By default, dividers are horizontal and should be used for separating content vertically. The vertical divider is used to separate content horizontally. + +### size + +The small divider is the default size. This is used to divide similar components such as table rows, action button groups, and components within a panel. + +The medium divider is used for dividing subsections on a page, or to separate different groupings of components such as panels, rails, etc. + +The large divider should only be used for page titles or section titles. + +## States + +| State | Support status | +| -------------- | -------------- | +| Default | Supported | +| Hover | Not supported | +| Down | Not supported | +| Keyboard focus | Not supported | +| Disabled | Not supported | +| Selected | Not supported | +| Dragged | Not supported | +| Error | Not supported | + +## Usage guidelines + +### Place a divider below a header + +Dividers (medium or large) can be used in combination with a header text to create a section or a page title. In such cases, place the divider below the header. + +### Don't overuse dividers + +Dividers lose their value when overused. Use them sparingly to avoid creating unnecessary noise. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). diff --git a/docs/s2-docs/components/containers/popover.md b/docs/s2-docs/components/containers/popover.md new file mode 100644 index 00000000..45a009c5 --- /dev/null +++ b/docs/s2-docs/components/containers/popover.md @@ -0,0 +1,120 @@ +--- + +title: "Popover" +source\_url: +last\_updated: 2026-02-02 +category: components/containers +component\_type: container +status: published +tags: + +* components-containers + related\_components: +* divider +* standard-panel + parent\_category: containers + +--- + +# Popover + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Popover](https://opensource.adobe.com/spectrum-css/?path=/docs/components-popover--docs) | +| Spectrum Web Components SWC: | \[Popover]\( | +| React Spectrum RSP: | [Popover](https://react-spectrum.adobe.com/s2/index.html?path=/docs/popover--docs) | + +## Anatomy + +``` +popover +- tip (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------- | +| width | number | – | | +| height | number | – | | +| hideTip | boolean | false | | +| placement | top / top left / top right / top start / top end / bottom / bottom left / bottom right / bottom start / bottom end / left / left top / left bottom / start / start top / start bottom / right / right top / right bottom / end / end top / end bottom top | – | | +| offset | number 8 pixel | measurement | | +| crossOffset | number | 0 | | +| containerPadding | number 8 pixel | measurement | | + +## External links + +Popovers are containers for transient content like menus, options, or additional actions. They float above the interface and stand out visually using stroke and drop shadow. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +To keep a popover within certain boundaries, such as a browser window, define a container and a container padding value. + +"The cross offset is the placement offset on the cross axis: the x-axis for top and bottom positions, and the y-axis for left and right positions." + +The offset is the space between the source and the popover (or tip, if present). Adjust it as needed to align visually with the source’s perceived bounds and maintain a balanced relationship between the two elements. + +A popover is positioned in relation to its source. + +Popovers usually appear without a tip and rely on a distinct down state in the source to show their origin. When the source lacks that visual cue, add a tip to reinforce the connection between the popover and its source. + +A popover’s height can be customized appropriately for its context. + +A popover’s width can be customized appropriately for its context. + +Popovers stem off of action buttons that act as a source to open up transient content. + +When displaying a popover, it should animate from its source to reinforce the connection between popover and source. It should fade in and slide with subtle motion from the source. + +A popover can be dismissed by clicking or tapping anywhere outside it, including the source, or by selecting an option or taking an action inside the popover. + +Trays can be used as alternatives to popovers on small screens. Use a tray when the amount of content is too large or overwhelming for a popover. + +When the source that triggers the popover does not have a visually distinct down state, use a popover with a tip to clearly indicate the connection to its source. + +## States + +Popovers stem off of action buttons that act as a source to open up transient content. + +Trays can be used as alternatives to popovers on small screens. Use a tray when the amount of content is too large or overwhelming for a popover. + +## Behaviors + +Popovers stem off of action buttons that act as a source to open up transient content. + +Trays can be used as alternatives to popovers on small screens. Use a tray when the amount of content is too large or overwhelming for a popover. + +## Usage guidelines + +Trays can be used as alternatives to popovers on small screens. Use a tray when the amount of content is too large or overwhelming for a popover. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Divider](/page/divider/) +* [Standard panel](/page/standard-panel/) diff --git a/docs/s2-docs/components/containers/standard-panel.md b/docs/s2-docs/components/containers/standard-panel.md new file mode 100644 index 00000000..b31f115e --- /dev/null +++ b/docs/s2-docs/components/containers/standard-panel.md @@ -0,0 +1,136 @@ +--- + +title: "Standard panel" +source\_url: +last\_updated: 2026-02-02 +category: components/containers +component\_type: container +status: published +tags: + +* components-containers + related\_components: +* popover +* table + parent\_category: containers + +--- + +# Standard panel + +## Resources + +### Design + +* **Figma**: S2 Web + +## Anatomy + +``` +standard panel +- header content area +- accordion +- back button +- close button (optional) +- gripper (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| --------------- | -------------------------------------- | ------------- | ----------- | +| container | anchored / floating / dragged anchored | – | | +| label | string | – | | +| description | string | – | | +| value | string | – | | +| density | compact / regular / spacious regular | – | | +| style | primary / secondary primary | – | | +| hideGripper | boolean | false | | +| hideCloseButton | boolean | false | | +| hideDivider | boolean | false | | + +## External links + +Standard panels are containers used to group related content or tools in a consistent layout. They support a range of sizes, densities, and configurations to fit different use cases across products. Panels can be placed alongside primary content to provide supporting controls or information. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Determines whether the close button is visible in the top right corner of the panel. Set to true to hide the button when panel dismissal is not required. + +Determines whether the gripper is visible at the top center of the panel. Set to true to hide the gripper when panel dragging is not required. + +Specifies the visual style of the panel. Use primary for panels that require high emphasis with the primary background color, and secondary for panels that require lower emphasis. + +"There are three density options for standard panel: compact, regular, and spacious. Regular is the default and recommended for layouts in creative tools, marketing, or analytics products. Use spacious for lighter-weight web experiences, such as Adobe Express. Use compact for complex professional tools where maximizing screen space is essential." + +Defines the panel’s layout behavior. Use anchored when the panel is docked alongside other panels on the same surface. Use floating when the panel is undocked and positioned above the application surface. Use dragged for the panel’s appearance while it is being moved. + +Controls whether the panel content is organized into sections. When set to true, the panel displays content without structural segmentation, allowing full customization based on product or experience needs. When set to false, the panel uses an embedded accordion component to divide content into smaller, structured segments, each customizable while maintaining a standardized layout for clarity and consistency. + +Determines whether the panel title is visible at the top of the panel. + +Determines whether the back button is visible at the top of the panel, positioned to the left of the panel title. + +Determines the size of the panel title. Options are small and medium. Use medium to establish visual hierarchy. Use small for compact layouts or secondary panels. + +A standard panel can sometimes be dragged and rearranged, or undocked to become a floating panel. In this case, display the gripper at the top of the panel, then click and drag to detach it. + +Standard panel uses an Accordion subcomponent to manage collapsible content sections. It can be configured to allow multiple sections to expand independently or restrict expansion to a single section at a time. + +A panel can scroll internally, and a group of panels can also scroll as a unit. Panels always scroll independently from the canvas or page content. The header and footer areas of a panel can remain fixed during scrolling. + +When users scroll in the outer areas of a panel — such as the header, footer, or sides — the entire panel group scrolls. When scrolling within the inner content area, only the panel’s content scrolls, while the header and footer (if present) stay in place. + +"Standard panel supports three widths: small, medium, and large. The small size is best for a single column of items, such as swatches or navigation elements. Medium is the default for most scenarios and works well for tools that interact with a canvas area, including filters, sliders, text boxes, or swatches. The large size is ideal for panels where users browse or search for content, such as images, assets, cards, or templates." + +The panel title can act as a label for the fields in the panel, if the design is reviewed and approved by an accessibility expert. + +Use a single panel density across a product to maintain visual consistency. Mixing densities within the same experience is not recommended. + +The choice of density often depends on context, user preference, and device type. Compact saves space in complex professional tools, regular balances usability across a range of products, and spacious improves comfort in lighter-weight experiences. + +Anchored panels are docked in fixed areas of the workspace and grouped with other panels on the same surface. They cannot move freely outside their designated location unless undocked. This layout helps maintain a consistent and organized workspace, making it easier for users to access essential tools without obstructing the canvas or working area. A common example is the layers panel docked to the right side of Photoshop. + +Floating panels are undocked and can be moved freely anywhere on the screen, independent of the main workspace. This style offers flexibility, especially when working across multiple monitors or when isolating a panel improves focus. A common example is a Properties panel floating near artwork in Illustrator for quick access. + +Dragging refers to manually moving a panel by clicking and dragging the gripper. This interaction allows users to reposition a panel within the workspace. A dragged panel can be docked into a new location (anchored) or left to float independently. This behavior supports workspace customization, helping users tailor panel placement to fit their workflow. For example, dragging the Tools panel from the left side of Photoshop to float next to the canvas. + +## States + +The panel title can act as a label for the fields in the panel, if the design is reviewed and approved by an accessibility expert. + +Use a single panel density across a product to maintain visual consistency. Mixing densities within the same experience is not recommended. + +## Behaviors + +The panel title can act as a label for the fields in the panel, if the design is reviewed and approved by an accessibility expert. + +Use a single panel density across a product to maintain visual consistency. Mixing densities within the same experience is not recommended. + +## Usage guidelines + +The panel title can act as a label for the fields in the panel, if the design is reviewed and approved by an accessibility expert. + +Use a single panel density across a product to maintain visual consistency. Mixing densities within the same experience is not recommended. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Popover](/page/popover/) +* [Table](/page/table/) diff --git a/docs/s2-docs/components/containers/table.md b/docs/s2-docs/components/containers/table.md new file mode 100644 index 00000000..cac7992a --- /dev/null +++ b/docs/s2-docs/components/containers/table.md @@ -0,0 +1,152 @@ +--- + +title: "Table" +source\_url: +last\_updated: 2026-02-02 +category: components/containers +component\_type: container +status: published +tags: + +* components-containers + related\_components: +* standard-panel +* alert-banner + parent\_category: containers + +--- + +# Table + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Table](https://opensource.adobe.com/spectrum-css/?path=/docs/components-table--docs) | +| Spectrum Web Components SWC: | \[Table]\( | +| React Spectrum RSP: | [TableView](https://react-spectrum.adobe.com/s2/index.html?path=/docs/tableview--docs) | + +## Anatomy + +``` +table +- column header +- label +- sort icon +- column divider +- row +- cell +- label +- row divider +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ---------------------------------------------- | ------------- | --------------------------------------------- | +| size | s / m / l m | Controls | the density of table rows. | +| hideHeader | boolean | false | If true, the table header is hidden. | +| header | object – Configuration for the table header | row. | | +| density | compact / regular / spacious regular | – | | +| isQuiet | boolean | false | If true, the table uses a quiet visual style. | +| isSortable | boolean | false | If true, table columns can be sorted. | +| columns | array – An array of column definitions for the | table. | | +| rows | array – An array of row data for the | table. | | + +## External links + +Tables organize and display structured information in rows and columns. They support scanning, sorting, comparing, and interacting with large amounts of data. Use when multiple data points need to be reviewed or acted on in one place. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +"Tables come in three sizes: small, medium, and large. Size affects the overall scale, including font size and spacing. Medium is the default. Use large for high-visibility tables or when readability is critical. Use small in constrained spaces or when the table is secondary to other content." + +If true, the table header is hidden. + +Configuration for the table header row. + +"Tables come in three densities: compact, regular, and spacious. Density controls vertical spacing while keeping font sizes consistent—compact rows have tighter padding, spacious rows have more breathing room. Regular is the default for most use cases. Use compact when fitting more data in a limited viewport is critical (e.g., dashboards, data-heavy admin panels). Use spacious when scannability and visual comfort are priorities (e.g., transaction histories, settings tables with minimal data)." + +Use a standard table when a table is the main focus of an experience. Quiet tables are for when a table is meant to be supplementary, subtle, or lightweight. + +If true, table columns can be sorted. + +An array of column definitions for the table. + +An array of row data for the table. + +Column dividers help organize table content and aid users in parsing related data. You can apply dividers selectively to group related columns—for example, separating user information from action columns, or grouping metadata fields together. Use dividers sparingly to avoid visual clutter. + +All tables have a hover state regardless of if actions or selections can be made. This aids the user in viewing content in a single row. + +Similar to a paragraph of text, textual data should be start-aligned within a table (left-aligned in LTR languages, right-aligned in RTL languages). Never use center alignment. + +"Numerical data should generally be right-aligned for ease of scanning and comparing. This alignment typically does NOT reverse in RTL languages because:" + +"Exception: Use start-alignment (left in LTR, right in RTL) when numbers are arbitrary identifiers, known as "nominal numbers," which can't be compared or combined arithmetically (e.g., ZIP codes, IP addresses, phone numbers). These behave like text." + +Column headers follow the alignment of their data. + +All content should be centered vertically within the row to offer the right visual balance. + +Tables use row dividers, hover states, and selection highlighting to help users track data. Zebra striping adds visual noise without improving usability. + +Column dividers are optional decorations that can help organize table content and create groups of data. Only use these when necessary, and don't add them to every column. + +When there are gaps in the data, use an en dash (–) to represent null or not applicable (N/A) values. + +## States + +All tables have a hover state regardless of if actions or selections can be made. This aids the user in viewing content in a single row. + +Column headers follow the alignment of their data. + +All content should be centered vertically within the row to offer the right visual balance. + +When there are gaps in the data, use an en dash (–) to represent null or not applicable (N/A) values. + +## Behaviors + +All tables have a hover state regardless of if actions or selections can be made. This aids the user in viewing content in a single row. + +Column headers follow the alignment of their data. + +All content should be centered vertically within the row to offer the right visual balance. + +When there are gaps in the data, use an en dash (–) to represent null or not applicable (N/A) values. + +## Usage guidelines + +Column headers follow the alignment of their data. + +All content should be centered vertically within the row to offer the right visual balance. + +When there are gaps in the data, use an en dash (–) to represent null or not applicable (N/A) values. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Standard panel](/page/standard-panel/) +* [Alert banner](/page/alert-banner/) diff --git a/docs/s2-docs/components/feedback/alert-banner.md b/docs/s2-docs/components/feedback/alert-banner.md new file mode 100644 index 00000000..2ade976d --- /dev/null +++ b/docs/s2-docs/components/feedback/alert-banner.md @@ -0,0 +1,168 @@ +--- + +title: "Alert banner" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback +* feedback +* overlay + related\_components: +* table +* alert-dialog + parent\_category: feedback + +--- + +# Alert banner + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Alert | [banner](https://opensource.adobe.com/spectrum-css/?path=/docs/components-alert-banner--docs) | +| Spectrum Web Components SWC: Alert | [Banner](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/alert-banner--docs\&globals=system:spectrum-two) | + +## Anatomy + +``` +alert banner +- background +- icon +- text +- button +- close button +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------- | ------------------------------------------------- | ------------- | ------------------------------------------ | +| text | string | – | | +| variant | neutral / informative / negative / accent neutral | – | | +| actionLabel | string | – | If undefined, this button does not appear. | +| isDismissible | boolean | false | | + +## External links + +Alert banners communicate high-priority messages that need immediate attention. They appear prominently in the interface and often prompt an action. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +An alert banner can include an icon-only close button to dismiss it. + +An alert banner ideally provides a way for a user to address an issue in-line with an action. It can have both an icon-only close button and a button with a contextual action to take. There should never be more than one button with a contextual action in an alert banner. + +An alert banner always has a semantic meaning and uses semantic colors. Only gray (neutral), blue (informative), and red (negative) are available as options. + +Text is required for all alert banners. The message should be concise and, if applicable, describe the next step that a user can take. + +When the text is too long for the available horizontal space, it wraps to form another line. In actionable alert banners, the button moves below the text prior to text wrapping. + +Whenever possible, add an in-line action button if there's a way for a user to quickly address the issue associated with an alert. + +The close button is optional, depending on context. Consider adding one to let a user easily dismiss the alert. + +Alert banners should be reserved only for high-signal, system-level alert messages, such as internet connection issues, expirations of subscriptions, or major changes. + +Don’t use yellow or orange colors for errors because the contrast is not accessible. + +If you need to show a “notice” message or other non-critical communication, use the gray (neutral) or blue (informative) semantic color options. Reserve the red (negative) option only for errors that directly interrupt or block a user’s experience — not for nice-to-know information. + +Don't include more than one action in an alert banner. Having more than one action to choose from can be overwhelming, and it can become difficult for users to decide what to do next in such a small space. + +Alert banners should appear at the top of a page, below the header. + +Don't show multiple alert banners at the same time. If a new alert banner appears with a higher priority message, it should replace an existing alert banner of lesser importance until the higher priority one has been addressed. + +Overlay an alert banner when it's expected to fade in and out without impacting the content underneath it, and when it's not hiding any important actions or information by being there. An alert banner should only overlay content if it is dismissible. + +Push an alert banner when it's expected to stay in place, when it's not dismissible, or when no information should be hidden from the view. + +If a user dismisses an alert banner without addressing an error that needs to be resolved, it should come back into view at the next possible occasion. + +Never allow alert banners to time out. Since these are system-level messages, they should not dismiss on their own unless there is a change in the system that resolves an issue (e.g., regaining internet connectivity after losing it). + +When used in the app frame, the alert banner appears above the Top App Bar (TAB) and header, or above the header if the TAB isn’t active. + +Learn more about how the Top App Bar (TAB) works in the app frame. + +## States + +Whenever possible, add an in-line action button if there's a way for a user to quickly address the issue associated with an alert. + +The close button is optional, depending on context. Consider adding one to let a user easily dismiss the alert. + +Don’t use yellow or orange colors for errors because the contrast is not accessible. + +Alert banners should appear at the top of a page, below the header. + +Push an alert banner when it's expected to stay in place, when it's not dismissible, or when no information should be hidden from the view. + +When used in the app frame, the alert banner appears above the Top App Bar (TAB) and header, or above the header if the TAB isn’t active. + +Learn more about how the Top App Bar (TAB) works in the app frame. + +## Behaviors + +Whenever possible, add an in-line action button if there's a way for a user to quickly address the issue associated with an alert. + +The close button is optional, depending on context. Consider adding one to let a user easily dismiss the alert. + +Don’t use yellow or orange colors for errors because the contrast is not accessible. + +Alert banners should appear at the top of a page, below the header. + +Push an alert banner when it's expected to stay in place, when it's not dismissible, or when no information should be hidden from the view. + +When used in the app frame, the alert banner appears above the Top App Bar (TAB) and header, or above the header if the TAB isn’t active. + +Learn more about how the Top App Bar (TAB) works in the app frame. + +## Usage guidelines + +Whenever possible, add an in-line action button if there's a way for a user to quickly address the issue associated with an alert. + +The close button is optional, depending on context. Consider adding one to let a user easily dismiss the alert. + +Don’t use yellow or orange colors for errors because the contrast is not accessible. + +Alert banners should appear at the top of a page, below the header. + +Push an alert banner when it's expected to stay in place, when it's not dismissible, or when no information should be hidden from the view. + +When used in the app frame, the alert banner appears above the Top App Bar (TAB) and header, or above the header if the TAB isn’t active. + +Learn more about how the Top App Bar (TAB) works in the app frame. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Table](/page/table/) +* [Alert dialog](/page/alert-dialog/) diff --git a/docs/s2-docs/components/feedback/alert-dialog.md b/docs/s2-docs/components/feedback/alert-dialog.md new file mode 100644 index 00000000..53003176 --- /dev/null +++ b/docs/s2-docs/components/feedback/alert-dialog.md @@ -0,0 +1,117 @@ +--- + +title: "Alert dialog" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback +* feedback +* overlay + related\_components: +* alert-banner +* coach-indicator + parent\_category: feedback + +--- + +# Alert dialog + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Alert | [dialog](https://opensource.adobe.com/spectrum-css/?path=/docs/components-alert-dialog--docs) | +| Spectrum Web Components SWC: Alert | [Dialog](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/alert-dialog--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [AlertDialog](https://react-spectrum.adobe.com/s2/index.html?path=/docs/alertdialog--docs) | + +## Anatomy + +``` +alert dialog +- alert dialog container +- title +- description +- primary action +- secondary action (optional) +- cancel action (optional) +- overlay +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------------- | ----------------------------------------------------------------------- | ------------- | ------------------------------------------ | +| title | string | – | | +| description | string | – | | +| variant | confirmation / information / warning / destructive / error confirmation | – | | +| primaryActionLabel | string | – | | +| secondaryActionLabel | string | – | If undefined, this button does not appear. | +| cancelActionLabel | string | cancel | If undefined, this button does not appear. | + +## External links + +Alert dialogs present critical information that must be acknowledged. They appear over the interface and block further interaction until an action is selected. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.” + +Alert dialogs can include up to three buttons if a secondary outline button label is defined. If no label is defined, the button won’t appear. The secondary outline button should use a short, actionable phrase that clearly communicates the result of selecting the action—typically describing the previous step or an alternative choice. + +An alert dialog must include at least one button. The primary action label refers to the rightmost button in the dialog footer for languages that read left to right. It should use a short, actionable phrase that clearly communicates the result of selecting the action—whether that means moving forward or dismissing the dialog. + +"Use the appropriate variant based on the context of the message:" + +Alert dialogs should include a description when available. The description briefly communicates any additional information or context a user needs to make a decision based on the options presented. + +All alert dialogs must have a title. The title appears at the top of the dialog and uses a few words to convey the outcome of what will happen if a user continues with the primary action. + +When the title and description text are too long for the available horizontal space, they wrap to form another line. + +Alert dialogs can include up to three buttons. When horizontal space is limited, the buttons stack vertically. Buttons should be ordered by ascending importance, with the most critical action placed at the end or bottom of the stack. + +Alert dialogs are interruptive, so they should be reserved for important information that users must acknowledge before continuing a task or workflow. Use them only when absolutely necessary—not for low-priority notifications or excessive confirmations. + +Alert dialogs are designed to pause the experience until a decision is made, so only one should appear at a time. Avoid opening an alert dialog from within another. If a situation seems to require a sequence of decisions, consider using a different design pattern. + +## States + +When the title and description text are too long for the available horizontal space, they wrap to form another line. + +## Behaviors + +When the title and description text are too long for the available horizontal space, they wrap to form another line. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Alert banner](/page/alert-banner/) +* [Coach indicator](/page/coach-indicator/) diff --git a/docs/s2-docs/components/feedback/coach-indicator.md b/docs/s2-docs/components/feedback/coach-indicator.md new file mode 100644 index 00000000..15dd7fbe --- /dev/null +++ b/docs/s2-docs/components/feedback/coach-indicator.md @@ -0,0 +1,103 @@ +--- + +title: "Coach indicator" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback + related\_components: +* alert-dialog +* coach-mark + parent\_category: feedback + +--- + +# Coach indicator + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Coach | [indicator](https://opensource.adobe.com/spectrum-css/?path=/docs/components-coach-indicator--docs) | +| Spectrum Web Components SWC: | [CoachIndicator](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/coachindicator--docs\&globals=system:spectrum-two) | + +## Anatomy + +``` +coach indicator +- inner stroke (small ring) +- outer stroke (big ring) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------- | +| cornerRounding | none / corner-radius-75 / corner-radius-100 / corner-radius-200 / corner-radius-300 / corner-radius-400 / corner-radius-500 / corner-radius-600 / corner-radius-700 / corner-radius-800 / full | – | | +| staticColor | white – If not set to white, the coach indicator uses the default | color. | | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +If not set to white, the coach indicator uses the default color. + +"The rounding of the indicator is determined by the shape of the object that it is highlighting. There are three types of rounding for coach indicators: no rounding, default rounding, and full rounding." + +No rounding means that there is no rounding on the object being indicated. In this case, a 6 px border radius rounding is applied to the coach indicator. + +Default rounding happens when an object has its own rounding, but isn’t fully rounded. In this case, the coach indicator should have the same rounding of that object with a 2 px gap. + +Full rounding occurs when an object already has a rounded style that gives it a pill shape (e.g., a button). In this case, the coach indicator is also rounded. + +The animation is always on the coach indicator. When an implementation is unable to animate the coach indicator, it can use a non-animated version to provide a similar experience. + +Coach indicators adopt the shape of the object they highlight. A 2 px space separates the indicator from the object’s placement area, creating padding on all sides. + +When an indicator needs to be placed on top of a visual, use the static white option. Static white does not change values depending upon the color theme. + +"Coach indicators are typically paired with coach marks to create accessible user onboarding experiences. When using coach indicators:" + +## States + +"Coach indicators are typically paired with coach marks to create accessible user onboarding experiences. When using coach indicators:" + +## Behaviors + +"Coach indicators are typically paired with coach marks to create accessible user onboarding experiences. When using coach indicators:" + +## Usage guidelines + +"Coach indicators are typically paired with coach marks to create accessible user onboarding experiences. When using coach indicators:" + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Alert dialog](/page/alert-dialog/) +* [Coach mark](/page/coach-mark/) diff --git a/docs/s2-docs/components/feedback/coach-mark.md b/docs/s2-docs/components/feedback/coach-mark.md new file mode 100644 index 00000000..6b329cbb --- /dev/null +++ b/docs/s2-docs/components/feedback/coach-mark.md @@ -0,0 +1,145 @@ +--- + +title: "Coach mark" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback + related\_components: +* coach-indicator +* contextual-help + parent\_category: feedback + +--- + +# Coach mark + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Coach | [mark](https://opensource.adobe.com/spectrum-css/?path=/docs/components-coach-mark--docs) | +| Spectrum Web Components SWC: | [Coachmark](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/coachmark--docs\&globals=system:spectrum-two) | + +## Anatomy + +``` +coach mark +- container +- image (optional) +- title +- more actions menu +- keyboard shortcuts +- description +- tour step counter +- button group +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ------------------------------------- | ------------- | ------------------------------------ | +| title | string | – | | +| description | string | – | | +| hideImage | boolean | false | Optional image to display in dialog. | +| actions | object – Configuration for coach mark | actions. | | + +## External links + +Coach marks are temporary messages that provide guidance during new or unfamiliar experiences. They can appear as a single message or be sequenced into a tour. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Actions is an area for certain configurations of a Coach mark and can contain an action menu, keyboard shortcut, or both. When both are enabled, the component layout adjusts to display the keyboard shortcut below the title. + +Coach marks can contain images or videos that relate to their content, such as demonstrations of gestures, the feature being used, or illustrations. + +Coach marks must include a title. Titles appear in bold at the top of the coach mark and use a few words to convey its purpose. + +All coach marks must have a description. Descriptions briefly communicate the information and context needed to educate a user about a new or unfamiliar product experience. + +When the text of a header or description is too long for the available horizontal space, it wraps to form another line. The steps in a tour are always shown in full and never wrap or truncate. + +By default, the step counter appears next to the title. If an action menu is also used, the keyboard shortcut appears below the title instead. + +Choose a width for coach marks that is spacious enough to accommodate all of their content. In a tour that includes several coach marks, keep the width consistent across each one. + +The “Previous” button should always be a quiet secondary button. + +The “Skip tour” and “Restart tour” options should only be available within the more actions menu. + +Titles help with way finding and setting context for what a user is learning about. Summarize the description of the coach mark in a few concise words. In a tour, use a different title for each coach mark to keep users active and engaged. Avoid repeating the title in the description. + +Coach marks are meant to provide quick overviews of functionality. Content should be at least a few words, but no more than a few sentences. + +The primary action should be brief and consistent. Use "OK" for a single coach mark. Within a tour, use “Next” for all but the last step, and “Finish” for the last step. Don’t use different primary action names for every step in a tour. + +When a part of the tour is dependent on a user taking an action, it’s okay to put the primary button in the disabled state as long as the user has a way to exit the tour. For a one-off coach mark, this means the primary button should remain as a route to dismiss. In a tour, it’s recommended to have the more actions menu present. + +When part of the tour is dependent on a user action, don't force users to confirm that they've taken that action. + +## States + +By default, the step counter appears next to the title. If an action menu is also used, the keyboard shortcut appears below the title instead. + +The “Previous” button should always be a quiet secondary button. + +The “Skip tour” and “Restart tour” options should only be available within the more actions menu. + +Coach marks are meant to provide quick overviews of functionality. Content should be at least a few words, but no more than a few sentences. + +When part of the tour is dependent on a user action, don't force users to confirm that they've taken that action. + +## Behaviors + +By default, the step counter appears next to the title. If an action menu is also used, the keyboard shortcut appears below the title instead. + +The “Previous” button should always be a quiet secondary button. + +The “Skip tour” and “Restart tour” options should only be available within the more actions menu. + +Coach marks are meant to provide quick overviews of functionality. Content should be at least a few words, but no more than a few sentences. + +When part of the tour is dependent on a user action, don't force users to confirm that they've taken that action. + +## Usage guidelines + +The “Previous” button should always be a quiet secondary button. + +The “Skip tour” and “Restart tour” options should only be available within the more actions menu. + +Coach marks are meant to provide quick overviews of functionality. Content should be at least a few words, but no more than a few sentences. + +When part of the tour is dependent on a user action, don't force users to confirm that they've taken that action. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Coach indicator](/page/coach-indicator/) +* [Contextual help](/page/contextual-help/) diff --git a/docs/s2-docs/components/feedback/contextual-help.md b/docs/s2-docs/components/feedback/contextual-help.md new file mode 100644 index 00000000..2d3bb8ec --- /dev/null +++ b/docs/s2-docs/components/feedback/contextual-help.md @@ -0,0 +1,102 @@ +--- + +title: "Contextual help" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback + related\_components: +* coach-mark +* illustrated-message + parent\_category: feedback + +--- + +# Contextual help + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Contextual | [help](https://opensource.adobe.com/spectrum-css/?path=/docs/components-contextual-help--docs) | +| Spectrum Web Components SWC: Contextual | [Help](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/contextual-help--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [ContextualHelp](https://react-spectrum.adobe.com/s2/index.html?path=/docs/contextualhelp--docs) | + +## Anatomy + +``` +contextual help +- action button +- popover +- title +- description +- link +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | --------------------------------------------------------------------- | +| icon | info / help info | – | | +| popoverPlacement | top / top left / top right / top start / top end / bottom / bottom left / bottom right / bottom start / bottom end / left / left top / left bottom / start / start top / start bottom / right / right top / right bottom / end / end top / end bottom bottom start | – | | +| popoverOffset | number | 8 | | +| href | string | – | Optional URL within contextual help content like a 'Learn more' link. | +| popoverCrossOffset | number | 0 | | +| containerPadding | number | 8 | | +| state | default / down / open / keyboard focus default | – | | + +## External links + +Contextual help displays additional information about the state of a nearby component or an entire view. It explains high-level concepts and can link to more detailed guidance. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +To make sure that a popover will stay within certain boundaries (e.g., a browser window) it’s possible to define a container, and a container padding value, to respect. + +The cross offset is the placement offset on the cross axis (x-axis for top and bottom, y-axis for left and right). + +A contextual help can have up to one link. + +The offset is the distance between the action button and the popover edge. There is a default value but this can also be adjusted depending on the context. + +Indicates whether contents are informative or provides helpful guidance. + +Contextual help can be used to explain why a component is disabled and how to enable it. Don’t make disabled components interactive (with focus states or hovering) as a way to display contextual information. + +"There are two size options for the action button in contextual help: extra-small and small. Regardless of size, the action button should be quiet and display only an icon." + +## States + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Coach mark](/page/coach-mark/) +* [Illustrated message](/page/illustrated-message/) diff --git a/docs/s2-docs/components/feedback/illustrated-message.md b/docs/s2-docs/components/feedback/illustrated-message.md new file mode 100644 index 00000000..bc1d0934 --- /dev/null +++ b/docs/s2-docs/components/feedback/illustrated-message.md @@ -0,0 +1,135 @@ +--- + +title: "Illustrated message" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback + related\_components: +* contextual-help +* in-line-alert + parent\_category: feedback + +--- + +# Illustrated message + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Illustrated | [message](https://opensource.adobe.com/spectrum-css/?path=/docs/components-illustrated-message--docs) | +| Spectrum Web Components SWC: | \[IllustratedMessage]\( | +| React Spectrum RSP: | [IllustratedMessage](https://react-spectrum.adobe.com/s2/index.html?path=/docs/illustratedmessage--docs) | + +## Anatomy + +``` +illustrated message +- illustration +- title +- description +- button group (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------------- | ------------------------------ | ------------- | ---------------------------------------------------------------------------------- | +| illustration | string | – | Optional illustration or icon displayed above the message. | +| size | s / m / l m | Size | of the illustration. | +| orientation | vertical / horizontal vertical | Orientation | of the illustrated message. | +| title | string | – | Primary heading text of the message. | +| description | string | – | Secondary descriptive text providing context or instructions. | +| primaryActionLabel | string | – | Label for the primary action button. If undefined, no primary action is shown. | +| secondaryActionLabel | string | – | Label for the secondary action button. If undefined, no secondary action is shown. | + +## External links + +Illustrated messages pair text with imagery to communicate a message with visual emphasis. They’re commonly used in empty states, feedback states, and error messaging. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +The secondary button provides a less prominent action that supports the overall message but is not the primary goal. It offers users an alternative path that’s relevant but lower priority. + +The primary button serves as the main call to action. It’s the clearest, most direct path forward for the user, and it should align with the purpose of the message. In an illustrated message—where visuals and copy work together to guide attention—the primary button anchors the experience. + +The description supports the illustration and buttons by delivering the core message in plain language. It helps users quickly grasp the purpose of the message and decide what to do next. + +A clear title for the description section in an illustrated message + +Orientation affects how users perceive and interact with content. Illustrated message layout can be horizontal or vertical. + +"Illustrated messages come in three different sizes: small, medium, and large. The medium size is the default and most frequently used option." + +The illustration sets the tone and draws attention. It visually reinforces the message’s purpose and helps users quickly understand the context before reading any text or taking action. + +Motion is an optional feature of illustrations, but it is not a requirement. When used, they should feel natural, intentional, and aligned with the emotional and functional goals of the message. + +Buttons in an illustrated message are designed to guide users toward a clear next step by translating the message’s intent into direct, actionable choices. They help users understand what will happen next and support decision-making within the context of the message. + +Horizontal orientation works best when there’s ample screen space, such as on desktop or wide containers, and when the message needs to sit alongside related content. It allows for a balanced layout where the illustration and text can appear side by side, supporting quick scanning and visual clarity. + +Vertical orientation is suited for constrained spaces like mobile screens or narrow containers. It supports a linear, top-to-bottom flow that guides the user through the illustration, description, and action in sequence. + +The linear illustration style works well for layouts that feature a number of illustrations together (such as a collection of cards). Linear illustrations draw a lower level of attention and blend in well with the UI, so it’s appropriate to use them in a collection of elements. Gradient illustrations draw a lot of attention in multiples, so they need to be used sparingly and sparsely. + +Gradient illustrations draw more attention because they’re very colorful. Using more then one in a given view will make the UI too busy and too loud. Use gradient illustrations sparingly to guide a user’s attention to engaging, high-value actions such as uploads, starting projects, or commenting. + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +Motion in illustrated messages can be used optionally to enhance engagement and reinforce meaning without overwhelming the user. When applied thoughtfully, they add subtle motion to the illustration—such as a gentle bounce, fade, or loop—that draws attention and supports the tone of the message. + +"These animations should be purposeful: they can signal success, soften interruptions, or guide the eye toward the primary action. However, they should never distract from the content or slow down the experience. Use them sparingly, especially in system messages or time-sensitive flows, and ensure they perform well across devices." + +Errors or critical messages should only use linear illustrations. Gradient illustrations use colors that can be misunderstood as semantic colors (e.g., green for positive, red for negative). They also have an upbeat and inspirational tone, which isn’t appropriate in situations where a user may be frustrated by something that’s an inconvenience or is disruptive to them in accomplishing their work. + +Use drag and drop when the user needs to complete a hands-on task—like uploading files, rearranging items, or customizing content. It’s an interaction pattern that supports direct manipulation, giving users a sense of control and immediacy. Drag and drop is ideal when the goal is action-oriented and the interface benefits from tactile engagement. + +Use an illustrated message when the goal is to communicate a state, guide a decision, or prompt an action. Illustrated messages are best for moments of transition—empty states, confirmations, errors, or onboarding—where visual context and clear messaging help orient the user. They’re not interactive themselves, but they support interaction by setting expectations and offering clear next steps. + +An illustrated message can be interruptive, so make it readily apparent that it’s adding value to a user’s experience or is putting the user on the right path to accomplish their goals. Don’t use an illustrated message for purely promotional purposes or for upsells of unrelated actions. + +## States + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +## Behaviors + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +## Usage guidelines + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Contextual help](/page/contextual-help/) +* [In-line alert](/page/in-line-alert/) diff --git a/docs/s2-docs/components/feedback/in-line-alert.md b/docs/s2-docs/components/feedback/in-line-alert.md new file mode 100644 index 00000000..2255bfdf --- /dev/null +++ b/docs/s2-docs/components/feedback/in-line-alert.md @@ -0,0 +1,97 @@ +--- + +title: "In-line alert" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback +* feedback +* overlay + related\_components: +* illustrated-message +* standard-dialog + parent\_category: feedback + +--- + +# In-line alert + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ------------------------------------ | --------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: In-line | [alert](https://opensource.adobe.com/spectrum-css/?path=/docs/components-in-line-alert--docs) | +| Spectrum Web Components Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/inlinealert--docs) | +| React Spectrum RSP: | [InlineAlert](https://react-spectrum.adobe.com/s2/index.html?path=/docs/inlinealert--docs) | + +## Anatomy + +``` +in-line alert +- background +- title (optional) +- icon +- body area +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | --------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------- | +| variant | neutral / informative / positive / notice / negative / accent neutral | – | | +| style | bold / subtle / outline outline | The | visual style of the alert. | +| href | string | – | Optional URL within in-line alert content like a 'Learn more' link. | +| heading | string | – | Optional heading text displayed at the top of the alert. | +| actionLabel | string | – | If undefined, this button does not appear. | + +## External links + +In-line alerts display non-modal messages connected to elements in a view. They’re often used in forms to show validation feedback across multiple fields. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +An in-line alert can have up to one button. This label should be kept concise, and it should only be used when there’s a direct action available that is related to the in-line alert text. + +Heading is optional for in-line alerts. + +The outline style is the default for in-line alerts. + +"There are five semantic variants:" + +When the title of an in-line alert is too long for the available horizontal space, it wraps to form another line. The optional icon in the top-right corner stays aligned to the top. + +## States + +## Behaviors + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Illustrated message](/page/illustrated-message/) +* [Standard dialog](/page/standard-dialog/) diff --git a/docs/s2-docs/components/feedback/standard-dialog.md b/docs/s2-docs/components/feedback/standard-dialog.md new file mode 100644 index 00000000..10bb6b84 --- /dev/null +++ b/docs/s2-docs/components/feedback/standard-dialog.md @@ -0,0 +1,140 @@ +--- + +title: "Standard dialog" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback +* feedback +* overlay + related\_components: +* in-line-alert +* takeover-dialog + parent\_category: feedback + +--- + +# Standard dialog + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: | [Dialog](https://opensource.adobe.com/spectrum-css/?path=/docs/components-dialog--docs) | +| Spectrum Web Components SWC: | [Dialog](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/dialog--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [Dialog](https://react-spectrum.adobe.com/s2/index.html?path=/docs/dialog--docs) | + +## Anatomy + +``` +standard dialog +- standard dialog container +- cover image (optional) +- close button (optional) +- header area +- title +- body area +- description (optional) +- footer area +- footer content (optional) +- button group +- overlay +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------------- | ----------- | ------------- | ------------------------------------------------------------------------ | +| title | string | – | | +| description | string | – | | +| hideImage | boolean | false | Optional image to display in dialog. | +| size | s / m / l m | – | | +| hideCloseButton | boolean | false | | +| footerContent | string | – | Optional footer content to display in the dialog footer like a checkbox. | +| primaryActionLabel | string | – | | +| secondaryActionLabel | string | – | If undefined, this button does not appear. | +| cancelActionLabel | string | cancel | If undefined, this button does not appear. | + +## External links + +Standard dialogs are containers that appear over the interface to present contextual information, tasks, or workflows. They’re centered on the screen and used for moderately complex actions that require focused attention. Interactions outside the dialog are blocked until it's dismissed or completed. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.” + +Standard dialogs can include up to three buttons if a secondary outline button label is defined. If no label is defined, the button won’t appear. The secondary outline button should use a short, actionable phrase that clearly communicates the result of selecting the action—typically describing the previous step or an alternative choice. + +The primary action label refers to the rightmost button in the dialog footer for languages that read left to right. It should use a short, actionable phrase that clearly communicates the result of selecting the action—whether that means moving forward or dismissing the dialog. + +The presence of a close button determines whether a dialog is dismissible. + +In both cases, pressing the Escape key should close the dialog and return the page to its previous state. This action should behave the same as clicking a close or cancel button. + +"Standard dialogs are available in three widths:" + +Dialogs automatically scale down to 90% of the screen width on smaller viewports. Height is flexible and adjusts to fit the content. + +Standard dialogs can include a full-bleed cover image at the top. Dialogs with a cover image should not be dismissible and rely on buttons in the footer area to close the dialog. + +Standard dialogs can include an optional description. Use the description to briefly provide additional context or information that helps users make an informed decision based on the available actions. + +All standard dialogs must include a title. The title appears at the top of the dialog and should briefly describe the expected outcome if the user proceeds with the primary action. If a cover image is shown, the title will appear below it. + +Standard dialogs appear in the center of the screen. + +When the title and description text are too long for the available horizontal space, they wrap to form another line. + +Standard dialogs can include up to three buttons. When horizontal space is limited, the buttons stack vertically. Buttons should be ordered by ascending importance, with the most critical action placed at the end or bottom of the stack. + +Avoid using a dismissible dialog when the user needs to confirm an action or make a decision. Instead, use a dismissible dialog for information that is optional or nice to know—content that can be quickly dismissed without requiring user action. + +A dismissible dialog should not include buttons in the footer. Instead, the dialog is dismissed by clicking the close button or the background overlay. + +Most dialog titles should communicate the primary action of the dialog. When possible, the button label should use the same language as the action mentioned in the title. For example, if the title is “Delete conversation,” the primary action button label should be “Delete.” + +## States + +Standard dialogs appear in the center of the screen. + +When the title and description text are too long for the available horizontal space, they wrap to form another line. + +## Behaviors + +Standard dialogs appear in the center of the screen. + +When the title and description text are too long for the available horizontal space, they wrap to form another line. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [In-line alert](/page/in-line-alert/) +* [Takeover dialog](/page/takeover-dialog/) diff --git a/docs/s2-docs/components/feedback/takeover-dialog.md b/docs/s2-docs/components/feedback/takeover-dialog.md new file mode 100644 index 00000000..1f022ddc --- /dev/null +++ b/docs/s2-docs/components/feedback/takeover-dialog.md @@ -0,0 +1,117 @@ +--- + +title: "Takeover dialog" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback +* feedback +* overlay + related\_components: +* standard-dialog +* toast + parent\_category: feedback + +--- + +# Takeover dialog + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Dialog Fullscreen | [Takeover](https://opensource.adobe.com/spectrum-css/?path=/story/components-dialog--fullscreen-takeover) | +| Spectrum Web Components SWC: Dialog Fullscreen | \[Takeover]\( | +| React Spectrum RSP: | [FullscreenDialog](https://react-spectrum.adobe.com/s2/index.html?path=/docs/fullscreendialog--docs\&globals=backgrounds.grid:!false) | + +## Anatomy + +``` +takeover dialog +- takeover dialog container +- header area +- title +- header content (optional) +- button group +- body area +- body content (optional) +- overlay +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------------- | ------------------------------------------------------------------------------------- | ------------- | ------------------------------------------ | +| title | string | – | | +| description | string | – | | +| variant | dialog / full screen dialog | – | | +| primaryActionLabel | string | – | | +| secondaryActionLabel | string | – | If undefined, this button does not appear. | +| cancelActionLabel | string | cancel | If undefined, this button does not appear. | +| slots | array – Areas where other components can be inserted (e.g. Side navigation, Steplist, | Forms). | | + +## External links + +Takeover dialogs are full-screen modals used for complex or immersive workflows. They block access to the rest of the interface and are typically used when multiple steps or tools need focused attention. Use when the task requires the entire screen and shouldn’t be interrupted. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +The takeover dialog supports two slots—one in the header and one in the body—where other components can be inserted. + +"Takeover dialogs support two layout variants: dialog and full-screen." + +All takeover dialogs must include a title. The title appears at the top of the dialog and should briefly describe the expected outcome if the user proceeds with the primary action. + +A takeover dialog must include at least one button. The primary action label refers to the rightmost button in the dialog footer for languages that read left to right. It should use a short, actionable phrase that clearly communicates the result of selecting the action—whether that means taking action, progressing through a workflow, or dismissing the dialog. + +Takeover dialogs can include up to three buttons if a secondary outline button label is defined. If no label is defined, the button won’t appear. The secondary outline button should use a short, actionable phrase that clearly communicates the result of selecting the action—typically describing the previous step or an alternative choice. + +By default, a takeover dialog that includes a button to cancel or go back will be labeled “Cancel.” + +When the title is too long for the available horizontal space, it wraps to form another line. + +Takeover dialogs can optionally include additional elements in the header custom content area. When horizontal space is limited, the header custom content will be displayed underneath the title. + +Most dialog titles should communicate the primary action of the dialog. When possible, the button label should use the same language as the action mentioned in the title. For example, if the title is “Delete conversation,” the primary action button label should be “Delete.” + +## States + +When the title is too long for the available horizontal space, it wraps to form another line. + +## Behaviors + +When the title is too long for the available horizontal space, it wraps to form another line. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Standard dialog](/page/standard-dialog/) +* [Toast](/page/toast/) diff --git a/docs/s2-docs/components/feedback/toast.md b/docs/s2-docs/components/feedback/toast.md new file mode 100644 index 00000000..7cb3bf72 --- /dev/null +++ b/docs/s2-docs/components/feedback/toast.md @@ -0,0 +1,157 @@ +--- + +title: "Toast" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback +* feedback +* overlay + related\_components: +* takeover-dialog +* tooltip + parent\_category: feedback + +--- + +# Toast + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Toast](https://opensource.adobe.com/spectrum-css/?path=/docs/components-toast--docs) | +| Spectrum Web Components SWC: | \[Toast]\( | +| React Spectrum RSP: | [Toast](https://react-spectrum.adobe.com/s2/index.html?path=/docs/toast--docs) | + +## Anatomy + +``` +toast +- background +- icon +- text +- button +- close button +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------------- | --------------------------------------------------- | ------------- | ------------------------------------------ | +| text | string | – | | +| variant | neutral / informative / positive / negative neutral | – | | +| actionLabel | string | – | If undefined, this button does not appear. | +| isAutoDismissible | boolean | false | | + +## External links + +Toasts display brief, temporary notifications. They appear briefly without blocking interaction and typically do not require user action. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Toasts must include text to communicate a message. Write the text as concisely as possible while still being clear about what has happened or is happening. + +The neutral toast is the default variant. It is gray and does not have an icon. This is used when the message is neutral in tone or when its semantics do not fit in any of the other variants. + +The informative toast uses the informative semantic color (blue) and has an info icon to help those with color vision deficiency discern the message tone. This should be used when the message should call extra attention compared to the neutral variant. + +The positive toast uses the positive semantic color (green) and has a checkmark icon to help those with color vision deficiency discern the message tone. This is used to inform about a successful action or completion of a task. + +The negative toast uses the negative semantic color (red) and has an alert icon to help those with color vision deficiency to discern the message tone. This is used to show an error or failure. + +By default, a toast will dismiss when the user clicks the close button. A toast also has the option to auto-dismiss. Be sure to set a minimum of 5 seconds so that users can have time to read the toast message. If an actionable toast is set to auto-dismiss, make sure that the action is still available elsewhere in the app. + +When the text is too long for the available horizontal space, it wraps to form another line. In actionable toasts, the button moves below the text prior to text wrapping. + +The default state can display up to three toasts at a time. To view additional toasts beyond this limit, users can click the “Show all” action button. Alternatively, they can reveal remaining toasts by interacting with a button or dismissing the component. Additionally, hovering over the upper part of the toasts triggers a subtle animation, signaling to the user that the group can be fully expanded. + +Please refer to more multiple toasts usage guideline below. + +Toasts should only be used for confirmations, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience. + +Dialogs are ideal for when a situation requires a user’s attention, either for displaying important information or prompting for a response. + +By default, a toast is placed at the bottom center for both desktop and mobile platform scales to avoid disrupting the user experience. + +For desktop applications, a toast should be placed 16 px away from the bottom of the viewport. + +If a toast isn’t noticeable or disrupts the user experience, its placement can be changed to bottom end, top end, or top center. + +Actionable toasts should only have one button. + +Actionable toasts should not have a button with a redundant action. For example, including a “Dismiss” button would be redundant because all toasts already have a close button. + +Products should allow for users to be able turn off all types of alerts. Doing this helps people who want to focus and minimize information that they may find non-essential. + +## States + +Please refer to more multiple toasts usage guideline below. + +Dialogs are ideal for when a situation requires a user’s attention, either for displaying important information or prompting for a response. + +By default, a toast is placed at the bottom center for both desktop and mobile platform scales to avoid disrupting the user experience. + +For desktop applications, a toast should be placed 16 px away from the bottom of the viewport. + +If a toast isn’t noticeable or disrupts the user experience, its placement can be changed to bottom end, top end, or top center. + +Actionable toasts should only have one button. + +## Behaviors + +Please refer to more multiple toasts usage guideline below. + +Dialogs are ideal for when a situation requires a user’s attention, either for displaying important information or prompting for a response. + +By default, a toast is placed at the bottom center for both desktop and mobile platform scales to avoid disrupting the user experience. + +For desktop applications, a toast should be placed 16 px away from the bottom of the viewport. + +If a toast isn’t noticeable or disrupts the user experience, its placement can be changed to bottom end, top end, or top center. + +Actionable toasts should only have one button. + +## Usage guidelines + +Dialogs are ideal for when a situation requires a user’s attention, either for displaying important information or prompting for a response. + +By default, a toast is placed at the bottom center for both desktop and mobile platform scales to avoid disrupting the user experience. + +For desktop applications, a toast should be placed 16 px away from the bottom of the viewport. + +If a toast isn’t noticeable or disrupts the user experience, its placement can be changed to bottom end, top end, or top center. + +Actionable toasts should only have one button. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Takeover dialog](/page/takeover-dialog/) +* [Tooltip](/page/tooltip/) diff --git a/docs/s2-docs/components/feedback/tooltip.md b/docs/s2-docs/components/feedback/tooltip.md new file mode 100644 index 00000000..4bb04f0c --- /dev/null +++ b/docs/s2-docs/components/feedback/tooltip.md @@ -0,0 +1,133 @@ +--- + +title: "Tooltip" +source\_url: +last\_updated: 2026-02-02 +category: components/feedback +component\_type: feedback +status: published +tags: + +* components-feedback + related\_components: +* toast +* calendar + parent\_category: feedback + +--- + +# Tooltip + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Tooltip](https://opensource.adobe.com/spectrum-css/?path=/docs/components-tooltip--docs) | +| Spectrum Web Components SWC: | [Tooltip](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/tooltip--docs) | +| React Spectrum RSP: | [Tooltip](https://react-spectrum.adobe.com/s2/index.html?path=/docs/tooltip--docs) | + +## Anatomy + +``` +tooltip +- background +- label +- tip +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------------- | ---------------------------------------- | ------------- | ----------------------------------------------- | +| label | string | – | | +| variant | neutral / informative / negative neutral | – | | +| hasIcon | boolean | false | If the neutral variant, there is never an icon. | +| maxWidth | number 160 units: | pixels | | +| placement | top / bottom / left / right top | – | | +| shouldFlip | boolean | false | | +| offset | number 4 units: | pixels | | +| containerPadding | number 8 units: | pixels | | + +## External links + +Tooltips display contextual information related to a specific component. They appear on hover or focus to clarify purpose or behavior. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +All tooltips have a label. The label communicates the contextual help or information about specific components when a user hovers over or focuses on them. + +By default, tooltips are the neutral variant. These are the most common variant because most tooltips are used to only disclose additional information, without conveying a semantic meaning. The neutral variant never includes an icon. + +"Tooltips also come in semantic variants: informative (blue), and negative (red). An icon is required for these variants to ensure information isn’t conveyed by color alone." + +2 of the 3 tooltip variants (informative and negative) can include an icon to supplement the messaging. These icons are predefined and can not be customized. Unless it's being used to provide context about the exact same icon, a semantic tooltip should always show an icon. Doing this is essential for helping users with color vision deficiency to discern the message tone. + +A tooltip is positioned in relation to its target. + +This option determines whether or not a tooltip should be able to switch sides when constrained by space. A tooltip placed at the top would flip to be placed at the bottom (and vice versa), and a tooltip placed at the left would flip to be placed at the right (and vice versa). + +The offset is the distance between the end of the tip and the target. + +To make sure that the tooltip will stay within certain boundaries (e.g., a browser window) it’s possible to define a container and a container padding value to respect. + +When the label is too long for the available horizontal space, it wraps to form another line. + +A tooltip fades in and out when showing and hiding, and slides a short distance from the source to indicate its origin. The direction of the slide (left, right, top, bottom) depends on the placement of the tooltip. The animation attributes (duration, easing, offset) are the same whether it’s showing or hiding. + +Tooltips attached to help icons appear immediately. For conventional UI elements where a tooltip appearing immediately would be intrusive, delay appearance with a warmup period. + +The warmup period is a global timer that requires the cursor to remain on a UI element for the allotted time before a tooltip appears. Once this period is complete, a tooltip appears instantly on any hovered-upon UI element until the cursor is in an area that does not trigger a tooltip for the duration of the cooldown period. + +Icons are not always easy to identify on their own. When you use components that don’t have labels — for example, icon-only action buttons and tabs — make sure to use tooltips to provide context for the icons. + +For example, in a scenario where a user is entering their password into a field, the crucial information would be to state the password requirements. Supplementary context would be a message about how to get help if they have forgotten their password. + +Tooltips should be as concise and clear as possible. Keep the text to 1 or 2 short sentences. If the information you need to communicate is longer than that, look into using a different design. + +If a tooltip is written in a full sentence (or is 2 or more sentences), include a period at the end. If it's a short phrase or is only the name of a tool, action, or icon, don't add a period to the end. + +Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links. + +## States + +When the label is too long for the available horizontal space, it wraps to form another line. + +Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links. + +## Behaviors + +When the label is too long for the available horizontal space, it wraps to form another line. + +Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links. + +## Usage guidelines + +Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Toast](/page/toast/) +* [Calendar](/page/calendar/) diff --git a/docs/s2-docs/components/inputs/calendar.md b/docs/s2-docs/components/inputs/calendar.md new file mode 100644 index 00000000..a54e4299 --- /dev/null +++ b/docs/s2-docs/components/inputs/calendar.md @@ -0,0 +1,163 @@ +--- + +title: "Calendar" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* tooltip +* checkbox + parent\_category: inputs + +--- + +# Calendar + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Calendar](https://opensource.adobe.com/spectrum-css/?path=/docs/components-calendar--docs) | +| Spectrum Web Components Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/calendar--docs) | +| React Spectrum RSP: | [Calendar](https://react-spectrum.adobe.com/s2/index.html?path=/docs/calendar--docs) | + +## Anatomy + +``` +calendar +- chevron +- month +- year +- week +- days +time field (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------- | ------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------- | +| currentMonth | number – The month currently displayed in the calendar (1 = January, 12 = | December). | | +| currentYear | number – The year currently displayed in the calendar (Gregorian year | number). | | +| selectionMode | single / range single | Controls | whether the calendar allows selecting a single date or a date range. | +| isDisabled | boolean | false | | +| isError | boolean | false | | +| minValue | string | – | The minimum allowed date that a user may select (ISO format string). | +| maxValue | string | – | The maximum allowed date that a user may select (ISO format string). | +| showTimeZone | boolean | false | Whether to show a time zone indicator in the calendar. | +| days | array – An array of days displayed in the current calendar | view. | | + +## External links + +Calendars display the days of a selected month and highlight the current day. They support navigating to past or future months and selecting a specific date. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +"An array of days that are displayed in the current calendar view. This includes:" + +The maximum amount of months displayed in the calendar popover is three. + +The minimum amount of months displayed in the calendar popover is one. + +The calendar popover may display an error as error text when a user attempts to provide an input that violates the defined constraints of the date selection. For example, when the user selects dates that fall outside allowable limits, or conflict with contextual restrictions. + +The calendar popover is disabled. For example, a month within a three-month range is disabled. + +The types of selection available for the calendar. + +The current year or month displayed in the calendar popover. + +When a day or several days are unavailable within the calendar popover, each day should display a strikethrough to help the user understand that they cannot select it. + +Disabled days use a distinct gray style to clearly differentiate them from unavailable days. When the calendar prevents selection of past dates, this visual treatment helps users distinguish disabled days from those marked as unavailable. + +In a date selection system, users often need to distinguish between dates that cannot be selected and dates that are simply inactive. Supporting both states improves clarity and prevents errors. + +"Here’s an example scenario: A potential guest is browsing a calendar to book a stay at a vacation rental." + +"Unavailable dates: Days when the rental is already booked or blocked by the owner. These appear with a strikethrough, indicating they cannot be selected." + +"Disabled dates: Past dates that are no longer valid for booking. These appear visually distinct (gray style) to show they are inactive." + +Guests see unavailable dates marked clearly so they don’t attempt to select them. Hosts or admins can view past dates as disabled and also mark future dates as unavailable when needed. + +By supporting both behaviors, the system provides a clear, intuitive experience for different user roles and prevents confusion during date selection. + +The range fill shows which days fall between two selected dates. If the range spans more than the three-month calendar view, it ends on the last visible day but continues as users navigate with the calendar chevrons. A dashed stroke outlines the fill to improve visibility on bright screens and for users with vision impairments. + +The strikethrough styling intentionally accommodates internationalization. + +The calendar popover supports a disabled state but not a read-only state. Dates or months may be temporarily disabled based on context (for example, if a user must complete a task before selecting a date). In these cases, help text can explain why certain dates are unavailable. + +If a date picker is truly read-only, users shouldn’t be able to open the calendar popover at all, since they can’t interact with it. + +The calendar popover can also include time-specific fields, allowing users to specify start and end times. + +## States + +"Here’s an example scenario: A potential guest is browsing a calendar to book a stay at a vacation rental." + +"Disabled dates: Past dates that are no longer valid for booking. These appear visually distinct (gray style) to show they are inactive." + +By supporting both behaviors, the system provides a clear, intuitive experience for different user roles and prevents confusion during date selection. + +The strikethrough styling intentionally accommodates internationalization. + +If a date picker is truly read-only, users shouldn’t be able to open the calendar popover at all, since they can’t interact with it. + +The calendar popover can also include time-specific fields, allowing users to specify start and end times. + +## Behaviors + +"Here’s an example scenario: A potential guest is browsing a calendar to book a stay at a vacation rental." + +"Disabled dates: Past dates that are no longer valid for booking. These appear visually distinct (gray style) to show they are inactive." + +By supporting both behaviors, the system provides a clear, intuitive experience for different user roles and prevents confusion during date selection. + +The strikethrough styling intentionally accommodates internationalization. + +If a date picker is truly read-only, users shouldn’t be able to open the calendar popover at all, since they can’t interact with it. + +The calendar popover can also include time-specific fields, allowing users to specify start and end times. + +## Usage guidelines + +The strikethrough styling intentionally accommodates internationalization. + +If a date picker is truly read-only, users shouldn’t be able to open the calendar popover at all, since they can’t interact with it. + +The calendar popover can also include time-specific fields, allowing users to specify start and end times. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Tooltip](/page/tooltip/) +* [Checkbox](/page/checkbox/) diff --git a/docs/s2-docs/components/inputs/checkbox-group.md b/docs/s2-docs/components/inputs/checkbox-group.md new file mode 100644 index 00000000..6e970e37 --- /dev/null +++ b/docs/s2-docs/components/inputs/checkbox-group.md @@ -0,0 +1,102 @@ +--- + +title: "Checkbox group" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* checkbox +* color-area + parent\_category: inputs + +--- + +# Checkbox group + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Field | [Group](https://opensource.adobe.com/spectrum-css/?path=/docs/components-field-group--docs) | +| Spectrum Web Components SWC: Field | \[Group]\( | +| React Spectrum RSP: | [CheckboxGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/checkboxgroup--docs) | + +## Anatomy + +``` +checkbox group +- field label +- checkbox +- help text +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ------------------------------ | ------------- | ----------- | +| label | string | – | | +| labelPosition | top / side top | – | | +| necessityIndicator | text / icon icon | – | | +| isRequired | boolean | false | | +| orientation | horizontal / vertical vertical | – | | +| isError | boolean | false | | +| isDisabled | boolean | false | | +| description | string | – | | +| errorMessage | string | – | | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +When a description is present and an error is triggered, it is replaced with an error message. Once the error is resolved, the help text description reappears. + +A checkbox group in a disabled state shows that a selection exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later. The field label, checkboxes, and help text are all displayed in a disabled state when the checkbox group is disabled. + +Checkbox groups can be either horizontal or vertical. By default, checkbox groups are stacked vertically. Use a horizontal checkbox group when vertical space is limited. + +Checkbox groups can be marked as optional or required, depending on the situation. Optional checkbox groups are either denoted with text added to the end of the label — “(optional)” — or have no indication at all. + +"For required checkbox groups, there are two necessity indicator options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include help text to explain what the asterisk means." + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +Checkbox groups should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These checkbox groups without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”). + +## States + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Checkbox](/page/checkbox/) +* [Color area](/page/color-area/) diff --git a/docs/s2-docs/components/inputs/checkbox.md b/docs/s2-docs/components/inputs/checkbox.md new file mode 100644 index 00000000..154e8f9c --- /dev/null +++ b/docs/s2-docs/components/inputs/checkbox.md @@ -0,0 +1,126 @@ +--- + +title: "Checkbox" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* calendar +* checkbox-group + parent\_category: inputs + +--- + +# Checkbox + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Field | [group](https://opensource.adobe.com/spectrum-css/?path=/docs/components-field-group--docs) | +| Spectrum Web Components SWC: Field | \[Group]\( | +| React Spectrum RSP: | [Checkbox](https://react-spectrum.adobe.com/s2/index.html?path=/docs/checkbox--docs) | + +## Anatomy + +``` +checkbox +- control +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| --------------- | ----------------------------------------------- | ------------- | ----------------------------------------------------------------------------- | +| label | string | – | When the label is not defined, the checkbox appears as a standalone checkbox. | +| isSelected | boolean | false | | +| isIndeterminate | boolean | false | When a checkbox is indeterminate, it overrides the selection state. | +| size | s / m / l / xl m | – | | +| isEmphasized | boolean | false | | +| isDisabled | boolean | false | | +| isError | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Checkboxes support selecting one or more items from a list. Each item can be selected independently or in combination with others. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Checkboxes can be marked as having an error to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid. For example, in a form that requires a user to acknowledge legal terms before proceeding, the checkbox would show an unchecked error to communicate that it needs to be selected. + +A checkbox in a disabled state shows that a selection exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later. + +By default, checkboxes are not emphasized (gray). This version is optimal for when the checkbox is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content. + +The emphasized (blue) version provides a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a checkbox need to be noticed. + +"Checkboxes come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +Checkboxes can be in an indeterminate state when they represent both selected and not selected values. + +Checkboxes can be selected or not selected. + +Checkboxes should always have a label. When the label is not defined, a checkbox becomes standalone. Standalone checkboxes are only used when their connection to other components is clear and they give sufficient context — for example, in application panels. + +A checkbox can be navigated using a keyboard. The keyboard focus state takes the checkbox’s visual hover state and adds a blue ring to the checkbox in focus. + +When the label is too long for the horizontal space available, it wraps to form another line. + +Emphasized checkboxes are optimal for forms, settings, etc. where the checkboxes need to be noticed, or to bring attention to selected items such as cards or table rows. Not emphasized checkboxes are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas. + +Standalone checkboxes should be used in situations where the context is clear without an associated text label. An example of this would be when a checkbox is connected to other controls inside of a panel. + +Checkboxes and radio buttons are not interchangeable. A set of checkboxes should be used to select as many options as desired (or none). A set of radio buttons should be used to select only a single option from a list of mutually exclusive options. + +Use checkboxes to show selection, such as choosing multiple table rows. Use switches to show activation, like turning a setting on or off. Unlike switches, checkboxes can display an error state. + +Sets of checkboxes should always have a clear label that describes what the list of options represents and guides users what to do. This is important for accessibility, since a screen reader will read the label before each option. + +When a checkbox represents multiple values that are not identical, the checkbox should appear in the indeterminate state. Any subsequent click or tap should select the checkbox, and update all values to be selected. Another click or tap after that should deselect the checkbox, and update all values to be not selected. + +## States + +When the label is too long for the horizontal space available, it wraps to form another line. + +## Behaviors + +When the label is too long for the horizontal space available, it wraps to form another line. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Calendar](/page/calendar/) +* [Checkbox group](/page/checkbox-group/) diff --git a/docs/s2-docs/components/inputs/color-area.md b/docs/s2-docs/components/inputs/color-area.md new file mode 100644 index 00000000..dd5abaec --- /dev/null +++ b/docs/s2-docs/components/inputs/color-area.md @@ -0,0 +1,123 @@ +--- + +title: "Color area" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* design-tokens +* color + related\_components: +* checkbox-group +* color-handle + parent\_category: inputs + +--- + +# Color area + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Color | [area](https://opensource.adobe.com/spectrum-css/?path=/docs/components-color-area--docs) | +| Spectrum Web Components SWC: Color | [Area](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/color-area--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [ColorArea](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorarea--docs) | + +## Anatomy + +``` +color area +- area +- handle +- loupe +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ----------------------------------------------- | ------------- | ------------------------------------------- | +| background | string | – | This will vary depending on implementation. | +| x-value | number – Number (from x-minValue to | x-maxValue) | | +| x-minValue | number | 0 | | +| x-maxValue | number | 100 | | +| y-value | number – Number (from y-minValue to | y-maxValue) | | +| y-minValue | number | 0 | | +| y-maxValue | number | 100 | | +| step | number | 1 | | +| width | number 192 units: | px | | +| height | number 192 units: | px | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +A color area enables visual selection of two color properties at once. It's often paired with a color slider or color wheel. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A color area in a disabled state shows that an input exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that the area may become available later. + +A color area’s height and width can be customized appropriately for its context. + +The step refers to the increment by which these values increase or decrease. A step value of 1 (default) allows a user to only select whole numbers within the min and max range. + +The x and y values are the numbers selected within the color area’s horizontal and vertical axes, respectively. + +The x/y min and max values also can be customized appropriately for what the color area is being used for. By default, the min value starts at 0 and max value is set to 100. + +A color area can be navigated using a keyboard. The keyboard focus state enlarges the handle to become twice as large. + +The color area’s handle can slide all the way over the edge of the area. It always displays the selected color inside the handle and never gets cut off by the border or any container. + +Minimum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +When using color areas, it’s important to clearly display the color selection in real time. This can be in a color swatch, directly on the canvas, or both. + +The color loupe component can be used above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type. + +## States + +A color area can be navigated using a keyboard. The keyboard focus state enlarges the handle to become twice as large. + +Minimum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +## Behaviors + +A color area can be navigated using a keyboard. The keyboard focus state enlarges the handle to become twice as large. + +Minimum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Checkbox group](/page/checkbox-group/) +* [Color handle and loupe](/page/color-handle/) diff --git a/docs/s2-docs/components/inputs/color-handle-and-loupe.md b/docs/s2-docs/components/inputs/color-handle-and-loupe.md new file mode 100644 index 00000000..5ad72c83 --- /dev/null +++ b/docs/s2-docs/components/inputs/color-handle-and-loupe.md @@ -0,0 +1,113 @@ +--- + +title: "Color handle and loupe" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* design-tokens +* color + related\_components: +* color-area +* color-slider + parent\_category: inputs + +--- + +# Color handle and loupe + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Color | [handle](https://opensource.adobe.com/spectrum-css/?path=/docs/components-color-handle--docs) | +| Spectrum Web Components SWC: Color | [Handle](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/color-handle--docs\&globals=system:spectrum-two) | + +## Anatomy + +``` +color handle and loupe +- color handle +- opacity checkerboard +- color loupe (optional) +- opacity checkerboard +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------- | +| channel | hue / saturation / lightness / red / green / blue / alpha hue | Which | channel of the color this handle controls. Use 'alpha' for opacity. | +| isDisabled | boolean | false | | + +## External links + +Color handles select or adjust a color value along a track or wheel. They’re often paired with a color loupe to preview the selected color in context. The outer border is not included in the handle’s size. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +In the disabled state, the color handle indicates that input exists but is unavailable. The color loupe is not visible, as it only appears when interacting with the handle. + +Color handle and loupe are purely indicators - they report the current color channel values at the handle position. + +In the color area and color slider, the handle can slide all the way to the edge of the component. It always displays the selected color inside the handle and never gets cut off by the border or any container. + +When using transparent colors, the handle and loupe display an opacity checkerboard background to clearly show the level of transparency. + +The loupe is a floating element positioned above the handle. It provides a preview that reflects the color currently sampled by its parent color component and disappears when the interaction ends. + +The keyboard focus state enlarges the handle to become twice as large. The loupe is a visual-only element and should not receive focus since it does not provide interactive functionality. + +"Color selection usually happens using a variety of input methods (color area, color slider, color wheel). The color loupe should display the final output color: the combined values from multiple color inputs." + +"The number of input methods is determined by the color space (or “mode”), for example:" + +The color loupe component can be used above the handle to show the selected color that would otherwise be covered by a cursor, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type. + +## States + +When using transparent colors, the handle and loupe display an opacity checkerboard background to clearly show the level of transparency. + +"The number of input methods is determined by the color space (or “mode”), for example:" + +## Behaviors + +When using transparent colors, the handle and loupe display an opacity checkerboard background to clearly show the level of transparency. + +"The number of input methods is determined by the color space (or “mode”), for example:" + +## Usage guidelines + +"The number of input methods is determined by the color space (or “mode”), for example:" + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Color area](/page/color-area/) +* [Color slider](/page/color-slider/) diff --git a/docs/s2-docs/components/inputs/color-handle.md b/docs/s2-docs/components/inputs/color-handle.md new file mode 100644 index 00000000..958bb902 --- /dev/null +++ b/docs/s2-docs/components/inputs/color-handle.md @@ -0,0 +1,23 @@ +--- + +title: "Color handle" +source\_url: +last\_updated: 2026-02-12 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* color +* color-picker + parent\_category: inputs + +--- + +# Color handle + +Color handle component for color picker interfaces. May overlap with [Color handle and loupe](color-handle-and-loupe.md). Content should be scraped from the live site when VPN/browser access is available. + +**Source:** diff --git a/docs/s2-docs/components/inputs/color-slider.md b/docs/s2-docs/components/inputs/color-slider.md new file mode 100644 index 00000000..34619720 --- /dev/null +++ b/docs/s2-docs/components/inputs/color-slider.md @@ -0,0 +1,127 @@ +--- + +title: "Color slider" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* design-tokens +* color + related\_components: +* color-handle +* color-wheel + parent\_category: inputs + +--- + +# Color slider + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Color | [slider](https://opensource.adobe.com/spectrum-css/?path=/docs/components-color-slider--docs) | +| Spectrum Web Components SWC: Color | [Slider](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/color-slider--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [ColorSlider](http://react-spectrum.adobe.com/s2/index.html?path=/docs/colorslider--docs) | + +## Anatomy + +``` +color slider +- track +- handle +- loupe +- label +- value +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------- | +| background | string | – | This will vary depending on implementation. | +| channel | hue / saturation / lightness / red / green / blue / alpha hue | Which | channel of the color this slider controls. Use 'alpha' for opacity. | +| value | number – Number (from minValue to | maxValue). | | +| minValue | number | 0 | | +| maxValue | number | 100 | | +| step | number | 1 | | +| orientation | horizontal / vertical horizontal | – | | +| length | number 192 units: | px | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Color sliders adjust a single channel of a color. They’re often used in combination with other color controls to provide fine-tuned visual selection. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A color slider in a disabled state shows that an input exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a slider may become available later. + +The slider’s length can be customized based on its context, while its thickness stays fixed for consistency and usability. + +Color sliders can be either in horizontal or vertical orientation. By default, a color slider is horizontal and should be used when vertical space is more limited. The vertical orientation is used when horizontal space is more limited. + +The step refers to the increment by which these values increase or decrease. A step value of 1 (default) allows a user to only select whole numbers within the min and max range. + +The min and max values also can be customized appropriately for what the color slider is being used for (such as 0 to 360 for hue). By default, the min value starts at 0 and max value is set to 100. + +The value is the number selected within the color slider’s range, from the min value to max value. + +Controls a single color channel — such as hue, lightness, or alpha—at a time. The track’s gradient visualizes the full range of values for that channel. + +The background of the color slider is a visual representation of the range of values a user can select from. This can represent color properties such as hues, color channel values (such as RGB or CMYK levels), or opacity. The exact format this background property takes will depend on what implementation you are working with. Some examples of the format include image, canvas, and gradient. + +The keyboard focus state enlarges the handle to become twice as large. The loupe is a visual-only element and should not receive focus since it does not provide interactive functionality. + +Unlike the slider itself, the color slider’s handle can slide all the way to the edge of the track. It always displays the selected color inside the handle and never gets cut off by the track or any container. + +A color slider’s minimum length is 80 px on desktop, 100 px on mobile. + +Color sliders should be labeled and, when applicable, paired with text fields. If labeling each individual slider is redundant, label the group of sliders instead (for example, “RGB” or “HSB”). + +When using color sliders, it’s important to clearly display the color selection in real time. It can be in a color swatch, directly on the canvas, or both. + +The color loupe component can be used above the handle to show the selected color that would otherwise be covered by a cursor, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type. + +## States + +A color slider’s minimum length is 80 px on desktop, 100 px on mobile. + +## Behaviors + +A color slider’s minimum length is 80 px on desktop, 100 px on mobile. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Color handle and loupe](/page/color-handle/) +* [Color wheel](/page/color-wheel/) diff --git a/docs/s2-docs/components/inputs/color-wheel.md b/docs/s2-docs/components/inputs/color-wheel.md new file mode 100644 index 00000000..b8d08130 --- /dev/null +++ b/docs/s2-docs/components/inputs/color-wheel.md @@ -0,0 +1,121 @@ +--- + +title: "Color wheel" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* design-tokens +* color + related\_components: +* color-slider +* combo-box + parent\_category: inputs + +--- + +# Color wheel + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Color | [wheel](https://opensource.adobe.com/spectrum-css/?path=/docs/components-color-wheel--docs) | +| Spectrum Web Components SWC: Color | [Wheel](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/color-wheel--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [ColorWheel](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorwheel--docs) | + +## Anatomy + +``` +color wheel +- track +- handle +- loupe +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ----------------------------------------------- | ------------- | ------------------------------------------- | +| background | string | – | This will vary depending on implementation. | +| value | number – Number (from minValue to | maxValue) | | +| minValue | number | 0 | | +| maxValue | number | 360 | | +| step | number | 1 | | +| size | number 192 units: | px | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Color wheels adjust a single color channel using a circular track. They offer a visual, radial interface often paired with other color selection tools for more precise control. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A color wheel in a disabled state shows that an input exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that the wheel may become available later. + +A color wheel’s size can be customized appropriately for its context. + +The step refers to the increment by which these values increase or decrease. A step value of 1 (default) allows a user to only select whole numbers within the min and max range. + +The min and max values can also be customized appropriately for what the color wheel is being used for. By default, the min value starts at 0 and max value is set to 360. + +The value is the number selected within the color wheel’s range, from the minimum value to the maximum value. + +The background of the color wheel is a visual representation of the range of values that a user can select from. It can represent color properties such as hues or color channel values (such as RGB or CMYK levels). The exact format this background property takes will depend on what implementation you are working with. Some examples of the format include image, canvas, and gradient. + +A color wheel can be navigated using a keyboard. The keyboard focus state enlarges the handle to become twice as large. + +Minimum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +The color wheel is often used together with the color area component for color selection. When placing the color area inside the color wheel, make sure to leave enough of a margin between the two components to ensure there’s enough space for the both the handles. + +When using color areas, it’s important to clearly display the color selection in real time. It can be in a color swatch, directly on the canvas, or both. + +The color loupe component can be used above the handle to show the selected color that would otherwise be covered by a cursor, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type. + +## States + +A color wheel can be navigated using a keyboard. The keyboard focus state enlarges the handle to become twice as large. + +Minimum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +## Behaviors + +A color wheel can be navigated using a keyboard. The keyboard focus state enlarges the handle to become twice as large. + +Minimum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Color slider](/page/color-slider/) +* [Combo box](/page/combo-box/) diff --git a/docs/s2-docs/components/inputs/combo-box.md b/docs/s2-docs/components/inputs/combo-box.md new file mode 100644 index 00000000..485a26ce --- /dev/null +++ b/docs/s2-docs/components/inputs/combo-box.md @@ -0,0 +1,210 @@ +--- + +title: "Combo box" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* color-wheel +* date-picker + parent\_category: inputs + +--- + +# Combo box + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Combobox](https://opensource.adobe.com/spectrum-css/?path=/docs/components-combobox--docs) | +| Spectrum Web Components SWC: | [Combobox](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/combobox--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [ComboBox](https://react-spectrum.adobe.com/s2/index.html?path=/docs/combobox--docs) | + +## Anatomy + +``` +combo box +- label +- necessity indicator +- field +- help text (help text or error message) +- menu container +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------- | ------------- | ----------- | +| label | string | – | | +| labelPosition | top / side / in line top | – | | +| value | string | – | | +| width | number | – | | +| size | s / m / l / xl m | – | | +| isRequired | boolean | false | | +| necessityIndicator | text / icon icon | – | | +| hasAutocomplete | boolean | false | | +| menuTrigger | input / focus / manual input | – | | +| isError | boolean | false | | +| isDisabled | boolean | false | | +| isReadOnly | boolean | false | | +| description | string | – | | +| errorMessage | string | – | | +| state | default / hover (text area) / hover (button area) / focus + hover / focus + not hover / keyboard focus default | – | | + +## External links + +Combo boxes combine a text field with a picker menu. They support filtering longer lists by narrowing options based on typed input. Use when both freeform entry and guided selection are needed. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A combo box can be marked as having an error to show that a value needs to be entered or that a value is invalid, prompting the user to correct their input before moving forward. + +A combo box can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field. + +Combo boxes have a read-only option for when content in the disabled state still needs to be shown. This allows for content to be copied, but not interacted with or changed. A combo box does not have a read-only option if no selection has been made. + +A combo box in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later. + +A combo box can be marked as having an error to show that a value needs to be entered in order to move forward, or that a value that was entered is invalid. + +"There are 3 options for how a combo box’s menu can be triggered: when a user starts typing (“input”), when focus is placed on the input field (“focus”), and manually when the user clicks or taps the field button (“manual”). These are used for different degrees of the information complexity and/or user familiarity of menu options." + +By default, the menu is triggered when a user starts typing. This should be used when the content is readily familiar or commonplace enough to a user that they can begin populating values without seeing a list of all available options. + +If the content of the combo box is unfamiliar or complex, the menu should be triggered when focus is placed on the input field because a user would benefit from seeing example content before selecting a value. + +If the content of the combo box is highly familiar and autocomplete is sufficient to surface options, the menu can be set to trigger manually. + +Combo boxes can automatically complete suggested results within the input field. + +"Combo boxes can be marked as optional or required, depending on the situation. For required combo boxes, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional combo boxes are either denoted with text added to the end of the label — “(optional)” — or have no indication at all." + +"Combo boxes come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +The value shows a user’s entered text or the option they’ve selected. + +Combo boxes should always have an accessible name, typically provided by a visible text label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the visible label may be hidden. When no visible label is present, the input must still expose an accessible name (for example, in HTML via “aria-label” or “aria-labelledby,” and on other platforms via the platform’s accessible-name mechanism). + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +When the field label and menu text are too long for the available horizontal space, they wrap to form another line. The field text itself truncates at the end, but the text can be shown in full in the menu. + +When the help text is too long for the available horizontal space, it wraps to form another line. + +The combo box menu can be as tall as necessary to show as many options as possible in the available space. There is no maximum height. + +The text input functionality of the combo box is meant to make large lists easier to search. If you have fewer than 6 items, use radio buttons. If you have more than 6 items, consider whether your list of selections is complex enough to merit searching and filtering. If it's not complex enough for a combo box, you can use a picker. + +It’s okay to suppress the popover when the combo box contains entries the user is familiar with, and when autocomplete is enabled. A suppressed popover can still be opened when the field button containing the chevron is clicked. + +Launch the popover immediately if your user is highly unfamiliar with the content in the combo box, or if the data is especially complex. + +Launch the popover on text change if your user can get started typing without seeing a long list of options. + +When a suggestion is appended to the end of typed text, it remains the selected value when focus leaves the field. This guards against the scenario when a user sees a word completed in a field, continues to another form component, and the failure to commit changes erases the suggestion. + +When autocomplete is disabled, best matches get a hover style in the popover, but don’t get saved as a value unless they’re clicked on or "Enter" is pressed. + +Every combo box should have a label. A combo box without a label is ambiguous and not accessible. In rare cases where a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. + +Keep menu items short and concise. Long menu items that cause text to wrap to multiple lines are discouraged. If text wrapping becomes a frequent concern, consider revising the text or use alternative UI patterns that will give your content more space. + +Choose a width for your combo boxes that is likely to accommodate the majority of selections available within it. When a combo box is in focus and the typed input exceeds the width of the field, push the leftmost text out of sight while allowing text to continue to be entered towards the chevron. When a combo box is deselected, truncate the selected entry with ellipsis before it collides with the chevron button. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling combo boxes in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional combo box." + +The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text. + +Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. + +Instead of placeholder text, use the help text description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, especially if they're communicating the same thing. + +The help text area also displays an error message. When a combo box already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the field. + +Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Error text tells a user how to fix the error by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other like minimum requirements. + +Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user. + +"Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For combo boxes, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a combo box that asks for them to choose a topic, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Choose at least one topic.”" + +## States + +When the help text is too long for the available horizontal space, it wraps to form another line. + +The combo box menu can be as tall as necessary to show as many options as possible in the available space. There is no maximum height. + +Launch the popover immediately if your user is highly unfamiliar with the content in the combo box, or if the data is especially complex. + +Launch the popover on text change if your user can get started typing without seeing a long list of options. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling combo boxes in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional combo box." + +## Behaviors + +When the help text is too long for the available horizontal space, it wraps to form another line. + +The combo box menu can be as tall as necessary to show as many options as possible in the available space. There is no maximum height. + +Launch the popover immediately if your user is highly unfamiliar with the content in the combo box, or if the data is especially complex. + +Launch the popover on text change if your user can get started typing without seeing a long list of options. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling combo boxes in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional combo box." + +## Usage guidelines + +Launch the popover immediately if your user is highly unfamiliar with the content in the combo box, or if the data is especially complex. + +Launch the popover on text change if your user can get started typing without seeing a long list of options. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling combo boxes in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional combo box." + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Color wheel](/page/color-wheel/) +* [Date picker](/page/date-picker/) diff --git a/docs/s2-docs/components/inputs/date-picker.md b/docs/s2-docs/components/inputs/date-picker.md new file mode 100644 index 00000000..86fddab7 --- /dev/null +++ b/docs/s2-docs/components/inputs/date-picker.md @@ -0,0 +1,150 @@ +--- + +title: "Date picker" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* combo-box +* drop-zone + parent\_category: inputs + +--- + +# Date picker + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------- | -------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Date | [picker](https://opensource.adobe.com/spectrum-css/?path=/docs/components-date-picker--docs) | +| Spectrum Web Components Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/datepicker--docs) | +| React Spectrum RSP: | [DatePicker](https://react-spectrum.adobe.com/s2/index.html?path=/docs/datepicker--docs) | + +## Anatomy + +``` +date picker +- date field (with in-field button) +- calendar +- time field (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| --------------- | ---------------------------------------------------------------------- | ------------- | --------------------------------------------------------------- | +| variant | single / double / triple single | Controls | the number of months displayed in the calendar popover. | +| selectedDate | string | – | The currently selected date. Used when selectionMode is single. | +| selectedRange | object – The currently selected date range, used when selectionMode is | range. | | +| dateField | object – Configuration for the date input | field. | | +| calendarPopover | object – Configuration for the calendar | popover. | | + +## External links + +Date pickers allow selection of a single date or a date range. They include a calendar within a popover, with optional manual entry. Date range variants support selecting a start and end date in one field. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Calendar popover displays a grid of days spanning one, two, or three months, enabling users to select a single date or a range. + +Date field allows users to enter and edit date values. Users can edit each part of a date value, such as the day, month, and year, by interacting with individual segments. A date field includes a label, segments for each value of the date, and an in-field button to allow the user to open the calendar popover. + +The range of days the user has selected (a start date and an end date). + +The selected date allows a user to see which date they have selected within the calendar popover. + +A single date picker only displays a single date within the date field as well as a single month within the calendar popover. + +A double date picker displays a date range within the date field as well as two consecutive months within the calendar popover. + +A triple date picker displays a date range within the date field as well as three consecutive months within the calendar popover. + +The calendar popover is displayed or hidden when the user selects the in-field button (the calendar icon). + +"If a user selects a day preceding the first selection, that earlier day becomes the start of the range. For example:" + +"A third selection resets the range. For example:" + +Date pickers display placeholder values in individual segments by default. This is to makes it easier for users to focus and edit specific values like the day, month, or year without re-entering the entire date. + +This approach reduces input errors, improves accessibility, and supports faster, more precise interactions. It also adapts well to different regional formats, enhancing clarity across locales. + +Date pickers can be used to select a single date or a date range (a start date and an end date). + +When a date picker is formatted to allow a range, it displays a placeholder by default. When the user first interacts with the date field, the first value of the placeholder is in focus. This is to allow the user to edit the individual segments. When the user opens the popover without interacting, it displays the current day along with the month and year based on their locale. However, the date field will continue to show the placeholder until the user either completes the range in the field or within the calendar popover. + +If the user inputs a date range within the date field that spans more than the maximum of three months that the calendar popover allows, the calendar popover will only show the first three consecutive months within that range. + +The date field can also capture time values with precision down to the second, and may include time zone information. The calendar popover can also include time-specific fields, allowing users to specify start and end times. + +"Date pickers can be marked as optional or required, depending on the situation. For required date pickers, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include help text to explain what the asterisk means. Optional date pickers are either denoted with text added to the end of the label — “(optional)” — or have no indication at all." + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +A read-only state of date picker means that the user cannot interact with the field, and they can only read what the field is displaying. Therefore, the in-field button is not clickable. In the disabled state, the read-only state of date picker allows the user to focus on a value—even though they cannot change the value. + +A disabled date picker means that the user cannot interact with the field, but not for the same reasons as a read-only scenario. For example, a date picker may be temporarily disabled because the user needs to complete a dependent task (such as filling out another field) somewhere within their experience. A disabled date picker does not allow for the ability to focus on a value, or to change its value. + +A date picker can be marked as having an error to show that a value needs to be entered in order to move forward, or that an entered value is invalid. In this scenario, displaying error text beneath the date field can aid the user in understanding how to resolve it. Error text within the calendar popover may also be helpful to aid the user in understanding what the error is signaling. + +## States + +The calendar popover is displayed or hidden when the user selects the in-field button (the calendar icon). + +"If a user selects a day preceding the first selection, that earlier day becomes the start of the range. For example:" + +"A third selection resets the range. For example:" + +Date pickers can be used to select a single date or a date range (a start date and an end date). + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +## Behaviors + +The calendar popover is displayed or hidden when the user selects the in-field button (the calendar icon). + +"If a user selects a day preceding the first selection, that earlier day becomes the start of the range. For example:" + +"A third selection resets the range. For example:" + +Date pickers can be used to select a single date or a date range (a start date and an end date). + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +## Usage guidelines + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Combo box](/page/combo-box/) +* [Drop zone](/page/drop-zone/) diff --git a/docs/s2-docs/components/inputs/drop-zone.md b/docs/s2-docs/components/inputs/drop-zone.md new file mode 100644 index 00000000..66505ac2 --- /dev/null +++ b/docs/s2-docs/components/inputs/drop-zone.md @@ -0,0 +1,98 @@ +--- + +title: "Drop zone" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* date-picker +* field-label + parent\_category: inputs + +--- + +# Drop zone + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Drop | [zone](https://opensource.adobe.com/spectrum-css/?path=/docs/components-drop-zone--docs) | +| Spectrum Web Components SWC: | [Dropzone](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/dropzone--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [DropZone](https://react-spectrum.adobe.com/s2/index.html?path=/docs/dropzone--docs) | + +## Anatomy + +``` +drop zone +- illustration +- title +- body +- button (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ----------- | ------------- | --------------------------------------------------------------------- | +| accept | array | – | | +| size | s / m / l m | – | | +| actionLabel | string | – | If undefined, this button does not appear. | +| onDrop | string | – | Callback function called when files are dropped onto the drop zone. | +| onDragOver | string | – | Callback function called when a file is dragged over the drop zone. | +| onDragLeave | string | – | Callback function called when a file is dragged out of the drop zone. | + +## External links + +Drop zones accept dragged and dropped objects. They support upload and file management workflows, and are commonly used to move or add content within an interface. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A button is an optional element to prompt the user to take action. + +"Drop zones come in three different sizes: small, medium, and large. The medium size is the default and most frequently used option." + +Indicate to users the accepted file types to let users know what they can upload before interacting. This can be done through helper text or placeholder content. + +When a file is dragged over or dropped into the zone, provide the user with visual feedback such as highlighting the border or changing the background, to confirm the interaction is recognized. + +Visual styling that indicates a user can replace file types within a dropzone should clearly communicate interactivity and the potential for change without disrupting the overall layout. This is typically achieved through subtle but intuitive cues such as displaying a button over the drop zone area informing the user that they may replace their content type. + +## States + +## Behaviors + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Date picker](/page/date-picker/) +* [Field label](/page/field-label/) diff --git a/docs/s2-docs/components/inputs/field-label.md b/docs/s2-docs/components/inputs/field-label.md new file mode 100644 index 00000000..bdf0ef6e --- /dev/null +++ b/docs/s2-docs/components/inputs/field-label.md @@ -0,0 +1,116 @@ +--- + +title: "Field label" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* drop-zone +* help-text + parent\_category: inputs + +--- + +# Field label + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Field | [label](https://opensource.adobe.com/spectrum-css/?path=/docs/components-field-label--docs) | +| Spectrum Web Components SWC: Field | \[Label]\( | + +## Anatomy + +``` +field label +- label +- necessity indicator +- input(s) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ---------------- | ------------- | ----------- | +| label | string | – | | +| labelPosition | top / side top | – | | +| size | s / m / l / xl m | – | | +| necessityIndicator | text / icon icon | – | | +| isRequired | boolean | false | | +| isDisabled | boolean | false | | + +## External links + +Field labels provide context for associated input fields. They describe the expected content or data type. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A field label in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an input field may become available later. + +"Inputs can be marked as required or optional, depending on the situation, using a necessity indicator. There are two styles for the necessity indicator: icon or text." + +By default, the necessity indicator is shown with an asterisk icon. Required inputs are marked with this at the end of the label. If you use this icon, be sure to include hint text to explain what it means. The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. Optional inputs do not have an icon. + +Alternatively, the necessity indicator can be shown with text. This appends text that reads either “(required)” or “(optional)” at the end of the label. + +"Field labels come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option with medium-sized inputs. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page. Both small and medium field labels have the same font size, but different paddings when used as side labels." + +A label can be placed either on top or on the side of an input. This option affects the bounding box of the component to ensure proper alignment. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +When the field label is too long for the available horizontal space, it wraps to form another line. + +In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. + +If most of the input fields are optional, only the required fields should be given an asterisk icon or have labels appended with “(required).” If most of the input fields are required, only the optional fields should be appended with “(optional).” An asterisk icon should never be used to note that a field is optional. + +## States + +When the field label is too long for the available horizontal space, it wraps to form another line. + +In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. + +## Behaviors + +When the field label is too long for the available horizontal space, it wraps to form another line. + +In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. + +## Usage guidelines + +In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Drop zone](/page/drop-zone/) +* [Help text](/page/help-text/) diff --git a/docs/s2-docs/components/inputs/help-text.md b/docs/s2-docs/components/inputs/help-text.md new file mode 100644 index 00000000..23c3df21 --- /dev/null +++ b/docs/s2-docs/components/inputs/help-text.md @@ -0,0 +1,109 @@ +--- + +title: "Help text" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* field-label +* number-field + parent\_category: inputs + +--- + +# Help text + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Help | [text](https://opensource.adobe.com/spectrum-css/?path=/docs/components-help-text--docs) | +| Spectrum Web Components SWC: Help | \[Text]\( | + +## Anatomy + +``` +help text (placed under the input) +- icon (optional) and text (description or error message) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | -------------------------- | ------------- | ------------------------------------------------------- | +| text | string | – | | +| variant | neutral / negative neutral | – | | +| hideIcon | boolean | false | Only applicable if variant is negative. | +| size | s / m / l / xl m | – | | +| isDisabled | boolean | false | Help text cannot be both disabled and negative variant. | + +## External links + +Help text provides additional context for an input field, such as descriptions, instructions, or error messages. It’s commonly used in forms to clarify what’s expected or to explain validation. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Help text using the neutral variant can be displayed in a disabled state. The text appears with a lighter gray that matches the style of other components in a disabled state. Help text using the negative variant cannot be displayed in a disabled state because it communicates an error, and error messages should not be visible when the component is disabled. + +"Help text comes in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly and pair them with components of the same size to respect the built-in hierarchy." + +"Help text has two variants: neutral and negative. The neutral variant is used to convey informative messages, while the negative variant is used to convey error messages." + +"The text can accommodate either a description or an error message, giving extra context and guidance. Sometimes this communicates what to input or select, and sometimes it communicates how. It includes information such as:" + +Regardless of the kind of message, it should be clear and concise. Use 1-2 short, complete sentences that end with a period (never an exclamation point). When showing formatting examples, it's not necessary to end with a period. + +When the text is too long for the available horizontal space, it wraps to form another line. + +For the optional icon that can be displayed with the negative variant, usage depends on what kind of component the help text is accompanying. Whether to include the optional icon with the negative variant depends on the component that the help text accompanies. + +Help text displays either a description (the neutral variant) or an error message (the negative variant) in the same space. When a description is present and an error is triggered, it is replaced with an error message. Once the error is resolved, the help text description reappears. + +Since one gets replaced by Because one replaces the other, the language of the help text description and the error need to work together to communicate convey the same message messaging. The description text explains the requirements or adds supplementary context for how to successfully interact with a component. The error message text restates the same requirements, guiding the user to fix the issue. tells a user how to fix the error by re-stating the interaction requirements. Make sure that the help text description and error message include the same essential information so that it isn’t lost if one replaces the other. + +Communicate error messages in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user. + +"For help text, usually the error is related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their email address, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter your email address.”" + +## States + +When the text is too long for the available horizontal space, it wraps to form another line. + +## Behaviors + +When the text is too long for the available horizontal space, it wraps to form another line. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Field label](/page/field-label/) +* [Number field](/page/number-field/) diff --git a/docs/s2-docs/components/inputs/number-field.md b/docs/s2-docs/components/inputs/number-field.md new file mode 100644 index 00000000..9e029359 --- /dev/null +++ b/docs/s2-docs/components/inputs/number-field.md @@ -0,0 +1,195 @@ +--- + +title: "Number field" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* help-text +* picker + parent\_category: inputs + +--- + +# Number field + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) Not | \[available]\( | +| Spectrum Web Components SWC: Number | \[Field]\( | +| React Spectrum RSP: | [NumberField](https://react-spectrum.adobe.com/s2/index.html?path=/docs/numberfield--docs) | + +## Anatomy + +``` +number field +- label +- required asterisk, required text, or optional text +- field +- value +- validation marker or error icon +- stepper +- help text (help text or error message) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ----------------------------------------------------------- | ------------- | ------------------------------------------------------------------ | +| label | string | – | | +| size | s / m / l / xl m | – | | +| labelPosition | top / side top | – | | +| hideLabel | boolean | false | | +| state | default / hover / focus + hover / focus + not hover default | – | | +| isDisabled | boolean | false | | +| isError | boolean | false | | +| isRequired | boolean | false | | +| necessityIndicator | text / icon icon | – | | +| hideStepper | boolean | false | If true, hides in-field increment and decrement buttons (stepper). | + +## External links + +Number fields accept numeric inputs and allow values to be incremented or decremented. They are commonly used when a defined range or step value is required. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Number fields can have optional stepper buttons to the side of the field. Regardless of if a number field has these buttons or not, is should always accommodate arrow key shortcuts to increase or decrease the number. + +If true, hides in-field increment and decrement buttons (stepper). + +"Number fields can be marked as optional or required, depending on the situation. For required number fields, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional number fields are either denoted with text added to the end of the label — “(optional)” — or have no indication at all." + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +A number field can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. For this component, an incorrect value should typically revert back to either the previously entered number or to the default value, rather than showing an error. + +A number field in a disabled state shows that an input exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that the field may become available later. + +Number fields should always have an accessible name, typically provided by a visible text label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the visible label may be hidden or omitted. When no visible label is present, the input must still expose an accessible name (for example, in HTML via “aria-label” or “aria-labelledby,” and on other platforms via the platform’s accessible-name mechanism). + +Number fields can show or hide the visible label. + +Labels can be placed either on top or on the side,. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +"Number fields come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +The value shows a user’s entered text or a default value, plus the units of measurement, if applicable. + +A number field can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. The error message communicates an error for when the field requirements aren’t met, prompting a user to adjust what they had originally input. If an error exists, the error icon always overrides the validation icon. + +When an error message is displayed, it replaces the help text. If an error exists, the error icon always overrides the validation icon. + +A number field can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field. + +Help text is replaced by error messages when validation fails. + +When the field label is too long for the available horizontal space, it wraps to form another line. The text inside the field truncates. + +When a number field presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Number fields should always allow users to add, subtract, multiply, and divide, with the field automatically calculating the result. + +Number fields can include units of measurement in the value. When focused or entering text, the units disappear. When scrolling, the units stay. If a user enters a unit that does not match the unit that the field requires, the field should automatically calculate a conversion and display the input value in the correct unit. + +Choose a default value for a field to revert back to if an invalid entry is input. If a user enters a valid number and then enters an invalid number, revert to the most recent valid entry. + +Most number fields should have a label. A field without a label is ambiguous and not accessible. In rare cases where context is sufficient and a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. These should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”). + +Labels for number fields should be in sentence case. + +"When labeling number fields in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional number field." + +Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible, and should be avoided. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. + +Instead of placeholder text, choose a default value to include in the field in default state. Use the help text description to convey requirements or to show any formatting examples that would help user comprehension. + +The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text. + +The help text area also displays an error message. When a number field already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the field. + +Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Error text tells a user how to fix the error by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other like formatting requirements. + +Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user. + +Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. Never end with an exclamation point. For number fields, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. + +## States + +When the field label is too long for the available horizontal space, it wraps to form another line. The text inside the field truncates. + +When a number field presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Number fields should always allow users to add, subtract, multiply, and divide, with the field automatically calculating the result. + +Labels for number fields should be in sentence case. + +"When labeling number fields in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional number field." + +## Behaviors + +When the field label is too long for the available horizontal space, it wraps to form another line. The text inside the field truncates. + +When a number field presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Number fields should always allow users to add, subtract, multiply, and divide, with the field automatically calculating the result. + +Labels for number fields should be in sentence case. + +"When labeling number fields in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional number field." + +## Usage guidelines + +Labels for number fields should be in sentence case. + +"When labeling number fields in a form, only mark the minority type—either required or optional—to reduce visual clutter:" + +"Important: Never use an asterisk to indicate an optional number field." + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Help text](/page/help-text/) +* [Picker](/page/picker/) diff --git a/docs/s2-docs/components/inputs/picker.md b/docs/s2-docs/components/inputs/picker.md new file mode 100644 index 00000000..c71940f7 --- /dev/null +++ b/docs/s2-docs/components/inputs/picker.md @@ -0,0 +1,223 @@ +--- + +title: "Picker" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* number-field +* radio-button + parent\_category: inputs + +--- + +# Picker + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Picker](https://opensource.adobe.com/spectrum-css/?path=/docs/components-picker--docs) | +| Spectrum Web Components SWC: | \[Picker]\( | +| React Spectrum RSP: | [Picker](https://react-spectrum.adobe.com/s2/index.html?path=/docs/picker--docs) | + +## Anatomy + +``` +picker +- label +- required asterisk, required text, or optional text +- field +- placeholder or value +- error icon +- chevron +- help text (help text or error message) +- menuContainer +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ---------------------------------------------------------------------------- | ------------- | ----------- | +| label | string | – | | +| labelPosition | top / side top | – | | +| placeholder | string | – | | +| value | string | – | | +| width | number – Not applicable to quiet | picker. | | +| size | s / m / l / xl m | – | | +| isQuiet | boolean | false | | +| necessityIndicator | text / icon icon | – | | +| isRequired | boolean | false | | +| menuContainer | popover / tray popover | – | | +| isDisabled | boolean | false | | +| isError | boolean | false | | +| description | string | null | | +| errorMessage | string | null | | +| state | default / hover / focus + hover / focus + not hover / keyboard focus default | – | | + +## External links + +Pickers present a list of options in a compact format for selection. They’re sometimes called “dropdowns” or “selects,” and the available options may change based on context. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +The error message communicates an error for when the selection requirements aren’t met, prompting a user to adjust what they had originally selected. + +A picker can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field. + +A picker can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. + +A picker in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later. + +The picker menu is a menu element that is used to display the options for the picker. A picker menu can include menu items, menu dividers, and menu groups. A picker menu should never contain submenus, as doing so would render it inaccessible. + +"For required pickers, you have two options:" + +"For optional pickers, you have two options:" + +By default, pickers have a visible background. This style works best in a dense array of controls where the background helps to separate the input from the surrounding container, or to give visibility to isolated buttons. + +Alternatively, quiet pickers can have no visible background. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read. + +"Pickers come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +The width of a picker can be customized appropriately for its context. This option is not applicable to quiet pickers. + +The value shows the option that a user has selected. + +Placeholder text provides hints about expected input values. It disappears once a user selects an option. + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +Pickers should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These pickers without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”). + +When the field label and menu text are too long for the available horizontal space, they wrap to form another line. The field text itself truncates at the end, but the text can be shown in full in the menu. + +When the help or error text is too long for the available horizontal space, it wraps to form another line. + +The picker menu can be as tall as necessary to show as many options as possible in the available space. There is no maximum height. + +Every picker should have a label. A picker without a label is ambiguous and not accessible. + +In rare cases where context is sufficient and a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. These should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”). + +Keep menu items short and concise. Long menu items that cause text to wrap to multiple lines are discouraged. If text wrapping becomes a frequent concern, consider revising the text or use alternative UI patterns that will give your content more space. + +When possible, the field button width should be wide enough so that any chosen menu items can be displayed in full. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling pickers in a form, only mark the minority type — either required or optional — to reduce visual clutter:" + +Never use an asterisk to indicate an optional picker. + +"A picker’s description in the help text is can communicate what to select or how to select an option. This includes information such as:" + +The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with a picker. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text. + +The help text area also displays an error message. When a picker already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the picker. + +Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to complete the interaction. Error text tells a user how to fix the error by re-stating the selection requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other like minimum requirements. + +Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user. + +"Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For pickers, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss selecting an option to note as their preferred contact method, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to be selected: “Select a contact method.”" + +Placeholder text provides hints about expected input values. When implemented properly, it enhances usability without compromising accessibility. + +"Placeholder text:" + +## States + +When the help or error text is too long for the available horizontal space, it wraps to form another line. + +The picker menu can be as tall as necessary to show as many options as possible in the available space. There is no maximum height. + +Every picker should have a label. A picker without a label is ambiguous and not accessible. + +When possible, the field button width should be wide enough so that any chosen menu items can be displayed in full. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling pickers in a form, only mark the minority type — either required or optional — to reduce visual clutter:" + +Never use an asterisk to indicate an optional picker. + +"A picker’s description in the help text is can communicate what to select or how to select an option. This includes information such as:" + +Placeholder text provides hints about expected input values. When implemented properly, it enhances usability without compromising accessibility. + +"Placeholder text:" + +## Behaviors + +When the help or error text is too long for the available horizontal space, it wraps to form another line. + +The picker menu can be as tall as necessary to show as many options as possible in the available space. There is no maximum height. + +Every picker should have a label. A picker without a label is ambiguous and not accessible. + +When possible, the field button width should be wide enough so that any chosen menu items can be displayed in full. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling pickers in a form, only mark the minority type — either required or optional — to reduce visual clutter:" + +Never use an asterisk to indicate an optional picker. + +"A picker’s description in the help text is can communicate what to select or how to select an option. This includes information such as:" + +Placeholder text provides hints about expected input values. When implemented properly, it enhances usability without compromising accessibility. + +"Placeholder text:" + +## Usage guidelines + +Every picker should have a label. A picker without a label is ambiguous and not accessible. + +When possible, the field button width should be wide enough so that any chosen menu items can be displayed in full. + +Field labels, placeholder text, and menu items should be in sentence case. + +"When labeling pickers in a form, only mark the minority type — either required or optional — to reduce visual clutter:" + +Never use an asterisk to indicate an optional picker. + +"A picker’s description in the help text is can communicate what to select or how to select an option. This includes information such as:" + +Placeholder text provides hints about expected input values. When implemented properly, it enhances usability without compromising accessibility. + +"Placeholder text:" + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Number field](/page/number-field/) +* [Radio button](/page/radio-button/) diff --git a/docs/s2-docs/components/inputs/radio-button.md b/docs/s2-docs/components/inputs/radio-button.md new file mode 100644 index 00000000..4f07e50f --- /dev/null +++ b/docs/s2-docs/components/inputs/radio-button.md @@ -0,0 +1,111 @@ +--- + +title: "Radio button" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* action +* button +* interactive + related\_components: +* picker +* radio-group + parent\_category: inputs + +--- + +# Radio button + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Radio](https://opensource.adobe.com/spectrum-css/?path=/docs/components-radio--docs) | +| Spectrum Web Components SWC: | \[Radio]\( | +| React Spectrum RSP: | [RadioGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/radiogroup--docs) | + +## Anatomy + +``` +radio button +- control +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------ | ----------------------------------------------- | ------------- | ------------------------------------------ | +| state | default / hover / down / keyboard focus default | – | | +| isSelected | boolean | false | | +| isEmphasized | boolean | false | | +| label | string | – | The text displayed next to a radio button. | + +## External links + +Radio buttons present a list of options where only one can be selected at a time. They are styled consistently with other components that support binary selection. Use when all options should be visible and only one can apply. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Radio button should always have a label for accessibility and clear comprehension. When the label is not defined, a radio button becomes standalone. Standalone radio buttons should only be used when their connection to other components is clear and they give sufficient context — for example, in application panels. + +By default, radio buttons are not emphasized. This version is optimal for when the radio button is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content. + +The emphasized version provides a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a radio button needs to be noticed. + +Radio button can either be selected or not selected. They cannot be in an indeterminate state (unlike checkboxes). + +"Radio buttons come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +A radio button can be navigated using a keyboard. The keyboard focus state takes the radio button’s visual hover state and adds a blue ring to the radio button in focus. + +When the button text is too long for the horizontal space available, it wraps to form another line. + +Radio buttons are best when only one option can be selected at a time from a set (for example choosing one preference or mode). Switches are best for communicating activation (e.g., turning a setting on or off). Checkboxes are best for communicating selection (e.g., selecting multiple items from a list). + +Emphasized radio buttons are optimal for forms, settings, and other scenarios where the radio buttons need to be noticed. Default radio buttons are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas. + +Radio buttons can only be on or off. Indeterminate radio buttons don’t exist in accessibility APIs, so it’s not possible to make an indeterminate radio button accessible. If you need to show a partial state, use a checkbox instead of a radio button. When a parent radio button represents a group of radio buttons, it should be turned off unless all of the radio buttons are on (turning the parent radio button on turns all of the radio buttons on). + +## States + +When the button text is too long for the horizontal space available, it wraps to form another line. + +## Behaviors + +When the button text is too long for the horizontal space available, it wraps to form another line. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Picker](/page/picker/) +* [Radio group](/page/radio-group/) diff --git a/docs/s2-docs/components/inputs/radio-group.md b/docs/s2-docs/components/inputs/radio-group.md new file mode 100644 index 00000000..7fb78086 --- /dev/null +++ b/docs/s2-docs/components/inputs/radio-group.md @@ -0,0 +1,154 @@ +--- + +title: "Radio group" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* radio-button +* rating + parent\_category: inputs + +--- + +# Radio group + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Field | [group](https://opensource.adobe.com/spectrum-css/?path=/docs/components-field-group--docs) | +| Spectrum Web Components SWC: Radio | \[Group]\( | +| React Spectrum RSP: | [RadioGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/radiogroup--docs) | + +## Anatomy + +``` +radio group +- field label +- radio button area +- help text (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ------------------------------ | ------------- | ----------- | +| label | string | – | | +| labelPosition | top / side top | – | | +| orientation | horizontal / vertical vertical | – | | +| size | s / m / l / xl m | – | | +| isEmphasized | boolean | false | | +| necessityIndicator | text / icon icon | – | | +| isRequired | boolean | false | | +| isError | boolean | false | | +| isDisabled | boolean | false | | +| errorMessage | string | – | | +| description | string | – | | + +## External links + +Radio groups organize related radio buttons into a single selection set. Only one option can be selected at a time. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Radio groups should use help text for error messaging and descriptions. Descriptions are valuable for giving context behind why a selection is required, or for clarifying the options. + +Radio groups can be marked as having an error to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid. The error is indicated with negative help text, along with an icon. + +A radio group in a disabled state shows that a selection exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later. The field label, radio buttons, and help text are all displayed in a disabled state when the radio group is disabled. + +"Radio groups can be marked as optional or required, depending on the situation. For required radio groups, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include help text to explain what the asterisk means. Optional radio groups are either denoted with text added to the end of the label — “(optional)” — or have no indication at all." + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +By default, radio buttons are not emphasized (gray). This option is best for when the radio button is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content. + +The emphasized (blue) version provides a visual prominence that is best for forms, settings, lists or grids of assets, and other situations where a radio button needs to be noticed. + +"Radio groups come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +Radio groups can be either horizontal or vertical. By default, radio groups are vertical. Use a horizontal radio group when vertical space is limited. + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +Radio groups should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These radio groups without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”). + +A radio button can be navigated using a keyboard. The keyboard focus state takes the radio button’s visual hover state and adds a blue ring to the radio button in focus. + +When the label is too long for the horizontal space available, it wraps to form another line. + +When a radio button group presents multiple values that are not identical, the group should not show a selection. Any subsequent selection should update all values. + +Emphasized radio group is optimal for forms, settings, and other scenarios where the radio group need to be noticed. Default radio group is optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas. + +Radio buttons and checkboxes are not interchangeable. Radio buttons are best used for selecting a single option from a list of mutually exclusive options. Checkboxes are best used for selecting multiple options at once (or no options). + +Radio groups should always have a label that clearly describes what the list of options represents. This is important for accessibility, since a screen reader will read the label before each option. Make sure to include a label, and don't assume that the options are self-explanatory without one. Write the label in sentence case. + +Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode). + +Switches are best for communicating activation (e.g., turning a setting on or off). + +Checkboxes are best for communicating selection (e.g., selecting multiple items from a list). + +## States + +When the label is too long for the horizontal space available, it wraps to form another line. + +Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode). + +Switches are best for communicating activation (e.g., turning a setting on or off). + +Checkboxes are best for communicating selection (e.g., selecting multiple items from a list). + +## Behaviors + +When the label is too long for the horizontal space available, it wraps to form another line. + +Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode). + +Switches are best for communicating activation (e.g., turning a setting on or off). + +Checkboxes are best for communicating selection (e.g., selecting multiple items from a list). + +## Usage guidelines + +Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode). + +Switches are best for communicating activation (e.g., turning a setting on or off). + +Checkboxes are best for communicating selection (e.g., selecting multiple items from a list). + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Radio button](/page/radio-button/) +* [Rating](/page/rating/) diff --git a/docs/s2-docs/components/inputs/rating.md b/docs/s2-docs/components/inputs/rating.md new file mode 100644 index 00000000..77d73b6e --- /dev/null +++ b/docs/s2-docs/components/inputs/rating.md @@ -0,0 +1,107 @@ +--- + +title: "Rating" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* radio-group +* search-field + parent\_category: inputs + +--- + +# Rating + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Rating](https://opensource.adobe.com/spectrum-css/?path=/docs/components-rating--docs) | + +## Anatomy + +``` +rating +- Star workflow icon +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------ | -------------------------------------------------------- | ------------- | ----------- | +| value | number 0 From 0 to 5, can be a decimal to represent half | stars | | +| isEmphasized | boolean | false | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Ratings allow scoring of an item or experience based on quality or preference. Common examples include images, forum posts, or products. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A rating in a disabled state shows that the component exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later. + +By default, ratings are not emphasized (dark gray). This version is optimal for when the rating is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content. + +The emphasized (blue) version provides a visual prominence that is optimal for forms, dialogs, and other situations where a rating needs to be noticed. + +The value is the number of the rating selected, on a sentiment scale from 0 to 5 (0 being the lowest, 5 being the highest). + +"The rating component supports two main use cases: inputting and aggregating. Inputting allows users to select a rating, while aggregating displays the average rating, which may include fractional stars. Interactive ratings show only whole stars to avoid confusion during selection." + +When a user interacts with a rating component that shows a previously entered value, a tooltip appears when they hover over a star. The language in the tooltip is phrased as a call-to-action to edit their rating. For example, “Edit 4 star rating”. + +A user’s previously entered rating can be cleared if they select the “highest” star (for example, clicking or tapping the fourth star from the left on a four-star rating). On keyboard focus, the left/down arrow keys will decrease the rating until the last star is removed. A tooltip appears on hover with alt text that describes the action, for example “Clear 4 star rating”. + +Rating can display approximate value or precise value depending on the needs of the product or service. For example, Amazon.com uses approximate rating, but Apple's App Store uses precise rating. + +When representing multiple values (e.g., rating 2 photos at the same time), the rating is shown as empty if the ratings are not the same. This behavior is consistent with how a radio button group works, as well. + +Star ratings should always have 5 available stars. This shouldn’t be increased or decreased to fit various containers. + +## States + +Star ratings should always have 5 available stars. This shouldn’t be increased or decreased to fit various containers. + +## Behaviors + +Star ratings should always have 5 available stars. This shouldn’t be increased or decreased to fit various containers. + +## Usage guidelines + +Star ratings should always have 5 available stars. This shouldn’t be increased or decreased to fit various containers. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Radio group](/page/radio-group/) +* [Search field](/page/search-field/) diff --git a/docs/s2-docs/components/inputs/search-field.md b/docs/s2-docs/components/inputs/search-field.md new file mode 100644 index 00000000..2ba5f37e --- /dev/null +++ b/docs/s2-docs/components/inputs/search-field.md @@ -0,0 +1,161 @@ +--- + +title: "Search field" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* rating +* segmented-control + parent\_category: inputs + +--- + +# Search field + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Search](https://opensource.adobe.com/spectrum-css/?path=/docs/components-search--docs) | +| Spectrum Web Components SWC: | \[Search]\( | +| React Spectrum RSP: | [SearchField](https://react-spectrum.adobe.com/s2/index.html?path=/docs/searchfield--docs) | + +## Anatomy + +``` +search field +- field +- leading icon (search or custom) +- label / search term +- in-field button +- help text (help text) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ----------------------------------------------------------------------------------- | ------------- | ----------- | +| label | string | – | | +| hideLabel | boolean | false | | +| icon | – – Icon must be present if the label is not | defined. | | +| value | string | – | | +| width | number | – | | +| size | s / m / l / xl m | – | | +| helpText | string | – | | +| placeholder | string | – | | +| isDisabled | boolean | false | | +| state | default / down / hover / focus + hover / focus + not hover / keyboard focus default | – | | + +## External links + +Search fields enable finding or filtering items based on text input. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A search field should include a label and a search icon. In the default state before a search term is input, the label is in regular body text style to meet contrast ratios and to show that this is a field label, not placeholder text. When no visible label is present, the input must still expose an accessible name (for example, in HTML via “aria-label” or “aria-labelledby,” and on other platforms via the platform’s accessible-name mechanism). + +The value shows a user’s entered text in regular body text style. + +The width of a search field can be customized appropriately for its context. + +"Search fields come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +A search field can have help text below the field to give extra context or instruction about what a user should input. The description communicates a hint or helpful information, such as a search’s scope. + +Placeholder text provides hints about expected input values. + +A search field in a disabled state shows that a search option exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later. + +The minimum width for a search field is 3× the height of the field, for both standard and quiet style. This minimum width guarantees that small search fields are readable and easy to target on touch devices. + +When the entered text is too long for the available horizontal space in the field, the text truncates. + +When the help text is too long for the available horizontal space, it wraps to form another line. + +A search field can be navigated using a keyboard. The keyboard focus state takes the field’s visual hover state and adds a blue ring to the field in focus. + +The in-field button offers an option to clear any input search term. + +If search results are being shown in a menu or popover, selecting this button will close the menu and clear the field. If a search term has been entered and the results have appeared, selecting this will only clear the field and not affect the list of results. + +Search fields do not have an error state. Search functionality should anticipate spelling mistakes in search queries, and accommodate multiple spellings of words in search results — not treating any search term as an error. + +Instead of showing an error, show a “No results” page or a section with any suggestions for how to get results to appear. + +In a searching scenario, a user inputs a search term for a specific thing they’re looking for. In a filtering scenario, a user generally knows what they’re looking for, but may not have a specific thing in mind. + +The search field can be used for both of these contexts. For a search experience, use the search field as-is. For a filtering experience, add a filter icon next to the search field, where a user can narrow down their search results before (or instead of) searching using a specific term. Filters can appear below the search field as tags. + +Spectrum previously had a specific “search within” component that would allow a user to filter down a search field category before searching for a particular term. It was deprecated because it did not meet accessibility and localization requirements. + +Any search field should include a label inside the field, in the default state. The default label text is Search, but this can be customized to be more specific for use cases like scoped search, wayfinding, or building context — acting like a prompt for a user to search more specifically. + +Keep in mind that once a search term is entered the label text is no longer viewable. Use help text to show search formatting examples or give hints about what to input. It can be distracting or redundant if the search field label and its help text are both communicating the same thing, so write these thoughtfully. + +The label within the search field should be in sentence case, following Spectrum’s UX writing standards for capitalization. + +## States + +When the entered text is too long for the available horizontal space in the field, the text truncates. + +When the help text is too long for the available horizontal space, it wraps to form another line. + +The in-field button offers an option to clear any input search term. + +Instead of showing an error, show a “No results” page or a section with any suggestions for how to get results to appear. + +The label within the search field should be in sentence case, following Spectrum’s UX writing standards for capitalization. + +## Behaviors + +When the entered text is too long for the available horizontal space in the field, the text truncates. + +When the help text is too long for the available horizontal space, it wraps to form another line. + +The in-field button offers an option to clear any input search term. + +Instead of showing an error, show a “No results” page or a section with any suggestions for how to get results to appear. + +The label within the search field should be in sentence case, following Spectrum’s UX writing standards for capitalization. + +## Usage guidelines + +Instead of showing an error, show a “No results” page or a section with any suggestions for how to get results to appear. + +The label within the search field should be in sentence case, following Spectrum’s UX writing standards for capitalization. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Rating](/page/rating/) +* [Segmented control](/page/segmented-control/) diff --git a/docs/s2-docs/components/inputs/segmented-control.md b/docs/s2-docs/components/inputs/segmented-control.md new file mode 100644 index 00000000..f7f0b4d1 --- /dev/null +++ b/docs/s2-docs/components/inputs/segmented-control.md @@ -0,0 +1,123 @@ +--- + +title: "Segmented control" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* search-field +* select-box + parent\_category: inputs + +--- + +# Segmented control + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------- | ---------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/segmentedcontrol--docs) | +| Spectrum Web Components Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/segmentedcontrol--docs) | +| React Spectrum RSP: | [SegmentedControl](https://react-spectrum.adobe.com/s2/index.html?path=/docs/segmentedcontrol--docs) | + +## Anatomy + +``` +segmented control +- track +- segmented control item +- icon (optional) +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- | +| orientation | horizontal / vertical horizontal | – | | +| isFluid | boolean | false | If true, the control takes up the full width of its container. Only applicable to horizontal segmented controls. | +| alignment | start / center start | – | | +| hideTracker | boolean | false | If true, the tracker that indicates the selected item is hidden. | +| selectedItem | string | – | The identifier of the currently selected item. | +| keyboardActivation | manual / automatic manual | – | | +| items | array – An array of segmented control | items. | | + +## External links + +Segmented controls display a group of buttons where only one can be selected at a time. They're ideal for toggling between layouts like a list, grid, or map. Avoid using them for navigation or triggering actions. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Segmented controls should have between two and five items. + +The identifier of the currently selected item. + +By default, segmented controls should include a track. The track style is justified within the parent container. Segmented controls without a track are left-aligned in left-to-right (LTR) languages. + +Segmented controls without a track are left aligned in left-to-right languages. + +If true, the control takes up the full width of its container. Only horizontal segmented controls support fluid behavior. + +Segmented controls can be either horizontal or vertical. By default, segmented controls are horizontal. + +Segmented controls have one item selected by default at all times, and are mutually exclusive. This means selecting one item automatically deselects the others. + +Clicking on a segmented control item immediately performs the view change. + +When the segmented control item text is too long for the available horizontal space, it truncates at the end. The full text should be revealed with a tooltip on hover. + +Icon-only or truncated label segmented controls can be hard to identify. They should display a tooltip after a brief hover, showing the name and a keyboard shortcut, if applicable. + +Segmented controls are only meant to be used to change the way you view information on a page. They should not be used for navigating, filtering content, or taking actions. + +Use a segmented control when the primary goal is to switch views of content. Tabs are reserved for navigation. Action groups are for triggering actions. Tag groups are for filtering content. + +It may not make sense in every case to include icons. If the items are too complicated to convey in an icon, don’t force it. Keep in mind that if one segmented control has an icon, then they all should have an icon. + +Segmented control groups work best with 2 to 5 items. If your component needs more than 5 items, consider using a dropdown or radio button group instead. + +Segmented control groups are meant for switching views on a page. To navigate to a different page or progressively disclose different content, use tabs instead. To perform actions or make a selection, use action groups. + +## States + +Clicking on a segmented control item immediately performs the view change. + +## Behaviors + +Clicking on a segmented control item immediately performs the view change. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Search field](/page/search-field/) +* [Select box](/page/select-box/) diff --git a/docs/s2-docs/components/inputs/select-box.md b/docs/s2-docs/components/inputs/select-box.md new file mode 100644 index 00000000..6bdb3cb7 --- /dev/null +++ b/docs/s2-docs/components/inputs/select-box.md @@ -0,0 +1,146 @@ +--- + +title: "Select box" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* segmented-control +* slider + parent\_category: inputs + +--- + +# Select box + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------- | ------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/selectboxgroup-alpha--docs) | +| Spectrum Web Components Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/selectboxgroup-alpha--docs) | +| React Spectrum RSP: | [SelectBoxGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/selectboxgroup-alpha--docs) | + +## Anatomy + +``` +select box +- illustration (optional) +- label (required) and body (optional) +- checkbox +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------------- | ----------------------------------------------- | ------------- | ----------------------------------------- | +| label | string | – | | +| orientation | horizontal / vertical vertical | – | | +| body | string | – | | +| isSelected | boolean | false | | +| hideIllustration | boolean | false | | +| showCheckbox | boolean | false | | +| isDisabled | boolean | false | | +| state | default / down / hover / keyboard focus default | – | | +| multiple | boolean | false | Set to true to allow multiple selections. | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Select boxes allow users to choose options in a workflow. Both single-select and multi-select versions use checkboxes to show selection. Multi-select boxes display unchecked checkboxes by default to signal that multiple choices are allowed. Single-select boxes only show an unchecked checkbox on hover. If showCheckbox is false, selection is only shown using the dark border. + +A select box in a disabled state shows that the items within the group exist, but are not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an option may become available later. Individual boxes may be disabled or the entire group may be disabled. + +Illustrations are optional but recommended and included by default. + +A label is required in select boxes. It acts as the title of the select box and explains its action or purpose.. Ideally, the label should be kept concise, even in the horizontal orientation. + +Body is optional in select boxes. If no value is entered for the body, then it will not appear in the component. Body is usually reserved for the horizontal version of select boxes. + +A select box is vertical by default, which works best when metadata is limited to a short title, with or without an illustration. The horizontal orientation is recommended when the select box includes longer-form metadata. + +Minimum and maximum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +All select boxes should be the same size as one another. Keep metadata concise, and make the size of the box large enough to accommodate longer text when translated to other languages. + +When the title of the select box is too long for the available horizontal space, it wraps to another line. Wrapped text should not affect the size of an individual select box. Each box in a group should have enough space to allow for longer, localized text to fit as necessary. + +Clicking a select box does not immediately move to the next step in the sequence. After making a selection, the user must initiate the next step by choosing a button or similar component outside the select box group. + +A select box group can be navigated using a keyboard. The keyboard focus state takes the button’s visual hover state and adds a blue ring to the button in focus. + +Illustrations should be used when they help clarify the content. If the items are too complex to represent visually, it may be better to omit them. For consistency, if one select box includes an illustration, all select boxes in the group should include one. + +Select box groups work best with 3 to 9 items. If your experience needs more than 9 items, consider using a dropdown, checkboxes, or radio button group instead. + +Select boxes are used to choose an item from a group. If clicking an item is meant to immediately trigger an action, use an action group instead. + +All select boxes in a group should be the same size to maintain visual consistency and usability. + +Select boxes use a checkbox to indicate both single- and multi-selection. Don’t use radio buttons for single-selection. + +Some cases may make more sense for the user to select one or a few options in a group of select boxes, but if the use case doesn’t make sense to be checking a selection, showCheckbox can be false and the highlight style can be used instead. There is no visual differentiation between single- and multi-select behaviors when checkboxes are not present. + +## States + +Minimum and maximum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +Select boxes are used to choose an item from a group. If clicking an item is meant to immediately trigger an action, use an action group instead. + +All select boxes in a group should be the same size to maintain visual consistency and usability. + +Select boxes use a checkbox to indicate both single- and multi-selection. Don’t use radio buttons for single-selection. + +## Behaviors + +Minimum and maximum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts. + +Select boxes are used to choose an item from a group. If clicking an item is meant to immediately trigger an action, use an action group instead. + +All select boxes in a group should be the same size to maintain visual consistency and usability. + +Select boxes use a checkbox to indicate both single- and multi-selection. Don’t use radio buttons for single-selection. + +## Usage guidelines + +Select boxes are used to choose an item from a group. If clicking an item is meant to immediately trigger an action, use an action group instead. + +All select boxes in a group should be the same size to maintain visual consistency and usability. + +Select boxes use a checkbox to indicate both single- and multi-selection. Don’t use radio buttons for single-selection. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Segmented control](/page/segmented-control/) +* [Slider](/page/slider/) diff --git a/docs/s2-docs/components/inputs/slider.md b/docs/s2-docs/components/inputs/slider.md new file mode 100644 index 00000000..b1ed7309 --- /dev/null +++ b/docs/s2-docs/components/inputs/slider.md @@ -0,0 +1,161 @@ +--- + +title: "Slider" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* select-box +* swatch + parent\_category: inputs + +--- + +# Slider + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Slider](https://opensource.adobe.com/spectrum-css/?path=/docs/components-slider--docs) | +| Spectrum Web Components SWC: | \[Slider]\( | +| React Spectrum RSP: | [Slider](https://react-spectrum.adobe.com/s2/index.html?path=/docs/slider--docs) | + +## Anatomy + +``` +slider +- label (optional) +- value (optional) +- track +- fill +- handle +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------------- | ----------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------- | +| label | string | – | | +| labelPosition | top / side top | – | | +| value | number – from minValue to | maxValue | | +| minValue | number | 0 | | +| maxValue | number | 100 | | +| isRange | boolean | false | If true, the slider will allow selection of a range of values by displaying two handles. | +| step | number | 1 | | +| valueFormat | string | – | This will vary depending on implementation. | +| progressionScale | linear / log linear | – | | +| width | number | – | | +| hasFill | boolean | false | | +| fillStart | number | 0 | | +| hasGradient | boolean | false | | +| isEditable | boolean | false | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Sliders select a value along a continuous range. They’re ideal when upper and lower limits are fixed. Use when approximate or fast selection is more important than precision. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long text, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +The value is the number selected within the slider’s range, from the min value to max value. + +The min and max values can also be customized appropriately for whatever the slider is showing. By default, the min value starts at 0 and the max value is set to 100. + +More information about a design scenario, to use this option in the component. + +The step is the increment by which these values increase or decrease. A step value of 1 (the default) lets a user only select whole numbers within the min and max range. + +Sometimes a value needs to be formatted for localization or for clearer communication such as currencies or percentages. Formatting can involve rounding, mathematical transformations, number formatting, or displaying a prefix or suffix, such as “+/-” or “px.” + +Sliders use a linear progression scale by default which means that value is directly correlated to the position of the handle along the track. In some cases, sliders can use a logarithmic (log) progression scale, which is helpful when users need finer control over small values. + +The width of a slider can be customized appropriately for its context. + +The track of the slider can have a fill. By default, the fill originates from the left side of the track. + +If the value represents an offset, the fill start can be set to represent the point of origin. This allows the slider fill to start from inside the track. + +A gradient can be added to the track of any slider to give more meaning to the range of values. Tracks with a gradient can also have a fill. A gradient track should not be used for choosing a precise color; use a color slider, color area, or color wheel instead. + +In situations where users should be able to precisely input a value, the value can be editable within a text field. + +A disabled slider shows that an input exists but is not available in the current context. This helps maintain layout continuity and signals that the slider may become available later. + +A slider can be navigated using a keyboard. The keyboard focus state takes the slider’s visual hover state and adds a blue ring to the slider handle in focus. + +A slider representing multiple non-identical values appears as indeterminate, with an en dash (–) in place of the value. The handle position corresponds to the first selected value. + +When the label is too long for the available horizontal space, it wraps to form another line. + +After a slider has been adjusted, it can be reset to the default value by double-clicking the handle. + +Every slider should have a label. A slider without a label is ambiguous and not accessible. Write the label in sentence case. + +In addition to dragging the handle, sliders can offer other ways to change the value, known as “hot text.” Users can click the value text and drag up or down, or scroll up or down while hovering over the value text. + +Slider values can include a unit when it adds context, such as “%” or “px.” When the value is shown within a text field, the unit disappears on focus. + +If the value ranges from negative to positive, prefix the value with a plus (+) or minus (-) sign. When the sign is shown within a text field, it remains visible on focus. When the sign is shown outside the text field, there should be a space between the sign and the numerical value for readability. + +## States + +When the label is too long for the available horizontal space, it wraps to form another line. + +After a slider has been adjusted, it can be reset to the default value by double-clicking the handle. + +Every slider should have a label. A slider without a label is ambiguous and not accessible. Write the label in sentence case. + +Slider values can include a unit when it adds context, such as “%” or “px.” When the value is shown within a text field, the unit disappears on focus. + +## Behaviors + +When the label is too long for the available horizontal space, it wraps to form another line. + +After a slider has been adjusted, it can be reset to the default value by double-clicking the handle. + +Every slider should have a label. A slider without a label is ambiguous and not accessible. Write the label in sentence case. + +Slider values can include a unit when it adds context, such as “%” or “px.” When the value is shown within a text field, the unit disappears on focus. + +## Usage guidelines + +Every slider should have a label. A slider without a label is ambiguous and not accessible. Write the label in sentence case. + +Slider values can include a unit when it adds context, such as “%” or “px.” When the value is shown within a text field, the unit disappears on focus. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Select box](/page/select-box/) +* [Swatch](/page/swatch/) diff --git a/docs/s2-docs/components/inputs/swatch-group.md b/docs/s2-docs/components/inputs/swatch-group.md new file mode 100644 index 00000000..afacdc0d --- /dev/null +++ b/docs/s2-docs/components/inputs/swatch-group.md @@ -0,0 +1,93 @@ +--- + +title: "Swatch group" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* swatch +* switch + parent\_category: inputs + +--- + +# Swatch group + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Swatch | [group](https://opensource.adobe.com/spectrum-css/?path=/docs/components-swatch-group--docs) | +| Spectrum Web Components SWC: Swatch | [group](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/swatch-group--docs) | +| React Spectrum RSP: | [ColorSwatchPicker](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorswatchpicker--docs) | + +## Anatomy + +``` +swatch group +- swatch +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------------- | ------------------------------------ | ------------- | ---------------------------------------------------------------------------------- | +| size | xs / s / m / l m | – | | +| density | compact / regular / spacious regular | – | | +| enableSelection | boolean | false | | +| selectionMode | single / multiple single | Only | applicable if selection is enabled. | +| allowsEmptySelection | boolean | false | Only applicable if selection is enabled. | +| cornerRadius | none / full / partial none | Determines | the corner radius of each swatch in the group. Partial refers to corner-radius-75. | + +## External links + +Swatch groups organize related swatches into a single container. They’re used to display collections of colors, gradients, textures, or materials for comparison or selection. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +"Swatch groups come in 3 densities: regular (default), compact, and spacious. Compact and spacious densities retain the same swatch size as regular density but have less or more padding between each swatch, respectively." + +By default, selection is not enabled in a swatch group. Selection can be enabled for a swatch group to allow for toggling. This is often used inside of swatch panels. + +When selection is enabled, a swatch group can allow for either single or multiple selection of swatches. This is often used inside of swatch panels to allow for bulk operations, such as deleting multiple swatches at once. + +It’s important for users to compare colors when they’re displayed in a swatch group. Because of this, swatches within a swatch group with low contrast (below 3:1 contrast with the background) have a less prominent border compared to the swatch component when used by itself. This reduces the likelihood of the UI interfering with color perception and comparisons. + +## States + +## Behaviors + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Swatch](/page/swatch/) +* [Switch](/page/switch/) diff --git a/docs/s2-docs/components/inputs/swatch.md b/docs/s2-docs/components/inputs/swatch.md new file mode 100644 index 00000000..d900c594 --- /dev/null +++ b/docs/s2-docs/components/inputs/swatch.md @@ -0,0 +1,105 @@ +--- + +title: "Swatch" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* slider +* swatch-group + parent\_category: inputs + +--- + +# Swatch + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Swatch](https://opensource.adobe.com/spectrum-css/?path=/docs/components-swatch--docs) | +| Spectrum Web Components SWC: | \[Swatch]\( | +| React Spectrum RSP: | [ColorSwatch](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorswatch--docs) | + +## Anatomy + +``` +swatch +- container +- color +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------------- | ----------------------------------------------- | ------------- | -------------------------------------------------------------------- | +| preview | string | – | This will vary depending on implementation. | +| size | xs / s / m / l m | – | | +| shape | square / rectangle square | – | | +| cornerRounding | none / partial / full none | Determines | the corner radius of the swatch. Partial refers to corner-radius-75. | +| isSelected | boolean | false | | +| isDisabled | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +A swatch shows a small sample of a fill — such as a color, gradient, texture, or material — that is intended to be applied to an object. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +The preview shows the sample of the fill that the swatch represents. This property can be a color, gradient, texture, or material. The exact format this property takes will depend on implementation. Some examples of the format include color values, image, canvas, and gradient. + +"Swatches come in four different sizes: extra-small, small, medium, and large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +"By default, swatches have partial rounding. There are 3 options for a swatch’s rounding: none, partial rounding, and full rounding." + +A swatch can have a selected state to allow for selection. This is often used in a swatch group. + +A swatch in a disabled state shows that the swatch exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that a swatch may become available later. Disabled swatches should be used with caution. + +A swatch can be navigated using a keyboard. The keyboard focus state adds a blue ring to the swatch in focus. + +Even though swatches can have a disabled state, hiding unavailable swatches reduces visual clutter and eases cognitive load. Only show disabled swatches if hiding them would cause confusion to your users. + +## States + +A swatch can be navigated using a keyboard. The keyboard focus state adds a blue ring to the swatch in focus. + +## Behaviors + +A swatch can be navigated using a keyboard. The keyboard focus state adds a blue ring to the swatch in focus. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Slider](/page/slider/) +* [Swatch group](/page/swatch-group/) diff --git a/docs/s2-docs/components/inputs/switch.md b/docs/s2-docs/components/inputs/switch.md new file mode 100644 index 00000000..ace0bc9c --- /dev/null +++ b/docs/s2-docs/components/inputs/switch.md @@ -0,0 +1,122 @@ +--- + +title: "Switch" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* swatch-group +* tag + parent\_category: inputs + +--- + +# Switch + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Switch](https://opensource.adobe.com/spectrum-css/?path=/docs/components-switch--docs) | +| Spectrum Web Components SWC: | \[Switch]\( | +| React Spectrum RSP: | [Switch](https://react-spectrum.adobe.com/s2/index.html?path=/docs/switch--docs) | + +## Anatomy + +``` +switch +- track +- handle +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------ | ----------------------------------------------- | ------------- | ----------- | +| label | string | – | | +| isSelected | boolean | false | | +| size | s / m / l / xl m | – | | +| isEmphasized | boolean | false | | +| isDisabled | boolean | false | | +| isReadOnly | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Switches toggle an individual option on or off. They're typically used to activate or deactivate a specific setting. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Switch should always have a label for accessibility and clear comprehension. When the label is not defined, a switch becomes standalone. Standalone switches should only be used when their connection to other components is clear and they give sufficient context — for example, in application panels. + +Switches can either be selected or not selected. They cannot be in an indeterminate state (unlike checkboxes). When a switch represents multiple values that are not identical, the switch should appear as not selected. + +"Switch come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +By default, switches are not emphasized (gray). This version is optimal for when the switch is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content. + +The emphasized (blue) version provides a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a switch needs to be noticed. + +A switch in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later. + +Switches have a read-only option for when they’re in the disabled state but still need their labels to be shown. This allows for content to be copied, but not interacted with or changed. + +A switch can be navigated using a keyboard. The keyboard focus state takes the switch’s visual hover state and adds a blue ring to the switch in focus. + +When the label is too long for the horizontal space available, it wraps to form another line. + +Emphasized switches are optimal for forms, settings, and other scenarios where the switches need to be noticed. Not emphasized switches are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas. + +Standalone switches should be used in situations where the context is clear without an associated text label. For example, a switch located at the top of a panel next to the panel's title makes it clear that the switch will enable/disable the panel options. + +Switches are best for communicating activation (e.g., turning a setting on or off). Checkboxes are best for communicating selection (e.g., selecting multiple items from a list). Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode). + +When a switch represents multiple values that are not identical, the switch should appear as not selected. Any subsequent click or tap should select the switch, and update all values to be selected. Another click or tap after that should deselect the switch, and update all values to be not selected. + +Switches can only be on or off. Indeterminate switches don’t exist in accessibility APIs, so it’s not possible to make an indeterminate switch accessible. If you need to show a partial state, use a checkbox instead of a switch. + +When a parent switch represents a group of switches, it should be turned off unless all of the switches are on (turning the parent switch on turns all of the switches on). + +## States + +When the label is too long for the horizontal space available, it wraps to form another line. + +## Behaviors + +When the label is too long for the horizontal space available, it wraps to form another line. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Swatch group](/page/swatch-group/) +* [Tag](/page/tag/) diff --git a/docs/s2-docs/components/inputs/tag-field.md b/docs/s2-docs/components/inputs/tag-field.md new file mode 100644 index 00000000..a78136b4 --- /dev/null +++ b/docs/s2-docs/components/inputs/tag-field.md @@ -0,0 +1,129 @@ +--- + +title: "Tag field" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* tag +* tag-group + parent\_category: inputs + +--- + +# Tag field + +## Resources + +### Design + +* **Figma**: S2 Web + +## Anatomy + +``` +tag field +- field label +- text area +- tag +- avatar (optional) +- label (required) +- close button (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ---------------------------------------------------------------------------- | ------------- | ----------- | +| size | s / m / l m | – | | +| state | default / hover / focus + hover / focus + not hover / keyboard focus default | – | | +| style | keyword / icon / thumbnail / avatar keyword | – | | +| isDisabled | boolean | false | | +| hideLabel | boolean | false | | + +## External links + +Tag field is an input component for adding and editing multiple tags. It includes standard field label and error options, and is used to capture grouped keywords or descriptors. Tags can be added directly in the field and displayed inline for editing or removal. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +The label of the tag field can be hidden if the context for the tags is sufficient without the title — for example, when the page title or section title applies to the group of tags. + +A tag field in a disabled state indicates that it exists but is not available in that context. This state helps maintain layout continuity and signals that tagging may become available later. + +Tag groups within a tag field can include a keyword, icon, thumbnail or avatar. Icons, thumbnails and avatars should also include a keyword. + +"Tag fields come in three different sizes: small, medium, and large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +A flyout/menu appears when the user starts typing to suggest tags that are supported or have already been entered previously. + +Sometimes tag field can be additive, meaning new tags may be added from this particular tag field. They can also be restricted to only allowing tags that already exist in the system + +When there are more tags than fit in the horizontal space, tags wrap to another line. + +If the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more. + +If there is space in an experience for the field to grow with the tags, such as at the bottom of a page or dialog, you can use the multi-line option. + +If the tag field is located at the top of a header or otherwise constrained space, it is better to use a non-multi-line tag field. + +The default option should be a standard text field with tags displayed below it. You may use a tag field if space is limited, especially when using a single-line tag field. This allows all fields to stay contained within a defined area. + +## States + +A flyout/menu appears when the user starts typing to suggest tags that are supported or have already been entered previously. + +When there are more tags than fit in the horizontal space, tags wrap to another line. + +If the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more. + +If there is space in an experience for the field to grow with the tags, such as at the bottom of a page or dialog, you can use the multi-line option. + +If the tag field is located at the top of a header or otherwise constrained space, it is better to use a non-multi-line tag field. + +## Behaviors + +A flyout/menu appears when the user starts typing to suggest tags that are supported or have already been entered previously. + +When there are more tags than fit in the horizontal space, tags wrap to another line. + +If the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more. + +If there is space in an experience for the field to grow with the tags, such as at the bottom of a page or dialog, you can use the multi-line option. + +If the tag field is located at the top of a header or otherwise constrained space, it is better to use a non-multi-line tag field. + +## Usage guidelines + +If there is space in an experience for the field to grow with the tags, such as at the bottom of a page or dialog, you can use the multi-line option. + +If the tag field is located at the top of a header or otherwise constrained space, it is better to use a non-multi-line tag field. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Tag](/page/tag/) +* [Tag group](/page/tag-group/) diff --git a/docs/s2-docs/components/inputs/tag-group.md b/docs/s2-docs/components/inputs/tag-group.md new file mode 100644 index 00000000..acde6406 --- /dev/null +++ b/docs/s2-docs/components/inputs/tag-group.md @@ -0,0 +1,109 @@ +--- + +title: "Tag group" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* tag-field +* text-area + parent\_category: inputs + +--- + +# Tag group + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Tag | [group](https://opensource.adobe.com/spectrum-css/?path=/docs/components-tag-group--docs) | +| Spectrum Web Components SWC: | \[Tags]\( | +| React Spectrum RSP: | [TagGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/taggroup--docs) | + +## Anatomy + +``` +tag group +- field label +- tag +- action button +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------- | -------------- | ------------- | ------------------------------------------ | +| size | s / m / l m | – | | +| labelPosition | top / side top | – | | +| hideLabel | boolean | false | | +| actionLabel | string | – | If undefined, this button does not appear. | + +## External links + +Tag groups organize multiple tags into a single visual group. They’re used to categorize content like keywords or names that describe an item or search query. Tags within the group can be added, removed, or styled to reflect different types of content. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +"Tag groups come in three different sizes: small, medium, and large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +Labels can be placed either on top or on the side of a group of tags. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +The label of the tag group can be hidden if the context for the tags is sufficient without the title — for example, when the page title or section title applies to the group of tags. + +Define an action label to include a link-style button to perform an action on the entire group of tags. This button always appears at the end of the tag group. + +When horizontal space is limited in a tag group, the individual tags wrap to form another line. + +If the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more. + +In some instances, it's possible to add an action next to a group of tags to provide a way to easily act on the entire group at once. Reveal the action only when more than one tag is displayed. + +In cases where users cannot interact with a large group of tags, consider hiding the group and its broader construct rather than disabling all the individual tags. + +## States + +When horizontal space is limited in a tag group, the individual tags wrap to form another line. + +If the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more. + +## Behaviors + +When horizontal space is limited in a tag group, the individual tags wrap to form another line. + +If the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Tag field](/page/tag-field/) +* [Text area](/page/text-area/) diff --git a/docs/s2-docs/components/inputs/tag.md b/docs/s2-docs/components/inputs/tag.md new file mode 100644 index 00000000..b1ce1c52 --- /dev/null +++ b/docs/s2-docs/components/inputs/tag.md @@ -0,0 +1,104 @@ +--- + +title: "Tag" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* switch +* tag-field + parent\_category: inputs + +--- + +# Tag + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Tag](https://opensource.adobe.com/spectrum-css/?path=/docs/components-tag--docs) | +| Spectrum Web Components SWC: | \[Tags]\( | +| React Spectrum RSP: | [TagGroup](https://react-spectrum.adobe.com/s2/index.html?path=/docs/taggroup--docs) | + +## Anatomy + +``` +tag +- avatar (optional) +- label (required) +- close button (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ----------------------------------------------- | ------------- | ----------- | +| label | string | – | | +| hasAvatar | boolean | false | | +| isRemovable | boolean | false | | +| isError | boolean | false | | +| isDisabled | boolean | false | | +| isReadOnly | boolean | false | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Tags categorize content such as keywords or names. They’re often grouped to represent a search query or describe an item. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Tags should always include a label. These can represent search terms, filters, or keywords. + +Tags have the option to include an avatar in addition to the label. These should be used to represent entities. + +Tags have the option to be removable or not. Removable tags have a small close (“x”) button. + +A tag can be marked as having an error to show that it has become invalid. + +A tag in a disabled state shows that a tag exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a tag may become available later. + +Tags have a read-only option for when content in the disabled state still needs to be shown. This allows for content to be copied, but not interacted with or changed. + +When the tag text is too long for the available horizontal space or when a tag reaches its maximum width, it truncates. Hovering over the tag shows a tooltip with the full text. + +A tag can either trigger navigation or filtering, or act as a dismissible chip. Combining both interactions disrupts focus order and accessibility states. Choose one behavior — navigation or dismissal — and apply it consistently. + +## States + +## Behaviors + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Switch](/page/switch/) +* [Tag field](/page/tag-field/) diff --git a/docs/s2-docs/components/inputs/text-area.md b/docs/s2-docs/components/inputs/text-area.md new file mode 100644 index 00000000..647b5b10 --- /dev/null +++ b/docs/s2-docs/components/inputs/text-area.md @@ -0,0 +1,181 @@ +--- + +title: "Text area" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* tag-group +* text-field + parent\_category: inputs + +--- + +# Text area + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Text | [area](https://opensource.adobe.com/spectrum-css/?path=/docs/components-text-area--docs) | +| Spectrum Web Components SWC: | \[Textarea]\( | +| React Spectrum RSP: | [TextField](https://react-spectrum.adobe.com/s2/index.html?path=/docs/textfield--docs#text-area-example) | + +## Anatomy + +``` +text area +- label +- required asterisk, required text, or optional text +- character count +- field +- value +- validation marker or error icon +- help text (help text or error message) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ---------------------------------------------------------------------------- | ------------- | ------------------------- | +| label | string | – | | +| labelPosition | top / side top | – | | +| hideLabel | boolean | false | | +| value | string | – | from minValue to maxValue | +| width | number | – | | +| size | s / m / l / xl m | – | | +| necessityIndicator | text / icon icon | – | | +| isRequired | boolean | false | | +| hasCharacterCount | boolean | false | | +| showValidIcon | boolean | false | | +| isError | boolean | false | | +| isDisabled | boolean | false | | +| hideDragIcon | boolean | false | | +| height | number – If undefined, height is dynamic and grows with input | text. | | +| helpText | string | – | | +| errorMessage | string | – | | +| inputType | text / url / phone / email / password text | – | | +| state | default / hover / focus + hover / focus + not hover / keyboard focus default | – | | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +The value shows a user’s entered text. + +The text area’s default width is field-default-width-\[small/medium/large/extra-large]. + +"Text areas come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +"Text areas can be marked as optional or required, depending on the situation. For required text areas, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional text areas are either denoted with text added to the end of the label — “(optional)” — or have no indication at all." + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +Text areas can show a character count when input must stay under a set limit. This indicator can appear alongside others, such as validation icons or “optional” and “required” labels. + +Text areas can show a validation icon when input must follow a specific format, such as an email or credit card number. The icon appears as soon as the entry is valid. + +A text area can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. If an error exists, the error icon always overrides the validation icon. + +A text area in a disabled state shows that the input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a text area may become available later. + +If the height is defined, text areas can either be a static size or can be resizable with a drag icon in the bottom right corner. The drag icon should be hidden if the fixed variant is turned off, or if the text area should not be resizable. + +When defined as fixed (either by the development team or by the end user via the dragIcon), users can scroll inside the field. + +A text area can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field. + +A text area can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. The error message communicates an error for when the field requirements aren’t met, prompting a user to adjust what they had originally input. If an error exists, the error icon always overrides the validation icon. + +A text area can have multiple input types, depending on the need and use case. Text areas have a text input type by default. + +"Use these input types for the following use cases:" + +When typing into a text area and reaching the end of the field on a number-height text area, the cursor should remain as static in the bottom right corner (for left-to-right languages) while text above it overflows through the top of the field. When the field loses focus, text should overflow through the bottom of the text area, showing the beginning of the text. + +When a text area presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Every text area should have a label. A text area without a label is ambiguous and not accessible. + +Text area labels and placeholder text should be written in sentence case. + +In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. If most of the text fields are optional, only the required fields should be give an asterisk or have labels appended with “(required)”. If most of the text fields are required, only the optional fields should be appended with “(optional)”. An asterisk should never be used to note that a text area is optional. + +"The description in the help text is flexible and encompasses a range of guidance. Sometimes this guidance is about what to input, and sometime it’s about how to input. This includes information such as:" + +The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text. + +Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. + +Instead of placeholder text, use the help text description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, especially if they're communicating the same thing. + +The help text area also displays an error message. When a text area already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the field. + +Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Error text tells a user how to fix the error by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other like minimum requirements. + +Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user. + +"Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For text areas, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their interests, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter at least one interest.”" + +## States + +When a text area presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Every text area should have a label. A text area without a label is ambiguous and not accessible. + +Text area labels and placeholder text should be written in sentence case. + +## Behaviors + +When a text area presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Every text area should have a label. A text area without a label is ambiguous and not accessible. + +Text area labels and placeholder text should be written in sentence case. + +## Usage guidelines + +Every text area should have a label. A text area without a label is ambiguous and not accessible. + +Text area labels and placeholder text should be written in sentence case. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Tag group](/page/tag-group/) +* [Text field](/page/text-field/) diff --git a/docs/s2-docs/components/inputs/text-field.md b/docs/s2-docs/components/inputs/text-field.md new file mode 100644 index 00000000..be566f47 --- /dev/null +++ b/docs/s2-docs/components/inputs/text-field.md @@ -0,0 +1,180 @@ +--- + +title: "Text field" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs +* input +* form + related\_components: +* text-area +* thumbnail + parent\_category: inputs + +--- + +# Text field + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Text | [field](https://opensource.adobe.com/spectrum-css/?path=/docs/components-text-field--docs) | +| Spectrum Web Components SWC: | \[Textfield]\( | +| React Spectrum RSP: | [TextField](https://react-spectrum.adobe.com/s2/index.html?path=/docs/textfield--docs) | + +## Anatomy + +``` +text field +- label +- required asterisk, required text, or optional text +- character count +- field +- value +- validation marker or error icon +- help text (help text or error message) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------------ | ---------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------- | +| label | string | – | | +| labelPosition | top / side top | – | | +| hideLabel | boolean | false | | +| value | string | – | from minValue to maxValue | +| width | number | – | | +| size | s / m / l / xl m | – | | +| necessityIndicator | text / icon icon | – | | +| isRequired | boolean | false | | +| hasCharacterCount | boolean | false | | +| showValidIcon | boolean | false | | +| isError | boolean | false | If there is an error, this property overrides show valid icon. | +| isDisabled | boolean | false | | +| helpText | string | – | | +| errorMessage | string | – | | +| state | default / hover / focus + hover / focus + not hover / keyboard focus default | – | | + +## External links + +Text fields collect custom text input. They can display optional cues to indicate formatting, validation, or other input requirements. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Text fields should always have an accessible name, typically provided by a visible text label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the visible label may be hidden or omitted. When no visible label is present, the input must still expose an accessible name (for example, in HTML via “aria-label” or “aria-labelledby,” and on other platforms via the platform’s accessible-name mechanism). + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +The value shows a user’s entered text. + +The text field’s default width is field-default-width-\[small/medium/large/extra-large]. + +"Text fields come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +"Text fields can be marked as optional or required, depending on the situation. For required text fields, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional text fields are either denoted with text added to the end of the label — “(optional)” — or have no indication at all." + +The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. + +Text fields can display a character count indicator when the length of the text entry needs to be kept under a predefined value. Character count indicators can be used in conjunction with other indicators (validation icon, “optional” or “required” indicators) when necessary. + +Text fields can display a validation icon when the text entry is expected to conform to a specific format such as email address, credit card number, password creation requirements, and many more. The icon appears as soon as a user types a valid entry in the field. + +A text field can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. If an error exists, the error icon always overrides the validation icon. + +A text field in a disabled state shows that an text field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a field may become available later. + +A text field can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field. + +A text field can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. The error message communicates an error for when the field requirements aren’t met, prompting a user to adjust what they had originally input. If an error exists, the error icon always overrides the validation icon. + +The minimum width for a text field is 1.5 × the height of the field. This minimum width guarantees that small text fields are readable and easy to target on touch devices. + +When the field label is too long for the available horizontal space, it wraps to form another line. The field text itself truncates. + +When a text field presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Every text field should have a label. A field without a label is ambiguous and not accessible. + +Field labels should be in sentence case. + +In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. If most of the text fields are optional, only the required fields should be give an asterisk or have labels appended with “(required)”. If most of the text fields are required, only the optional fields should be appended with “(optional)”. An asterisk should never be used to note that a text field is optional. + +The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text. + +Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. + +Instead, use the help text description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, especially if they're communicating the same thing. + +The help text area also displays an error message. When a text field already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the field. + +Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Error text tells a user how to fix the error by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other like password requirements. + +Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user. + +"Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For text fields, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their email address, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter your email address.”" + +## States + +When the field label is too long for the available horizontal space, it wraps to form another line. The field text itself truncates. + +When a text field presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Every text field should have a label. A field without a label is ambiguous and not accessible. + +Field labels should be in sentence case. + +## Behaviors + +When the field label is too long for the available horizontal space, it wraps to form another line. The field text itself truncates. + +When a text field presents multiple values that are not identical, the field should show an en dash (–). + +When the help text is too long for the available horizontal space, it wraps to form another line. + +Every text field should have a label. A field without a label is ambiguous and not accessible. + +Field labels should be in sentence case. + +## Usage guidelines + +Every text field should have a label. A field without a label is ambiguous and not accessible. + +Field labels should be in sentence case. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Text area](/page/text-area/) +* [Thumbnail](/page/thumbnail/) diff --git a/docs/s2-docs/components/inputs/thumbnail.md b/docs/s2-docs/components/inputs/thumbnail.md new file mode 100644 index 00000000..ed770a50 --- /dev/null +++ b/docs/s2-docs/components/inputs/thumbnail.md @@ -0,0 +1,105 @@ +--- + +title: "Thumbnail" +source\_url: +last\_updated: 2026-02-02 +category: components/inputs +component\_type: input +status: published +tags: + +* components-inputs + related\_components: +* text-field +* accordion + parent\_category: inputs + +--- + +# Thumbnail + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Thumbnail](https://opensource.adobe.com/spectrum-css/?path=/docs/components-thumbnail--docs) | +| Spectrum Web Components SWC: | \[Thumbnail]\( | + +## Anatomy + +``` +thumbnail +- container +- image +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------- | -------------------------------------------------------------------- | ------------- | ----------- | +| size | 50 / 75 / 100 / 200 / 300 / 400 / 500 / 600 / 700 / 800 / 900 / 1000 | – | | +| state | default / disabled default | – | | + +## External links + +Thumbnails display a preview of an image, layer, or effect, and appear in a variety of locations as a visual reference. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Thumbnail sizes scale exponentially. The opacity checkerboard responsively resizes to appropriately fit within each thumbnail size. + +Thumbnails can be navigated using a keyboard in certain scenarios, such as layers or layer masks. When a thumbnail is used as pure representation of an item, focus should be set on the component the thumbnail is used within. + +Thumbnails feature rounded corners and may include images with transparency. A subtle inset border helps distinguish images that might otherwise blend into the product’s theme colors. + +When thumbnails are used in layer management (such as Treeview, Compact or Detail Layers panels), the thumbnail is given a thick gray border. + +When a user selects a thumbnail in layer management, such as in Treeview, Compact or Detail Layers panels, it is highlighted with a thick blue border. + +Tree view items can show thumbnails as an alternative to icons. Thumbnails are best used when a user needs to have a preview of the content represented by the tree view item. Icons can be used as a fallback for when an image is unavailable, but should be appropriately sized to match the thumbnail. + +Tree views with thumbnails should use a thumbnail size that is appropriate to the size of the tree view itself. For example, an extra-large tree view would not work well with small thumbnails; those proportions may be better suited for using icons instead. + +In some cases, multiple thumbnails need to be displayed in-line with the tree view item (e.g., layer masks). These thumbnails should be individually selectable and inherit all other behaviors of a standard tree view item, such as drag-and-drop behavior. Don't use more than 3 thumbnails per tree view item. + +## States + +When thumbnails are used in layer management (such as Treeview, Compact or Detail Layers panels), the thumbnail is given a thick gray border. + +When a user selects a thumbnail in layer management, such as in Treeview, Compact or Detail Layers panels, it is highlighted with a thick blue border. + +## Behaviors + +When thumbnails are used in layer management (such as Treeview, Compact or Detail Layers panels), the thumbnail is given a thick gray border. + +When a user selects a thumbnail in layer management, such as in Treeview, Compact or Detail Layers panels, it is highlighted with a thick blue border. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Text field](/page/text-field/) +* [Accordion](/page/accordion/) diff --git a/docs/s2-docs/components/navigation/accordion.md b/docs/s2-docs/components/navigation/accordion.md new file mode 100644 index 00000000..5517ecf0 --- /dev/null +++ b/docs/s2-docs/components/navigation/accordion.md @@ -0,0 +1,119 @@ +--- + +title: "Accordion" +source\_url: +last\_updated: 2026-02-02 +category: components/navigation +component\_type: navigation +status: published +tags: + +* components-navigation + related\_components: +* thumbnail +* breadcrumbs + parent\_category: navigation + +--- + +# Accordion + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: | [Accordion](https://opensource.adobe.com/spectrum-css/?path=/docs/components-accordion--docs) | +| Spectrum Web Components SWC: | [Accordion](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/accordion--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [Accordion](https://react-spectrum.adobe.com/s2/index.html?path=/docs/accordion--docs) | + +## Anatomy + +``` +accordion +- accordion items +- small divider +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ----------------------------------------------- | ------------- | ------------------------------------------------------------------- | +| state | default / hover / down / keyboard focus default | – | | +| size | s / m / l / xl m | – | | +| isQuiet | boolean | false | | +| isDisabled | boolean | false | | +| density | compact / regular / spacious regular | – | | +| items | array – An array of accordion | items. | | +| isMultiple | boolean | false | If true, multiple accordion items can be expanded at the same time. | + +## External links + +An accordion displays a list of items that can be expanded or collapsed to show additional content. It can support zero, one, or multiple expanded items at a time. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +By default, only one accordion item can be expanded at a time. Use the isMultiple option to allow multiple items to be expanded simultaneously. + +Accordions can contain any number of items. Each item can be expanded or collapsed by interacting with any part of the item. + +"Accordions come in three densities: compact, regular, and spacious. Each of the different densities have the same font size, but have tighter or looser vertical spacing between the rows." + +Individual accordion items can be disabled using the isDisabled option. Disabled items cannot be expanded or collapsed. + +By default, accordions have dividers between sections. This style works best when lots of content is inside each section. + +Alternatively, you can have no dividers between sections. This style works best when a clear layout (vertical stack, table, grid) makes it easy see and understand. Too many quiet components in a small space can be hard to differentiate. + +"Accordions come in four different sizes: small, medium, large, and extra-large. The medium size is the default and recommended option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page. Each of the different sizes have varying font sizes, and tighter or looser vertical spacing between the rows." + +By default, only one accordion item may be expanded at a time. However, the component can be configured to allow multiple items to remain open simultaneously. + +Accordion titles wrap automatically if they exceed the available width. + +An optional action button or switch can be placed on the trailing edge of an accordion item to support contextual interactions. + +Accordions are effective for organizing large amounts of related content within a limited space. They help users stay focused by revealing information only when it's needed, making them ideal for scenarios where not all content needs to be visible at once. + +Avoid using accordions when users are likely to read all the content in one go, as they can introduce unnecessary clicks and hinder the user experience. For complex or deeply nested information structures, consider alternative components such as tree views or tabs to maintain clarity and ease of navigation. + +## States + +Accordion titles wrap automatically if they exceed the available width. + +An optional action button or switch can be placed on the trailing edge of an accordion item to support contextual interactions. + +## Behaviors + +Accordion titles wrap automatically if they exceed the available width. + +An optional action button or switch can be placed on the trailing edge of an accordion item to support contextual interactions. + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Thumbnail](/page/thumbnail/) +* [Breadcrumbs](/page/breadcrumbs/) diff --git a/docs/s2-docs/components/navigation/breadcrumbs.md b/docs/s2-docs/components/navigation/breadcrumbs.md new file mode 100644 index 00000000..03f449d8 --- /dev/null +++ b/docs/s2-docs/components/navigation/breadcrumbs.md @@ -0,0 +1,141 @@ +--- + +title: "Breadcrumbs" +source\_url: +last\_updated: 2026-02-02 +category: components/navigation +component\_type: navigation +status: published +tags: + +* components-navigation + related\_components: +* accordion +* side-navigation + parent\_category: navigation + +--- + +# Breadcrumbs + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Breadcrumbs](https://opensource.adobe.com/spectrum-css/?path=/docs/components-breadcrumbs--docs) | +| Spectrum Web Components SWC: | [Breadcrumbs](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/breadcrumbs--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [Breadcrumbs](https://react-spectrum.adobe.com/s2/index.html?path=/docs/breadcrumbs--docs) | + +## Anatomy + +``` +breadcrumbs +- truncated menu +- breadcrumbs item +- separator +- breadcrumbs title +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------ | --------------------------------------------------------------- | ------------- | --------------------------------------------------------------------- | +| state | default / hover / down / keyboard focus / drag and drop default | – | | +| isMultiline | boolean | false | If true, the breadcrumb items will wrap to multiple lines. | +| size | m / l m | Controls | the overall size of the breadcrumb component. | +| items | array – An array of breadcrumb | items. | | +| separator | chevron / none chevron | The | separator icon used between breadcrumb items. | +| isTruncated | boolean | false | If true, the breadcrumb item is truncated and displayed as icon only. | +| sizeOverride | s / m / l / xl | – | Overrides the size of the breadcrumb items when isMultiline is true. | + +## External links + +Breadcrumbs show hierarchy and navigational context for a user’s location within an app. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +When set to true, the breadcrumb item is displayed as an icon only. + +Separators visually divide breadcrumb items and convey hierarchy. + +Breadcrumbs can include multiple items, but too many levels can overwhelm users. Limit the hierarchy to four items (including the root, if shown) to provide clear context while keeping truncated options accessible. + +"Breadcrumbs come in two sizes: medium, and large. The medium size is the default and most frequently used option." + +The multiline variation places emphasis on the selected breadcrumb item as a page title, helping a user to more clearly identify their current location. + +Breadcrumbs truncate when there is not enough room to display all levels of the breadcrumb list, or as a way of managing relevance of the visible breadcrumb items in a deeply nested hierarchy. The truncation of breadcrumb items begins when either there is not enough room to display all items, or if there are 5 or more breadcrumbs to display. + +The truncation menu displays all options within a breadcrumb. Items are listed with the hierarchy ordered from top (root) to bottom and include the currently selected item. + +Breadcrumbs need a consistent hierarchical structure because they create a path for discovery and context for a user’s current location. + +Breadcrumbs should be a form of navigating a linear hierarchy. They should not be used for any other interactions, such as displaying filters. + +The truncation menu should display all available options within the hierarchy where a user is located — not as indented. Doing this provides context for the directionality of how the menu is being displayed. Adding indentation to the menu items does not add value to understanding the hierarchy, and it can actually decrease the readability of the menu options. + +When list items are truncated into a menu but the label text is still too large for the horizontal space, truncate the text with an ellipsis. By default, truncation should occur at the end of the title. If your users need to see the end of truncated titles, truncating the middle of the title is acceptable. + +When the breadcrumb title is truncated, a tooltip should display the full title when the user hovers, keyboard focuses, or single-taps on mobile. + +Prioritize using the truncation menu when breadcrumb labels are long. Never truncate more than one breadcrumb label. If the current location has a long label, all items can be truncated into the menu. + +Truncation should be avoided by way of the breadcrumbs overflow behavior, although in some cases the final breadcrumb title may truncate with an ellipsis. + +Be mindful of your user’s cognitive load and truncate breadcrumbs appropriately. Displaying too many levels can be overwhelming. By displaying only 4 items in the hierarchy (including the root item, if you are displaying it), users will quickly understand context while still having easy access to any truncated options. Truncation of breadcrumb items begins when either there is not enough room to display all items, or if there are 5 or more breadcrumbs to display. + +Don't use icons within the labels for breadcrumbs. Since breadcrumb labels are horizontally distributed, icons disrupt the rhythm and readability of the list. + +Breadcrumbs are a way for traveling up a hierarchical navigation and should not be mixed with controls intended for lateral or non-hierarchical navigation. + +## States + +Breadcrumbs need a consistent hierarchical structure because they create a path for discovery and context for a user’s current location. + +Breadcrumbs should be a form of navigating a linear hierarchy. They should not be used for any other interactions, such as displaying filters. + +When the breadcrumb title is truncated, a tooltip should display the full title when the user hovers, keyboard focuses, or single-taps on mobile. + +## Behaviors + +Breadcrumbs need a consistent hierarchical structure because they create a path for discovery and context for a user’s current location. + +Breadcrumbs should be a form of navigating a linear hierarchy. They should not be used for any other interactions, such as displaying filters. + +When the breadcrumb title is truncated, a tooltip should display the full title when the user hovers, keyboard focuses, or single-taps on mobile. + +## Usage guidelines + +Breadcrumbs need a consistent hierarchical structure because they create a path for discovery and context for a user’s current location. + +Breadcrumbs should be a form of navigating a linear hierarchy. They should not be used for any other interactions, such as displaying filters. + +When the breadcrumb title is truncated, a tooltip should display the full title when the user hovers, keyboard focuses, or single-taps on mobile. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Accordion](/page/accordion/) +* [Side navigation](/page/side-navigation/) diff --git a/docs/s2-docs/components/navigation/side-navigation.md b/docs/s2-docs/components/navigation/side-navigation.md new file mode 100644 index 00000000..ebf3da8f --- /dev/null +++ b/docs/s2-docs/components/navigation/side-navigation.md @@ -0,0 +1,144 @@ +--- + +title: "Side navigation" +source\_url: +last\_updated: 2026-02-02 +category: components/navigation +component\_type: navigation +status: published +tags: + +* components-navigation + related\_components: +* breadcrumbs +* tabs + parent\_category: navigation + +--- + +# Side navigation + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Side | [nav](https://opensource.adobe.com/spectrum-css/?path=/docs/components-side-nav--docs) | +| Spectrum Web Components SWC: | \[Sidenav]\( | + +## Anatomy + +``` +side navigation +- header +- item +- icon (optional) +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ------------- | ----------------------------------------------- | ------------- | ------------------------------- | +| state | default / hover / down / keyboard focus default | – | | +| items | array – The list of navigation | items. | | +| selectionMode | none / single / multiple single | How | selection is handled for items. | + +## External links + +Side navigation provides access to the main content areas of a product or section. It can support single-level or multi-level navigation. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +The type of selection allowed in side navigation can be none, single or multiple. + +The list of navigation items displayed in a side navigation. Each item includes a label by default and can optionally include an icon. Items that contain nested navigation levels can also include a trailing accessory area, which supports a chevron and an optional counter. + +At a glance, the app frame side navigation may look similar to the standard side navigation. However, its interaction model introduces key differences. + +The app frame side navigation includes a collapsible menu that lets users hide or reveal labels. + +The standard side navigation, on the other hand, is best suited for fixed layouts that support multiple visual styles, such as icon-only, text-only, or mixed. Note that the standard side navigation cannot collapse. + +The width of the side navigation is flexible, so choose a width that works with the navigation items in your experience. Make the width generous enough so that it doesn’t feel too condensed. Doing this will ensure that users won't confuse the side navigation with buttons or other controls. + +When the navigation item text is too long for the horizontal space available, it wraps to form another line. + +Make sure the width is generous enough so that it doesn’t feel too condensed. This ensures it doesn’t get confused with buttons or other controls. + +Navigation should be helpful. Choose titles for navigation items that clearly communicate the places where they'll go. Arbitrary or non-useful titles cause usability issues. + +Along with being descriptive, the labels of navigation items should be succinct. Keep navigation strings to 1 or 2 and no more than 3 concise words (in U.S. English, which is the source locale). Reduce any unnecessary words in order to ensure simplicity. + +Navigation items should never be so long that they require truncation, except in instances where navigation is user-generated, such as folder and filenames. + +When possible, the default width should automatically adjust to the longest string in the navigation to accommodate all translations. As a last resort for long strings, specific line breaks can be built into the implementation. These breaks depend on the content and require manual handling by globalization engineers. + +In multi-level side navigation, icon and text-only styles can be used together. Users may include supporting icons on the first level and omit them on the second and third levels, or choose to use no icons at all. + +Do not mix icon and no-icon options within the same navigation level. + +The multi-level side navigation goes to three levels deep. Adding more than three levels will make the indentation indiscernible, which becomes a major usability issue. + +If top-level navigation items have a location associated with them, send the user to that location and open the sub-level navigation items. If a top-level navigation item does not have any associated location, only open the sub-level navigation items. + +Side navigation can use either of these behaviors, but should never mix behaviors in the same experience. + +## States + +The app frame side navigation includes a collapsible menu that lets users hide or reveal labels. + +When the navigation item text is too long for the horizontal space available, it wraps to form another line. + +Make sure the width is generous enough so that it doesn’t feel too condensed. This ensures it doesn’t get confused with buttons or other controls. + +Do not mix icon and no-icon options within the same navigation level. + +Side navigation can use either of these behaviors, but should never mix behaviors in the same experience. + +## Behaviors + +The app frame side navigation includes a collapsible menu that lets users hide or reveal labels. + +When the navigation item text is too long for the horizontal space available, it wraps to form another line. + +Make sure the width is generous enough so that it doesn’t feel too condensed. This ensures it doesn’t get confused with buttons or other controls. + +Do not mix icon and no-icon options within the same navigation level. + +Side navigation can use either of these behaviors, but should never mix behaviors in the same experience. + +## Usage guidelines + +Make sure the width is generous enough so that it doesn’t feel too condensed. This ensures it doesn’t get confused with buttons or other controls. + +Do not mix icon and no-icon options within the same navigation level. + +Side navigation can use either of these behaviors, but should never mix behaviors in the same experience. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Breadcrumbs](/page/breadcrumbs/) +* [Tabs](/page/tabs/) diff --git a/docs/s2-docs/components/navigation/tabs.md b/docs/s2-docs/components/navigation/tabs.md new file mode 100644 index 00000000..fce42209 --- /dev/null +++ b/docs/s2-docs/components/navigation/tabs.md @@ -0,0 +1,115 @@ +--- + +title: "Tabs" +source\_url: +last\_updated: 2026-02-02 +category: components/navigation +component\_type: navigation +status: published +tags: + +* components-navigation + related\_components: +* side-navigation +* tree-view + parent\_category: navigation + +--- + +# Tabs + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Tabs](https://opensource.adobe.com/spectrum-css/?path=/docs/components-tabs--docs) | +| Spectrum Web Components SWC: | \[Tabs]\( | +| React Spectrum RSP: | [Tabs](https://react-spectrum.adobe.com/s2/index.html?path=/docs/tabs--docs) | + +## Anatomy + +``` +tabs +- tab item (selected) +- tab item +- selection indicator +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | -------------------------------- | ------------- | ----------- | +| orientation | horizontal / vertical horizontal | – | | +| items | array – An array of tab | items. | | + +## External links + +Tabs organize related content into multiple sections. They allow navigation between views while keeping the content grouped under a single context. Use when content can be divided logically into categories within the same view. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Tabs can be horizontal or vertical. By default, tabs are horizontal and should be used when horizontal space is limited. + +Use vertical tabs when horizontal space is more generous or when the list of sections is too long for a horizontal layout. Vertical tabs can also serve as anchor links, providing shortcuts to sections on a single page. In this case, tab items link to on-page anchors rather than opening a new tab view. + +When a user selects a tab item, the selection indicator slides along the base to the newly selected tab. The text and icon colors of both tabs fade during the transition. The tab view changes immediately upon selection. + +When there are too many tabs to fit horizontally across the viewport, display the tabs component as a quiet picker. When appropriate, you can also use alternative overflow methods such as horizontal scrolling. + +When there are too many tabs to fit horizontally across the viewport, you can either allow horizontal scrolling or place all tab items in a quiet picker. Do not truncate multiple tab items just to make them fit horizontally. + +Use tabs to organize sections of equal importance. Groups of content under each tab item should not be of different natures. Don't use tabs to replace a flow; use pagination components instead. + +Avoid using multiple levels of tabs. Instead, consider other organizational patterns such as side navigation, accordions or collapsible panels. Nesting tabs is acceptable only when there is a clear separation between the two tab experiences or when different orientations are used. + +Do not compromise hierarchy by using the same tab variations or orientations. + +Don’t mix the use of icons in tabs. Navigation controls require a clear spacial relationship to one another, and mixing the use of icons can dramatically impact the visual balance and presence for each tab item. Keep in mind that if one tab item has an icon, then they all should have an icon. + +It can often be hard to identify the meaning of icon-only tabs. An icon-only tab should always show a tooltip displaying the label on hover. + +## States + +Do not compromise hierarchy by using the same tab variations or orientations. + +It can often be hard to identify the meaning of icon-only tabs. An icon-only tab should always show a tooltip displaying the label on hover. + +## Behaviors + +Do not compromise hierarchy by using the same tab variations or orientations. + +It can often be hard to identify the meaning of icon-only tabs. An icon-only tab should always show a tooltip displaying the label on hover. + +## Usage guidelines + +Do not compromise hierarchy by using the same tab variations or orientations. + +It can often be hard to identify the meaning of icon-only tabs. An icon-only tab should always show a tooltip displaying the label on hover. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Side navigation](/page/side-navigation/) +* [Tree view](/page/tree-view/) diff --git a/docs/s2-docs/components/navigation/tree-view.md b/docs/s2-docs/components/navigation/tree-view.md new file mode 100644 index 00000000..93e49a57 --- /dev/null +++ b/docs/s2-docs/components/navigation/tree-view.md @@ -0,0 +1,169 @@ +--- + +title: "Tree view" +source\_url: +last\_updated: 2026-02-02 +category: components/navigation +component\_type: navigation +status: published +tags: + +* components-navigation + related\_components: +* tabs +* avatar + parent\_category: navigation + +--- + +# Tree view + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| --------------------------------- | ---------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Tree | [view](https://opensource.adobe.com/spectrum-css/?path=/docs/components-tree-view--docs) | +| Spectrum Web Components Not | [available](https://react-spectrum.adobe.com/s2/index.html?path=/docs/treeview--docs) | +| React Spectrum RSP: | [TreeView](https://react-spectrum.adobe.com/s2/index.html?path=/docs/treeview--docs) | + +## Anatomy + +``` +tree view +- header (optional) +- tree view item +- label +- collapse and expand button +- checkbox (optional) +- drag icon (optional) +- context area (optional icon or thumbnail) +- actions area (optional action button or action group) +- in-field progress circle +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------------- | ----------------------------------------------- | ------------- | ----------- | +| size | s / m / l / xl m | – | | +| isDetached | boolean | false | | +| isEmphasized | boolean | false | | +| showDragIcon | boolean | false | | +| selectionMode | single / multiple multiple | – | | +| selectionStyle | checkbox / highlight checkbox | – | | +| selectionBehavior | toggle / replace toggle | – | | +| state | default / hover / down / keyboard focus default | – | | + +## External links + +Tree views display nested, hierarchical content in a collapsible structure. They allow for navigation through multiple levels of grouped information. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +"A tree view offers four sizes: small, medium, large and extra-large. Medium is the default and most common. Use other sizes sparingly to create a visual hierarchy of importance on the page." + +When placed outside a panel, a tree view uses the detached style with rounded corners. Inside a panel, it spans edge to edge by default and does not include rounded corners. + +Tree view items can include a drag icon when needed. The icon serves as a keyboard-navigable indicator for items that support multiple actions. It appears only on hover, active and keyboard focus states. + +The type of selection allowed in a collection can be none, single or multiple. + +Checkbox With checkboxes, both single-select and multi-select views display boxes on the left of each item. Clicking another item adds it to the selection, and clicking a selected item removes it. + +Highlight Use highlight selection when checkboxes add clutter or unnecessary controls. This style shows a highlighted state for selected items, and clicking a new item replaces the previous selection by default. + +All tree views have a hover state, regardless of whether actions or selections can be made. + +Tree views support both single-select and multi-select modes, using either checkbox or highlight styles. In multi-select mode, selecting an item toggles its selection on or off. In single-select mode, selecting an item replaces the current selection. + +Clicking the collapse and expand button will expand or collapse a tree view item that contains child tree view items. + +Tree view items can be dragged and dropped to reorder or restructure the hierarchy, including multiple items at once. Dropping items from different hierarchies into a new location flattens them as sibling children. Tree views should also accept external drops, such as files, to create new items. + +When a tree view item label is too long for the available horizontal space, it truncates. The full label appears in a tooltip on hover or keyboard focus. + +For proper functionality, a parent-level tree view must include a collapse-and-expand button that uses a chevron icon - regardless of its nesting level. This makes the expected behavior clear when users click an item icon. + +When displaying hierarchical information from different sources, use a single tree view with separate sections and headings. Do not cross-reference sources to avoid confusing users. Single and multi-selection should work as expected within one tree view component. + +The root (topmost) level of the hierarchy does not always need to be shown or displayed as a tree view item. If the root provides no useful context, hide it or replace it with a section header. In cases such as mixed tree views, the root can serve as a “Back” button. + +In some cases, users may need to view different hierarchies depending on context. To support this, let users drill into a tree view item to display a different variation of the tree view within the same panel. Use a navigation controller with a “Back” button to let users return to the previous view. + +Choose icons that match the object type represented in the tree view. Icons can be unique to specific data types to help clarify meaning for users. + +Tree view items can display thumbnails instead of icons when users need a content preview. Use icons as a fallback when an image is unavailable, and size them to match the thumbnail. Thumbnails should scale appropriately to the tree view size. For example, an extra-large tree view should not use small thumbnails; in that case, icons may work better. + +One way to manage overflow is to limit how many levels of hierarchy users can create in a tree view. Some products use this approach to reduce the complexity of deeply nested hierarchies. Setting limits helps when a complex hierarchy is unnecessary for the experience. + +When a label is too long to fit in the tree view, it truncates with an ellipsis. Hovering over or focusing on the item reveals a tooltip with the full label text. + +When a tree view hierarchy may extend beyond the available layout space, use an adjustable layout mechanism such as panels or rails. This lets users modify the layout while preserving visibility of the tree view. + +If you have a layout that doesn't allow for users to adjust the width of the container for a tree view, allow them to horizontally scroll in order to see the full depth of the hierarchy. + +When tree views are very large, use a progress circle or a “Show more” control to reveal additional parts when contextually relevant. These loading patterns can apply to the entire tree view or to nested items. + +If system processes are delaying the display of child tree view items when a parent tree view item is expanded, show a clear indication that the items are in the process of loading. + +Users should be able to sort a tree view. Sorting should not affect the hierarchical structure since each layer of the hierarchy is sorted individually. + +Users may need to modify a tree view directly. They should be able to create new parent or child items, such as groups or folders, and flatten the hierarchy at the item level, such as ungrouping layers. In some cases, users should be able to edit item labels directly. + +Any action for modifying the hierarchy should be offered as an explicit control and, if needed, as a keyboard shortcut — but never as a shortcut alone. + +Allow users to enter multiple-selection mode explicitly when keyboard shortcuts such as Shift + click are unavailable or when you need to show a different selection type. Do this by toggling the selection style from highlight to checkbox. + +The checkbox selection style is intended for performing bulk actions on tree view items. Use this option when selection corresponds to bulk actions. + +When you need to provide selection controls within a hierarchy, use a checkbox component instead of the tree view item’s label. This should not correspond to selecting specific content and works best for cases like categorized filtering. + +## States + +Clicking the collapse and expand button will expand or collapse a tree view item that contains child tree view items. + +Choose icons that match the object type represented in the tree view. Icons can be unique to specific data types to help clarify meaning for users. + +The checkbox selection style is intended for performing bulk actions on tree view items. Use this option when selection corresponds to bulk actions. + +## Behaviors + +Clicking the collapse and expand button will expand or collapse a tree view item that contains child tree view items. + +Choose icons that match the object type represented in the tree view. Icons can be unique to specific data types to help clarify meaning for users. + +The checkbox selection style is intended for performing bulk actions on tree view items. Use this option when selection corresponds to bulk actions. + +## Usage guidelines + +Choose icons that match the object type represented in the tree view. Icons can be unique to specific data types to help clarify meaning for users. + +The checkbox selection style is intended for performing bulk actions on tree view items. Use this option when selection corresponds to bulk actions. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Tabs](/page/tabs/) +* [Avatar](/page/avatar/) diff --git a/docs/s2-docs/components/status/avatar-group.md b/docs/s2-docs/components/status/avatar-group.md new file mode 100644 index 00000000..61118be7 --- /dev/null +++ b/docs/s2-docs/components/status/avatar-group.md @@ -0,0 +1,102 @@ +--- + +title: "Avatar group" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* avatar +* badge + parent\_category: status + +--- + +# Avatar group + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) Available by using | [Avatar](https://opensource.adobe.com/spectrum-css/?path=/docs/components-avatar--docs) | +| Spectrum Web Components Available by using | [Avatar](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/avatar--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [AvatarGroup](http://react-spectrum.adobe.com/s2/index.html?path=/docs/avatargroup--docs) | + +## Anatomy + +``` +avatar group +- avatar +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------- | ----------------------------------------- | ------------- | ----------------------------------------------------------------------- | +| label | string | – | Optional text label displayed with the avatar group (e.g., group name). | +| size | 50 / 75 / 100 / 200 / 300 / 400 / 500 100 | – | | + +## External links + +An avatar group displays a set of related avatars together. It’s typically used to represent a collection of people or entities. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Avatar sizes scale exponentially, based on the Spectrum type scale. Avatar has preset sizes to flex across all surfaces and can also be customized to fit appropriately for your context. + +An Avatar group can have an optional text label that clearly describes the group or number of users that it represents. + +Individual avatars inside Avatar group can be navigated using a keyboard. The keyboard focus state adds a focus ring around the avatar. + +Each individual avatar has a stroke applied to better show distinction between individual users in the group. By default, the outline color is a neutral gray, but the stroke color should be adjusted manually to match the background where the avatar group is placed. + +When using a colored background the avatar stroke color should remain set as default for both light and dark themes. + +## States + +Individual avatars inside Avatar group can be navigated using a keyboard. The keyboard focus state adds a focus ring around the avatar. + +When using a colored background the avatar stroke color should remain set as default for both light and dark themes. + +## Behaviors + +Individual avatars inside Avatar group can be navigated using a keyboard. The keyboard focus state adds a focus ring around the avatar. + +When using a colored background the avatar stroke color should remain set as default for both light and dark themes. + +## Usage guidelines + +When using a colored background the avatar stroke color should remain set as default for both light and dark themes. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Avatar](/page/avatar/) +* [Badge](/page/badge/) diff --git a/docs/s2-docs/components/status/avatar.md b/docs/s2-docs/components/status/avatar.md new file mode 100644 index 00000000..ada82503 --- /dev/null +++ b/docs/s2-docs/components/status/avatar.md @@ -0,0 +1,120 @@ +--- + +title: "Avatar" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* tree-view +* avatar-group + parent\_category: status + +--- + +# Avatar + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: | [Avatar](https://opensource.adobe.com/spectrum-css/?path=/docs/components-avatar--docs) | +| Spectrum Web Components SWC: | [Avatar](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/avatar--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [Avatar](https://react-spectrum.adobe.com/s2/index.html?path=/docs/avatar--docs) | + +## Anatomy + +``` +avatar +- container +- user image +- gradient image +- initials +- guest icon +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ----------------------------------------------------------------------------------------------------------- | ------------- | ----------- | +| size | 50 / 75 / 100 / 200 / 300 / 400 / 500 / 600 / 700 / 800 / 900 / 1000 / 1100 / 1200 / 1300 / 1400 / 1500 500 | – | | +| image | user image / gradient image / gradient / guest image / initials user image | – | | +| isDisabled | boolean | false | | +| showStroke | boolean | false | | +| state | default / down / keyboard focus default | – | | + +## External links + +An avatar is a thumbnail representation of an entity, such as a user or an organization. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +An avatar in a disabled state shows that an avatar exists, but is not available or a user is not active in that circumstance. This can be used to maintain layout continuity and communicate that an avatar may become available or active later. + +When used as an individual Avatar, showStroke is false by default. When used in Avatar group, showStroke is true by default to create separation between the stacked group of Avatar components. + +Avatar sizes scale exponentially, based on the Spectrum type scale. Avatar has preset sizes to flex across all surfaces and can also be customized to fit appropriately for your context. + +An avatar has multiple visual styles, depending on the user preference. These show up as branded gradient images, initials of the user’s name, as well as any image that a user uploads. For users who do not have Adobe accounts, they will default to the guest avatar. + +An avatar can be navigated using a keyboard. The keyboard focus state adds a blue ring to the avatar in focus. + +An avatar group displays a set of related avatars together. It’s typically used to represent a collection of people or entities. + +Use branded generic avatars when a user has not set their avatar image. These images are designed to be abstracted from all genders, locales, and cultures. + +The initials avatar is designed to work with latin characters only and supports 1 or 2 characters that are programmatically identified by the first name and last name in a user’s account settings. For users with non-latin characters, their default avatar should be the gradient image style. + +The guest avatar style is designed for users who may be interacting with Adobe products, but are not logged in or do not have an Adobe account. + +## States + +An avatar can be navigated using a keyboard. The keyboard focus state adds a blue ring to the avatar in focus. + +An avatar group displays a set of related avatars together. It’s typically used to represent a collection of people or entities. + +The guest avatar style is designed for users who may be interacting with Adobe products, but are not logged in or do not have an Adobe account. + +## Behaviors + +An avatar can be navigated using a keyboard. The keyboard focus state adds a blue ring to the avatar in focus. + +An avatar group displays a set of related avatars together. It’s typically used to represent a collection of people or entities. + +The guest avatar style is designed for users who may be interacting with Adobe products, but are not logged in or do not have an Adobe account. + +## Usage guidelines + +The guest avatar style is designed for users who may be interacting with Adobe products, but are not logged in or do not have an Adobe account. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Tree view](/page/tree-view/) +* [Avatar group](/page/avatar-group/) diff --git a/docs/s2-docs/components/status/badge.md b/docs/s2-docs/components/status/badge.md new file mode 100644 index 00000000..db864a4b --- /dev/null +++ b/docs/s2-docs/components/status/badge.md @@ -0,0 +1,125 @@ +--- + +title: "Badge" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* avatar-group +* meter + parent\_category: status + +--- + +# Badge + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Badge](https://opensource.adobe.com/spectrum-css/?path=/docs/components-badge--docs) | +| Spectrum Web Components SWC: | [Badge](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/badge--docs\&globals=system:spectrum-two) | +| React Spectrum RSP: | [Badge](https://react-spectrum.adobe.com/s2/index.html?path=/docs/badge--docs) | + +## Anatomy + +``` +badge +- icon +- label +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------- | +| label | string | – | When the label is not defined, the badge appears as icon-only. | +| icon | – | – | | +| variant | neutral / info / positive / negative / indigo / yellow / magenta / fuchsia / purple / seafoam / accent / notice / gray / red / orange / chartreuse / celery / green / cyan / blue / pink / turquoise / brown / cinnamon / silver | – | | +| style | bold / subtle / outline | – | | +| fixed | none / top / right / bottom / left none | – | | +| isDisabled | boolean | false | | +| size | s / m / l / xl s | – | | + +## External links + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +"Badges come in four different sizes: small, medium, large, and extra-large. The small size is the default and most frequently used option. Use the other sizes sparingly to create a hierarchy of importance on a page." + +Badges can be placed as floating in a container, or they can be fixed to any edge of a container. They lose their default corner rounding on the fixed edge. + +"A Badge’s style determines its visual emphasis. Badges come in three different styles: bold, subtle, and outline." + +"When badges have a semantic meaning, they use semantic colors. Use these variants for the following statuses:" + +When badges are for color-coded categories, they use non-semantic colors. Non-semantic variants are ideally used for when there are 8 categories or less. + +A badge can have an optional icon. If no label is used, a badge becomes icon-only and it must include an icon. An icon-only badge is best for very small spaces, and it should always include a tooltip on hover to provide more context for the icon's meaning. + +Badges should always have a label for accessibility and clear comprehension. When the label is not defined, a badge becomes icon-only. + +Badges are display elements, not actions. They should not behave like buttons or links. If an action is required, use a more appropriate component (e.g., Button, Action button). + +When a badge's label is too long for the available horizontal space, it wraps to form another line. If there is no room for a second line of text, the badge should truncate and include a tooltip to expose the full text upon hover. + +Blue badges are easily confused with Spectrum's blue accent buttons. Only use blue badges when absolutely necessary. + +The yellow badge is reserved to communicate "best deal" or "discount" situations only. Do not use the yellow badge for other situations. + +Badges are meant to offer quick context about what category, status, or meaning an item is associated with. If your design requires multiple badges, consider using regular text metadata and reserve a single badge for only the most important status, category, or meaning instead. + +It's best to use a text label on a badge whenever possible because communicating with an icon alone may be unclear or subjective. Reserve icon-only badges for responsive cases, such as for cards in a panel that don't have space for a full badge. In related contexts, pair the icon with a label to help teach a user what the icon means. Icon-only badges should always include a tooltip on hover to show their associated label. + +Badge placement varies widely depending on the use case. In cards, place the badge on the left side of the footer, if possible. If there is no footer or if that space is filled, affix the badge to the right edge of the preview. If there is no preview, affix the badge to the top right corner of the card. + +## States + +Blue badges are easily confused with Spectrum's blue accent buttons. Only use blue badges when absolutely necessary. + +The yellow badge is reserved to communicate "best deal" or "discount" situations only. Do not use the yellow badge for other situations. + +## Behaviors + +Blue badges are easily confused with Spectrum's blue accent buttons. Only use blue badges when absolutely necessary. + +The yellow badge is reserved to communicate "best deal" or "discount" situations only. Do not use the yellow badge for other situations. + +## Usage guidelines + +Blue badges are easily confused with Spectrum's blue accent buttons. Only use blue badges when absolutely necessary. + +The yellow badge is reserved to communicate "best deal" or "discount" situations only. Do not use the yellow badge for other situations. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Avatar group](/page/avatar-group/) +* [Meter](/page/meter/) diff --git a/docs/s2-docs/components/status/meter.md b/docs/s2-docs/components/status/meter.md new file mode 100644 index 00000000..e0bed3a9 --- /dev/null +++ b/docs/s2-docs/components/status/meter.md @@ -0,0 +1,108 @@ +--- + +title: "Meter" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* badge +* progress-bar + parent\_category: status + +--- + +# Meter + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Meter](https://opensource.adobe.com/spectrum-css/?path=/docs/components-meter--docs) | +| Spectrum Web Components SWC: | \[Meter]\( | +| React Spectrum RSP: | [Meter](https://react-spectrum.adobe.com/s2/index.html?path=/docs/meter--docs) | + +## Anatomy + +``` +meter +- label +- value +- track +- fill +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ---------- | ------------------------------------------------------ | ------------- | ----------- | +| variant | informative / positive / notice / negative informative | – | | +| label | string | – | | +| hideLabel | boolean | false | | +| valueLabel | string | – | | +| width | number | – | | +| size | s / m / l / xl m | – | | +| value | number | – | | +| helpText | string | – | | + +## External links + +Meters are visual representations of a quantity or an achievement. Their progress is determined by user actions, rather than system actions. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A meter can include help text below it to explain what the value means and how to reach the target. This text may include units, value ranges, thresholds like targets or warnings, and actions that affect the meter. + +The value represents a user-driven quantity or achievement, such as tutorials completed or storage used. Unlike a progress bar, it reflects user actions, not system activity. + +"Meters come in four different sizes: small, medium, large, and extra-large. By default, meters use medium size. Use the small size when there are multiple meters shown at the same time in a more confined space, such as in tables or cards." + +Meters can include a value label to show details like “60%” or “2 of 8.” It should only appear if the main label is shown and is always placed above the track. + +Meters should always have a label placed above the track. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These meters without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”). + +"Meter has four variants: informative, positive, notice, and negative." + +When the label is too long for the available horizontal space, it wraps to form another line. The value is always shown in full and never wraps or truncates. + +Use the built-in style for showing a label associated with the meter. By default, the label is start-aligned and an optional value is end-aligned above the track. (In left-to-right languages, this means the label appears on the left and the value on the right; in right-to-left languages, this flips.) The label should be written in sentence case. + +Meter variants can be used to represent semantic values by switching variants as the value changes, from positive, to notice, and then to negative. This kind of variant switching should be handled appropriately within the context of your product so that you’re setting accurate expectations for your users about the semantic meaning. + +## States + +## Behaviors + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Badge](/page/badge/) +* [Progress bar](/page/progress-bar/) diff --git a/docs/s2-docs/components/status/progress-bar.md b/docs/s2-docs/components/status/progress-bar.md new file mode 100644 index 00000000..81f5d8c5 --- /dev/null +++ b/docs/s2-docs/components/status/progress-bar.md @@ -0,0 +1,122 @@ +--- + +title: "Progress bar" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* meter +* progress-circle + parent\_category: status + +--- + +# Progress bar + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Progress | [bar](https://opensource.adobe.com/spectrum-css/?path=/docs/components-progress-bar--docs) | +| Spectrum Web Components SWC: Progress | \[Bar]\( | +| React Spectrum RSP: | [ProgressBar](https://react-spectrum.adobe.com/s2/index.html?path=/docs/progressbar--docs) | + +## Anatomy + +``` +progress bar +- label +- value +- track +- fill +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| --------------- | ------------------------------------------------------- | -------------- | ----------- | +| variant | default / over background default | – | | +| staticColor | white – Static color can only be white, otherwise it is | default. | | +| label | string | – | | +| labelPosition | top / side top | – | | +| hideLabel | boolean | false | | +| value | number – Not applicable when | indeterminate. | | +| minValue | number 0 Not applicable when | indeterminate. | | +| maxValue | number 1 Not applicable when | indeterminate. | | +| valueLabel | string | – | | +| width | number | – | | +| size | s / m / l / xl m | – | | +| isIndeterminate | boolean | false | | + +## External links + +"Progress bars show the progression of a system operation: downloading, uploading, processing, etc., in a visual way. They can represent either determinate or indeterminate progress." + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A progress bar can be either determinate or indeterminate. By default, progress bars are determinate. Use a determinate progress bar when progress can be calculated against a specific goal (e.g., downloading a file of a known size). Use an indeterminate progress bar when progress is happening but the time or effort to completion can’t be determined (e.g., attempting to reconnect to a server). + +"Progress bars come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +Progress bars can have a value label that gives detailed information about the progress (e.g. "60%" or "2 of 8"). This value label works alongside the label and should not be displayed if the label itself is not displayed. It should also not be displayed if the progress is indeterminate. Similar to the label, the value label is always placed above the track. + +The value represents progress within the bar’s range, from minimum to maximum. These defaults are 0 and 100 but can be customized. Min and max values don’t apply to indeterminate progress bars. + +The label of the progress bar can be hidden if the context for the progress bar is sufficient without the title — for example, when the progress bar is shown inside a table row and the item is labeled in another column. + +Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited. + +Progress bars should have a label that gives context about the operation being performed. Use an ellipsis at the end of the label text to communicate that the process is in progress. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These progress bars should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”). + +When a progress bar needs to be placed on top of a colored background, use the over background variant. This progress bar uses a static white color regardless of the color theme. Make sure the background offers enough contrast for the progress bar to be legible. + +Use the over background variant when a progress bar needs to be placed on top of a colored background or visual. + +Over background progress bars are available in static black or white, meaning they don’t change with the theme of the page. Use static black on light color or image backgrounds, and white on dark color or image backgrounds. + +The minimum width of a progress bar is 48 px and the maximum width of a progress bar is 768 px, for both desktop and mobile platform scale. Smaller progress bars should only be used in places where it’s not necessary to have a label. + +When the label is too long for the available horizontal space, it wraps to form another line. The value is always shown in full and never wraps or truncates. + +Both progress bars and circles can show either determinate or indeterminate progress. The available space should help determine whether a progress bar or circle is best. Progress bars are preferred in vertically narrow areas such as tables or cards. Use a progress circle for full-page loading or very small areas. Use a progress bar in a loader dialog. + +Use the built-in style to show a label associated with the operation. This style always includes a left-aligned label and a right-aligned percentage value above the track. The label should be in sentence case. Add an ellipsis ("...") at the end to indicate that the action is in progress — for example, "Loading data..." or "Updating settings..." + +## States + +## Behaviors + +## Usage guidelines + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Meter](/page/meter/) +* [Progress circle](/page/progress-circle/) diff --git a/docs/s2-docs/components/status/progress-circle.md b/docs/s2-docs/components/status/progress-circle.md new file mode 100644 index 00000000..754f782e --- /dev/null +++ b/docs/s2-docs/components/status/progress-circle.md @@ -0,0 +1,100 @@ +--- + +title: "Progress circle" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* progress-bar +* status-light + parent\_category: status + +--- + +# Progress circle + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Spectrum CSS (archived) CSS: Progress | [circle](https://opensource.adobe.com/spectrum-css/?path=/docs/components-progress-circle--docs) | +| Spectrum Web Components SWC: Progress | \[Circle]\( | +| React Spectrum RSP: | [ProgressCircle](https://react-spectrum.adobe.com/s2/index.html?path=/docs/progresscircle--docs) | + +## Anatomy + +``` +progress circle +- track +- fill +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| --------------- | --------------------------------- | -------------- | ----------- | +| variant | default / over background default | – | | +| value | number – Not applicable when | indeterminate. | | +| minValue | number 0 Not applicable when | indeterminate. | | +| maxValue | number 1 Not applicable when | indeterminate. | | +| size | s / m / l m | – | | +| isIndeterminate | boolean | false | | + +## External links + +Progress circles show the progression of a system operation such as downloading, uploading, processing, etc. in a visual way. They can represent determinate or indeterminate progress. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Progress circles can be determinate or indeterminate. Use determinate when progress can be measured against a goal, such as downloading a file. Use indeterminate when the duration or effort is unknown, like reconnecting to a server. + +"Progress circles come in 3 sizes: small, medium (default), or large. These are available to fit various contexts. For example, the small progress circle can be used in place of an icon or in tight spaces, while the large one can be used for full-page loading." + +The value represents progress within the circle’s range, from minimum to maximum. These defaults are 0 and 100 but can be customized. Min and max values don’t apply to indeterminate progress circles. + +When a progress circle needs to be placed on top of a colored background, use the over background variant. This progress circle uses a static white color regardless of the color theme. Make sure the background offers enough contrast for the progress circle to be legible. + +Medium and large progress circles are optimized for large areas with no space constraints. Use them for loading content into views (e.g., web pages, panels, etc.) + +Small progress circles are well suited when space is limited both vertically and horizontally, such as in buttons, menu items, and input fields. + +## States + +Small progress circles are well suited when space is limited both vertically and horizontally, such as in buttons, menu items, and input fields. + +## Usage guidelines + +Small progress circles are well suited when space is limited both vertically and horizontally, such as in buttons, menu items, and input fields. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Progress bar](/page/progress-bar/) +* [Status light](/page/status-light/) diff --git a/docs/s2-docs/components/status/status-light.md b/docs/s2-docs/components/status/status-light.md new file mode 100644 index 00000000..0de23827 --- /dev/null +++ b/docs/s2-docs/components/status/status-light.md @@ -0,0 +1,107 @@ +--- + +title: "Status light" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* progress-circle +* steplist + parent\_category: status + +--- + +# Status light + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: Status | [light](https://opensource.adobe.com/spectrum-css/?path=/docs/components-status-light--docs) | +| Spectrum Web Components SWC: | [StatusLight](https://opensource.adobe.com/spectrum-web-components/storybook/?path=/docs/statuslight--docs) | +| React Spectrum RSP: | [StatusLight](https://react-spectrum.adobe.com/s2/index.html?path=/docs/statuslight--docs) | + +## Anatomy + +``` +status light +- label +- dot +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------- | +| label | string | – | | +| variant | informative / neutral / positive / notice / negative / indigo / celery / chartreuse / yellow / magenta / fuchsia / purple / seafoam / pink / turquoise / cinnamon / brown / silver / gray / red / orange / green / cyan informative | – | | +| size | s / m / l / xl m | – | | + +## External links + +Status lights indicate the state or condition of an item. They convey semantic meaning such as statuses and categories. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +Status lights should always include a label. Color alone is not enough to communicate the status. + +"When status lights have a semantic meaning, they use semantic colors. Use these variants for the following statuses:" + +When status lights are used to color code categories and labels that are commonly found in data visualization, they use non-semantic label colors. The ideal usage for these is when there are 8 or fewer categories or labels being color coded. + +"Status lights come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page." + +When the text is too long for the horizontal space available, it wraps to form another line. + +Semantic status lights should never be used for color coding categories or labels, and vice versa. + +A status light should always include a label with text that clearly communicates about the kind of status being shown. Do not change the text color to match the dot. + +## States + +When the text is too long for the horizontal space available, it wraps to form another line. + +Semantic status lights should never be used for color coding categories or labels, and vice versa. + +## Behaviors + +When the text is too long for the horizontal space available, it wraps to form another line. + +Semantic status lights should never be used for color coding categories or labels, and vice versa. + +## Usage guidelines + +Semantic status lights should never be used for color coding categories or labels, and vice versa. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Progress circle](/page/progress-circle/) +* [Steplist](/page/steplist/) diff --git a/docs/s2-docs/components/status/steplist.md b/docs/s2-docs/components/status/steplist.md new file mode 100644 index 00000000..079fb6e7 --- /dev/null +++ b/docs/s2-docs/components/status/steplist.md @@ -0,0 +1,110 @@ +--- + +title: "Steplist" +source\_url: +last\_updated: 2026-02-02 +category: components/status +component\_type: status +status: published +tags: + +* components-status + related\_components: +* status-light +* faqs + parent\_category: status + +--- + +# Steplist + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------- | +| Spectrum CSS (archived) CSS: | [Steplist](https://opensource.adobe.com/spectrum-css/?path=/docs/components-steplist--docs) | + +## Anatomy + +``` +steplist +- step item +- track +- label (optional) +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------- | ------------------------------------------ | ------------- | ----------------------------------------------------- | +| orientation | horizontal / vertical horizontal | – | | +| items | array – An array of step items in the step | list. | | +| currentStep | string | – | The identifier or label of the currently active step. | + +## External links + +Steplists show progress across a series of discrete steps in a process. Use them for setups, wizards, or other flows with a fixed number of stages. They can be displayed horizontally or vertically. + +These options are used in Spectrum’s design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +A current step in a steplist is styled to indicate the user's active position within a sequence. This styling helps orient the user by showing which step they are currently working on or viewing. It typically uses a distinct visual treatment, such as displaying the number of the step, to differentiate it from completed or incomplete steps. This ensures clarity in navigation and reinforces the sense of progress through the workflow. + +Represents an individual step within the steplist. Each item conveys a specific stage in a process or workflow. + +By default, steplists are horizontal and should be used for wider layouts or panels to keep the user’s focus moving from left to right. Vertical steplists should be used for more narrow layouts or panels to accommodate more steps without crowding. + +Users can’t click on incomplete steps. The steplist follows a linear flow, requiring completion of the previous step before moving to the next. + +Completed steps display a checkmark, while remaining steps retain their numeric indicators. The current step uses a darker fill to indicate selection. This treatment is available in medium, large, and extra-large sizes. + +When a step’s label is long for the available horizontal space, it wraps to form another line. + +"Labels are optional in a steplist. Here are three recommended approaches:" + +## States + +Users can’t click on incomplete steps. The steplist follows a linear flow, requiring completion of the previous step before moving to the next. + +When a step’s label is long for the available horizontal space, it wraps to form another line. + +"Labels are optional in a steplist. Here are three recommended approaches:" + +## Behaviors + +Users can’t click on incomplete steps. The steplist follows a linear flow, requiring completion of the previous step before moving to the next. + +When a step’s label is long for the available horizontal space, it wraps to form another line. + +"Labels are optional in a steplist. Here are three recommended approaches:" + +## Usage guidelines + +"Labels are optional in a steplist. Here are three recommended approaches:" + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ------------------ | ------ | ----------------------------------------------------------- | +| November 19, 2025 | 1.1.0 | New guidelines were added to this page. | +| September 15, 2025 | 1.0.0 | This component was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Status light](/page/status-light/) +* [FAQs](/page/faqs/) diff --git a/docs/s2-docs/designing/app-frame-content-area.md b/docs/s2-docs/designing/app-frame-content-area.md new file mode 100644 index 00000000..7000d7af --- /dev/null +++ b/docs/s2-docs/designing/app-frame-content-area.md @@ -0,0 +1,95 @@ +--- + +title: "App frame content area (browsing context)" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* s2-app-frame-side-navigation-browsing-context +* s2-app-frame-creating-bluelines-browsing-context + +--- + +# App frame content area (browsing context) + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +This layout is suitable when all content is related and unified by the primary purpose of the page. This single section can be subdivided using full-width dividers, or by creating visual groupings of content using proximity and spacing. + +Dividers are useful to separate content when using spacing alone wouldn’t be clear enough to mark the boundaries of distinct areas. Generally, more complex content with a varying alignment of objects will benefit the most from using a divider. + +The top section can also be useful to visually indicate that the content is separate and has additional affordances, such as the ability to be minimized. For example, “welcome” type content might be shown in the top section, and recent files might be shown below. + +When using horizontal sections, the page should scroll as a single unit. Consider other ways to minimize the top section if needed, such as through an additional control to show and hide content. + +The top section of a horizontal layout should be reserved for high-attention marketing messages or quick actions, and it should not be scrollable. Put infinite scrolling and longer content in the bottom section. + +This layout is suitable to separate content that’s not semantically related, and if one of the content areas can be minimized. For example, this might apply for onboarding tutorials, or to include an AI assistant. + +This layout is suitable to separate multiple groups of content that aren’t semantically related. For example, this could show several widgets and distinct marketing messages. This layout can also be useful if a user is able to customize the page. + +Make sure to consider smaller breakpoints and decide how content areas should reflow, hide, or combine. In general, show the most important information at the top, and if possible, then progressively disclose the not-as-important information. + +Backgrounds that use gradients are always placed within the app frame intentionally and with a strategic meaning. They should contribute to the visual hierarchy, not distract from it. And, their colors are directly tied to product brand color palettes. + +For example, on a Home screen, gradient backgrounds might call attention to new AI features in the product. On a Learn screen, gradient backgrounds might call attention to tutorials from new creators. On a Files screen, gradient backgrounds might not be used at all in order to focus attention on asset previews. In any context, consider where you want to draw attention and what you want to highlight for the user, what the user’s intentions might be, and how gradient backgrounds may add or detract from the goals of the page. + +While there isn’t an objective scale for each style, it can be helpful to think about backgrounds in terms of how much attention they draw, on a scale of low-to-high. + +While you may have seen past Spectrum 2 explorations showing gradients as the background in header and navigational areas, they should not be used in that context. This is because gradients that appear in the navigation of every page distract from more important information on the page, clash with other imagery, and might not work for some product segments. + +By using gradients in the content areas as backgrounds instead, there’s more flexibility to direct attention to different content and messages, depending on what’s important in the context of that page or workflow. + +Gradients are used to draw attention to important content and features. They can be used in the background of content areas. Using gradients in more than one content area results in multiple areas competing for attention. This is distracting from the task-at-hand workflows on the page. + +Gradients should always be delivered directly from the Spectrum Brand team and used as-is. Do not modify them. + +## Single section + +Gradients should always be delivered directly from the Spectrum Brand team and used as-is. Do not modify them. + +## Horizontal sections + +Gradients should always be delivered directly from the Spectrum Brand team and used as-is. Do not modify them. + +## Vertical sections + +Gradients should always be delivered directly from the Spectrum Brand team and used as-is. Do not modify them. + +## Multiple sections in a grid layout + +Gradients should always be delivered directly from the Spectrum Brand team and used as-is. Do not modify them. + +## App frame usage of gradients + +Gradients should always be delivered directly from the Spectrum Brand team and used as-is. Do not modify them. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ----------------- | ------ | ---------------------------------------------------------------------------------- | +| November 19, 2025 | 2.0.0 | Images converted to light mode. Updated guidance to match latest design decisions. | +| December 10, 2024 | 1.0.0 | This framework was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Browsing context: Side navigation](/page/s2-app-frame-side-navigation-browsing-context/) +* [Creating bluelines](/page/s2-app-frame-creating-bluelines-browsing-context/) diff --git a/docs/s2-docs/designing/app-frame-creating-bluelines.md b/docs/s2-docs/designing/app-frame-creating-bluelines.md new file mode 100644 index 00000000..f42b6fbd --- /dev/null +++ b/docs/s2-docs/designing/app-frame-creating-bluelines.md @@ -0,0 +1,114 @@ +--- + +title: "Creating bluelines (browsing context)" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* s2-app-frame-content-area-browsing-context +* brand + +--- + +# Creating bluelines (browsing context) + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Accessible names vary depending on the content. Accessible names must be defined for controls that don’t have visible text labels. + +"Here are some guidelines to keep in mind as you define accessible names in the app frame:" + +"Any non-text element in a digital interface with a text label must have a text alternative. Here’s an example of how you might name landmark regions in an app frame:" + +"Here’s an example of how you might structure heading annotations for this screen:" + +"Keyboard focus order will depend on what controls are available on the page. Here’s an example of how you might define the order in the app frame:" + +Example of correct usage, support for keyboard focus for size navigation. The side navigation width is focusable and resizable by using the left and right arrow keys. + +Example of correct usage, inclusion of a Skip to main content button within the app frame header. + +When properly supported, the F6 key allows keyboard users to navigate through different regions of an application efficiently. Without this support, keyboard-only users have no means to jump to specific areas of the application, resulting in an excessive number of keystrokes to reach their desired goal. + +"Here are some key quality factors to consider:" + +For mobile breakpoints, a tray is used to open and close the app frame side navigation. In this example, the keyboard focus order starts at the “Create” button and ends at the close button. Clicking on esc should also close the tray. + +## Accessible names + +Accessible names vary depending on the content. Accessible names must be defined for controls that don’t have visible text labels. + +"Here are some guidelines to keep in mind as you define accessible names in the app frame:" + +"Here’s an example of how you might structure heading annotations for this screen:" + +"Keyboard focus order will depend on what controls are available on the page. Here’s an example of how you might define the order in the app frame:" + +Example of correct usage, inclusion of a Skip to main content button within the app frame header. + +"Here are some key quality factors to consider:" + +## Landmark regions + +"Here’s an example of how you might structure heading annotations for this screen:" + +"Keyboard focus order will depend on what controls are available on the page. Here’s an example of how you might define the order in the app frame:" + +Example of correct usage, inclusion of a Skip to main content button within the app frame header. + +"Here are some key quality factors to consider:" + +## Heading annotations + +"Here’s an example of how you might structure heading annotations for this screen:" + +"Keyboard focus order will depend on what controls are available on the page. Here’s an example of how you might define the order in the app frame:" + +Example of correct usage, inclusion of a Skip to main content button within the app frame header. + +"Here are some key quality factors to consider:" + +## Keyboard focus order + +"Keyboard focus order will depend on what controls are available on the page. Here’s an example of how you might define the order in the app frame:" + +Example of correct usage, inclusion of a Skip to main content button within the app frame header. + +"Here are some key quality factors to consider:" + +## Usage guidelines + +Example of correct usage, inclusion of a Skip to main content button within the app frame header. + +"Here are some key quality factors to consider:" + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| November 19, 2025 | 2.0.0 | Images converted to light mode. Updated guidance to match latest design decisions. Added new sections: • Support F6 navigation • Mobile overlay guidance | +| February 10, 2025 | 1.1.0 | Updated side navigation state control to behave as a button, and use the same icon (hamburger menu) for all side navigation states. | +| December 10, 2024 | 1.0.0 | This framework was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Browsing context: Content area](/page/s2-app-frame-content-area-browsing-context/) +* [Brand](/page/brand/) diff --git a/docs/s2-docs/designing/app-frame-header.md b/docs/s2-docs/designing/app-frame-header.md new file mode 100644 index 00000000..1c15fcb5 --- /dev/null +++ b/docs/s2-docs/designing/app-frame-header.md @@ -0,0 +1,128 @@ +--- + +title: "App frame header (browsing context)" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* s2-app-frame +* s2-app-frame-side-navigation-browsing-context + +--- + +# App frame header (browsing context) + +## Resources + +### Design + +* **Figma**: S2 Web + +## Anatomy + +``` +Property Value Default value Description +Property Value Default value Description +hasSideNavigationStateControl boolean false This is required when the side navigation is draggable for accessibility. +hasNavigationItems boolean false If a side nav is present, there should be no navigation items in the header. +hasSearch boolean false - +searchStyle default / minimized default Search can be shown in the default style (expanded) or minimized when there isn't enough space. +hasSkipToMainContentButton boolean false If using this, it appears only on keyboard focus, as the first item in the focus order. +Property Value Default value Description +Property Value Default value Description +hasIcon boolean false - +icon icon - - +label text - A label is required and is also used as the accessible name. +isSelected boolean false Selected items have a different visual style (inverted) in order to sufficiently differentiate from items that are not selected. +isDisabled boolean false Individual header navigation items can be disabled. +hasPopover boolean false Instead of clicking to select the item, a popover is shown instead with additional navigation items. +Property Value Default value Description +Property Value Default value Description +label text Show menu labels / Hide menu labels The label (optional) should be the same as the accessible name (required). +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| ----------------------------- | ------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| hasSideNavigationStateControl | boolean | false | This is required when the side navigation is draggable for accessibility. | +| hasNavigationItems | boolean | false | If a side nav is present, there should be no navigation items in the header. | +| hasSearch | boolean | false | - | +| searchStyle | default / minimized default | Search | can be shown in the default style (expanded) or minimized when there isn't enough space. | +| hasSkipToMainContentButton | boolean | false | If using this, it appears only on keyboard focus, as the first item in the focus order. | +| hasIcon | boolean | false | - | +| icon | icon - | - | | +| label | text - A label is required and is also used as the accessible | name. | | +| isSelected | boolean | false | Selected items have a different visual style (inverted) in order to sufficiently differentiate from items that are not selected. | +| isDisabled | boolean | false | Individual header navigation items can be disabled. | +| hasPopover | boolean | false | Instead of clicking to select the item, a popover is shown instead with additional navigation items. | +| label | text | Show | menu labels / Hide menu labels The label (optional) should be the same as the accessible name (required). | + +## External links + +"There are several parts of the header that are consistent across all Adobe products:" + +Shows a hamburger button on the far left of the header. This controls whether the minimized style of the side navigation (partial/full). + +Shows navigation items in the header. + +Shows a search option in the header. + +Defines the style of the search option that's shown. + +The “skip to main content” button helps improve keyboard navigation by creating a shortcut to the main content of the page. This button is an accessibility feature to allow skipping to the first navigable HTML item. + +Shows an icon to represent the header navigation item. + +The text that is displayed as the label of the header navigation item. + +The text that is displayed as the label of the header navigation item. + +Presents the header side navigation as selected or not selected. + +Changes the header navigation item to the disabled state. + +Shows a chevron next to the label that indicates an additional menu. + +The text that is displayed as the label of the tooltip. + +As a general rule, only use one call-to-action (CTA) button, aside from any buttons used to log in or log out, as defined in the universal nav. When too many CTAs are shown at once, the messages compete for attention and dilute the ability for a focused attention hierarchy. + +If there are multiple actions, consider combining them into a single menu or use other button types. The button should represent the most important CTA across the product; for example, “Share” and “Get desktop app” are common CTAs. + +Diagram with notes about the app frame header in the editing context. If there’s a menu represented by a hamburger icon, such as the application menu in Creative Cloud, it should be shown to the left of the product logo for continuity with the browsing context. The product name can be hidden in the editing context in order to provide more room for other actions. The height of the header should be the same as in the browsing context (56 px). + +## States + +## Usage guidelines + +## Accessibility + +## Notes on the editing context + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| November 19, 2025 | 2.0.0 | Images converted to light mode. Updated guidance to match latest design decisions. Added new sections specific to header: • Component options • States | +| February 10, 2025 | 1.1.0 | Updated side navigation state control to behave as a button, and use the same icon (hamburger menu) for all side navigation states. | +| December 10, 2024 | 1.0.0 | This framework was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [App frame](/page/s2-app-frame/) +* [Browsing context: Side navigation](/page/s2-app-frame-side-navigation-browsing-context/) diff --git a/docs/s2-docs/designing/app-frame-overview.md b/docs/s2-docs/designing/app-frame-overview.md new file mode 100644 index 00000000..11b28380 --- /dev/null +++ b/docs/s2-docs/designing/app-frame-overview.md @@ -0,0 +1,298 @@ +--- + +title: "App frame" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* containers +* s2-app-frame-header-browsing-context + +--- + +# App frame + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +The app frame is the core navigation direction for Spectrum 2. It’s designed as a flexible framework that’s readily adaptable to specific product needs while still creating a shared, predictable experience across products. + +The app frame needs to be opinionated without being restrictive. It directly accounts for the needs of future Spectrum 2 products, and is also flexible enough to be readily adaptable across varying product segment needs. + +A cohesive, consistent app frame reinforces Adobe’s brand and helps users feel comfortable and familiar with our products. Predictable navigation across products is also imperative for Adobe to support users working across multiple applications — and helps people more readily learn how to use new products. + +The app frame is the main stage to showcase the Spectrum 2 style, and it reflects the core foundations and principles of the design system. It works readily with all other design system resources, is committed to complying with WCAG standards, and holds the highest standards for globalization support. + +Spectrum offers a high-level direction as well as a definition of which parts can be flexible and which parts need to be highly predictable. Product teams are then empowered to apply this direction in ways that make the most sense for their use cases and users. + +Zones are the general areas into which certain types of actions should go. They’re not specific to components. + +This is a general area that contains global actions, such as view actions (e.g., layout and zoom options) and supplemental features (e.g., AI Assistants). Actions here can be shown in different ways, such as using part of the content area to show actions in the header, or in a dedicated side rail. There is no single visual representation of how actions should look in this area. + +This area is reserved for transient actions that are contextual to content on the page (e.g., an action bar). + +Parts of the anatomy have defined rules and behaviors. The terms used here to describe the anatomy of the app framework are for internal alignment only, and are not representative of how these parts of the app frame should be described to end users. + +In the S2 app frame, gradients are only used as backgrounds in content areas — they are not used in the header (A) and navigational areas (B). This allows for greater flexibility between pages where gradients may be calling attention to different kinds of content. + +"There are two variants of the side navigation state control: hamburger and panel. They should never be used at the same time." + +Interacting with this icon in the header will either fully expand and collapse, or partially collapse, the panel. + +When hovering on the panel icon, the icon will show an animated preview of what action would be done upon interaction (either expanding or collapsing). This animation offers more context about what to expect. The placement of the panel icon is at the bottom of the app frame side navigation panel. + +To activate or deactivate the TAB, select the 9-grid icon. Once clicked on, the TAB will appear above the header. On a screen reader, if there is an alert banner present, then the visual placement from top to bottom would be alert banner, TAB, then header. + +The placement and appearance of the TAB icon may differ across Adobe products. Not all products will utilize the TAB. The currently supported products are Adobe Home, Firefly, Express, Photoshop, Lightroom, and Acrobat. + +For products that use the TAB, the side navigation state control (panel icon) will be at the bottom of the side navigation. For mobile experiences, the side navigation state control (hamburger icon) and product switcher will be in the header. + +The following are some common terms used at Adobe for describing the core UI elements that make up the app frame, along with some notable usage considerations. Consider this as a starting point for you to take and develop into working language that may need to be more contextual for your product. Work with your Content Strategy partners to adapt it to your needs. + +The word “content” is general in theory but specific in application. In general, it’s a catch-all word for something that is contained in a designated space, and communicates meaning or intention. Specific to the context of the app frame, it describes that what goes into this area is at the discretion of a given situation or user experience. + +"This is a commonly used internal term, but is not recommended for describing the interface to an end user. This is because it relies upon a visual metaphor to mimic an analog concept: something that “sinks” into a UI plane, like a water well sinks into the surface of the ground." + +"Internal jargon is important and we want to be aligned across teams, but we also need to be careful about using internal terms, externally. By “user-facing term,” we mean that user to be the “end user”: the person who encounters the UI of an Adobe experience." + +"In general, if you’re creating resources for internal usage (such as design guidelines or specs), you can safely use internal jargon. If you’re creating actual product UI, you will need to ensure that you’re using the appropriate terms that will help your user best understand and navigate the interface. Use the following steps to decide on terms:" + +What's the context — the workflow or scenario — for where a term will appear? That will help you determine who you’re speaking to, with what language. + +"Different deliverables will each have their own audience. For example:" + +Are you creating something for internal builders (designers, engineers, anyone creating products) at Adobe? Or are you creating something for an external user? + +Be specific about who you’re speaking to. If you're speaking to an internal audience looking at design direction for how to build UI, that’s a different audience from the users who will ultimately work with the UI. + +Will the term appear as a UI string (such as the title of a panel)? Would it appear as a label in an image that shows the anatomy of different parts of the component? + +The main focus for most users is on the content — the information being shown, and the actions to select from — rather than where or the means by which the action is contained. + +This app framework intentionally uses the anatomy term “content area” to describe the main information or main focus in a given view, because it’s a flexible area that’s contextual to the main view of a given place in a user’s workflow. + +"To create more inclusive products, describe parts of the UI in terms of function (what something does, or what something is) rather than appearance or position (such as relative direction: left, right, top, bottom)." + +Describe the actions or items available. + +Avoid describing where to find specific items or actions in relation to UI construction. + +The word panel is acceptable as a user-facing term only when there is no other way to describe the interface. + +"The word rail is acceptable to use as internal jargon, but it should never be used as a user-facing term. This is because the word is about how something looks: a long, straight divider, like a slide rule or a railroad track." + +Show more options + +Describe the action to take on the UI. + +Hide navigation rail + +Don’t describe the UI itself. + +"“Show” and “hide” are the preferred terms to use to describe the open/close actions on the side navigation. This is for several reasons:" + +As you’re designing the UI content of your app frame using this framework, follow the Spectrum content standards for all UI text and labels. + +All templates + +"Most of the components that will go into your app frame design have their own associated content standards:" + +## Framework principles + +Zones are the general areas into which certain types of actions should go. They’re not specific to components. + +This area is reserved for transient actions that are contextual to content on the page (e.g., an action bar). + +"There are two variants of the side navigation state control: hamburger and panel. They should never be used at the same time." + +Interacting with this icon in the header will either fully expand and collapse, or partially collapse, the panel. + +What's the context — the workflow or scenario — for where a term will appear? That will help you determine who you’re speaking to, with what language. + +"Different deliverables will each have their own audience. For example:" + +Describe the actions or items available. + +Avoid describing where to find specific items or actions in relation to UI construction. + +The word panel is acceptable as a user-facing term only when there is no other way to describe the interface. + +Show more options + +Describe the action to take on the UI. + +Hide navigation rail + +Don’t describe the UI itself. + +"“Show” and “hide” are the preferred terms to use to describe the open/close actions on the side navigation. This is for several reasons:" + +As you’re designing the UI content of your app frame using this framework, follow the Spectrum content standards for all UI text and labels. + +All templates + +"Most of the components that will go into your app frame design have their own associated content standards:" + +## What’s here, and what’s to come + +Zones are the general areas into which certain types of actions should go. They’re not specific to components. + +This area is reserved for transient actions that are contextual to content on the page (e.g., an action bar). + +"There are two variants of the side navigation state control: hamburger and panel. They should never be used at the same time." + +Interacting with this icon in the header will either fully expand and collapse, or partially collapse, the panel. + +What's the context — the workflow or scenario — for where a term will appear? That will help you determine who you’re speaking to, with what language. + +"Different deliverables will each have their own audience. For example:" + +Describe the actions or items available. + +Avoid describing where to find specific items or actions in relation to UI construction. + +The word panel is acceptable as a user-facing term only when there is no other way to describe the interface. + +Show more options + +Describe the action to take on the UI. + +Hide navigation rail + +Don’t describe the UI itself. + +"“Show” and “hide” are the preferred terms to use to describe the open/close actions on the side navigation. This is for several reasons:" + +As you’re designing the UI content of your app frame using this framework, follow the Spectrum content standards for all UI text and labels. + +All templates + +"Most of the components that will go into your app frame design have their own associated content standards:" + +## App frame construction + +Zones are the general areas into which certain types of actions should go. They’re not specific to components. + +This area is reserved for transient actions that are contextual to content on the page (e.g., an action bar). + +"There are two variants of the side navigation state control: hamburger and panel. They should never be used at the same time." + +Interacting with this icon in the header will either fully expand and collapse, or partially collapse, the panel. + +What's the context — the workflow or scenario — for where a term will appear? That will help you determine who you’re speaking to, with what language. + +"Different deliverables will each have their own audience. For example:" + +Describe the actions or items available. + +Avoid describing where to find specific items or actions in relation to UI construction. + +The word panel is acceptable as a user-facing term only when there is no other way to describe the interface. + +Show more options + +Describe the action to take on the UI. + +Hide navigation rail + +Don’t describe the UI itself. + +"“Show” and “hide” are the preferred terms to use to describe the open/close actions on the side navigation. This is for several reasons:" + +As you’re designing the UI content of your app frame using this framework, follow the Spectrum content standards for all UI text and labels. + +All templates + +"Most of the components that will go into your app frame design have their own associated content standards:" + +## Side navigation state control + +"There are two variants of the side navigation state control: hamburger and panel. They should never be used at the same time." + +Interacting with this icon in the header will either fully expand and collapse, or partially collapse, the panel. + +What's the context — the workflow or scenario — for where a term will appear? That will help you determine who you’re speaking to, with what language. + +"Different deliverables will each have their own audience. For example:" + +Describe the actions or items available. + +Avoid describing where to find specific items or actions in relation to UI construction. + +The word panel is acceptable as a user-facing term only when there is no other way to describe the interface. + +Show more options + +Describe the action to take on the UI. + +Hide navigation rail + +Don’t describe the UI itself. + +"“Show” and “hide” are the preferred terms to use to describe the open/close actions on the side navigation. This is for several reasons:" + +As you’re designing the UI content of your app frame using this framework, follow the Spectrum content standards for all UI text and labels. + +All templates + +"Most of the components that will go into your app frame design have their own associated content standards:" + +## App frame variants: Top App Bar (TAB) + +## Terminology and content standards + +What's the context — the workflow or scenario — for where a term will appear? That will help you determine who you’re speaking to, with what language. + +"Different deliverables will each have their own audience. For example:" + +Describe the actions or items available. + +Avoid describing where to find specific items or actions in relation to UI construction. + +The word panel is acceptable as a user-facing term only when there is no other way to describe the interface. + +Show more options + +Describe the action to take on the UI. + +Hide navigation rail + +Don’t describe the UI itself. + +"“Show” and “hide” are the preferred terms to use to describe the open/close actions on the side navigation. This is for several reasons:" + +As you’re designing the UI content of your app frame using this framework, follow the Spectrum content standards for all UI text and labels. + +All templates + +"Most of the components that will go into your app frame design have their own associated content standards:" + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| November 19, 2025 | 2.0.0 | Images converted to light mode. Updated guidance to match latest design decisions. Added new sections: • Side navigation state control • App frame variants: Top App Bar (TAB) | +| February 10, 2025 | 1.1.0 | Updated side navigation state control to behave as a button, and use the same icon (hamburger menu) for all side navigation states. | +| December 10, 2024 | 1.0.0 | This framework was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Containers](/page/containers/) +* [Browsing context: Header](/page/s2-app-frame-header-browsing-context/) diff --git a/docs/s2-docs/designing/app-frame-side-navigation.md b/docs/s2-docs/designing/app-frame-side-navigation.md new file mode 100644 index 00000000..17019b65 --- /dev/null +++ b/docs/s2-docs/designing/app-frame-side-navigation.md @@ -0,0 +1,172 @@ +--- + +title: "App frame side navigation (browsing context)" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* s2-app-frame-header-browsing-context +* s2-app-frame-content-area-browsing-context + +--- + +# App frame side navigation (browsing context) + +## Resources + +### Design + +* **Figma**: S2 Web + +### Implementations + +| Platform | Link | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Spectrum Web Components UEC: | [Sidenav](https://git.corp.adobe.com/pages/Spectrum/unified-experience-components/main/storybook/index.html?path=/story/labs-sidenav--default\&globals=system:spectrum-two) | + +## Anatomy + +``` +Property Value Default value Description +Property Value Default value Description +minimized boolean false If the side navigation can be minimized, the app frame side navigation control must be present. +minimizedStyle partial / full partial Use a partial style when users still need access to navigation items when the navigation is minimized. The panel supports expanded and partially minimized, or expanded and fully minimized states, not all three. +hasCreateButton boolean false This is an instance of the button component specific to only app frame. +isResizable boolean false Resizing is primarily useful when there is user-generated content in the side navigation. Otherwise, the default expanded and minimized states are sufficient. +dragToMinimize boolean false - +minWidth (expanded) number 160px If drag to collapse is enabled, this is the minimum width at which the side navigation will be minimized. +defaultWdth (expanded) auto / number auto The default panel width should auto-adjust to the longest string in the navigation in order to accommodate all translations. +Property Value Default value Description +Property Value Default value Description +icon icon - An icon is required in order to identify the side navigation item for the first level. +label text - A label is required and is also used as the accessible name. +hideLabel boolean false If the label is hidden, the label will appear in the tooltip on hover. If the side navigation panel supports behavior to minimize and expand, it will override this option. +labelTruncation one line / two lines / none two lines The default value works for most cases based on Spectrum's recommended string length in English (in U.S. English, which is the source locale). However, this should be validated on a case-by-case basis, depending on the label. In general, labels should not be so long that they require truncation. +isSelected boolean false Selected items have a different visual style (inverted) in order to sufficiently differentiate from items that are not selected. +isDisabled boolean false Individual side navigation items can be disabled. +Property Value Default value Description +Property Value Default value Description +label text Show menu labels / Hide menu labels The label (optional) should be the same as the accessible name (required). +``` + +## Component options + +These options are used in Spectrum's design data JSON. There may be additional or slightly different options that are available for this component in Figma and in Spectrum implementations. This is being continuously updated. + +| Property | Value | Default value | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| minimized | boolean | false | If the side navigation can be minimized, the app frame side navigation control must be present. | +| minimizedStyle | partial / full partial | Use | a partial style when users still need access to navigation items when the navigation is minimized. The panel supports expanded and partially minimized, or expanded and fully minimized states, not all three. | +| hasCreateButton | boolean | false | This is an instance of the button component specific to only app frame. | +| isResizable | boolean | false | Resizing is primarily useful when there is user-generated content in the side navigation. Otherwise, the default expanded and minimized states are sufficient. | +| dragToMinimize | boolean | false | - | +| minWidth | (expanded) number 160px If drag to collapse is enabled, this is the minimum width at which the side navigation will be | minimized. | | +| defaultWdth | (expanded) auto / number auto | The | default panel width should auto-adjust to the longest string in the navigation in order to accommodate all translations. | +| icon | icon - An icon is required in order to identify the side navigation item for the first | level. | | +| label | text - A label is required and is also used as the accessible | name. | | +| hideLabel | boolean | false | If the label is hidden, the label will appear in the tooltip on hover. If the side navigation panel supports behavior to minimize and expand, it will override this option. | +| labelTruncation | one line / two lines / none two lines | The | default value works for most cases based on Spectrum's recommended string length in English (in U.S. English, which is the source locale). However, this should be validated on a case-by-case basis, depending on the label. In general, labels should not be so long that they require truncation. | +| isSelected | boolean | false | Selected items have a different visual style (inverted) in order to sufficiently differentiate from items that are not selected. | +| isDisabled | boolean | false | Individual side navigation items can be disabled. | +| label | text | Show | menu labels / Hide menu labels The label (optional) should be the same as the accessible name (required). | + +## External links + +The side navigation is always used in partnership with the header, and never instead of it. When used, the side navigation holds the main categories of product functionality, such as workflow-related navigational items (e.g., Home, Files, Learn, Dashboards). Don’t use this for categorizing marketing pages. + +"Side navigation consists of a few parts:" + +Additionally, this button should not be used outside of the app frame context. It has unique animations between expanding and collapsing that are optimized for the app frame side navigation panel. + +Allows the side navigation to be minimized by the user. + +The partial style displays icon-only side navigation items when minimized. The full style hides the side navigation when minimized. + +Shows a create button at the top of the panel. + +Enables drag on the side navigation. + +"If the side navigation panel can be minimized (Can be minimized: true), dragging to the min width (expanded) will collapse the side navigation into the minimized state." + +The minimum width that the side navigation panel can be adjusted to. + +The default width that the side navigation panel appears in. + +The text that is displayed as the label of the app frame side navigation item, to supplement the icon. + +Hides the label, making the app frame side navigation item icon-only. + +The number of lines that is shown before the label is truncated. + +After the user clicks on an app frame side navigation item, the left visual bar will turn gray-800, text will bold, and color will change to content-neutral. + +Changes the side navigation item to the disabled state. + +The text that is displayed as the label of the tooltip. + +"Use the overlay variant of the app frame: side navigation (browsing) component for smaller breakpoints. The overlay is triggered via the hamburger menu in the header (rather than a touchpoint at the bottom)." + +Although 768 px is the recommended breakpoint to begin displaying the overlay designs, each product team should determine which breakpoint best suits their needs. + +The divider at the bottom of the side navigation is an intentional visual element that separates overflow side navigation items and end section items from the state control icon. + +The end section is optional and used to contain navigation items in a separate category that is secondary to the main navigation items. Categories, when defined, should readily communicate a clear purpose and be meaningful to users. Items placed here sit on a separate area. When resized to a smaller height, the items should append onto the start section and scroll together. + +"The minimum width is customizable, depending on the number of levels:" + +If the side navigation contains user-generated content (like shortcuts to folders and files), enabling resizing can be a good way to improve usability by respecting user content, without needing to predict the length of labels that users might input. + +Along with being descriptive, the labels of navigation items should be succinct. Keep navigation strings to 1 or 2 and no more than 3 concise words (in U.S. English, which is the source locale). Reduce any unnecessary words in order to ensure simplicity. + +Navigation items should never be so long that they require truncation, except in instances where navigation is user-generated (e.g., folder and file names). + +If possible, the default width should auto-adjust to the longest string in the navigation in order to accommodate all translations. As a last resort for long strings, specific line breaks can be built into the implementation. These line breaks depend on the content, and requires manual handling by Globalization engineers. + +When navigation items are shown in both the side navigation and header at the same time, the hierarchy and relationships between them become unclear. If the side navigation is used, don’t put any navigation items in the header. + +Supporting multiple states (default, and partial or fully minimized style) provides users with the option to choose their preferred layout based on their own preferences. In user studies, individual preference is the biggest factor when it comes to whether or not people want to view labels by default. + +If supporting multiple states, consider showing the side navigation in the expanded state by default, and preserve user preferences across pages and sessions. If minimizing the side navigation is not supported, show the side navigation in the expanded state. Showing labels by default increases recognition and familiarity. + +There are some app frame-specific constraints for the side navigation. Icons are required at the parent level. Nested items can have no icon, but the parent level must have an icon. + +"Diagram describing notes about the side navigation for the app frame, in the editing context. While toolbars share the same location as the app frame side navigation in a browsing context, toolbars in an editing context serve a different purpose: to readily select commonly used tools, rather than to navigate between pages. The behavior and interaction of toolbars doesn’t need to mirror the side navigation and should instead best serve user needs in an editing context. For example, the option to show and hide tool labels can be an additional customization option and doesn’t need to be controlled by the hamburger menu, which is used to display the application menu in Creative Cloud." + +## States + +"The minimum width is customizable, depending on the number of levels:" + +## Behaviors + +"The minimum width is customizable, depending on the number of levels:" + +## Usage guidelines + +## Accessibility + +## Notes on the editing context + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Changelog + +| Date | Number | Notes | +| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| November 19, 2025 | 2.0.0 | Images converted to light mode. Updated guidance to match latest design decisions. Added new sections specific to side navigation: • Mobile overlay guidance • End section divider • Minimum width • Component options • States | +| February 10, 2025 | 1.1.0 | - | +| December 10, 2024 | 1.0.0 | This framework was added to the Spectrum 2 guidelines site. | + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Browsing context: Header](/page/s2-app-frame-header-browsing-context/) +* [Browsing context: Content area](/page/s2-app-frame-content-area-browsing-context/) diff --git a/docs/s2-docs/designing/attention-hierarchy.md b/docs/s2-docs/designing/attention-hierarchy.md new file mode 100644 index 00000000..50b37c6b --- /dev/null +++ b/docs/s2-docs/designing/attention-hierarchy.md @@ -0,0 +1,34 @@ +--- + +title: "Attention hierarchy" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + +--- + +# Attention hierarchy + +## About this concept + +Design systems are ultimately communication systems. A main goal of any kind of UI communication — visual, linguistic, motion, and more — is to convey a message in a way that the audience can readily understand what they need to know and why it matters. And most importantly, communication needs to be respectful of user attention. + +**Attention hierarchy** is a core concept in Spectrum 2. This idea has always been a part of Spectrum as a design system — and a tenet of responsible UX design as a whole — but it's now more formalized as a way to validate assumptions using clear guidelines and considerations. It's based on the methods of typographic hierarchy, where scale, size, and text pairings help readers to readily recognize what's the most broad and important information to the most detailed and nice-to-know information. We've extended this practice beyond just text and into all the ways that UI communicates. + +Another way to think of attention hierarchy is as a way to manage the ratio of signal-to-noise in an experience. Different parts of the UI all communicate meaning, at different levels of attention. High attention elements show a primary area of focus, and communicate timely, high-signal meanings. Low attention elements blend into the background, and communicate more utilitarian, lower-priority meanings. Things like object styles, component options, and typography all draw different levels of attention. + +## Working with attention hierarchy + +High attention elements should be used sparingly and selectively. If too many things are high attention at once, the experience becomes noisy and unfocused. For example, both high-contrast colors and elevation communicate specific meanings and add emphasis within pages and flows — and these are both used very thoughtfully. + +## Example + +As a general rule, only one element or group of elements should have high attention on a page. Too many elements drawing high attention makes it difficult to focus. + +**Good example:** The "Share" button is the most timely and high-impact action to take in this example. It's high attention because the next step after finishing creating something within the canvas would be to share it. + +**Bad example:** The "Share" button is competing with the selected states of items in the navigation. These navigational items are still important for communicating wayfinding and context, but are not as timely as the action of sharing. diff --git a/docs/s2-docs/designing/background-layers.md b/docs/s2-docs/designing/background-layers.md new file mode 100644 index 00000000..004137e7 --- /dev/null +++ b/docs/s2-docs/designing/background-layers.md @@ -0,0 +1,60 @@ +--- + +title: "Background layers" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* colors +* typography-fundamentals + +--- + +# Background layers + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Layer 2 is the color of the canvas. This background layer color can also be used in both professional and lightweight editing applications, in the app frame, to put it on the same dimension as the primary content. + +Layer 1 can be used as the app frame color in professional editing applications, which require additional depth differentiation. + +The pasteboard has a dedicated background layer. This is because no components are placed directly on top of it, with the exception of an artboard (which uses a white background color). Other components should be placed on a layer 1, layer 2, or elevated background. + +This example shows an editing application using background layer 2 for both the artboard and the app frame. An elevated background is used for a floating toolbar, which appears on top of the canvas. + +Spectrum 2 uses gray-25 as the base background color to draw attention to the primary content of a page. Using gray-25 allows for higher contrast between the background and content, and it provides a blank canvas for more vibrant colors. + +In dark theme, the primary background (using the background base layer) is the darkest color. This allows for more flexibility for the grays that are layered on top of it, and provides contrast for more vibrant user-created content. + +## Overview + +Layer 1 can be used as the app frame color in professional editing applications, which require additional depth differentiation. + +## Editing contexts + +Layer 1 can be used as the app frame color in professional editing applications, which require additional depth differentiation. + +## Browsing contexts + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Colors](/page/colors/) +* [Fundamentals](/page/typography-fundamentals/) diff --git a/docs/s2-docs/designing/brand.md b/docs/s2-docs/designing/brand.md new file mode 100644 index 00000000..9e7b8caa --- /dev/null +++ b/docs/s2-docs/designing/brand.md @@ -0,0 +1,86 @@ +--- + +title: "Brand" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + +--- + +# Brand + +Brand considerations are significantly interwoven into Spectrum 2. What's covered here is primarily focused on **in-app UI** considerations. Please note that what's here is still in progress, and we'll update these guidelines with more details over time. Check the release notes ([#spectrum-bulletin](https://adobe.slack.com/archives/C7N4YET0R)) for announcements about updates, or post questions in [#product-branding](https://adobe.slack.com/archives/CTVNUS39T). + +## Brand assets + +There are a number of key assets that are used systematically across interfaces. + +### Product logos, app icons, and lockups + +A product logo or tile color does not change, even if the background is dark. One-color product logos are for usage as workflow icons. You can find app icons within the [App Icons library](https://www.figma.com/file/8or0zCnGc5fiTnQ1NeIRnh/Product-App-icons?type=design\&node-id=501%3A685\&mode=design\&t=BCgDXidUN5VZiBwu-1). + +### Loading screens + +Loading screens include desktop splash screens, mobile loading screens, and web loaders. + +Desktop splash screens celebrate artwork from the Adobe community and are updated at least once a year. All desktop products that have a loading time of longer than 2 seconds, or don't open instantaneously, are required to have a splash screen. This is so a user can understand that there's a loading process happening. + +Follow OS-specific conventions for mobile loading screens. View more information about using [Android loading screens](https://wiki.corp.adobe.com/display/AdobeDesign/Android+Launch+Screens). + +### File type and folder illustrations + +On desktop, product folder icons are branded to help users find any product-related settings. For web and mobile, folders use Spectrum colors to fit better in the experience. + +Primary file types always utilize brand colors, since they're often file formats proprietary to the product (for example, PSD to Photoshop, or AEP to AE). Secondary filetypes are shared across many products, so they take a neutral palette using Spectrum 1 colors. + +The Brand team creates desktop versions of these icons in ICNS (for Mac) and ICO (for Windows) files, while web versions are delivered most often as SVGs. Desktop folders and file types can be found on the [Brand wiki](https://wiki.corp.adobe.com/pages/viewpage.action?spaceKey=AdobeDesign\&title=Adobe+Design+Brand) under individual product delivery pages. View [web folders and file types](https://wiki.corp.adobe.com/pages/viewpage.action?pageId=1994851879). + +## Color + +Color has historically been an extremely important part of Adobe's brand. Bringing more color into Spectrum 2 lets product experiences draw a much closer connection to marketing materials and product branding. + +Spectrum's [6.0.0 color system](https://spectrum.corp.adobe.com/page/color-system/) didn't throughly incorporate the Adobe brand colors, even though in-product UI colors are so close to them in both hue and saturation. With the colors for Spectrum 2, we've made [some shifts to ensure that brand colors are better represented](https://s2.spectrum.corp.adobe.com/page/colors/#better-inclusion-of-brand-colors) throughout product experiences. + +Brand colors used outside of in-product illustrations and splash imagery may differ slightly from the Spectrum 2 colors. + +Along with Adobe's primary brand color palette (red, black, grey, and white), there's also an extended color palette that brings a modern and bold personality to the Adobe brand. These colors are the starting point for graphics, diagrams and icons, illustrations, and backgrounds — and there are additional considerations for colors in Creative Cloud, Document Cloud, Experience Cloud, and Adobe Express for Spectrum 2 experiences. + +### Creative Cloud + +Creative Cloud uses Adobe red and six product-specific colors, each with corresponding light and dark values. + +### Document Cloud + +Document Cloud's colors align to Spectrum. There's three primary product colors plus Adobe red, as well as six secondary colors. + +### Experience Cloud + +Experience Cloud's colors align to Spectrum. The foundational apps use cool colors, while the functional apps use warm colors. + +### Adobe Express + +Adobe Express uses three colors. Indigo is used for a fill accent color and for highlighting main metaphors. Spectrum gray is the main stroke color. + +## Gradients + +Gradients are a significant characteristic of Spectrum 2 and a very noticeable part of how the Adobe brand is expressed in UI contexts. They help communicate product differentiation across our brand portfolio, and also allow for individual products to have a wider range of expression. Both of these aspects heavily contribute to the bolder, more colorful visual language of Spectrum 2. + +Because gradients are very expressive, they're always placed intentionally and with a strategic meaning. **They should not distract from the main content in an experience.** They're only used in specific areas in order to create a system, feature the product brand, and support visual hierarchy. And, their colors are directly tied to product brand color palettes. + +### Premium and Generative AI gradients + +\[See embedded content on website] + +## Usage guidelines + +### Request assets from the Brand team + +Brand considerations are highly strategic, and coherence is a priority. Don't make your own illustrations, colors, gradients, logos, or other assets. The Brand team will work with you to create assets that align to your product's strategy and timing. + +Any new Spectrum 2 assets must be requested directly from the Brand team. It's very important that you do not create your own. + +To view existing S2 Illustrations, visit the [S2 / Illustrations library](https://www.figma.com/design/xGhSI7y1ewp2fEiX5eNOKv/S2-%2F-Illustrations?node-id=1508-8563\&t=T5G2KGbuUHuqGUnA-0) in Figma. If you need a new illustration, [make a request using Workfront](https://experience.adobe.com/#/@wfadoberm/so:adoberm-Production/workfront/requests/new?activeTab=tab-new-helpRequest\&projectID=6780593b001a3fa9fe20195fcec6c39a\&path=). diff --git a/docs/s2-docs/designing/colors.md b/docs/s2-docs/designing/colors.md new file mode 100644 index 00000000..c83ef83d --- /dev/null +++ b/docs/s2-docs/designing/colors.md @@ -0,0 +1,74 @@ +--- + +title: "Colors" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing +* design-tokens +* color + related\_components: +* grays +* background-layers + +--- + +# Colors + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +This update to the color palette improves how colors appear on the solid white primary background, includes brand colors in the palette, and makes our data visualization colors more color vision deficiency-safe. + +The 6.0.0 color system didn’t account for any Adobe product brand colors, despite the colors being so close in hue and saturation. With the Spectrum 2 color update, we’ve shifted some previous colors to be able to include brand colors in the new palette. + +The Leonardo tool generated the color palette by using several key colors, including brand colors. Most color scales are not a single hue key color. Leonardo tends to darken and lighten on either end of the gradient by adding black and white to the key colors, so some are included to ensure a high degree of saturation in the palette. In other cases, some key colors shift the actual hue in order to keep colors bright or recognizable, or shift them to help most users avoid confusion with adjacent colors. + +Once the color scale is determined, lightness stops are input for each color in order to get aliased colors. + +Brand colors are used to generate the Spectrum colors, but brand colors aren’t used one-to-one in the Spectrum palette. Branding is not strictly tied to using Spectrum colors, despite this alignment for Spectrum 2. + +In Spectrum 2, colors have shifted blue to be more indigo. This is so we can continue using “blue” aliases but can have an updated, more approachable blue hue that leans more indigo. Moving forward, all products will use blue for the informative and accent semantics. This will help better unify all of Adobe’s products, including Adobe Express. + +This change works nicely with the new integration with brand colors. For example, Photoshop’s blue is somewhere in between the current Spectrum blue and cyan. Pushing blue to be more indigo creates space for cyan to lean more blue and accommodate Photoshop’s blue. Similarly, pushing blue more indigo also means pushing indigo to be more purple, which allows for After Effect’s purple to fit nicely in the new indigo range. + +The lightest shades of yellow and chartreuse were extra-saturated in Spectrum 6.0.0 colors, despite being the same 1.08:1 contrast with all the other colors. The Spectrum 2 update for colors desaturates these shades to keep them more uniform in style. + +Spectrum 2 now uses solid white as the primary background for light UI. There’s also new variants of components, like the in-line alert, that use color-100 as the background. Having this lighter background introduced the need for a lighter shade for components, so the contrast of the lightest value (color-100) was lowered from 1.08:1 to 1.06:1. + +We also needed a couple of darker shades to work for our data visualization palettes (available soon). + +The color update for Spectrum 2 also aimed to fix some general issues with the previous color palette. Colors have become brighter and more saturated, contrast has been lightened where possible, and some shades like orange, yellow, and chartreuse have been fixed to appear less muddy. + +## Overview + +Once the color scale is determined, lightness stops are input for each color in order to get aliased colors. + +We also needed a couple of darker shades to work for our data visualization palettes (available soon). + +## Improvements to the current color system + +Once the color scale is determined, lightness stops are input for each color in order to get aliased colors. + +We also needed a couple of darker shades to work for our data visualization palettes (available soon). + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Grays](/page/grays/) +* [Background layers](/page/background-layers/) diff --git a/docs/s2-docs/designing/containers.md b/docs/s2-docs/designing/containers.md new file mode 100644 index 00000000..2ccd6f4a --- /dev/null +++ b/docs/s2-docs/designing/containers.md @@ -0,0 +1,106 @@ +--- + +title: "Containers" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* states +* s2-app-frame + +--- + +# Containers + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Containers separate concepts with distinct purposes. + +In Spectrum 2, containers have more defined rules to help guide in the creation of custom containers for product-specific contexts. Containers are used across Spectrum 2 interfaces in multiple ways, but the commonality they share is that they group related concepts together into distinct areas. Some usages of containers have more detailed guidelines. + +For example, a card uses a container and inherits its properties, but it can only represent a distinct object (such as an individual asset or product). A block of marketing material containing multiple concepts (like subscription information plus actions to take) is grouped together in a container, but is not considered a card. Whether broad or specific, a user should be able to readily tell the purpose of a container. + +"Examples of containers: two cards with different sizes and layout options, and a select box." + +All containers share a set of defined styles. + +Internal padding is dependent on component size, density, and platform scale, all of which vary for specific components and patterns. + +This medium card uses spacing-300 for internal padding. + +In this group of containers — each representing a product — different container styles can be used to draw attention to a specific item. In this case, the emphasized container is paired with a badge, and contrasts against the more subdued containers with filled (gray) backgrounds. + +Note that specific components might have different options and states. + +A consistent app frame helps create a sense of brand unity and helps users feel comfortable and familiar with our products. Predictable navigation is also especially helpful for users who work across multiple applications, and it makes it easier to learn how to use new products. + +Example of an app frame with a side navigation. + +## Overview + +"Examples of containers: two cards with different sizes and layout options, and a select box." + +All containers share a set of defined styles. + +Internal padding is dependent on component size, density, and platform scale, all of which vary for specific components and patterns. + +This medium card uses spacing-300 for internal padding. + +Note that specific components might have different options and states. + +Example of an app frame with a side navigation. + +## Styles + +All containers share a set of defined styles. + +Internal padding is dependent on component size, density, and platform scale, all of which vary for specific components and patterns. + +This medium card uses spacing-300 for internal padding. + +Note that specific components might have different options and states. + +Example of an app frame with a side navigation. + +## Padding + +Internal padding is dependent on component size, density, and platform scale, all of which vary for specific components and patterns. + +This medium card uses spacing-300 for internal padding. + +Note that specific components might have different options and states. + +Example of an app frame with a side navigation. + +## Emphasis + +Note that specific components might have different options and states. + +Example of an app frame with a side navigation. + +## App frame + +Example of an app frame with a side navigation. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [States](/page/states/) +* [App frame](/page/s2-app-frame/) diff --git a/docs/s2-docs/designing/fonts.md b/docs/s2-docs/designing/fonts.md new file mode 100644 index 00000000..44a9a730 --- /dev/null +++ b/docs/s2-docs/designing/fonts.md @@ -0,0 +1,84 @@ +--- + +title: "Fonts" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + +--- + +# Fonts + +Adobe Clean Spectrum is the default font family for Spectrum 2. This family contains both variable and static options. The variable font (VF) is the default typeface for Spectrum 2. Additional fonts are also used in the design system. Learn more about the difference between fonts on the [Typography](https://s2.spectrum.corp.adobe.com/page/typography-fundamentals/#overview) page. + +## Spectrum fonts + +For design, these fonts are pre-installed on Adobe's enterprise Figma account. For implementation, look for these in Adobe Fonts (formerly Typekit). If neither of those options support your use case, these fonts are available for download here. View [Using restricted Adobe fonts](#using-restricted-adobe-fonts) for more information. + +### Adobe Clean Spectrum VF + +Adobe Clean Spectrum VF is Spectrum's primary typeface and an update to Adobe Clean, with more modern metrics for usage in UI and product design. It can be used for Latin-based languages as well as Greek and Cyrillic scripts. + +[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EovtJyyD70JGnU6GAFB39a8B0igit__I1kwIOdOQmRdZRg?e=5PaJvw) + +### Adobe Clean Spectrum Serif VF + +Adobe Clean Spectrum Serif VF is a companion font to Adobe Clean Spectrum VF, for usage in UI and product design. It can be used for Latin-based languages as well as Greek and Cyrillic scripts. + +[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EtGh4hIaNC5BplE0Fpd42aMBucEzpj85P3-uwnQoSS56Zg?e=7rkwnp) + +### Adobe Clean + +Adobe Clean is Adobe's corporate typeface. It can be used for Latin-based languages as well as Greek and Cyrillic scripts. + +[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EtE69FE1M5NNssssA8MUktcB69v3tyM8x9mz-Qs9sHmG3g?e=cbftOo) + +### Adobe Clean Serif + +Adobe Clean Serif is a companion font family to Adobe Clean. It covers most Latin-based languages as well as Greek and Cyrillic scripts. + +[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/Ej0pcVTelONCqghOsr5W4EwBWX-tOlQl4jx8iuHPHHatIQ?e=wvXNfq) + +### Source Code Pro + +Source Code Pro is used to display code snippets, either inline with another typeface or as a standalone block. + +[Download from Github](https://github.com/adobe-fonts/source-code-pro) + +### Adobe Clean Han + +Adobe Clean Han is a version of Adobe Clean supporting ideographic scripts – Chinese (Simplified and Traditional), Japanese, and Korean. + +[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/EsY41oy5pZxNlTrUwlEw-iYBthO9_oR9e1mzSSr_pFLCuw?e=d2Pd6m) + +### Adobe Clean Thai + +Adobe Clean Thai is used for setting the Thai script, in both looped and loopless styles. + +[Download font](https://adobe.sharepoint.com/:f:/s/Spectrum/ErsoedmOVINBqpzUC1CTu8gBfZrAeEQ1pKq6gwHHYIN7Dg?e=8GtE7b) + +### Adobe Clean Arabic + +Adobe Clean Arabic is used for the Arabic language, as well as other languages using the Arabic script, such as Persian. + +[Download font](https://adobe.sharepoint.com/sites/Spectrum/Design%20files/Forms/AllItems.aspx?id=%2Fsites%2FSpectrum%2FDesign%20files%2FSpectrum%20fonts%2FAdobe%20Clean%20Arabic\&p=true\&ga=1) + +### Adobe Clean Hebrew + +Adobe Clean Hebrew is used for modern Hebrew typesetting. + +[Download font](https://adobe.sharepoint.com/sites/Spectrum/Design%20files/Forms/AllItems.aspx?id=%2Fsites%2FSpectrum%2FDesign%20files%2FSpectrum%20fonts%2FAdobe%20Clean%20Hebrew\&p=true\&ga=1) + +### Adobe Clean Devanagari + +Adobe Clean Devanagari supports the Devanagari script, which is used for Hindi and Marathi languages. + +[Download font](https://adobe.sharepoint.com/sites/Spectrum/Design%20files/Forms/AllItems.aspx?id=%2Fsites%2FSpectrum%2FDesign%20files%2FSpectrum%20fonts%2FAdobe%20Clean%20Devanagari\&p=true\&ga=1) + +## Using restricted Adobe fonts + +These resources are [restricted fonts](https://www.adobe.com/products/type/font-licensing/restricted-fonts.html) for the exclusive use of Adobe products and software. They should only be used through Adobe Fonts (not self-hosted). For instructions, view [Using Adobe Fonts at Adobe](https://wiki.corp.adobe.com/display/fonts/Using+Adobe+Fonts+at+Adobe). diff --git a/docs/s2-docs/designing/grays.md b/docs/s2-docs/designing/grays.md new file mode 100644 index 00000000..f4f52d68 --- /dev/null +++ b/docs/s2-docs/designing/grays.md @@ -0,0 +1,98 @@ +--- + +title: "Grays" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* attention-hierarchy +* colors + +--- + +# Grays + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Gray-100 was previously the default background color. With Spectrum 2, gray-25 is the new default background color, which makes the UI brighter and have higher contrast than before. + +Spectrum 2 includes two new grays — gray-25 and gray-1000 — plus an update to the rest of the 11 grays. This means that there are 13 grays total in the system. + +The Spectrum team collected feedback from product teams across Adobe and determined that the 6.0.0 color system for light UI had an issue with the steps between gray-50 and gray-75. The difference between these two was so slight it was almost imperceivable, making it so that gray-75 was not very useful. Also, the grays from -100 to -400 had too much contrast between each step, making it so that each component state appeared too harsh. Gray-900 was solid black, which was too high of a contrast to be used in text components. Reading solid black text on a solid white background is not ideal; it creates optical strain for a significant number of users. + +Adding two new grays also allowed us to keep a solid black (in light UI) and solid white (in dark UI) without having to keep gray-900 so bright. Now gray-1000 can be used for borders with opacities. + +Adding an extra shade in the low range allowed for us to make more incremental steps between background grays. + +With the 6.0.0 gray system, users working in apps that support dark theme felt the colors were too light and muddy. And, users working in apps that support darkest theme felt the UI was too high-contrast, which makes it difficult to view the screen comfortably for long periods of time. The Spectrum 2 update addresses both issues by combining the dark and darkest themes into a new theme, with brightness values that are between the two existing themes. + +This update affects the layering system. The primary, secondary, and tertiary layers now use grays 25-75 instead of grays 50-100. + +"There are no current WCAG or W3C guidelines about if every fill and stroke in every component of every state needs to be 3:1 in contrast. Another thing to consider is that it’s irresponsible to approach the topic of contrast with a “one-size-fits-all” approach: every user has different needs, and design should account for user preference and customization. While one user may need interfaces to be higher contrast to be able to more clearly read and interact with the content, others may prefer interfaces to be lower in contrast (for example, people who are prone to getting migraines)." + +Because of this, Spectrum designs all active states of UI components to be at least 3:1 in contrast in some way with the background (such as a text field’s active state border). And, all objects within components, such as icons, drag handles, and text, are also compliant with the 3:1 or 4.5:1 requirement. Other graphical objects also always use at least 3:1 contrast and are accompanied by textual descriptions. Products using Spectrum should be built in such a way that the interface contrast, coloring, sizing, motion, and more can all be adjustable by the user to fit their own specific needs. + +The Spectrum 2 color update changed gray-900 (which is used by most heading or title text) to slightly lower contrast in both dark and light UI to ensure improved readability for as many users as possible. + +Color updates are breaking changes, so you’ll need to use the following information to responsibly migrate to Spectrum 2 colors. If this isn’t done correctly, backgrounds and components will appear extra dark. + +Field borders are currently the only objects that stay gray-300 in the default state. + +## Overview + +Adding an extra shade in the low range allowed for us to make more incremental steps between background grays. + +This update affects the layering system. The primary, secondary, and tertiary layers now use grays 25-75 instead of grays 50-100. + +Field borders are currently the only objects that stay gray-300 in the default state. + +## Two new grays + +Adding an extra shade in the low range allowed for us to make more incremental steps between background grays. + +This update affects the layering system. The primary, secondary, and tertiary layers now use grays 25-75 instead of grays 50-100. + +Field borders are currently the only objects that stay gray-300 in the default state. + +## A single dark theme + +This update affects the layering system. The primary, secondary, and tertiary layers now use grays 25-75 instead of grays 50-100. + +Field borders are currently the only objects that stay gray-300 in the default state. + +## Layering system + +This update affects the layering system. The primary, secondary, and tertiary layers now use grays 25-75 instead of grays 50-100. + +Field borders are currently the only objects that stay gray-300 in the default state. + +## Accessibility + +Field borders are currently the only objects that stay gray-300 in the default state. + +## Migration guide + +Field borders are currently the only objects that stay gray-300 in the default state. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Attention hierarchy](/page/attention-hierarchy/) +* [Colors](/page/colors/) diff --git a/docs/s2-docs/designing/icon-fundamentals.md b/docs/s2-docs/designing/icon-fundamentals.md new file mode 100644 index 00000000..633ccc50 --- /dev/null +++ b/docs/s2-docs/designing/icon-fundamentals.md @@ -0,0 +1,56 @@ +--- + +title: "Icon fundamentals" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + +--- + +# Icon fundamentals + +## Overview + +### Icons designed to balance personality with function + +Spectrum 2 icons are crisp, modern, and clean. They have more personality in the form of rounder corners and motion, and use more playful but modern metaphors when there's the need to have more brand expression (for example, in feature onboarding, marketing, and Learn content). The updated icon style picks up the clean and irreducible style of Spectrum and supports the efforts to bring a unified experience to all Adobe products. + +### What's been updated? + +Most noticeably, there's been a switch to an outline style from the previous style of icons as being filled. There's also an updated priority for using meaningful metaphors consistently, focusing on content, and helping users navigate across interfaces. This combines into a cohesive theme: **icons signal familiarity**. In a product portfolio as complex as Adobe's, this familiarity is expressed through a consistent and cohesive usage of UI elements, colors, patterns, and icon metaphors. + +The purpose of the updated icon style isn't just about functionality or the Adobe brand: it's about how many intricate details add up to make a big difference in the user experience. Using icon metaphors consistently makes Adobe's products usable. + +## History + +### How the Spectrum 2 icon set was developed + +Several teams collaborated on the overall Spectrum 2 design language updates. One goal for iconography was to build out the current style into a unified icon language, to more closely align with our multi-platform design approach and to look and feel cohesive with the iOS and Android iconography systems. Previous testing and the launch of the outline icon style for Acrobat Modern Viewer and Adobe Express provided insights that informed style refinements. + +### Why is this icon set intentionally different? + +This updated icon style aims to connect with a wider audience and a younger user base by pairing a more modern look with a simplified but functional approach. Being mostly monochrome allows for colored accents in badges. + +## Additional considerations + +The Spectrum 2 icon style aligns with contemporary UI and icon trends and is optimized for where the icons are viewed: displays across desktop and mobile. With a bigger focus on high-res screens, we've prioritized spacing and contrast for a more expressive range — leaving behind the problem of pixel-perfect snapping. + +We're also aligning the stroke weight into 4 subdivisions inside the pixel unit to create balanced stroke rendering with a 1.5 px stroke weight. This weight has been proven to work well with mobile retina screens, and it allows for a stronger appearance of the line renderings of icon shapes. + +## Appearance + +Icons are outlined. They're mostly monochrome to allow for colored accents in badges for status updates like alerts, information, and notifications. Some icons also use fill and a stroke to illustrate a concept more clearly (for example, the favorite star rating, or third-party logos). + +Occasionally, there are duotone icons to indicate a perceived change of direction, exclusion, transition, or speed (like in flip horizontal/vertical). + +## Style + +### Characteristics + +Adobe products often have complex controls, so our icon metaphors are **clear**, **functional**, and **additive to experiences**. They describe tools and topics as simply and accurately as possible. Icons that attempt to relay too much information often become busy and don't read well at small sizes. + +The shapes of the icons themselves are based on predefined **key shapes** to ensure a balanced look and feel across interfaces. diff --git a/docs/s2-docs/designing/illustrations.md b/docs/s2-docs/designing/illustrations.md new file mode 100644 index 00000000..e8a71c62 --- /dev/null +++ b/docs/s2-docs/designing/illustrations.md @@ -0,0 +1,160 @@ +--- + +title: "Illustrations" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* using-icons +* motion + +--- + +# Illustrations + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +The illustrations and graphics in Spectrum 2 have been completely reworked to reflect the significant update of our design system. + +Spectrum 2 (S2) evolved around the need to bridge the gap between purely professional tools and more consumer-orientated applications, creating updates that prioritize more approachability, a clearer sense of attention hierarchy, and a stronger connection to product branding. Illustrations are a major part of how Spectrum 2 creates such experiences. + +Please note that parts of this illustration system are still in exploration, and will be added to these guidelines once they’re more defined. Animation is also currently being explored. + +"Here’s a summary of the main updates that you’ll notice with Spectrum 2 illustrations, compared to the style of Spectrum 1:" + +Linear illustrations are monochromatic. They use the same color token as the icons (S2 / gray 800), and switch colors according to dark and light UI. + +"Linear illustrations use the following naming convention:" + +Gradient illustrations are new to our design system with the update to Spectrum 2. Compared to linear illustrations, they’re much bolder. They can help users understand a message more quickly, or motivate them to perform a specific action. + +There are two gradients that can be used for surfaces that show different products, or that are not product-specific. The other gradients are tied to specific products or clouds. For example, blue is tied to the photography and digital imaging category (such as Photoshop, Lightroom, and Fresco), while green represents the 3D category (such as Substance 3D Stager and Substance 3D Designer). It’s essential to use the appropriate illustration colors according to the product categories. If the application is for multiple products, use one of the gradient swatches that incorporate the Adobe brand red. + +Do not use the category gradient sets as semantic colors to communicate meanings like errors (red), warnings (yellow), or successes (green). + +"Gradient illustrations use the following naming convention:" + +Linear illustrations are elements that communicate lower attention, as they blend in well with the rest of the UI. They can be used multiple times in a layout without drawing too much attention. + +Errors or critical messages should only use linear illustrations. + +Gradient illustrations use colors that can be misunderstood as semantic colors (e.g., green for positive, red for negative). They also have an upbeat and inspirational tone, which isn’t appropriate in situations where a user may be frustrated by something that’s an inconvenience or is disruptive to them in accomplishing their work. + +The linear illustration style works well for layouts that feature a number of illustrations together (such as a collection of cards). Linear illustrations draw a lower level of attention and blend in well with the UI, so it’s appropriate to use them in a collection of elements. Gradient illustrations draw a lot of attention in multiples, so they need to be used sparingly and sparsely. + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +Gradient illustrations are high attention elements in the layout. Use them strategically and thoughtfully to draw the user’s attention and to provoke a delightful moment. + +Gradient illustrations draw more attention because they’re very colorful. Using more then one in a given view will make the UI too busy and too loud. Use gradient illustrations sparingly to guide a user’s attention to engaging, high-value actions such as uploads, starting projects, or commenting. + +"Gradient illustrations incorporate product category colors, and also include colors that have semantic meanings in Spectrum: red, orange, or green. It creates inconsistency and confusion to have an error message or a critical alert in green (a color has a positive semantic meaning)." + +Use gradient illustrations when you want to emphasize positive actions. Gradient illustrations have an upbeat and inspirational tone, which isn’t appropriate in situations where a user may be frustrated by something that’s an inconvenience or is disruptive to them in accomplishing their work. + +The colors in gradient illustrations are connected to the product categories. For example, an illustration for a Substance 3D product should use the Substance 3D green colors. + +Do not use different colors than those of your product category. Reach out to the Spectrum Brand team for guidance about the appropriate colors for your use case. + +It’s highly recommended to test gradient illustrations as you’re designing your layout. They’re very expressive and colorful, so it’s important to determine how they complement (or don’t) different communication points (e.g., user-generated content, onboarding, feature banners, upsells, and more). + +If gradient illustrations are making the layout too noisy, use linear illustrations instead. + +Thematic banners are descriptive and represent a specific topic or feature. Similar to the gradient illustrations, they’re either connected to the product brand categories by color, or they use the generic gradient swatches. + +## Fundamentals + +"Here’s a summary of the main updates that you’ll notice with Spectrum 2 illustrations, compared to the style of Spectrum 1:" + +Linear illustrations are monochromatic. They use the same color token as the icons (S2 / gray 800), and switch colors according to dark and light UI. + +"Linear illustrations use the following naming convention:" + +Do not use the category gradient sets as semantic colors to communicate meanings like errors (red), warnings (yellow), or successes (green). + +"Gradient illustrations use the following naming convention:" + +Errors or critical messages should only use linear illustrations. + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +If gradient illustrations are making the layout too noisy, use linear illustrations instead. + +## Illustration styles + +Linear illustrations are monochromatic. They use the same color token as the icons (S2 / gray 800), and switch colors according to dark and light UI. + +"Linear illustrations use the following naming convention:" + +Do not use the category gradient sets as semantic colors to communicate meanings like errors (red), warnings (yellow), or successes (green). + +"Gradient illustrations use the following naming convention:" + +Errors or critical messages should only use linear illustrations. + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +If gradient illustrations are making the layout too noisy, use linear illustrations instead. + +## Linear illustrations + +Linear illustrations are monochromatic. They use the same color token as the icons (S2 / gray 800), and switch colors according to dark and light UI. + +"Linear illustrations use the following naming convention:" + +Do not use the category gradient sets as semantic colors to communicate meanings like errors (red), warnings (yellow), or successes (green). + +"Gradient illustrations use the following naming convention:" + +Errors or critical messages should only use linear illustrations. + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +If gradient illustrations are making the layout too noisy, use linear illustrations instead. + +## Gradient illustrations + +Do not use the category gradient sets as semantic colors to communicate meanings like errors (red), warnings (yellow), or successes (green). + +"Gradient illustrations use the following naming convention:" + +Errors or critical messages should only use linear illustrations. + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +If gradient illustrations are making the layout too noisy, use linear illustrations instead. + +## Usage guidelines + +Errors or critical messages should only use linear illustrations. + +Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes. + +If gradient illustrations are making the layout too noisy, use linear illustrations instead. + +## Thematic banners + +## Resources and contact information + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Using icons](/page/using-icons/) +* [Motion](/page/motion/) diff --git a/docs/s2-docs/designing/motion.md b/docs/s2-docs/designing/motion.md new file mode 100644 index 00000000..70fe53c3 --- /dev/null +++ b/docs/s2-docs/designing/motion.md @@ -0,0 +1,58 @@ +--- + +title: "Motion" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + +--- + +# Motion + +**Motion in Spectrum 2 is still being developed. There's currently a dedicated working group of subject matter experts from across Adobe whose work will be added to these guidelines.** + +## Overview + +Spectrum 2 builds on top of the [existing motion guidelines for the design system](https://spectrum.corp.adobe.com/page/motion/): that motion is always purposeful, intuitive, and seamless. With this update, we also use motion to draw attention to areas where we want to add personality. No matter what, the usage of motion should be adding meaning to an experience. And, motion over large surface areas needs to support browser and system settings for reduced motion. + +Motion is also an important part of brand expression. Just like tone in language, tone in motion can range from formal and direct to lighthearted and subtle. + +Motion in Spectrum 2 is categorized into the areas of **directional** motion, **interaction** motion, and **wayfinding** motion. Wayfinding motion is still in development. + +## Directional motion + +The directions in which motion happens communicate intentional meanings. There are three basic categories of directional motion, each used for their own purpose. + +### Linear + +Linear motion indicates forward movement and a sentiment of progress. When emphasizing movement to a different section, page, or item (such as a button or link), the destination is readily clear and minimally disruptive. + +If you're creating a custom animation, consider [RTL (right-to-left) languages](https://spectrum.corp.adobe.com/page/bi-directionality/) and also how the meaning of motion might differ depending on cultural context. + +Progress bars communicate forward progression. They work well to show determinate (finite) progress. + +In the example of a button, a static arrow icon facing toward the right already indicates forward movement. When linear motion is added to the arrow upon hover, the movement is emphasized. Use this button option with motion sparingly, only on the most important action(s) on a page. + +### Diagonal + +Diagonal motion indicates larger movement, and can be potentially disruptive. This type of motion can be used to emphasize that there's a switch in context happening, like linking out to a different view or destination. + +In the example of a link, a static arrow icon facing the top right already indicates a potentially disruptive action. When diagonal motion is added to the arrow on hover, the meaning of the arrow is emphasized. Use this link option with motion sparingly, and only to communicate that there will be a switch in context. + +### Clockwise + +Clockwise motion indicates a holding pattern that's repetitive and doesn't have clear forward momentum or progress. This is most often used for loading indicators. + +Progress circles have clockwise motion and work well to show indeterminate (infinite) progress. + +## Interaction motion + +Motion shows users feedback that, when interacting with the UI, their actions are registering with a system. It's not the only way to show feedback, but it helps objects to feel more dynamic and responsive. It also can help communicate meaning, or add emphasis that something is happening that requires attention. + +A [microinteraction](https://www.nngroup.com/articles/microinteractions/) is a single action (like a click, tap, or swipe) which triggers a response (like a transition or animation). In Spectrum 2, microinteractions offer moments of personality that are reflective of product branding. + +In this example, the button scales down on the down state, emphasizing that something — the action of selecting — happened. diff --git a/docs/s2-docs/designing/object-styles.md b/docs/s2-docs/designing/object-styles.md new file mode 100644 index 00000000..8ed48f6e --- /dev/null +++ b/docs/s2-docs/designing/object-styles.md @@ -0,0 +1,140 @@ +--- + +title: "Object styles" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* fonts +* spacing + +--- + +# Object styles + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Object styles are specific visual shapes or effects that are used to communicate intent or to give cues about an interaction. + +"For example, different types of inputs all share styles. Search fields, text fields, and combo boxes use object styles to communicate a primary purpose: text input. A search field is often more of a global scope, and has full rounding to add emphasis and differentiation from other types of fields. Action buttons, pickers, and in-field buttons share a fill color to indicate selection. Checkboxes, radio buttons, and switches share object styles to indicate binary selection." + +Example of how object styles are combined to communicate different interactions. + +In general, Spectrum 2’s system for rounding is more pronounced and flexible than in Spectrum 1. + +Larger rounding values give components more expression and personality, and having more rounding options makes it possible to create visual balance across a wide range of contexts. + +In general, this system of rounding creates a visually balanced gap when nesting smaller objects within larger objects. + +Avatars are displayed in circles to draw attention to user content. All other representations, such as groups and products, are displayed in rounded squares. + +In Spectrum 2, rounding for different sized components varies based on a Major Second logarithmic scale. This allows for components to retain a consistent and identifiable shape at all sizes. Desktop and mobile scales share the same base rounding. Note that the values displayed are base values for desktop scale components, and specific corner radius values may vary between components. + +Borders are only used when spacing isn’t enough to show separation. For example, a divider might sometimes be needed to separate two distinct action button groups. Or, an object might have a border to demarcate distinct areas, such as separating a panel or card from the rest of the content on a page. + +"There are two border widths used within in-product UI contexts:" + +"The third option is not used within in-product UI contexts:" + +A medium divider separates two action button groups. Note that when dividers are used with visible gaps on both ends, the end caps are fully rounded. + +In Spectrum 2, large borders are only used in longform content, such as in documentation pages. Large borders aren’t used within in-product UI contexts. + +A full-width medium divider can be a helpful option for separating two distinct parts of a page, such as dividing a navigation panel from the rest of the content. When deciding whether a divider is needed, consider whether groups of information are still clear without one. Generally, more complex content with a varying alignment of objects will benefit the most from using a divider. + +Similarly to the previous example, a full-width medium divider separates a commenting panel from the rest of the page. The divider is helpful in this context since the commenting panel can have varying content, from an empty state to many layers of nested comments. By creating a clear boundary, this helps set expectations for what content is presented in the panel. + +Drop shadows draw attention and give the appearance of depth. By default, this style is used to show elevation, when content appears on top of other content. + +While the detailed values are still in progress, the foundational concepts for drop shadows still apply. + +"In Spectrum 2, shadows are composed of three layers: a key shadow, an ambient shadow, and a transition shadow that’s between them." + +Containers that appear on top of content, such as menus and tooltips, have drop shadows to show elevation. + +By default, objects have no drop shadows. When a container is dragged, a drop shadow is used to show elevation in both default and emphasized containers. + +"An overlay represents elevation in a different way: it focuses attention on the content above the overlay only. When using an overlay (for example, behind a dialog), no additional drop shadow is applied to the background." + +## Overview + +Example of how object styles are combined to communicate different interactions. + +In general, Spectrum 2’s system for rounding is more pronounced and flexible than in Spectrum 1. + +In general, this system of rounding creates a visually balanced gap when nesting smaller objects within larger objects. + +"There are two border widths used within in-product UI contexts:" + +"The third option is not used within in-product UI contexts:" + +A medium divider separates two action button groups. Note that when dividers are used with visible gaps on both ends, the end caps are fully rounded. + +While the detailed values are still in progress, the foundational concepts for drop shadows still apply. + +"In Spectrum 2, shadows are composed of three layers: a key shadow, an ambient shadow, and a transition shadow that’s between them." + +Containers that appear on top of content, such as menus and tooltips, have drop shadows to show elevation. + +## Rounding + +In general, Spectrum 2’s system for rounding is more pronounced and flexible than in Spectrum 1. + +In general, this system of rounding creates a visually balanced gap when nesting smaller objects within larger objects. + +"There are two border widths used within in-product UI contexts:" + +"The third option is not used within in-product UI contexts:" + +A medium divider separates two action button groups. Note that when dividers are used with visible gaps on both ends, the end caps are fully rounded. + +While the detailed values are still in progress, the foundational concepts for drop shadows still apply. + +"In Spectrum 2, shadows are composed of three layers: a key shadow, an ambient shadow, and a transition shadow that’s between them." + +Containers that appear on top of content, such as menus and tooltips, have drop shadows to show elevation. + +## Border width + +"There are two border widths used within in-product UI contexts:" + +"The third option is not used within in-product UI contexts:" + +A medium divider separates two action button groups. Note that when dividers are used with visible gaps on both ends, the end caps are fully rounded. + +While the detailed values are still in progress, the foundational concepts for drop shadows still apply. + +"In Spectrum 2, shadows are composed of three layers: a key shadow, an ambient shadow, and a transition shadow that’s between them." + +Containers that appear on top of content, such as menus and tooltips, have drop shadows to show elevation. + +## Drop shadow + +While the detailed values are still in progress, the foundational concepts for drop shadows still apply. + +"In Spectrum 2, shadows are composed of three layers: a key shadow, an ambient shadow, and a transition shadow that’s between them." + +Containers that appear on top of content, such as menus and tooltips, have drop shadows to show elevation. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Fonts](/page/fonts/) +* [Spacing](/page/spacing/) diff --git a/docs/s2-docs/designing/s2-app-frame-content-area-browsing-context.md b/docs/s2-docs/designing/s2-app-frame-content-area-browsing-context.md new file mode 100644 index 00000000..689ff567 --- /dev/null +++ b/docs/s2-docs/designing/s2-app-frame-content-area-browsing-context.md @@ -0,0 +1,21 @@ +--- + +title: "S2 App Frame - Content Area (Browsing Context)" +source\_url: +last\_updated: 2026-02-12 +category: designing +status: published +tags: + +* designing +* app-frame +* content-area +* browsing-context + +--- + +# S2 App Frame - Content Area (Browsing Context) + +Interactive browsing context for the app frame content area. Content should be scraped from the live site when VPN/browser access is available. + +**Source:** diff --git a/docs/s2-docs/designing/s2-app-frame-creating-bluelines-browsing-context.md b/docs/s2-docs/designing/s2-app-frame-creating-bluelines-browsing-context.md new file mode 100644 index 00000000..b56684d9 --- /dev/null +++ b/docs/s2-docs/designing/s2-app-frame-creating-bluelines-browsing-context.md @@ -0,0 +1,21 @@ +--- + +title: "S2 App Frame - Creating Bluelines (Browsing Context)" +source\_url: +last\_updated: 2026-02-12 +category: designing +status: published +tags: + +* designing +* app-frame +* bluelines +* browsing-context + +--- + +# S2 App Frame - Creating Bluelines (Browsing Context) + +Interactive browsing context for creating bluelines in the app frame. Content should be scraped from the live site when VPN/browser access is available. + +**Source:** diff --git a/docs/s2-docs/designing/s2-app-frame-header-browsing-context.md b/docs/s2-docs/designing/s2-app-frame-header-browsing-context.md new file mode 100644 index 00000000..ba063657 --- /dev/null +++ b/docs/s2-docs/designing/s2-app-frame-header-browsing-context.md @@ -0,0 +1,21 @@ +--- + +title: "S2 App Frame - Header (Browsing Context)" +source\_url: +last\_updated: 2026-02-12 +category: designing +status: published +tags: + +* designing +* app-frame +* header +* browsing-context + +--- + +# S2 App Frame - Header (Browsing Context) + +Interactive browsing context for the app frame header. Content should be scraped from the live site when VPN/browser access is available. + +**Source:** diff --git a/docs/s2-docs/designing/s2-app-frame-side-navigation-browsing-context.md b/docs/s2-docs/designing/s2-app-frame-side-navigation-browsing-context.md new file mode 100644 index 00000000..ec8268f1 --- /dev/null +++ b/docs/s2-docs/designing/s2-app-frame-side-navigation-browsing-context.md @@ -0,0 +1,21 @@ +--- + +title: "S2 App Frame - Side Navigation (Browsing Context)" +source\_url: +last\_updated: 2026-02-12 +category: designing +status: published +tags: + +* designing +* app-frame +* side-navigation +* browsing-context + +--- + +# S2 App Frame - Side Navigation (Browsing Context) + +Interactive browsing context for the app frame side navigation. Content should be scraped from the live site when VPN/browser access is available. + +**Source:** diff --git a/docs/s2-docs/designing/s2-app-frame.md b/docs/s2-docs/designing/s2-app-frame.md new file mode 100644 index 00000000..84dabcfb --- /dev/null +++ b/docs/s2-docs/designing/s2-app-frame.md @@ -0,0 +1,22 @@ +--- + +title: "S2 App Frame" +source\_url: +last\_updated: 2026-02-12 +category: designing +status: published +tags: + +* designing +* app-frame +* layout + +--- + +# S2 App Frame + +Main app frame documentation for Spectrum 2. Content should be scraped from the live site when VPN/browser access is available. + +**Source:** + +Related: [App frame overview](app-frame-overview.md), [App frame header](app-frame-header.md), [App frame side navigation](app-frame-side-navigation.md), [App frame content area](app-frame-content-area.md). diff --git a/docs/s2-docs/designing/spacing.md b/docs/s2-docs/designing/spacing.md new file mode 100644 index 00000000..eb8e8c48 --- /dev/null +++ b/docs/s2-docs/designing/spacing.md @@ -0,0 +1,40 @@ +--- + +title: "Spacing" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + +--- + +# Spacing + +## Overview + +Spectrum 2 continues with Spectrum's current guidelines for spacing and responsive grids. More detailed guidelines for responsive design are currently in progress. + +The primary update for Spectrum 2 is that **instead of dividers, spacing is used as the primary way to group and divide content**. Different spacing values establish rhythm and create hierarchy within a page. The [spacing values](https://spectrum.corp.adobe.com/page/spacing/#Spacing-values) themselves remain unchanged from Spectrum 1. + +Smaller spacing values should generally be used for objects that are closely related. An example of this would be to use a smaller spacing value in between the components that make up a component group, like in a button group or a group of cards. + +Larger spacing values should be used for groups of things that are less closely related. An example of this would be to use a larger spacing value to separate two distinct sections of content. Doing this helps to better organize a page. + +In some contexts, a divider can still be appropriate to define larger areas of a page. View more about [border width](https://s2.spectrum.corp.adobe.com/page/object-styles/#border-width). + +### Example + +In this example, the side navigation items use a smaller spacing value (spacing-75) in order to show a closer relationship. The side navigation items are grouped with a combination of a section title and a larger spacing value (spacing-400) to divide two distinct sections. + +Similarly, cards that are part of the same group have a smaller spacing value (spacing-300) between them. Each group of cards has a title and a larger spacing value (spacing-500) to show two that the two groups are distinct. + +By using spacing intentionally, the purpose of page content becomes more readily apparent and information can become easier to parse. + +## Density + +Spectrum defines density as the spacing between components or UI elements, regardless of their size and scale. Density can be used alongside component size to create a range of layouts, from spacious to dense. + +For example, when creating complex UI layouts, high density is often combined with smaller components and tighter spacing in between elements. diff --git a/docs/s2-docs/designing/states.md b/docs/s2-docs/designing/states.md new file mode 100644 index 00000000..06d99667 --- /dev/null +++ b/docs/s2-docs/designing/states.md @@ -0,0 +1,34 @@ +--- + +title: "States" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + +--- + +# States + +Spectrum 2 components generally follow [the existing patterns for states](https://spectrum.corp.adobe.com/page/states/). A change in color is the primary way that a state is communicated. Colors follow a standard progression for user-initiated states: default, hover, down, and keyboard focus. There are minor updates to the styles of disabled, selected, and dragged states, and these are all component options. + +## Down state + +In Spectrum 2, some components use a change in size instead of color to communicate a down state. This gives the illusion of objects being pressed-in, and makes interactions more dynamic and responsive. + +## Disabled state + +[Disabled states](https://spectrum.corp.adobe.com/page/states/#Disabled) generally stay the same from Spectrum 1, but there have been some minor updates to specific components. For example, a text field retains the outline style when disabled, to more closely match its default state. + +## Selected state + +Selected states use a primary style by default, generally through a gray-800 fill. Some have an accent color option that can be used to draw emphasis. This is primarily helpful in contexts with a specific and narrowly-scoped goal (for example, in a dialog), or when there's a single, clear call to action within a page (for example, a "Create" button). + +When there's many groups of controls that require the same amount of attention (such as in a panel) the not emphasized option works best. For more details about this concept, view [Attention hierarchy](https://s2.spectrum.corp.adobe.com/page/attention-hierarchy/). + +## Dragged state + +A dragged state has a unique drop shadow to draw attention to the dragged object. Learn more about [drop shadows](https://s2.spectrum.corp.adobe.com/page/object-styles/#drop-shadow). diff --git a/docs/s2-docs/designing/typography-fundamentals.md b/docs/s2-docs/designing/typography-fundamentals.md new file mode 100644 index 00000000..4a167a5e --- /dev/null +++ b/docs/s2-docs/designing/typography-fundamentals.md @@ -0,0 +1,216 @@ +--- + +title: "Typography fundamentals" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* background-layers +* fonts + +--- + +# Typography fundamentals + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +The variable font (VF) is the default typeface for Spectrum 2 web, iOS, and future desktop explorations. + +"There are two major updates, compared with Adobe Clean:" + +"If you need to deviate from the default typeface (Adobe Clean Spectrum VF), you can use Adobe Clean Spectrum Serif VF, Adobe Clean Han, and Source Code Pro:" + +"In general:" + +Spectrum ensures that different sizes of text can work together harmoniously, on both desktop and mobile. For Spectrum 2, all font sizes follow the Major Second type scale, which has a ratio of 1.125. This means that each size is multiplied or divided by 1.125 from the previous size, starting with the base size (font-size-100), and rounded to the nearest whole number. Custom text (any non-existing typography styles) or modifications to existing type styles should use a font size from this list. + +When selecting font sizes to ensure readability, keep in mind that Adobe Clean does not match 1:1 with system font size definitions. It’s generally a size smaller than system fonts such as SF Pro, Segoe UI, Roboto, and others. + +Updated (\*) means that these sizes didn't follow the Major Second type scale in Spectrum 1 and have now been updated to reflect the accurate values + +"New (\*\*) shows Spectrum 2's new additions: font-size-25 is new to accommodate scaling to the smallest detail and body sizes. Font-size-1400 and -1500 are now available to provide consistent scaling to larger sizes. These are often needed in website design and for marketing scenarios." + +Spectrum 2 offers guidance for a wider range of font weights to help establish visual hierarchy in layouts, including the specific usages of Black, ExtraBold, and Medium weights. + +When used in Adobe Express products, the weight is set to Black in order to align to the Adobe Express brand guidelines. Black weight text should only be used in heading type styles, and never below 18 px font-size, to ensure the text remains legible. + +Select elements in the UI use a Bold font weight. Bold text is often used to accentuate the primary focus on a page or in a container, and in many uses, it’s paired with regular body text to create hierarchy. Titles, file names, user names, and button labels all use bold weight. + +In Spectrum 2, some components, like action buttons, badges, and tags, use Medium weight labels in order to maintain balance with Spectrum 2’s icons, which use a 1.5 px stroke. + +Regular is the default font weight for Spectrum components and body text. It should also be used for any content that’s entered by users, is editable, or longer in form (for example, text fields and text areas). + +Line height values are updated in Spectrum 2 to better accommodate the baseline shift of the new default font — Adobe Clean Spectrum VF — and to position the text as vertically centered in UI components. + +To ensure that the space between lines of text appears balanced, the default line-height is adjusted from \~130% at smaller font-sizes to \~115% at larger font-sizes, and then rounded to whole even numbers to ensure that text within a component will not sit on a half-pixel. + +Body and Code type styles use a more spacious line height multiplier of 1.5x the font-size (line-height-200) to ensure that longform text has more space and is legible. CJK languages use a 1.7x multiplier. + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +"Keep in mind that a single product won’t need all of theses sizes, and especially at the same time. As a starting point, use a t-shirt size from each of the type styles (in Figma, these are known as text styles). For example: pair Heading Medium with Title Medium, Body Medium, and Medium t-shirt sized components." + +If you’d like to override these styles, there’s some flexibility for you to define your own typography and hierarchy as long as any customization follows Spectrum guidance for font size and color usage. Use what best fits your context and best supports your users. + +Heading text represents the biggest and boldest text on a page, and it draws the most attention. Only the broadest idea, such as the main page title, should use this style. + +Body is the type style that’s primarily used for longer-form text that may extend to multiple lines. “Body text” is a frequently used term to describe the text that creates the main content on a page, which is where this style gets its name from. + +“Detail text” is a broad term for any kind of text that communicates ideas that are even more specific than body text. Text using the Detail style acts as supporting context to any other information presented. + +Detail text often uses Medium weight when paired with iconography, to maintain visual balance with the 1.5 px stroke width of Spectrum 2 icons. It’s also often shown in gray-600 or gray-700 to make it more subdued in terms of visual hierarchy. + +The differences between Detail text, Component text, and Body text are nuanced and often come down to applied semantic meaning. The characteristic differences in Detail text are the default weight, size, letter spacing, all-caps treatment for marketing contexts, and color usage. Detail text defaults to Medium weight, a smaller font size, and lighter shades of gray. It also uses the updated per-font-size line height, while Body text uses the spacious line height multiplier of 1.5x font-size. + +Component is the type style that is applied to text within UI components. + +In Spectrum 1, the “component” line height meant “a line-height applied to text within UI elements.” Spectrum 2 expands on this by having text styles in the Spectrum Figma libraries, to let you quickly apply text formatting to any text element in a design. This will help you stay connected to the system without needing to detach or override other text styles like Body or Title. + +The Component type style comes in multiple font weights to support its flexibility across components in the design system. For example, the Spectrum 2 button uses the Component type style with bold weight. Action button uses the Component type style with medium weight, and text field uses the Component type style with regular weight. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +The following are some general examples to show how the Spectrum 2 typography system all comes together, and how type styles can be used together to create visual hierarchy. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +In instances where Spectrum’s typefaces might fail to load properly, there are defined fallback fonts that have been selected based on operating system consistency and similar anatomical relationships. + +## Overview + +The variable font (VF) is the default typeface for Spectrum 2 web, iOS, and future desktop explorations. + +"There are two major updates, compared with Adobe Clean:" + +"In general:" + +Updated (\*) means that these sizes didn't follow the Major Second type scale in Spectrum 1 and have now been updated to reflect the accurate values + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +Component is the type style that is applied to text within UI components. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Typefaces + +The variable font (VF) is the default typeface for Spectrum 2 web, iOS, and future desktop explorations. + +"There are two major updates, compared with Adobe Clean:" + +"In general:" + +Updated (\*) means that these sizes didn't follow the Major Second type scale in Spectrum 1 and have now been updated to reflect the accurate values + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +Component is the type style that is applied to text within UI components. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Hierarchy + +"In general:" + +Updated (\*) means that these sizes didn't follow the Major Second type scale in Spectrum 1 and have now been updated to reflect the accurate values + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +Component is the type style that is applied to text within UI components. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Font size + +Updated (\*) means that these sizes didn't follow the Major Second type scale in Spectrum 1 and have now been updated to reflect the accurate values + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +Component is the type style that is applied to text within UI components. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Font weight + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +Component is the type style that is applied to text within UI components. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Line height + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +Component is the type style that is applied to text within UI components. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Type styles + +Spectrum 2 uses type styles to help maintain a consistent semantic meaning and create accessible, legible, and on-brand experiences across platforms. + +Component is the type style that is applied to text within UI components. + +Code is a typography component used for text that represents code. The default font for showing code is Source Code Pro. + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Typography examples + +In this file browsing example, Heading, Title, Component, and Detail style text are used to create hierarchy throughout the page. + +In this commenting example, Title, Body, Component, and Detail style text are used to create hierarchy within the comments panel. + +## Fallback fonts + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Background layers](/page/background-layers/) +* [Fonts](/page/fonts/) diff --git a/docs/s2-docs/designing/using-icons.md b/docs/s2-docs/designing/using-icons.md new file mode 100644 index 00000000..5f233b6d --- /dev/null +++ b/docs/s2-docs/designing/using-icons.md @@ -0,0 +1,170 @@ +--- + +title: "Using icons" +source\_url: +last\_updated: 2026-02-02 +category: designing +status: published +tags: + +* designing + related\_components: +* icon-fundamentals +* illustrations + +--- + +# Using icons + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Workflow icons are graphical metaphors or symbols that users interact with to navigate and manipulate objects. They maintain a consistent size and style within each platform to ensure visual harmony and usability. While consistency is key, it is now fairly common to combine different icon scales to support hierarchy and context. + +UI icons are atomic pieces — like arrows, crosses, or chevrons — that are part of a component. They aren’t metaphorical per se, but they’re an indication of how users interact with a component (for example, what happens when you click on a disclosure chevron or drag handle in a panel). Unlike workflow icons, UI icons come in assorted sizes. + +Status badges are indicators that communicate a variety of statuses or states, such as presence, validity, completeness, and more. Premium badges indicate that a feature is only available to paying customers. + +"Spectrum 2 workflow icons come in two sizes per platform, but with one stroke weight: 1.5 px." + +The primary size for Desktop/Web is a canvas of 20 px with the icon being \~18 px. There’s a secondary size for UI areas — like a layers panel, lists, or cards — which require smaller versions and come in a 16 px canvas with the icon being \~14 px. + +The equivalent for Mobile is the primary size of the canvas at 24 px with the icon being \~22 px. The secondary size canvas is 20 px with the icon being \~18px. + +"In Spectrum components, workflow icons scale up or down slightly when they’re used. For example: a 20 px icon in a medium-sized component will be slightly larger in a large-sized component, and smaller in a small-sized component. UI icons come in their respective size range, since Spectrum components treat these differently." + +“S2” is the prefix for Spectrum 2 icons. + +"Here’s a breakdown of each part of the icon naming convention:" + +An example of the naming convention for Spectrum 2 (S2) icons. + +Keeping one stroke weight consistent within a size range helps to balance out and contrast the visual weight. For Web and Desktop platforms, icons are designed at a 20 px canvas as default with a 1.5 px stroke, resulting in a 1.64 px stroke when sized up to 24 px for mobile. This helps keep a unified look, and it builds icons efficiently since it’s not necessary to redraw them for each platform. + +All icons with angles get a 1.5 px rounding treatment to achieve a rounder appearance. Inner corners are slightly rounded, and all stroke ends have rounded end caps. By default, the corner radius can be decreased in case a metaphor requires pointy edges. + +Icon designs include a safe area to ensure there’s flexibility for finding the best positioning and balance in a layout. The main shape should be centered, and modifier placement is primarily at the bottom right corner of the canvas. Notification dots appear at the top right corner (these are mostly added programmatically). + +The intersections of badge/modifier placement. + +The vertical spacing between icons and text is adjusted to create balance. + +"For example: in a medium-sized component, shifting the text box 1 px up and the icon box 1 px down inside a button better balances out the appearance and refines the relationship with text in Adobe Clean Medium." + +An example of icon and text alignment in a button. + +An example of a quiet action button with a 16 px icon. + +The new SVG native format for icons allows for automatic tinting to match different states (hover, selected, etc.) and can programmatically switch depending on UI brightness or color theme. It’s not about tinting the whole SVG in one color, but tinting single elements inside the SVG. To do this, the new SVGs use named CSS variables to set color values for every element. There will be Spectrum tokens for this, so automatic tinting will work out-of-the-box in any product using Spectrum CSS. + +For other apps, it will be easier to add the needed color information to their own CSS. Transparencies will be used to achieve tints of the primary icon color, making it easy to use at least the gray tone when it’s not possible to work with CSS variables. + +Example of SVG code. The highlighted sections show that two dynamic colors will be changed programmatically, and that there's a white exclamation mark which should always be displayed in white. + +If you diverge from Spectrum colors, you’ll need to make sure that your design has enough contrast between the icon and the background. Use subtle fills in light and dark themes to maintain legibility without overpowering the UI. Make sure that the icons remain legible and distinguishable across varied backgrounds and themes. + +The library currently only includes a subset of icons, and are for mock-up purposes only. If you need to create a mock-up with an icon that isn’t available yet, just use a placeholder icon. Don’t use unapproved icons in your work (for example, downloaded from Noun Project, or icons you’ve created yourself). + +## Types of icons + +"Spectrum 2 workflow icons come in two sizes per platform, but with one stroke weight: 1.5 px." + +“S2” is the prefix for Spectrum 2 icons. + +"Here’s a breakdown of each part of the icon naming convention:" + +An example of the naming convention for Spectrum 2 (S2) icons. + +The intersections of badge/modifier placement. + +The vertical spacing between icons and text is adjusted to create balance. + +An example of icon and text alignment in a button. + +An example of a quiet action button with a 16 px icon. + +## Sizes + +"Spectrum 2 workflow icons come in two sizes per platform, but with one stroke weight: 1.5 px." + +“S2” is the prefix for Spectrum 2 icons. + +"Here’s a breakdown of each part of the icon naming convention:" + +An example of the naming convention for Spectrum 2 (S2) icons. + +The intersections of badge/modifier placement. + +The vertical spacing between icons and text is adjusted to create balance. + +An example of icon and text alignment in a button. + +An example of a quiet action button with a 16 px icon. + +## Naming convention + +“S2” is the prefix for Spectrum 2 icons. + +"Here’s a breakdown of each part of the icon naming convention:" + +An example of the naming convention for Spectrum 2 (S2) icons. + +The intersections of badge/modifier placement. + +The vertical spacing between icons and text is adjusted to create balance. + +An example of icon and text alignment in a button. + +An example of a quiet action button with a 16 px icon. + +## Attributes + +The intersections of badge/modifier placement. + +The vertical spacing between icons and text is adjusted to create balance. + +An example of icon and text alignment in a button. + +An example of a quiet action button with a 16 px icon. + +## Icon and badges placement + +The intersections of badge/modifier placement. + +The vertical spacing between icons and text is adjusted to create balance. + +An example of icon and text alignment in a button. + +An example of a quiet action button with a 16 px icon. + +## Text and icon alignment + +The vertical spacing between icons and text is adjusted to create balance. + +An example of icon and text alignment in a button. + +An example of a quiet action button with a 16 px icon. + +## New SVG structure + +## Usage guidelines + +## Requesting icons + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Fundamentals](/page/icon-fundamentals/) +* [Illustrations](/page/illustrations/) diff --git a/docs/s2-docs/developing/developer-overview.md b/docs/s2-docs/developing/developer-overview.md new file mode 100644 index 00000000..d15195b7 --- /dev/null +++ b/docs/s2-docs/developing/developer-overview.md @@ -0,0 +1,60 @@ +--- + +title: "Developer overview" +source\_url: +last\_updated: 2026-02-02 +category: developing +status: published +tags: + +* developing + related\_components: +* motion +* action-bar + +--- + +# Developer overview + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Spectrum 2 offers a new look and feel that your team will want to adopt for your product. You’ll probably have questions, like “How do we get started?” “How do we migrate?” or “How do we roll this out?” + +On this page, we’ve addressed some common questions from product developers as Spectrum 2 has rolled out. For more specific, detailed, and up-to-date information about working with a particular implementation, visit its documentation site. + +As of May 2025, Spectrum is in the process of staffing a team to design and build an implementation of Spectrum for Android. Once onboarding wraps up and development begins, the team will begin communication about the status of the new library. + +If your team uses design data (like design tokens or CSS custom properties from Spectrum CSS) in any customizations or overrides in your project, you’ll want to keep track of updates to the implementation or design data resource you’re using and plan for time to verify any breaking changes. + +The most important thing you can do — as noted above — is to limit your usage of hard-coded values, direct usage of global tokens, or overriding global tokens via CSS properties/override APIs. Using the correct aliases ensures that components will continue to point to sensible values. In some cases, you may not even notice the change! + +## I work on a web-based product. How will I integrate Spectrum 2 into my application? + +## I work on a desktop product. How will I integrate Spectrum 2 into my application? + +## I work on a mobile product. How will I integrate Spectrum 2 into my application? + +## What if my tech stack has no implementation? How can I adopt Spectrum 2 on a new platform? + +## My team has some slight changes on top of Spectrum 1. How will that affect us in Spectrum 2? + +## How can I control unexpected changes to my UI while the migration is in progress? Or, how can I programmatically test between the differences of Spectrum 1 and Spectrum 2 (such as for A/B testing)? + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Motion](/page/motion/) +* [Action bar](/page/action-bar/) diff --git a/docs/s2-docs/fundamentals/home.md b/docs/s2-docs/fundamentals/home.md new file mode 100644 index 00000000..106e12c9 --- /dev/null +++ b/docs/s2-docs/fundamentals/home.md @@ -0,0 +1,20 @@ +--- + +title: "Spectrum 2 Home" +source\_url: +last\_updated: 2026-02-12 +category: fundamentals +status: published +tags: + +* fundamentals +* home +* overview + +--- + +# Spectrum 2 Home + +Landing page for Spectrum 2 documentation. Content should be scraped from the live site when VPN/browser access is available. + +**Source:** diff --git a/docs/s2-docs/fundamentals/introduction.md b/docs/s2-docs/fundamentals/introduction.md new file mode 100644 index 00000000..202d9638 --- /dev/null +++ b/docs/s2-docs/fundamentals/introduction.md @@ -0,0 +1,52 @@ +--- + +title: "Introduction" +source\_url: +last\_updated: 2026-02-02 +category: fundamentals +status: published +tags: + +* fundamentals + related\_components: +* home +* principles + +--- + +# Introduction + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +Spectrum 2 came about from the general need for Adobe products to start thinking beyond being purely "professional" tools, and from a decision that Adobe should have one design system (not multiple) that is adaptable and flexible enough to support diverse products with diverse users. + +Spectrum is approachable, friendly, and for the next generation of Adobe products. There's updated colors, icons, states, styles, and more. And, there's even more detailed guidance on design fundamentals like typography and layout. + +"Here's an example of how a Spectrum action button has changed over design language updates:" + +Spectrum is Adobe's design system. It belongs to all of us, and is shaped according to our customers' needs. We'd like to thank everyone who participated in shaping and testing Spectrum 2 for their hard and thoughtful work. + +## About Spectrum 2 + +"Here's an example of how a Spectrum action button has changed over design language updates:" + +## Using this documentation + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Home](/page/home/) +* [Principles](/page/principles/) diff --git a/docs/s2-docs/fundamentals/principles.md b/docs/s2-docs/fundamentals/principles.md new file mode 100644 index 00000000..e5f7950d --- /dev/null +++ b/docs/s2-docs/fundamentals/principles.md @@ -0,0 +1,52 @@ +--- + +title: "Principles" +source\_url: +last\_updated: 2026-02-02 +category: fundamentals +status: published +tags: + +* fundamentals + +--- + +# Principles + +Spectrum 2 is a major update that expands the meaning of the design system's [core principles](https://spectrum.corp.adobe.com/page/principles/). + +The foundational principles — **rational**, **human**, **focused** — have been updated to reflect the developments in how Spectrum has evolved and where it's going. We've also added a new principle — **collaborative** — to reflect how the design system has become something that's possible entirely because of the contributions and collaborations from all of Adobe. + +We think of and use these principles in a few ways: + +* The ideas on which Spectrum is built +* The considerations for building products at Adobe +* The criteria for validating decisions + +These principles aren't just for visual or interaction design. We extend them to engineering, writing, strategy, and all of the ways that we build products at Adobe. + +## Spectrum 2 principles + +### Rational + +Spectrum is based on real-world situations. Every component, pattern, and principle is informed by thoughtful testing. Every decision is backed by thorough interdisciplinary research. + +Spectrum is not a rigid set of rules for how to build products, but rather a set of adaptable resources for making experiences feel contextual, cohesive, and performant. + +### Human + +Spectrum places people's needs first. It's deeply committed to a high standard of inclusivity, accessibility, honesty, and respect. + +Spectrum is adaptable to meet as many user expectations, platform requirements, and product visions as possible. It's always what it needs to be, accommodating a flexible range of expression. It balances the human needs of utility and joy. + +### Focused + +Spectrum delivers what's needed, when it's needed. Every decoration is purposeful and meaningful. Every communication touchpoint is relevant. + +Spectrum experiences are built to a high standard of quality. Everything incorporates attention to details, and that creates experiences that look and feel well-crafted. Things are delightful to use because they balance functionality and expression. + +### Collaborative + +Spectrum belongs to everyone. It's a reflection of an ever-growing community that makes decisions thoughtfully, holistically, and collectively. + +Spectrum examines from multiple angles, then refines, then repeats. Constantly. diff --git a/docs/s2-docs/index.json b/docs/s2-docs/index.json new file mode 100644 index 00000000..db702bbb --- /dev/null +++ b/docs/s2-docs/index.json @@ -0,0 +1,500 @@ +{ + "generated": "2026-02-12T18:47:20.452Z", + "categories": { + "actions": [ + { + "slug": "action-bar", + "name": "Action Bar", + "url": "https://s2.spectrum.corp.adobe.com/page/action-bar/", + "file": "components/actions/action-bar.md", + "exists": true + }, + { + "slug": "action-button", + "name": "Action Button", + "url": "https://s2.spectrum.corp.adobe.com/page/action-button/", + "file": "components/actions/action-button.md", + "exists": true + }, + { + "slug": "action-group", + "name": "Action Group", + "url": "https://s2.spectrum.corp.adobe.com/page/action-group/", + "file": "components/actions/action-group.md", + "exists": true + }, + { + "slug": "button-group", + "name": "Button Group", + "url": "https://s2.spectrum.corp.adobe.com/page/button-group/", + "file": "components/actions/button-group.md", + "exists": true + }, + { + "slug": "button", + "name": "Button", + "url": "https://s2.spectrum.corp.adobe.com/page/button/", + "file": "components/actions/button.md", + "exists": true + }, + { + "slug": "close-button", + "name": "Close Button", + "url": "https://s2.spectrum.corp.adobe.com/page/close-button/", + "file": "components/actions/close-button.md", + "exists": true + }, + { + "slug": "link", + "name": "Link", + "url": "https://s2.spectrum.corp.adobe.com/page/link/", + "file": "components/actions/link.md", + "exists": true + }, + { + "slug": "list-view", + "name": "List View", + "url": "https://s2.spectrum.corp.adobe.com/page/list-view/", + "file": "components/actions/list-view.md", + "exists": true + }, + { + "slug": "menu", + "name": "Menu", + "url": "https://s2.spectrum.corp.adobe.com/page/menu/", + "file": "components/actions/menu.md", + "exists": true + } + ], + "containers": [ + { + "slug": "cards", + "name": "Cards", + "url": "https://s2.spectrum.corp.adobe.com/page/cards/", + "file": "components/containers/cards.md", + "exists": true + }, + { + "slug": "divider", + "name": "Divider", + "url": "https://s2.spectrum.corp.adobe.com/page/divider/", + "file": "components/containers/divider.md", + "exists": true + }, + { + "slug": "popover", + "name": "Popover", + "url": "https://s2.spectrum.corp.adobe.com/page/popover/", + "file": "components/containers/popover.md", + "exists": true + }, + { + "slug": "standard-panel", + "name": "Standard Panel", + "url": "https://s2.spectrum.corp.adobe.com/page/standard-panel/", + "file": "components/containers/standard-panel.md", + "exists": true + }, + { + "slug": "table", + "name": "Table", + "url": "https://s2.spectrum.corp.adobe.com/page/table/", + "file": "components/containers/table.md", + "exists": true + } + ], + "feedback": [ + { + "slug": "alert-banner", + "name": "Alert Banner", + "url": "https://s2.spectrum.corp.adobe.com/page/alert-banner/", + "file": "components/feedback/alert-banner.md", + "exists": true + }, + { + "slug": "alert-dialog", + "name": "Alert Dialog", + "url": "https://s2.spectrum.corp.adobe.com/page/alert-dialog/", + "file": "components/feedback/alert-dialog.md", + "exists": true + }, + { + "slug": "coach-indicator", + "name": "Coach Indicator", + "url": "https://s2.spectrum.corp.adobe.com/page/coach-indicator/", + "file": "components/feedback/coach-indicator.md", + "exists": true + }, + { + "slug": "coach-mark", + "name": "Coach Mark", + "url": "https://s2.spectrum.corp.adobe.com/page/coach-mark/", + "file": "components/feedback/coach-mark.md", + "exists": true + }, + { + "slug": "contextual-help", + "name": "Contextual Help", + "url": "https://s2.spectrum.corp.adobe.com/page/contextual-help/", + "file": "components/feedback/contextual-help.md", + "exists": true + }, + { + "slug": "illustrated-message", + "name": "Illustrated Message", + "url": "https://s2.spectrum.corp.adobe.com/page/illustrated-message/", + "file": "components/feedback/illustrated-message.md", + "exists": true + }, + { + "slug": "in-line-alert", + "name": "In Line Alert", + "url": "https://s2.spectrum.corp.adobe.com/page/in-line-alert/", + "file": "components/feedback/in-line-alert.md", + "exists": true + }, + { + "slug": "standard-dialog", + "name": "Standard Dialog", + "url": "https://s2.spectrum.corp.adobe.com/page/standard-dialog/", + "file": "components/feedback/standard-dialog.md", + "exists": true + }, + { + "slug": "takeover-dialog", + "name": "Takeover Dialog", + "url": "https://s2.spectrum.corp.adobe.com/page/takeover-dialog/", + "file": "components/feedback/takeover-dialog.md", + "exists": true + }, + { + "slug": "toast", + "name": "Toast", + "url": "https://s2.spectrum.corp.adobe.com/page/toast/", + "file": "components/feedback/toast.md", + "exists": true + }, + { + "slug": "tooltip", + "name": "Tooltip", + "url": "https://s2.spectrum.corp.adobe.com/page/tooltip/", + "file": "components/feedback/tooltip.md", + "exists": true + } + ], + "inputs": [ + { + "slug": "calendar", + "name": "Calendar", + "url": "https://s2.spectrum.corp.adobe.com/page/calendar/", + "file": "components/inputs/calendar.md", + "exists": true + }, + { + "slug": "checkbox-group", + "name": "Checkbox Group", + "url": "https://s2.spectrum.corp.adobe.com/page/checkbox-group/", + "file": "components/inputs/checkbox-group.md", + "exists": true + }, + { + "slug": "checkbox", + "name": "Checkbox", + "url": "https://s2.spectrum.corp.adobe.com/page/checkbox/", + "file": "components/inputs/checkbox.md", + "exists": true + }, + { + "slug": "color-area", + "name": "Color Area", + "url": "https://s2.spectrum.corp.adobe.com/page/color-area/", + "file": "components/inputs/color-area.md", + "exists": true + }, + { + "slug": "color-handle-and-loupe", + "name": "Color Handle And Loupe", + "url": "https://s2.spectrum.corp.adobe.com/page/color-handle-and-loupe/", + "file": "components/inputs/color-handle-and-loupe.md", + "exists": true + }, + { + "slug": "color-handle", + "name": "Color Handle", + "url": "https://s2.spectrum.corp.adobe.com/page/color-handle/", + "file": "components/inputs/color-handle.md", + "exists": true + }, + { + "slug": "color-slider", + "name": "Color Slider", + "url": "https://s2.spectrum.corp.adobe.com/page/color-slider/", + "file": "components/inputs/color-slider.md", + "exists": true + }, + { + "slug": "color-wheel", + "name": "Color Wheel", + "url": "https://s2.spectrum.corp.adobe.com/page/color-wheel/", + "file": "components/inputs/color-wheel.md", + "exists": true + }, + { + "slug": "combo-box", + "name": "Combo Box", + "url": "https://s2.spectrum.corp.adobe.com/page/combo-box/", + "file": "components/inputs/combo-box.md", + "exists": true + }, + { + "slug": "date-picker", + "name": "Date Picker", + "url": "https://s2.spectrum.corp.adobe.com/page/date-picker/", + "file": "components/inputs/date-picker.md", + "exists": true + }, + { + "slug": "drop-zone", + "name": "Drop Zone", + "url": "https://s2.spectrum.corp.adobe.com/page/drop-zone/", + "file": "components/inputs/drop-zone.md", + "exists": true + }, + { + "slug": "field-label", + "name": "Field Label", + "url": "https://s2.spectrum.corp.adobe.com/page/field-label/", + "file": "components/inputs/field-label.md", + "exists": true + }, + { + "slug": "help-text", + "name": "Help Text", + "url": "https://s2.spectrum.corp.adobe.com/page/help-text/", + "file": "components/inputs/help-text.md", + "exists": true + }, + { + "slug": "number-field", + "name": "Number Field", + "url": "https://s2.spectrum.corp.adobe.com/page/number-field/", + "file": "components/inputs/number-field.md", + "exists": true + }, + { + "slug": "picker", + "name": "Picker", + "url": "https://s2.spectrum.corp.adobe.com/page/picker/", + "file": "components/inputs/picker.md", + "exists": true + }, + { + "slug": "radio-button", + "name": "Radio Button", + "url": "https://s2.spectrum.corp.adobe.com/page/radio-button/", + "file": "components/inputs/radio-button.md", + "exists": true + }, + { + "slug": "radio-group", + "name": "Radio Group", + "url": "https://s2.spectrum.corp.adobe.com/page/radio-group/", + "file": "components/inputs/radio-group.md", + "exists": true + }, + { + "slug": "rating", + "name": "Rating", + "url": "https://s2.spectrum.corp.adobe.com/page/rating/", + "file": "components/inputs/rating.md", + "exists": true + }, + { + "slug": "search-field", + "name": "Search Field", + "url": "https://s2.spectrum.corp.adobe.com/page/search-field/", + "file": "components/inputs/search-field.md", + "exists": true + }, + { + "slug": "segmented-control", + "name": "Segmented Control", + "url": "https://s2.spectrum.corp.adobe.com/page/segmented-control/", + "file": "components/inputs/segmented-control.md", + "exists": true + }, + { + "slug": "select-box", + "name": "Select Box", + "url": "https://s2.spectrum.corp.adobe.com/page/select-box/", + "file": "components/inputs/select-box.md", + "exists": true + }, + { + "slug": "slider", + "name": "Slider", + "url": "https://s2.spectrum.corp.adobe.com/page/slider/", + "file": "components/inputs/slider.md", + "exists": true + }, + { + "slug": "swatch-group", + "name": "Swatch Group", + "url": "https://s2.spectrum.corp.adobe.com/page/swatch-group/", + "file": "components/inputs/swatch-group.md", + "exists": true + }, + { + "slug": "swatch", + "name": "Swatch", + "url": "https://s2.spectrum.corp.adobe.com/page/swatch/", + "file": "components/inputs/swatch.md", + "exists": true + }, + { + "slug": "switch", + "name": "Switch", + "url": "https://s2.spectrum.corp.adobe.com/page/switch/", + "file": "components/inputs/switch.md", + "exists": true + }, + { + "slug": "tag-field", + "name": "Tag Field", + "url": "https://s2.spectrum.corp.adobe.com/page/tag-field/", + "file": "components/inputs/tag-field.md", + "exists": true + }, + { + "slug": "tag-group", + "name": "Tag Group", + "url": "https://s2.spectrum.corp.adobe.com/page/tag-group/", + "file": "components/inputs/tag-group.md", + "exists": true + }, + { + "slug": "tag", + "name": "Tag", + "url": "https://s2.spectrum.corp.adobe.com/page/tag/", + "file": "components/inputs/tag.md", + "exists": true + }, + { + "slug": "text-area", + "name": "Text Area", + "url": "https://s2.spectrum.corp.adobe.com/page/text-area/", + "file": "components/inputs/text-area.md", + "exists": true + }, + { + "slug": "text-field", + "name": "Text Field", + "url": "https://s2.spectrum.corp.adobe.com/page/text-field/", + "file": "components/inputs/text-field.md", + "exists": true + }, + { + "slug": "thumbnail", + "name": "Thumbnail", + "url": "https://s2.spectrum.corp.adobe.com/page/thumbnail/", + "file": "components/inputs/thumbnail.md", + "exists": true + } + ], + "navigation": [ + { + "slug": "accordion", + "name": "Accordion", + "url": "https://s2.spectrum.corp.adobe.com/page/accordion/", + "file": "components/navigation/accordion.md", + "exists": true + }, + { + "slug": "breadcrumbs", + "name": "Breadcrumbs", + "url": "https://s2.spectrum.corp.adobe.com/page/breadcrumbs/", + "file": "components/navigation/breadcrumbs.md", + "exists": true + }, + { + "slug": "side-navigation", + "name": "Side Navigation", + "url": "https://s2.spectrum.corp.adobe.com/page/side-navigation/", + "file": "components/navigation/side-navigation.md", + "exists": true + }, + { + "slug": "tabs", + "name": "Tabs", + "url": "https://s2.spectrum.corp.adobe.com/page/tabs/", + "file": "components/navigation/tabs.md", + "exists": true + }, + { + "slug": "tree-view", + "name": "Tree View", + "url": "https://s2.spectrum.corp.adobe.com/page/tree-view/", + "file": "components/navigation/tree-view.md", + "exists": true + } + ], + "status": [ + { + "slug": "avatar-group", + "name": "Avatar Group", + "url": "https://s2.spectrum.corp.adobe.com/page/avatar-group/", + "file": "components/status/avatar-group.md", + "exists": true + }, + { + "slug": "avatar", + "name": "Avatar", + "url": "https://s2.spectrum.corp.adobe.com/page/avatar/", + "file": "components/status/avatar.md", + "exists": true + }, + { + "slug": "badge", + "name": "Badge", + "url": "https://s2.spectrum.corp.adobe.com/page/badge/", + "file": "components/status/badge.md", + "exists": true + }, + { + "slug": "meter", + "name": "Meter", + "url": "https://s2.spectrum.corp.adobe.com/page/meter/", + "file": "components/status/meter.md", + "exists": true + }, + { + "slug": "progress-bar", + "name": "Progress Bar", + "url": "https://s2.spectrum.corp.adobe.com/page/progress-bar/", + "file": "components/status/progress-bar.md", + "exists": true + }, + { + "slug": "progress-circle", + "name": "Progress Circle", + "url": "https://s2.spectrum.corp.adobe.com/page/progress-circle/", + "file": "components/status/progress-circle.md", + "exists": true + }, + { + "slug": "status-light", + "name": "Status Light", + "url": "https://s2.spectrum.corp.adobe.com/page/status-light/", + "file": "components/status/status-light.md", + "exists": true + }, + { + "slug": "steplist", + "name": "Steplist", + "url": "https://s2.spectrum.corp.adobe.com/page/steplist/", + "file": "components/status/steplist.md", + "exists": true + } + ] + } +} diff --git a/docs/s2-docs/moon.yml b/docs/s2-docs/moon.yml new file mode 100644 index 00000000..0868f4e9 --- /dev/null +++ b/docs/s2-docs/moon.yml @@ -0,0 +1,7 @@ +$schema: "https://moonrepo.dev/schemas/project.json" + +project: + name: "s2-docs" + description: "Spectrum 2 documentation" + type: "library" + language: "markdown" diff --git a/docs/s2-docs/support/faqs.md b/docs/s2-docs/support/faqs.md new file mode 100644 index 00000000..cf68f9c1 --- /dev/null +++ b/docs/s2-docs/support/faqs.md @@ -0,0 +1,72 @@ +--- + +title: "FAQs" +source\_url: +last\_updated: 2026-02-02 +category: support +status: published +tags: + +* support + related\_components: +* steplist +* contact + +--- + +# FAQs + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +As we progress, we're committed to extending Spectrum 2 to include desktop and mobile platforms with ongoing workshops and to ensure a comprehensive update to our design system. + +Though Spectrum has always made cross-platform design a priority, the majority of emerging products at Adobe have been web-first in recent years. + +That said, Adobe Design has been collectively working on the future of desktop and mobile. One of the central goals of Spectrum 2 is to make sure that it feels “at home.” Both professional desktop and mobile tools have a unique set of requirements and each will get the attention they require. + +In the meantime, we’ve been partnering with both desktop and mobile teams and preparing their implementations for Spectrum 2 by using Spectrum’s design data. We continue to expand the scope of our partnership as we build out Spectrum 2 and the toolchain to support it. + +Carve out time to plan for the update and create a migration plan. We recommend breaking down the update process into planned, manageable tasks in order to avoid a need to react to massive changes all at once. Prioritize areas of the code base that directly impact the UI, as well as the code that customizes, overrides, or otherwise changes Spectrum defaults. + +## What is Spectrum 2? + +Though Spectrum has always made cross-platform design a priority, the majority of emerging products at Adobe have been web-first in recent years. + +## When can I start to use Spectrum 2? + +Though Spectrum has always made cross-platform design a priority, the majority of emerging products at Adobe have been web-first in recent years. + +## What about Spectrum 2 for desktop or mobile platforms? + +Though Spectrum has always made cross-platform design a priority, the majority of emerging products at Adobe have been web-first in recent years. + +## Tips for designers + +## Tips for engineers + +## Tips for product managers + +## Tips for other roles + +## Where can I find Spectrum 2 components and styles in Figma? + +## Who should I reach out to if I have questions? + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Steplist](/page/steplist/) +* [Contact](/page/contact/) diff --git a/docs/s2-docs/support/resources.md b/docs/s2-docs/support/resources.md new file mode 100644 index 00000000..7d7edbf8 --- /dev/null +++ b/docs/s2-docs/support/resources.md @@ -0,0 +1,96 @@ +--- + +title: "Resources" +source\_url: +last\_updated: 2026-02-02 +category: support +status: published +tags: + +* support + related\_components: +* contact + +--- + +# Resources + +## Resources + +### Design + +* **Figma**: S2 Web + +## External links + +The Spectrum 2 Figma libraries are the primary resource for Spectrum 2 components, styles, and variables. These libraries are stable, so you can use the designs in production. + +"An example of the Spectrum 2 library: the action button page." + +This GitHub repository houses Spectrum’s design tokens, which are primarily name-value pairs used to store design decisions and distributed in a way that platforms, implementations, and products can use across design tools and coding languages. + +This tool allows you to search for token names or values, filter values by scale and theme, and explore the relationship between Spectrum’s tokens by selecting tokens to see their connections. + +To support this transition, S2/Color has been removed from the inheritance chain in the Figma libraries. Designers should update their files to replace color styles with color variables. Following the steps in the guide will help ensure your files remain stable and aligned with the Spectrum system moving forward. + +These changes are for Spectrum 2 libraries. They do not apply to Spectrum 1. + +To support the new font, we’ve updated our default line-height values and introduced symmetrical vertical padding token values to our design system. The Spectrum 2 typography guide includes details about what’s changing, what’s staying the same, and options for updating design files or implementations. + +These changes are for Spectrum 2 libraries and implementations. They do not apply to Spectrum 1 components. + +Spectrum 2 includes two new grays — gray-25 and gray-1000 — plus an update to the rest of the 11 grays. The migration guide goes into more detail about what’s changing and what’s staying the same. + +Creating interfaces that support right-to-left (RTL) and bi-directional (Bidi) languages is essential to ensuring that our products are inclusive of global audiences. These guides, created by the Adobe International team, offer comprehensive frameworks on how to design and build for both web and mobile components. + +The Adobe Design Brand team has created Spectrum 2-inspired desktop and mobile backgrounds for you to download. + +## Design resources + +"An example of the Spectrum 2 library: the action button page." + +These changes are for Spectrum 2 libraries. They do not apply to Spectrum 1. + +These changes are for Spectrum 2 libraries and implementations. They do not apply to Spectrum 1 components. + +The Adobe Design Brand team has created Spectrum 2-inspired desktop and mobile backgrounds for you to download. + +## Implementation resources + +These changes are for Spectrum 2 libraries. They do not apply to Spectrum 1. + +These changes are for Spectrum 2 libraries and implementations. They do not apply to Spectrum 1 components. + +The Adobe Design Brand team has created Spectrum 2-inspired desktop and mobile backgrounds for you to download. + +## Resources for product developers + +These changes are for Spectrum 2 libraries. They do not apply to Spectrum 1. + +These changes are for Spectrum 2 libraries and implementations. They do not apply to Spectrum 1 components. + +The Adobe Design Brand team has created Spectrum 2-inspired desktop and mobile backgrounds for you to download. + +## More resources + +These changes are for Spectrum 2 libraries. They do not apply to Spectrum 1. + +These changes are for Spectrum 2 libraries and implementations. They do not apply to Spectrum 1 components. + +The Adobe Design Brand team has created Spectrum 2-inspired desktop and mobile backgrounds for you to download. + +## Spectrum 2 swag + +The Adobe Design Brand team has created Spectrum 2-inspired desktop and mobile backgrounds for you to download. + +## Design tokens + +Use the [Spectrum Token Visualization Tool](https://opensource.adobe.com/spectrum-tokens/s2-visualizer/?filter=spectrum%2Clight%2Cdesktop) to review the tokens for this component. + +## Questions or feedback? + +Ask questions about this component by posting in [#spectrum-design](https://adobe.enterprise.slack.com/archives/C0B4ZDHEE) on Slack. Submit any feedback or file bugs (either about this component or its documentation) through Spectrum's [feedback form](https://adobe.enterprise.slack.com/lists/T024FSURM/F08FFP5MLHJ). + +## Related Components + +* [Contact](/page/contact/) diff --git a/package.json b/package.json index 330a46fa..bae8b8dd 100644 --- a/package.json +++ b/package.json @@ -37,6 +37,7 @@ "prettier": "^3.5.3", "remark": "^15.0.1", "remark-cli": "^12.0.1", + "remark-frontmatter": "^5.0.0", "remark-gfm": "^4.0.1", "remark-github": "^12.0.0" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4a3dad42..030d6ad4 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -46,6 +46,9 @@ importers: remark-cli: specifier: ^12.0.1 version: 12.0.1 + remark-frontmatter: + specifier: ^5.0.0 + version: 5.0.0 remark-gfm: specifier: ^4.0.1 version: 4.0.1 @@ -602,6 +605,21 @@ importers: specifier: ^6.0.0 version: 6.4.0(@ava/typescript@6.0.0)(rollup@4.44.1) + tools/s2-docs-mcp: + dependencies: + "@modelcontextprotocol/sdk": + specifier: ^0.5.0 + version: 0.5.0 + commander: + specifier: ^13.1.0 + version: 13.1.0 + + tools/s2-docs-transformer: + dependencies: + "@modelcontextprotocol/sdk": + specifier: ^1.0.4 + version: 1.26.0(zod@3.25.76) + tools/spectrum-design-data-mcp: dependencies: "@adobe/spectrum-component-api-schemas": @@ -1577,6 +1595,15 @@ packages: integrity: sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ==, } + "@hono/node-server@1.19.9": + resolution: + { + integrity: sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw==, + } + engines: { node: ">=18.14.1" } + peerDependencies: + hono: ^4 + "@humanfs/core@0.19.1": resolution: { @@ -1739,6 +1766,19 @@ packages: integrity: sha512-RXgulUX6ewvxjAG0kOpLMEdXXWkzWgaoCGaA2CwNW7cQCIphjpJhjpHSiaPdVCnisjRF/0Cm9KWHUuIoeiAblQ==, } + "@modelcontextprotocol/sdk@1.26.0": + resolution: + { + integrity: sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==, + } + engines: { node: ">=18" } + peerDependencies: + "@cfworker/json-schema": ^4.1.1 + zod: ^3.25 || ^4.0 + peerDependenciesMeta: + "@cfworker/json-schema": + optional: true + "@moonrepo/cli@1.39.1": resolution: { @@ -3314,6 +3354,13 @@ packages: } engines: { node: ^18.17.0 || >=20.5.0 } + accepts@2.0.0: + resolution: + { + integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==, + } + engines: { node: ">= 0.6" } + acorn-import-attributes@1.9.5: resolution: { @@ -3641,6 +3688,13 @@ packages: integrity: sha512-DRQrD6gJyy8FbiE4s+bDoXS9hiW3Vbx5uCdwvcCf3zLHL+Iv7LtGHLpr+GZV8rHG8tK766FGYBwRbu8pELTt+w==, } + body-parser@2.2.2: + resolution: + { + integrity: sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==, + } + engines: { node: ">=18" } + boolbase@1.0.0: resolution: { @@ -3707,6 +3761,20 @@ packages: monocart-coverage-reports: optional: true + call-bind-apply-helpers@1.0.2: + resolution: + { + integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==, + } + engines: { node: ">= 0.4" } + + call-bound@1.0.4: + resolution: + { + integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==, + } + engines: { node: ">= 0.4" } + callsites@3.1.0: resolution: { @@ -4056,6 +4124,13 @@ packages: integrity: sha512-I2hSBi7Vvs7BEuJDr5dDHfzb/Ruj3FyvFyh7KLilAjNQw3Be+xgqUBA2W6scVEcL0hL1dwPRtIqEPVUCKkSsyQ==, } + content-disposition@1.0.1: + resolution: + { + integrity: sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==, + } + engines: { node: ">=18" } + content-type@1.0.5: resolution: { @@ -4098,6 +4173,27 @@ packages: } engines: { node: ^12.20.0 || ^14.13.1 || >=16.0.0 } + cookie-signature@1.2.2: + resolution: + { + integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==, + } + engines: { node: ">=6.6.0" } + + cookie@0.7.2: + resolution: + { + integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==, + } + engines: { node: ">= 0.6" } + + cors@2.8.6: + resolution: + { + integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==, + } + engines: { node: ">= 0.10" } + cosmiconfig-typescript-loader@6.1.0: resolution: { @@ -4578,6 +4674,13 @@ packages: } engines: { node: ">=10" } + dunder-proto@1.0.1: + resolution: + { + integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==, + } + engines: { node: ">= 0.4" } + eastasianwidth@0.2.0: resolution: { @@ -4716,12 +4819,33 @@ packages: integrity: sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==, } + es-define-property@1.0.1: + resolution: + { + integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==, + } + engines: { node: ">= 0.4" } + + es-errors@1.3.0: + resolution: + { + integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==, + } + engines: { node: ">= 0.4" } + es-module-lexer@2.0.0: resolution: { integrity: sha512-5POEcUuZybH7IdmGsD8wlf0AI55wMecM9rVBTI/qEAy2c1kTOm3DjFYjrBdI2K3BaJjJYfYFeRtM0t9ssnRuxw==, } + es-object-atoms@1.1.1: + resolution: + { + integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==, + } + engines: { node: ">= 0.4" } + esbuild@0.21.5: resolution: { @@ -4916,6 +5040,20 @@ packages: } engines: { node: ">=0.8.x" } + eventsource-parser@3.0.6: + resolution: + { + integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==, + } + engines: { node: ">=18.0.0" } + + eventsource@3.0.7: + resolution: + { + integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==, + } + engines: { node: ">=18.0.0" } + execa@8.0.1: resolution: { @@ -4930,6 +5068,22 @@ packages: } engines: { node: ^18.19.0 || >=20.5.0 } + express-rate-limit@8.2.1: + resolution: + { + integrity: sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==, + } + engines: { node: ">= 16" } + peerDependencies: + express: ">= 4.11" + + express@5.2.1: + resolution: + { + integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==, + } + engines: { node: ">= 18" } + extend-shallow@2.0.1: resolution: { @@ -5006,6 +5160,12 @@ packages: integrity: sha512-GwLTyxkCXjXbxqIhTsMI2Nui8huMPtnxg7krajPJAjnEG/iiOS7i+zCtWGZR9G0NBKbXKh6X9m9UIsYX/N6vvQ==, } + fault@2.0.1: + resolution: + { + integrity: sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==, + } + fdir@6.5.0: resolution: { @@ -5066,6 +5226,13 @@ packages: } engines: { node: ">= 0.8" } + finalhandler@2.1.1: + resolution: + { + integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==, + } + engines: { node: ">= 18.0.0" } + find-duplicated-property-keys@1.2.9: resolution: { @@ -5147,6 +5314,13 @@ packages: } engines: { node: ">=14" } + format@0.2.2: + resolution: + { + integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==, + } + engines: { node: ">=0.4.x" } + formdata-polyfill@4.0.10: resolution: { @@ -5154,6 +5328,13 @@ packages: } engines: { node: ">=12.20.0" } + forwarded@0.2.0: + resolution: + { + integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==, + } + engines: { node: ">= 0.6" } + fresh@2.0.0: resolution: { @@ -5217,6 +5398,20 @@ packages: } engines: { node: ">=18" } + get-intrinsic@1.3.0: + resolution: + { + integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==, + } + engines: { node: ">= 0.4" } + + get-proto@1.0.1: + resolution: + { + integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==, + } + engines: { node: ">= 0.4" } + get-stream@8.0.1: resolution: { @@ -5270,6 +5465,7 @@ packages: { integrity: sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==, } + deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me hasBin: true glob@11.0.3: @@ -5278,6 +5474,7 @@ packages: integrity: sha512-2Nim7dha1KVkaiF4q6Dj+ngPPMdfvLJEOpZk/jKiUAkqKebpGAWQXAq9z1xu9HKu5lWfqw/FASuccEjyznjPaA==, } engines: { node: 20 || >=22 } + deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me hasBin: true global-directory@4.0.1: @@ -5308,6 +5505,13 @@ packages: } engines: { node: ">=18" } + gopd@1.2.0: + resolution: + { + integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==, + } + engines: { node: ">= 0.4" } + graceful-fs@4.2.11: resolution: { @@ -5343,6 +5547,13 @@ packages: } engines: { node: ">=8" } + has-symbols@1.1.0: + resolution: + { + integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==, + } + engines: { node: ">= 0.4" } + hasown@2.0.2: resolution: { @@ -5363,6 +5574,13 @@ packages: integrity: sha512-H/vuk5TEEVZwrR0lp2zed9OCo1uAILMlx0JEMgC26rzyJJ3N1v6XkwHHXJQdR2doSjcGPM6OKPYoJgf0plJ11Q==, } + hono@4.11.9: + resolution: + { + integrity: sha512-Eaw2YTGM6WOxA6CXbckaEvslr2Ne4NFsKrvc0v97JD5awbmeBLO5w9Ho9L9kmKonrwF9RJlW6BxT1PVv/agBHQ==, + } + engines: { node: ">=16.9.0" } + hosted-git-info@7.0.2: resolution: { @@ -5492,6 +5710,13 @@ packages: } engines: { node: ">=0.10.0" } + iconv-lite@0.7.2: + resolution: + { + integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==, + } + engines: { node: ">=0.10.0" } + icss-utils@5.1.0: resolution: { @@ -5598,6 +5823,20 @@ packages: } engines: { node: ">=10.13.0" } + ip-address@10.0.1: + resolution: + { + integrity: sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==, + } + engines: { node: ">= 12" } + + ipaddr.js@1.9.1: + resolution: + { + integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==, + } + engines: { node: ">= 0.10" } + irregular-plurals@3.5.0: resolution: { @@ -5855,6 +6094,12 @@ packages: } hasBin: true + jose@6.1.3: + resolution: + { + integrity: sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==, + } + js-string-escape@1.0.1: resolution: { @@ -5913,6 +6158,12 @@ packages: integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==, } + json-schema-typed@8.0.2: + resolution: + { + integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==, + } + json-stable-stringify-without-jsonify@1.0.1: resolution: { @@ -6279,6 +6530,13 @@ packages: } engines: { node: ^12.20.0 || ^14.13.1 || >=16.0.0 } + math-intrinsics@1.1.0: + resolution: + { + integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==, + } + engines: { node: ">= 0.4" } + maximatch@0.1.0: resolution: { @@ -6305,6 +6563,12 @@ packages: integrity: sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==, } + mdast-util-frontmatter@2.0.1: + resolution: + { + integrity: sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==, + } + mdast-util-gfm-autolink-literal@2.0.1: resolution: { @@ -6365,6 +6629,13 @@ packages: integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==, } + media-typer@1.1.0: + resolution: + { + integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==, + } + engines: { node: ">= 0.8" } + memoize@10.1.0: resolution: { @@ -6379,6 +6650,13 @@ packages: } engines: { node: ">=16.10" } + merge-descriptors@2.0.0: + resolution: + { + integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==, + } + engines: { node: ">=18" } + merge-stream@2.0.0: resolution: { @@ -6398,6 +6676,12 @@ packages: integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==, } + micromark-extension-frontmatter@2.0.0: + resolution: + { + integrity: sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==, + } + micromark-extension-gfm-autolink-literal@2.1.0: resolution: { @@ -6710,6 +6994,13 @@ packages: integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==, } + negotiator@1.0.0: + resolution: + { + integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==, + } + engines: { node: ">= 0.6" } + neo-async@2.6.2: resolution: { @@ -6901,6 +7192,20 @@ packages: chokidar: optional: true + object-assign@4.1.1: + resolution: + { + integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==, + } + engines: { node: ">=0.10.0" } + + object-inspect@1.13.4: + resolution: + { + integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==, + } + engines: { node: ">= 0.4" } + on-finished@2.4.1: resolution: { @@ -6908,6 +7213,12 @@ packages: } engines: { node: ">= 0.8" } + once@1.4.0: + resolution: + { + integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==, + } + onetime@6.0.0: resolution: { @@ -7138,6 +7449,12 @@ packages: } engines: { node: 20 || >=22 } + path-to-regexp@8.3.0: + resolution: + { + integrity: sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==, + } + path-type@4.0.0: resolution: { @@ -7187,6 +7504,13 @@ packages: } engines: { node: ">=6" } + pkce-challenge@5.0.1: + resolution: + { + integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==, + } + engines: { node: ">=16.20.0" } + pkg-dir@4.2.0: resolution: { @@ -7374,6 +7698,13 @@ packages: } engines: { node: ">=10" } + proxy-addr@2.0.7: + resolution: + { + integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==, + } + engines: { node: ">= 0.10" } + prr@1.0.1: resolution: { @@ -7394,6 +7725,13 @@ packages: } engines: { node: ">=6" } + qs@6.14.2: + resolution: + { + integrity: sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q==, + } + engines: { node: ">=0.6" } + quansync@0.2.10: resolution: { @@ -7426,6 +7764,13 @@ packages: } engines: { node: ">= 0.8" } + raw-body@3.0.2: + resolution: + { + integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==, + } + engines: { node: ">= 0.10" } + react-dom@18.3.1: resolution: { @@ -7497,6 +7842,12 @@ packages: } hasBin: true + remark-frontmatter@5.0.0: + resolution: + { + integrity: sha512-XTFYvNASMe5iPN0719nPrdItC9aU0ssC4v14mH1BCi1u0n1gAocqcujWUrByftZTbLhRtiKRyjYTSIOcr69UVQ==, + } + remark-gfm@4.0.1: resolution: { @@ -7631,6 +7982,13 @@ packages: engines: { node: ">=18.0.0", npm: ">=8.0.0" } hasBin: true + router@2.2.0: + resolution: + { + integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==, + } + engines: { node: ">= 18" } + run-parallel@1.2.0: resolution: { @@ -7715,6 +8073,13 @@ packages: integrity: sha512-Saa1xPByTTq2gdeFZYLLo+RFE35NHZkAbqZeWNd3BpzppeVisAqpDjcp8dyf6uIvEqJRd46jemmyA4iFIeVk8g==, } + serve-static@2.2.1: + resolution: + { + integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==, + } + engines: { node: ">= 18" } + setprototypeof@1.2.0: resolution: { @@ -7749,6 +8114,34 @@ packages: } engines: { node: ">= 0.4" } + side-channel-list@1.0.0: + resolution: + { + integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==, + } + engines: { node: ">= 0.4" } + + side-channel-map@1.0.1: + resolution: + { + integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==, + } + engines: { node: ">= 0.4" } + + side-channel-weakmap@1.0.2: + resolution: + { + integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==, + } + engines: { node: ">= 0.4" } + + side-channel@1.1.0: + resolution: + { + integrity: sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==, + } + engines: { node: ">= 0.4" } + signal-exit@4.1.0: resolution: { @@ -8115,6 +8508,7 @@ packages: integrity: sha512-5S7Va8hKfV7W5U6g3aYxXmlPoZVAwUMy9AOKyF2fVuZa2UD3qZjg578OrLRt8PcNN1PleVaL/5/yYATNL0ICUw==, } engines: { node: ">=18" } + deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me temp-dir@3.0.0: resolution: @@ -8315,6 +8709,13 @@ packages: } engines: { node: ">=14.16" } + type-is@2.0.1: + resolution: + { + integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==, + } + engines: { node: ">= 0.6" } + typedarray@0.0.6: resolution: { @@ -8543,6 +8944,13 @@ packages: } engines: { node: ^14.17.0 || ^16.13.0 || >=18.0.0 } + vary@1.1.2: + resolution: + { + integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==, + } + engines: { node: ">= 0.8" } + vfile-message@4.0.3: resolution: { @@ -8753,6 +9161,12 @@ packages: } engines: { node: ">=18" } + wrappy@1.0.2: + resolution: + { + integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==, + } + write-file-atomic@6.0.0: resolution: { @@ -8832,6 +9246,14 @@ packages: } engines: { node: ">=18" } + zod-to-json-schema@3.25.1: + resolution: + { + integrity: sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==, + } + peerDependencies: + zod: ^3.25 || ^4 + zod@3.25.76: resolution: { @@ -9445,6 +9867,10 @@ snapshots: "@floating-ui/utils@0.2.10": {} + "@hono/node-server@1.19.9(hono@4.11.9)": + dependencies: + hono: 4.11.9 + "@humanfs/core@0.19.1": {} "@humanfs/node@0.16.7": @@ -9559,6 +9985,28 @@ snapshots: raw-body: 3.0.0 zod: 3.25.76 + "@modelcontextprotocol/sdk@1.26.0(zod@3.25.76)": + dependencies: + "@hono/node-server": 1.19.9(hono@4.11.9) + ajv: 8.17.1 + ajv-formats: 3.0.1(ajv@8.17.1) + content-type: 1.0.5 + cors: 2.8.6 + cross-spawn: 7.0.6 + eventsource: 3.0.7 + eventsource-parser: 3.0.6 + express: 5.2.1 + express-rate-limit: 8.2.1(express@5.2.1) + hono: 4.11.9 + jose: 6.1.3 + json-schema-typed: 8.0.2 + pkce-challenge: 5.0.1 + raw-body: 3.0.0 + zod: 3.25.76 + zod-to-json-schema: 3.25.1(zod@3.25.76) + transitivePeerDependencies: + - supports-color + "@moonrepo/cli@1.39.1": dependencies: detect-libc: 2.0.4 @@ -10965,6 +11413,11 @@ snapshots: abbrev@3.0.1: {} + accepts@2.0.0: + dependencies: + mime-types: 3.0.2 + negotiator: 1.0.0 + acorn-import-attributes@1.9.5(acorn@8.15.0): dependencies: acorn: 8.15.0 @@ -11153,6 +11606,20 @@ snapshots: blueimp-md5@2.19.0: {} + body-parser@2.2.2: + dependencies: + bytes: 3.1.2 + content-type: 1.0.5 + debug: 4.4.3 + http-errors: 2.0.1 + iconv-lite: 0.7.2 + on-finished: 2.4.1 + qs: 6.14.2 + raw-body: 3.0.2 + type-is: 2.0.1 + transitivePeerDependencies: + - supports-color + boolbase@1.0.0: {} brace-expansion@1.1.12: @@ -11198,6 +11665,16 @@ snapshots: yargs: 17.7.2 yargs-parser: 21.1.1 + call-bind-apply-helpers@1.0.2: + dependencies: + es-errors: 1.3.0 + function-bind: 1.1.2 + + call-bound@1.0.4: + dependencies: + call-bind-apply-helpers: 1.0.2 + get-intrinsic: 1.3.0 + callsites@3.1.0: {} callsites@4.2.0: {} @@ -11395,6 +11872,8 @@ snapshots: tslib: 2.8.1 upper-case: 2.0.2 + content-disposition@1.0.1: {} + content-type@1.0.5: {} conventional-changelog-angular@7.0.0: @@ -11416,6 +11895,15 @@ snapshots: convert-to-spaces@2.0.1: {} + cookie-signature@1.2.2: {} + + cookie@0.7.2: {} + + cors@2.8.6: + dependencies: + object-assign: 4.1.1 + vary: 1.1.2 + cosmiconfig-typescript-loader@6.1.0(@types/node@22.15.33)(cosmiconfig@9.0.0(typescript@5.8.3))(typescript@5.8.3): dependencies: "@types/node": 22.15.33 @@ -11704,6 +12192,12 @@ snapshots: dotenv@8.6.0: {} + dunder-proto@1.0.1: + dependencies: + call-bind-apply-helpers: 1.0.2 + es-errors: 1.3.0 + gopd: 1.2.0 + eastasianwidth@0.2.0: {} ee-first@1.1.1: {} @@ -11756,8 +12250,16 @@ snapshots: dependencies: is-arrayish: 0.2.1 + es-define-property@1.0.1: {} + + es-errors@1.3.0: {} + es-module-lexer@2.0.0: {} + es-object-atoms@1.1.1: + dependencies: + es-errors: 1.3.0 + esbuild@0.21.5: optionalDependencies: "@esbuild/aix-ppc64": 0.21.5 @@ -11918,6 +12420,12 @@ snapshots: events@3.3.0: {} + eventsource-parser@3.0.6: {} + + eventsource@3.0.7: + dependencies: + eventsource-parser: 3.0.6 + execa@8.0.1: dependencies: cross-spawn: 7.0.6 @@ -11945,6 +12453,44 @@ snapshots: strip-final-newline: 4.0.0 yoctocolors: 2.1.2 + express-rate-limit@8.2.1(express@5.2.1): + dependencies: + express: 5.2.1 + ip-address: 10.0.1 + + express@5.2.1: + dependencies: + accepts: 2.0.0 + body-parser: 2.2.2 + content-disposition: 1.0.1 + content-type: 1.0.5 + cookie: 0.7.2 + cookie-signature: 1.2.2 + debug: 4.4.3 + depd: 2.0.0 + encodeurl: 2.0.0 + escape-html: 1.0.3 + etag: 1.8.1 + finalhandler: 2.1.1 + fresh: 2.0.0 + http-errors: 2.0.1 + merge-descriptors: 2.0.0 + mime-types: 3.0.2 + on-finished: 2.4.1 + once: 1.4.0 + parseurl: 1.3.3 + proxy-addr: 2.0.7 + qs: 6.14.2 + range-parser: 1.2.1 + router: 2.2.0 + send: 1.2.1 + serve-static: 2.2.1 + statuses: 2.0.2 + type-is: 2.0.1 + vary: 1.1.2 + transitivePeerDependencies: + - supports-color + extend-shallow@2.0.1: dependencies: is-extendable: 0.1.1 @@ -11983,6 +12529,10 @@ snapshots: dependencies: reusify: 1.1.0 + fault@2.0.1: + dependencies: + format: 0.2.2 + fdir@6.5.0(picomatch@4.0.3): optionalDependencies: picomatch: 4.0.3 @@ -12020,6 +12570,17 @@ snapshots: transitivePeerDependencies: - supports-color + finalhandler@2.1.1: + dependencies: + debug: 4.4.3 + encodeurl: 2.0.0 + escape-html: 1.0.3 + on-finished: 2.4.1 + parseurl: 1.3.3 + statuses: 2.0.2 + transitivePeerDependencies: + - supports-color + find-duplicated-property-keys@1.2.9: dependencies: chalk: 4.1.2 @@ -12068,10 +12629,14 @@ snapshots: cross-spawn: 7.0.6 signal-exit: 4.1.0 + format@0.2.2: {} + formdata-polyfill@4.0.10: dependencies: fetch-blob: 3.2.0 + forwarded@0.2.0: {} + fresh@2.0.0: {} fs-extra@10.1.0: @@ -12103,6 +12668,24 @@ snapshots: get-east-asian-width@1.3.0: {} + get-intrinsic@1.3.0: + dependencies: + call-bind-apply-helpers: 1.0.2 + es-define-property: 1.0.1 + es-errors: 1.3.0 + es-object-atoms: 1.1.1 + function-bind: 1.1.2 + get-proto: 1.0.1 + gopd: 1.2.0 + has-symbols: 1.1.0 + hasown: 2.0.2 + math-intrinsics: 1.1.0 + + get-proto@1.0.1: + dependencies: + dunder-proto: 1.0.1 + es-object-atoms: 1.1.1 + get-stream@8.0.1: {} get-stream@9.0.1: @@ -12172,6 +12755,8 @@ snapshots: slash: 5.1.0 unicorn-magic: 0.3.0 + gopd@1.2.0: {} + graceful-fs@4.2.11: {} gray-matter@4.0.3: @@ -12194,6 +12779,8 @@ snapshots: has-flag@4.0.0: {} + has-symbols@1.1.0: {} + hasown@2.0.2: dependencies: function-bind: 1.1.2 @@ -12205,6 +12792,8 @@ snapshots: capital-case: 1.0.4 tslib: 2.8.1 + hono@4.11.9: {} + hosted-git-info@7.0.2: dependencies: lru-cache: 10.4.3 @@ -12291,6 +12880,10 @@ snapshots: dependencies: safer-buffer: 2.1.2 + iconv-lite@0.7.2: + dependencies: + safer-buffer: 2.1.2 + icss-utils@5.1.0(postcss@8.5.6): dependencies: postcss: 8.5.6 @@ -12329,6 +12922,10 @@ snapshots: interpret@3.1.1: {} + ip-address@10.0.1: {} + + ipaddr.js@1.9.1: {} + irregular-plurals@3.5.0: {} is-alphabetical@2.0.1: {} @@ -12439,6 +13036,8 @@ snapshots: jiti@2.4.2: {} + jose@6.1.3: {} + js-string-escape@1.0.1: {} js-tokens@4.0.0: {} @@ -12462,6 +13061,8 @@ snapshots: json-schema-traverse@1.0.0: {} + json-schema-typed@8.0.2: {} + json-stable-stringify-without-jsonify@1.0.1: {} json5@2.2.3: {} @@ -12665,6 +13266,8 @@ snapshots: dependencies: escape-string-regexp: 5.0.0 + math-intrinsics@1.1.0: {} + maximatch@0.1.0: dependencies: array-differ: 1.0.0 @@ -12700,6 +13303,17 @@ snapshots: transitivePeerDependencies: - supports-color + mdast-util-frontmatter@2.0.1: + dependencies: + "@types/mdast": 4.0.4 + devlop: 1.1.0 + escape-string-regexp: 5.0.0 + mdast-util-from-markdown: 2.0.2 + mdast-util-to-markdown: 2.1.2 + micromark-extension-frontmatter: 2.0.0 + transitivePeerDependencies: + - supports-color + mdast-util-gfm-autolink-literal@2.0.1: dependencies: "@types/mdast": 4.0.4 @@ -12780,12 +13394,16 @@ snapshots: mdurl@2.0.0: {} + media-typer@1.1.0: {} + memoize@10.1.0: dependencies: mimic-function: 5.0.1 meow@12.1.1: {} + merge-descriptors@2.0.0: {} + merge-stream@2.0.0: {} merge2@1.4.1: {} @@ -12809,6 +13427,13 @@ snapshots: micromark-util-symbol: 2.0.1 micromark-util-types: 2.0.2 + micromark-extension-frontmatter@2.0.0: + dependencies: + fault: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + micromark-extension-gfm-autolink-literal@2.1.0: dependencies: micromark-util-character: 2.1.1 @@ -13040,6 +13665,8 @@ snapshots: natural-compare@1.4.0: {} + negotiator@1.0.0: {} + neo-async@2.6.2: {} next@14.2.30(react-dom@18.3.1(react@18.3.1))(react@18.3.1): @@ -13166,10 +13793,18 @@ snapshots: optionalDependencies: chokidar: 3.6.0 + object-assign@4.1.1: {} + + object-inspect@1.13.4: {} + on-finished@2.4.1: dependencies: ee-first: 1.1.1 + once@1.4.0: + dependencies: + wrappy: 1.0.2 + onetime@6.0.0: dependencies: mimic-fn: 4.0.0 @@ -13296,6 +13931,8 @@ snapshots: lru-cache: 11.1.0 minipass: 7.1.2 + path-to-regexp@8.3.0: {} + path-type@4.0.0: {} path-type@6.0.0: {} @@ -13310,6 +13947,8 @@ snapshots: pify@4.0.1: {} + pkce-challenge@5.0.1: {} + pkg-dir@4.2.0: dependencies: find-up: 4.1.0 @@ -13407,12 +14046,21 @@ snapshots: err-code: 2.0.3 retry: 0.12.0 + proxy-addr@2.0.7: + dependencies: + forwarded: 0.2.0 + ipaddr.js: 1.9.1 + prr@1.0.1: {} punycode.js@2.3.1: {} punycode@2.3.1: {} + qs@6.14.2: + dependencies: + side-channel: 1.1.0 + quansync@0.2.10: {} queue-microtask@1.2.3: {} @@ -13430,6 +14078,13 @@ snapshots: iconv-lite: 0.6.3 unpipe: 1.0.0 + raw-body@3.0.2: + dependencies: + bytes: 3.1.2 + http-errors: 2.0.1 + iconv-lite: 0.7.2 + unpipe: 1.0.0 + react-dom@18.3.1(react@18.3.1): dependencies: loose-envify: 1.4.0 @@ -13480,6 +14135,15 @@ snapshots: - bluebird - supports-color + remark-frontmatter@5.0.0: + dependencies: + "@types/mdast": 4.0.4 + mdast-util-frontmatter: 2.0.1 + micromark-extension-frontmatter: 2.0.0 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + remark-gfm@4.0.1: dependencies: "@types/mdast": 4.0.4 @@ -13596,6 +14260,16 @@ snapshots: "@rollup/rollup-win32-x64-msvc": 4.44.1 fsevents: 2.3.3 + router@2.2.0: + dependencies: + debug: 4.4.3 + depd: 2.0.0 + is-promise: 4.0.0 + parseurl: 1.3.3 + path-to-regexp: 8.3.0 + transitivePeerDependencies: + - supports-color + run-parallel@1.2.0: dependencies: queue-microtask: 1.2.3 @@ -13656,6 +14330,15 @@ snapshots: dependencies: randombytes: 2.1.0 + serve-static@2.2.1: + dependencies: + encodeurl: 2.0.0 + escape-html: 1.0.3 + parseurl: 1.3.3 + send: 1.2.1 + transitivePeerDependencies: + - supports-color + setprototypeof@1.2.0: {} shallow-clone@3.0.1: @@ -13670,6 +14353,34 @@ snapshots: shell-quote@1.8.3: {} + side-channel-list@1.0.0: + dependencies: + es-errors: 1.3.0 + object-inspect: 1.13.4 + + side-channel-map@1.0.1: + dependencies: + call-bound: 1.0.4 + es-errors: 1.3.0 + get-intrinsic: 1.3.0 + object-inspect: 1.13.4 + + side-channel-weakmap@1.0.2: + dependencies: + call-bound: 1.0.4 + es-errors: 1.3.0 + get-intrinsic: 1.3.0 + object-inspect: 1.13.4 + side-channel-map: 1.0.1 + + side-channel@1.1.0: + dependencies: + es-errors: 1.3.0 + object-inspect: 1.13.4 + side-channel-list: 1.0.0 + side-channel-map: 1.0.1 + side-channel-weakmap: 1.0.2 + signal-exit@4.1.0: {} skin-tone@2.0.0: @@ -13969,6 +14680,12 @@ snapshots: type-fest@3.13.1: {} + type-is@2.0.1: + dependencies: + content-type: 1.0.5 + media-typer: 1.1.0 + mime-types: 3.0.2 + typedarray@0.0.6: {} typescript-eslint@8.52.0(eslint@9.39.2(jiti@2.4.2))(typescript@4.9.5): @@ -14123,6 +14840,8 @@ snapshots: validate-npm-package-name@5.0.1: {} + vary@1.1.2: {} + vfile-message@4.0.3: dependencies: "@types/unist": 3.0.3 @@ -14278,6 +14997,8 @@ snapshots: string-width: 7.2.0 strip-ansi: 7.1.0 + wrappy@1.0.2: {} + write-file-atomic@6.0.0: dependencies: imurmurhash: 0.1.4 @@ -14309,6 +15030,10 @@ snapshots: yoctocolors@2.1.2: {} + zod-to-json-schema@3.25.1(zod@3.25.76): + dependencies: + zod: 3.25.76 + zod@3.25.76: {} zwitch@2.0.4: {} diff --git a/tools/s2-docs-mcp/README.md b/tools/s2-docs-mcp/README.md new file mode 100644 index 00000000..6f97e80f --- /dev/null +++ b/tools/s2-docs-mcp/README.md @@ -0,0 +1,161 @@ +# S2 Docs MCP Server + +A Model Context Protocol server that provides AI tools with access to Spectrum 2 documentation. Part of the [Spectrum Design Data](https://github.com/adobe/spectrum-design-data) monorepo. + +## Features + +* **Search components** by name, category, or content +* **Get component docs** with full formatting +* **Statistics** on scraped documentation +* **Find by use case** (e.g., "form input", "navigation") +* **List all components** by category + +## Installation + +```bash +cd ~/Spectrum/spectrum-design-data/tools/s2-docs-mcp +pnpm install +``` + +## Usage + +### Start the MCP Server + +```bash +pnpm start +``` + +Or add to your `.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "s2-docs": { + "command": "node", + "args": [ + "/Users/YOUR_USERNAME/Spectrum/spectrum-design-data/tools/s2-docs-mcp/src/cli.js" + ] + } + } +} +``` + +### Batch Scraping + +List all components: + +```bash +pnpm run scrape list +``` + +Parse a snapshot file: + +```bash +pnpm run scrape parse +``` + +Example: + +```bash +pnpm run scrape parse ~/.cursor/browser-logs/snapshot.log actions button +``` + +Generate component index (scans `docs/s2-docs/`): + +```bash +pnpm run scrape index +``` + +Check scraping status: + +```bash +pnpm run scrape report +``` + +## Available MCP Tools + +### `list-s2-components` + +List all available Spectrum 2 components, optionally filtered by category. + +**Parameters:** + +* `category` (optional): Filter by category (actions, containers, feedback, inputs, navigation, status) + +### `get-s2-component` + +Get full documentation for a specific component. + +**Parameters:** + +* `name` (required): Component name or slug +* `category` (optional): Component category for faster lookup + +### `search-s2-docs` + +Search documentation by component name or within content. + +**Parameters:** + +* `query` (required): Search query +* `searchContent` (optional, default: false): Search within component content + +### `get-s2-stats` + +Get statistics about scraped documentation coverage. + +### `find-s2-component-by-use-case` + +Find components by use case or design pattern. + +**Parameters:** + +* `useCase` (required): Use case description (e.g., "form input", "navigation") + +## Scraping Workflow + +1. **Use Cursor's scrape-s2-docs skill** to scrape components into `docs/s2-docs/` +2. **Regenerate index** after adding or updating docs: + ```bash + pnpm run scrape index + ``` +3. **Check status**: + ```bash + pnpm run scrape report + ``` +4. Start the MCP server to query docs + +## Data Location + +Documentation is read from: + +``` +spectrum-design-data/docs/s2-docs/ +├── components/ +├── designing/ +├── fundamentals/ +├── developing/ +├── support/ +└── index.json +``` + +See [docs/s2-docs/README.md](../../docs/s2-docs/README.md) for maintenance and transform scripts. + +## Using with Cursor + +* **MCP (this server)** – Add the s2-docs MCP server to `.cursor/mcp.json` (see [Usage](#usage) above). The AI can then use the tools to list, search, and fetch component docs on demand. +* **[**@Files**](https://github.com/Files) & Folders** – In chat, reference the `docs/s2-docs` folder (or a subfolder like `docs/s2-docs/components`) so the AI gets the markdown files as context. +* **[**@Docs**](https://github.com/Docs)** – If the S2 documentation is published at a URL, add it in Cursor via **[**@Docs**](https://github.com/Docs) → Add new doc** so Cursor indexes it. See [Cursor’s @Docs documentation](https://cursor.com/docs/context/mentions#docs). + +## Integration with spectrum-design-data-mcp + +This server complements the existing **spectrum-design-data-mcp** tool in this monorepo: + +* **spectrum-design-data-mcp**: Design tokens and component schemas +* **s2-docs-mcp**: S2 component documentation and design guidelines + +Both can run simultaneously in Cursor. + +## License + +Apache-2.0 © Adobe diff --git a/tools/s2-docs-mcp/moon.yml b/tools/s2-docs-mcp/moon.yml new file mode 100644 index 00000000..21f5a778 --- /dev/null +++ b/tools/s2-docs-mcp/moon.yml @@ -0,0 +1,21 @@ +$schema: "https://moonrepo.dev/schemas/project.json" + +project: + name: "s2-docs-mcp" + description: "MCP server for S2 documentation" + type: "tool" + language: "javascript" + +tasks: + build: + command: 'echo "No build required for MCP server"' + + index: + command: "node src/batch-scraper.js index" + inputs: + - "../../docs/s2-docs/**/*.md" + outputs: + - "../../docs/s2-docs/index.json" + + report: + command: "node src/batch-scraper.js report" diff --git a/tools/s2-docs-mcp/package.json b/tools/s2-docs-mcp/package.json new file mode 100644 index 00000000..fb82d46c --- /dev/null +++ b/tools/s2-docs-mcp/package.json @@ -0,0 +1,49 @@ +{ + "name": "@adobe/s2-docs-mcp", + "version": "0.0.0", + "description": "MCP server for Spectrum 2 documentation", + "type": "module", + "main": "./src/index.js", + "bin": { + "s2-docs-mcp": "./src/cli.js" + }, + "files": [ + "src/", + "README.md", + "LICENSE" + ], + "scripts": { + "start": "node src/cli.js", + "scrape": "node src/batch-scraper.js" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/adobe/spectrum-design-data.git", + "directory": "tools/s2-docs-mcp" + }, + "bugs": { + "url": "https://github.com/adobe/spectrum-design-data/issues" + }, + "homepage": "https://github.com/adobe/spectrum-design-data/tree/main/tools/s2-docs-mcp#readme", + "publishConfig": { + "access": "public", + "registry": "https://registry.npmjs.org/", + "provenance": true + }, + "dependencies": { + "@modelcontextprotocol/sdk": "^0.5.0", + "commander": "^13.1.0" + }, + "engines": { + "node": ">=20.12.0" + }, + "keywords": [ + "mcp", + "spectrum", + "s2", + "documentation", + "design-system" + ], + "author": "Adobe", + "license": "Apache-2.0" +} diff --git a/tools/s2-docs-mcp/src/batch-scraper.js b/tools/s2-docs-mcp/src/batch-scraper.js new file mode 100755 index 00000000..287c8a7c --- /dev/null +++ b/tools/s2-docs-mcp/src/batch-scraper.js @@ -0,0 +1,253 @@ +#!/usr/bin/env node + +/** + * S2 Documentation Batch Scraper + * Scrapes all components from s2.spectrum.corp.adobe.com + */ + +import { + readFileSync, + writeFileSync, + mkdirSync, + existsSync, + readdirSync, +} from "fs"; +import { join, dirname } from "path"; +import { homedir } from "os"; +import { execSync } from "child_process"; + +const BASE_URL = "https://s2.spectrum.corp.adobe.com"; +const OUTPUT_DIR = join( + homedir(), + "Spectrum", + "spectrum-design-data", + "docs", + "s2-docs", +); +const PARSER_SCRIPT = join( + homedir(), + ".cursor", + "skills", + "scrape-s2-docs", + "scripts", + "parse-s2-snapshot.mjs", +); + +// Component list by category +const COMPONENTS = { + actions: [ + "action-bar", + "action-button", + "action-group", + "button", + "button-group", + "close-button", + "link", + "list-view", + "menu", + ], + containers: ["dialog", "popover", "card", "divider", "tray"], + feedback: ["alert", "progress-bar", "progress-circle", "toast", "meter"], + inputs: [ + "checkbox", + "checkbox-group", + "color-area", + "color-field", + "color-slider", + "color-swatch", + "color-wheel", + "combo-box", + "number-field", + "picker", + "radio-group", + "search-field", + "slider", + "switch", + "text-area", + "text-field", + ], + navigation: ["breadcrumbs", "pagination", "tabs", "tree-view"], + status: ["badge", "tag", "status-light"], +}; + +/** + * Instructions for manual browser scraping + */ +function printInstructions() { + console.log("\n📋 S2 Documentation Batch Scraper\n"); + console.log( + "This tool requires manual browser interaction via Cursor's browser MCP.\n", + ); + console.log("Steps:\n"); + console.log( + "1. Ensure you're connected to Adobe VPN or have certificate installed", + ); + console.log("2. Open Cursor and use browser MCP to navigate to S2 docs"); + console.log( + "3. For each component, take a snapshot and note the file path\n", + ); + console.log("Component list:"); + + let total = 0; + Object.entries(COMPONENTS).forEach(([category, components]) => { + console.log(`\n${category.toUpperCase()} (${components.length}):`); + components.forEach((slug) => { + console.log(` - ${slug}: ${BASE_URL}/page/${slug}/`); + total++; + }); + }); + + console.log(`\nTotal: ${total} components\n`); + console.log( + "Automated scraping not possible due to authentication requirements.", + ); + console.log("Use Cursor's scrape-s2-docs skill to scrape components.\n"); +} + +/** + * Parse a single snapshot file + */ +function parseSnapshot(snapshotPath, componentUrl, outputPath) { + try { + const command = `node "${PARSER_SCRIPT}" "${snapshotPath}" "${componentUrl}"`; + const markdown = execSync(command, { encoding: "utf-8" }); + + // Ensure output directory exists + mkdirSync(dirname(outputPath), { recursive: true }); + + // Write markdown file + writeFileSync(outputPath, markdown, "utf-8"); + + return true; + } catch (error) { + console.error(`Failed to parse ${snapshotPath}:`, error.message); + return false; + } +} + +/** + * Generate component index by scanning components directory (includes all scraped files) + */ +function generateIndex() { + const indexPath = join(OUTPUT_DIR, "index.json"); + const index = { + generated: new Date().toISOString(), + categories: {}, + }; + + const componentsDir = join(OUTPUT_DIR, "components"); + if (existsSync(componentsDir)) { + const categories = readdirSync(componentsDir, { withFileTypes: true }) + .filter((e) => e.isDirectory()) + .map((e) => e.name); + for (const category of categories) { + const categoryPath = join(componentsDir, category); + const files = readdirSync(categoryPath) + .filter((f) => f.endsWith(".md")) + .map((f) => f.replace(/\.md$/, "")); + index.categories[category] = files.map((slug) => ({ + slug, + name: slug + .split("-") + .map((w) => w.charAt(0).toUpperCase() + w.slice(1)) + .join(" "), + url: `${BASE_URL}/page/${slug}/`, + file: `components/${category}/${slug}.md`, + exists: true, + })); + } + } + + writeFileSync(indexPath, JSON.stringify(index, null, 2), "utf-8"); + const total = Object.values(index.categories).reduce( + (n, arr) => n + arr.length, + 0, + ); + console.log(`\n✅ Generated index: ${indexPath} (${total} components)`); + + return index; +} + +/** + * Generate scraping status report + */ +function generateReport() { + const index = generateIndex(); + + let total = 0; + let scraped = 0; + let missing = []; + + Object.entries(index.categories).forEach(([category, components]) => { + components.forEach((comp) => { + total++; + if (comp.exists) { + scraped++; + } else { + missing.push(`${category}/${comp.slug}`); + } + }); + }); + + console.log("\n📊 Scraping Status Report\n"); + console.log(`Total components: ${total}`); + console.log(`Scraped: ${scraped} (${Math.round((scraped / total) * 100)}%)`); + console.log(`Missing: ${total - scraped}\n`); + + if (missing.length > 0) { + console.log("Missing components:"); + missing.forEach((comp) => console.log(` - ${comp}`)); + } +} + +// Main execution +const command = process.argv[2]; + +switch (command) { + case "list": + printInstructions(); + break; + + case "parse": + if (process.argv.length < 5) { + console.error( + "Usage: s2-docs-mcp scrape parse ", + ); + console.error( + "Example: s2-docs-mcp scrape parse snapshot.log actions button", + ); + process.exit(1); + } + const snapshotPath = process.argv[3]; + const category = process.argv[4]; + const slug = process.argv[5]; + const componentUrl = `${BASE_URL}/page/${slug}/`; + const outputPath = join(OUTPUT_DIR, "components", category, `${slug}.md`); + + if (parseSnapshot(snapshotPath, componentUrl, outputPath)) { + console.log(`✅ Parsed: ${outputPath}`); + } else { + process.exit(1); + } + break; + + case "index": + generateIndex(); + break; + + case "report": + generateReport(); + break; + + default: + console.log("S2 Documentation Batch Scraper\n"); + console.log("Commands:"); + console.log(" list - List all components to scrape"); + console.log(" parse - Parse a snapshot file"); + console.log(" index - Generate component index"); + console.log(" report - Generate scraping status report"); + console.log("\nExamples:"); + console.log(" npm run scrape list"); + console.log(" npm run scrape parse snapshot.log actions button"); + console.log(" npm run scrape report"); +} diff --git a/tools/s2-docs-mcp/src/cli.js b/tools/s2-docs-mcp/src/cli.js new file mode 100755 index 00000000..1da34b6e --- /dev/null +++ b/tools/s2-docs-mcp/src/cli.js @@ -0,0 +1,20 @@ +#!/usr/bin/env node + +/* +Copyright 2024 Adobe. All rights reserved. +This file is licensed to you under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. You may obtain a copy +of the License at http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software distributed under +the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS +OF ANY KIND, either express or implied. See the License for the specific language +governing permissions and limitations under the License. +*/ + +import { startServer } from "./index.js"; + +startServer().catch((error) => { + console.error("Failed to start S2 Docs MCP server:", error); + process.exit(1); +}); diff --git a/tools/s2-docs-mcp/src/data/docs.js b/tools/s2-docs-mcp/src/data/docs.js new file mode 100644 index 00000000..9a8789db --- /dev/null +++ b/tools/s2-docs-mcp/src/data/docs.js @@ -0,0 +1,170 @@ +/** + * S2 Documentation Data Access + */ + +import { readFileSync, readdirSync, existsSync } from "fs"; +import { join } from "path"; +import { homedir } from "os"; + +const DOCS_DIR = join( + homedir(), + "Spectrum", + "spectrum-design-data", + "docs", + "s2-docs", +); + +/** + * Load component index + */ +export function loadIndex() { + const indexPath = join(DOCS_DIR, "index.json"); + if (!existsSync(indexPath)) { + return { categories: {} }; + } + return JSON.parse(readFileSync(indexPath, "utf-8")); +} + +/** + * Get list of all components + */ +export function getAllComponents() { + const index = loadIndex(); + const components = []; + + Object.entries(index.categories || {}).forEach(([category, items]) => { + items.forEach((comp) => { + if (comp.exists) { + components.push({ + ...comp, + category, + }); + } + }); + }); + + return components; +} + +/** + * Get components by category + */ +export function getComponentsByCategory(category) { + const index = loadIndex(); + return (index.categories[category] || []).filter((comp) => comp.exists); +} + +/** + * Get component documentation + */ +export function getComponentDoc(category, slug) { + const filePath = join(DOCS_DIR, "components", category, `${slug}.md`); + + if (!existsSync(filePath)) { + throw new Error(`Component not found: ${category}/${slug}`); + } + + return readFileSync(filePath, "utf-8"); +} + +/** + * Search components by query + */ +export function searchComponents(query) { + const lowerQuery = query.toLowerCase(); + const components = getAllComponents(); + + return components.filter( + (comp) => + comp.name.toLowerCase().includes(lowerQuery) || + comp.slug.toLowerCase().includes(lowerQuery) || + comp.category.toLowerCase().includes(lowerQuery), + ); +} + +/** + * Search in component content + */ +export function searchInContent(query) { + const lowerQuery = query.toLowerCase(); + const components = getAllComponents(); + const results = []; + + components.forEach((comp) => { + try { + const content = getComponentDoc(comp.category, comp.slug); + if (content.toLowerCase().includes(lowerQuery)) { + // Extract context around the match + const lines = content.split("\n"); + const matchingLines = lines + .map((line, index) => ({ line, index })) + .filter(({ line }) => line.toLowerCase().includes(lowerQuery)) + .slice(0, 3); // Limit to 3 matches per component + + results.push({ + component: comp, + matches: matchingLines.map(({ line, index }) => ({ + line: line.trim(), + lineNumber: index + 1, + })), + }); + } + } catch (error) { + // Skip if file not found + } + }); + + return results; +} + +/** + * Get component by name (fuzzy match) + */ +export function findComponentByName(name) { + const components = getAllComponents(); + const lowerName = name.toLowerCase(); + + // Try exact match first + let match = components.find( + (c) => c.name.toLowerCase() === lowerName || c.slug === lowerName, + ); + + // Try partial match + if (!match) { + match = components.find( + (c) => + c.name.toLowerCase().includes(lowerName) || c.slug.includes(lowerName), + ); + } + + return match; +} + +/** + * Get statistics + */ +export function getStats() { + const index = loadIndex(); + let total = 0; + let scraped = 0; + const byCategory = {}; + + Object.entries(index.categories || {}).forEach(([category, components]) => { + const existing = components.filter((c) => c.exists); + byCategory[category] = { + total: components.length, + scraped: existing.length, + percentage: Math.round((existing.length / components.length) * 100), + }; + total += components.length; + scraped += existing.length; + }); + + return { + total, + scraped, + missing: total - scraped, + percentage: Math.round((scraped / total) * 100), + byCategory, + }; +} diff --git a/tools/s2-docs-mcp/src/index.js b/tools/s2-docs-mcp/src/index.js new file mode 100644 index 00000000..4cbe38ac --- /dev/null +++ b/tools/s2-docs-mcp/src/index.js @@ -0,0 +1,96 @@ +/* +Copyright 2024 Adobe. All rights reserved. +This file is licensed to you under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. You may obtain a copy +of the License at http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software distributed under +the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS +OF ANY KIND, either express or implied. See the License for the specific language +governing permissions and limitations under the License. +*/ + +import { Server } from "@modelcontextprotocol/sdk/server/index.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { + CallToolRequestSchema, + ListToolsRequestSchema, +} from "@modelcontextprotocol/sdk/types.js"; + +import { createDocsTools } from "./tools/docs.js"; + +/** + * Create and configure the S2 Docs MCP server + * @returns {Server} Configured MCP server instance + */ +export function createMCPServer() { + const server = new Server( + { + name: "s2-docs", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + }, + }, + ); + + // Get all available tools + const allTools = createDocsTools(); + + // Register list_tools handler + server.setRequestHandler(ListToolsRequestSchema, async () => { + return { + tools: allTools.map((tool) => ({ + name: tool.name, + description: tool.description, + inputSchema: tool.inputSchema, + })), + }; + }); + + // Register call_tool handler + server.setRequestHandler(CallToolRequestSchema, async (request) => { + const { name, arguments: args } = request.params; + + const tool = allTools.find((t) => t.name === name); + if (!tool) { + throw new Error(`Tool not found: ${name}`); + } + + try { + const result = await tool.handler(args || {}); + return { + content: [ + { + type: "text", + text: + typeof result === "string" + ? result + : JSON.stringify(result, null, 2), + }, + ], + }; + } catch (error) { + throw new Error(`Tool execution failed: ${error.message}`); + } + }); + + return server; +} + +/** + * Start the MCP server with stdio transport + */ +export async function startServer() { + const server = createMCPServer(); + const transport = new StdioServerTransport(); + await server.connect(transport); + + // Log server start for debugging (this goes to stderr, not stdout which is used for MCP) + console.error("S2 Docs MCP server started"); +} + +// Export for testing +export { createDocsTools }; diff --git a/tools/s2-docs-mcp/src/tools/docs.js b/tools/s2-docs-mcp/src/tools/docs.js new file mode 100644 index 00000000..1b68108a --- /dev/null +++ b/tools/s2-docs-mcp/src/tools/docs.js @@ -0,0 +1,238 @@ +/** + * S2 Documentation MCP Tools + */ + +import { + getAllComponents, + getComponentsByCategory, + getComponentDoc, + searchComponents, + searchInContent, + findComponentByName, + getStats, +} from "../data/docs.js"; + +export function createDocsTools() { + return [ + { + name: "list-s2-components", + description: "List all available Spectrum 2 components", + inputSchema: { + type: "object", + properties: { + category: { + type: "string", + description: + "Filter by category (actions, containers, feedback, inputs, navigation, status)", + enum: [ + "actions", + "containers", + "feedback", + "inputs", + "navigation", + "status", + ], + }, + }, + }, + handler: async (args) => { + if (args.category) { + const components = getComponentsByCategory(args.category); + return { + category: args.category, + count: components.length, + components: components.map((c) => ({ + name: c.name, + slug: c.slug, + url: c.url, + })), + }; + } + + const components = getAllComponents(); + const byCategory = components.reduce((acc, comp) => { + if (!acc[comp.category]) acc[comp.category] = []; + acc[comp.category].push({ + name: comp.name, + slug: comp.slug, + }); + return acc; + }, {}); + + return { + total: components.length, + categories: byCategory, + }; + }, + }, + + { + name: "get-s2-component", + description: "Get documentation for a specific Spectrum 2 component", + inputSchema: { + type: "object", + properties: { + name: { + type: "string", + description: + 'Component name (e.g., "Button", "Action Button") or slug (e.g., "button", "action-button")', + }, + category: { + type: "string", + description: "Component category (optional, helps with lookup)", + }, + }, + required: ["name"], + }, + handler: async (args) => { + const component = findComponentByName(args.name); + + if (!component) { + throw new Error(`Component not found: ${args.name}`); + } + + const content = getComponentDoc(component.category, component.slug); + + return { + component: { + name: component.name, + slug: component.slug, + category: component.category, + url: component.url, + }, + documentation: content, + }; + }, + }, + + { + name: "search-s2-docs", + description: + "Search Spectrum 2 documentation by component name or content", + inputSchema: { + type: "object", + properties: { + query: { + type: "string", + description: "Search query", + }, + searchContent: { + type: "boolean", + description: + "Search within component content (slower but more thorough)", + default: false, + }, + }, + required: ["query"], + }, + handler: async (args) => { + if (args.searchContent) { + const results = searchInContent(args.query); + return { + query: args.query, + found: results.length, + results: results.map((r) => ({ + component: r.component.name, + category: r.component.category, + slug: r.component.slug, + matches: r.matches, + })), + }; + } + + const components = searchComponents(args.query); + return { + query: args.query, + found: components.length, + components: components.map((c) => ({ + name: c.name, + slug: c.slug, + category: c.category, + url: c.url, + })), + }; + }, + }, + + { + name: "get-s2-stats", + description: "Get statistics about scraped S2 documentation", + inputSchema: { + type: "object", + properties: {}, + }, + handler: async () => { + return getStats(); + }, + }, + + { + name: "find-s2-component-by-use-case", + description: "Find S2 components by use case or design pattern", + inputSchema: { + type: "object", + properties: { + useCase: { + type: "string", + description: + 'Use case or design pattern (e.g., "form input", "navigation", "feedback", "selection")', + }, + }, + required: ["useCase"], + }, + handler: async (args) => { + // Map common use cases to categories + const useCaseMap = { + form: "inputs", + input: "inputs", + selection: "inputs", + navigation: "navigation", + nav: "navigation", + action: "actions", + button: "actions", + click: "actions", + feedback: "feedback", + notification: "feedback", + alert: "feedback", + progress: "feedback", + container: "containers", + layout: "containers", + overlay: "containers", + status: "status", + badge: "status", + indicator: "status", + }; + + const lowerUseCase = args.useCase.toLowerCase(); + const matchedCategory = Object.entries(useCaseMap).find(([key]) => + lowerUseCase.includes(key), + )?.[1]; + + if (matchedCategory) { + const components = getComponentsByCategory(matchedCategory); + return { + useCase: args.useCase, + suggestedCategory: matchedCategory, + components: components.map((c) => ({ + name: c.name, + slug: c.slug, + description: `Component in ${matchedCategory} category`, + })), + }; + } + + // Fall back to content search + const results = searchInContent(args.useCase); + return { + useCase: args.useCase, + found: results.length, + components: results.slice(0, 5).map((r) => ({ + name: r.component.name, + category: r.component.category, + relevantContent: r.matches[0]?.line, + })), + }; + }, + }, + ]; +} diff --git a/tools/s2-docs-transformer/README.md b/tools/s2-docs-transformer/README.md new file mode 100644 index 00000000..c784f5c4 --- /dev/null +++ b/tools/s2-docs-transformer/README.md @@ -0,0 +1,201 @@ +# S2 Docs Transformer + +Tools for scraping and transforming Spectrum 2 documentation. Part of the [Spectrum Design Data](https://github.com/adobe/spectrum-design-data) monorepo. + +## Overview + +This package provides utilities for: + +* **Scraping** S2 documentation from s2.spectrum.corp.adobe.com +* **Transforming** markdown files to add YAML frontmatter +* **Adding metadata** like related components and tags +* **Maintaining** consistency across all S2 docs + +## Installation + +```bash +cd ~/Spectrum/spectrum-design-data/tools/s2-docs-transformer +pnpm install +``` + +## Tools + +### 1. Scraper (Browser-based) + +Scrape S2 documentation using your authenticated browser session. + +**List all components:** + +```bash +pnpm run list +``` + +**Scrape a single component:** + +```bash +pnpm run scrape button actions +pnpm run scrape text-field inputs +``` + +**Scrape all components:** + +```bash +pnpm run scrape-all +``` + +**How it works:** + +* Uses cursor-browser-extension MCP to access your Chrome session +* Navigates to S2 docs (requires VPN/certificate) +* Extracts content and converts to markdown +* Saves to `docs/s2-docs/components/` + +See [SCRAPING.md](SCRAPING.md) for detailed scraping workflow. + +### 2. Transform to Frontmatter + +Convert markdown files to use YAML frontmatter with proper source URLs. + +```bash +pnpm run transform +``` + +**What it does:** + +* Converts blockquote metadata ("> Last updated") to YAML frontmatter +* Sets correct `source_url` from file path +* Adds `title`, `category`, `component_type`, `tags`, `status` +* Removes "On this page" TOC sections +* Removes HTML comments and duplicate content blocks +* Idempotent (safe to run multiple times) + +### 3. Add Related Metadata + +Parse "Related Components" sections and add to frontmatter. + +```bash +pnpm run add-metadata +``` + +**What it does:** + +* Extracts component links from "## Related Components" section +* Adds `related_components` array to frontmatter +* Adds `parent_category` for component docs +* Only updates files that have related links + +### 4. Process All + +Run complete transformation pipeline: + +```bash +pnpm run process-all +``` + +Runs: transform → add-metadata + +## File Structure + +``` +tools/s2-docs-transformer/ +├── scripts/ +│ ├── transform-to-frontmatter.js # Convert to YAML frontmatter +│ └── add-related-metadata.js # Add relationship metadata +├── src/ +│ ├── cli.js # Scraper CLI +│ ├── scraper.js # Main scraping logic +│ ├── parser.js # S2 page parsing +│ └── browser-client.js # Browser MCP client +├── SCRAPING.md # Scraping documentation +├── package.json +└── README.md +``` + +## Workflow + +### Scraping New Components + +1. **Connect to VPN** (if needed for s2.spectrum.corp.adobe.com) +2. **Open Chrome** with cursor-browser-extension +3. **Scrape component:** + ```bash + pnpm run scrape button actions + ``` +4. **Transform frontmatter:** + ```bash + pnpm run process-all + ``` +5. **Regenerate index:** + ```bash + cd ../s2-docs-mcp + node src/batch-scraper.js index + ``` + +### Updating Existing Docs + +If you manually edit markdown files and need to fix frontmatter: + +```bash +# Re-process all docs +pnpm run process-all + +# Regenerate component index +cd ../s2-docs-mcp +pnpm run scrape index +``` + +### Complete Re-scrape + +To refresh all documentation from the live site: + +1. **Backup current docs:** + ```bash + cp -r ../../docs/s2-docs ../../docs/s2-docs.backup + ``` + +2. **Scrape all components:** + ```bash + pnpm run scrape-all + ``` + +3. **Process frontmatter:** + ```bash + pnpm run process-all + ``` + +4. **Regenerate index:** + ```bash + cd ../s2-docs-mcp + pnpm run scrape index + ``` + +## Scripts Reference + +### transform-to-frontmatter.js + +Transforms markdown files in `docs/s2-docs/`: + +* **Input:** Files with blockquote metadata or old frontmatter +* **Output:** Files with standardized YAML frontmatter +* **Idempotent:** Safe to run multiple times + +### add-related-metadata.js + +Enhances frontmatter with relationships: + +* **Input:** Files with "## Related Components" section +* **Output:** Frontmatter with `related_components` and `parent_category` +* **Idempotent:** Safe to run multiple times + +## Integration + +Works with: + +* **docs/s2-docs/**: Documentation content +* **tools/s2-docs-mcp/**: MCP server that reads the docs + +After transforming, the MCP server can query the enhanced metadata. + +## License + +Apache-2.0 © Adobe diff --git a/tools/s2-docs-transformer/SCRAPING.md b/tools/s2-docs-transformer/SCRAPING.md new file mode 100644 index 00000000..1b8ef91d --- /dev/null +++ b/tools/s2-docs-transformer/SCRAPING.md @@ -0,0 +1,74 @@ +# Cursor-Based S2 Documentation Scraper + +This is a simplified approach to scraping S2 docs using Cursor's browser MCP tools directly. + +## How It Works + +Instead of running a separate Node.js script, you can ask Cursor to scrape components for you using the browser MCP integration. Cursor already has access to your authenticated browser session. + +## Usage + +Just ask Cursor to scrape specific components or all components: + +### Scrape a Single Component + +``` +"Can you scrape the Action Button component from S2 docs and save it to ~/Spectrum/s2-internal-docs/components/actions/action-button.md?" +``` + +### Scrape Multiple Components + +``` +"Can you scrape all Action components from S2 docs (Action bar, Action button, Action group, etc.)?" +``` + +### Scrape All Components + +``` +"Can you scrape all components from S2 docs and organize them by category?" +``` + +## What Cursor Will Do + +1. Navigate to the component page using browser MCP +2. Extract the page snapshot +3. Parse the content into structured markdown +4. Save to the appropriate category folder +5. Format with proper headings, tables, and lists + +## Advantages + +* ✅ Uses your existing authenticated browser session +* ✅ No additional setup or dependencies required +* ✅ Can run one component at a time or in batches +* ✅ Cursor handles all the parsing and formatting +* ✅ Can customize the output format on the fly + +## Components to Scrape + +### Actions (9 components) + +* Action bar: `/page/action-bar/` +* Action button: `/page/action-button/` +* Action group: `/page/action-group/` +* Button: `/page/button/` ✅ (already scraped) +* Button group: `/page/button-group/` +* Close button: `/page/close-button/` +* Link: `/page/link/` +* List view: `/page/list-view/` +* Menu: `/page/menu/` + +### Other Categories + +Ask Cursor to explore each category to find all available components. + +## Tips + +* Scrape components as you need them (on-demand) +* Or do a bulk scrape and have all docs available +* Update docs periodically by re-scraping changed components +* Reference docs in Cursor using `@~/Spectrum/s2-internal-docs/` + +## Example Output + +See `~/Spectrum/s2-internal-docs/components/actions/button.md` for an example of the formatted output. diff --git a/tools/s2-docs-transformer/moon.yml b/tools/s2-docs-transformer/moon.yml new file mode 100644 index 00000000..00f538e2 --- /dev/null +++ b/tools/s2-docs-transformer/moon.yml @@ -0,0 +1,32 @@ +$schema: "https://moonrepo.dev/schemas/project.json" + +project: + name: "s2-docs-transformer" + description: "Tools for scraping and transforming S2 documentation" + type: "tool" + language: "javascript" + +tasks: + transform: + command: "node scripts/transform-to-frontmatter.js" + inputs: + - "../../docs/s2-docs/**/*.md" + - "scripts/transform-to-frontmatter.js" + outputs: + - "../../docs/s2-docs/**/*.md" + + add-metadata: + command: "node scripts/add-related-metadata.js" + inputs: + - "../../docs/s2-docs/**/*.md" + - "scripts/add-related-metadata.js" + outputs: + - "../../docs/s2-docs/**/*.md" + deps: + - "transform" + + process-all: + command: "pnpm run process-all" + deps: + - "transform" + - "add-metadata" diff --git a/tools/s2-docs-transformer/package.json b/tools/s2-docs-transformer/package.json new file mode 100644 index 00000000..c3918838 --- /dev/null +++ b/tools/s2-docs-transformer/package.json @@ -0,0 +1,32 @@ +{ + "name": "@adobe/s2-docs-transformer", + "version": "1.0.0", + "description": "Tools for scraping and transforming Spectrum 2 documentation", + "type": "module", + "bin": { + "s2-scraper": "./src/cli.js" + }, + "scripts": { + "scrape": "node src/cli.js scrape", + "scrape-all": "node src/cli.js scrape-all", + "list": "node src/cli.js list", + "transform": "node scripts/transform-to-frontmatter.js", + "add-metadata": "node scripts/add-related-metadata.js", + "process-all": "npm run transform && npm run add-metadata" + }, + "dependencies": { + "@modelcontextprotocol/sdk": "^1.0.4" + }, + "keywords": [ + "spectrum", + "s2", + "documentation", + "scraper", + "transformer" + ], + "author": "Adobe", + "license": "Apache-2.0", + "engines": { + "node": ">=20.12.0" + } +} diff --git a/tools/s2-docs-transformer/scripts/add-related-metadata.js b/tools/s2-docs-transformer/scripts/add-related-metadata.js new file mode 100644 index 00000000..1fc72773 --- /dev/null +++ b/tools/s2-docs-transformer/scripts/add-related-metadata.js @@ -0,0 +1,107 @@ +#!/usr/bin/env node +/** + * Add related_components and parent_category to YAML frontmatter by parsing + * "## Related Components" section links (/page/slug/ -> slug). + */ + +const fs = require("fs"); +const path = require("path"); + +const DOCS_ROOT = path.join(__dirname, "..", "..", "..", "docs", "s2-docs"); + +function getDocFiles() { + const files = []; + function walk(dir) { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + for (const e of entries) { + const full = path.join(dir, e.name); + if (e.isDirectory()) { + if ( + e.name !== "node_modules" && + e.name !== "scripts" && + !full.includes("/tools/") + ) { + walk(full); + } + } else if (e.name.endsWith(".md")) { + const rel = path.relative(DOCS_ROOT, full); + if ( + !rel.includes("node_modules") && + rel !== "INDEX.md" && + rel !== "README.md" && + !rel.startsWith("tools/") && + !rel.includes("contact.md") && + !rel.includes("spectrum-quarterly-recap.md") + ) { + files.push(rel); + } + } + } + } + walk(DOCS_ROOT); + return files.sort(); +} + +function parseFrontmatter(content) { + const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/); + if (!m) return { fm: null, body: content }; + return { + fm: m[1], + body: content.slice(m[0].length), + fmRange: [0, m[0].length], + }; +} + +function extractRelatedSlugs(body) { + const section = body.match(/## Related Components\n\n([\s\S]*?)(?=\n## |$)/i); + if (!section) return []; + const links = section[1].matchAll(/\/page\/([^/]+)\//g); + return [...new Set([...links].map(([, slug]) => slug))]; +} + +function getParentCategory(relPath) { + const dir = path.dirname(relPath); + if (dir.startsWith("components/")) { + return path.dirname(relPath).split("/").pop(); + } + return null; +} + +function hasKey(fm, key) { + return new RegExp(`^${key}:`, "m").test(fm); +} + +function addRelatedToFrontmatter(fm, related, parentCategory) { + const toAdd = []; + if (related.length && !hasKey(fm, "related_components")) { + toAdd.push("related_components:"); + related.forEach((s) => toAdd.push(` - ${s}`)); + } + if (parentCategory && !hasKey(fm, "parent_category")) { + toAdd.push(`parent_category: ${parentCategory}`); + } + if (toAdd.length === 0) return fm; + return fm.trimEnd() + "\n" + toAdd.join("\n") + "\n"; +} + +function main() { + const files = getDocFiles(); + let updated = 0; + for (const rel of files) { + const full = path.join(DOCS_ROOT, rel); + const content = fs.readFileSync(full, "utf-8"); + const { fm, body } = parseFrontmatter(content); + if (!fm) continue; + const related = extractRelatedSlugs(body); + const parentCategory = getParentCategory(rel); + const newFm = addRelatedToFrontmatter(fm, related, parentCategory); + if (newFm !== fm) { + const newContent = "---\n" + newFm + "\n---\n" + body; + fs.writeFileSync(full, newContent, "utf-8"); + updated++; + } + } + console.error(`Updated frontmatter in ${updated} files.`); +} + +main(); diff --git a/tools/s2-docs-transformer/scripts/transform-to-frontmatter.js b/tools/s2-docs-transformer/scripts/transform-to-frontmatter.js new file mode 100644 index 00000000..e7d50ed6 --- /dev/null +++ b/tools/s2-docs-transformer/scripts/transform-to-frontmatter.js @@ -0,0 +1,263 @@ +#!/usr/bin/env node +/** + * Transform S2 doc markdown files: + * 1. Convert blockquote metadata to YAML frontmatter + * 2. Set correct source_url from file path (slug) + * 3. Remove "On this page" TOC, HTML comments, duplicate content blocks + * 4. Skip INDEX.md and README.md + */ + +const fs = require("fs"); +const path = require("path"); + +const BASE_URL = "https://s2.spectrum.corp.adobe.com"; +const DOCS_ROOT = path.join(__dirname, "..", "..", "..", "docs", "s2-docs"); + +function getDocFiles() { + const files = []; + function walk(dir) { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + for (const e of entries) { + const full = path.join(dir, e.name); + if (e.isDirectory()) { + if ( + e.name !== "node_modules" && + e.name !== "scripts" && + !full.includes("/tools/") + ) { + walk(full); + } + } else if ( + e.name.endsWith(".md") && + (e.name === "INDEX.md" || + e.name === "README.md" || + !full.includes("/tools/")) && + !full.includes("node_modules") + ) { + const rel = path.relative(DOCS_ROOT, full); + // Skip specific files + if ( + rel !== "INDEX.md" && + rel !== "README.md" && + !rel.includes("contact.md") && + !rel.includes("spectrum-quarterly-recap.md") + ) { + files.push(rel); + } + } + } + } + walk(DOCS_ROOT); + return files.sort(); +} + +function slugFromRel(rel) { + const base = path.basename(rel, ".md"); + return base; +} + +function categoryFromRel(rel) { + const dir = path.dirname(rel); + return dir || "root"; +} + +function sourceUrlFromSlug(slug) { + return `${BASE_URL}/page/${slug}/`; +} + +function stripExistingFrontmatter(content) { + const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/); + if (fmMatch) { + return { frontmatter: fmMatch[1], body: content.slice(fmMatch[0].length) }; + } + return { frontmatter: null, body: content }; +} + +function parseFrontmatterYaml(yaml) { + const out = {}; + for (const line of yaml.split("\n")) { + const m = line.match(/^(\w+):\s*(.+)$/); + if (m) out[m[1]] = m[2].replace(/^["']|["']$/g, "").trim(); + } + return out; +} + +function extractTitle(content, existingFm) { + if (existingFm && existingFm.title) return existingFm.title; + const m = content.match(/^#\s+(.+)$/m); + return m ? m[1].trim() : path.basename(content, ".md"); +} + +function extractLastUpdated(content, existingFm) { + if (existingFm && existingFm.last_updated) return existingFm.last_updated; + const m = content.match(/>\s*Last updated:\s*([^\n]+)/); + return m ? m[1].trim() : null; +} + +function extractBlockquoteSource(content) { + const m = content.match(/>\s*Source:\s*([^\n]+)/); + return m ? m[1].trim() : null; +} + +function removeBlockquoteMeta(body) { + return body + .replace(/^>\s*Last updated:.*$/gm, "") + .replace(/^>\s*Source:.*$/gm, "") + .replace(/\n{3,}/g, "\n\n") + .trim(); +} + +function removeOnThisPage(body) { + return body + .replace(/(^|\n)## On this page\n\n(?:- \[[^\]]+\]\(#[^)]+\)\n)*/gi, "\n") + .replace(/(^|\n)## On this page\n\n/gi, "\n") + .replace(/\n{3,}/g, "\n\n") + .trim(); +} + +function removeHtmlComments(body) { + return body + .replace(/\s*\s*/g, "\n\n") + .replace(/\n{3,}/g, "\n\n") + .trim(); +} + +function removeDuplicateParagraphBlocks(body) { + const paragraphs = body.split(/\n\n+/); + const seen = new Set(); + const out = []; + for (const p of paragraphs) { + const normalized = p.replace(/\s+/g, " ").trim(); + if (normalized.length > 150 && seen.has(normalized)) { + continue; + } + if (normalized.length > 150) seen.add(normalized); + out.push(p); + } + return out + .join("\n\n") + .replace(/\n{3,}/g, "\n\n") + .trim(); +} + +function removeEmptySections(body) { + return body.replace(/\n## [^\n]+\n\n(\s*)\n/g, (match, blank) => { + if (blank.trim() === "") return "\n"; + return match; + }); +} + +function buildFrontmatter(opts) { + const lines = [ + "---", + `title: ${JSON.stringify(opts.title)}`, + `source_url: ${opts.source_url}`, + ]; + if (opts.last_updated) { + lines.push(`last_updated: ${opts.last_updated}`); + } + lines.push(`category: ${opts.category}`); + if (opts.component_type) { + lines.push(`component_type: ${opts.component_type}`); + } + lines.push("status: published"); + if (opts.tags && opts.tags.length) { + lines.push(`tags:\n${opts.tags.map((t) => ` - ${t}`).join("\n")}`); + } + lines.push("---", ""); + return lines.join("\n"); +} + +const COMPONENT_TYPE_SINGULAR = { + actions: "action", + inputs: "input", + containers: "container", +}; +function getComponentType(category) { + if (category.startsWith("components/")) { + const sub = category.split("/")[1]; + return sub ? COMPONENT_TYPE_SINGULAR[sub] || sub : null; + } + return null; +} + +function getTagsForCategory(category, title) { + const tags = [category.replace(/\//g, "-")]; + const t = (title || "").toLowerCase(); + if (t.includes("button")) tags.push("action", "button", "interactive"); + if (t.includes("menu")) tags.push("navigation", "menu", "dropdown"); + if ( + t.includes("input") || + t.includes("field") || + t.includes("checkbox") || + t.includes("select") + ) + tags.push("input", "form"); + if ( + t.includes("dialog") || + t.includes("modal") || + t.includes("alert") || + t.includes("toast") + ) + tags.push("feedback", "overlay"); + if (t.includes("color")) tags.push("design-tokens", "color"); + if (category.startsWith("designing/")) tags.push("design", "guidelines"); + if (category.startsWith("fundamentals/")) + tags.push("fundamentals", "principles"); + return [...new Set(tags)]; +} + +function transform(content, relPath) { + const { frontmatter: existingFmStr, body: contentAfterFm } = + stripExistingFrontmatter(content); + const existingFm = existingFmStr ? parseFrontmatterYaml(existingFmStr) : {}; + const slug = slugFromRel(relPath); + const category = categoryFromRel(relPath); + const source_url = sourceUrlFromSlug(slug); + const title = extractTitle(contentAfterFm, existingFm); + const last_updated = extractLastUpdated(contentAfterFm, existingFm); + + let body = contentAfterFm.replace(/^#\s+[^\n]+\n\n/, "").trim(); + body = removeBlockquoteMeta(body); + body = removeOnThisPage(body); + body = removeHtmlComments(body); + body = removeDuplicateParagraphBlocks(body); + body = removeEmptySections(body); + + const componentType = getComponentType(category); + const tags = getTagsForCategory(category, title); + + const frontmatter = buildFrontmatter({ + title, + source_url, + last_updated, + category, + component_type: componentType || undefined, + tags, + }); + + return frontmatter + "# " + title + "\n\n" + body.trim() + "\n"; +} + +function main() { + const files = getDocFiles(); + console.error(`Transforming ${files.length} files...`); + let ok = 0; + let err = 0; + for (const rel of files) { + const full = path.join(DOCS_ROOT, rel); + try { + const content = fs.readFileSync(full, "utf-8"); + const out = transform(content, rel); + fs.writeFileSync(full, out, "utf-8"); + ok++; + } catch (e) { + console.error(`Error ${rel}:`, e.message); + err++; + } + } + console.error(`Done: ${ok} ok, ${err} errors`); + process.exit(err ? 1 : 0); +} + +main(); diff --git a/tools/s2-docs-transformer/src/browser-client.js b/tools/s2-docs-transformer/src/browser-client.js new file mode 100644 index 00000000..819ac7c5 --- /dev/null +++ b/tools/s2-docs-transformer/src/browser-client.js @@ -0,0 +1,74 @@ +/** + * Browser MCP Client + * Communicates with cursor-browser-extension MCP server + */ + +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; + +export class BrowserClient { + constructor() { + this.client = null; + this.transport = null; + } + + async connect() { + // Connect to the browser extension MCP server + // This assumes the cursor-browser-extension is already running + console.log("Connecting to browser MCP..."); + + this.transport = new StdioClientTransport({ + command: "cursor-browser-extension", + args: [], + }); + + this.client = new Client( + { + name: "s2-docs-scraper", + version: "1.0.0", + }, + { + capabilities: {}, + }, + ); + + await this.client.connect(this.transport); + console.log("Connected to browser MCP"); + } + + async navigate(url) { + if (!this.client) { + throw new Error("Not connected to browser MCP"); + } + + const result = await this.client.callTool("browser_navigate", { url }); + return result; + } + + async snapshot() { + if (!this.client) { + throw new Error("Not connected to browser MCP"); + } + + const result = await this.client.callTool("browser_snapshot", {}); + return result; + } + + async click(element, ref) { + if (!this.client) { + throw new Error("Not connected to browser MCP"); + } + + const result = await this.client.callTool("browser_click", { + element, + ref, + }); + return result; + } + + async close() { + if (this.client) { + await this.client.close(); + } + } +} diff --git a/tools/s2-docs-transformer/src/cli.js b/tools/s2-docs-transformer/src/cli.js new file mode 100755 index 00000000..35b57666 --- /dev/null +++ b/tools/s2-docs-transformer/src/cli.js @@ -0,0 +1,134 @@ +#!/usr/bin/env node +/** + * S2 Documentation Scraper CLI + * Usage: + * s2-scraper list List available components + * s2-scraper scrape Scrape a single component + * s2-scraper scrape-all Scrape all components + */ + +/** + * S2 Documentation Scraper CLI + * Command-line interface for scraping S2 docs + */ + +import { BrowserClient } from "./browser-client.js"; +import { + listComponents, + scrapeComponent, + scrapeAllComponents, +} from "./scraper.js"; + +const commands = { + async list() { + console.log("📋 Listing all S2 components...\n"); + + const browser = new BrowserClient(); + try { + await browser.connect(); + const components = await listComponents(browser); + + console.log("Components by category:\n"); + for (const [category, items] of Object.entries(components)) { + console.log(`\n${category.toUpperCase()} (${items.length}):`); + items.forEach((item) => { + console.log(` - ${item.name} (${item.slug})`); + }); + } + } finally { + await browser.close(); + } + }, + + async scrape(componentSlug, category) { + if (!componentSlug || !category) { + console.error("Usage: s2-scraper scrape "); + console.error("Example: s2-scraper scrape button actions"); + process.exit(1); + } + + console.log(`📄 Scraping ${componentSlug} from ${category} category...\n`); + + const browser = new BrowserClient(); + try { + await browser.connect(); + const url = `https://s2.spectrum.corp.adobe.com/page/${componentSlug}/`; + const result = await scrapeComponent( + browser, + url, + category, + componentSlug, + ); + + if (result.success) { + console.log(`\n✅ Successfully scraped ${componentSlug}`); + console.log(`📁 Saved to: ${result.outputPath}`); + } else { + console.error(`\n❌ Failed to scrape ${componentSlug}`); + process.exit(1); + } + } finally { + await browser.close(); + } + }, + + async scrapeAll() { + console.log("🚀 Starting full S2 documentation scrape...\n"); + console.log("This will take several minutes...\n"); + + const browser = new BrowserClient(); + try { + await browser.connect(); + const results = await scrapeAllComponents(browser); + + console.log("\n✅ Scraping complete!"); + console.log( + `📊 ${results.success}/${results.total} components scraped successfully`, + ); + } finally { + await browser.close(); + } + }, + + help() { + console.log(` +S2 Documentation Scraper + +Usage: + s2-scraper list List all available components + s2-scraper scrape Scrape a single component + s2-scraper scrape-all Scrape all components + s2-scraper help Show this help message + +Examples: + s2-scraper list + s2-scraper scrape button actions + s2-scraper scrape text-field inputs + s2-scraper scrape-all + +Categories: + actions, containers, feedback, inputs, navigation, status + `); + }, +}; + +// Parse command line arguments +const [, , command, ...args] = process.argv; + +if ( + !command || + command === "help" || + command === "--help" || + command === "-h" +) { + commands.help(); +} else if (commands[command]) { + commands[command](...args).catch((error) => { + console.error("\n❌ Error:", error.message); + process.exit(1); + }); +} else { + console.error(`Unknown command: ${command}`); + commands.help(); + process.exit(1); +} diff --git a/tools/s2-docs-transformer/src/parser.js b/tools/s2-docs-transformer/src/parser.js new file mode 100644 index 00000000..237b83d2 --- /dev/null +++ b/tools/s2-docs-transformer/src/parser.js @@ -0,0 +1,157 @@ +/** + * S2 Documentation Parser + * Extracts structured content from S2 docs pages + */ + +/** + * Parse a component page snapshot into structured data + */ +export function parseComponentPage(snapshot, url) { + const component = { + name: "", + url: url, + overview: "", + sections: [], + navigation: [], + }; + + // Extract component name from page title or heading + const titleMatch = snapshot.match(/heading "([^"]+)" \[level=1\]/); + if (titleMatch) { + component.name = titleMatch[1]; + } + + // Extract main content sections + const mainContentMatch = snapshot.match(/main "Main content"[\s\S]*$/); + if (mainContentMatch) { + const mainContent = mainContentMatch[0]; + + // Find all section headings + const headingRegex = /heading "([^"#]+)#?" \[level=(\d)\]/g; + let match; + const sections = []; + + while ((match = headingRegex.exec(mainContent)) !== null) { + sections.push({ + title: match[1].trim(), + level: parseInt(match[2]), + position: match.index, + }); + } + + component.sections = sections; + } + + // Extract navigation items from "On this page" section + const onThisPageMatch = snapshot.match( + /heading "On this page"[\s\S]*?(?=(?:heading|$))/, + ); + if (onThisPageMatch) { + const navItems = onThisPageMatch[0].match(/link "([^"]+)"/g); + if (navItems) { + component.navigation = navItems.map( + (item) => item.match(/link "([^"]+)"/)[1], + ); + } + } + + return component; +} + +/** + * Extract component list from navigation + */ +export function extractComponentList(snapshot) { + const components = { + actions: [], + containers: [], + feedback: [], + inputs: [], + navigation: [], + status: [], + }; + + const categories = [ + "Actions", + "Containers", + "Feedback", + "Inputs", + "Navigation", + "Status", + ]; + + for (const category of categories) { + const categoryKey = category.toLowerCase(); + const categoryRegex = new RegExp( + `link "${category}"[\\s\\S]*?list "${category}"[\\s\\S]*?(?=listitem \\[ref=|$)`, + "i", + ); + const categoryMatch = snapshot.match(categoryRegex); + + if (categoryMatch) { + const componentLinks = categoryMatch[0].match( + /link "([^"]+)" \[ref=[^\]]+\] \[cursor=pointer\]:\s*- \/url: \/page\/([^/]+)\//g, + ); + + if (componentLinks) { + for (const link of componentLinks) { + const nameMatch = link.match(/link "([^"]+)"/); + const urlMatch = link.match(/\/page\/([^/]+)\//); + + if (nameMatch && urlMatch) { + components[categoryKey].push({ + name: nameMatch[1], + slug: urlMatch[1], + url: `https://s2.spectrum.corp.adobe.com/page/${urlMatch[1]}/`, + }); + } + } + } + } + } + + return components; +} + +/** + * Convert component data to markdown + */ +export function componentToMarkdown(component, pageContent = "") { + const lines = []; + + lines.push(`# ${component.name}`); + lines.push(""); + lines.push(`> Last updated: ${new Date().toISOString().split("T")[0]}`); + lines.push(`> Source: ${component.url}`); + lines.push(""); + + if (component.navigation.length > 0) { + lines.push("## On this page"); + lines.push(""); + for (const item of component.navigation) { + lines.push(`- [${item}](#${item.toLowerCase().replace(/\s+/g, "-")})`); + } + lines.push(""); + } + + if (component.sections.length > 0) { + lines.push("## Sections"); + lines.push(""); + for (const section of component.sections) { + lines.push(`${"#".repeat(section.level + 1)} ${section.title}`); + lines.push(""); + lines.push("[Content to be extracted from page]"); + lines.push(""); + } + } + + if (pageContent) { + lines.push("## Raw Content"); + lines.push(""); + lines.push("```"); + lines.push(pageContent); + lines.push("```"); + } + + return lines.join("\n"); +} diff --git a/tools/s2-docs-transformer/src/scraper.js b/tools/s2-docs-transformer/src/scraper.js new file mode 100644 index 00000000..9230b460 --- /dev/null +++ b/tools/s2-docs-transformer/src/scraper.js @@ -0,0 +1,172 @@ +/** + * S2 Documentation Scraper + * Main scraping logic + */ + +import { promises as fs } from "fs"; +import path from "path"; +import { + parseComponentPage, + extractComponentList, + componentToMarkdown, +} from "./parser.js"; + +const BASE_URL = "https://s2.spectrum.corp.adobe.com"; +const OUTPUT_DIR = path.join( + process.env.HOME, + "Spectrum", + "spectrum-design-data", + "docs", + "s2-docs", +); + +/** + * Get list of all components from S2 site + */ +export async function listComponents(browserClient) { + console.log("Fetching component list from S2 docs..."); + + // Navigate to home page + await browserClient.navigate(BASE_URL); + + // Expand Components menu + const snapshot1 = await browserClient.snapshot(); + const componentsLinkMatch = snapshot1.content[0].text.match( + /link "Components" \[ref=([^\]]+)\]/, + ); + + if (componentsLinkMatch) { + await browserClient.click( + "Components navigation link", + componentsLinkMatch[1], + ); + } + + // Get updated snapshot with expanded menu + const snapshot2 = await browserClient.snapshot(); + const components = extractComponentList(snapshot2.content[0].text); + + return components; +} + +/** + * Scrape a single component page + */ +export async function scrapeComponent( + browserClient, + componentUrl, + category, + slug, +) { + console.log(`Scraping: ${componentUrl}`); + + try { + // Navigate to component page + const navResult = await browserClient.navigate(componentUrl); + + // Wait a moment for page to load + await new Promise((resolve) => setTimeout(resolve, 2000)); + + // Get page snapshot + const snapshot = await browserClient.snapshot(); + + // Parse the page + const componentData = parseComponentPage( + snapshot.content[0].text, + componentUrl, + ); + + // Convert to markdown + const markdown = componentToMarkdown( + componentData, + snapshot.content[0].text, + ); + + // Save to file + const outputPath = path.join( + OUTPUT_DIR, + "components", + category, + `${slug}.md`, + ); + await fs.mkdir(path.dirname(outputPath), { recursive: true }); + await fs.writeFile(outputPath, markdown, "utf-8"); + + console.log(`✅ Saved: ${outputPath}`); + + return { + success: true, + component: componentData, + outputPath, + }; + } catch (error) { + console.error(`❌ Failed to scrape ${componentUrl}:`, error.message); + return { + success: false, + error: error.message, + }; + } +} + +/** + * Scrape all components + */ +export async function scrapeAllComponents(browserClient) { + console.log("Starting full documentation scrape..."); + + // Get component list + const components = await listComponents(browserClient); + + const results = { + total: 0, + success: 0, + failed: 0, + components: [], + }; + + // Scrape each category + for (const [category, items] of Object.entries(components)) { + console.log( + `\n📁 Scraping ${category} category (${items.length} components)...`, + ); + + for (const component of items) { + results.total++; + + const result = await scrapeComponent( + browserClient, + component.url, + category, + component.slug, + ); + + if (result.success) { + results.success++; + } else { + results.failed++; + } + + results.components.push({ + ...component, + category, + ...result, + }); + + // Small delay between requests + await new Promise((resolve) => setTimeout(resolve, 1000)); + } + } + + // Save summary + const summaryPath = path.join(OUTPUT_DIR, "scrape-summary.json"); + await fs.writeFile(summaryPath, JSON.stringify(results, null, 2), "utf-8"); + + console.log("\n" + "=".repeat(50)); + console.log("📊 Scraping Complete!"); + console.log(`Total: ${results.total}`); + console.log(`Success: ${results.success}`); + console.log(`Failed: ${results.failed}`); + console.log(`Summary saved to: ${summaryPath}`); + + return results; +}