Skip to content

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.json
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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 &quot;{topic}&quot;</XDSText>
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.ts
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.ts
index 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.ts
index 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.mjs
index 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)