@wordpress/theme 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# (Experimental) Theme
+
+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
+
+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.
+
+## Theme Provider
+
+The `ThemeProvider` is a React component that should wrap your application to provide design tokens and theme context to the child UI components.
+
+```tsx
+import { ThemeProvider } from '@wordpress/theme';
+
+function App() {
+	return (
+		<ThemeProvider color={ { scheme: 'light', accent: 'blue' } }>
+			{ /* Your app content */ }
+		</ThemeProvider>
+	);
+}
+```
+
+The provider can be used recursively to override or modify the theme for a specific subtree.
+
+```tsx
+<ThemeProvider>
+	{ /* system-themed UI components */ }
+	<ThemeProvider color={ { scheme: 'dark' } }>
+		{ /* dark-themed UI components */ }
+		<ThemeProvider color={ { scheme: 'light' } }>
+			{ /* light-themed UI components */ }
+		</ThemeProvider>
+		{ /* dark-themed UI components */ }
+	</ThemeProvider>
+	{ /* system-themed UI components */ }
+</ThemeProvider>
+```
+
+The `ThemeProvider` redefines some of the design system tokens. Components consuming semantic design system tokens will automatically follow the chosen theme. Note that the tokens are defined and inherited using the CSS cascade, and therefore the DOM tree, not the React tree. This is very important when using React portals.
+
+### Building
+
+This package is built in two steps. When `npm run build` is run at the root of the repo, it will first run the "prebuild" step of this package, which is defined in the `build` script of this package's package.json.
+
+This step will:
+
+1. Generate primitive tokens.
+2. Build CSS and JavaScript token files.
+3. Update the design tokens documentation.
+4. Format all generated files.
+
+The files generated in this step will all be committed to the repo.
+
+After the prebuild step, the package will be built into its final form via the repo's standard package build script.
+
+## Contributing to this package
+
+This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
+
+To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
+
+<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

package/bin/build-tokens.js

@@ -0,0 +1,83 @@
+/**
+ * External dependencies
+ */
+const { execSync } = require( 'child_process' );
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Build script for design tokens.
+ *
+ * This script:
+ * 1. Compiles and runs the primitive token generator
+ * 2. Compiles the terrazzo config and runs the Terrazzo build
+ * 3. Cleans up temporary files
+ */
+
+const TEMP_FILES = [
+	'bin/generate-primitive-tokens/index.mjs',
+	'terrazzo.config.mjs',
+];
+
+function cleanup() {
+	TEMP_FILES.forEach( ( file ) => {
+		const filePath = path.join( process.cwd(), file );
+		if ( fs.existsSync( filePath ) ) {
+			fs.unlinkSync( filePath );
+		}
+	} );
+}
+
+// Ensure cleanup happens even if the process exits unexpectedly
+process.on( 'exit', cleanup );
+process.on( 'SIGINT', () => {
+	cleanup();
+	process.exit( 130 );
+} );
+process.on( 'SIGTERM', () => {
+	cleanup();
+	process.exit( 143 );
+} );
+
+try {
+	// Step 1: Compile the primitive token generator
+	console.log( '🔨 Compiling primitive token generator...' );
+	execSync(
+		'npx esbuild bin/generate-primitive-tokens/index.ts --bundle --platform=node --format=esm --packages=external --outfile=bin/generate-primitive-tokens/index.mjs',
+		{
+			stdio: 'inherit',
+			cwd: process.cwd(),
+		}
+	);
+
+	// Step 2: Run the primitive token generator
+	console.log( '🎨 Generating primitive tokens...' );
+	execSync( 'node bin/generate-primitive-tokens/index.mjs', {
+		stdio: 'inherit',
+		cwd: process.cwd(),
+	} );
+
+	// Step 3: Compile the terrazzo config
+	console.log( '🔨 Compiling terrazzo config...' );
+	execSync(
+		'npx esbuild terrazzo.config.ts --bundle --platform=node --format=esm --packages=external --outfile=terrazzo.config.mjs',
+		{
+			stdio: 'inherit',
+			cwd: process.cwd(),
+		}
+	);
+
+	// Step 4: Run terrazzo build
+	console.log( '🏗️  Running terrazzo build...' );
+	execSync( 'npx tz build --config terrazzo.config.mjs', {
+		stdio: 'inherit',
+		cwd: process.cwd(),
+	} );
+
+	console.log( '✅ Token build complete!' );
+} catch ( error ) {
+	console.error( '❌ Build failed:', error.message );
+	process.exit( 1 );
+} finally {
+	cleanup();
+}

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

