@wordpress/theme 0.3.1-next.8b30e05b0.0 → 0.4.0

package/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.

package/bin/generate-primitive-tokens/index.ts

@@ -4,14 +4,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import {
-	parse,
-	to,
-	serialize,
-	OKLCH,
-	sRGB,
-	type PlainColorObject,
-} from 'colorjs.io/fn';
+import { parse, to, serialize, sRGB } from 'colorjs.io/fn';
 
 /**
  * Internal dependencies
@@ -29,29 +22,28 @@ const __dirname = path.dirname( __filename );
 // Path to the color.json file
 const colorJsonPath = path.join( __dirname, '../../tokens/color.json' );
 
-const transformColorStringToDTCGValue = ( color: string ) => {
-	if ( /oklch|p3/.test( color ) ) {
-		let parsed: PlainColorObject;
-		try {
-			parsed = to( parse( color ), OKLCH );
-		} catch {
-			return color;
-		}
+/**
+ * Rounds a given hex value (0-255) to 3 decimal places.
+ *
+ * 3 decimal places is the minimum precision for lossless hex serialization.
+ * With 3 decimal places rounding to the nearest 0.001, the maximum rounding
+ * error is 0.0005. With 256 possible hex values, 0.0005 × 256 = 0.128,
+ * guaranteeing the rounded value stays within 0.5 of the original value.
+ *
+ * @param n - The hex value to round.
+ * @return The rounded hex value.
+ */
+const roundHexComponent = ( n: number ) => Math.round( n * 1000 ) / 1000;
 
-		const coords = parsed.coords;
-		return {
-			colorSpace: 'oklch',
-			components: [
-				Math.floor( 10000 * coords[ 0 ] ) / 10000, // l
-				coords[ 1 ], // c
-				isNaN( coords[ 2 ] ) ? 0 : coords[ 2 ], // h
-			],
-			...( parsed.alpha < 1 ? { alpha: parsed.alpha } : undefined ),
-			hex: serialize( to( parsed, sRGB ), { format: 'hex' } ),
-		};
-	}
+const transformColorStringToDTCGValue = ( color: string ) => {
+	const parsed = to( parse( color ), sRGB );
 
-	return color;
+	return {
+		colorSpace: 'srgb',
+		components: parsed.coords.map( roundHexComponent ),
+		...( parsed.alpha < 1 ? { alpha: parsed.alpha } : undefined ),
+		hex: serialize( parsed, { format: 'hex' } ),
+	};
 };
 
 // Main function
@@ -82,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 ),
+					};
 			}
 		} );
 

package/bin/terrazzo-plugin-mode-overrides/index.ts

