An open source design system that's fully customizable and agent ready
TypeScript
feat(docs): foundational token section docs with preview types and token-ref resolution (#1825)
Cindy Zhang2965822a820a
diff --git a/apps/sandbox/package.json b/apps/sandbox/package.jsonindex 0f88e28d01..0dfaad4574 100644--- a/apps/sandbox/package.json+++ b/apps/sandbox/package.json@@ -7,9 +7,9 @@"generate:versions": "node scripts/generate-versions.js","generate:changelog": "node scripts/generate-changelog.js","generate:cli": "node scripts/generate-cli-registry.mjs",- "predev": "node ../../scripts/sync-templates.js && yarn generate:versions && yarn generate:changelog && yarn generate:cli",+ "predev": "node ../../scripts/sync-templates.js && yarn generate:versions && yarn generate:changelog && yarn generate:cli && node scripts/generate-foundation-docs.mjs","dev": "node ../../scripts/sync-templates.js --watch & next dev",- "prebuild": "node ../../scripts/sync-templates.js && yarn generate:versions && yarn generate:changelog && yarn generate:cli",+ "prebuild": "node ../../scripts/sync-templates.js && yarn generate:versions && yarn generate:changelog && yarn generate:cli && node scripts/generate-foundation-docs.mjs","build": "next build","start": "next start","postinstall": "xds agent-docs"diff --git a/apps/sandbox/scripts/generate-foundation-docs.mjs b/apps/sandbox/scripts/generate-foundation-docs.mjsnew file mode 100644index 0000000000..e0bfa5100a--- /dev/null+++ b/apps/sandbox/scripts/generate-foundation-docs.mjs@@ -0,0 +1,39 @@+#!/usr/bin/env node++/**+ * Pre-generate resolved foundation docs as a JSON file for the sandbox.+ *+ * The CLI docs API uses dynamic imports and filesystem operations that+ * can't run in a webpack/Next.js client bundle. This script resolves+ * token-refs at build time and writes a static JSON file.+ *+ * Run: node apps/sandbox/scripts/generate-foundation-docs.mjs+ */++import {writeFileSync} from 'node:fs';+import {resolve, dirname} from 'node:path';+import {fileURLToPath} from 'node:url';+import {docs as docsApi} from '../../../packages/cli/src/api/docs.mjs';++const __dirname = dirname(fileURLToPath(import.meta.url));+const OUTPUT = resolve(__dirname, '../src/generated/foundationDocs.json');++const TOPICS = ['color', 'spacing', 'typography', 'elevation', 'shape', 'motion'];++async function main() {+ const result = {};+ for (const topic of TOPICS) {+ const res = await docsApi(topic);+ if (res.type === 'docs.detail') {+ result[topic] = res.data;+ }+ }+ writeFileSync(OUTPUT, JSON.stringify(result, null, 2));+ const kb = (Buffer.byteLength(JSON.stringify(result)) / 1024).toFixed(1);+ console.log(`✓ Generated ${OUTPUT} (${TOPICS.length} topics, ${kb} KB)`);+}++main().catch(err => {+ console.error(err);+ process.exit(1);+});diff --git a/apps/sandbox/src/app/(sandbox)/pages/doc-preview/DocPreview.tsx b/apps/sandbox/src/app/(sandbox)/pages/doc-preview/DocPreview.tsxnew file mode 100644index 0000000000..079458bd1e--- /dev/null+++ b/apps/sandbox/src/app/(sandbox)/pages/doc-preview/DocPreview.tsx@@ -0,0 +1,572 @@+'use client';++import {useMemo, useRef, useEffect, useState} from 'react';+import * as stylex from '@stylexjs/stylex';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSText, XDSHeading} from '@xds/core/Text';+import {XDSCodeBlock} from '@xds/core/CodeBlock';+import {XDSDivider} from '@xds/core/Divider';+import {useXDSTheme} from '@xds/core/theme';+import type {+ ReferenceDoc,+ ReferenceSection,+ ContentBlock,+ TokenPreviewType,+} from '@xds/core';++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ maxWidth: 960,+ margin: '0 auto',+ padding: 32,+ },+ sectionTitle: {+ scrollMarginTop: 80,+ },+ tokenTable: {+ width: '100%',+ borderCollapse: 'collapse',+ fontSize: 13,+ },+ th: {+ textAlign: 'start',+ fontWeight: 600,+ fontSize: 12,+ paddingBlock: 8,+ paddingInline: 12,+ borderBottom: '1px solid var(--color-border)',+ color: 'var(--color-text-secondary)',+ textTransform: 'uppercase' as const,+ letterSpacing: '0.04em',+ },+ td: {+ paddingBlock: 8,+ paddingInline: 12,+ borderBottom: '1px solid var(--color-border)',+ verticalAlign: 'middle',+ fontFamily: 'var(--font-family-code)',+ fontSize: 12,+ },+ tokenName: {+ fontWeight: 500,+ color: 'var(--color-text-primary)',+ whiteSpace: 'nowrap' as const,+ },+ tokenValue: {+ color: 'var(--color-text-secondary)',+ maxWidth: 320,+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap' as const,+ },+ previewCell: {+ width: 48,+ },+ listItem: {+ paddingBlock: 2,+ color: 'var(--color-text-primary)',+ fontSize: 14,+ lineHeight: 1.5,+ },+ doIcon: {+ color: 'var(--color-success)',+ flexShrink: 0,+ fontWeight: 700,+ },+ dontIcon: {+ color: 'var(--color-error)',+ flexShrink: 0,+ fontWeight: 700,+ },+ prose: {+ fontSize: 14,+ lineHeight: 1.6,+ color: 'var(--color-text-primary)',+ },+});++// =============================================================================+// Token Preview Renderers+// =============================================================================++function SwatchPreview({value}: {value: string}) {+ return (+ <div+ style={{+ width: 28,+ height: 28,+ borderRadius: 6,+ backgroundColor: value,+ border: '1px solid var(--color-border)',+ flexShrink: 0,+ }}+ />+ );+}++function ShadowBoxPreview({value}: {value: string}) {+ return (+ <div+ style={{+ width: 32,+ height: 24,+ borderRadius: 6,+ backgroundColor: 'var(--color-background-surface)',+ boxShadow: value,+ flexShrink: 0,+ }}+ />+ );+}++function RadiusBoxPreview({value}: {value: string}) {+ return (+ <div+ style={{+ width: 28,+ height: 28,+ borderRadius: value,+ border: '2px solid var(--color-accent)',+ flexShrink: 0,+ }}+ />+ );+}++function SpacingBarPreview({value}: {value: string}) {+ return (+ <div+ style={{+ width: value,+ minWidth: 2,+ maxWidth: 64,+ height: 12,+ borderRadius: 2,+ backgroundColor: 'var(--color-accent)',+ opacity: 0.6,+ flexShrink: 0,+ }}+ />+ );+}++function SizeBarPreview({value}: {value: string}) {+ return (+ <div+ style={{+ height: value,+ width: 40,+ maxHeight: 48,+ borderRadius: 4,+ backgroundColor: 'var(--color-accent-muted)',+ border: '1px solid var(--color-accent)',+ flexShrink: 0,+ }}+ />+ );+}++function BorderLinePreview({value}: {value: string}) {+ return (+ <div+ style={{+ width: 32,+ height: 0,+ borderBottom: `${value} solid var(--color-border-emphasized)`,+ flexShrink: 0,+ }}+ />+ );+}++function DurationBarPreview({value}: {value: string}) {+ const ref = useRef<HTMLDivElement>(null);+ const [animate, setAnimate] = useState(false);++ useEffect(() => {+ const interval = setInterval(() => setAnimate(a => !a), 2000);+ return () => clearInterval(interval);+ }, []);++ return (+ <div+ style={{+ width: 40,+ height: 8,+ borderRadius: 4,+ backgroundColor: 'var(--color-neutral)',+ overflow: 'hidden',+ flexShrink: 0,+ }}>+ <div+ ref={ref}+ style={{+ width: animate ? '100%' : '0%',+ height: '100%',+ borderRadius: 4,+ backgroundColor: 'var(--color-accent)',+ transition: `width ${value} ease`,+ }}+ />+ </div>+ );+}++function EasingCurvePreview({value}: {value: string}) {+ // Parse cubic-bezier values and draw a mini SVG curve+ const match = value.match(+ /cubic-bezier\(\s*([\d.]+)\s*,\s*([-\d.]+)\s*,\s*([\d.]+)\s*,\s*([-\d.]+)\s*\)/,+ );+ if (!match) return null;+ const [, x1, y1, x2, y2] = match.map(Number);+ return (+ <svg width={32} height={24} viewBox="0 0 1 1" style={{flexShrink: 0}}>+ <path+ d={`M 0 1 C ${x1} ${1 - y1}, ${x2} ${1 - y2}, 1 0`}+ fill="none"+ stroke="var(--color-accent)"+ strokeWidth={0.06}+ />+ </svg>+ );+}++function FontSamplePreview({+ tokenName,+ value,+}: {+ tokenName: string;+ value: string;+}) {+ const style: React.CSSProperties = {+ flexShrink: 0,+ whiteSpace: 'nowrap',+ maxWidth: 120,+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ };++ if (tokenName.includes('font-family')) {+ return <span style={{...style, fontFamily: value, fontSize: 13}}>Aa</span>;+ }+ if (tokenName.includes('font-size')) {+ return <span style={{...style, fontSize: value}}>Aa</span>;+ }+ if (tokenName.includes('font-weight')) {+ return <span style={{...style, fontWeight: value, fontSize: 13}}>Aa</span>;+ }+ if (tokenName.includes('text-') && tokenName.includes('-size')) {+ return <span style={{...style, fontSize: value}}>Aa</span>;+ }+ if (tokenName.includes('text-') && tokenName.includes('-weight')) {+ return <span style={{...style, fontWeight: value, fontSize: 13}}>Aa</span>;+ }+ return <span style={{...style, fontSize: 13}}>Aa</span>;+}++function TokenPreview({+ type,+ tokenName,+ value,+}: {+ type: TokenPreviewType;+ tokenName: string;+ value: string;+}) {+ switch (type) {+ case 'swatch':+ return <SwatchPreview value={value} />;+ case 'shadow-box':+ return <ShadowBoxPreview value={value} />;+ case 'radius-box':+ return <RadiusBoxPreview value={value} />;+ case 'spacing-bar':+ return <SpacingBarPreview value={value} />;+ case 'size-bar':+ return <SizeBarPreview value={value} />;+ case 'border-line':+ return <BorderLinePreview value={value} />;+ case 'duration-bar':+ return <DurationBarPreview value={value} />;+ case 'easing-curve':+ return <EasingCurvePreview value={value} />;+ case 'font-sample':+ return <FontSamplePreview tokenName={tokenName} value={value} />;+ default:+ return null;+ }+}++// =============================================================================+// Block Renderers+// =============================================================================++function TokenTable({+ rows,+ previewType,+}: {+ headers: string[];+ rows: string[][];+ previewType?: TokenPreviewType;+}) {+ const {token} = useXDSTheme();++ return (+ <div style={{overflowX: 'auto'}}>+ <table {...stylex.props(styles.tokenTable)}>+ <thead>+ <tr>+ {previewType && (+ <th {...stylex.props(styles.th, styles.previewCell)} />+ )}+ <th {...stylex.props(styles.th)}>Token</th>+ <th {...stylex.props(styles.th)}>Value</th>+ </tr>+ </thead>+ <tbody>+ {rows.map((row, i) => {+ const tokenName = row[0];+ // Resolve the live value from the current theme+ const liveValue = token(tokenName) ?? row[1];+ return (+ <tr key={i}>+ {previewType && (+ <td {...stylex.props(styles.td, styles.previewCell)}>+ <TokenPreview+ type={previewType}+ tokenName={tokenName}+ value={liveValue}+ />+ </td>+ )}+ <td {...stylex.props(styles.td, styles.tokenName)}>+ {tokenName}+ </td>+ <td {...stylex.props(styles.td, styles.tokenValue)}>+ {liveValue}+ </td>+ </tr>+ );+ })}+ </tbody>+ </table>+ </div>+ );+}++function ProseBlock({text}: {text: string}) {+ return (+ <div {...stylex.props(styles.prose)}>+ <XDSText>{text}</XDSText>+ </div>+ );+}++function CodeBlockRenderer({+ lang,+ code,+ label,+}: {+ lang: string;+ code: string;+ label?: string;+}) {+ return (+ <XDSVStack gap={1}>+ {label && (+ <XDSText type="supporting" color="secondary">+ {label}+ </XDSText>+ )}+ <XDSCodeBlock code={code} language={lang} hasCopyButton />+ </XDSVStack>+ );+}++function ListBlock({+ items,+ listStyle,+}: {+ items: string[];+ listStyle: 'ordered' | 'unordered' | 'do' | 'dont';+}) {+ return (+ <XDSVStack gap={1}>+ {items.map((item, i) => (+ <XDSHStack key={i} gap={2} align="start">+ {listStyle === 'do' && (+ <span {...stylex.props(styles.doIcon)}>✓</span>+ )}+ {listStyle === 'dont' && (+ <span {...stylex.props(styles.dontIcon)}>✗</span>+ )}+ {listStyle === 'ordered' && (+ <XDSText type="body" color="secondary">+ {i + 1}.+ </XDSText>+ )}+ {listStyle === 'unordered' && (+ <XDSText type="body" color="secondary">+ •+ </XDSText>+ )}+ <div {...stylex.props(styles.listItem)}>{item}</div>+ </XDSHStack>+ ))}+ </XDSVStack>+ );+}++function ContentBlockRenderer({+ block,+ previewType,+}: {+ block: ContentBlock;+ previewType?: TokenPreviewType;+}) {+ switch (block.type) {+ case 'prose':+ return <ProseBlock text={block.text} />;+ case 'code':+ return (+ <CodeBlockRenderer+ lang={block.lang}+ code={block.code}+ label={block.label}+ />+ );+ case 'table':+ return (+ <TokenTable+ headers={block.headers}+ rows={block.rows}+ previewType={previewType}+ />+ );+ case 'list':+ return <ListBlock items={block.items} listStyle={block.style} />;+ case 'token-ref':+ // Should already be resolved by the CLI — render nothing if unresolved+ return null;+ default:+ return null;+ }+}++// =============================================================================+// Section Renderer+// =============================================================================++function SectionRenderer({section}: {section: ReferenceSection}) {+ return (+ <XDSVStack gap={4}>+ <XDSHeading+ level={2}+ id={section.title.toLowerCase().replace(/\s+/g, '-')}+ xstyle={styles.sectionTitle}>+ {section.title}+ </XDSHeading>+ {section.content.map((block, i) => (+ <ContentBlockRenderer+ key={i}+ block={block}+ previewType={section.previewType}+ />+ ))}+ </XDSVStack>+ );+}++// =============================================================================+// DocPreview+// =============================================================================++export function DocPreview({doc}: {doc: ReferenceDoc}) {+ // Group sections into: token tables, usage/code, best practices, and other+ const {tokenSections, usageSections, practiceSections, otherSections} =+ useMemo(() => {+ const token: ReferenceSection[] = [];+ const usage: ReferenceSection[] = [];+ const practice: ReferenceSection[] = [];+ const other: ReferenceSection[] = [];++ for (const section of doc.sections) {+ const titleLower = section.title.toLowerCase();+ if (+ section.previewType ||+ section.content.some(b => b.type === 'table')+ ) {+ token.push(section);+ } else if (titleLower.includes('usage')) {+ usage.push(section);+ } else if (+ titleLower.includes('best practice') ||+ titleLower.includes('guidance')+ ) {+ practice.push(section);+ } else {+ other.push(section);+ }+ }++ return {+ tokenSections: token,+ usageSections: usage,+ practiceSections: practice,+ otherSections: other,+ };+ }, [doc.sections]);++ return (+ <div {...stylex.props(styles.root)}>+ <XDSVStack gap={8}>+ {/* Title + Description */}+ <XDSVStack gap={2}>+ <XDSHeading level={1}>{doc.title}</XDSHeading>+ <XDSText type="large" color="secondary">+ {doc.description}+ </XDSText>+ </XDSVStack>++ {/* Overview / other sections first */}+ {otherSections.map((section, i) => (+ <SectionRenderer key={`other-${i}`} section={section} />+ ))}++ {/* Token tables */}+ {tokenSections.length > 0 && (+ <>+ <XDSDivider />+ {tokenSections.map((section, i) => (+ <SectionRenderer key={`token-${i}`} section={section} />+ ))}+ </>+ )}++ {/* Usage */}+ {usageSections.length > 0 && (+ <>+ <XDSDivider />+ {usageSections.map((section, i) => (+ <SectionRenderer key={`usage-${i}`} section={section} />+ ))}+ </>+ )}++ {/* Best Practices */}+ {practiceSections.length > 0 && (+ <>+ <XDSDivider />+ {practiceSections.map((section, i) => (+ <SectionRenderer key={`practice-${i}`} section={section} />+ ))}+ </>+ )}+ </XDSVStack>+ </div>+ );+}diff --git a/apps/sandbox/src/app/(sandbox)/pages/doc-preview/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/doc-preview/page.tsxnew file mode 100644index 0000000000..a6c63e055d--- /dev/null+++ b/apps/sandbox/src/app/(sandbox)/pages/doc-preview/page.tsx@@ -0,0 +1,98 @@+"use client";++import { useState, useEffect } from "react";+import * as stylex from "@stylexjs/stylex";+import { XDSHStack } from "@xds/core/Layout";+import { XDSText } from "@xds/core/Text";+import {+ XDSSegmentedControl,+ XDSSegmentedControlItem,+} from "@xds/core/SegmentedControl";+import { XDSSpinner } from "@xds/core/Spinner";+import type { ReferenceDoc } from "@xds/core";+import { DocPreview } from "./DocPreview";++const styles = stylex.create({+ page: {+ minHeight: "100vh",+ },+ topBar: {+ position: "sticky",+ top: 0,+ zIndex: 10,+ backgroundColor: "var(--color-background-body)",+ borderBottom: "1px solid var(--color-border)",+ padding: "12px 32px",+ },+ loading: {+ display: "flex",+ alignItems: "center",+ justifyContent: "center",+ padding: 64,+ },+});++/** Foundational doc topics — the section docs that have tokenCategory */+const TOPICS = [+ { value: "color", label: "Color" },+ { value: "spacing", label: "Spacing" },+ { value: "typography", label: "Typography" },+ { value: "elevation", label: "Elevation" },+ { value: "shape", label: "Shape" },+ { value: "motion", label: "Motion" },+] as const;++export default function DocPreviewPage() {+ const [topic, setTopic] = useState<string>("color");+ const [docs, setDocs] = useState<Record<string, ReferenceDoc>>({});+ const [loading, setLoading] = useState(true);++ // Load pre-generated doc data+ useEffect(() => {+ import("../../../../generated/foundationDocs.json")+ .then((mod) => {+ setDocs(mod.default as Record<string, ReferenceDoc>);+ setLoading(false);+ })+ .catch(() => setLoading(false));+ }, []);++ const doc = docs[topic] ?? null;++ return (+ <div {...stylex.props(styles.page)}>+ <div {...stylex.props(styles.topBar)}>+ <XDSHStack gap={4} align="center">+ <XDSText type="label" color="secondary">+ Foundations+ </XDSText>+ <XDSSegmentedControl+ value={topic}+ onChange={setTopic}+ label="Doc topic"+ size="sm"+ >+ {TOPICS.map((t) => (+ <XDSSegmentedControlItem+ key={t.value}+ value={t.value}+ label={t.label}+ />+ ))}+ </XDSSegmentedControl>+ </XDSHStack>+ </div>+ {loading ? (+ <div {...stylex.props(styles.loading)}>+ <XDSSpinner size="md" />+ </div>+ ) : doc ? (+ <DocPreview doc={doc} />+ ) : (+ <div {...stylex.props(styles.loading)}>+ <XDSText color="secondary">No doc found for "{topic}"</XDSText>+ </div>+ )}+ </div>+ );+}diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.tsindex 5e4865444a..eb8733435e 100644--- a/apps/sandbox/src/app/sandboxPages.ts+++ b/apps/sandbox/src/app/sandboxPages.ts@@ -114,6 +114,12 @@ export const categories: SandboxCategory[] = [href: '/pages/codeblock-perf/',description: 'Compare highlight modes and scroll performance',},+ {+ name: 'Foundations',+ href: '/pages/doc-preview/',+ description:+ 'Token reference docs with live theme previews — color, spacing, typography, and more',+ },{name: 'Docsite',href: '/pages/docsite/',diff --git a/packages/cli/docs/color.doc.mjs b/packages/cli/docs/color.doc.mjsnew file mode 100644index 0000000000..8a2082a2ee--- /dev/null+++ b/packages/cli/docs/color.doc.mjs@@ -0,0 +1,81 @@+/** @type {import('../../core/src/docs-types').ReferenceDoc} */++export const docs = {+ name: 'color',+ title: 'Color',+ description:+ 'Semantic color tokens for surfaces, text, icons, borders, and status indicators.',+ tokenCategory: 'color',++ sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'XDS colors are semantic — tokens describe purpose, not appearance. Every color adapts automatically between light and dark modes via CSS light-dark(). Themes override the resolved values, so your code never references raw hex colors.',+ },+ ],+ },+ {+ title: 'Surface Colors',+ content: [+ {+ type: 'prose',+ text: 'Layered surface hierarchy: body → surface → card → popover. Each level sits visually above the previous one.',+ },+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Color Tokens',+ },+ ],+ },+ {+ title: 'Usage',+ content: [+ {+ type: 'code',+ lang: 'tsx',+ label: 'Applying color tokens',+ code: `import * as stylex from '@stylexjs/stylex';+import {colorVars} from '@xds/core';++const styles = stylex.create({+ container: {+ backgroundColor: colorVars['--color-background-surface'],+ color: colorVars['--color-text-primary'],+ borderColor: colorVars['--color-border'],+ },+ accent: {+ color: colorVars['--color-text-accent'],+ },+});`,+ },+ ],+ },+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use semantic tokens (--color-text-primary) instead of raw hex values.',+ 'Rely on the surface hierarchy (body → surface → card → popover) for layering.',+ 'Use status colors (success, error, warning) only for their semantic meaning.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ "Hardcode hex values — they won't adapt to dark mode or custom themes.",+ 'Mix accent colors with status colors in the same context.',+ 'Use --color-on-accent on non-accent backgrounds.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/docs/elevation.doc.mjs b/packages/cli/docs/elevation.doc.mjsnew file mode 100644index 0000000000..da1ca1c95e--- /dev/null+++ b/packages/cli/docs/elevation.doc.mjs@@ -0,0 +1,79 @@+/** @type {import('../../core/src/docs-types').ReferenceDoc} */++export const docs = {+ name: 'elevation',+ title: 'Elevation',+ description:+ 'Shadow tokens for visual elevation and inset state rings.',+ tokenCategory: 'shadow',++ sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'Elevation tokens create depth through box-shadow. Three levels (low, med, high) establish a visual hierarchy for floating elements. Inset shadows provide focus and selection rings for interactive components.',+ },+ ],+ },+ {+ title: 'Elevation Scale',+ content: [+ {+ type: 'prose',+ text: 'Each level adds stronger offset and spread. Shadow color adapts to dark mode automatically via light-dark().',+ },+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Shadow Tokens',+ },+ ],+ },+ {+ title: 'Usage',+ content: [+ {+ type: 'code',+ lang: 'tsx',+ label: 'Applying elevation',+ code: `import {shadowVars} from '@xds/core';++const styles = stylex.create({+ dropdown: {+ boxShadow: shadowVars['--shadow-med'],+ },+ dialog: {+ boxShadow: shadowVars['--shadow-high'],+ },+ inputFocused: {+ boxShadow: shadowVars['--shadow-inset-selected'],+ },+});`,+ },+ ],+ },+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Match elevation to interaction context: low for tooltips, med for dropdowns, high for dialogs.',+ 'Use inset shadows for input focus/selection states — they compose better than outlines.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Stack multiple elevation levels on the same element.',+ 'Use elevation shadows for decorative borders — use --color-border tokens instead.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/docs/motion.doc.mjs b/packages/cli/docs/motion.doc.mjsnew file mode 100644index 0000000000..c311aa37f4--- /dev/null+++ b/packages/cli/docs/motion.doc.mjs@@ -0,0 +1,87 @@+/** @type {import('../../core/src/docs-types').ReferenceDoc} */++export const docs = {+ name: 'motion',+ title: 'Motion',+ description:+ 'Duration and easing tokens for animations and transitions.',+ tokenCategory: 'duration',++ sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'XDS motion tokens define timing in three bands: fast (micro-interactions like hover/press), medium (entrance/exit), and slow (continuous/looping). Each band has a base value with min/max variants derived from a consistent ratio.',+ },+ ],+ },+ {+ title: 'Duration',+ content: [+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Duration Tokens',+ },+ ],+ },+ {+ title: 'Easing',+ content: [+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Easing Tokens',+ },+ ],+ },+ {+ title: 'Usage',+ content: [+ {+ type: 'code',+ lang: 'tsx',+ label: 'Applying motion tokens',+ code: `import {durationVars, easeVars} from '@xds/core';++const styles = stylex.create({+ fadeIn: {+ transitionProperty: 'opacity',+ transitionDuration: durationVars['--duration-fast'],+ transitionTimingFunction: easeVars['--ease-standard'],+ },+ slideUp: {+ transitionProperty: 'transform, opacity',+ transitionDuration: durationVars['--duration-medium'],+ transitionTimingFunction: easeVars['--ease-standard'],+ },+});`,+ },+ ],+ },+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use fast durations for state changes (hover, press, toggle).',+ 'Use medium durations for element entrance/exit (dialogs, dropdowns).',+ 'Use slow durations sparingly — only for continuous animations (loading spinners, progress bars).',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Use slow durations for interactive feedback — users will perceive lag.',+ 'Skip easing on transitions — linear motion feels robotic.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/docs/shape.doc.mjs b/packages/cli/docs/shape.doc.mjsnew file mode 100644index 0000000000..7b30b847af--- /dev/null+++ b/packages/cli/docs/shape.doc.mjs@@ -0,0 +1,69 @@+/** @type {import('../../core/src/docs-types').ReferenceDoc} */++export const docs = {+ name: 'shape',+ title: 'Shape',+ description:+ 'Border radius tokens for consistent component rounding — from sharp corners to full pills.',+ tokenCategory: 'radius',++ sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'The radius scale uses a semantic naming system: inner → element → container → page. Each level is designed for a specific context. Themes can multiply the entire scale via a radius multiplier, with --radius-none and --radius-full as fixed anchors.',+ },+ ],+ },+ {+ title: 'Radius Scale',+ content: [+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Radius Tokens',+ },+ ],+ },+ {+ title: 'Concentric Radius',+ content: [+ {+ type: 'prose',+ text: 'When a rounded container has padding, inner elements need a smaller radius to appear concentric. XDS components like Card handle this automatically — the inner radius is computed as max(0, outerRadius - padding).',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'Concentric radius formula',+ code: `/* Automatic in XDS Card */+--card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,+ },+ ],+ },+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use --radius-element for interactive controls (buttons, inputs, selectors).',+ 'Use --radius-container for content containers (cards, panels, dialogs).',+ 'Use --radius-full for pill shapes (badges, tags, avatar status dots).',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ "Use --radius-page for small elements — it's designed for page-level containers.",+ "Hardcode radius values — they won't scale with theme radius multipliers.",+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/docs/spacing.doc.mjs b/packages/cli/docs/spacing.doc.mjsnew file mode 100644index 0000000000..869acde5e4--- /dev/null+++ b/packages/cli/docs/spacing.doc.mjs@@ -0,0 +1,79 @@+/** @type {import('../../core/src/docs-types').ReferenceDoc} */++export const docs = {+ name: 'spacing',+ title: 'Spacing',+ description:+ 'Spacing scale tokens for padding, gap, and margin — the rhythmic foundation of XDS layouts.',+ tokenCategory: 'spacing',++ sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'XDS uses a 4px base-unit spacing scale. Component gap props accept step values that map to these tokens. The scale provides fine-grained control at the small end (2px, 4px, 6px) and consistent rhythm at larger sizes (multiples of 4px).',+ },+ ],+ },+ {+ title: 'Scale',+ content: [+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Spacing Tokens',+ },+ ],+ },+ {+ title: 'Usage',+ content: [+ {+ type: 'prose',+ text: 'Most components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Spacing via component props vs StyleX',+ code: `// Via component props (preferred)+<XDSStack gap={4}>{/* 16px gap */}</XDSStack>++// Via StyleX tokens (custom layouts)+import {spacingVars} from '@xds/core';++const styles = stylex.create({+ custom: {+ padding: spacingVars['--spacing-4'],+ gap: spacingVars['--spacing-3'],+ },+});`,+ },+ ],+ },+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use component gap props when available — they handle automatic spacing compensation.',+ "Stick to the scale for consistency. If a value isn't on the scale, reconsider the design.",+ 'Use smaller steps (0.5–2) for tight internal spacing and larger steps (4–8) for section gaps.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Use arbitrary pixel values outside the scale.',+ 'Mix spacing tokens with raw px/rem values in the same component.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/docs/tokens.doc.mjs b/packages/cli/docs/tokens.doc.mjsindex 445d4f7655..a928815397 100644--- a/packages/cli/docs/tokens.doc.mjs+++ b/packages/cli/docs/tokens.doc.mjs@@ -417,7 +417,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "swatch"},{"title": "Spacing Tokens",@@ -495,7 +496,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "spacing-bar"},{"title": "Size Tokens",@@ -525,7 +527,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "size-bar"},{"title": "Border Tokens",@@ -547,7 +550,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "border-line"},{"title": "Radius Tokens",@@ -589,7 +593,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "radius-box"},{"title": "Shadow Tokens",@@ -639,7 +644,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "shadow-box"},{"title": "Duration Tokens",@@ -693,7 +699,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "duration-bar"},{"title": "Easing Tokens",@@ -715,7 +722,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "easing-curve"},{"title": "Font Family Tokens",@@ -745,7 +753,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "font-sample"},{"title": "Font Size Tokens",@@ -811,7 +820,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "font-sample"},{"title": "Font Weight Tokens",@@ -845,7 +855,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "font-sample"},{"title": "Type Scale Tokens",@@ -1031,7 +1042,8 @@ export const docs = {]]}- ]+ ],+ "previewType": "font-sample"},{"title": "Usage in StyleX",diff --git a/packages/cli/docs/typography.doc.mjs b/packages/cli/docs/typography.doc.mjsnew file mode 100644index 0000000000..053ea66ab6--- /dev/null+++ b/packages/cli/docs/typography.doc.mjs@@ -0,0 +1,213 @@+/** @type {import('../../core/src/docs-types').ReferenceDoc} */++export const docs = {+ name: 'typography',+ title: 'Typography',+ description:+ 'Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.',+ tokenCategory: 'typography',++ sections: [+ // ── Overview ────────────────────────────────────────────────────────────+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'XDS typography is built on a geometric type scale: base size × ratio^step, with 14px and 1.2 as defaults. Every text style is a semantic token that composes font size, weight, and line-height — so components express intent (heading, body, label) rather than raw values.',+ },+ {+ type: 'prose',+ text: 'Two layers work together: raw size tokens (--font-size-xs … --font-size-5xl) form the geometric scale, and semantic type scale tokens (--text-heading-1-size, --text-body-leading, etc.) reference them by var(). Themes override the entire scale by adjusting base and ratio in defineTheme — all semantic tokens recompute automatically.',+ },+ ],+ },++ // ── Font Families ───────────────────────────────────────────────────────+ {+ title: 'Font Families',+ content: [+ {+ type: 'prose',+ text: 'Three font roles: body (UI text), heading (titles and headings), and code (monospace). By default, body and heading share the same system font stack; code uses a monospace stack. Custom themes can assign different families per role — heading inherits from body when not explicitly set.',+ },+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Font Family Tokens',+ },+ ],+ },++ // ── Font Sizes ──────────────────────────────────────────────────────────+ {+ title: 'Font Sizes',+ content: [+ {+ type: 'prose',+ text: 'Geometric scale: round(base × ratio^step), expressed in rem. The default scale is 14px × 1.2, producing 12 steps from 4xs (6px) to 5xl (42px). Adjusting base and ratio in defineTheme regenerates every size token while preserving proportional relationships.',+ },+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Font Size Tokens',+ },+ ],+ },++ // ── Font Weights ────────────────────────────────────────────────────────+ {+ title: 'Font Weights',+ content: [+ {+ type: 'prose',+ text: 'Four semantic weights: normal (400, body/code), medium (500, labels/data), semibold (600, headings/titles), bold (700, strong emphasis). Type scale tokens reference these by var() so themes can remap numeric values.',+ },+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Font Weight Tokens',+ },+ ],+ },++ // ── Line Height ─────────────────────────────────────────────────────────+ {+ title: 'Line Height',+ content: [+ {+ type: 'prose',+ text: 'Line heights are computed from a tiered target ratio and snapped to a 4px vertical grid. Small text (<20px) targets 1.5, medium text (20–31px) targets 1.4, and large text (≥32px) targets 1.25. A minimum gap of fontSize + 4px is enforced. The result is a unitless ratio stored in each --text-*-leading token.',+ },+ {+ type: 'prose',+ text: 'The 4px grid is critical: every line box aligns to 4px increments, which keeps baselines, spacing, and component heights predictable. The expandTypeScale utility computes these automatically when you provide a base and ratio — you should never need to set line-height manually.',+ },+ ],+ },++ // ── Type Scale ──────────────────────────────────────────────────────────+ {+ title: 'Type Scale',+ content: [+ {+ type: 'prose',+ text: 'Semantic tokens that combine size, weight, and line-height into a single type style. Each token triplet (--text-*-size, --text-*-weight, --text-*-leading) is consumed by XDSText and XDSHeading. Use the component props rather than composing raw font tokens.',+ },+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Type Scale Tokens',+ },+ ],+ },++ // ── Display Text ────────────────────────────────────────────────────────+ {+ title: 'Display Text',+ content: [+ {+ type: 'prose',+ text: 'Display variants (display-1, display-2, display-3) continue the geometric progression above heading-1, at steps +6, +5, and +4. They use normal weight (400) instead of semibold, and tighter line-heights (~1.2) — large text reads better with less leading. Use display types for hero banners, marketing headlines, and data callouts — not for document headings.',+ },+ {+ type: 'prose',+ text: 'Display text often needs heading semantics for accessibility. Use the as prop on XDSText to render the correct HTML element: <XDSText type="display-1" as="h1"> gives you display-1 styling with an <h1> tag, so screen readers see the correct document outline.',+ },+ ],+ },++ // ── Usage ────────────────────────────────────────────────────────────────+ {+ title: 'Usage',+ content: [+ {+ type: 'code',+ lang: 'tsx',+ label: 'XDSHeading for document structure',+ code: `import {XDSHeading} from '@xds/core';++// Heading levels map to semantic tokens: level 1 → --text-heading-1-*+<XDSHeading level={1}>Page Title</XDSHeading>+<XDSHeading level={2}>Section</XDSHeading>+<XDSHeading level={3}>Subsection</XDSHeading>++// Override the accessibility level when visual ≠ document hierarchy+<XDSHeading level={2} accessibilityLevel={3}>+ Sidebar Section+</XDSHeading>`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'XDSText for body, label, and display text',+ code: `import {XDSText} from '@xds/core';++<XDSText type="body">Body text at the base scale.</XDSText>+<XDSText type="large">Emphasized body text.</XDSText>+<XDSText type="label">Form label</XDSText>+<XDSText type="supporting">Helper text, timestamps, metadata.</XDSText>+<XDSText type="code">{'const x = 1;'}</XDSText>++// Display with heading semantics for accessibility+<XDSText type="display-1" as="h1">Hero Title</XDSText>+<XDSText type="display-2" as="h2">$1.2M Revenue</XDSText>`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Customizing the type scale via defineTheme',+ code: `import {defineTheme} from '@xds/core';++// Adjust the entire ramp holistically with base and ratio+const editorialTheme = defineTheme({+ name: 'editorial',+ typography: {+ scale: { base: 16, ratio: 1.25 }, // airy / article feel+ body: { family: 'Geist', fallbacks: '-apple-system, sans-serif' },+ heading: { weight: 'bold' },+ code: { family: 'Geist Mono', fallbacks: '"SF Mono", monospace' },+ },+});++const denseTheme = defineTheme({+ name: 'dense',+ typography: {+ scale: { base: 12, ratio: 1.125 }, // compact / data-dense UI+ },+});`,+ },+ ],+ },++ // ── Best Practices ──────────────────────────────────────────────────────+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use XDSHeading for document headings and XDSText for everything else — they apply the full type scale automatically.',+ 'Adjust typography holistically: change base and ratio in defineTheme to shift the entire ramp (e.g. { base: 16, ratio: 1.25 } for editorial, { base: 12, ratio: 1.125 } for dense UI).',+ 'Use display types with as="h1" (or h2/h3) when display text is a page heading — this preserves accessibility while giving you display-level sizing.',+ 'Let line-height snap to the 4px grid via the type scale — expandTypeScale computes leading automatically from base and ratio.',+ 'Use the supporting type for secondary information: timestamps, helper text, metadata, captions.',+ 'Use accessibilityLevel on XDSHeading when the visual hierarchy doesn\u2019t match the document outline (e.g. sidebar or card headings).',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Set font-size or line-height manually — use the semantic type scale tokens so the full ramp stays consistent and 4px-grid-aligned.',+ 'Skip heading levels (e.g. h1 \u2192 h3) — screen readers rely on an unbroken hierarchy. Use accessibilityLevel to decouple visual from semantic level.',+ 'Use display types for body content or in-page sections — they\u2019re designed for hero/marketing/data-callout contexts only.',+ 'Override individual size tokens (--font-size-lg) to "tweak" a heading — adjust base/ratio instead so proportions remain coherent across the entire scale.',+ 'Use raw numeric font-weight values (400, 600) — reference the semantic weight tokens so themes can remap them.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/src/api/docs.mjs b/packages/cli/src/api/docs.mjsindex e520ffca2e..2bf22d9f2c 100644--- a/packages/cli/src/api/docs.mjs+++ b/packages/cli/src/api/docs.mjs@@ -56,6 +56,53 @@ async function loadReferenceDocs(docPath, {lang} = {}) {};}+/**+ * Resolve token-ref blocks by inlining the referenced section's table.+ * This allows section docs to reference token tables without duplicating data.+ */+async function resolveTokenRefs(docsData, topics) {+ const resolved = {...docsData, sections: [...docsData.sections]};+ for (let si = 0; si < resolved.sections.length; si++) {+ const section = resolved.sections[si];+ const newContent = [];+ for (const block of section.content) {+ if (block.type === 'token-ref') {+ const refPath = topics[block.topic];+ if (!refPath) {+ newContent.push({type: 'prose', text: `[token-ref: unknown topic "${block.topic}"]`});+ continue;+ }+ const refMod = await import(pathToFileURL(refPath).href);+ const refDocs = refMod.docs;+ const refSection = refDocs.sections.find(+ s => s.title.toLowerCase() === block.section.toLowerCase(),+ );+ if (!refSection) {+ newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});+ continue;+ }+ // Inline the referenced section's content blocks (tables, prose, etc.)+ // and carry over the previewType+ for (const refBlock of refSection.content) {+ newContent.push(refBlock);+ }+ // If the referenced section has a previewType, attach it to our section+ if (refSection.previewType && !section.previewType) {+ resolved.sections[si] = {...section, previewType: refSection.previewType, content: newContent};+ }+ } else {+ newContent.push(block);+ }+ }+ if (resolved.sections[si] === section) {+ resolved.sections[si] = {...section, content: newContent};+ } else {+ resolved.sections[si].content = newContent;+ }+ }+ return resolved;+}+/*** @param {string} [topic]* @param {string} [section]@@ -106,5 +153,6 @@ export async function docs(topic, section, options = {}) {return {type: 'docs.detail.section', data: match};}- return {type: 'docs.detail', data: docsData};+ const resolved = await resolveTokenRefs(docsData, topics);+ return {type: 'docs.detail', data: resolved};}diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex 2bb504638a..5c80e47e8b 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -421,6 +421,7 @@ export interface TranslationDoc {* { type: 'code', lang: 'tsx', code: 'padding: spacingVars[...]' }* { type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']] }* { type: 'list', style: 'do', items: ['Use semantic tokens'] }+ * { type: 'token-ref', topic: 'tokens', section: 'Color Tokens' }* ```*/export type ContentBlock =@@ -431,8 +432,44 @@ export type ContentBlock =type: 'list';style: 'ordered' | 'unordered' | 'do' | 'dont';items: string[];+ }+ | {+ /** Reference to a token table in another doc topic.+ * The CLI resolves this at read time and inlines the referenced+ * section's table. The docsite can render it with live theme values+ * and type-specific previews instead of static strings. */+ type: 'token-ref';+ /** Doc topic name containing the tokens. e.g. `'tokens'` */+ topic: string;+ /** Section title to pull from that topic. e.g. `'Color Tokens'` */+ section: string;};+/**+ * Preview type hint for token tables. Tells the docsite how to render+ * a visual preview column for each token row.+ *+ * - `'swatch'` — Color circle/square showing the token value+ * - `'shadow-box'` — Box with the shadow applied+ * - `'radius-box'` — Box with the border-radius applied+ * - `'spacing-bar'` — Horizontal bar at the token's width+ * - `'size-bar'` — Horizontal bar at the token's height+ * - `'border-line'` — Line at the token's border-width+ * - `'duration-bar'` — Animated bar showing the timing+ * - `'easing-curve'` — Bezier curve visualization+ * - `'font-sample'` — Text sample in the font family/size/weight+ */+export type TokenPreviewType =+ | 'swatch'+ | 'shadow-box'+ | 'radius-box'+ | 'spacing-bar'+ | 'size-bar'+ | 'border-line'+ | 'duration-bar'+ | 'easing-curve'+ | 'font-sample';+/*** A section within a reference doc. Sections are the primary* organizational unit — each becomes an h2 in full output,@@ -443,6 +480,10 @@ export interface ReferenceSection {title: string;/** Ordered content blocks. Mix prose, code, tables, and lists freely. */content: ContentBlock[];+ /** Preview type for token tables in this section. When set, the docsite+ * renders a visual preview column using the token's computed CSS value+ * from the current theme. Omit for non-token sections. */+ previewType?: TokenPreviewType;}/**@@ -467,6 +508,11 @@ export interface ReferenceDoc {description: string;/** Ordered sections that make up the doc. */sections: ReferenceSection[];+ /** Token category for foundational docs that map to a token section.+ * When set, the docsite can link from the tokens overview page+ * to this doc for detailed guidance on that category.+ * e.g. `'color'` links tokens → color foundational doc. */+ tokenCategory?: string;}/**diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex aa84a70b30..4894e9c43c 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -162,4 +162,8 @@ export type {DerivedVar,TranslationDoc,GroupDoc,+ ReferenceDoc,+ ReferenceSection,+ ContentBlock,+ TokenPreviewType,} from './docs-types';diff --git a/scripts/generate-token-docs.mjs b/scripts/generate-token-docs.mjsindex ef4e0d53f4..5752a4e715 100644--- a/scripts/generate-token-docs.mjs+++ b/scripts/generate-token-docs.mjs@@ -61,6 +61,7 @@ function extractDefaults(name) {const groups = [{key: 'color',+ previewType: 'swatch',exportName: 'colorDefaults',title: 'Color Tokens',description:@@ -76,6 +77,7 @@ const groups = [},{key: 'spacing',+ previewType: 'spacing-bar',exportName: 'spacingDefaults',title: 'Spacing Tokens',description:@@ -85,6 +87,7 @@ const groups = [},{key: 'size',+ previewType: 'size-bar',exportName: 'sizeDefaults',title: 'Size Tokens',description:@@ -94,6 +97,7 @@ const groups = [},{key: 'border',+ previewType: 'border-line',exportName: 'borderDefaults',title: 'Border Tokens',description: 'Border width for card and input borders.',@@ -102,6 +106,7 @@ const groups = [},{key: 'radius',+ previewType: 'radius-box',exportName: 'radiusDefaults',title: 'Radius Tokens',description:@@ -111,6 +116,7 @@ const groups = [},{key: 'shadow',+ previewType: 'shadow-box',exportName: 'shadowDefaults',title: 'Shadow Tokens',description:@@ -120,6 +126,7 @@ const groups = [},{key: 'duration',+ previewType: 'duration-bar',exportName: 'durationDefaults',title: 'Duration Tokens',description:@@ -129,6 +136,7 @@ const groups = [},{key: 'ease',+ previewType: 'easing-curve',exportName: 'easeDefaults',title: 'Easing Tokens',description: 'Easing curves for animations and transitions.',@@ -137,6 +145,7 @@ const groups = [},{key: 'typography',+ previewType: 'font-sample',exportName: 'typographyDefaults',title: 'Font Family Tokens',description: 'Font family stacks for body, code, and heading text.',@@ -145,6 +154,7 @@ const groups = [},{key: 'textSize',+ previewType: 'font-sample',exportName: 'textSizeDefaults',title: 'Font Size Tokens',description:@@ -154,6 +164,7 @@ const groups = [},{key: 'fontWeight',+ previewType: 'font-sample',exportName: 'fontWeightDefaults',title: 'Font Weight Tokens',description: 'Font weight values for body, emphasis, and headings.',@@ -162,6 +173,7 @@ const groups = [},{key: 'typeScale',+ previewType: 'font-sample',exportName: 'typeScaleDefaults',title: 'Type Scale Tokens',description:@@ -189,7 +201,9 @@ for (const group of groups) {{type: 'table', headers: group.headers, rows},];- sections.push({title: group.title, content});+ const section = {title: group.title, content};+ if (group.previewType) section.previewType = group.previewType;+ sections.push(section);}// Add a usage section at the end (hand-written, not generated)