Theme: Restructure theme tokens to embed prefix, flattened modifiers

packages/theme/README.md

@@ -13,27 +13,91 @@ A theming package that's part of the WordPress Design System. It has two parts:
 
 In the **[Design Tokens Reference](docs/ds-tokens.md)** document there is a complete reference of all available design tokens including colors, spacing, typography, and more.
 
-### Color Tokens
+### Architecture
 
-The design system defines color tokens using the following naming scheme:
+Internally, the design system uses a tiered token architecture:
+
+- **Primitive tokens**: Raw values like hex colors or pixel dimensions which are what the browsers eventually interpret. These live in the `/tokens` directory as JSON source files and are an internal implementation detail.
+- **Semantic tokens**: Purpose-driven tokens with meaningful names that reference primitives and describe their intended use. These are what get exported as CSS custom properties.
+
+This separation allows the design system to maintain consistency while providing flexibility, since primitive values can be updated without changing the semantic token names that developers use in their code.
+
+### Design Tokens
+
+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.
+
+Rather than hardcoding values like `#3858e9` or `16px` throughout your code, tokens provide semantic names like `--wpds-color-bg-interactive-brand-strong` or `--wpds-dimension-padding-surface-md` 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.
+
+#### Structure
+
+The design system follows the [Design Tokens Community Group (DTCG)](https://design-tokens.github.io/community-group/format/) specification and organizes tokens into distinct types based on what kind of visual property they represent. Token definitions are stored as JSON files in the `/tokens` directory:
+
+| File              | Description                                                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `color.json`      | Color palettes including primitive color ramps and semantic color tokens for backgrounds, foregrounds, strokes, and focus states |
+| `dimension.json`  | Spacing scale and semantic spacing tokens for padding, margins, and sizing                                                       |
+| `typography.json` | Font family stacks, font sizes, and line heights                                                                                 |
+| `border.json`     | Border radius and width values                                                                                                   |
+| `elevation.json`  | Shadow definitions for creating depth and layering                                                                               |
+
+Each JSON file contains both primitive and semantic token definitions in a hierarchical structure. These files are the source of truth for the design system and are processed during the build step to generate CSS custom properties and other output formats in `/src/prebuilt`.
+
+#### Token Naming
+
+Semantic tokens follow a consistent naming pattern:
 
 ```
---wpds-<element>-<tone>[-<emphasis>][-<state>]
+--wpds-<type>-<property>-<target>[-<modifier>]
 ```
 
-**Element** specifies what the color is applied to.
+**Type** indicates what kind of value it represents, usually mapping to a DTCG token type.
 
-| Value                | Description                                                                                 |
-| -------------------- | ------------------------------------------------------------------------------------------- |
-| `bg-surface`         | Backgrounds of layout or container surfaces.                                                |
-| `bg-interactive`     | Backgrounds of interactive elements such as buttons, inputs, and toggles.                   |
-| `bg-track`           | Backgrounds of track components like scrollbars and slider tracks.                          |
-| `bg-thumb`           | Backgrounds of thumb components like scrollbar thumbs and slider thumbs.                    |
-| `fg-content`         | Foreground color for text and icons in static content.                                      |
-| `fg-interactive`     | Foreground color for text and icons in interactive elements such as links and buttons.      |
-| `stroke-surface`     | Decorative borders and dividers for non-interactive surfaces.                               |
-| `stroke-interactive` | Accessible borders for interactive controls.                                                |
-| `stroke-focus`       | Stroke color specifically for focus rings.                                                  |
+| 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                                      |
+| `font`      | Typography properties like family, 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                       |
+| `size`   | Font size                          |
+| `family` | Font family                        |
+
+**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          |
+| ----------------------------------- | -------------------- |
+| `2xs`, `xs`, `sm`, `md`, `lg`, `xl` | 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.
 
@@ -53,9 +117,9 @@ The design system defines color tokens using the following naming scheme:
 
 **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.   |
+| 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.

packages/theme/bin/generate-primitive-tokens/index.ts

@@ -74,13 +74,14 @@ function generatePrimitiveColorTokens() {
 			},
 			...accentRamps,
 		].forEach( ( { scaleName, ramp } ) => {
-			colorJson.color.primitive[ scaleName ] = {};
+			colorJson[ 'wpds-color' ].primitive[ scaleName ] = {};
 			for ( const [ tokenName, tokenValue ] of Object.entries(
 				ramp.ramp
 			) ) {
-				colorJson.color.primitive[ scaleName ][ tokenName ] = {
-					$value: transformColorStringToDTCGValue( tokenValue ),
-				};
+				colorJson[ 'wpds-color' ].primitive[ scaleName ][ tokenName ] =
+					{
+						$value: transformColorStringToDTCGValue( tokenValue ),
+					};
 			}
 		} );
 

