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.ymlindex 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 syncrun: 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.mjsindex 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.tsindex 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.mjsnew file mode 100644index 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)`,+ );+}