Skip to content

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.md
index 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 its
unit; code that needs pixels resolves the value against the root font size
instead 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 supported
references and color expressions; unsupported expressions remain intact
rather 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 duplicate
across `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.ts
index 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);
+ }
+ });
+});