Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: generate token docs from source, add CI drift check (#1654)

Cindy Zhang4376bb7a646d
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7ef1fc46e9..d0ed7df7c0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -58,6 +58,9 @@ jobs:
- name: Check package.json exports are in sync
run: node scripts/sync-exports.js --check
+ - name: Check token docs are in sync
+ run: node scripts/generate-token-docs.mjs --check
+
- run: yarn test
# Build storybook + analyze components (parallel with test)
diff --git a/packages/cli/docs/tokens.doc.mjs b/packages/cli/docs/tokens.doc.mjs
index 08ae3b3b17..414166938c 100644
--- a/packages/cli/docs/tokens.doc.mjs
+++ b/packages/cli/docs/tokens.doc.mjs
@@ -1,251 +1,1052 @@
+// AUTO-GENERATED — do not edit manually.
+// Source: packages/core/src/theme/tokens.stylex.ts
+// Run: node scripts/generate-token-docs.mjs
+// Total: 182 tokens across 12 categories.
+
/** @type {import('../../core/src/docs-types').ReferenceDoc} */
export const docs = {
- name: 'tokens',
- title: 'XDS Design Tokens',
- description: 'Spacing, color, radius, typography, and shadow token reference.',
-
- sections: [
+ "name": "tokens",
+ "title": "XDS Design Tokens",
+ "description": "Complete reference for spacing, color, radius, typography, shadow, motion, and size tokens.",
+ "sections": [
{
- title: 'Spacing Tokens',
- content: [
+ "title": "Color Tokens",
+ "content": [
{
- type: 'prose',
- text: 'All design tokens are defined in packages/core/src/theme/tokens.stylex.ts. Component gap props use space0-space12 which map to these tokens.',
+ "type": "prose",
+ "text": "Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching."
},
{
- type: 'table',
- headers: ['Token', 'Value', 'Usage'],
- rows: [
- ['--spacing-0', '0px', 'No spacing'],
- ['--spacing-0-5', '2px', 'Hairline spacing'],
- ['--spacing-1', '4px', 'Tight spacing'],
- ['--spacing-2', '8px', 'Compact spacing'],
- ['--spacing-3', '12px', 'Default small'],
- ['--spacing-4', '16px', 'Default medium'],
- ['--spacing-5', '20px', 'Comfortable'],
- ['--spacing-6', '24px', 'Loose'],
- ['--spacing-7', '28px', 'Semi-loose'],
- ['--spacing-8', '32px', 'Extra loose'],
- ['--spacing-9', '36px', 'Spacious'],
- ['--spacing-10', '40px', 'Extra spacious'],
- ['--spacing-11', '44px', 'Ultra spacious'],
- ['--spacing-12', '48px', 'Maximum spacing'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Light",
+ "Dark"
],
- },
- ],
+ "rows": [
+ [
+ "--color-accent",
+ "#0064E0",
+ "#2694FE"
+ ],
+ [
+ "--color-accent-muted",
+ "#0082FB33",
+ "#0082FB3F"
+ ],
+ [
+ "--color-on-accent",
+ "#FFFFFF",
+ "#FFFFFF"
+ ],
+ [
+ "--color-neutral",
+ "light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))",
+ "light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))"
+ ],
+ [
+ "--color-background-surface",
+ "#FFFFFF",
+ "#1F1F22"
+ ],
+ [
+ "--color-background-body",
+ "#F1F4F7",
+ "#111112"
+ ],
+ [
+ "--color-overlay",
+ "#01122866",
+ "#11111299"
+ ],
+ [
+ "--color-overlay-hover",
+ "#0536590C",
+ "#FFFFFF0C"
+ ],
+ [
+ "--color-overlay-pressed",
+ "#05365919",
+ "#FFFFFF19"
+ ],
+ [
+ "--color-background-muted",
+ "#0536590C",
+ "#1111127F"
+ ],
+ [
+ "--color-text-primary",
+ "#0A1317",
+ "#DFE2E5"
+ ],
+ [
+ "--color-text-secondary",
+ "#4E606F",
+ "#AAAFB5"
+ ],
+ [
+ "--color-text-disabled",
+ "#A4B0BC",
+ "#6F747C"
+ ],
+ [
+ "--color-text-accent",
+ "#0064E0",
+ "#3E9EFB"
+ ],
+ [
+ "--color-on-dark",
+ "#FFFFFF",
+ "#FFFFFF"
+ ],
+ [
+ "--color-on-light",
+ "#000000",
+ "#000000"
+ ],
+ [
+ "--color-icon-accent",
+ "#0064E0",
+ "#2694FE"
+ ],
+ [
+ "--color-icon-primary",
+ "#0A1317",
+ "#DFE2E5"
+ ],
+ [
+ "--color-icon-secondary",
+ "#4E606F",
+ "#AAAFB5"
+ ],
+ [
+ "--color-icon-disabled",
+ "#A4B0BC",
+ "#6F747C"
+ ],
+ [
+ "--color-background-card",
+ "#FFFFFF",
+ "#1F1F22"
+ ],
+ [
+ "--color-background-popover",
+ "#FFFFFF",
+ "#28292C"
+ ],
+ [
+ "--color-background-inverted",
+ "#0A1317",
+ "#FFFFFF"
+ ],
+ [
+ "--color-background-error-inverted",
+ "#AA071E",
+ "#E3193B"
+ ],
+ [
+ "--color-success",
+ "#0D8626",
+ "#0D8626"
+ ],
+ [
+ "--color-success-muted",
+ "#0B991F33",
+ "#0B991F3F"
+ ],
+ [
+ "--color-on-success",
+ "#FFFFFF",
+ "#FFFFFF"
+ ],
+ [
+ "--color-error",
+ "#E3193B",
+ "#F5394F"
+ ],
+ [
+ "--color-error-muted",
+ "#E3193B33",
+ "#F5394F3F"
+ ],
+ [
+ "--color-on-error",
+ "#FFFFFF",
+ "#FFFFFF"
+ ],
+ [
+ "--color-warning",
+ "#E9AF08",
+ "#F2C00B"
+ ],
+ [
+ "--color-warning-muted",
+ "#E2A40033",
+ "#E2A4003F"
+ ],
+ [
+ "--color-on-warning",
+ "#0A1317",
+ "#0A1317"
+ ],
+ [
+ "--color-border",
+ "#05365919",
+ "#F2F4F619"
+ ],
+ [
+ "--color-border-emphasized",
+ "#CCD3DB",
+ "#494D53"
+ ],
+ [
+ "--color-skeleton",
+ "#CCD3DB",
+ "#5A5E66"
+ ],
+ [
+ "--color-shadow",
+ "light-dark(rgba(5, 54, 89, 0.1), rgba(0, 0, 0, 0.3))",
+ "light-dark(rgba(5, 54, 89, 0.1), rgba(0, 0, 0, 0.3))"
+ ],
+ [
+ "--color-tint-hover",
+ "black",
+ "white"
+ ],
+ [
+ "--color-background-blue",
+ "#0171E333",
+ "#0171E333"
+ ],
+ [
+ "--color-border-blue",
+ "#0171E3",
+ "#4BA9FE"
+ ],
+ [
+ "--color-icon-blue",
+ "#0064E0",
+ "#2694FE"
+ ],
+ [
+ "--color-text-blue",
+ "#042F97",
+ "#AFD7FF"
+ ],
+ [
+ "--color-background-cyan",
+ "#03A7D733",
+ "#03A7D733"
+ ],
+ [
+ "--color-border-cyan",
+ "#00BCD4",
+ "#4DD0E1"
+ ],
+ [
+ "--color-icon-cyan",
+ "#00ACC1",
+ "#26C6DA"
+ ],
+ [
+ "--color-text-cyan",
+ "#014975",
+ "#A1EEF9"
+ ],
+ [
+ "--color-background-gray",
+ "#0A131733",
+ "#666A724C"
+ ],
+ [
+ "--color-border-gray",
+ "#647685",
+ "#8C939B"
+ ],
+ [
+ "--color-icon-gray",
+ "#4E606F",
+ "#AAAFB5"
+ ],
+ [
+ "--color-text-gray",
+ "#0A1317",
+ "#E7EAED"
+ ],
+ [
+ "--color-background-green",
+ "#24BB5E33",
+ "#24BB5E33"
+ ],
+ [
+ "--color-border-green",
+ "#24BB5E",
+ "#4CD964"
+ ],
+ [
+ "--color-icon-green",
+ "#0D8626",
+ "#26A756"
+ ],
+ [
+ "--color-text-green",
+ "#09441F",
+ "#A5F690"
+ ],
+ [
+ "--color-background-orange",
+ "#F2790233",
+ "#F2790233"
+ ],
+ [
+ "--color-border-orange",
+ "#F27902",
+ "#FFA040"
+ ],
+ [
+ "--color-icon-orange",
+ "#E9690B",
+ "#FB8C00"
+ ],
+ [
+ "--color-text-orange",
+ "#6B2203",
+ "#FDB876"
+ ],
+ [
+ "--color-background-pink",
+ "#E638B333",
+ "#E638B333"
+ ],
+ [
+ "--color-border-pink",
+ "#E91E63",
+ "#F48FB1"
+ ],
+ [
+ "--color-icon-pink",
+ "#C2185B",
+ "#EC407A"
+ ],
+ [
+ "--color-text-pink",
+ "#650053",
+ "#FEADE3"
+ ],
+ [
+ "--color-background-purple",
+ "#7952FF33",
+ "#7952FF33"
+ ],
+ [
+ "--color-border-purple",
+ "#7952FF",
+ "#9575CD"
+ ],
+ [
+ "--color-icon-purple",
+ "#5B08D8",
+ "#7952FF"
+ ],
+ [
+ "--color-text-purple",
+ "#3E0697",
+ "#B3B0FE"
+ ],
+ [
+ "--color-background-red",
+ "#E3193B33",
+ "#E3193B33"
+ ],
+ [
+ "--color-border-red",
+ "#E3193B",
+ "#F5394F"
+ ],
+ [
+ "--color-icon-red",
+ "#D31130",
+ "#E3193B"
+ ],
+ [
+ "--color-text-red",
+ "#7B0210",
+ "#FFB2B8"
+ ],
+ [
+ "--color-background-teal",
+ "#0DB7AF33",
+ "#0DB7AF33"
+ ],
+ [
+ "--color-border-teal",
+ "#0DB7AF",
+ "#4DB6AC"
+ ],
+ [
+ "--color-icon-teal",
+ "#009688",
+ "#26A69A"
+ ],
+ [
+ "--color-text-teal",
+ "#083943",
+ "#40DCCD"
+ ],
+ [
+ "--color-background-yellow",
+ "#E2A40033",
+ "#E2A40033"
+ ],
+ [
+ "--color-border-yellow",
+ "#FFEB3B",
+ "#FFF176"
+ ],
+ [
+ "--color-icon-yellow",
+ "#FBC02D",
+ "#FFEE58"
+ ],
+ [
+ "--color-text-yellow",
+ "#753F07",
+ "#FBCE03"
+ ]
+ ]
+ }
+ ]
},
{
- title: 'Size Tokens',
- content: [
+ "title": "Spacing Tokens",
+ "content": [
{
- type: 'prose',
- text: 'Control heights for consistent sizing across buttons, inputs, and selectors.',
+ "type": "prose",
+ "text": "Spacing scale used for padding, gap, and margin. Component gap props map spacing steps to these tokens."
},
{
- type: 'table',
- headers: ['Token', 'Value', 'Usage'],
- rows: [
- ['--size-element-sm', '28px', 'Compact controls'],
- ['--size-element-md', '32px', 'Default control size'],
- ['--size-element-lg', '36px', 'Larger, more prominent controls'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
- },
- ],
+ "rows": [
+ [
+ "--spacing-0",
+ "0px"
+ ],
+ [
+ "--spacing-0-5",
+ "2px"
+ ],
+ [
+ "--spacing-1",
+ "4px"
+ ],
+ [
+ "--spacing-1-5",
+ "6px"
+ ],
+ [
+ "--spacing-2",
+ "8px"
+ ],
+ [
+ "--spacing-3",
+ "12px"
+ ],
+ [
+ "--spacing-4",
+ "16px"
+ ],
+ [
+ "--spacing-5",
+ "20px"
+ ],
+ [
+ "--spacing-6",
+ "24px"
+ ],
+ [
+ "--spacing-7",
+ "28px"
+ ],
+ [
+ "--spacing-8",
+ "32px"
+ ],
+ [
+ "--spacing-9",
+ "36px"
+ ],
+ [
+ "--spacing-10",
+ "40px"
+ ],
+ [
+ "--spacing-11",
+ "44px"
+ ],
+ [
+ "--spacing-12",
+ "48px"
+ ]
+ ]
+ }
+ ]
},
{
- title: 'Color Tokens',
- content: [
+ "title": "Size Tokens",
+ "content": [
{
- type: 'prose',
- text: 'Semantic colors for consistent theming. All colors support light-dark() for automatic mode switching.',
+ "type": "prose",
+ "text": "Control heights for consistent sizing across buttons, inputs, and selectors."
},
{
- type: 'table',
- headers: ['Token', 'Usage'],
- rows: [
- ['--color-accent', 'Primary action color'],
- ['--color-background-surface', 'Background surface'],
- ['--color-background-body', 'Secondary background'],
- ['--color-success', 'Success states'],
- ['--color-error', 'Error states'],
- ['--color-warning', 'Warning states'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
+ "rows": [
+ [
+ "--size-element-sm",
+ "28px"
+ ],
+ [
+ "--size-element-md",
+ "32px"
+ ],
+ [
+ "--size-element-lg",
+ "36px"
+ ]
+ ]
+ }
+ ]
+ },
+ {
+ "title": "Border Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Border width for card and input borders."
},
{
- type: 'table',
- headers: ['Token', 'Usage'],
- rows: [
- ['--color-text-primary', 'Main text'],
- ['--color-text-secondary', 'Secondary text'],
- ['--color-text-disabled', 'Disabled text'],
- ['--color-text-accent', 'Link text'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
+ "rows": [
+ [
+ "--border-width",
+ "1px"
+ ]
+ ]
+ }
+ ]
+ },
+ {
+ "title": "Radius Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Numeric scale based on a 4dp base unit. Tokens scale with the theme's radius multiplier; --radius-none and --radius-full are fixed."
},
{
- type: 'table',
- headers: ['Token', 'Usage'],
- rows: [
- ['--color-icon-primary', 'Main icons'],
- ['--color-icon-secondary', 'Secondary icons'],
- ['--color-icon-disabled', 'Disabled icons'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
- },
- ],
+ "rows": [
+ [
+ "--radius-none",
+ "0px"
+ ],
+ [
+ "--radius-inner",
+ "4px"
+ ],
+ [
+ "--radius-element",
+ "8px"
+ ],
+ [
+ "--radius-container",
+ "12px"
+ ],
+ [
+ "--radius-page",
+ "28px"
+ ],
+ [
+ "--radius-full",
+ "9999px"
+ ]
+ ]
+ }
+ ]
},
{
- title: 'Radius Tokens',
- content: [
+ "title": "Shadow Tokens",
+ "content": [
{
- type: 'prose',
- text: 'Numeric scale based on a 4dp base unit. Tokens 1–4 scale with the theme\'s radius multiplier; tokens 0 and rounded are fixed.',
+ "type": "prose",
+ "text": "Elevation shadows (low → med → high) and inset shadows for input state rings."
},
{
- type: 'table',
- headers: ['Token', 'Value', 'Usage', 'Scales'],
- rows: [
- ['--radius-none', '0px', 'No radius (dividers, table cells)', 'No'],
- ['--radius-inner', '4px', 'Code blocks, inner content', 'Yes'],
- ['--radius-element', '8px', 'Buttons, inputs, text areas', 'Yes'],
- ['--radius-container', '12px', 'Cards, modals, popovers, dropdowns', 'Yes'],
- ['--radius-page', '28px', 'Page sections, large containers', 'Yes'],
- ['--radius-full', '9999px', 'Badges, avatars, status dots, toggles', 'No'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
- },
+ "rows": [
+ [
+ "--shadow-low",
+ "0px 1px 1px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 8px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"
+ ],
+ [
+ "--shadow-med",
+ "0px 1px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 12px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"
+ ],
+ [
+ "--shadow-high",
+ "0px 2px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 8px 24px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.3))"
+ ],
+ [
+ "--shadow-inset-hover",
+ "inset 0px 0px 0px 2px rgba(1, 113, 227, 0.3)"
+ ],
+ [
+ "--shadow-inset-selected",
+ "inset 0px 0px 0px 2px rgba(1, 113, 227, 0.5)"
+ ],
+ [
+ "--shadow-inset-success",
+ "inset 0px 0px 0px 2px rgba(38, 167, 86, 0.3)"
+ ],
+ [
+ "--shadow-inset-warning",
+ "inset 0px 0px 0px 2px rgba(226, 164, 0, 0.3)"
+ ],
+ [
+ "--shadow-inset-error",
+ "inset 0px 0px 0px 2px rgba(227, 25, 59, 0.3)"
+ ]
+ ]
+ }
+ ]
+ },
+ {
+ "title": "Duration Tokens",
+ "content": [
{
- type: 'prose',
- text: 'Use radius in defineTheme to generate all radius tokens from a base unit and multiplier: defineTheme({ radius: { base: 4, multiplier: 1.5 } }). Multiplier 0 = sharp, 1 = default, 1.5 = rounded, 2 = pill-like. Explicit token overrides take precedence over radius values.',
+ "type": "prose",
+ "text": "Motion duration primitives. Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous). Min/max variants derive from base × ratio."
},
{
- type: 'code',
- lang: 'tsx',
- label: 'radius example',
- code: `import {defineTheme} from '@xds/core/theme';
-
-// Rounded theme — all scalable radii increased by 50%
-const roundedTheme = defineTheme({
- name: 'rounded',
- radius: { base: 4, multiplier: 1.5 },
-});
-
-// Sharp/brutalist theme — all scalable radii become 0
-const sharpTheme = defineTheme({
- name: 'sharp',
- radius: { base: 4, multiplier: 0 },
- tokens: { '--radius-full': '0px' }, // even pills are sharp
-});`,
- },
- ],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
+ ],
+ "rows": [
+ [
+ "--duration-fast-min",
+ "130ms"
+ ],
+ [
+ "--duration-fast",
+ "175ms"
+ ],
+ [
+ "--duration-fast-max",
+ "230ms"
+ ],
+ [
+ "--duration-medium-min",
+ "310ms"
+ ],
+ [
+ "--duration-medium",
+ "410ms"
+ ],
+ [
+ "--duration-medium-max",
+ "550ms"
+ ],
+ [
+ "--duration-slow-min",
+ "730ms"
+ ],
+ [
+ "--duration-slow",
+ "975ms"
+ ],
+ [
+ "--duration-slow-max",
+ "1300ms"
+ ]
+ ]
+ }
+ ]
},
{
- title: 'Shadow Tokens',
- content: [
- {
- type: 'table',
- headers: ['Token', 'Usage'],
- rows: [
- ['--shadow-low', 'Subtle lift (cards, menus, popovers)'],
- ['--shadow-med', 'Hover lift, toasts'],
- ['--shadow-high', 'Dialogs, modals'],
- ['--shadow-inset-hover', 'Input hover ring'],
- ['--shadow-inset-selected', 'Input focused/active ring'],
- ['--shadow-inset-success', 'Input success ring'],
- ['--shadow-inset-warning', 'Input warning ring'],
- ['--shadow-inset-error', 'Input error ring'],
- ],
+ "title": "Easing Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Easing curves for animations and transitions."
},
- ],
+ {
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
+ ],
+ "rows": [
+ [
+ "--ease-standard",
+ "cubic-bezier(0.24, 1, 0.4, 1)"
+ ]
+ ]
+ }
+ ]
},
{
- title: 'Typography Tokens',
- content: [
- {
- type: 'list',
- style: 'unordered',
- items: [
- '--font-family-body: System UI font stack',
- '--font-family-code: Monospace font stack',
- '--font-family-heading: System UI font stack',
- ],
+ "title": "Font Family Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Font family stacks for body, code, and heading text."
},
{
- type: 'table',
- headers: ['Token', 'Value'],
- rows: [
- ['--font-size-4xs', '8px'],
- ['--font-size-3xs', '10px'],
- ['--font-size-2xs', '11px'],
- ['--font-size-xs', '12px'],
- ['--font-size-sm', '13px'],
- ['--font-size-base', '14px (default)'],
- ['--font-size-lg', '16px'],
- ['--font-size-xl', '18px'],
- ['--font-size-2xl', '20px'],
- ['--font-size-3xl', '24px'],
- ['--font-size-4xl', '32px'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
+ "rows": [
+ [
+ "--font-family-body",
+ "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+ ],
+ [
+ "--font-family-code",
+ "\"SF Mono\", Monaco, Consolas, monospace"
+ ],
+ [
+ "--font-family-heading",
+ "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+ ]
+ ]
+ }
+ ]
+ },
+ {
+ "title": "Font Size Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base)."
},
{
- type: 'list',
- style: 'unordered',
- items: [
- '--font-weight-normal: 400',
- '--font-weight-medium: 500',
- '--font-weight-semibold: 600',
- '--font-weight-bold: 700',
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
+ "rows": [
+ [
+ "--font-size-4xs",
+ "0.375rem"
+ ],
+ [
+ "--font-size-3xs",
+ "0.4375rem"
+ ],
+ [
+ "--font-size-2xs",
+ "0.5rem"
+ ],
+ [
+ "--font-size-xs",
+ "0.625rem"
+ ],
+ [
+ "--font-size-sm",
+ "0.75rem"
+ ],
+ [
+ "--font-size-base",
+ "0.875rem"
+ ],
+ [
+ "--font-size-lg",
+ "1.0625rem"
+ ],
+ [
+ "--font-size-xl",
+ "1.25rem"
+ ],
+ [
+ "--font-size-2xl",
+ "1.5rem"
+ ],
+ [
+ "--font-size-3xl",
+ "1.8125rem"
+ ],
+ [
+ "--font-size-4xl",
+ "2.1875rem"
+ ],
+ [
+ "--font-size-5xl",
+ "2.625rem"
+ ]
+ ]
+ }
+ ]
+ },
+ {
+ "title": "Font Weight Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Font weight values for body, emphasis, and headings."
},
{
- type: 'table',
- headers: ['Token', 'Value', 'Usage'],
- rows: [
- ['--leading-tight', '1.25', 'Display text, headings'],
- ['--leading-snug', '1.375', 'Compact body text, headings'],
- ['--leading-base', '1.4286', 'Body text with --font-size-base'],
- ['--leading-normal', '1.5', 'Body text, large body'],
- ['--leading-relaxed', '1.625', 'Editorial body, reading text'],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
],
- },
- ],
+ "rows": [
+ [
+ "--font-weight-normal",
+ "400"
+ ],
+ [
+ "--font-weight-medium",
+ "500"
+ ],
+ [
+ "--font-weight-semibold",
+ "600"
+ ],
+ [
+ "--font-weight-bold",
+ "700"
+ ]
+ ]
+ }
+ ]
},
{
- title: 'Usage in StyleX',
- content: [
- {
- type: 'code',
- lang: 'tsx',
- label: 'Using token imports',
- code: `import * as stylex from '@stylexjs/stylex';
-import {colorVars, spacingVars, sizeVars, radiusVars} from '@xds/core';
-
-const styles = stylex.create({
- card: {
- padding: spacingVars['--spacing-4'],
- backgroundColor: colorVars['--color-background-surface'],
- borderRadius: radiusVars['--radius-container'],
- },
- button: {
- height: sizeVars['--size-element-md'],
- },
-});`,
- },
+ "title": "Type Scale Tokens",
+ "content": [
{
- type: 'code',
- lang: 'tsx',
- label: 'Using CSS custom properties directly',
- code: `const styles = stylex.create({
- card: {
- padding: 'var(--spacing-4)',
- backgroundColor: 'var(--color-background-surface)',
- borderRadius: 'var(--radius-container)',
- },
-});`,
+ "type": "prose",
+ "text": "Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme."
},
{
- type: 'prose',
- text: 'See `npx xds docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx xds docs theme` for overriding tokens with defineTheme.',
- },
- ],
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
+ ],
+ "rows": [
+ [
+ "--text-heading-1-size",
+ "var(--font-size-2xl)"
+ ],
+ [
+ "--text-heading-1-weight",
+ "var(--font-weight-semibold)"
+ ],
+ [
+ "--text-heading-1-leading",
+ "1.3333"
+ ],
+ [
+ "--text-heading-2-size",
+ "var(--font-size-xl)"
+ ],
+ [
+ "--text-heading-2-weight",
+ "var(--font-weight-semibold)"
+ ],
+ [
+ "--text-heading-2-leading",
+ "1.4"
+ ],
+ [
+ "--text-heading-3-size",
+ "var(--font-size-lg)"
+ ],
+ [
+ "--text-heading-3-weight",
+ "var(--font-weight-semibold)"
+ ],
+ [
+ "--text-heading-3-leading",
+ "1.4118"
+ ],
+ [
+ "--text-heading-4-size",
+ "var(--font-size-base)"
+ ],
+ [
+ "--text-heading-4-weight",
+ "var(--font-weight-semibold)"
+ ],
+ [
+ "--text-heading-4-leading",
+ "1.4286"
+ ],
+ [
+ "--text-heading-5-size",
+ "var(--font-size-sm)"
+ ],
+ [
+ "--text-heading-5-weight",
+ "var(--font-weight-semibold)"
+ ],
+ [
+ "--text-heading-5-leading",
+ "1.6667"
+ ],
+ [
+ "--text-heading-6-size",
+ "var(--font-size-xs)"
+ ],
+ [
+ "--text-heading-6-weight",
+ "var(--font-weight-semibold)"
+ ],
+ [
+ "--text-heading-6-leading",
+ "1.6"
+ ],
+ [
+ "--text-body-size",
+ "var(--font-size-base)"
+ ],
+ [
+ "--text-body-weight",
+ "var(--font-weight-normal)"
+ ],
+ [
+ "--text-body-leading",
+ "1.4286"
+ ],
+ [
+ "--text-large-size",
+ "var(--font-size-lg)"
+ ],
+ [
+ "--text-large-weight",
+ "var(--font-weight-semibold)"
+ ],
+ [
+ "--text-large-leading",
+ "1.4118"
+ ],
+ [
+ "--text-label-size",
+ "var(--font-size-base)"
+ ],
+ [
+ "--text-label-weight",
+ "var(--font-weight-medium)"
+ ],
+ [
+ "--text-label-leading",
+ "1.4286"
+ ],
+ [
+ "--text-code-size",
+ "var(--font-size-base)"
+ ],
+ [
+ "--text-code-weight",
+ "var(--font-weight-normal)"
+ ],
+ [
+ "--text-code-leading",
+ "1.4286"
+ ],
+ [
+ "--text-supporting-size",
+ "var(--font-size-sm)"
+ ],
+ [
+ "--text-supporting-weight",
+ "var(--font-weight-normal)"
+ ],
+ [
+ "--text-supporting-leading",
+ "1.6667"
+ ],
+ [
+ "--text-display-1-size",
+ "var(--font-size-5xl)"
+ ],
+ [
+ "--text-display-1-weight",
+ "var(--font-weight-normal)"
+ ],
+ [
+ "--text-display-1-leading",
+ "1.2381"
+ ],
+ [
+ "--text-display-2-size",
+ "var(--font-size-4xl)"
+ ],
+ [
+ "--text-display-2-weight",
+ "var(--font-weight-normal)"
+ ],
+ [
+ "--text-display-2-leading",
+ "1.2571"
+ ],
+ [
+ "--text-display-3-size",
+ "var(--font-size-3xl)"
+ ],
+ [
+ "--text-display-3-weight",
+ "var(--font-weight-normal)"
+ ],
+ [
+ "--text-display-3-leading",
+ "1.2414"
+ ]
+ ]
+ }
+ ]
},
- ],
+ {
+ "title": "Usage in StyleX",
+ "content": [
+ {
+ "type": "code",
+ "lang": "tsx",
+ "label": "Using token imports",
+ "code": "import * as stylex from '@stylexjs/stylex';\nimport {colorVars, spacingVars, sizeVars, radiusVars} from '@xds/core';\n\nconst styles = stylex.create({\n card: {\n padding: spacingVars['--spacing-4'],\n backgroundColor: colorVars['--color-background-surface'],\n borderRadius: radiusVars['--radius-container'],\n },\n button: {\n height: sizeVars['--size-element-md'],\n },\n});"
+ },
+ {
+ "type": "prose",
+ "text": "See `npx xds docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx xds docs theme` for overriding tokens with defineTheme."
+ }
+ ]
+ }
+ ]
};
diff --git a/packages/core/src/theme/tokens.stylex.ts b/packages/core/src/theme/tokens.stylex.ts
index 8514a8888f..0ae7b4fa16 100644
--- a/packages/core/src/theme/tokens.stylex.ts
+++ b/packages/core/src/theme/tokens.stylex.ts
@@ -5,7 +5,8 @@
* - *Defaults: Plain objects with default values (used by defineVars and themes)
* - *Vars: CSS custom properties that themes can override via createTheme
*
- * SYNC: When modified, update /packages/agent-tools/docs/tokens.md
+ * SYNC: When modified, run `node scripts/generate-token-docs.mjs` to update docs.
+ * CI checks for drift via --check flag.
*
* Domain tokens (syntax highlighting, data visualization) live separately in
* /packages/core/src/theme/domainTokens/ — they're tree-shaken from core components.
diff --git a/scripts/generate-token-docs.mjs b/scripts/generate-token-docs.mjs
new file mode 100644
index 0000000000..ef4e0d53f4
--- /dev/null
+++ b/scripts/generate-token-docs.mjs
@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+/**
+ * @file generate-token-docs.mjs
+ * @description Generates packages/cli/docs/tokens.doc.mjs from the source of
+ * truth: packages/core/src/theme/tokens.stylex.ts
+ *
+ * Run: node scripts/generate-token-docs.mjs
+ * CI: Add to lint or build to catch drift.
+ *
+ * Reads the *Defaults export objects from tokens.stylex.ts, groups them by
+ * category, and writes a ReferenceDoc-shaped .doc.mjs file.
+ */
+
+import {readFileSync, writeFileSync} from 'node:fs';
+import {resolve, dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const TOKENS_SRC = resolve(
+ ROOT,
+ 'packages/core/src/theme/tokens.stylex.ts',
+);
+const TOKENS_DOC = resolve(ROOT, 'packages/cli/docs/tokens.doc.mjs');
+
+// ---------------------------------------------------------------------------
+// 1. Parse token groups from source
+// ---------------------------------------------------------------------------
+
+const src = readFileSync(TOKENS_SRC, 'utf-8');
+
+/**
+ * Extract key-value pairs from a `const xxxDefaults = { ... } as const;` block.
+ * Returns array of [tokenName, defaultValue].
+ */
+function extractDefaults(name) {
+ // Match: `export const <name> = {` ... `} as const;`
+ const re = new RegExp(
+ `export const ${name}\\s*=\\s*\\{([^}]+(?:\\{[^}]*\\}[^}]*)*)\\}\\s*as const`,
+ 's',
+ );
+ const m = src.match(re);
+ if (!m) return [];
+
+ const body = m[1];
+ const pairs = [];
+ // Match lines like: '--token-name': 'value', or '--token-name': '...',
+ // Also handles multi-line values (e.g. shadow tokens with commas inside)
+ const lineRe = /^\s*'(--[^']+)':\s*'([^']*(?:'[^']*'[^']*)*)',?\s*$/;
+ // Simpler: match '--key': 'value' or '--key': "value" on each entry
+ const entryRe = /'(--[^']+)':\s*'([^']*)'/g;
+ let em;
+ while ((em = entryRe.exec(body)) !== null) {
+ pairs.push([em[1], em[2]]);
+ }
+ return pairs;
+}
+
+/** Map of group name → { exportName, title, description, headers } */
+const groups = [
+ {
+ key: 'color',
+ exportName: 'colorDefaults',
+ title: 'Color Tokens',
+ description:
+ 'Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching.',
+ headers: ['Token', 'Light', 'Dark'],
+ formatRow(name, value) {
+ const ldMatch = value.match(
+ /^light-dark\(([^,]+),\s*([^)]+)\)$/,
+ );
+ if (ldMatch) return [name, ldMatch[1].trim(), ldMatch[2].trim()];
+ return [name, value, value];
+ },
+ },
+ {
+ key: 'spacing',
+ exportName: 'spacingDefaults',
+ title: 'Spacing Tokens',
+ description:
+ 'Spacing scale used for padding, gap, and margin. Component gap props map spacing steps to these tokens.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'size',
+ exportName: 'sizeDefaults',
+ title: 'Size Tokens',
+ description:
+ 'Control heights for consistent sizing across buttons, inputs, and selectors.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'border',
+ exportName: 'borderDefaults',
+ title: 'Border Tokens',
+ description: 'Border width for card and input borders.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'radius',
+ exportName: 'radiusDefaults',
+ title: 'Radius Tokens',
+ description:
+ "Numeric scale based on a 4dp base unit. Tokens scale with the theme's radius multiplier; --radius-none and --radius-full are fixed.",
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'shadow',
+ exportName: 'shadowDefaults',
+ title: 'Shadow Tokens',
+ description:
+ 'Elevation shadows (low → med → high) and inset shadows for input state rings.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'duration',
+ exportName: 'durationDefaults',
+ title: 'Duration Tokens',
+ description:
+ 'Motion duration primitives. Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous). Min/max variants derive from base × ratio.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'ease',
+ exportName: 'easeDefaults',
+ title: 'Easing Tokens',
+ description: 'Easing curves for animations and transitions.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'typography',
+ exportName: 'typographyDefaults',
+ title: 'Font Family Tokens',
+ description: 'Font family stacks for body, code, and heading text.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'textSize',
+ exportName: 'textSizeDefaults',
+ title: 'Font Size Tokens',
+ description:
+ 'Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base).',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'fontWeight',
+ exportName: 'fontWeightDefaults',
+ title: 'Font Weight Tokens',
+ description: 'Font weight values for body, emphasis, and headings.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+ {
+ key: 'typeScale',
+ exportName: 'typeScaleDefaults',
+ title: 'Type Scale Tokens',
+ description:
+ 'Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
+ },
+];
+
+// ---------------------------------------------------------------------------
+// 2. Build sections
+// ---------------------------------------------------------------------------
+
+const sections = [];
+
+for (const group of groups) {
+ const pairs = extractDefaults(group.exportName);
+ if (pairs.length === 0) continue;
+
+ const rows = pairs.map(([name, value]) => group.formatRow(name, value));
+
+ /** @type {import('../../core/src/docs-types').ContentBlock[]} */
+ const content = [
+ {type: 'prose', text: group.description},
+ {type: 'table', headers: group.headers, rows},
+ ];
+
+ sections.push({title: group.title, content});
+}
+
+// Add a usage section at the end (hand-written, not generated)
+sections.push({
+ title: 'Usage in StyleX',
+ content: [
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Using token imports',
+ code: `import * as stylex from '@stylexjs/stylex';
+import {colorVars, spacingVars, sizeVars, radiusVars} from '@xds/core';
+
+const styles = stylex.create({
+ card: {
+ padding: spacingVars['--spacing-4'],
+ backgroundColor: colorVars['--color-background-surface'],
+ borderRadius: radiusVars['--radius-container'],
+ },
+ button: {
+ height: sizeVars['--size-element-md'],
+ },
+});`,
+ },
+ {
+ type: 'prose',
+ text: "See `npx xds docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx xds docs theme` for overriding tokens with defineTheme.",
+ },
+ ],
+});
+
+// ---------------------------------------------------------------------------
+// 3. Write output (or check for drift)
+// ---------------------------------------------------------------------------
+
+const isCheck = process.argv.includes('--check');
+
+// Count total tokens for the header comment
+const totalTokens = groups.reduce(
+ (sum, g) => sum + extractDefaults(g.exportName).length,
+ 0,
+);
+
+const output = `\
+// AUTO-GENERATED — do not edit manually.
+// Source: packages/core/src/theme/tokens.stylex.ts
+// Run: node scripts/generate-token-docs.mjs
+// Total: ${totalTokens} tokens across ${groups.length} categories.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = ${JSON.stringify(
+ {
+ name: 'tokens',
+ title: 'XDS Design Tokens',
+ description:
+ 'Complete reference for spacing, color, radius, typography, shadow, motion, and size tokens.',
+ sections,
+ },
+ null,
+ 2,
+)};
+`;
+
+if (isCheck) {
+ // CI mode: compare generated output to existing file
+ let existing = '';
+ try {
+ existing = readFileSync(TOKENS_DOC, 'utf-8');
+ } catch {
+ console.error('✗ tokens.doc.mjs does not exist. Run: node scripts/generate-token-docs.mjs');
+ process.exit(1);
+ }
+ if (existing !== output) {
+ console.error('✗ tokens.doc.mjs is out of date. Run: node scripts/generate-token-docs.mjs');
+ process.exit(1);
+ }
+ console.log(`✓ tokens.doc.mjs is up to date (${totalTokens} tokens)`);
+} else {
+ writeFileSync(TOKENS_DOC, output);
+ const lineCount = output.split('\n').length;
+ console.log(
+ `✓ Generated ${TOKENS_DOC} (${totalTokens} tokens, ${lineCount} lines)`,
+ );
+}