diff --git a/packages/theme/CHANGELOG.md b/packages/theme/CHANGELOG.md index 8f3927358606b3..70147d49597fab 100644 --- a/packages/theme/CHANGELOG.md +++ b/packages/theme/CHANGELOG.md @@ -2,6 +2,10 @@ ## Unreleased +### Documentation + +- Add "How to pick a token" and "Naming pattern" guidance to [the design system tokens reference documentation](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/docs/tokens.md) ([#78438](https://github.com/WordPress/gutenberg/pull/78438)). + ## 0.13.0 (2026-05-14) ### New Features diff --git a/packages/theme/README.md b/packages/theme/README.md index efdd5dc3492261..e5b514428f6521 100644 --- a/packages/theme/README.md +++ b/packages/theme/README.md @@ -75,93 +75,7 @@ Each JSON file contains both primitive and semantic token definitions in a hiera #### Token Naming -Semantic tokens follow a consistent naming pattern: - -``` ---wpds---[-] -``` - -**Type** indicates what kind of value it represents, usually mapping to a DTCG token type. - -| Value | Description | -| ------------ | ------------------------------------------------------------------------------ | -| `color` | Color values for backgrounds, foregrounds, and strokes | -| `dimension` | Spacing, sizing, and other measurable lengths (e.g., padding, margins, widths) | -| `border` | Border properties like radius and width | -| `elevation` | Shadow definitions for layering and depth | -| `motion` | Animation durations and easing curves | -| `typography` | Typography properties like font family, font size, and line-height | - -**Property** is the specific design property being defined. - -| Value | Description | -| ------------- | ---------------------------------- | -| `bg` | Background color | -| `fg` | Foreground color (text and icons) | -| `stroke` | Border and outline color | -| `padding` | Internal spacing within an element | -| `gap` | Spacing between elements | -| `radius` | Border radius for rounded corners | -| `width` | Border width | -| `duration` | Animation duration | -| `easing` | Animation easing curve | -| `font-size` | Font size | -| `font-family` | Font family | -| `font-weight` | Font weight | -| `line-height` | Line height | - -**Target** is the component or element type the token applies to. - -| Value | Description | -| ------------- | --------------------------------------------------------- | -| `surface` | Container or layout backgrounds and borders | -| `interactive` | Interactive elements like buttons, inputs, and controls | -| `content` | Static content like text and icons | -| `track` | Track components like scrollbars and slider tracks | -| `thumb` | Thumb components like scrollbar thumbs and slider handles | -| `focus` | Focus indicators and rings | - -**Modifier** is an optional size or intensity modifier. - -| Value | Description | -| ------------------------------------------ | -------------------- | -| `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl` | Size scale modifiers | - -#### Color Token Modifiers - -Color tokens extend the base pattern with additional modifiers for tone, emphasis, and state: - -``` ---wpds-color---[-][-] -``` - -**Tone** defines the semantic intent of the color. - -| Value | Description | -| --------- | --------------------------------------------------------------------------------------- | -| `neutral` | Neutrally toned UI elements | -| `brand` | Brand-accented or primary action colors | -| `success` | Positive or completed states | -| `info` | Informational or system-generated context | -| `caution` | Heads-up or low-severity issues; “proceed carefully” | -| `warning` | Higher-severity or time-sensitive issues that require user attention but are not errors | -| `error` | Blocking issues, validation failures, or destructive actions | - -Note: `caution` and `warning` represent two escalation levels of non-error severity. Use **`caution`** for guidance or minor risks, and **`warning`** when the user must act to prevent an error. - -**Emphasis** adjusts color strength relative to the base tone, if specified. The default is a normal emphasis. - -| Value | Description | -| -------- | ---------------------------------------------- | -| `strong` | Higher contrast and/or elevated emphasis | -| `weak` | Subtle variant for secondary or muted elements | - -**State** represents the interactive state of the element, if specified. The default is an idle state. - -| Value | Description | -| ---------- | ----------------------------------- | -| `active` | Hovered, pressed, or selected state | -| `disabled` | Unavailable or inoperable state | +Semantic tokens follow a consistent naming pattern that encodes the token's purpose. See the [Design Tokens Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/docs/tokens.md) for the naming pattern, the meaning of each segment (type, property, target, tone, emphasis, state), and guidance on how to pick the right token. ## Theme Provider diff --git a/packages/theme/bin/terrazzo-plugin-ds-tokens-docs/index.ts b/packages/theme/bin/terrazzo-plugin-ds-tokens-docs/index.ts index 0e15c5a36a7283..6bf21d3094f5d9 100644 --- a/packages/theme/bin/terrazzo-plugin-ds-tokens-docs/index.ts +++ b/packages/theme/bin/terrazzo-plugin-ds-tokens-docs/index.ts @@ -8,6 +8,123 @@ function titleCase( str: string ) { return str[ 0 ].toUpperCase() + str.slice( 1 ); } +const STATIC_PREAMBLE = `Design tokens are named values. They encode design decisions which describe the visual purpose of a value. Rather than referencing a raw value like \`#3858e9\`, a token like \`--wpds-color-bg-interactive-brand-strong\` describes what the value is for. Tokens are delivered as CSS custom properties and consumed with \`var( --wpds-* )\`. + +## How to pick a token + +Each segment of a token name answers one question about the value being applied: + +- **Type** identifies the kind of value, like \`color\` or \`dimension\`. It is usually determined by the CSS property being set. +- **Property** describes which aspect of the element the token applies to, such as \`bg\`, \`fg\`, \`stroke\`, \`padding\`, or \`gap\`. +- **Target** describes the kind of element the token applies to, such as a \`surface\`, an \`interactive\` control, static \`content\`, a \`track\` or \`thumb\`, or a \`focus\` indicator. +- **Tone** describes the semantic intent of a color, such as \`neutral\`, \`brand\`, \`success\`, or \`error\`. +- **Emphasis** and **state** are modifiers that adjust strength and reflect interactive states. + +## Naming pattern + +Semantic tokens follow a consistent naming pattern: + +\`\`\` +--wpds---[-] +\`\`\` + +### Type + +Indicates what kind of value the token represents, usually mapping to a [DTCG](https://design-tokens.github.io/community-group/format/) token type. + +| Value | Description | +| ------------ | ------------------------------------------------------------------------------ | +| \`color\` | Color values for backgrounds, foregrounds, and strokes | +| \`dimension\` | Spacing, sizing, and other measurable lengths (e.g., padding, margins, widths) | +| \`border\` | Border properties like radius and width | +| \`elevation\` | Shadow definitions for layering and depth | +| \`motion\` | Animation durations and easing curves | +| \`typography\` | Typography properties like font family, font size, and line-height | + +### Property + +The specific design property being defined. + +| Value | Description | +| ------------- | ---------------------------------- | +| \`bg\` | Background color | +| \`fg\` | Foreground color (text and icons) | +| \`stroke\` | Border and outline color | +| \`padding\` | Internal spacing within an element | +| \`gap\` | Spacing between elements | +| \`radius\` | Border radius for rounded corners | +| \`width\` | Border width | +| \`duration\` | Animation duration | +| \`easing\` | Animation easing curve | +| \`font-size\` | Font size | +| \`font-family\` | Font family | +| \`font-weight\` | Font weight | +| \`line-height\` | Line height | + +### Target + +The component or element type the token applies to. + +| Value | Description | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| \`surface\` | Backgrounds and borders of containers, cards, panels, message bubbles, and other static layout elements. Not for clickable parts. | +| \`interactive\` | Elements the user directly interacts with: buttons, inputs, links, checkboxes, toggles, menu items. Implies a clickable/focusable affordance. | +| \`content\` | Static content like body text and icons. Use for foreground colors where there is no interactive behavior. | +| \`track\` | The non-moving rail of a track-and-thumb control (scrollbar track, slider track, progressbar track). | +| \`thumb\` | The moving indicator of a track-and-thumb control (scrollbar thumb, slider handle, filled progress). | +| \`focus\` | Focus indicators and rings. | + +### Modifier + +An optional size or intensity modifier. + +| Value | Description | +| ------------------------------------------ | -------------------- | +| \`xs\`, \`sm\`, \`md\`, \`lg\`, \`xl\`, \`2xl\`, \`3xl\` | Size scale modifiers | + +## Color token modifiers + +Color tokens extend the base pattern with additional modifiers for tone, emphasis, and state: + +\`\`\` +--wpds-color---[-][-] +\`\`\` + +### Tone + +The semantic intent of the color. + +| Value | Description | +| --------- | --------------------------------------------------------------------------------------- | +| \`neutral\` | Neutrally toned UI elements | +| \`brand\` | Brand-accented or primary action colors | +| \`success\` | Positive or completed states | +| \`info\` | Informational or system-generated context | +| \`caution\` | Heads-up or low-severity issues; "proceed carefully" | +| \`warning\` | Higher-severity or time-sensitive issues that require user attention but are not errors | +| \`error\` | Blocking issues, validation failures, or destructive actions | + +Note: \`caution\` and \`warning\` represent two escalation levels of non-error severity. Use **\`caution\`** for guidance or minor risks, and **\`warning\`** when the user must act to prevent an error. + +### Emphasis + +Adjusts color strength relative to the base tone. The default (no modifier) is normal emphasis. + +| Value | Description | +| -------- | ---------------------------------------------- | +| \`strong\` | Higher contrast and/or elevated emphasis | +| \`weak\` | Subtle variant for secondary or muted elements | + +### State + +The interactive state of the element. The default (no modifier) is the idle state. + +| Value | Description | +| ---------- | ----------------------------------- | +| \`active\` | Hovered, pressed, or selected state | +| \`disabled\` | Unavailable or inoperable state | +`; + type TokensMap = Record< string, Record< string, string > >; export default function pluginDsTokenDocs( { @@ -73,6 +190,8 @@ export default function pluginDsTokenDocs( { '', '# Design System Tokens reference', '', + STATIC_PREAMBLE, + '', '## Semantic tokens', '', ...tokensToMdTable( semanticTokens ), diff --git a/packages/theme/docs/tokens.md b/packages/theme/docs/tokens.md index 59af41fae0c770..54cbc21c50a551 100644 --- a/packages/theme/docs/tokens.md +++ b/packages/theme/docs/tokens.md @@ -5,6 +5,122 @@ Do not edit directly. # Design System Tokens reference +Design tokens are named values. They encode design decisions which describe the visual purpose of a value. Rather than referencing a raw value like `#3858e9`, a token like `--wpds-color-bg-interactive-brand-strong` describes what the value is for. Tokens are delivered as CSS custom properties and consumed with `var( --wpds-* )`. + +## How to pick a token + +Each segment of a token name answers one question about the value being applied: + +- **Type** identifies the kind of value, like `color` or `dimension`. It is usually determined by the CSS property being set. +- **Property** describes which aspect of the element the token applies to, such as `bg`, `fg`, `stroke`, `padding`, or `gap`. +- **Target** describes the kind of element the token applies to, such as a `surface`, an `interactive` control, static `content`, a `track` or `thumb`, or a `focus` indicator. +- **Tone** describes the semantic intent of a color, such as `neutral`, `brand`, `success`, or `error`. +- **Emphasis** and **state** are modifiers that adjust strength and reflect interactive states. + +## Naming pattern + +Semantic tokens follow a consistent naming pattern: + +``` +--wpds---[-] +``` + +### Type + +Indicates what kind of value the token represents, usually mapping to a [DTCG](https://design-tokens.github.io/community-group/format/) token type. + +| Value | Description | +| ------------ | ------------------------------------------------------------------------------ | +| `color` | Color values for backgrounds, foregrounds, and strokes | +| `dimension` | Spacing, sizing, and other measurable lengths (e.g., padding, margins, widths) | +| `border` | Border properties like radius and width | +| `elevation` | Shadow definitions for layering and depth | +| `motion` | Animation durations and easing curves | +| `typography` | Typography properties like font family, font size, and line-height | + +### Property + +The specific design property being defined. + +| Value | Description | +| ------------- | ---------------------------------- | +| `bg` | Background color | +| `fg` | Foreground color (text and icons) | +| `stroke` | Border and outline color | +| `padding` | Internal spacing within an element | +| `gap` | Spacing between elements | +| `radius` | Border radius for rounded corners | +| `width` | Border width | +| `duration` | Animation duration | +| `easing` | Animation easing curve | +| `font-size` | Font size | +| `font-family` | Font family | +| `font-weight` | Font weight | +| `line-height` | Line height | + +### Target + +The component or element type the token applies to. + +| Value | Description | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `surface` | Backgrounds and borders of containers, cards, panels, message bubbles, and other static layout elements. Not for clickable parts. | +| `interactive` | Elements the user directly interacts with: buttons, inputs, links, checkboxes, toggles, menu items. Implies a clickable/focusable affordance. | +| `content` | Static content like body text and icons. Use for foreground colors where there is no interactive behavior. | +| `track` | The non-moving rail of a track-and-thumb control (scrollbar track, slider track, progressbar track). | +| `thumb` | The moving indicator of a track-and-thumb control (scrollbar thumb, slider handle, filled progress). | +| `focus` | Focus indicators and rings. | + +### Modifier + +An optional size or intensity modifier. + +| Value | Description | +| ------------------------------------------ | -------------------- | +| `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl` | Size scale modifiers | + +## Color token modifiers + +Color tokens extend the base pattern with additional modifiers for tone, emphasis, and state: + +``` +--wpds-color---[-][-] +``` + +### Tone + +The semantic intent of the color. + +| Value | Description | +| --------- | --------------------------------------------------------------------------------------- | +| `neutral` | Neutrally toned UI elements | +| `brand` | Brand-accented or primary action colors | +| `success` | Positive or completed states | +| `info` | Informational or system-generated context | +| `caution` | Heads-up or low-severity issues; "proceed carefully" | +| `warning` | Higher-severity or time-sensitive issues that require user attention but are not errors | +| `error` | Blocking issues, validation failures, or destructive actions | + +Note: `caution` and `warning` represent two escalation levels of non-error severity. Use **`caution`** for guidance or minor risks, and **`warning`** when the user must act to prevent an error. + +### Emphasis + +Adjusts color strength relative to the base tone. The default (no modifier) is normal emphasis. + +| Value | Description | +| -------- | ---------------------------------------------- | +| `strong` | Higher contrast and/or elevated emphasis | +| `weak` | Subtle variant for secondary or muted elements | + +### State + +The interactive state of the element. The default (no modifier) is the idle state. + +| Value | Description | +| ---------- | ----------------------------------- | +| `active` | Hovered, pressed, or selected state | +| `disabled` | Unavailable or inoperable state | + ## Semantic tokens ### Border