packages/theme/docs/ds-tokens.md

@@ -109,7 +109,7 @@ Do not edit directly.
 | `--wpds-color-stroke-surface-neutral-weak`            | Decorative stroke color used to define neutrally-toned surface boundaries with weak emphasis.                                               |
 | `--wpds-color-stroke-surface-neutral-strong`          | Decorative stroke color used to define neutrally-toned surface boundaries with strong emphasis.                                             |
 | `--wpds-color-stroke-surface-brand`                   | Decorative stroke color used to define brand-toned surface boundaries with normal emphasis.                                                 |
-| `--wpds-color-stroke-surface-brand-strong`            | Decorative stroke color used to define neutrally-toned surface boundaries with strong emphasis.                                             |
+| `--wpds-color-stroke-surface-brand-strong`            | Decorative stroke color used to define brand-toned surface boundaries with strong emphasis.                                                 |
 | `--wpds-color-stroke-surface-success`                 | Decorative stroke color used to define success-toned surface boundaries with normal emphasis.                                               |
 | `--wpds-color-stroke-surface-success-strong`          | Decorative stroke color used to define success-toned surface boundaries with strong emphasis.                                               |
 | `--wpds-color-stroke-surface-info`                    | Decorative stroke color used to define info-toned surface boundaries with normal emphasis.                                                  |

packages/theme/src/prebuilt/css/design-tokens.css

@@ -103,7 +103,7 @@
 	--wpds-color-stroke-interactive-neutral-disabled: #d8d8d8; /* Accessible stroke color used for interactive neutrally-toned elements with normal emphasis, in their disabled state. */
 	--wpds-color-stroke-interactive-neutral-strong: #6c6c6c; /* Accessible stroke color used for interactive neutrally-toned elements with strong emphasis. */
 	--wpds-color-stroke-surface-brand: #a3b1d4; /* Decorative stroke color used to define brand-toned surface boundaries with normal emphasis. */
-	--wpds-color-stroke-surface-brand-strong: #3858e9; /* Decorative stroke color used to define neutrally-toned surface boundaries with strong emphasis. */
+	--wpds-color-stroke-surface-brand-strong: #3858e9; /* Decorative stroke color used to define brand-toned surface boundaries with strong emphasis. */
 	--wpds-color-stroke-surface-error: #daa39b; /* Decorative stroke color used to define error-toned surface boundaries with normal emphasis. */
 	--wpds-color-stroke-surface-error-strong: #cc1818; /* Decorative stroke color used to define error-toned surface boundaries with strong emphasis. */
 	--wpds-color-stroke-surface-info: #9fbcdc; /* Decorative stroke color used to define info-toned surface boundaries with normal emphasis. */

packages/theme/src/prebuilt/ts/color-tokens.ts