@@ -0,0 +1,115 @@
+/**
+ * External dependencies
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import Color from 'colorjs.io';
+
+/**
+ * Internal dependencies
+ */
+import {
+	DEFAULT_SEED_COLORS,
+	buildBgRamp,
+	buildAccentRamp,
+} from '../../src/color-ramps/index';
+
+const __filename = fileURLToPath( import.meta.url );
+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: Color;
+		try {
+			parsed = new Color( color ).to( 'oklch' );
+		} catch {
+			return color;
+		}
+
+		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: parsed.to( 'srgb' ).toString( { format: 'hex' } ),
+		};
+	}
+
+	return color;
+};
+
+// Main function
+function generatePrimitiveColorTokens() {
+	const startTime = performance.now();
+	console.log( '🎨 Starting primitive color tokens generation...' );
+
+	try {
+		// Read the color.json file
+		const colorJson = JSON.parse(
+			fs.readFileSync( colorJsonPath, 'utf8' )
+		);
+
+		// Build the ramps
+		const bgRamp = buildBgRamp( { seed: DEFAULT_SEED_COLORS.bg } );
+		const accentRamps = [ ...Object.entries( DEFAULT_SEED_COLORS ) ]
+			.filter( ( [ scaleName ] ) => scaleName !== 'bg' )
+			.map( ( [ scaleName, seed ] ) => ( {
+				scaleName,
+				ramp: buildAccentRamp( {
+					seed,
+					bgRamp,
+				} ),
+			} ) );
+
+		// Convert the ramp values in a DTCG compatible format
+		[
+			{
+				scaleName: 'bg',
+				ramp: bgRamp,
+			},
+			...accentRamps,
+		].forEach( ( { scaleName, ramp } ) => {
+			colorJson.color.primitive[ scaleName ] = {};
+			for ( const [ tokenName, tokenValue ] of Object.entries(
+				ramp.ramp
+			) ) {
+				colorJson.color.primitive[ scaleName ][ tokenName ] = {
+					$value: transformColorStringToDTCGValue( tokenValue.color ),
+				};
+			}
+		} );
+
+		// Write the updated JSON back to the file with proper formatting
+		fs.writeFileSync(
+			colorJsonPath,
+			JSON.stringify( colorJson, null, '\t' )
+		);
+
+		const endTime = performance.now();
+		const duration = endTime - startTime;
+		console.log(
+			`✅ Successfully updated color.json (${ duration.toFixed( 2 ) }ms)`
+		);
+	} catch ( error ) {
+		const endTime = performance.now();
+		const duration = endTime - startTime;
+		console.error(
+			`❌ Error updating color tokens after ${ duration.toFixed(
+				2
+			) }ms:`,
+			error
+		);
+		process.exit( 1 );
+	}
+}
+
+// Run the script
+generatePrimitiveColorTokens();

package/bin/terrazzo-plugin-ds-tokens-docs/index.ts

