An open source design system that's fully customizable and agent ready
TypeScript
spec(theme-tokens): name colour tokens by one grammar (#8103)
Cindy Zhang443b80317429
diff --git a/docs/architecture/theme-tokens.md b/docs/architecture/theme-tokens.mdindex 17751f7d90..2bda6fcb94 100644--- a/docs/architecture/theme-tokens.md+++ b/docs/architecture/theme-tokens.md@@ -36,7 +36,7 @@ deciding_specs: [spec:AST-006/DEC-1, spec:AST-006/DEC-5]{"scope": "global","triggers": {- "tokens": ["INV1", "INV3", "INV4", "INV6", "INV8", "INV9"]+ "tokens": ["INV1", "INV3", "INV4", "INV6", "INV8", "INV9", "INV10"]}}```@@ -114,6 +114,37 @@ then have contradictory winners.`resolveThemeToken()`, `tokenDefaults`) return the token's value with itsunit; code that needs pixels resolves the value against the root font sizeinstead of parsing a number.+- **INV10 — Astryx's colour token names follow one grammar.** The grammar+ governs only the colour tokens Astryx defines: the Core `colorDefaults`, the+ domain-layer defaults, and the tokens Astryx's first-party themes set from+ that vocabulary. It does not govern names Astryx does not define, such as a+ product's or application's own CSS variables, a theme author's extensions or+ local tokens (INV8), or another design system's tokens. Every colour token+ Astryx defines takes one of five shapes:+ 1. `--color-<property>-<role>`: a colour for one paint property. The property+ is `text`, `icon`, `background`, or `border`. The role is an emphasis+ (`primary`, `secondary`, `disabled`, `emphasized`), an intent+ (`--color-text-accent`), a surface (`surface`, `body`, `card`, `popover`,+ `muted`, `inverted`), or a hue (`--color-text-green`).+ 2. `--color-<intent>`: the intent's own colour. The intents are `accent`,+ `neutral`, `info`, `success`, `warning`, and `error`.+ 3. A shape-1 or shape-2 name with one variant suffix: `-muted` (the pale+ form), `-emphasized` (the strong form), `-hover` or `-pressed` (an+ interaction state), or `-inverted` (for an inverted surface).+ 4. `--color-on-<fill>`: content placed on a fill, where `<fill>` is a shape-2+ or shape-3 intent name, `dark`, or `light`. `--color-on-<intent>` is+ content on the intent's strong fills, its bare and `-emphasized` forms; a+ `-muted` fill pairs with its own `--color-on-<intent>-muted`.+ 5. `--color-<domain>-…` for a domain layer under INV5: `--color-data-*` and+ `--color-syntax-*`.++ The role-less utility names `--color-border`, `--color-overlay` (with its+ `-hover` and `-pressed` states), `--color-shadow`, `--color-skeleton`,+ `--color-track`, and `--color-tint-hover` keep their names. A new name adds+ no group segment (such as `status`), no other property word (such as+ `foreground`), and no property suffix (such as `-text`). Tailwind keys are a+ projection: a key may alias a token under a shorter name, and it never adds a+ CSS variable.This record does not own:@@ -140,6 +171,8 @@ does not silently change authoring, runtime, compiler, or component contracts.- Changes to JavaScript resolution preserve CSS cascade semantics for supportedreferences and color expressions; unsupported expressions remain intactrather than being guessed.+- Adding a portable colour token chooses its name under INV10; a role the+ grammar cannot name changes INV10 first.- Adding a theme-local name does not update portable defaults, name types,helpers, or generated token docs. Authoring validation rejects a duplicateacross `tokens` and `localTokens` before the compiler or helpers can disagree.@@ -213,5 +246,6 @@ decision).| INV6 | `packages/core/src/theme/tokens.test.ts` | JavaScript resolution disagrees with defaults, mode selection, references, or supported color expressions || INV8 | `defineTheme.test.ts`, template checks, and token-doc generation | A local name enters portable helpers/docs or can conflict with a portable declaration || INV9 | `tokens.test.ts` (core defaults), `SpacingRootFontSize.a11y.chromium.spec.ts` (real-Chromium root font size), each overriding theme's `*Theme.spacing.test.ts`, `check-cli-theme-bundle.test.mjs` (bundled copies byte-equal to the packages), `theme-concentricity.test.ts` (playground ramp read in rem) | A spacing step in `px` that no theme documents as its exception: a core default, a theme override, a bundled copy, or a generated ramp step |+| INV10 | `tokens.test.ts` name check over Astryx's own `colorDefaults` and `domainTokenDefaults` only | A colour token Astryx defines fits none of the five shapes || Released token compatibility | Type checking plus representative package/source builds | A released CSS variable or typed token name disappears without an explicit migration decision || Visual defaults | Real Chromium examples in light, dark, status, and high-contrast contexts | A changed default produces unreadable or semantically inconsistent output |diff --git a/packages/core/src/theme/tokens.test.ts b/packages/core/src/theme/tokens.test.tsindex f5d8542a74..bc60c476ba 100644--- a/packages/core/src/theme/tokens.test.ts+++ b/packages/core/src/theme/tokens.test.ts@@ -8,6 +8,8 @@ import {tokenVar,tokenVars,} from './tokens';+import {colorDefaults} from './tokens.stylex';+import {domainTokenDefaults} from './domainTokens';const testTheme = defineTheme({name: 'test',@@ -329,3 +331,61 @@ describe('focus outline tokens', () => {expect(tokens['--focus-outline-offset']).toBe('0px');});});++// INV10 governs only the colour tokens Astryx defines. The check reads Astryx's+// own defaults, never consumer, application, or theme-author variables.+describe('colour token name grammar (architecture:theme-tokens INV10)', () => {+ const property = '(?:text|icon|background|border)';+ const intent = '(?:accent|neutral|info|success|warning|error)';+ const hue = '(?:blue|cyan|gray|green|orange|pink|purple|red|teal|yellow)';+ const emphasis = '(?:primary|secondary|disabled|emphasized)';+ const surface = '(?:surface|body|card|popover|muted|inverted)';+ const variant = '(?:-(?:muted|emphasized|hover|pressed|inverted))?';+ const shapes = [+ // 1 and 3: property first, then role, then an optional variant.+ `^--color-${property}-(?:${emphasis}|${intent}|${surface}|${hue})${variant}$`,+ // 2 and 3: the intent's own colour, then an optional variant.+ `^--color-${intent}${variant}$`,+ // 4: content on a fill.+ `^--color-on-(?:${intent}${variant}|dark|light)$`,+ // 5: domain layers.+ '^--color-(?:data|syntax)-[a-z0-9-]+$',+ ].map(source => new RegExp(source));+ const utilityNames = new Set([+ '--color-border',+ '--color-overlay',+ '--color-overlay-hover',+ '--color-overlay-pressed',+ '--color-shadow',+ '--color-skeleton',+ '--color-track',+ '--color-tint-hover',+ ]);+ const colourNames = [+ ...Object.keys(colorDefaults),+ ...Object.keys(domainTokenDefaults),+ ].filter(name => name.startsWith('--color-'));++ it('checks a non-empty colour vocabulary', () => {+ expect(colourNames.length).toBeGreaterThan(50);+ });++ it('gives every colour token Astryx defines one of the five shapes', () => {+ const misfits = colourNames.filter(+ name =>+ !utilityNames.has(name) && !shapes.some(shape => shape.test(name)),+ );+ expect(misfits).toEqual([]);+ });++ it('rejects names outside the grammar', () => {+ for (const name of [+ '--color-status-foreground-success',+ '--color-success-text',+ '--color-foreground-error',+ '--color-success-on',+ ]) {+ expect(shapes.some(shape => shape.test(name))).toBe(false);+ }+ });+});