@@ -0,0 +1,208 @@
+/**
+ * External dependencies
+ */
+import { basename } from 'node:path';
+import type { Plugin } from '@terrazzo/parser';
+
+type DTCGPrimitiveValue =
+	| string
+	| number
+	| boolean
+	| { value: number; unit: string }
+	| { r: number; g: number; b: number; a?: number };
+
+type DTCGValue = DTCGPrimitiveValue | Record< string, DTCGPrimitiveValue >;
+
+interface DTCGExtensions {
+	[ key: string ]: unknown;
+	mode?: Record< string, DTCGValue >;
+}
+
+/**
+ * @see https://tr.designtokens.org/format/
+ */
+interface DTCGToken {
+	$value: DTCGValue;
+	$type?: string;
+	$description?: string;
+	$extensions?: DTCGExtensions;
+}
+
+interface DTCGGroup {
+	$type?: string;
+	$description?: string;
+	$extensions?: DTCGExtensions;
+	[ key: string ]:
+		| DTCGToken
+		| DTCGGroup
+		| string
+		| DTCGExtensions
+		| undefined;
+}
+
+type DTCGDocument = Record< string, DTCGGroup >;
+
+interface ModeOverride {
+	path: string[];
+	$value: DTCGValue;
+	$type?: string;
+}
+
+/**
+ * Type guard to check if a value is a DTCG token (has $value).
+ *
+ * @param value - The value to check.
+ * @return True if the value is a DTCG token.
+ */
+function isDTCGToken( value: DTCGToken | DTCGGroup ): value is DTCGToken {
+	return '$value' in value;
+}
+
+/**
+ * Set a nested value in an object from a path array.
+ *
+ * @param object    - The object to modify.
+ * @param pathParts - The path at which to set the value.
+ * @param value     - The value to set.
+ */
+function setNestedValue(
+	object: Record< string, unknown >,
+	pathParts: string[],
+	value: any
+): void {
+	let current = object;
+
+	for ( let i = 0; i < pathParts.length - 1; i++ ) {
+		const key = pathParts[ i ];
+
+		if ( ! ( key in current ) ) {
+			current[ key ] = {};
+		}
+
+		current = current[ key ] as Record< string, unknown >;
+	}
+
+	current[ pathParts[ pathParts.length - 1 ] ] = value;
+}
+
+/**
+ * Recursively extracts mode overrides from a DTCG token tree.
+ *
+ * @param object      - The DTCG group to extract from.
+ * @param currentPath - The current path in the token tree.
+ * @param currentType - The $type inherited from parent groups.
+ * @return A map of mode names to their token overrides.
+ */
+function getModeOverrides(
+	object: DTCGGroup,
+	currentPath: string[] = [],
+	currentType?: string
+): Map< string, ModeOverride[] > {
+	const modeOverrides = new Map< string, ModeOverride[] >();
+
+	// Check if this group defines a $type that should be inherited by children
+	const groupType = object.$type ?? currentType;
+
+	for ( const [ key, value ] of Object.entries( object ) ) {
+		// Skip DTCG metadata keys
+		if ( key.startsWith( '$' ) ) {
+			continue;
+		}
+
+		const node = value as DTCGToken | DTCGGroup;
+
+		if ( isDTCGToken( node ) ) {
+			// Extract mode-specific values from extensions
+			const modes = node.$extensions?.mode;
+			if ( modes ) {
+				for ( const [ mode, modeValue ] of Object.entries( modes ) ) {
+					modeOverrides.set( mode, [
+						...( modeOverrides.get( mode ) ?? [] ),
+						{
+							path: [ ...currentPath, key ],
+							$value: modeValue,
+							$type: node.$type ?? groupType,
+						},
+					] );
+				}
+			}
+		} else {
+			// Recurse into nested groups, passing down the type
+			const nextPath = [ ...currentPath, key ];
+			const childOverrides = getModeOverrides(
+				node,
+				nextPath,
+				groupType
+			);
+
+			// Merge child results
+			for ( const [ mode, overrides ] of childOverrides ) {
+				modeOverrides.set( mode, [
+					...( modeOverrides.get( mode ) ?? [] ),
+					...overrides,
+				] );
+			}
+		}
+	}
+
+	return modeOverrides;
+}
+
+/**
+ * Terrazzo plugin that generates mode-specific DTCG override files.
+ *
+ * For each mode found in tokens (via $extensions.mode), generates a separate
+ * JSON file per source file containing tokens that have values for that mode.
+ *
+ * @return A Terrazzo plugin that generates mode-specific DTCG override files.
+ */
+export default function pluginModeOverrides(): Plugin {
+	return {
+		name: '@wordpress/terrazzo-plugin-mode-overrides',
+		async build( { outputFile, sources } ) {
+			for ( const { filename, src } of sources ) {
+				if ( ! filename ) {
+					continue;
+				}
+
+				// Parse the source JSON file
+				let document: DTCGDocument;
+				try {
+					document = JSON.parse( src ) as DTCGDocument;
+				} catch ( error ) {
+					throw new Error(
+						`Could not parse ${ filename }\n\n${ error }`
+					);
+				}
+
+				// Extract mode overrides from this file
+				const fileOverrides = getModeOverrides( document );
+
+				// Generate a DTCG file for each mode found in this source file
+				for ( const [ mode, overrides ] of fileOverrides ) {
+					const output: Record< string, unknown > = {};
+
+					for ( const override of overrides ) {
+						const { path, $value, $type } = override;
+						setNestedValue( output, path, { $type, $value } );
+					}
+
+					// Output as {basename}.{mode}.json (e.g., dimension.compact.json)
+					const sourceDir = new URL( './', filename );
+					const outFileName = `${ basename(
+						filename.pathname,
+						'.json'
+					) }.${ mode }.json`;
+					const outFileUrl = new URL(
+						`modes/${ outFileName }`,
+						sourceDir
+					);
+					outputFile(
+						outFileUrl.href,
+						JSON.stringify( output, null, '\t' )
+					);
+				}
+			}
+		},
+	};
+}