@@ -0,0 +1,103 @@
+/**
+ * External dependencies
+ */
+import { FORMAT_ID } from '@terrazzo/plugin-css';
+import type { Plugin } from '@terrazzo/parser';
+
+function isPrivateToken( token: string ) {
+	return /-private-/i.test( token );
+}
+
+function titleCase( str: string ) {
+	return str[ 0 ].toUpperCase() + str.slice( 1 );
+}
+
+type TokensMap = Record< string, Record< string, string > >;
+
+export default function pluginDsTokenDocs( {
+	filename = 'design-tokens.md',
+} = {} ): Plugin {
+	return {
+		name: '@terrazzo/terrazzo-plugin-ds-tokens-docs',
+		async build( { getTransforms, outputFile } ) {
+			if ( ! filename ) {
+				return;
+			}
+
+			const primitiveTokens: TokensMap = {};
+			const semanticTokens: TokensMap = {};
+			// Re-use transformed tokens from the CSS plugin
+			for ( const token of getTransforms( {
+				format: FORMAT_ID,
+				id: '*',
+				mode: '.',
+			} ) ) {
+				if ( token.localID === undefined ) {
+					console.warn(
+						'Unexpected — Missing local ID when building token list for eslint plugin'
+					);
+					continue;
+				}
+
+				// Use the tokens filename (without .json) as the group name
+				const group =
+					token.token.source.loc
+						?.split( '/' )
+						.at( -1 )
+						?.split( '.json' )[ 0 ] ?? 'Miscellaneous';
+
+				// Organize tokens in semantic/private, and group by category.
+				const tokensObject = isPrivateToken( token.localID )
+					? primitiveTokens
+					: semanticTokens;
+				tokensObject[ group ] ??= {};
+				tokensObject[ group ][ token.localID ] =
+					token.token.$description ?? 'N/A';
+			}
+
+			function tokensToMdTable(
+				tokens: TokensMap,
+				isPrivate: boolean = false
+			) {
+				return Object.entries( tokens )
+					.map( ( [ group, tokensInGroup ] ) => [
+						`### ${ titleCase( group ) }${
+							isPrivate ? ' (private)' : ''
+						}`,
+						'',
+						'| Variable name | Description |',
+						'|---|---|',
+						...Object.entries( tokensInGroup ).map(
+							( [ name, description ] ) =>
+								`| \`${ name }\` | ${ description } |`
+						),
+						'',
+					] )
+					.flat( 2 );
+			}
+
+			outputFile(
+				filename,
+				[
+					'<!--',
+					'This file is generated by @terrazzo/terrazzo-plugin-ds-tokens-docs.',
+					'Do not edit directly.',
+					'-->',
+					'',
+					'# DS Tokens reference',
+					'',
+					'## Semantic tokens',
+					'',
+					...tokensToMdTable( semanticTokens ),
+					'',
+					'## Primitive tokens',
+					'',
+					'**🚨 Note: These tokens are only private implementation details of the Theme, and should never be referenced / consumed directly in the code.**',
+					'',
+					...tokensToMdTable( primitiveTokens, true ),
+					'', // final empty line
+				].join( '\n' )
+			);
+		},
+	};
+}

package/bin/terrazzo-plugin-figma-ds-token-manager/index.ts

