Skip to content

Theme: Move token structure descriptions into tokens document #78438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aduth merged 3 commits into from
May 19, 2026
Merged

Theme: Move token structure descriptions into tokens document #78438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f76dc3c
Theme: Move token structure descriptions into tokens document
aduth May 19, 2026
46cd0fe
Add CHANGELOG note
aduth May 19, 2026
740fa94
Move CHANGELOG note under correct heading
aduth May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions packages/theme/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
88 changes: 1 addition & 87 deletions packages/theme/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>-<property>-<target>[-<modifier>]
```

**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-<property>-<target>-<tone>[-<emphasis>][-<state>]
```

**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

Expand Down
119 changes: 119 additions & 0 deletions packages/theme/bin/terrazzo-plugin-ds-tokens-docs/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>-<property>-<target>[-<modifier>]
\`\`\`

### 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-<property>-<target>-<tone>[-<emphasis>][-<state>]
\`\`\`

### 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( {
Expand Down Expand Up @@ -73,6 +190,8 @@ export default function pluginDsTokenDocs( {
'',
'# Design System Tokens reference',
'',
STATIC_PREAMBLE,
'',
'## Semantic tokens',
'',
...tokensToMdTable( semanticTokens ),
Expand Down
116 changes: 116 additions & 0 deletions packages/theme/docs/tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>-<property>-<target>[-<modifier>]
```

### 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-<property>-<target>-<tone>[-<emphasis>][-<state>]
```

### 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
Expand Down
Loading