package/build/color-ramps/lib/default-ramps.js

@@ -55,10 +55,10 @@ var DEFAULT_RAMPS = {
       bgFill1: "#3858e9",
       fgFill: "#eff0f2",
       bgFill2: "#2e49d9",
-      surface2: "#f6f8fc",
-      surface6: "#c7d2ee",
+      surface2: "#f6f8fd",
+      surface6: "#c7d2ed",
       surface5: "#dbe2f4",
-      surface4: "#e4eaf7",
+      surface4: "#e6eaf4",
       surface3: "#fff",
       fgSurface4: "#0b0070",
       fgSurface3: "#3858e9",
@@ -66,11 +66,11 @@ var DEFAULT_RAMPS = {
       fgSurface1: "#85a9ff",
       stroke3: "#3858e9",
       stroke4: "#2337c8",
-      stroke2: "#9aaad3",
-      stroke1: "#a2b1d6",
-      bgFillDark: "#1b1e26",
+      stroke2: "#9caacc",
+      stroke1: "#a3b1d4",
+      bgFillDark: "#1a1e27",
       fgFillDark: "#eff0f2",
-      bgFillInverted2: "#1b1e26",
+      bgFillInverted2: "#1a1e27",
       bgFillInverted1: "#13009f",
       fgFillInverted: "#eff0f2",
       surface1: "#ecf0f9"
@@ -80,27 +80,27 @@ var DEFAULT_RAMPS = {
   info: {
     ramp: {
       bgFill1: "#0090ff",
-      fgFill: "#1b1e23",
+      fgFill: "#1a1f24",
       bgFill2: "#007fed",
-      surface2: "#f5f9fd",
-      surface6: "#bdd5f1",
-      surface5: "#d4e4f6",
-      surface4: "#dfebf8",
+      surface2: "#f3f9ff",
+      surface6: "#bcd5f1",
+      surface5: "#d3e4f7",
+      surface4: "#deebfa",
       surface3: "#fff",
       fgSurface4: "#001b4f",
       fgSurface3: "#006bd7",
       fgSurface2: "#008bfa",
-      fgSurface1: "#59b0ff",
+      fgSurface1: "#58b0ff",
       stroke3: "#006bd7",
       stroke4: "#004fa9",
-      stroke2: "#94b5d9",
-      stroke1: "#9fbcdd",
-      bgFillDark: "#1b1e23",
-      fgFillDark: "#eff0f2",
-      bgFillInverted2: "#1b1e23",
+      stroke2: "#95b5d9",
+      stroke1: "#9fbcdc",
+      bgFillDark: "#1a1f24",
+      fgFillDark: "#eef0f3",
+      bgFillInverted2: "#1a1f24",
       bgFillInverted1: "#002a69",
-      fgFillInverted: "#eff0f2",
-      surface1: "#e9f1fa"
+      fgFillInverted: "#eef0f3",
+      surface1: "#e4f1ff"
     },
     direction: "darker"
   },
@@ -109,25 +109,25 @@ var DEFAULT_RAMPS = {
       bgFill1: "#4ab866",
       fgFill: "#1b1f1c",
       bgFill2: "#37a756",
-      surface2: "#f0fcf2",
-      surface6: "#7eea95",
-      surface5: "#b5f1bf",
-      surface4: "#cbf5d1",
+      surface2: "#eaffed",
+      surface6: "#88e89b",
+      surface5: "#aff3bb",
+      surface4: "#c5f7cc",
       surface3: "#fff",
       fgSurface4: "#002900",
       fgSurface3: "#007f30",
       fgSurface2: "#2b9e4e",
-      fgSurface1: "#53c06e",
+      fgSurface1: "#53c16e",
       stroke3: "#007f30",
       stroke4: "#006013",
-      stroke2: "#7dc189",
-      stroke1: "#82c98f",
+      stroke2: "#84c08e",
+      stroke1: "#8ac894",
       bgFillDark: "#1b1f1c",
-      fgFillDark: "#edf2ed",
+      fgFillDark: "#eaf3eb",
       bgFillInverted2: "#1b1f1c",
       bgFillInverted1: "#003701",
-      fgFillInverted: "#edf2ed",
-      surface1: "#dbf8df"
+      fgFillInverted: "#eaf3eb",
+      surface1: "#cbfdd2"
     },
     direction: "darker"
   },
@@ -136,25 +136,25 @@ var DEFAULT_RAMPS = {
       bgFill1: "#f0d149",
       fgFill: "#1f1e1b",
       bgFill2: "#dcbe2f",
-      surface2: "#fdf9e7",
-      surface6: "#ecd264",
-      surface5: "#f5e297",
-      surface4: "#f7eab3",
+      surface2: "#fff9c9",
+      surface6: "#e8d172",
+      surface5: "#f7e18a",
+      surface4: "#fee994",
       surface3: "#fff",
       fgSurface4: "#281d00",
-      fgSurface3: "#836b00",
-      fgSurface2: "#a58700",
-      fgSurface1: "#c7a900",
-      stroke3: "#836b00",
-      stroke4: "#635000",
-      stroke2: "#bfb17a",
-      stroke1: "#c7b97f",
+      fgSurface3: "#826a00",
+      fgSurface2: "#a48600",
+      fgSurface1: "#c6a800",
+      stroke3: "#826a00",
+      stroke4: "#624f00",
+      stroke2: "#bdb17e",
+      stroke1: "#c5b883",
       bgFillDark: "#1f1e1b",
-      fgFillDark: "#f6f1da",
+      fgFillDark: "#fdf1bf",
       bgFillInverted2: "#1f1e1b",
       bgFillInverted1: "#392c00",
-      fgFillInverted: "#f6f1da",
-      surface1: "#f9f0c8"
+      fgFillInverted: "#fdf1bf",
+      surface1: "#ffef9b"
     },
     direction: "darker"
   },
@@ -163,25 +163,25 @@ var DEFAULT_RAMPS = {
       bgFill1: "#f0b849",
       fgFill: "#1f1e1b",
       bgFill2: "#dda633",
-      surface2: "#fdf7ee",
-      surface6: "#f1ce8f",
-      surface5: "#f6e0b9",
-      surface4: "#f8e8cc",
+      surface2: "#fff7e0",
+      surface6: "#f4cc84",
+      surface5: "#faddac",
+      surface4: "#fde6bd",
       surface3: "#fff",
       fgSurface4: "#2e1900",
-      fgSurface3: "#936400",
-      fgSurface2: "#b68000",
-      fgSurface1: "#d8a12c",
-      stroke3: "#936400",
-      stroke4: "#704a00",
-      stroke2: "#caae7c",
-      stroke1: "#d2b581",
+      fgSurface3: "#926300",
+      fgSurface2: "#b47f00",
+      fgSurface1: "#d7a02a",
+      stroke3: "#926300",
+      stroke4: "#6f4900",
+      stroke2: "#c7ad7e",
+      stroke1: "#d0b381",
       bgFillDark: "#1f1e1b",
-      fgFillDark: "#f3f0e9",
+      fgFillDark: "#f7efe2",
       bgFillInverted2: "#1f1e1b",
       bgFillInverted1: "#422800",
-      fgFillInverted: "#f3f0e9",
-      surface1: "#faeeda"
+      fgFillInverted: "#f7efe2",
+      surface1: "#ffecc4"
     },
     direction: "darker"
   },
@@ -190,10 +190,10 @@ var DEFAULT_RAMPS = {
       bgFill1: "#cc1818",
       fgFill: "#f2efef",
       bgFill2: "#b90000",
-      surface2: "#fdf6f5",
-      surface6: "#f5c8c1",
-      surface5: "#f9dbd7",
-      surface4: "#fae4e1",
+      surface2: "#fff6f4",
+      surface6: "#f3c8c2",
+      surface5: "#f8dcd7",
+      surface4: "#f6e6e3",
       surface3: "#fff",
       fgSurface4: "#470000",
       fgSurface3: "#cc1818",
@@ -201,14 +201,14 @@ var DEFAULT_RAMPS = {
       fgSurface1: "#ff8879",
       stroke3: "#cc1818",
       stroke4: "#9d0000",
-      stroke2: "#de988e",
-      stroke1: "#e1a198",
+      stroke2: "#d39c95",
+      stroke1: "#daa39b",
       bgFillDark: "#231c1b",
       fgFillDark: "#f2efef",
       bgFillInverted2: "#231c1b",
       bgFillInverted1: "#640000",
       fgFillInverted: "#f2efef",
-      surface1: "#fbece9"
+      surface1: "#fcece9"
     },
     direction: "darker"
   }