WordPress · ciampo · Jul 6, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
@@ -8,6 +8,7 @@
 
 ### Documentation
 
+-   Clarify the design token documentation entry points and keep the generated token guidance source internal ([#79829](https://github.com/WordPress/gutenberg/pull/79829)).
 -   Clarify that `--wpds-color-stroke-focus` is a standalone exception to the normal color token naming pattern ([#79764](https://github.com/WordPress/gutenberg/pull/79764)).
 
 ## 0.17.0 (2026-06-30)

@@ -9,15 +9,19 @@ A theming package that's part of the WordPress Design System. It has two parts:
 -   **Design Tokens**: A comprehensive system of design tokens for colors, spacing, typography, and more.
 -   **Theme System**: A flexible theming provider for consistent theming across applications.
 
-## Design Tokens
+## Documentation
+
+This README is the entry point for package consumers. It covers how to load design tokens, use `ThemeProvider`, and configure the package's development tooling.
 
-Design tokens are the visual design atoms of a design system. They are named entities that store visual design attributes like colors, spacing, typography, and shadows. They serve as a single source of truth that bridges design and development, ensuring consistency across platforms and making it easy to maintain and evolve the visual language of an application.
+-   To use design tokens and `ThemeProvider`, start here.
+-   To pick the right design token or browse every available token, see the generated [Design Tokens Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/docs/tokens.md).
+-   To edit token source files, see the [Design Tokens Maintainer's Guide](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/tokens/README.md).
 
-Rather than hardcoding values like `#3858e9` or `16px` throughout your code, tokens provide semantic names like `--wpds-color-background-interactive-brand-strong` or `--wpds-dimension-padding-2xl` that describe the purpose and context of the value. This makes code more maintainable and allows the design system to evolve. When a token's value changes, all components using that token automatically reflect the update.
+## Design Tokens
 
-The **[Design Tokens Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/docs/tokens.md)** contains a complete reference of all available design tokens including colors, spacing, typography, and more.
+Design tokens are named values that describe the visual purpose of a value. Rather than hardcoding values like `#3858e9` or `16px`, use semantic custom properties like `--wpds-color-background-interactive-brand-strong` or `--wpds-dimension-padding-2xl`.
 
-The **[Design Tokens Maintainer's Guide](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/tokens/README.md)** describes how design tokens are implemented in the design system.
+The **[Design Tokens Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/docs/tokens.md)** explains the naming pattern, how to choose a token, and the complete generated list of available design tokens.
 
 ### Using Design Tokens
 
@@ -40,7 +44,7 @@ Stylesheets are managed on your behalf in a WordPress context, so you don't need
 
 Outside of WordPress, you will need to install and load the design tokens stylesheet to support the full range of theming capabilities:
 
-```
+```sh
 npm install @wordpress/theme
 ```
 

@@ -1,132 +1,25 @@
+import { readFileSync } from 'node:fs';
+
 import { FORMAT_ID } from '@terrazzo/plugin-css';
 import type { Plugin } from '@terrazzo/parser';
 
+const GENERATED_SECTION_START =
+	'<!-- START GENERATED TOKEN TABLES: Do not edit this section directly. -->';
+const GENERATED_SECTION_END = '<!-- END GENERATED TOKEN TABLES -->';
+
+function escapeRegExp( str: string ) {
+	return str.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' );
+}
+
 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-background-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 \`background\`, \`foreground\`, \`stroke\`, \`padding\`, or \`gap\`.
--   **Target** describes the kind of element the token applies to, such as a \`surface\`, an \`interactive\` control, static \`content\`, or a \`track\` or \`thumb\`. The standalone focus-ring color token is documented below as an exception.
--   **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:
-
-\`\`\`text
---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                        |
-| ------------- | ---------------------------------- |
-| \`background\`  | Background color                   |
-| \`foreground\`  | 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).                              |
-
-### Modifier
-
-An optional size or intensity modifier.
-
-| Value                                      | Description          |
-| ------------------------------------------ | -------------------- |
-| \`xs\`, \`sm\`, \`md\`, \`lg\`, \`xl\`, \`2xl\`, \`3xl\` | Size scale modifiers |
-
-## Color token modifiers
-
-Most color tokens extend the base pattern with additional modifiers for tone, emphasis, and state:
-
-\`\`\`text
---wpds-color-<property>-<target>-<tone>[-<emphasis>][-<state>]
-\`\`\`
-
-\`--wpds-color-stroke-focus\` is the only color token that does not follow this target/tone grammar. Its \`focus\` segment describes the focus-ring purpose directly, and the token intentionally applies across tones.
-
-### 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( {
 	filename = 'design-tokens.md',
+	sourceFilename = '../../docs/tokens.md',
 } = {} ): Plugin {
 	return {
 		name: '@terrazzo/terrazzo-plugin-ds-tokens-docs',
@@ -178,23 +71,36 @@ export default function pluginDsTokenDocs( {
 					.flat( 2 );
 			}
 
+			const generatedTokenTables = [
+				GENERATED_SECTION_START,
+				'',
+				'## Semantic tokens',
+				'',
+				...tokensToMdTable( semanticTokens ),
+				GENERATED_SECTION_END,
+			].join( '\n' );
+
+			const template = readFileSync(
+				new URL( sourceFilename, import.meta.url ),
+				'utf8'
+			);
+			const generatedSectionPattern = new RegExp(
+				`${ escapeRegExp(
+					GENERATED_SECTION_START
+				) }[\\s\\S]*${ escapeRegExp( GENERATED_SECTION_END ) }`
+			);
+
+			if ( ! generatedSectionPattern.test( template ) ) {
+				throw new Error(
+					`@terrazzo/terrazzo-plugin-ds-tokens-docs: Missing generated token section markers in ${ sourceFilename }.`
+				);
+			}
+
 			outputFile(
 				filename,
-				[
-					'<!--',
-					'This file is generated by @terrazzo/terrazzo-plugin-ds-tokens-docs.',
-					'Do not edit directly.',
-					'-->',
-					'',
-					'# Design System Tokens reference',
-					'',
-					STATIC_PREAMBLE,
-					'',
-					'## Semantic tokens',
-					'',
-					...tokensToMdTable( semanticTokens ),
-					'', // final empty line
-				].join( '\n' )
+				template
+					.replace( generatedSectionPattern, generatedTokenTables )
+					.trimEnd() + '\n'
 			);
 		},
 	};

@@ -1,10 +1,7 @@
-<!--
-This file is generated by @terrazzo/terrazzo-plugin-ds-tokens-docs.
-Do not edit directly.
--->
-
 # Design System Tokens reference
 
+This consumer-facing guide explains how to choose semantic WordPress Design System tokens. For token source-file maintenance, see the [Design Tokens Maintainer's Guide](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/tokens/README.md).
+
 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-background-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
@@ -122,6 +119,8 @@ The interactive state of the element. The default (no modifier) is the idle stat
 | `active`   | Hovered, pressed, or selected state |
 | `disabled` | Unavailable or inoperable state     |
 
+<!-- START GENERATED TOKEN TABLES: Do not edit this section directly. -->
+
 ## Semantic tokens
 
 ### Border
@@ -327,3 +326,5 @@ The interactive state of the element. The default (no modifier) is the idle stat
 | `--wpds-typography-line-height-2xl`     | 2X large line height                         |
 | `--wpds-typography-font-weight-regular` | Regular font weight for body text            |
 | `--wpds-typography-font-weight-medium`  | Medium font weight for emphasis and headings |
+
+<!-- END GENERATED TOKEN TABLES -->
@@ -1,10 +1,8 @@
 # Design Tokens Maintainer's Guide
 
-Design tokens are the visual design atoms of a design system. They are named entities that store visual design attributes like colors, spacing, typography, and shadows. They serve as a single source of truth that bridges design and development, ensuring consistency across platforms and making it easy to maintain and evolve the visual language of an application.
+This maintainer-facing guide explains how the WordPress Design System token source files are organized and generated.
 
-Components that use these design tokens benefit from the consistency they guarantee with other components that extend from the same system. Future theming improvements or configurations like color theming (or "dark mode") or roundness will cascade automatically to these components without any additional effort on the part of the component maintainer.
-
-This document includes information about how the design system maintains its tokens implementation. For information about how to use design tokens, refer to the [`@wordpress/theme` package README](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/README.md) and [Design Tokens Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/docs/tokens.md).
+For consumer-facing usage, start with the [`@wordpress/theme` package README](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/README.md) and the generated [Design Tokens Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/theme/docs/tokens.md).
 
 ## Structure
 
@@ -23,7 +21,7 @@ Each JSON file contains both primitive and semantic token definitions in a hiera
 
 ## Token Naming
 
-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.
+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), guidance on how to pick the right token, and the complete generated list of token names.
 
 ## Primitive and Semantic Tokens