@@ -0,0 +1,210 @@
+/**
+ * External dependencies
+ */
+import type { Plugin, TokenNormalized } from '@terrazzo/parser';
+import { transformCSSValue } from '@terrazzo/token-tools/css';
+import Color from 'colorjs.io';
+
+/**
+ * Internal dependencies
+ */
+import { FORMAT_JSON_ID } from './lib';
+
+function titleCase( str: string ) {
+	return str[ 0 ].toUpperCase() + str.slice( 1 );
+}
+
+function kebabToCamel( str: string ) {
+	return str.replace( /-([a-z])/g, ( _, letter ) => letter.toUpperCase() );
+}
+
+function transformTokenName( { id }: { id: string } ) {
+	return (
+		id
+			// Capitalize first segment
+			.replace( /^(\w+)\./g, ( _, g1 ) => `${ titleCase( g1 ) }/` )
+			// Capitalize
+			.replace( /primitive\./g, '_Primitives/' )
+			.replace( /semantic\./g, 'Semantic/' )
+			.replace(
+				/(color\/_Primitives)\/(\w+)\.(.*)/gi,
+				( _, prefix, tone, rampStep ) => {
+					return `${ prefix }/${ titleCase( tone ) }/${ rampStep }`;
+				}
+			)
+			// Color-specific transformation for semantic tokens:
+			// - add extra folder (Background, Foreground, Stroke)
+			// - swap "tone" folder order, capitalize
+			// - limit bg-* to 6 characters
+			// - keep last part of the token name with dots (eg no folders)
+			.replace(
+				/(color\/Semantic)\/([\w,\-]+)\.(\w+)\.(.*)/gi,
+				( _, prefix, element, tone, emphasisAndState ) => {
+					let extraFolder = '';
+					let elementName = element;
+					if ( /bg/.test( element ) ) {
+						extraFolder = 'Background/';
+						elementName = element.slice( 0, 6 );
+					} else if ( /fg/.test( element ) ) {
+						extraFolder = 'Foreground/';
+						elementName = element.slice( 0, 6 );
+					} else if ( /stroke/.test( element ) ) {
+						extraFolder = 'Stroke/';
+						elementName = element.slice( 0, 10 );
+					}
+					return `${ prefix }/${ extraFolder }${ titleCase(
+						tone
+					) }/${ kebabToCamel(
+						elementName
+					) }.${ tone }.${ emphasisAndState }`;
+				}
+			)
+			// Remove default emphasis and state variants from variable name
+			.replace( /normal\./g, '' )
+			.replace( /resting/g, '' )
+			// Remove double dots
+			.replace( /\.{2,}/g, '.' )
+			// Remove trailing dot
+			.replace( /\.$/g, '' )
+			// Replace remaining dots with dashes
+			.replace( /\./g, '-' )
+	);
+}
+
+function transformColorToken(
+	token: TokenNormalized,
+	mode: string,
+	tokens: Record< string, TokenNormalized >
+) {
+	if (
+		token.mode[ mode ]?.aliasChain &&
+		token.mode[ mode ].aliasChain.length > 0
+	) {
+		// Keep aliases
+		return `{${ transformTokenName( {
+			id: token.mode[ mode ].aliasChain[ 0 ],
+		} ) }}`;
+	}
+	// Start by letting terrazzo do the heavy lifting.
+	const baselineCSSValue = transformCSSValue( token, {
+		mode,
+		tokensSet: tokens,
+		transformAlias: transformTokenName,
+	} );
+
+	if ( baselineCSSValue === undefined ) {
+		console.warn( 'Unexpected: could not tranform color token value' );
+		return;
+	}
+
+	let cssColorValue: string;
+
+	if ( typeof baselineCSSValue === 'object' ) {
+		if ( 'srgb' in baselineCSSValue ) {
+			// Pick SRGB gamut (safer compared to p3 or rec2020)
+			cssColorValue = baselineCSSValue.srgb;
+		} else {
+			console.log( 'UNSUPPORTED USE CASE' );
+			return;
+		}
+	} else {
+		cssColorValue = baselineCSSValue;
+	}
+
+	// Always convert to hex
+	// (easier to convert to Figma RGB, and includes clamping)
+	let convertedColor: Color;
+	try {
+		convertedColor = new Color( cssColorValue );
+	} catch {
+		console.warn( 'Unexpected: could not convert token value to Color' );
+		return;
+	}
+
+	return convertedColor.to( 'srgb' ).toString( { format: 'hex' } );
+}
+
+export default function pluginFigmaDsTokenManager( {
+	filename = 'figma-ds-tokens.json',
+} = {} ): Plugin {
+	return {
+		name: '@terrazzo/plugin-figma-ds-token-manager',
+		async transform( { tokens, getTransforms, setTransform } ) {
+			// skip work if another .json plugin has already run
+			const jsonTokens = getTransforms( {
+				format: FORMAT_JSON_ID,
+				id: '*',
+				mode: '.',
+			} );
+			if ( jsonTokens.length ) {
+				return;
+			}
+
+			for ( const [ id, token ] of Object.entries( tokens ) ) {
+				for ( const mode of Object.keys( token.mode ) ) {
+					const localID = transformTokenName( token );
+
+					let transformedValue;
+
+					if ( token.$type === 'color' ) {
+						transformedValue = transformColorToken(
+							token,
+							mode,
+							tokens
+						);
+					} else if (
+						token.mode[ mode ]?.aliasChain &&
+						token.mode[ mode ].aliasChain.length > 0
+					) {
+						// Keep aliases
+						transformedValue = `{${ transformTokenName( {
+							id: token.mode[ mode ].aliasChain[ 0 ],
+						} ) }}`;
+					} else {
+						// Fallback to terrazzo
+						transformedValue = transformCSSValue( token, {
+							mode,
+							tokensSet: tokens,
+							transformAlias: transformTokenName,
+						} );
+					}
+
+					if ( transformedValue !== undefined ) {
+						setTransform( id, {
+							format: FORMAT_JSON_ID,
+							localID,
+							value: transformedValue,
+							mode,
+						} );
+					}
+				}
+			}
+		},
+		async build( { getTransforms, outputFile } ) {
+			const tokenVals: Record<
+				string,
+				{
+					value: Record< string, string | Record< string, string > >;
+					description?: string;
+				}
+			> = {};
+
+			for ( const token of getTransforms( {
+				format: FORMAT_JSON_ID,
+				id: '*',
+			} ) ) {
+				if ( ! token.localID ) {
+					continue;
+				}
+
+				tokenVals[ token.localID ] ??= { value: {}, description: '' };
+
+				tokenVals[ token.localID ].value[ token.mode ] = token.value;
+				tokenVals[ token.localID ].description =
+					token.token.$description;
+			}
+
+			outputFile( filename, JSON.stringify( tokenVals, null, 2 ) );
+		},
+	};
+}

