Theme: Update Figma plugin to convert additional properties

packages/theme/README.md

@@ -13,12 +13,80 @@ 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`.
+
+#### General Token Naming
+
+Most semantic tokens follow a pattern:
+
+```
+--wpds-<type>-<property>-<target>[-<modifier>]
+```
+
+**Type** indicates what kind of value it represents, usually mapping to a DTCG token type.
+
+| Value                | Description                                                                    |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `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                        |
+| -------------------- | ---------------------------------- |
+| `padding`            | Internal spacing within an element |
+| `radius`             | Border radius for rounded corners  |
+| `size`               | Font size or element dimensions    |
+
+**Target** is the component or element type the token applies to.
+
+| Value                | Description                                             |
+| -------------------- | ------------------------------------------------------- |
+| `surface`            | Container or layout backgrounds                         |
+| `interactive`        | Interactive elements like buttons, inputs, and controls |
+| `focus`              | Focus indicators and rings                              |
+
+**Modifier** is an optional size or intensity modifier.
+
+| Value                         | Description          |
+| ----------------------------- | -------------------- |
+| `2xs`, `sm`, `md`, `lg`, `xl` | Size scale modifiers |
+
+#### Color Tokens
+
+Color tokens extend the general token naming scheme with additional structure:
 
 ```
---wpds-<element>-<tone>[-<emphasis>][-<state>]
+--wpds-color-<element>-<tone>[-<emphasis>][-<state>]
 ```
 
 **Element** specifies what the color is applied to.

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

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import type { Plugin, TokenNormalized } from '@terrazzo/parser';
+import { kebabCase } from '@terrazzo/token-tools';
 import { transformCSSValue } from '@terrazzo/token-tools/css';
 import {
 	parse,
@@ -16,66 +17,36 @@ import {
  */
 import '../../src/color-ramps/lib/register-color-spaces';
 import { FORMAT_JSON_ID } from './lib';
+import { publicTokenId } from '../../src/token-id';
 
-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, '-' )
-	);
+/**
+ * Transforms a token ID to a Figma variable name including folders.
+ *
+ * Token IDs are transformed to match the CSS variable naming convention
+ * (`--wpds-<type>-<property>-<target>[-<modifier>]`) but using `/` as
+ * folder separators for the first 3 segments (type, property, target),
+ * with remaining segments joined by dashes.
+ *
+ * Examples:
+ * - `color.bg.surface.info.weak` → `wpds-color/bg/surface/info-weak`
+ * - `dimension.padding.surface.sm` → `wpds-dimension/padding/surface/sm`
+ * - `font.lineHeight.small` → `wpds-font/line-height/small`
+ *
+ * @param options    Options object.
+ * @param options.id The token ID to transform.
+ * @return The transformed token name.
+ */
+function transformTokenName( { id }: { id: string } ): string {
+	const [ type, property, target, ...modifiers ] =
+		publicTokenId( id ).split( '.' );
+
+	return [
+		`wpds-${ type }/${ kebabCase( property ) }`,
+		target && kebabCase( target ),
+		modifiers.map( kebabCase ).join( '-' ),
+	]
+		.filter( Boolean )
+		.join( '/' );
 }
 
 function transformColorToken(