@@ -6,19 +6,19 @@
 export default {
 	'primary-bgFill1': [ 'bg-interactive-brand-strong' ],
 	'primary-fgFill': [
-		'fg-interactive-brand-strong-active',
 		'fg-interactive-brand-strong',
+		'fg-interactive-brand-strong-active',
 	],
 	'primary-bgFill2': [ 'bg-interactive-brand-strong-active' ],
 	'primary-surface2': [ 'bg-interactive-brand-active' ],
 	'primary-surface4': [ 'bg-interactive-brand-weak-active' ],
 	'primary-fgSurface3': [
-		'fg-interactive-brand-active',
 		'fg-interactive-brand',
+		'fg-interactive-brand-active',
 	],
 	'primary-stroke3': [
-		'bg-thumb-brand-active',
 		'bg-thumb-brand',
+		'bg-thumb-brand-active',
 		'stroke-focus-brand',
 		'stroke-interactive-brand',
 		'stroke-surface-brand-strong',
@@ -46,8 +46,8 @@ export default {
 	'warning-stroke1': [ 'stroke-surface-warning' ],
 	'error-bgFill1': [ 'bg-interactive-error-strong' ],
 	'error-fgFill': [
-		'fg-interactive-error-strong-active',
 		'fg-interactive-error-strong',
+		'fg-interactive-error-strong-active',
 	],
 	'error-bgFill2': [ 'bg-interactive-error-strong-active' ],
 	'error-surface2': [
@@ -61,8 +61,8 @@ export default {
 	'error-fgSurface4': [ 'fg-content-error' ],
 	'error-fgSurface3': [
 		'fg-content-error-weak',
-		'fg-interactive-error-active',
 		'fg-interactive-error',
+		'fg-interactive-error-active',
 	],
 	'error-stroke3': [
 		'stroke-interactive-error',
@@ -92,8 +92,8 @@ export default {
 	'bg-surface3': [ 'bg-surface-neutral-strong' ],
 	'bg-fgSurface4': [
 		'fg-content-neutral',
-		'fg-interactive-neutral-active',
 		'fg-interactive-neutral',
+		'fg-interactive-neutral-active',
 	],
 	'bg-fgSurface3': [
 		'fg-content-neutral-weak',
@@ -128,8 +128,8 @@ export default {
 	'bg-bgFillInverted2': [ 'bg-interactive-neutral-strong-active' ],
 	'bg-bgFillInverted1': [ 'bg-interactive-neutral-strong' ],
 	'bg-fgFillInverted': [
-		'fg-interactive-neutral-strong-active',
 		'fg-interactive-neutral-strong',
+		'fg-interactive-neutral-strong-active',
 	],
 	'bg-surface1': [ 'bg-surface-neutral-weak' ],
 	'caution-surface2': [ 'bg-surface-caution-weak' ],

packages/theme/terrazzo.config.ts

@@ -8,11 +8,9 @@ import { makeCSSVar } from '@terrazzo/token-tools/css';
 /**
  * Internal dependencies
  */
-import pluginFigmaDsTokenManager from './bin/terrazzo-plugin-figma-ds-token-manager/index';
 import pluginKnownWpdsCssVariables from './bin/terrazzo-plugin-known-wpds-css-variables/index';
 import pluginDsTokenDocs from './bin/terrazzo-plugin-ds-tokens-docs/index';
 import inlineAliasValues from './bin/terrazzo-plugin-inline-alias-values/index';
-import { publicTokenId } from './src/token-id.ts';
 
 export default defineConfig( {
 	tokens: [
@@ -26,36 +24,36 @@ export default defineConfig( {
 
 	plugins: [
 		inlineAliasValues( {
-			pattern: /^color\.primitive\./,
+			pattern: /^wpds-color\.primitive\./,
 			filename: 'ts/color-tokens.ts',
 			tokenId: ( tokenId ) =>
-				publicTokenId( tokenId )
-					.replace( /^color\./, '' )
+				tokenId
+					.replace( /\.primitive/, '' )
+					.replace( /^wpds-color\./, '' )
 					.replace( /\./g, '-' ),
 		} ),
-		inlineAliasValues( { pattern: /^dimension\.primitive\./ } ),
+		inlineAliasValues( { pattern: /^wpds-dimension\.primitive\./ } ),
 		pluginCSS( {
 			filename: 'css/design-tokens.css',
-			variableName: ( token ) =>
-				makeCSSVar( `wpds.${ publicTokenId( token.id ) }` ),
+			variableName: ( token ) => makeCSSVar( token.id ),
 			baseSelector: ':root',
 			modeSelectors: [
 				{
-					tokens: [ 'dimension.*' ],
+					tokens: [ 'wpds-dimension.*' ],
 					mode: '.',
 					selectors: [
 						"[data-wpds-theme-provider-id][data-wpds-density='default']",
 					],
 				},
 				{
-					tokens: [ 'dimension.*' ],
+					tokens: [ 'wpds-dimension.*' ],
 					mode: 'compact',
 					selectors: [
 						"[data-wpds-theme-provider-id][data-wpds-density='compact']",
 					],
 				},
 				{
-					tokens: [ 'dimension.*' ],
+					tokens: [ 'wpds-dimension.*' ],
 					mode: 'comfortable',
 					selectors: [
 						"[data-wpds-theme-provider-id][data-wpds-density='comfortable']",
@@ -70,9 +68,6 @@ export default defineConfig( {
 			],
 			legacyHex: true,
 		} ),
-		pluginFigmaDsTokenManager( {
-			filename: 'json/figma.json',
-		} ),
 		pluginKnownWpdsCssVariables( {
 			filename: 'js/design-tokens.js',
 		} ),

packages/theme/tokens/border.json

@@ -1,5 +1,5 @@
 {
-	"border": {
+	"wpds-border": {
 		"$type": "dimension",
 		"radius": {
 			"surface": {