package/bin/terrazzo-plugin-figma-ds-token-manager/lib.ts

@@ -0,0 +1 @@
+export const FORMAT_JSON_ID = 'json';

package/bin/terrazzo-plugin-known-wpds-css-variables/index.ts

@@ -0,0 +1,72 @@
+/**
+ * External dependencies
+ */
+import { FORMAT_ID } from '@terrazzo/plugin-css';
+import type { Plugin } from '@terrazzo/parser';
+
+function isPrivateToken( token: string ) {
+	return /-private-/i.test( token );
+}
+
+export default function pluginKnownWpdsCssVariables( {
+	exports = [ { filename: 'design-tokens.js', modes: false } ],
+} = {} ): Plugin {
+	return {
+		name: '@terrazzo/plugin-known-wpds-css-variables',
+		async build( { getTransforms, outputFile } ) {
+			// Either a string (modes=false) or an object (modes=true)
+			const tokensToExport: Record<
+				string,
+				Record< string, string | Record< string, string > >
+			> = {};
+
+			for ( const token of getTransforms( {
+				format: FORMAT_ID,
+				id: '*',
+			} ) ) {
+				if ( ! token.localID ) {
+					console.warn(
+						'Unexpected — Missing local ID when building token list for eslint plugin'
+					);
+					continue;
+				}
+
+				if ( ! isPrivateToken( token.localID ) ) {
+					tokensToExport[ token.localID ] ??= {};
+
+					tokensToExport[ token.localID ][ token.mode ] = token.value;
+				}
+			}
+
+			const exportsAsArray = ! Array.isArray( exports )
+				? [ exports ]
+				: exports;
+			for ( const { filename, modes } of exportsAsArray ) {
+				outputFile(
+					filename,
+					[
+						'/**',
+						' * This file is generated by the @terrazzo/plugin-known-wpds-css-variables plugin.',
+						' * Do not edit this file directly.',
+						' */',
+						'',
+						`export default ${ JSON.stringify(
+							modes === false
+								? Array.from(
+										new Set( Object.keys( tokensToExport ) )
+								  )
+								: tokensToExport,
+							null,
+							2
+						) }${
+							filename.endsWith( '.ts' ) && modes
+								? ' as Record< string, Record< string, string > >'
+								: ''
+						}`,
+						'', // final empty line
+					].join( '\n' )
+				);
+			}
+		},
+	};
+}