An open source design system that's fully customizable and agent ready
TypeScript
docs: split large flat topics into progressive-disclosure namespaces (#7184)
Joeyffa4f72f3ead
diff --git a/.changeset/docs-split-six-topics.md b/.changeset/docs-split-six-topics.mdnew file mode 100644index 0000000000..ccd177c34c--- /dev/null+++ b/.changeset/docs-split-six-topics.md@@ -0,0 +1,10 @@+---+'@astryxdesign/cli': patch+---++[docs] `astryx docs migration`, `internationalization`, `styling`, `styling-libraries`, `typography` and `tokens` still work and now list focused guides. Each section is also readable under its guide, for example `astryx docs tokens/tokens-spacing` or `astryx docs styling/tokens-and-setup stylex-setup`, and `astryx docs <topic> <section>` keeps working: every section key these topics had still opens the same section. `astryx docs tokens --depth all --detail full` prints every token table, and a `token-ref` to `tokens` keeps resolving through the guide that holds the table.++Integrations: these six names are now docs-tree sections, not topics, so an integration doc that declares `extends` or `replaces` with one of them is reported as naming no topic, and its content no longer shows. To keep that content, ship it as your own topic under a new name, or as a guide in your package's own section (`astryx integration add doc <name> --parent <your-section>`). Topics that are still flat, such as `theme` or `color`, can still be extended or replaced.++(#7184)+@josephfarinadiff --git a/apps/sandbox/scripts/generate-foundation-docs.mjs b/apps/sandbox/scripts/generate-foundation-docs.mjsindex 6fa244bab7..7f3e7f796c 100644--- a/apps/sandbox/scripts/generate-foundation-docs.mjs+++ b/apps/sandbox/scripts/generate-foundation-docs.mjs@@ -28,12 +28,43 @@ const TOPICS = ['motion',];+/**+ * A topic split into a docs-tree namespace, read whole: its title and summary,+ * and every guide's sections below it in tree order, as+ * `astryx docs <topic> --depth all --detail full` returns them. The same shape+ * as the flat topic's read, so the preview keeps rendering it.+ * @param {string} topic+ */+async function namespaceTopic(topic) {+ const res = await docsApi(topic, undefined, {depth: 'all', detail: 'full'});+ const sections = [];+ const walk = slots => {+ for (const slot of slots ?? []) {+ for (const child of slot.children) {+ if (child.kind === 'generic') sections.push(...(child.sections ?? []));+ else walk(child.slots);+ }+ }+ };+ walk(res.data.slots);+ return {+ name: topic,+ title: res.data.title,+ description: res.data.summary,+ sections,+ };+}+async function main() {const result = {};for (const topic of TOPICS) {const res = await docsApi(topic);if (res.type === 'docs.detail') {result[topic] = res.data;+ } else if (res.type === 'docs.node' && res.data.kind === 'namespace') {+ result[topic] = await namespaceTopic(topic);+ } else {+ throw new Error(`astryx docs ${topic} returned ${res.type}, not a topic.`);}}writeFileSync(OUTPUT, JSON.stringify(result, null, 2));diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex 8f75f37061..25a66b99ed 100644--- a/packages/cli/api/docs/_adapter.mjs+++ b/packages/cli/api/docs/_adapter.mjs@@ -732,10 +732,57 @@ export async function packageDocsProblems(integration, discovered) {export function referenceTargets(catalog, lang) {return async topic => {const target = catalog.resolve(topic);- return target ? lowerTopic(catalog, target, lang) : null;+ if (target) return lowerTopic(catalog, target, lang);+ return namespaceReferenceTarget(catalog, topic, lang);};}+/**+ * A docs-tree namespace as the target of a token reference: every guide placed+ * below it, lowered for `lang` and read in tree order as one topic. A flat+ * topic split into a namespace keeps answering the references its readers+ * wrote, so `{type: 'token-ref', topic: 'tokens', section: 'Color Tokens'}`+ * finds the guide that now holds that table. Null for any other route.+ * @param {DocsCatalog} catalog+ * @param {string} route+ * @param {string | null} lang+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}+ */+async function namespaceReferenceTarget(catalog, route, lang) {+ const tree = await projectTree(catalog);+ const node = tree.get(route) ?? tree.getFolded(route);+ if (!node || node.kind !== 'namespace' || node.generated) return null;+ /** @type {any[]} */+ const sections = [];+ /** @type {Record<string, string>} */+ const sourceTitles = {};+ /** @param {TreeNode} parent */+ const walk = async parent => {+ for (const slot of parent.slots) {+ for (const childRoute of slot.children) {+ const child = tree.get(childRoute);+ if (!child || child.parent !== parent.route) continue;+ if (child.kind === 'namespace') {+ await walk(child);+ } else if (child.kind === 'generic' && child.ref?.topicFile) {+ const lowered = await lowerTopic(catalog, guideEntry(child), lang);+ sections.push(...lowered.doc.sections);+ for (const [key, title] of Object.entries(lowered.sourceTitles)) {+ sourceTitles[key] ??= title;+ }+ }+ }+ }+ };+ await walk(node);+ if (sections.length === 0) return null;+ return /** @type {any} */ ({+ id: node.route,+ doc: {sections},+ sourceTitles,+ });+}+/*** Each reference block in one integration's docs that cannot include what it* names (spec:AST-047 FR9): a target that names no doc, a field its schemadiff --git a/packages/cli/api/docs/compiled-topics.test.mjs b/packages/cli/api/docs/compiled-topics.test.mjsindex 6d7053863a..6d73b220c3 100644--- a/packages/cli/api/docs/compiled-topics.test.mjs+++ b/packages/cli/api/docs/compiled-topics.test.mjs@@ -53,7 +53,7 @@ describe('reads that share a catalog', () => {'never let one read change another',async () => {const catalog = await loadDocsCatalog();- const tokens = catalog.resolve('tokens');+ const tokens = catalog.resolve('color');const first = detailView(await compileTopic(catalog, tokens));for (const section of first.sections) {section.title = 'EDITED';diff --git a/packages/cli/api/docs/detail/section/section.test.mjs b/packages/cli/api/docs/detail/section/section.test.mjsindex 9a0855e05a..71f40c3774 100644--- a/packages/cli/api/docs/detail/section/section.test.mjs+++ b/packages/cli/api/docs/detail/section/section.test.mjs@@ -16,7 +16,7 @@ const SLOW = 30_000;describe('docs.detail.section leaf', () => {it('resolves a named section (case-insensitive) into a docs.detail.section envelope', async () => {- const res = await section('tokens', 'spacing');+ const res = await section('tokens/tokens-spacing', 'spacing');expect(res.type).toBe('docs.detail.section');expect(res.data.title.toLowerCase()).toContain('spacing');}, SLOW);@@ -24,7 +24,7 @@ describe('docs.detail.section leaf', () => {it('throws ERR_UNKNOWN_SECTION for an unknown section', async () => {let err;try {- await section('tokens', 'zzzznope');+ await section('tokens/tokens-spacing', 'zzzznope');} catch (e) {err = e;}@@ -44,10 +44,10 @@ describe('docs.detail.section leaf', () => {}, SLOW);it('does not return the first section for an empty section name', async () => {- await expect(section('tokens', '')).rejects.toMatchObject({+ await expect(section('tokens/tokens-spacing', '')).rejects.toMatchObject({code: 'ERR_UNKNOWN_SECTION',});- await expect(section('tokens', ' ')).rejects.toMatchObject({+ await expect(section('tokens/tokens-spacing', ' ')).rejects.toMatchObject({code: 'ERR_UNKNOWN_SECTION',});}, SLOW);diff --git a/packages/cli/api/docs/docOverlays.test.mjs b/packages/cli/api/docs/docOverlays.test.mjsindex 339bf6bdac..4b18de12f1 100644--- a/packages/cli/api/docs/docOverlays.test.mjs+++ b/packages/cli/api/docs/docOverlays.test.mjs@@ -114,26 +114,37 @@ describe('reference doc overlays (#2182)', () => {describe('the reported defect: docs tokens --dense (#2182)', () => {it('does not print the colour table under the Spacing heading', async () => {- const result = await docs('tokens', null, {dense: true});- const spacing = result.data.sections.find(s => /spacing/i.test(s.title));- expect(spacing, 'tokens docs should have a spacing section').toBeTruthy();-- const text = JSON.stringify(spacing);- expect(- text.includes('--color-'),- `The "${spacing.title}" section of \`docs tokens --dense\` contains ` +- `colour tokens. An agent reading this learns that spacing tokens are ` +- `named --color-*.`,- ).toBe(false);- expect(text).toContain('--spacing-');+ // The spacing table lives in its own guide; the spacing topic shows it+ // through a token reference to the tokens namespace. Both, read dense.+ for (const topic of ['tokens/tokens-spacing', 'spacing']) {+ const result = await docs(topic, null, {dense: true});+ const spacing = result.data.sections.find(s =>+ JSON.stringify(s).includes('--spacing-'),+ );+ expect(spacing, `${topic} --dense should show the spacing table`).toBeTruthy();+ const text = JSON.stringify(spacing);+ expect(+ text.includes('--color-'),+ `The "${spacing.title}" section of \`docs ${topic} --dense\` contains ` ++ `colour tokens. An agent reading this learns that spacing tokens are ` ++ `named --color-*.`,+ ).toBe(false);+ }});it('keeps every base section reachable, even without an overlay entry', async () => {- // The tokens overlay compresses only 6 of 13 sections. The other 7 must- // still render (in English), not vanish or absorb a neighbour's title.- const full = await docs('tokens', null, {});- const dense = await docs('tokens', null, {dense: true});- expect(dense.data.sections.length).toBe(full.data.sections.length);+ // The tokens overlays compress 5 of 15 category tables. Read through the+ // namespace, the other 10 must still render (in English), not vanish or+ // absorb a neighbour's title.+ const full = await docs('tokens', null, {depth: 'all', detail: 'full'});+ const dense = await docs('tokens', null, {depth: 'all', detail: 'full', dense: true});+ const titles = read =>+ read.data.slots.flatMap(slot =>+ slot.children.flatMap(child => (child.sections ?? []).map(s => s.title)),+ );+ expect(titles(dense).length).toBe(titles(full).length);+ expect(titles(dense)).toContain('Color');+ expect(titles(dense)).toContain('Font Size Tokens');});it('does not lose a section from docs theme --dense', async () => {diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjsindex fb5d1dab02..fa850130c8 100644--- a/packages/cli/api/docs/docs.doc.mjs+++ b/packages/cli/api/docs/docs.doc.mjs@@ -168,7 +168,7 @@ export const doc = {label: 'A whole guide from the docs tree',code: "await docs('cli/integrations/quick-start');",},- {label: 'One section by key', code: "await docs('tokens', 'spacing');"},+ {label: 'One section by key', code: "await docs('spacing', 'scale');"},],command: 'docs',related: ['search', 'component', 'hook', 'template'],diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjsindex 0f897d9771..d391321937 100644--- a/packages/cli/api/docs/docs.test.mjs+++ b/packages/cli/api/docs/docs.test.mjs@@ -53,7 +53,7 @@ describe('docs() dispatcher routing', () => {it('reads a shortened section by its old key, which its title still derives', async () => {const r = await docs(- 'styling',+ 'styling/tokens-and-setup','stylex-build-setup-required-for-swizzled-components',);expect(r.type).toBe('docs.detail.section');@@ -92,7 +92,7 @@ describe('docs() dispatcher routing', () => {it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {const res = await docs();- expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'layout', 'unorganized']);+ expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);for (const entry of res.data) {expect((await docs(entry.topic)).type).toBe('docs.detail');}diff --git a/packages/cli/api/docs/integration-tree.test.mjs b/packages/cli/api/docs/integration-tree.test.mjsindex f422ce7f43..d9be801204 100644--- a/packages/cli/api/docs/integration-tree.test.mjs+++ b/packages/cli/api/docs/integration-tree.test.mjs@@ -247,7 +247,7 @@ describe('integration docs in the docs tree', () => {scaffold({...kit(),'unorganized.doc.mjs': {...NAMESPACE, name: 'unorganized', title: 'Mine', summary: 'Mine.'},- 'tokens.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Acme tokens', summary: 'Acme tokens.'},+ 'use-a-theme.doc.mjs': {...NAMESPACE, name: 'use-a-theme', title: 'Acme use-a-theme', summary: 'Acme use-a-theme.'},'cli.doc.mjs': flat('cli'),});const listed = await docs(undefined, undefined, {cwd: tmpDir});@@ -257,24 +257,24 @@ describe('integration docs in the docs tree', () => {expect.objectContaining({topic: 'unorganized', package: '@astryxdesign/cli'}),]),);- expect(listed.meta.namespaces.filter(n => ['tokens', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);+ expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);expect(listed.data.map(entry => entry.topic)).not.toContain('cli');// Each name opens the CLI's doc, and a CLI topic keeps its home.expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});- const tokens = await docs('tokens', undefined, {cwd: tmpDir});+ const tokens = await docs('use-a-theme', undefined, {cwd: tmpDir});expect(tokens.type).toBe('docs.detail');expect(tokens.data.links.up).toBe('astryx docs unorganized');// The project doctor and the package doctor both name the claims.const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});expect(check.status).toBe('warn');expect(check.message).toContain('takes the route "unorganized", which the CLI\'s own docs keep');- expect(check.message).toContain('takes the route "tokens"');+ expect(check.message).toContain('takes the route "use-a-theme"');expect(check.message).toContain('both have the route "cli"');const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message).join('\n');expect(graph).toContain('takes the route "unorganized"');- expect(graph).toContain('takes the route "tokens"');+ expect(graph).toContain('takes the route "use-a-theme"');expect(graph).toContain('route "cli"');}, SLOW);@@ -298,8 +298,8 @@ describe('integration docs in the docs tree', () => {`export const docs = ${JSON.stringify(flat('Unorganized'), null, 2)};\n`,);fs.writeFileSync(- path.join(nested, 'caps-tokens.doc.mjs'),- `export const docs = ${JSON.stringify(flat('TOKENS'), null, 2)};\n`,+ path.join(nested, 'caps-use-a-theme.doc.mjs'),+ `export const docs = ${JSON.stringify(flat('USE-A-THEME'), null, 2)};\n`,);expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});@@ -315,10 +315,10 @@ describe('integration docs in the docs tree', () => {expect(check.status).toBe('warn');expect(check.message).toContain('route "CLI"');expect(check.message).toContain('takes the route "Unorganized"');- // `TOKENS` is the CLI's topic `tokens` in another spelling: the CLI's wins.- const tokens = await docs('TOKENS', undefined, {cwd: tmpDir, index: true});- expect(tokens.data).toMatchObject({name: 'tokens', links: {up: 'astryx docs unorganized'}});- expect(tokens.data.title).not.toBe('Acme TOKENS');+ // `USE-A-THEME` is the CLI's topic `use-a-theme` in another spelling: the CLI's wins.+ const tokens = await docs('USE-A-THEME', undefined, {cwd: tmpDir, index: true});+ expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs unorganized'}});+ expect(tokens.data.title).not.toBe('Acme USE-A-THEME');const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph')@@ -329,7 +329,7 @@ describe('integration docs in the docs tree', () => {}, SLOW);it("keeps a replaced name for the topic that replaces it, over another integration's namespace", async () => {- scaffold({...kit(), 'tokens-ns.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Kit tokens', summary: 'Kit tokens.'}});+ scaffold({...kit(), 'use-a-theme-ns.doc.mjs': {...NAMESPACE, name: 'use-a-theme', title: 'Kit use-a-theme', summary: 'Kit use-a-theme.'}});const two = path.join(tmpDir, 'node_modules', '@acme', 'two');fs.mkdirSync(path.join(two, 'docs'), {recursive: true});fs.writeFileSync(path.join(two, 'package.json'), JSON.stringify({name: '@acme/two', version: '1.0.0'}));@@ -341,7 +341,7 @@ describe('integration docs in the docs tree', () => {name: 'acme-tokens',title: 'Acme tokens',description: 'Acme tokens.',- replaces: 'tokens',+ replaces: 'use-a-theme',sections: [{title: 'One', content: [{type: 'prose', text: 'One.'}]}],}, null, 2)};\n`,);@@ -350,8 +350,8 @@ describe('integration docs in the docs tree', () => {"export default {integrations: ['@acme/kit', '@acme/two']};\n",);const listed = await docs(undefined, undefined, {cwd: tmpDir});- expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('tokens');- const read = await docs('tokens', undefined, {cwd: tmpDir, index: true});+ expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('use-a-theme');+ const read = await docs('use-a-theme', undefined, {cwd: tmpDir, index: true});expect(read.data.name).toBe('acme-tokens');const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});expect(check.status).toBe('warn');@@ -359,7 +359,7 @@ describe('integration docs in the docs tree', () => {}, SLOW);it('keeps every name a topic replaced twice answers to, and the CLI\'s links to it still open', async () => {- scaffold({...kit(), 'tokens-ns.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Kit tokens', summary: 'Kit tokens.'}});+ scaffold({...kit(), 'use-a-theme-ns.doc.mjs': {...NAMESPACE, name: 'use-a-theme', title: 'Kit use-a-theme', summary: 'Kit use-a-theme.'}});/** @param {string} pkg @param {string} name @param {string} replaces */const replacement = (pkg, name, replaces) => {const dir = path.join(tmpDir, 'node_modules', '@acme', pkg);@@ -378,30 +378,30 @@ describe('integration docs in the docs tree', () => {}, null, 2)};\n`,);};- replacement('two', 'acme-tokens', 'tokens');- replacement('three', 'b-tokens', 'tokens');+ replacement('two', 'acme-tokens', 'use-a-theme');+ replacement('three', 'b-tokens', 'use-a-theme');replacement('four', 'super-tokens', 'b-tokens');fs.writeFileSync(path.join(tmpDir, 'astryx.config.mjs'),"export default {integrations: ['@acme/kit', '@acme/two', '@acme/three', '@acme/four']};\n",);const listed = await docs(undefined, undefined, {cwd: tmpDir});- expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('tokens');- for (const name of ['tokens', 'acme-tokens', 'b-tokens', 'super-tokens']) {+ expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('use-a-theme');+ for (const name of ['use-a-theme', 'acme-tokens', 'b-tokens', 'super-tokens']) {expect((await docs(name, undefined, {cwd: tmpDir, index: true})).data.name).toBe('super-tokens');}- // A walk over every topic: the CLI's own links to `tokens` still open it.+ // A walk over every topic: the CLI's own links to `use-a-theme` still open it./** @type {string[]} */const raw = [];for (const entry of listed.data) {const read = await docs(entry.topic, undefined, {cwd: tmpDir});- if (/\{@link [^}]*tokens\}/.test(JSON.stringify(read.data))) raw.push(entry.topic);+ if (/\{@link [^}]*use-a-theme\}/.test(JSON.stringify(read.data))) raw.push(entry.topic);}expect(raw).toEqual([]);- const principles = await docs('principles', undefined, {cwd: tmpDir});- expect(JSON.stringify(principles.data)).toContain('astryx docs super-tokens');+ const theme = await docs('theme', undefined, {cwd: tmpDir});+ expect(JSON.stringify(theme.data)).toContain('astryx docs super-tokens');const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});- expect(check.message).toContain('takes the route "tokens", which the topic "super-tokens" also answers to');+ expect(check.message).toContain('takes the route "use-a-theme", which the topic "super-tokens" also answers to');expect(check.message).not.toContain('names no doc');}, SLOW);@@ -510,7 +510,7 @@ describe('integration docs in the docs tree', () => {content: [{type: 'prose',- text: 'See {@link generic:integrations}, and {@link @astryxdesign/cli:generic:tokens} for the tokens.',+ text: 'See {@link generic:integrations}, and {@link @astryxdesign/cli:namespace:tokens} for the tokens.',},],},diff --git a/packages/cli/api/docs/integrationDocs.test.mjs b/packages/cli/api/docs/integrationDocs.test.mjsindex 576ca8ac11..2bcca41714 100644--- a/packages/cli/api/docs/integrationDocs.test.mjs+++ b/packages/cli/api/docs/integrationDocs.test.mjs@@ -100,7 +100,7 @@ describe('integration-contributed topics', () => {package: '@acme/widgets',});// The built-in topics keep their own owner.- expect(listed.data.find(t => t.topic === 'tokens').package).toBe('@astryxdesign/cli');+ expect(listed.data.find(t => t.topic === 'color').package).toBe('@astryxdesign/cli');const detail = await docs('deploying', undefined, {cwd: tmpDir, full: true});expect(detail.type).toBe('docs.detail');@@ -331,7 +331,7 @@ describe('integration-contributed topics', () => {it("falls back to the CLI's own topics when the project config is unreadable", async () => {scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {integrations: 42};\n'});const catalog = await loadDocsCatalog(tmpDir);- expect(catalog.resolve('tokens')).toBeTruthy();+ expect(catalog.resolve('color')).toBeTruthy();expect(catalog.resolve('deploying')).toBeUndefined();}, SLOW);});diff --git a/packages/cli/api/docs/token-tables.test.mjs b/packages/cli/api/docs/token-tables.test.mjsnew file mode 100644index 0000000000..aa4f6a1822--- /dev/null+++ b/packages/cli/api/docs/token-tables.test.mjs@@ -0,0 +1,93 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The design tokens are written once. Each category's table lives in its+ * guide under the tokens namespace; a token reference to `tokens` reads that+ * guide, so no flat copy of the tables is listed, searched, or compiled.+ */++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import {docs} from './docs.mjs';+import {search} from '../search/search.mjs';++const SLOW = 60_000;+const DOCS_DIR = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../assets/docs',+);++/** Every authored CLI doc file, flat and placed (translation overlays aside). */+function authoredDocFiles() {+ return [DOCS_DIR, path.join(DOCS_DIR, 'tree')].flatMap(dir =>+ fs+ .readdirSync(dir)+ .filter(file => /^[\w-]+\.doc\.mjs$/.test(file))+ .map(file => path.join(dir, file)),+ );+}++describe('the design tokens', () => {+ it('are each written in exactly one doc table', async () => {+ /** @type {Map<string, string[]>} */+ const owners = new Map();+ for (const file of authoredDocFiles()) {+ const {docs: doc} = await import(file);+ for (const section of doc.sections ?? []) {+ for (const block of section.content ?? []) {+ if (block?.type !== 'table') continue;+ for (const row of block.rows) {+ if (!/^--[a-z]/.test(row[0])) continue;+ owners.set(row[0], [+ ...(owners.get(row[0]) ?? []),+ path.relative(DOCS_DIR, file),+ ]);+ }+ }+ }+ }+ expect(owners.size).toBeGreaterThan(200);+ expect([...owners].filter(([, files]) => files.length > 1)).toEqual([]);+ });++ it(+ 'are not listed or searched twice',+ async () => {+ const listed = await docs();+ const names = listed.data.map(entry => entry.topic);+ expect(names).not.toContain('token-tables');+ expect(listed.meta.namespaces.map(entry => entry.topic)).toContain(+ 'tokens',+ );++ const found = (await search('spacing tokens', {type: 'doc', limit: 50}))+ .data.results;+ const holders = found+ .filter(+ hit =>+ hit.section === 'spacing-tokens' ||+ hit.name === 'tokens/tokens-spacing',+ )+ .map(hit => hit.name);+ expect(new Set(holders)).toEqual(new Set(['tokens/tokens-spacing']));+ },+ SLOW,+ );++ it(+ 'still answer a token reference to `tokens`, in every language',+ async () => {+ for (const options of [{}, {dense: true}, {zh: true}]) {+ const read = await docs('color', null, options);+ const text = JSON.stringify(read.data.sections);+ expect(text).not.toContain('[token-ref');+ expect(text).toContain('--color-accent');+ }+ const section = await docs('spacing', 'scale');+ expect(JSON.stringify(section.data)).toContain('--spacing-4');+ },+ SLOW,+ );+});diff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjsindex 2bedadf05a..0892910afa 100644--- a/packages/cli/assets/docs/author-a-theme.doc.mjs+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs@@ -67,7 +67,7 @@ export const docs = {{title: 'Component Style Overrides',content: [- {type: 'prose', text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in {@link generic:styling}.'},+ {type: 'prose', text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in {@link generic:styling-advanced}.'},{type: 'code', lang: 'tsx', label: 'Component overrides with standard CSS', code: "components: {\n card: {\n base: { borderRadius: '20px', padding: '24px' },\n },\n button: {\n base: {\n borderRadius: '9999px',\n textTransform: 'uppercase',\n '--button-focus-offset': '3px',\n },\n 'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },\n },\n}"},{type: 'prose', text: "Run `astryx theme targets` for every themeable key in the system (`astryx theme targets <Name>` to scope it, `--json` to lint a theme against it), and `astryx component <Name>` for one component's theming targets, public CSS variables, and which standard CSS properties are supported."},{type: 'list', style: 'do', items: ['Write standard CSS properties (borderRadius, padding); the pipeline expands them into internal vars.', 'Set public CSS vars directly when no standard property equivalent exists.']},@@ -121,7 +121,7 @@ export const docs = {]},{type: 'prose', text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it. Load the generated CSS wherever you load the module.'},{type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n <App />\n</Theme>"},- {type: 'prose', text: "After upgrading Astryx, rerun `astryx theme build` for every custom prebuilt theme. Deploy the regenerated files together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build. The build also warns when the theme names font families it does not load. See {@link generic:typography} for the full recipe."},+ {type: 'prose', text: "After upgrading Astryx, rerun `astryx theme build` for every custom prebuilt theme. Deploy the regenerated files together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build. The build also warns when the theme names font families it does not load. See {@link generic:font-setup} for the full recipe."},{type: 'prose', text: 'For the runtime vs built tradeoff, see the Runtime vs Built section of {@link generic:use-a-theme}.'},],},@@ -151,7 +151,7 @@ export const docs = {{type: 'code', lang: 'ts', label: 'CSS var references for styling-library configs', code: "import {tokenVar, tokenVars} from '@astryxdesign/core/theme/tokens';\n\nconst pandaOrEmotionTheme = {\n colors: {\n text: tokenVar('--color-text-primary'),\n surface: tokenVars['--color-background-surface'],\n },\n};"},{type: 'code', lang: 'ts', label: 'Resolve token values without a hook', code: "import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';\nimport {neutralTheme} from '@astryxdesign/theme-neutral';\n\nconst lightTokens = resolveThemeTokens(neutralTheme, {mode: 'light'});\nconst chartTheme = {\n textColor: lightTokens['--color-text-primary'],\n seriesColor: lightTokens['--color-data-categorical-blue'],\n};"},{type: 'prose', text: 'The `@astryxdesign/core/theme/tokens` subpath is server-safe and does not require React. The main `@astryxdesign/core/theme` barrel also re-exports these helpers for client code that already imports theme APIs.'},- {type: 'prose', text: 'For styling library interop patterns, see {@link generic:styling-libraries}.'},+ {type: 'prose', text: 'For styling library interop patterns, see {@link namespace:styling-libraries}.'},],},{@@ -159,7 +159,7 @@ export const docs = {content: [{type: 'prose', text: '`useTheme()` reads the nearest Theme and effective color mode from React context. Use it inside client components for SVG, canvas, charts, maps, and third-party configuration objects that need token values in JavaScript.'},{type: 'code', lang: 'tsx', label: 'Access resolved token values in React', code: "import {useMemo} from 'react';\nimport {useTheme} from '@astryxdesign/core/theme';\n\nfunction ChartConfig() {\n const {mode, tokens} = useTheme();\n const options = useMemo(() => ({\n mode,\n textColor: tokens['--color-text-primary'],\n gridColor: tokens['--color-border'],\n seriesColor: tokens['--color-data-categorical-blue'],\n }), [mode, tokens]);\n return <Chart options={options} />;\n}"},- {type: 'prose', text: 'Prefer CSS variables for ordinary styling. See {@link generic:use-a-theme} for the provider setup, and {@link generic:tokens} for the full token reference.'},+ {type: 'prose', text: 'Prefer CSS variables for ordinary styling. See {@link generic:use-a-theme} for the provider setup, and {@link namespace:tokens} for the full token reference.'},],},],diff --git a/packages/cli/assets/docs/getting-started.doc.mjs b/packages/cli/assets/docs/getting-started.doc.mjsindex 9f2d7666cd..2721e10795 100644--- a/packages/cli/assets/docs/getting-started.doc.mjs+++ b/packages/cli/assets/docs/getting-started.doc.mjs@@ -106,7 +106,7 @@ import {themes, defaultThemeSlug} from './astryx-themes';},{type: 'prose',- text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. Before building screens, read the two cascade layer sections of {@link generic:migration}.',+ text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. Before building screens, read the two cascade layer sections of {@link generic:migration-setup}.',},{type: 'prose',@@ -143,7 +143,7 @@ export default function Page() {content: [{type: 'prose',- text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See {@link generic:styling} for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',+ text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See {@link namespace:styling} for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',},{type: 'code',diff --git a/packages/cli/assets/docs/principles.doc.dense.mjs b/packages/cli/assets/docs/principles.doc.dense.mjsindex 5d3aba0069..d4132457aa 100644--- a/packages/cli/assets/docs/principles.doc.dense.mjs+++ b/packages/cli/assets/docs/principles.doc.dense.mjs@@ -6,9 +6,9 @@ export const docsDense = {description: 'core design principles + rules for the design system',sections: [{ section: 'Design Philosophy', title: 'Philosophy', content: [{ type: 'prose', text: 'consistency, adaptability, DX. core ideas:' }, { type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },- { section: 'Rules', title: 'Rules', content: [{ type: 'prose', text: '8 rules for on-system app code.' }, { type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content ({@link namespace:layout})', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling ({@link generic:styling})', 'semantic tokens only ({@link generic:tokens})', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },- { section: 'Styling Approach', title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout.' }, { type: 'prose', text: 'full guide: {@link generic:styling}' }] },+ { section: 'Rules', title: 'Rules', content: [{ type: 'prose', text: '8 rules for on-system app code.' }, { type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content ({@link namespace:layout})', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling ({@link namespace:styling})', 'semantic tokens only ({@link namespace:tokens})', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },+ { section: 'Styling Approach', title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout.' }, { type: 'prose', text: 'full guide: {@link namespace:styling}' }] },{ section: 'Anti-Patterns', title: 'Anti-Patterns', content: [{ type: 'prose', text: 'what breaks theming, routing, or layout, and the fix.' }, { type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data ({@link namespace:layout})', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },- { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'full token reference: {@link generic:tokens}' }] },+ { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'full token reference: {@link namespace:tokens}' }] },],};diff --git a/packages/cli/assets/docs/principles.doc.mjs b/packages/cli/assets/docs/principles.doc.mjsindex 0cea0a231b..957a9fa672 100644--- a/packages/cli/assets/docs/principles.doc.mjs+++ b/packages/cli/assets/docs/principles.doc.mjs@@ -45,8 +45,8 @@ export const docs = {'Use components for everything they cover','Page layout is frame-first: pick the shell and budget regions before writing content (see {@link namespace:layout})','Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',- 'StyleX or Tailwind for custom styling; both are first-class (see {@link generic:styling})',- 'Semantic tokens, not hardcoded values (see {@link generic:tokens})',+ 'StyleX or Tailwind for custom styling; both are first-class (see {@link namespace:styling})',+ 'Semantic tokens, not hardcoded values (see {@link namespace:tokens})','CSS custom properties for colors, not hex values','Form inputs are controlled (value + onChange)','Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider',@@ -64,7 +64,7 @@ export const docs = {},{type: 'prose',- text: 'See {@link generic:styling} for the complete guide with examples.',+ text: 'See {@link namespace:styling} for the complete guide with examples.',},],},@@ -97,7 +97,7 @@ export const docs = {content: [{type: 'prose',- text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run {@link generic:tokens} for the full reference with all values.',+ text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run {@link namespace:tokens} for the full reference with all values.',},],},diff --git a/packages/cli/assets/docs/principles.doc.zh.mjs b/packages/cli/assets/docs/principles.doc.zh.mjsindex 0252817a4b..ffa99c6992 100644--- a/packages/cli/assets/docs/principles.doc.zh.mjs+++ b/packages/cli/assets/docs/principles.doc.zh.mjs@@ -6,9 +6,9 @@ export const docsZh = {description: 'Astryx 核心设计原则和规则。',sections: [{ section: 'Design Philosophy', title: '设计哲学', content: [{ type: 'prose', text: '一个注重一致性、适应性和开发者体验的设计系统。核心理念:' }, { type: 'list', items: ['组件优于原始元素 — 优先使用 Astryx 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },- { section: 'Rules', title: '规则', content: [{ type: 'prose', text: '让应用代码保持在设计系统之内的八条规则。' }, { type: 'list', items: ['所有支持的场景都使用 Astryx 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 {@link namespace:layout})', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置(见 {@link generic:styling})', '使用语义化令牌,不使用硬编码值(见 {@link generic:tokens})', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },- { section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。' }, { type: 'prose', text: '完整指南见 {@link generic:styling}。' }] },+ { section: 'Rules', title: '规则', content: [{ type: 'prose', text: '让应用代码保持在设计系统之内的八条规则。' }, { type: 'list', items: ['所有支持的场景都使用 Astryx 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 {@link namespace:layout})', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置(见 {@link namespace:styling})', '使用语义化令牌,不使用硬编码值(见 {@link namespace:tokens})', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },+ { section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。' }, { type: 'prose', text: '完整指南见 {@link namespace:styling}。' }] },{ section: 'Anti-Patterns', title: '反模式', content: [{ type: 'prose', text: '会破坏主题、路由或布局的写法,以及应改用的做法。' }, { type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 {@link namespace:layout})', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },- { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '完整令牌参考见 {@link generic:tokens}。' }] },+ { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '完整令牌参考见 {@link namespace:tokens}。' }] },],};diff --git a/packages/cli/assets/docs/styling-libraries.doc.mjs b/packages/cli/assets/docs/styling-libraries.doc.mjsdeleted file mode 100644index 111322f19d..0000000000--- a/packages/cli/assets/docs/styling-libraries.doc.mjs+++ /dev/null@@ -1,469 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */--export const docs = {- name: 'styling-libraries',- title: 'Styling Library Interop',- category: 'guide',- description:- 'Integrate Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, and non-CSS renderers with system tokens.',-- sections: [- {- title: 'Core Principle',- category: 'guide',- content: [- {- type: 'prose',- text: 'Keep the system as the source of truth for theme values. Components read design tokens from CSS custom properties such as `--color-text-primary`, `--color-background-surface`, `--spacing-4`, and `--radius-container`. Other styling libraries should map their own semantic tokens, utility names, or theme objects to those system CSS variables whenever possible.',- },- {- type: 'prose',- text: 'Use CSS variables for ordinary DOM styling because they inherit through the tree, follow `data-theme` color mode, respect nested `data-astryx-theme` scopes, and update when themes switch. Use token resolver APIs only for non-CSS consumers such as SVG attribute values, canvas, chart configuration, color calculations, or static config generation.',- },- {- type: 'prose',- text: 'For available token names and values, run {@link generic:tokens}. Focused references are also available with {@link generic:color}, {@link generic:spacing}, {@link generic:shape}, {@link generic:typography}, {@link generic:elevation}, and {@link generic:motion}.',- },- ],- },- {- title: 'Choose an Integration Path',- category: 'guide',- content: [- {- type: 'prose',- text: 'Choose the narrowest integration path that fits the styling library. Most DOM styling should stay on the CSS-variable path; JavaScript token resolution is for APIs that cannot consume CSS custom properties.',- },- {- type: 'table',- headers: ['Path', 'Use when', 'Value shape'],- rows: [- [- 'CSS variable aliases',- 'The library ultimately writes CSS and accepts string values',- '`var(--color-text-primary)`',- ],- [- 'StyleX token imports',- 'You are writing StyleX styles in application code',- "`colorVars['--color-text-primary']`",- ],- [- 'Tailwind bridge',- 'You want utility classes backed by active system tokens',- '`@astryxdesign/core/tailwind-theme.css`',- ],- [- 'Design token resolver APIs',- 'JavaScript needs token values for charts, canvas, SVG, or config objects',- "`resolveThemeToken(theme, '--color-data-categorical-blue', {mode})`",- ],- ],- },- ],- },- {- title: 'Best Practices',- category: 'guide',- content: [- {- type: 'list',- style: 'do',- items: [- 'Map by semantic intent: text, surface, border, accent, status, radius, spacing, typography.',- 'Let the system own color mode. The root Theme syncs `data-theme="light|dark"` and `data-astryx-theme` to `<html>` for portals and first-level theme scope.',- 'Prefer CSS variables for runtime theme switching and nested themes.',- ],- },- {- type: 'list',- style: 'dont',- items: [- 'Copy raw hex/px values into a second theme object when a `var(...)` reference would work.',- 'Run a second unsynchronized dark-mode provider that disagrees with Theme.',- 'Make another library\'s CSS variables the source of truth for the system. Some consumers need token values outside the DOM.',- ],- },- ],- },- {- title: 'Plain CSS and CSS Modules',- category: 'guide',- content: [- {- type: 'prose',- text: 'The simplest integration is direct CSS variable usage. CSS Modules scope class names, but system token variables are global/inherited values supplied by package CSS and the active theme.',- },- {- type: 'code',- lang: 'css',- label: 'Card.module.css',- code: `.card {- background: var(--color-background-surface);- color: var(--color-text-primary);- border: 1px solid var(--color-border);- border-radius: var(--radius-container);- padding: var(--spacing-4);-}`,- },- {- type: 'prose',- text: 'Sass variables are compile-time only. They are useful for generating static CSS, but they do not update when the system switches theme or color mode. Use native CSS custom properties for themeable values.',- },- ],- },- {- title: 'StyleX',- category: 'guide',- content: [- {- type: 'prose',- text: 'For StyleX styles, prefer the typed token exports from `@astryxdesign/core/theme/tokens.stylex`. They provide autocomplete and catch token-name typos while still resolving through the same system CSS variables at runtime.',- },- {- type: 'code',- lang: 'tsx',- label: 'Typed token imports',- code: `import * as stylex from '@stylexjs/stylex';-import {colorVars, spacingVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';--const styles = stylex.create({- panel: {- backgroundColor: colorVars['--color-background-surface'],- color: colorVars['--color-text-primary'],- padding: spacingVars['--spacing-4'],- borderRadius: radiusVars['--radius-container'],- },-});`,- },- {- type: 'prose',- text: 'Use `xstyle` for component overrides and `stylex.props()` for your own DOM nodes. Use `className` when integrating a non-StyleX styling library.',- },- ],- },- {- title: 'Tailwind',- category: 'guide',- content: [- {- type: 'prose',- text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme reference inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme without emitting competing runtime declarations.',- },- {- type: 'code',- lang: 'css',- label: 'globals.css',- code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;--@import "tailwindcss/theme.css" layer(theme);-@import "tailwindcss/preflight.css" layer(base);-@import "@astryxdesign/core/reset.css";-@import "@astryxdesign/core/astryx.css";-@import "@astryxdesign/theme-neutral/theme.css";-@import "@astryxdesign/core/tailwind-theme.css";-@import "tailwindcss/utilities.css" layer(utilities);`,- },- {- type: 'prose',- text: 'Pre-declare every layer before any imports. This keeps reset lowest, Tailwind preflight above reset, component/theme styles in the middle, and Tailwind utilities last so utility classes on `className` can intentionally override component defaults.',- },- {- type: 'code',- lang: 'tsx',- label: 'Tailwind classes backed by system tokens',- code: `<section className="rounded-lg border border-border bg-surface p-4 text-primary shadow-md">- <Button label="Save" variant="primary" />-</section>`,- },- {- type: 'prose',- text: 'The Tailwind bridge is the concrete example of the general interop pattern: expose another library\'s semantic API, but point the values at system token variables.',- },- ],- },- {- id: 'semantic-token-systems',- title: 'Panda, Chakra, and Other Semantic Token Systems',- category: 'guide',- content: [- {- type: 'prose',- text: 'Libraries like Panda CSS and Chakra UI have first-class semantic token objects. Put system CSS variables at the leaves of those objects so product code can use the library\'s semantic names while the system still owns the values.',- },- {- type: 'code',- lang: 'ts',- label: 'Semantic token aliases',- code: `semanticTokens: {- colors: {- text: {- primary: {value: 'var(--color-text-primary)'},- secondary: {value: 'var(--color-text-secondary)'},- },- background: {- surface: {value: 'var(--color-background-surface)'},- body: {value: 'var(--color-background-body)'},- },- border: {- default: {value: 'var(--color-border)'},- },- },-},-tokens: {- spacing: {- 4: {value: 'var(--spacing-4)'},- },- radii: {- container: {value: 'var(--radius-container)'},- },-}`,- },- {- type: 'code',- lang: 'tsx',- label: 'Panda-style usage',- code: `<section- className={css({- bg: 'background.surface',- color: 'text.primary',- borderColor: 'border.default',- p: '4',- rounded: 'container',- })}-/>`,- },- {- type: 'prose',- text: 'If a semantic-token library needs to generate its own light/dark CSS from raw values, align its mode selector with Theme (`data-theme="light|dark"`) and generate that adapter from system theme data. Otherwise it can drift from nested or runtime themes.',- },- ],- },- {- title: 'MUI and Palette-Based Themes',- category: 'guide',- content: [- {- type: 'prose',- text: '`MUI` expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.',- },- {- type: 'code',- lang: 'ts',- label: 'MUI palette mapped to system vars',- code: `const theme = createTheme({- cssVariables: true,- colorSchemes: {- light: {- palette: {- primary: {main: 'var(--color-accent)'},- background: {- default: 'var(--color-background-body)',- paper: 'var(--color-background-surface)',- },- text: {- primary: 'var(--color-text-primary)',- secondary: 'var(--color-text-secondary)',- },- divider: 'var(--color-border)',- },- },- dark: {- palette: {- primary: {main: 'var(--color-accent)'},- background: {- default: 'var(--color-background-body)',- paper: 'var(--color-background-surface)',- },- text: {- primary: 'var(--color-text-primary)',- secondary: 'var(--color-text-secondary)',- },- divider: 'var(--color-border)',- },- },- },-});`,- },- {- type: 'prose',- text: 'If MUI owns color mode in an app, generate the light and dark palette values from system theme data and keep Theme mode synchronized. If Theme owns color mode, keep both MUI schemes pointing at the same system CSS variables.',- },- ],- },- {- id: 'css-in-js',- title: 'Emotion, styled-components, Theme UI, and Styled System',- category: 'guide',- content: [- {- type: 'prose',- text: 'Runtime CSS-in-JS libraries such as `Emotion` and `styled-components` usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.',- },- {- type: 'code',- lang: 'ts',- label: 'Generic CSS-in-JS theme object',- code: `const appTheme = {- colors: {- textPrimary: 'var(--color-text-primary)',- textSecondary: 'var(--color-text-secondary)',- surface: 'var(--color-background-surface)',- border: 'var(--color-border)',- accent: 'var(--color-accent)',- },- spacing: {- 4: 'var(--spacing-4)',- },- radius: {- container: 'var(--radius-container)',- },-};`,- },- {- type: 'prose',- text: 'Avoid rebuilding CSS-in-JS theme objects with raw color values on every mode switch. CSS variables let the class names stay the same while the browser resolves the active values.',- },- ],- },- {- id: 'unocss',- title: 'UnoCSS and Custom Utility Systems',- category: 'guide',- content: [- {- type: 'prose',- text: 'Utility generators such as UnoCSS can put system variables in their theme config or shortcuts. Keep classes semantic (`bg-surface`, `text-primary`) and let the values point at system tokens.',- },- {- type: 'code',- lang: 'ts',- label: 'UnoCSS-style config',- code: `export default defineConfig({- theme: {- colors: {- surface: 'var(--color-background-surface)',- primary: 'var(--color-text-primary)',- border: 'var(--color-border)',- accent: 'var(--color-accent)',- },- spacing: {- 4: 'var(--spacing-4)',- },- },- shortcuts: {- 'astryx-card': 'bg-surface text-primary border border-border rounded-lg p-4',- },-});`,- },- {- type: 'prose',- text: 'Static utility extractors cannot see dynamically constructed class names. Prefer explicit class strings or the library\'s safelist/source-registration mechanism.',- },- ],- },- {- title: 'Non-CSS Processing',- category: 'guide',- content: [- {- type: 'prose',- text: 'Use `resolveThemeTokens()` or `resolveThemeToken()` when code outside React needs token values for a known theme and mode. Use `useTheme()` inside client components when the values should come from the nearest Theme and active mode.',- },- {- type: 'code',- lang: 'ts',- label: 'Resolve tokens without React context',- code: `import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';-import {neutralTheme} from '@astryxdesign/theme-neutral/built';--const tokens = resolveThemeTokens(neutralTheme, {mode: 'light'});--const chartOptions = {- textColor: tokens['--color-text-primary'],- mutedTextColor: tokens['--color-text-secondary'],- gridColor: tokens['--color-border'],- seriesColors: [- tokens['--color-data-categorical-blue'],- tokens['--color-data-categorical-orange'],- tokens['--color-data-categorical-purple'],- ],-};`,- },- {- type: 'code',- lang: 'tsx',- label: 'Resolve tokens from the nearest Theme',- code: `'use client';--import {useMemo} from 'react';-import {useTheme} from '@astryxdesign/core/theme';--function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {- const {mode, tokens} = useTheme();-- const chartOptions = useMemo(- () => ({- mode,- textColor: tokens['--color-text-primary'],- mutedTextColor: tokens['--color-text-secondary'],- gridColor: tokens['--color-border'],- seriesColors: [- tokens['--color-data-categorical-blue'],- tokens['--color-data-categorical-orange'],- tokens['--color-data-categorical-purple'],- ],- }),- [mode, tokens],- );-- return <ThirdPartyChart data={data} options={chartOptions} />;-}`,- },- ],- },- {- id: 'non-css-best-practices',- title: 'Non-CSS Processing Best Practices',- category: 'guide',- content: [- {- type: 'list',- style: 'do',- items: [- 'Use the returned `tokens` object as a memo dependency; it is stable until the active theme or mode changes.',- 'Use data visualization tokens such as `--color-data-categorical-blue` for chart series instead of reusing arbitrary UI colors.',- 'Prefer CSS variables for SVG elements when possible (`fill="var(--color-accent)"`); use token resolver APIs when an API requires a string value in JavaScript.',- ],- },- {- type: 'list',- style: 'dont',- items: [- 'Use token resolver APIs for ordinary DOM styling. Use CSS variables, StyleX tokens, xstyle, or library aliases instead.',- 'Assume the returned values reflect every CSS cascade override. They resolve tokens for the current theme and mode; local media-surface overrides and arbitrary CSS overrides may not be represented in the returned map.',- ],- },- ],- },- {- title: 'Interop Checklist',- category: 'guide',- content: [- {- type: 'list',- style: 'ordered',- items: [- 'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `astryx theme build` or published `/built` theme imports plus `theme.css`.',- 'Choose one owner for color mode. Theme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.',- 'Map the external library\'s semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.',- 'Use {@link generic:tokens} and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',- 'Use token resolver APIs only for non-CSS APIs that need resolved values.',- ],- },- ],- },- ],-};diff --git a/packages/cli/assets/docs/styling-overview.doc.mjs b/packages/cli/assets/docs/styling-overview.doc.mjsindex 7175ba8192..9917612327 100644--- a/packages/cli/assets/docs/styling-overview.doc.mjs+++ b/packages/cli/assets/docs/styling-overview.doc.mjs@@ -112,7 +112,7 @@ export const docs = {},{type: 'prose',- text: 'For Tailwind v3, see the layer workaround in {@link generic:migration}.',+ text: 'For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',},],},@@ -155,7 +155,7 @@ export const docs = {},{type: 'prose',- text: 'If a swizzled component renders with no styles and no error, a missing compiler is almost always why. See the StyleX Build Setup section of {@link generic:styling} for bundler config examples.',+ text: 'If a swizzled component renders with no styles and no error, a missing compiler is almost always why. See the StyleX Build Setup section of {@link generic:tokens-and-setup} for bundler config examples.',},],},@@ -199,10 +199,10 @@ export const docs = {type: 'list',style: 'unordered',items: [- '{@link generic:styling} \u2014 xstyle, className, data-attribute selectors, design tokens in code.',- '{@link generic:styling-libraries} \u2014 Tailwind bridge details, Panda, Chakra, MUI, CSS Modules, and non-CSS token resolution.',+ '{@link namespace:styling} \u2014 xstyle, className, data-attribute selectors, design tokens in code.',+ '{@link namespace:styling-libraries} \u2014 Tailwind bridge details, Panda, Chakra, MUI, CSS Modules, and non-CSS token resolution.','{@link generic:use-a-theme} \u2014 applying themes, dark mode, nested themes. {@link generic:author-a-theme} \u2014 defineTheme, overrides, production builds.',- '{@link generic:migration} \u2014 cascade layer audit, Tailwind v3 coexistence, and foundation smoke test.',+ '{@link namespace:migration} \u2014 cascade layer audit, Tailwind v3 coexistence, and foundation smoke test.',],},],diff --git a/packages/cli/assets/docs/styling.doc.mjs b/packages/cli/assets/docs/styling.doc.mjsdeleted file mode 100644index 430eb94390..0000000000--- a/packages/cli/assets/docs/styling.doc.mjs+++ /dev/null@@ -1,412 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */--export const docs = {- name: 'styling',- title: 'Styling Components',- category: 'guide',- description:- 'How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, theming hooks, and styling-library interop.',- keywords: ['override', 'customize', 'css'],-- sections: [- {- title: 'Overview',- category: 'guide',- content: [- {- type: 'prose',- text: 'Style components with `xstyle` (StyleX), `className` (Tailwind or your own CSS), or a styling library aliased to Astryx tokens. All of them resolve to the same tokens.',- },- {- type: 'table',- headers: ['Approach', 'Use for', 'Example'],- rows: [- ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', '`const styles = stylex.create(...); <Button xstyle={styles.save} />`'],- ['Tailwind utilities', 'Page layout, wrappers, and utility styling', '`className="flex gap-3 p-4"`'],- ['className', 'Integrating with external CSS or Tailwind on components', '`className="my-card shadow-lg"`'],- ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "`colors.surface = 'var(--color-background-surface)'`"],- ],- },- {- type: 'prose',- text: 'Theming and dark mode work whichever you choose. For external styling libraries, run {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',- },- ],- },- {- title: 'xstyle Prop',- category: 'guide',- content: [- {- type: 'prose',- text: 'Every component accepts an `xstyle` prop for style customization. It accepts StyleX styles created via `stylex.create()`, not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.',- },- {- type: 'code',- lang: 'tsx',- label: 'Simple overrides',- code: `import * as stylex from '@stylexjs/stylex';--const overrides = stylex.create({- card: { maxWidth: 400, marginBlock: 16 },- saveButton: { alignSelf: 'flex-end' },-});--<Card xstyle={overrides.card} />-<Button label="Save" xstyle={overrides.saveButton} />`,- },- {- type: 'code',- lang: 'tsx',- label: 'Pseudo-classes and conditional styles',- code: `import * as stylex from '@stylexjs/stylex';--const overrides = stylex.create({- card: {- boxShadow: {- default: 'none',- ':hover': { '@media (hover: hover)': '0 4px 12px rgba(0,0,0,0.1)' },- },- },-});--<Card xstyle={overrides.card}>...</Card>`,- },- {- type: 'list',- style: 'unordered',- items: [- 'All xstyle values must come from stylex.create()',- 'Pseudo-classes (:hover, :focus-visible) are supported inside stylex.create',- 'All :hover styles MUST use @media (hover: hover) guard',- 'For non-StyleX styling (Tailwind, external CSS), use className instead',- ],- },- ],- },- {- title: 'Tailwind Integration',- category: 'guide',- content: [- {- type: 'prose',- text: 'The package ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.',- },- {- type: 'prose',- text: 'For the imports and the cascade-layer order to put in your global CSS, see the Tailwind section of {@link generic:styling-libraries}.',- },- {- type: 'code',- lang: 'tsx',- label: 'Tailwind utilities alongside components',- code: `<div className="text-primary bg-surface rounded-lg p-4 flex gap-3">- <Button label="Save" variant="primary" />- <Button label="Cancel" variant="secondary" />-</div>`,- },- {- type: 'prose',- text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run {@link generic:styling-libraries}.',- },- ],- },- {- title: 'className and style Props',- category: 'guide',- content: [- {- type: 'prose',- text: 'Every component also accepts standard `className` and `style` props. `className` is appended after the component\'s own classes. `style` is merged after StyleX inline styles, so consumer values win on conflict.',- },- {- type: 'code',- lang: 'tsx',- label: 'className with Tailwind utilities',- code: `<Card className="shadow-lg hover:shadow-xl transition-shadow">- ...-</Card>-<Button label="Save" className="my-app-save-btn" />`,- },- {- type: 'prose',- text: 'For layout and wrapper styling, Tailwind utilities on className work well. For component-specific overrides (padding, colors, borders), prefer xstyle; it integrates with StyleX deduplication and the component\'s internal style pipeline.',- },- ],- },- {- title: 'Rest Props (Prop Drilling)',- category: 'guide',- content: [- {- type: 'prose',- text: 'Components extend HTML attributes and spread rest props onto their root DOM element. This means data-* attributes, aria-* attributes, event handlers, and other HTML props pass through automatically.',- },- {- type: 'code',- lang: 'tsx',- label: 'Data attributes, event handlers, and ARIA',- code: `<Card- data-testid="user-card"- data-user-id={user.id}- onMouseEnter={handleHover}- aria-label="User profile card"->- ...-</Card>`,- },- {- type: 'code',- lang: 'tsx',- label: 'Ref forwarding',- code: `const cardRef = useRef<HTMLDivElement>(null);-<Card ref={cardRef}>...</Card>`,- },- {- type: 'prose',- text: 'A few HTML attributes are intentionally omitted from the base type (contentEditable, dangerouslySetInnerHTML). children is not in the base type either; components that accept children declare it explicitly, so slot-based components don\'t silently drop JSX children.',- },- ],- },- {- title: 'Compound Components',- category: 'guide',- content: [- {- type: 'prose',- text: 'Complex components are composed from smaller components. Each sub-component accepts its own xstyle, className, and rest props. You style the parts individually; there\'s no single "drill into sub-part" prop.',- },- {- type: 'code',- lang: 'tsx',- label: 'Dialog with individually styled parts',- code: `import * as stylex from '@stylexjs/stylex';--const overrides = stylex.create({- dialog: { maxWidth: 500 },- content: { gap: 'var(--spacing-4)' },-});--<Dialog isOpen={isOpen} onOpenChange={close} xstyle={overrides.dialog}>- <Layout- header={- <LayoutHeader hasDivider>- <Heading level={2}>Edit Profile</Heading>- </LayoutHeader>- }- content={- <LayoutContent xstyle={overrides.content}>- <TextInput label="Name" value={name} onChange={setName} />- </LayoutContent>- }- footer={- <LayoutFooter hasDivider>- <Button label="Cancel" variant="secondary" onClick={close} />- <Button label="Save" variant="primary" onClick={save} />- </LayoutFooter>- }- />-</Dialog>`,- },- {- type: 'prose',- text: 'The pattern: the parent component (Dialog) controls structure and behavior, child components (Layout, Header, Button) control their own appearance. Style each piece where it lives.',- },- ],- },- {- // The key it had in 0.6, so `astryx docs styling- // preferred-selector-surface-data-attributes` keeps working.- id: 'preferred-selector-surface-data-attributes',- title: 'Data attribute selectors',- category: 'guide',- content: [- {- type: 'prose',- text: 'When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',- },- {- type: 'code',- lang: 'css',- code: `.my-app .astryx-button[data-variant="primary"] {- /* primary buttons in this app context */-}--.my-app .astryx-button[data-variant="primary"][data-size="sm"] {- /* small primary buttons */-}--.my-app .astryx-heading[data-level="2"] {- /* level 2 headings; numeric values stay literal in data attrs */-}`,- },- {- type: 'code',- lang: 'tsx',- label: 'What components reflect',- code: `// <Button variant="primary" size="sm" />-// preferred selector attrs: data-variant="primary" data-size="sm"--// <Card variant="elevated" />-// preferred selector attrs: data-variant="elevated"--// <Heading level={2} />-// preferred selector attrs: data-level="2"`,- },- {- type: 'prose',- text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run {@link generic:author-a-theme} for component theming.',- },- ],- },- {- id: 'deprecated-classes',- title: 'Deprecated: Bare Prop and State Classes',- category: 'guide',- content: [- {- type: 'prose',- text: 'Astryx still emits the deprecated bare classes (`.primary`, `.sm`, `.level-2`, `.checked`) and will remove them in a later release. Use data attributes for new CSS; `astryx upgrade --from <old version> --apply` rewrites qualified selectors in `.css` files.',- },- {- type: 'code',- lang: 'css',- code: `/* The upgrade preserves old consumer classes and adds the v0.6 prop match */-.my-app .astryx-button:is(.primary, [data-variant="primary"]) {- /* primary buttons or a consumer-supplied .primary class */-}--/* Numeric values stay literal in data attributes */-.my-app .astryx-heading:is(.level-2, [data-level="2"]) {- /* level 2 headings or a consumer-supplied .level-2 class */-}`,- },- {- type: 'prose',- text: 'The upgrade rewrites a selector only when an `.astryx-*` component class qualifies it, turning the old class into an `:is(...)` union of that class and the data attributes it stood for. The union keeps the selector\'s specificity and your own `className` matches, and keeps matching once the bare classes are gone; the `.astryx-*` classes themselves stay. It leaves unqualified classes (a bare `.primary`), unknown classes, and selectors in JavaScript or TypeScript alone: migrate those by hand, and only where they target Astryx.',- },- ],- },- {- title: 'Design Tokens',- category: 'guide',- content: [- {- type: 'prose',- text: 'When writing custom styles, use design tokens instead of hardcoded values. Tokens are CSS custom properties that adapt to the active theme and color mode. The system provides tokens for spacing, color, radius, shadow, typography, and size.',- },- {- type: 'code',- lang: 'tsx',- label: 'Using tokens in stylex.create',- code: `import * as stylex from '@stylexjs/stylex';--const styles = stylex.create({- surface: {- padding: 'var(--spacing-4)',- borderRadius: 'var(--radius-container)',- backgroundColor: 'var(--color-background-surface)',- },-});--<Card xstyle={styles.surface} />`,- },- {- type: 'code',- lang: 'tsx',- label: 'Using typed token imports in stylex.create',- code: `import {colorVars, spacingVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';--const styles = stylex.create({- highlight: {- backgroundColor: colorVars['--color-accent-muted'],- padding: spacingVars['--spacing-3'],- borderRadius: radiusVars['--radius-element'],- },-});`,- },- {- type: 'prose',- text: 'Both approaches work: var() strings or typed imports from tokens.stylex. The typed imports give autocomplete and catch typos at build time.',- },- {- type: 'prose',- text: 'See {@link generic:tokens} for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See {@link generic:author-a-theme} for how to override tokens via defineTheme.',- },- ],- },- {- id: 'stylex-setup',- title: 'StyleX Build Setup (required for swizzled components)',- category: 'guide',- content: [- {- type: 'prose',- text: 'Astryx components ship pre-compiled, so consuming the published package needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',- },- {- type: 'table',- headers: ['Bundler', 'StyleX plugin'],- rows: [- ['Webpack', '@stylexjs/webpack-plugin'],- ['Vite / Rollup', '@stylexjs/rollup-plugin (or a community Vite plugin)'],- ['Babel (any bundler)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],- ['Next.js (App Router, SWC)', 'An SWC-based transform; see the Next.js note below'],- ],- },- {- type: 'prose',- text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.',- },- {- type: 'prose',- text: 'The repo\'s `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.',- },- {- type: 'code',- lang: 'js',- label: 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',- code: `import stylexPlugin from '@stylexswc/nextjs-plugin';--export default stylexPlugin({- rsOptions: {- // Resolve @astryxdesign/core's StyleX so swizzled component source compiles.- aliases: {'@/*': ['./src/*']},- unstable_moduleResolution: {type: 'commonJS'},- },-})({- // your existing Next.js config-});`,- },- {- type: 'list',- style: 'unordered',- items: [- 'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',- 'A Babel config turns off SWC in Next.js; skip it if you need `next/font`.',- 'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',- ],- },- ],- },- {- title: 'What NOT to Do',- category: 'guide',- content: [- {- type: 'list',- style: 'dont',- items: [- 'style={{}} on raw <div> wrappers. Use xstyle on the component directly.',- 'Hardcoded colors (#fff, rgb(...)). Use var(--color-*) tokens or Tailwind semantic classes (text-primary, bg-surface).',- 'Hardcoded spacing (16px, 1rem). Use var(--spacing-*) tokens or Tailwind spacing utilities (p-4, gap-3).',- 'Wrapping a component in a <div> just to add margin. Use xstyle with stylex.create on the component.',- 'Using !important. If styles aren\'t applying, check specificity; xstyle is merged last.',- ],- },- ],- },- ],-};diff --git a/packages/cli/assets/docs/tokens.doc.dense.mjs b/packages/cli/assets/docs/tokens.doc.dense.mjsdeleted file mode 100644index 30e7e2e743..0000000000--- a/packages/cli/assets/docs/tokens.doc.dense.mjs+++ /dev/null@@ -1,15 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */--export const docsDense = {- description: 'color/data-viz/syntax/spacing/size/radius/shadow/motion/type token ref',- sections: [- { section: 'Color Tokens', title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },- { section: 'Spacing Tokens', title: 'Spacing', content: [{ type: 'prose', text: 'padding/gap/margin scale. gap props take steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.' }, null] },- { section: 'Size Tokens', title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },- { section: 'Radius Tokens', title: 'Radius', content: [null] },- { section: 'Shadow Tokens', title: 'Elevation', content: [null] },- { section: 'Usage in StyleX', title: 'StyleX Usage', content: [null, null] },- ],-};diff --git a/packages/cli/assets/docs/tokens.doc.mjs b/packages/cli/assets/docs/tokens.doc.mjsdeleted file mode 100644index d488dea2fa..0000000000--- a/packages/cli/assets/docs/tokens.doc.mjs+++ /dev/null@@ -1,1491 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--// AUTO-GENERATED — do not edit manually.-// Source: packages/core/src/theme/tokens.stylex.ts,-// dataTokens.stylex.ts, and syntax/tokens.ts-// Run: node scripts/generate-token-docs.mjs-// Total: 258 tokens across 15 categories.--/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */--export const docs = {- "name": "tokens",- "title": "All Tokens",- "category": "foundations",- "description": "Complete reference for color, data visualization, syntax, spacing, size, border, focus, radius, shadow, motion, and typography tokens.",- "keywords": [- "design tokens",- "css variables",- "custom properties"- ],- "sections": [- {- "title": "Color Tokens",- "content": [- {- "type": "prose",- "text": "Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching."- },- {- "type": "table",- "headers": [- "Token",- "Light",- "Dark"- ],- "rows": [- [- "--color-accent",- "#0064E0",- "#2694FE"- ],- [- "--color-accent-muted",- "#0082FB33",- "#0082FB3F"- ],- [- "--color-on-accent",- "#FFFFFF",- "#FFFFFF"- ],- [- "--color-neutral",- "rgba(5, 54, 89, 0.1)",- "rgba(223, 226, 229, 0.2)"- ],- [- "--color-background-surface",- "#FFFFFF",- "#1F1F22"- ],- [- "--color-background-body",- "#F1F4F7",- "#111112"- ],- [- "--color-overlay",- "#01122866",- "#11111299"- ],- [- "--color-overlay-hover",- "#0536590C",- "#FFFFFF0C"- ],- [- "--color-overlay-pressed",- "#05365919",- "#FFFFFF19"- ],- [- "--color-background-muted",- "#0536590C",- "#1111127F"- ],- [- "--color-text-primary",- "#0A1317",- "#DFE2E5"- ],- [- "--color-text-secondary",- "#4E606F",- "#AAAFB5"- ],- [- "--color-text-disabled",- "#A4B0BC",- "#6F747C"- ],- [- "--color-text-accent",- "#0064E0",- "#3E9EFB"- ],- [- "--color-on-dark",- "#FFFFFF",- "#FFFFFF"- ],- [- "--color-on-light",- "#000000",- "#000000"- ],- [- "--color-icon-accent",- "#0064E0",- "#2694FE"- ],- [- "--color-icon-primary",- "#0A1317",- "#DFE2E5"- ],- [- "--color-icon-secondary",- "#4E606F",- "#AAAFB5"- ],- [- "--color-icon-disabled",- "#A4B0BC",- "#6F747C"- ],- [- "--color-background-card",- "#FFFFFF",- "#1F1F22"- ],- [- "--color-background-popover",- "#FFFFFF",- "#28292C"- ],- [- "--color-background-inverted",- "#0A1317",- "#FFFFFF"- ],- [- "--color-background-error-inverted",- "#AA071E",- "#E3193B"- ],- [- "--color-success",- "#0D8626",- "#0D8626"- ],- [- "--color-success-muted",- "#0B991F33",- "#0B991F3F"- ],- [- "--color-on-success",- "#FFFFFF",- "#FFFFFF"- ],- [- "--color-error",- "#E3193B",- "#F5394F"- ],- [- "--color-error-muted",- "#E3193B33",- "#F5394F3F"- ],- [- "--color-on-error",- "#FFFFFF",- "#FFFFFF"- ],- [- "--color-warning",- "#E9AF08",- "#F2C00B"- ],- [- "--color-warning-muted",- "#E2A40033",- "#E2A4003F"- ],- [- "--color-on-warning",- "#0A1317",- "#0A1317"- ],- [- "--color-border",- "#05365919",- "#F2F4F619"- ],- [- "--color-border-emphasized",- "#CCD3DB",- "#494D53"- ],- [- "--color-skeleton",- "#CCD3DB",- "#5A5E66"- ],- [- "--color-track",- "#CCD3DB",- "#5A5E66"- ],- [- "--color-shadow",- "rgba(5, 54, 89, 0.1)",- "rgba(0, 0, 0, 0.3)"- ],- [- "--color-tint-hover",- "black",- "white"- ],- [- "--color-background-blue",- "#0171E333",- "#0171E333"- ],- [- "--color-border-blue",- "#0064E0",- "#2694FE"- ],- [- "--color-icon-blue",- "#0064E0",- "#2694FE"- ],- [- "--color-text-blue",- "#042F97",- "#AFD7FF"- ],- [- "--color-background-cyan",- "#03A7D733",- "#03A7D733"- ],- [- "--color-border-cyan",- "#089DD0",- "#0171A4"- ],- [- "--color-icon-cyan",- "#00ACC1",- "#26C6DA"- ],- [- "--color-text-cyan",- "#014975",- "#A1EEF9"- ],- [- "--color-background-gray",- "#0A131733",- "#666A724C"- ],- [- "--color-border-gray",- "#647685",- "#748695"- ],- [- "--color-icon-gray",- "#4E606F",- "#AAAFB5"- ],- [- "--color-text-gray",- "#0A1317",- "#E7EAED"- ],- [- "--color-background-green",- "#24BB5E33",- "#24BB5E33"- ],- [- "--color-border-green",- "#0D8626",- "#0B991F"- ],- [- "--color-icon-green",- "#0D8626",- "#26A756"- ],- [- "--color-text-green",- "#09441F",- "#A5F690"- ],- [- "--color-background-orange",- "#F2790233",- "#F2790233"- ],- [- "--color-border-orange",- "#EB6E00",- "#B34A01"- ],- [- "--color-icon-orange",- "#E9690B",- "#FB8C00"- ],- [- "--color-text-orange",- "#6B2203",- "#FDB876"- ],- [- "--color-background-pink",- "#E638B333",- "#E638B333"- ],- [- "--color-border-pink",- "#F351C0",- "#C02294"- ],- [- "--color-icon-pink",- "#C2185B",- "#EC407A"- ],- [- "--color-text-pink",- "#650053",- "#FEADE3"- ],- [- "--color-background-purple",- "#7952FF33",- "#7952FF33"- ],- [- "--color-border-purple",- "#9081FF",- "#7340FE"- ],- [- "--color-icon-purple",- "#5B08D8",- "#7952FF"- ],- [- "--color-text-purple",- "#3E0697",- "#B3B0FE"- ],- [- "--color-background-red",- "#E3193B33",- "#E3193B33"- ],- [- "--color-border-red",- "#E3193B",- "#F5394F"- ],- [- "--color-icon-red",- "#D31130",- "#E3193B"- ],- [- "--color-text-red",- "#7B0210",- "#FFB2B8"- ],- [- "--color-background-teal",- "#0DB7AF33",- "#0DB7AF33"- ],- [- "--color-border-teal",- "#08A3A3",- "#08767D"- ],- [- "--color-icon-teal",- "#009688",- "#26A69A"- ],- [- "--color-text-teal",- "#083943",- "#40DCCD"- ],- [- "--color-background-yellow",- "#E2A40033",- "#E2A40033"- ],- [- "--color-border-yellow",- "#C58600",- "#B47700"- ],- [- "--color-icon-yellow",- "#FBC02D",- "#FFEE58"- ],- [- "--color-text-yellow",- "#753F07",- "#FBCE03"- ]- ]- }- ],- "previewType": "swatch"- },- {- "title": "Data Visualization Tokens",- "content": [- {- "type": "prose",- "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import their public StyleX variables from @astryxdesign/core/theme/dataTokens.stylex."- },- {- "type": "table",- "headers": [- "Token",- "Light",- "Dark"- ],- "rows": [- [- "--color-data-categorical-blue",- "#0171E3",- "#0171E3"- ],- [- "--color-data-categorical-orange",- "#EB6E00",- "#EB6E00"- ],- [- "--color-data-categorical-purple",- "#6B1EFD",- "#6B1EFD"- ],- [- "--color-data-categorical-green",- "#0B991F",- "#0B991F"- ],- [- "--color-data-categorical-pink",- "#F351C0",- "#F351C0"- ],- [- "--color-data-categorical-cyan",- "#0171A4",- "#0171A4"- ],- [- "--color-data-categorical-red",- "#F5394F",- "#F5394F"- ],- [- "--color-data-categorical-teal",- "#08A3A3",- "#08A3A3"- ],- [- "--color-data-categorical-brown",- "#965E03",- "#965E03"- ],- [- "--color-data-categorical-indigo",- "#6F8AFF",- "#6F8AFF"- ],- [- "--color-data-neutral",- "#8494A3",- "#8C939B"- ],- [- "--color-data-blue-5",- "#02165E",- "#02165E"- ],- [- "--color-data-blue-4",- "#004CBC",- "#004CBC"- ],- [- "--color-data-blue-3",- "#2694FE",- "#2694FE"- ],- [- "--color-data-blue-2",- "#78BEFF",- "#78BEFF"- ],- [- "--color-data-blue-1",- "#DBECFF",- "#DBECFF"- ],- [- "--color-data-shamrock-5",- "#0B603D",- "#0B603D"- ],- [- "--color-data-shamrock-4",- "#138546",- "#138546"- ],- [- "--color-data-shamrock-3",- "#24BB5E",- "#24BB5E"- ],- [- "--color-data-shamrock-2",- "#8EF7AA",- "#8EF7AA"- ],- [- "--color-data-shamrock-1",- "#D6FEE4",- "#D6FEE4"- ],- [- "--color-data-orange-5",- "#A13F04",- "#A13F04"- ],- [- "--color-data-orange-4",- "#D66100",- "#D66100"- ],- [- "--color-data-orange-3",- "#FD9537",- "#FD9537"- ],- [- "--color-data-orange-2",- "#FDB876",- "#FDB876"- ],- [- "--color-data-orange-1",- "#FFE6CF",- "#FFE6CF"- ],- [- "--color-data-pink-5",- "#8E1073",- "#8E1073"- ],- [- "--color-data-pink-4",- "#D123A1",- "#D123A1"- ],- [- "--color-data-pink-3",- "#F989D3",- "#F989D3"- ],- [- "--color-data-pink-2",- "#FEADE3",- "#FEADE3"- ],- [- "--color-data-pink-1",- "#FCE3F4",- "#FCE3F4"- ],- [- "--color-data-purple-5",- "#3E0697",- "#3E0697"- ],- [- "--color-data-purple-4",- "#6B1EFD",- "#6B1EFD"- ],- [- "--color-data-purple-3",- "#9081FF",- "#9081FF"- ],- [- "--color-data-purple-2",- "#B3B0FE",- "#B3B0FE"- ],- [- "--color-data-purple-1",- "#E8E8FB",- "#E8E8FB"- ],- [- "--color-data-red-5",- "#9D0519",- "#9D0519"- ],- [- "--color-data-red-4",- "#D31130",- "#D31130"- ],- [- "--color-data-red-3",- "#FB7D87",- "#FB7D87"- ],- [- "--color-data-red-2",- "#FFB2B8",- "#FFB2B8"- ],- [- "--color-data-red-1",- "#FEE4E6",- "#FEE4E6"- ],- [- "--color-data-teal-5",- "#08767D",- "#08767D"- ],- [- "--color-data-teal-4",- "#0C9293",- "#0C9293"- ],- [- "--color-data-teal-3",- "#0DB7AF",- "#0DB7AF"- ],- [- "--color-data-teal-2",- "#6CE6D8",- "#6CE6D8"- ],- [- "--color-data-teal-1",- "#D7FCF8",- "#D7FCF8"- ],- [- "--color-data-yellow-5",- "#8A5001",- "#8A5001"- ],- [- "--color-data-yellow-4",- "#D69804",- "#D69804"- ],- [- "--color-data-yellow-3",- "#FBCE03",- "#FBCE03"- ],- [- "--color-data-yellow-2",- "#FCEC85",- "#FCEC85"- ],- [- "--color-data-yellow-1",- "#FDF6BA",- "#FDF6BA"- ],- [- "--color-data-gray-5",- "#25363F",- "#333338"- ],- [- "--color-data-gray-4",- "#5D6C7B",- "#666A72"- ],- [- "--color-data-gray-3",- "#AFB9C4",- "#B2B8BE"- ],- [- "--color-data-gray-2",- "#CCD3DB",- "#D0D3D6"- ],- [- "--color-data-gray-1",- "#F1F4F7",- "#F2F4F6"- ]- ]- }- ],- "previewType": "swatch"- },- {- "title": "Syntax Tokens",- "content": [- {- "type": "prose",- "text": "Code highlighting colors used by CodeBlock. Each defaults to a palette token, so syntax colors follow the theme; defineTheme({syntax}) sets a syntax theme instead."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--color-syntax-keyword",- "var(--color-text-accent)"- ],- [- "--color-syntax-string",- "var(--color-text-green)"- ],- [- "--color-syntax-comment",- "var(--color-text-secondary)"- ],- [- "--color-syntax-number",- "var(--color-text-orange)"- ],- [- "--color-syntax-function",- "var(--color-text-blue)"- ],- [- "--color-syntax-type",- "var(--color-text-purple)"- ],- [- "--color-syntax-variable",- "var(--color-text-primary)"- ],- [- "--color-syntax-operator",- "var(--color-text-cyan)"- ],- [- "--color-syntax-constant",- "var(--color-text-orange)"- ],- [- "--color-syntax-tag",- "var(--color-text-red)"- ],- [- "--color-syntax-attribute",- "var(--color-text-teal)"- ],- [- "--color-syntax-property",- "var(--color-text-cyan)"- ],- [- "--color-syntax-punctuation",- "var(--color-text-secondary)"- ],- [- "--color-syntax-background",- "var(--color-background-muted)"- ]- ]- }- ],- "previewType": "swatch"- },- {- "title": "Spacing Tokens",- "content": [- {- "type": "prose",- "text": "Spacing scale used for padding, gap, and margin. Component gap props map spacing steps to these tokens."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--spacing-0",- "0px"- ],- [- "--spacing-0-5",- "2px"- ],- [- "--spacing-1",- "4px"- ],- [- "--spacing-1-5",- "6px"- ],- [- "--spacing-2",- "8px"- ],- [- "--spacing-3",- "12px"- ],- [- "--spacing-4",- "16px"- ],- [- "--spacing-5",- "20px"- ],- [- "--spacing-6",- "24px"- ],- [- "--spacing-7",- "28px"- ],- [- "--spacing-8",- "32px"- ],- [- "--spacing-9",- "36px"- ],- [- "--spacing-10",- "40px"- ],- [- "--spacing-11",- "44px"- ],- [- "--spacing-12",- "48px"- ]- ]- }- ],- "previewType": "spacing-bar"- },- {- "title": "Size Tokens",- "content": [- {- "type": "prose",- "text": "Control heights for consistent sizing across buttons, inputs, and selectors."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--size-element-sm",- "28px"- ],- [- "--size-element-md",- "32px"- ],- [- "--size-element-lg",- "36px"- ]- ]- }- ],- "previewType": "size-bar"- },- {- "title": "Border Tokens",- "content": [- {- "type": "prose",- "text": "Border width for card and input borders."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--border-width",- "1px"- ]- ]- }- ],- "previewType": "border-line"- },- {- "title": "Focus Tokens",- "content": [- {- "type": "prose",- "text": "The keyboard focus ring, shared by every component that draws one. Override these to restyle focus across the system."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--focus-outline-width",- "2px"- ],- [- "--focus-outline-style",- "solid"- ],- [- "--focus-outline-color",- "var(--color-accent)"- ],- [- "--focus-outline-offset",- "3px"- ]- ]- }- ]- },- {- "title": "Radius Tokens",- "content": [- {- "type": "prose",- "text": "Numeric scale based on a 4dp base unit. Tokens scale with the theme's radius multiplier; --radius-none and --radius-full are fixed."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--radius-none",- "0px"- ],- [- "--radius-inner",- "4px"- ],- [- "--radius-element",- "8px"- ],- [- "--radius-container",- "12px"- ],- [- "--radius-page",- "28px"- ],- [- "--radius-chat",- "28px"- ],- [- "--radius-full",- "9999px"- ]- ]- }- ],- "previewType": "radius-box"- },- {- "title": "Shadow Tokens",- "content": [- {- "type": "prose",- "text": "Elevation shadows (low to med to high) and inset shadows for input state rings."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--shadow-low",- "0px 1px 1px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 8px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"- ],- [- "--shadow-med",- "0px 1px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 12px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"- ],- [- "--shadow-high",- "0px 2px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 8px 24px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.3))"- ],- [- "--shadow-inset-hover",- "inset 0px 0px 0px 2px light-dark(rgba(5, 54, 89, 0.15), rgba(223, 226, 229, 0.2))"- ],- [- "--shadow-inset-selected",- "inset 0px 0px 0px 2px rgba(1, 113, 227, 0.5)"- ],- [- "--shadow-inset-success",- "inset 0px 0px 0px 2px rgba(38, 167, 86, 0.3)"- ],- [- "--shadow-inset-warning",- "inset 0px 0px 0px 2px rgba(226, 164, 0, 0.3)"- ],- [- "--shadow-inset-error",- "inset 0px 0px 0px 2px rgba(227, 25, 59, 0.3)"- ]- ]- }- ],- "previewType": "shadow-box"- },- {- "title": "Duration Tokens",- "content": [- {- "type": "prose",- "text": "Motion duration primitives. Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous). Min/max variants derive from base × ratio."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--duration-fast-min",- "130ms"- ],- [- "--duration-fast",- "175ms"- ],- [- "--duration-fast-max",- "230ms"- ],- [- "--duration-medium-min",- "310ms"- ],- [- "--duration-medium",- "410ms"- ],- [- "--duration-medium-max",- "550ms"- ],- [- "--duration-slow-min",- "730ms"- ],- [- "--duration-slow",- "975ms"- ],- [- "--duration-slow-max",- "1300ms"- ]- ]- }- ],- "previewType": "duration-bar"- },- {- "title": "Easing Tokens",- "content": [- {- "type": "prose",- "text": "Easing curves for animations and transitions."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--ease-standard",- "cubic-bezier(0.24, 1, 0.4, 1)"- ]- ]- }- ],- "previewType": "easing-curve"- },- {- "title": "Font Family Tokens",- "content": [- {- "type": "prose",- "text": "Font family stacks for body, code, and heading text."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--font-family-body",- "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"- ],- [- "--font-family-code",- "\"SF Mono\", Monaco, Consolas, monospace"- ],- [- "--font-family-heading",- "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"- ]- ]- }- ],- "previewType": "font-sample"- },- {- "title": "Font Size Tokens",- "content": [- {- "type": "prose",- "text": "Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base)."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--font-size-4xs",- "0.375rem"- ],- [- "--font-size-3xs",- "0.4375rem"- ],- [- "--font-size-2xs",- "0.5rem"- ],- [- "--font-size-xs",- "0.625rem"- ],- [- "--font-size-sm",- "0.75rem"- ],- [- "--font-size-base",- "0.875rem"- ],- [- "--font-size-lg",- "1.0625rem"- ],- [- "--font-size-xl",- "1.25rem"- ],- [- "--font-size-2xl",- "1.5rem"- ],- [- "--font-size-3xl",- "1.8125rem"- ],- [- "--font-size-4xl",- "2.1875rem"- ],- [- "--font-size-5xl",- "2.625rem"- ]- ]- }- ],- "previewType": "font-sample"- },- {- "title": "Font Weight Tokens",- "content": [- {- "type": "prose",- "text": "Font weight values for body, emphasis, and headings."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--font-weight-normal",- "400"- ],- [- "--font-weight-medium",- "500"- ],- [- "--font-weight-semibold",- "600"- ],- [- "--font-weight-bold",- "700"- ]- ]- }- ],- "previewType": "font-sample"- },- {- "title": "Type Scale Tokens",- "content": [- {- "type": "prose",- "text": "Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme."- },- {- "type": "table",- "headers": [- "Token",- "Value"- ],- "rows": [- [- "--text-heading-1-size",- "var(--font-size-2xl)"- ],- [- "--text-heading-1-weight",- "var(--font-weight-semibold)"- ],- [- "--text-heading-1-leading",- "1.3333"- ],- [- "--text-heading-2-size",- "var(--font-size-xl)"- ],- [- "--text-heading-2-weight",- "var(--font-weight-semibold)"- ],- [- "--text-heading-2-leading",- "1.4"- ],- [- "--text-heading-3-size",- "var(--font-size-lg)"- ],- [- "--text-heading-3-weight",- "var(--font-weight-semibold)"- ],- [- "--text-heading-3-leading",- "1.4118"- ],- [- "--text-heading-4-size",- "var(--font-size-base)"- ],- [- "--text-heading-4-weight",- "var(--font-weight-semibold)"- ],- [- "--text-heading-4-leading",- "1.4286"- ],- [- "--text-heading-5-size",- "var(--font-size-sm)"- ],- [- "--text-heading-5-weight",- "var(--font-weight-semibold)"- ],- [- "--text-heading-5-leading",- "1.6667"- ],- [- "--text-heading-6-size",- "var(--font-size-xs)"- ],- [- "--text-heading-6-weight",- "var(--font-weight-semibold)"- ],- [- "--text-heading-6-leading",- "1.6"- ],- [- "--text-body-size",- "var(--font-size-base)"- ],- [- "--text-body-weight",- "var(--font-weight-normal)"- ],- [- "--text-body-leading",- "1.4286"- ],- [- "--text-large-size",- "var(--font-size-lg)"- ],- [- "--text-large-weight",- "var(--font-weight-semibold)"- ],- [- "--text-large-leading",- "1.4118"- ],- [- "--text-label-size",- "var(--font-size-base)"- ],- [- "--text-label-weight",- "var(--font-weight-medium)"- ],- [- "--text-label-leading",- "1.4286"- ],- [- "--text-code-size",- "var(--font-size-base)"- ],- [- "--text-code-weight",- "var(--font-weight-normal)"- ],- [- "--text-code-leading",- "1.4286"- ],- [- "--text-supporting-size",- "var(--font-size-sm)"- ],- [- "--text-supporting-weight",- "var(--font-weight-normal)"- ],- [- "--text-supporting-leading",- "1.6667"- ],- [- "--text-display-1-size",- "var(--font-size-5xl)"- ],- [- "--text-display-1-weight",- "var(--font-weight-normal)"- ],- [- "--text-display-1-leading",- "1.2381"- ],- [- "--text-display-2-size",- "var(--font-size-4xl)"- ],- [- "--text-display-2-weight",- "var(--font-weight-normal)"- ],- [- "--text-display-2-leading",- "1.2571"- ],- [- "--text-display-3-size",- "var(--font-size-3xl)"- ],- [- "--text-display-3-weight",- "var(--font-weight-normal)"- ],- [- "--text-display-3-leading",- "1.2414"- ]- ]- }- ],- "previewType": "font-sample"- },- {- "title": "Usage in StyleX",- "content": [- {- "type": "code",- "lang": "tsx",- "label": "Using token imports",- "code": "import * as stylex from '@stylexjs/stylex';\nimport {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';\nimport {dataVars} from '@astryxdesign/core/theme/dataTokens.stylex';\n\nconst styles = stylex.create({\n card: {\n padding: spacingVars['--spacing-4'],\n backgroundColor: colorVars['--color-background-surface'],\n borderRadius: radiusVars['--radius-container'],\n },\n series: {\n color: dataVars['--color-data-categorical-blue'],\n },\n button: {\n height: sizeVars['--size-element-md'],\n },\n});"- },- {- "type": "prose",- "text": "See {@link generic:styling} for how to apply tokens via xstyle, className, and compound component patterns. See {@link generic:author-a-theme} for overriding tokens with defineTheme."- }- ]- }- ]-};diff --git a/packages/cli/assets/docs/tokens.doc.zh.mjs b/packages/cli/assets/docs/tokens.doc.zh.mjsdeleted file mode 100644index 0d8916dc20..0000000000--- a/packages/cli/assets/docs/tokens.doc.zh.mjs+++ /dev/null@@ -1,15 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */--export const docsZh = {- description: '颜色、数据可视化、语法高亮、间距、尺寸、圆角、阴影、动效和排版设计令牌参考。',- sections: [- { section: 'Color Tokens', title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色,支持 light-dark() 自动切换模式。' }, null, null, null] },- { section: 'Spacing Tokens', title: '间距令牌', content: [{ type: 'prose', text: '用于内边距、间距和外边距的刻度。组件 gap 属性接受步长 0、0.5、1、1.5、2、3、4、5、6、8、10。' }, null] },- { section: 'Size Tokens', title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },- { section: 'Radius Tokens', title: '圆角令牌', content: [null] },- { section: 'Shadow Tokens', title: '阴影令牌', content: [null] },- { section: 'Usage in StyleX', title: 'StyleX 用法', content: [null, null] },- ],-};diff --git a/packages/cli/assets/docs/tree/component-migration.doc.mjs b/packages/cli/assets/docs/tree/component-migration.doc.mjsnew file mode 100644index 0000000000..0fa3c6ed05--- /dev/null+++ b/packages/cli/assets/docs/tree/component-migration.doc.mjs@@ -0,0 +1,107 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs migration/component-migration`: migrate the app frame,+ * map shadcn/Radix primitives, and wire up command palette, settings, and+ * theme controls.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'component-migration',+ title: 'Component Migration',+ placement: {parent: 'namespace:migration', slot: 'guides', order: 20},+ category: 'guide',+ description:+ 'Move the app frame first, map shadcn and Radix primitives to components, and wire up command palette, settings, and theme controls.',+ keywords: [+ 'Button',+ 'TextInput',+ 'CommandPalette',+ ],++ sections: [+ {+ title: 'Move the App Frame First',+ content: [+ {+ type: 'prose',+ text: 'Start with AppShell so page migration happens inside the final navigation, spacing, surface, and responsive frame. This also exposes theme and color issues early because every route shares the same shell.',+ },+ {+ type: 'table',+ headers: ['Legacy surface', 'Component', 'Notes'],+ rows: [+ ['Header', 'TopNav', 'Use for product identity, global actions, account entry, and command/search trigger.'],+ ['Sidebar', 'SideNav', 'Use sections and nested nav items for route groups. Keep selection state driven by the router.'],+ ['Main page wrapper', 'AppShell + Layout', 'Let the shell own persistent structure; let route components own page content.'],+ ['Mobile drawer nav', 'MobileNav or AppShell mobile behavior', 'Verify focus, close behavior, and route changes on narrow viewports.'],+ ['Settings menu', 'Popover + Layout + Switch', 'Use as the home for theme mode and app preferences.'],+ ],+ },+ ],+ },+ {+ title: 'Map shadcn and Radix Primitives',+ content: [+ {+ type: 'prose',+ text: 'Do not wrap old shadcn components in design system styles. Replace the primitive with the component that owns the behavior, accessibility, state classes, and token usage.',+ },+ {+ type: 'table',+ headers: ['Existing primitive', 'Component', 'Migration note'],+ rows: [+ ['button / shadcn Button', 'Button or IconButton', 'Use Button for labeled commands and IconButton for icon-only toolbar actions.'],+ ['input', 'TextInput', 'Keep validation state in status props rather than ad hoc border classes.'],+ ['textarea', 'TextArea', 'Use when multiline editing is the primary action.'],+ ['switch', 'Switch', 'Use for persisted boolean settings, including theme mode when represented as a binary choice.'],+ ['checkbox', 'CheckboxInput or CheckboxList', 'Use list variants for grouped selection.'],+ ['radio group', 'RadioList', 'Use when one option must be selected from a visible set.'],+ ['select / combobox', 'Selector or Typeahead', 'Use Selector for bounded options and Typeahead for searchable async options.'],+ ['tabs used as page nav', 'TabList', 'Use route state or current page state as the source of truth.'],+ ['command dialog', 'CommandPalette', 'Keep app-specific search sources outside the shell and feed searchable items.'],+ ['dropdown action menu', 'DropdownMenu or MoreMenu', 'Use MoreMenu for compact overflow actions.'],+ ['alert / callout', 'Banner or Toast', 'Use Banner for page or section messages and Toast for transient feedback.'],+ ['dialog', 'Dialog or AlertDialog', 'Use AlertDialog for destructive confirmation and Dialog for task flows.'],+ ['card-like list row', 'ListItem', 'Prefer ListItem for selectable rows instead of styling Button as a row.'],+ ],+ },+ ],+ },+ {+ id: 'command-palette',+ title: 'Command Palette, Settings, and Theme',+ content: [+ {+ type: 'prose',+ text: 'Move global search to CommandPalette once the shell exists. Treat the palette as a view over app commands: routes, contextual actions, create actions, filters, recent items, and entity results. Keep data normalization in app code so search sources always return arrays of searchable items.',+ },+ {+ type: 'prose',+ text: 'Put light and dark mode controls in the settings popover or account menu. The switch or selector should update the mode passed to Theme, not toggle isolated body classes.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Settings popover theme control',+ code: `function ThemeModeSwitch() {+ const {mode, setMode} = useSettings();+ const isDark = mode === 'dark';++ return (+ <Switch+ label="Dark mode"+ description="Use the dark color theme"+ value={isDark}+ onChange={next => setMode(next ? 'dark' : 'light')}+ />+ );+}`,+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/css-and-stylex.doc.mjs b/packages/cli/assets/docs/tree/css-and-stylex.doc.mjsnew file mode 100644index 0000000000..c13bc4a394--- /dev/null+++ b/packages/cli/assets/docs/tree/css-and-stylex.doc.mjs@@ -0,0 +1,150 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling-libraries/css-and-stylex`: core integration+ * principle, plain CSS / CSS Modules, and StyleX typed-token imports.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'css-and-stylex',+ title: 'CSS & StyleX',+ placement: {parent: 'namespace:styling-libraries', slot: 'guides', order: 10},+ category: 'guide',+ description:+ 'Core integration principle, plain CSS / CSS Modules, and StyleX typed-token imports.',++ sections: [+ {+ title: 'Core Principle',+ content: [+ {+ type: 'prose',+ text: 'Keep the system as the source of truth for theme values. Components read design tokens from CSS custom properties such as `--color-text-primary`, `--color-background-surface`, `--spacing-4`, and `--radius-container`. Other styling libraries should map their own semantic tokens, utility names, or theme objects to those system CSS variables whenever possible.',+ },+ {+ type: 'prose',+ text: 'Use CSS variables for ordinary DOM styling because they inherit through the tree, follow `data-theme` color mode, respect nested `data-astryx-theme` scopes, and update when themes switch. Use token resolver APIs only for non-CSS consumers such as SVG attribute values, canvas, chart configuration, color calculations, or static config generation.',+ },+ {+ type: 'prose',+ text: 'For available token names and values, run {@link namespace:tokens}. Focused references are also available with {@link generic:color}, {@link generic:spacing}, {@link generic:shape}, {@link namespace:typography}, {@link generic:elevation}, and {@link generic:motion}.',+ },+ ],+ },+ {+ title: 'Choose an Integration Path',+ content: [+ {+ type: 'prose',+ text: 'Choose the narrowest integration path that fits the styling library. Most DOM styling should stay on the CSS-variable path; JavaScript token resolution is for APIs that cannot consume CSS custom properties.',+ },+ {+ type: 'table',+ headers: ['Path', 'Use when', 'Value shape'],+ rows: [+ [+ 'CSS variable aliases',+ 'The library ultimately writes CSS and accepts string values',+ '`var(--color-text-primary)`',+ ],+ [+ 'StyleX token imports',+ 'You are writing StyleX styles in application code',+ "`colorVars['--color-text-primary']`",+ ],+ [+ 'Tailwind bridge',+ 'You want utility classes backed by active system tokens',+ '`@astryxdesign/core/tailwind-theme.css`',+ ],+ [+ 'Design token resolver APIs',+ 'JavaScript needs token values for charts, canvas, SVG, or config objects',+ "`resolveThemeToken(theme, '--color-data-categorical-blue', {mode})`",+ ],+ ],+ },+ ],+ },+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Map by semantic intent: text, surface, border, accent, status, radius, spacing, typography.',+ 'Let the system own color mode. The root Theme syncs `data-theme="light|dark"` and `data-astryx-theme` to `<html>` for portals and first-level theme scope.',+ 'Prefer CSS variables for runtime theme switching and nested themes.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Copy raw hex/px values into a second theme object when a `var(...)` reference would work.',+ 'Run a second unsynchronized dark-mode provider that disagrees with Theme.',+ 'Make another library\'s CSS variables the source of truth for the system. Some consumers need token values outside the DOM.',+ ],+ },+ ],+ },+ {+ title: 'Plain CSS and CSS Modules',+ content: [+ {+ type: 'prose',+ text: 'The simplest integration is direct CSS variable usage. CSS Modules scope class names, but system token variables are global/inherited values supplied by package CSS and the active theme.',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'Card.module.css',+ code: `.card {+ background: var(--color-background-surface);+ color: var(--color-text-primary);+ border: 1px solid var(--color-border);+ border-radius: var(--radius-container);+ padding: var(--spacing-4);+}`,+ },+ {+ type: 'prose',+ text: 'Sass variables are compile-time only. They are useful for generating static CSS, but they do not update when the system switches theme or color mode. Use native CSS custom properties for themeable values.',+ },+ ],+ },+ {+ title: 'StyleX',+ content: [+ {+ type: 'prose',+ text: 'For StyleX styles, prefer the typed token exports from `@astryxdesign/core/theme/tokens.stylex`. They provide autocomplete and catch token-name typos while still resolving through the same system CSS variables at runtime.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Typed token imports',+ code: `import * as stylex from '@stylexjs/stylex';+import {colorVars, spacingVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';++const styles = stylex.create({+ panel: {+ backgroundColor: colorVars['--color-background-surface'],+ color: colorVars['--color-text-primary'],+ padding: spacingVars['--spacing-4'],+ borderRadius: radiusVars['--radius-container'],+ },+});`,+ },+ {+ type: 'prose',+ text: 'Use `xstyle` for component overrides and `stylex.props()` for your own DOM nodes. Use `className` when integrating a non-StyleX styling library.',+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/font-setup.doc.mjs b/packages/cli/assets/docs/tree/font-setup.doc.mjsnew file mode 100644index 0000000000..c8e71f87e4--- /dev/null+++ b/packages/cli/assets/docs/tree/font-setup.doc.mjs@@ -0,0 +1,122 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs typography/font-setup`: font families, custom fonts,+ * font sizes, and font weights.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'font-setup',+ title: 'Font Setup',+ placement: {parent: 'namespace:typography', slot: 'guides', order: 10},+ category: 'foundations',+ description:+ 'Font families, custom font loading, geometric font sizes, and semantic font weights.',+ keywords: [+ 'font family',+ 'custom fonts',+ 'webfont',+ 'Google Fonts',+ 'font-face',+ 'font size',+ 'font weight',+ 'geometric scale',+ ],++ sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: '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.',+ },+ ],+ },+ {+ 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',+ },+ ],+ },+ {+ id: 'loading-custom-fonts',+ title: 'Custom fonts',+ content: [+ {+ type: 'prose',+ text: 'Astryx never loads font files. defineTheme and the built CSS only set font-family: naming a webfont (Fraunces, JetBrains Mono, and so on) makes every browser look for it, and quietly fall back when the app has not loaded it. `astryx theme build` warns when a theme names families that are neither CSS generics nor common system fonts and prints the snippet to add; loading the font is always the app\'s job.',+ },+ {+ type: 'code',+ lang: 'html',+ label: 'Google Fonts: add to your document <head>',+ code: `<link rel="preconnect" href="https://fonts.googleapis.com" />+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />+<link+ rel="stylesheet"+ href="https://fonts.googleapis.com/css2?family=Fraunces:wght@400;600;700&family=JetBrains+Mono&display=swap"+/>`,+ },+ {+ type: 'code',+ lang: 'css',+ label: 'Self-hosted: one @font-face per family and weight',+ code: `@font-face {+ font-family: 'Fraunces';+ src: url('/fonts/fraunces.woff2') format('woff2');+ font-weight: 400 700; /* variable-font range, or one weight per file */+ font-display: swap; /* fallback text stays visible while the font loads */+}`,+ },+ {+ type: 'prose',+ text: "Always pair a webfont with a real fallback stack (metric-similar system fonts plus a generic) so text stays readable before the font loads and wherever it never does: defineTheme({typography: {heading: {family: 'Fraunces', fallbacks: 'Georgia, serif'}}}).",+ },+ ],+ },+ {+ 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',+ },+ ],+ },+ {+ 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',+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/headers-and-footers.doc.mjs b/packages/cli/assets/docs/tree/headers-and-footers.doc.mjsindex 9f1b553dc3..438f70d655 100644--- a/packages/cli/assets/docs/tree/headers-and-footers.doc.mjs+++ b/packages/cli/assets/docs/tree/headers-and-footers.doc.mjs@@ -19,7 +19,6 @@ export const docs = {'LayoutHeader','LayoutFooter','Toolbar',- 'hasDivider','defaultHasDividers','pinned header','pinned footer',diff --git a/packages/cli/assets/docs/tree/i18n-library-integration.doc.mjs b/packages/cli/assets/docs/tree/i18n-library-integration.doc.mjsnew file mode 100644index 0000000000..3f26f475a5--- /dev/null+++ b/packages/cli/assets/docs/tree/i18n-library-integration.doc.mjs@@ -0,0 +1,167 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs internationalization/i18n-library-integration`: override+ * default text, coexist with your own i18n library, or use astryx as your+ * i18n library.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'i18n-library-integration',+ title: 'Library Integration',+ placement: {parent: 'namespace:internationalization', slot: 'guides', order: 20},+ category: 'guide',+ description:+ "Override astryx's default text, coexist with react-intl / i18next / next-intl / LinguiJS, or use astryx as your i18n library.",+ keywords: [+ 'react-intl',+ 'i18next',+ 'next-intl',+ 'LinguiJS',+ 'overrides',+ 'useTranslator',+ ],++ sections: [+ {+ title: "Overriding astryx's default text",+ content: [+ {+ type: 'prose',+ text: 'Use `overrides` to change individual strings without shipping a full catalog. Overrides are keyed by locale and merged on top of the built-in and user-supplied catalogs.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Change one string in English',+ code: `<InternationalizationProvider+ locale="en"+ overrides={{en: {'@astryx.pagination.next': 'Next →'}}}+>+ <App />+</InternationalizationProvider>`,+ },+ {+ type: 'prose',+ text: 'Overrides win over both bundled English and any `messages` catalog for the same key. Use them for brand voice tweaks or one-off wording changes.',+ },+ ],+ },+ {+ title: 'Using astryx with your own i18n library',+ content: [+ {+ type: 'prose',+ text: "Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use: react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.",+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Astryx + react-intl side by side',+ code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';+import {Selector} from '@astryxdesign/core/Selector';+import {Button} from '@astryxdesign/core/Button';+import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';+import astryxFr from './locales/astryx/fr.json'; // astryx's UI, in French+import appFr from './locales/app/fr.json'; // your app strings, in French++function Pricing() {+ // Consumer strings — resolved by react-intl.+ const intl = useIntl();++ return (+ <section>+ <h1><FormattedMessage id="pricing.heading" /></h1>++ {/* Astryx Selector — trigger placeholder, search-box placeholder,+ clear-button aria-label all resolved by+ <InternationalizationProvider>. Options come from react-intl. */}+ <Selector+ label={intl.formatMessage({id: 'pricing.region.label'})}+ options={[+ {value: 'na', label: intl.formatMessage({id: 'pricing.region.na'})},+ {value: 'eu', label: intl.formatMessage({id: 'pricing.region.eu'})},+ ]}+ hasSearch+ hasClear+ />++ <Button label={intl.formatMessage({id: 'pricing.cta.subscribe'})} />+ </section>+ );+}++export default function App() {+ return (+ // Same locale, two providers reading their own catalogs.+ <IntlProvider locale="fr" messages={appFr}>+ <InternationalizationProvider locale="fr" messages={{fr: astryxFr}}>+ <Pricing />+ </InternationalizationProvider>+ </IntlProvider>+ );+}`,+ },+ {+ type: 'prose',+ text: 'Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way: re-render both providers with a new `locale` prop and the whole tree updates live.',+ },+ {+ type: 'prose',+ text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029). For now, run the two providers side by side as shown above.",+ },+ ],+ },+ {+ title: 'Using astryx as your i18n library',+ content: [+ {+ type: 'prose',+ text: "For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.",+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Translate app strings with astryx',+ code: `import {Button} from '@astryxdesign/core/Button';+import {+ InternationalizationProvider,+ useTranslator,+ type Catalog,+ type MessagesByLocale,+} from '@astryxdesign/core/i18n';++const en: Catalog = {+ '@myapp.actions.save': {defaultMessage: 'Save'},+};++const fr: Catalog = {+ '@myapp.actions.save': {defaultMessage: 'Enregistrer'},+};++const messages: MessagesByLocale = {en, fr};++function SaveButton() {+ const t = useTranslator();+ return <Button label={t('@myapp.actions.save')} />;+}++export default function App() {+ return (+ <InternationalizationProvider locale="fr" messages={messages}>+ <SaveButton />+ </InternationalizationProvider>+ );+}`,+ },+ {+ type: 'prose',+ text: '`Catalog` types the rich `{defaultMessage, description?}` authoring shape. `RuntimeCatalog` types the generated key-to-message string map. `ProviderMessagesByLocale` accepts either shape for the provider, while `MessagesByLocale` keeps the original rich-only context shape.',+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/i18n-quick-start.doc.mjs b/packages/cli/assets/docs/tree/i18n-quick-start.doc.mjsnew file mode 100644index 0000000000..37aa1aa4df--- /dev/null+++ b/packages/cli/assets/docs/tree/i18n-quick-start.doc.mjs@@ -0,0 +1,101 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs internationalization/i18n-quick-start`: wrap your app in+ * a provider, load a locale catalog, and swap languages at runtime.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'i18n-quick-start',+ title: 'Quick Start',+ placement: {parent: 'namespace:internationalization', slot: 'guides', order: 10},+ category: 'guide',+ description:+ 'Wrap your app in InternationalizationProvider, load a locale catalog, and swap languages at runtime.',+ keywords: [+ 'InternationalizationProvider',+ 'quick start',+ 'language swap',+ ],++ sections: [+ {+ title: 'Quick Start',+ content: [+ {+ type: 'prose',+ text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Wrap your app',+ code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';++function App() {+ return (+ <InternationalizationProvider locale="en">+ <YourApp />+ </InternationalizationProvider>+ );+}`,+ },+ {+ type: 'prose',+ text: 'The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Load an astryx locale catalog',+ code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';++<InternationalizationProvider+ locale="fr-FR"+ messages={{'fr-FR': frFR}}>+ <App />+</InternationalizationProvider>;`,+ },+ {+ type: 'prose',+ text: 'Astryx ships English and first-party translations for supported locales. Compact runtime modules from `@astryxdesign/core/locales/*.generated.js` contain only the messages apps need; the existing `@astryxdesign/core/locales/*.json` files retain translator context. Until a locale is available, apps can pass a local catalog in either shape. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',+ },+ {+ type: 'prose',+ text: 'Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.',+ },+ ],+ },+ {+ title: 'Runtime language swap',+ content: [+ {+ type: 'prose',+ text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Toggle between locales',+ code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');++<InternationalizationProvider locale={locale} messages={{fr}}>+ <Button+ label={locale === 'en' ? 'Français' : 'English'}+ onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}+ />+ <App />+</InternationalizationProvider>;`,+ },+ {+ type: 'prose',+ text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/internationalization.doc.mjs b/packages/cli/assets/docs/tree/i18n-rtl-and-testing.doc.mjssimilarity index 51%rename from packages/cli/assets/docs/internationalization.doc.mjsrename to packages/cli/assets/docs/tree/i18n-rtl-and-testing.doc.mjsindex 2f6091dd84..7b55923254 100644--- a/packages/cli/assets/docs/internationalization.doc.mjs+++ b/packages/cli/assets/docs/tree/i18n-rtl-and-testing.doc.mjs@@ -1,95 +1,31 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/**+ * @file `astryx docs internationalization/i18n-rtl-and-testing`: text+ * direction (RTL), pseudo-locale testing, and contributor guidance.+ */+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */export const docs = {- name: 'internationalization',- title: 'Internationalization',+ type: 'generic',+ name: 'i18n-rtl-and-testing',+ title: 'RTL & Testing',+ placement: {parent: 'namespace:internationalization', slot: 'guides', order: 30},category: 'guide',description:- 'Set the active locale for astryx components, load locale catalogs, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',+ 'Text direction (RTL), pseudo-locale testing, and contributor guidance for developers and translators.',+ keywords: [+ 'dir',+ 'pseudo locale',+ 'testing',+ 'Crowdin',+ 'logical properties',+ ],sections: [- {- title: 'Quick Start',- category: 'guide',- content: [- {- type: 'prose',- text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.',- },- {- type: 'code',- lang: 'tsx',- label: 'Wrap your app',- code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';--function App() {- return (- <InternationalizationProvider locale="en">- <YourApp />- </InternationalizationProvider>- );-}`,- },- {- type: 'prose',- text: 'The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.',- },- {- type: 'code',- lang: 'tsx',- label: 'Load an astryx locale catalog',- code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';-import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';--<InternationalizationProvider- locale="fr-FR"- messages={{'fr-FR': frFR}}>- <App />-</InternationalizationProvider>;`,- },- {- type: 'prose',- text: 'Astryx ships English and first-party translations for supported locales. Compact runtime modules from `@astryxdesign/core/locales/*.generated.js` contain only the messages apps need; the existing `@astryxdesign/core/locales/*.json` files retain translator context. Until a locale is available, apps can pass a local catalog in either shape. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',- },- {- type: 'prose',- text: 'Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.',- },- ],- },- {- title: 'Runtime language swap',- category: 'guide',- content: [- {- type: 'prose',- text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',- },- {- type: 'code',- lang: 'tsx',- label: 'Toggle between locales',- code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');--<InternationalizationProvider locale={locale} messages={{fr}}>- <Button- label={locale === 'en' ? 'Français' : 'English'}- onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}- />- <App />-</InternationalizationProvider>;`,- },- {- type: 'prose',- text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",- },- ],- },{title: 'Text direction (RTL)',- category: 'guide',content: [{type: 'prose',@@ -156,149 +92,8 @@ export default function RootLayout({children, params}) {},],},- {- title: "Overriding astryx's default text",- category: 'guide',- content: [- {- type: 'prose',- text: 'Use `overrides` to change individual strings without shipping a full catalog. Overrides are keyed by locale and merged on top of the built-in and user-supplied catalogs.',- },- {- type: 'code',- lang: 'tsx',- label: 'Change one string in English',- code: `<InternationalizationProvider- locale="en"- overrides={{en: {'@astryx.pagination.next': 'Next →'}}}->- <App />-</InternationalizationProvider>`,- },- {- type: 'prose',- text: 'Overrides win over both bundled English and any `messages` catalog for the same key. Use them for brand voice tweaks or one-off wording changes.',- },- ],- },- {- title: 'Using astryx with your own i18n library',- category: 'guide',- content: [- {- type: 'prose',- text: "Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use: react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.",- },- {- type: 'code',- lang: 'tsx',- label: 'Astryx + react-intl side by side',- code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';-import {Selector} from '@astryxdesign/core/Selector';-import {Button} from '@astryxdesign/core/Button';-import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';-import astryxFr from './locales/astryx/fr.json'; // astryx's UI, in French-import appFr from './locales/app/fr.json'; // your app strings, in French--function Pricing() {- // Consumer strings — resolved by react-intl.- const intl = useIntl();-- return (- <section>- <h1><FormattedMessage id="pricing.heading" /></h1>-- {/* Astryx Selector — trigger placeholder, search-box placeholder,- clear-button aria-label all resolved by- <InternationalizationProvider>. Options come from react-intl. */}- <Selector- label={intl.formatMessage({id: 'pricing.region.label'})}- options={[- {value: 'na', label: intl.formatMessage({id: 'pricing.region.na'})},- {value: 'eu', label: intl.formatMessage({id: 'pricing.region.eu'})},- ]}- hasSearch- hasClear- />-- <Button label={intl.formatMessage({id: 'pricing.cta.subscribe'})} />- </section>- );-}--export default function App() {- return (- // Same locale, two providers reading their own catalogs.- <IntlProvider locale="fr" messages={appFr}>- <InternationalizationProvider locale="fr" messages={{fr: astryxFr}}>- <Pricing />- </InternationalizationProvider>- </IntlProvider>- );-}`,- },- {- type: 'prose',- text: 'Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way: re-render both providers with a new `locale` prop and the whole tree updates live.',- },- {- type: 'prose',- text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029). For now, run the two providers side by side as shown above.",- },- ],- },- {- title: 'Using astryx as your i18n library',- category: 'guide',- content: [- {- type: 'prose',- text: "For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.",- },- {- type: 'code',- lang: 'tsx',- label: 'Translate app strings with astryx',- code: `import {Button} from '@astryxdesign/core/Button';-import {- InternationalizationProvider,- useTranslator,- type Catalog,- type MessagesByLocale,-} from '@astryxdesign/core/i18n';--const en: Catalog = {- '@myapp.actions.save': {defaultMessage: 'Save'},-};--const fr: Catalog = {- '@myapp.actions.save': {defaultMessage: 'Enregistrer'},-};--const messages: MessagesByLocale = {en, fr};--function SaveButton() {- const t = useTranslator();- return <Button label={t('@myapp.actions.save')} />;-}--export default function App() {- return (- <InternationalizationProvider locale="fr" messages={messages}>- <SaveButton />- </InternationalizationProvider>- );-}`,- },- {- type: 'prose',- text: '`Catalog` types the rich `{defaultMessage, description?}` authoring shape. `RuntimeCatalog` types the generated key-to-message string map. `ProviderMessagesByLocale` accepts either shape for the provider, while `MessagesByLocale` keeps the original rich-only context shape.',- },- ],- },{title: 'Testing your translations',- category: 'guide',content: [{type: 'prose',@@ -319,7 +114,6 @@ import pseudo from '@astryxdesign/core/locales/pseudo.generated.js';},{title: 'For contributors',- category: 'guide',content: [{type: 'heading',diff --git a/packages/cli/assets/docs/tree/internationalization.doc.mjs b/packages/cli/assets/docs/tree/internationalization.doc.mjsnew file mode 100644index 0000000000..5eb287648f--- /dev/null+++ b/packages/cli/assets/docs/tree/internationalization.doc.mjs@@ -0,0 +1,29 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs internationalization`: the internationalization namespace.+ * Groups guides for quick-start locale setup, library integration, and+ * RTL + testing.+ */++/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */+export const docs = {+ type: 'namespace',+ name: 'internationalization',+ title: 'Internationalization',+ summary:+ 'Set the active locale, load catalogs, coexist with your own i18n library, handle RTL, and test translations.',+ keywords: [+ 'i18n',+ 'internationalization',+ 'locale',+ 'translation',+ 'RTL',+ 'right-to-left',+ 'language',+ 'catalog',+ ],+ slots: {+ guides: {title: 'Guides', accepts: {kinds: ['generic']}},+ },+};diff --git a/packages/cli/assets/docs/tree/layout.doc.mjs b/packages/cli/assets/docs/tree/layout.doc.mjsindex 13450939cb..8d6982cb35 100644--- a/packages/cli/assets/docs/tree/layout.doc.mjs+++ b/packages/cli/assets/docs/tree/layout.doc.mjs@@ -25,6 +25,9 @@ export const docs = {'AppShell','SideNav','TopNav',+ 'hasDivider',+ 'MobileNav',+ 'contentWidth',],blocks: [{diff --git a/packages/cli/assets/docs/migration.doc.mjs b/packages/cli/assets/docs/tree/migration-setup.doc.mjssimilarity index 64%rename from packages/cli/assets/docs/migration.doc.mjsrename to packages/cli/assets/docs/tree/migration-setup.doc.mjsindex c4c70d0d5b..85c5323151 100644--- a/packages/cli/assets/docs/migration.doc.mjs+++ b/packages/cli/assets/docs/tree/migration-setup.doc.mjs@@ -1,13 +1,28 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/**+ * @file `astryx docs migration/migration-setup`: theme and CSS setup,+ * cascade layer safety, layer audit, and the foundation smoke test.+ */+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */export const docs = {- name: 'migration',- title: 'Migration Guide',+ type: 'generic',+ name: 'migration-setup',+ title: 'Setup',+ placement: {parent: 'namespace:migration', slot: 'guides', order: 10},category: 'guide',description:- 'How to migrate an existing Tailwind, shadcn, or Radix application to the design system incrementally.',+ 'Install the theme, wire CSS layers, audit resets, and run the foundation smoke test before migrating any surface.',+ keywords: [+ 'setup',+ 'theme',+ 'reset',+ 'smoke test',+ 'layer audit',+ 'Tailwind coexistence',+ ],sections: [{@@ -30,15 +45,15 @@ export const docs = {type: 'list',style: 'ordered',items: [- 'Install the packages and run `astryx init` for agent docs, then add the reset, `astryx.css`, and theme CSS imports (see Theme and CSS Setup).',+ 'Install the packages and run `astryx init` for agent docs, then add the reset, `astryx.css`, and theme CSS imports (see Theme and CSS Setup below).','Wrap the app root with Theme and choose the initial light, dark, or system mode behavior.','Make Tailwind and design system CSS layer order explicit before replacing components.','Render the foundation smoke test page and confirm primitives keep their padding before migrating any surface.',- 'Move the persistent frame first: AppShell, TopNav, SideNav, page content, and mobile navigation.',- 'Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, TabList, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.',+ 'Move the persistent frame first: AppShell, TopNav, SideNav, page content, and mobile navigation. See {@link generic:component-migration}.',+ 'Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, TabList, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem. See {@link generic:component-migration}.','Replace global workflows: command palette, settings popover, theme toggle, search, filters, create flows, and destructive confirmation dialogs.','Remove legacy Tailwind classes from each completed surface, keeping only token-backed layout utilities or local wrappers that still need to be migrated.',- 'Verify both light and dark modes, keyboard navigation, responsive layout, and empty/error/loading states before moving to the next route.',+ 'Verify both light and dark modes, keyboard navigation, responsive layout, and empty/error/loading states before moving to the next route. See {@link generic:migration-verification}.',],},],@@ -110,7 +125,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {},{type: 'prose',- text: 'When Tailwind remains in the app, declare layer order once in the global CSS file. Load the Astryx reset and theme CSS before Tailwind utilities so migrated components keep design system defaults while legacy utility classes still work. On Tailwind v4, use the imports and layer order in the Tailwind section of {@link generic:styling-libraries}.',+ text: 'When Tailwind remains in the app, declare layer order once in the global CSS file. Load the Astryx reset and theme CSS before Tailwind utilities so migrated components keep design system defaults while legacy utility classes still work. On Tailwind v4, use the imports and layer order in {@link generic:tailwind}.',},{type: 'prose',@@ -155,7 +170,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {},{type: 'prose',- text: 'Before building screens, check every stylesheet against Cascade layer audit.',+ text: 'Before building screens, check every stylesheet against the cascade layer audit below.',},],},@@ -258,125 +273,5 @@ if (getComputedStyle(button).paddingInline === '0px') {},],},- {- title: 'Move the App Frame First',- content: [- {- type: 'prose',- text: 'Start with AppShell so page migration happens inside the final navigation, spacing, surface, and responsive frame. This also exposes theme and color issues early because every route shares the same shell.',- },- {- type: 'table',- headers: ['Legacy surface', 'Component', 'Notes'],- rows: [- ['Header', 'TopNav', 'Use for product identity, global actions, account entry, and command/search trigger.'],- ['Sidebar', 'SideNav', 'Use sections and nested nav items for route groups. Keep selection state driven by the router.'],- ['Main page wrapper', 'AppShell + Layout', 'Let the shell own persistent structure; let route components own page content.'],- ['Mobile drawer nav', 'MobileNav or AppShell mobile behavior', 'Verify focus, close behavior, and route changes on narrow viewports.'],- ['Settings menu', 'Popover + Layout + Switch', 'Use as the home for theme mode and app preferences.'],- ],- },- ],- },- {- title: 'Map shadcn and Radix Primitives',- content: [- {- type: 'prose',- text: 'Do not wrap old shadcn components in design system styles. Replace the primitive with the component that owns the behavior, accessibility, state classes, and token usage.',- },- {- type: 'table',- headers: ['Existing primitive', 'Component', 'Migration note'],- rows: [- ['button / shadcn Button', 'Button or IconButton', 'Use Button for labeled commands and IconButton for icon-only toolbar actions.'],- ['input', 'TextInput', 'Keep validation state in status props rather than ad hoc border classes.'],- ['textarea', 'TextArea', 'Use when multiline editing is the primary action.'],- ['switch', 'Switch', 'Use for persisted boolean settings, including theme mode when represented as a binary choice.'],- ['checkbox', 'CheckboxInput or CheckboxList', 'Use list variants for grouped selection.'],- ['radio group', 'RadioList', 'Use when one option must be selected from a visible set.'],- ['select / combobox', 'Selector or Typeahead', 'Use Selector for bounded options and Typeahead for searchable async options.'],- ['tabs used as page nav', 'TabList', 'Use route state or current page state as the source of truth.'],- ['command dialog', 'CommandPalette', 'Keep app-specific search sources outside the shell and feed searchable items.'],- ['dropdown action menu', 'DropdownMenu or MoreMenu', 'Use MoreMenu for compact overflow actions.'],- ['alert / callout', 'Banner or Toast', 'Use Banner for page or section messages and Toast for transient feedback.'],- ['dialog', 'Dialog or AlertDialog', 'Use AlertDialog for destructive confirmation and Dialog for task flows.'],- ['card-like list row', 'ListItem', 'Prefer ListItem for selectable rows instead of styling Button as a row.'],- ],- },- ],- },- {- id: 'command-palette',- title: 'Command Palette, Settings, and Theme',- content: [- {- type: 'prose',- text: 'Move global search to CommandPalette once the shell exists. Treat the palette as a view over app commands: routes, contextual actions, create actions, filters, recent items, and entity results. Keep data normalization in app code so search sources always return arrays of searchable items.',- },- {- type: 'prose',- text: 'Put light and dark mode controls in the settings popover or account menu. The switch or selector should update the mode passed to Theme, not toggle isolated body classes.',- },- {- type: 'code',- lang: 'tsx',- label: 'Settings popover theme control',- code: `function ThemeModeSwitch() {- const {mode, setMode} = useSettings();- const isDark = mode === 'dark';-- return (- <Switch- label="Dark mode"- description="Use the dark color theme"- value={isDark}- onChange={next => setMode(next ? 'dark' : 'light')}- />- );-}`,- },- ],- },- {- title: 'Verification Checklist',- content: [- {- type: 'list',- style: 'unordered',- items: [- 'Run the app in light and dark mode and check that surfaces, borders, text, icons, hover states, focus rings, and status colors flow together.',- 'Open the command palette from the shell, type into it, select items by keyboard, and confirm focus returns to the trigger.',- 'Check the SideNav at collapsed, expanded, active, hover, nested, and mobile states.',- 'Verify settings popovers and dialogs in jsdom and in a real browser because the native dialog and [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) APIs may need test shims.',- 'Search for leftover hardcoded Tailwind colors, arbitrary hex values, and one-off hover colors after each route migration.',- 'Run component tests, build, and at least one browser screenshot pass for each migrated route.',- ],- },- ],- },- {- title: 'AI Migration Prompt',- content: [- {- type: 'prose',- text: 'When using an AI coding agent, give it an explicit migration loop instead of asking for a full-app rewrite.',- },- {- type: 'code',- lang: 'text',- label: 'Paste this into your AI',- code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.--First run:-- astryx docs migration --dense-- astryx docs theme --dense-- astryx docs styling --dense-- astryx template AppShellTopNavWithSideNav --skeleton--Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,- },- ],- },],};diff --git a/packages/cli/assets/docs/tree/migration-verification.doc.mjs b/packages/cli/assets/docs/tree/migration-verification.doc.mjsnew file mode 100644index 0000000000..2400a45267--- /dev/null+++ b/packages/cli/assets/docs/tree/migration-verification.doc.mjs@@ -0,0 +1,67 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs migration/migration-verification`: post-migration+ * verification checklist and AI migration prompt.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'migration-verification',+ title: 'Verification',+ placement: {parent: 'namespace:migration', slot: 'guides', order: 30},+ category: 'guide',+ description:+ 'Post-migration verification checklist and an AI migration prompt to paste into your coding tool.',+ keywords: [+ 'verification',+ 'checklist',+ 'AI prompt',+ 'keyboard navigation',+ ],++ sections: [+ {+ title: 'Verification Checklist',+ content: [+ {+ type: 'list',+ style: 'unordered',+ items: [+ 'Run the app in light and dark mode and check that surfaces, borders, text, icons, hover states, focus rings, and status colors flow together.',+ 'Open the command palette from the shell, type into it, select items by keyboard, and confirm focus returns to the trigger.',+ 'Check the SideNav at collapsed, expanded, active, hover, nested, and mobile states.',+ 'Verify settings popovers and dialogs in jsdom and in a real browser because the native dialog and [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) APIs may need test shims.',+ 'Search for leftover hardcoded Tailwind colors, arbitrary hex values, and one-off hover colors after each route migration.',+ 'Run component tests, build, and at least one browser screenshot pass for each migrated route.',+ ],+ },+ ],+ },+ {+ title: 'AI Migration Prompt',+ content: [+ {+ type: 'prose',+ text: 'When using an AI coding agent, give it an explicit migration loop instead of asking for a full-app rewrite.',+ },+ {+ type: 'code',+ lang: 'text',+ label: 'Paste this into your AI',+ code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.++First run:+- astryx docs migration --dense+- astryx docs theme --dense+- astryx docs styling --dense+- astryx template AppShellTopNavWithSideNav --skeleton++Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/migration.doc.mjs b/packages/cli/assets/docs/tree/migration.doc.mjsnew file mode 100644index 0000000000..7c04058870--- /dev/null+++ b/packages/cli/assets/docs/tree/migration.doc.mjs@@ -0,0 +1,28 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs migration`: the migration namespace. Groups the+ * incremental migration guides: setup (theme, CSS, layers), component+ * replacement, and verification.+ */++/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */+export const docs = {+ type: 'namespace',+ name: 'migration',+ title: 'Migration Guide',+ summary:+ 'Migrate an existing Tailwind, shadcn, or Radix app to the design system incrementally — setup, component replacement, and verification.',+ keywords: [+ 'migration',+ 'migrate',+ 'Tailwind',+ 'shadcn',+ 'Radix',+ 'cascade layers',+ 'coexistence',+ ],+ slots: {+ guides: {title: 'Guides', accepts: {kinds: ['generic']}},+ },+};diff --git a/packages/cli/assets/docs/tree/non-css-processing.doc.mjs b/packages/cli/assets/docs/tree/non-css-processing.doc.mjsnew file mode 100644index 0000000000..e429b7d86b--- /dev/null+++ b/packages/cli/assets/docs/tree/non-css-processing.doc.mjs@@ -0,0 +1,112 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling-libraries/non-css-processing`: resolve token+ * values outside the DOM for charts, canvas, SVG, and config objects.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'non-css-processing',+ title: 'Non-CSS Processing',+ placement: {parent: 'namespace:styling-libraries', slot: 'guides', order: 40},+ category: 'guide',+ description:+ 'Resolve token values outside the DOM for charts, canvas, SVG, and config objects using resolveThemeTokens() and useTheme().',+ keywords: [+ 'resolveThemeTokens',+ 'resolveThemeToken',+ 'useTheme',+ 'chart',+ 'canvas',+ 'SVG',+ 'non-CSS',+ ],++ sections: [+ {+ title: 'Non-CSS Processing',+ content: [+ {+ type: 'prose',+ text: 'Use `resolveThemeTokens()` or `resolveThemeToken()` when code outside React needs token values for a known theme and mode. Use `useTheme()` inside client components when the values should come from the nearest Theme and active mode.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'Resolve tokens without React context',+ code: `import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';+import {neutralTheme} from '@astryxdesign/theme-neutral/built';++const tokens = resolveThemeTokens(neutralTheme, {mode: 'light'});++const chartOptions = {+ textColor: tokens['--color-text-primary'],+ mutedTextColor: tokens['--color-text-secondary'],+ gridColor: tokens['--color-border'],+ seriesColors: [+ tokens['--color-data-categorical-blue'],+ tokens['--color-data-categorical-orange'],+ tokens['--color-data-categorical-purple'],+ ],+};`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Resolve tokens from the nearest Theme',+ code: `'use client';++import {useMemo} from 'react';+import {useTheme} from '@astryxdesign/core/theme';++function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {+ const {mode, tokens} = useTheme();++ const chartOptions = useMemo(+ () => ({+ mode,+ textColor: tokens['--color-text-primary'],+ mutedTextColor: tokens['--color-text-secondary'],+ gridColor: tokens['--color-border'],+ seriesColors: [+ tokens['--color-data-categorical-blue'],+ tokens['--color-data-categorical-orange'],+ tokens['--color-data-categorical-purple'],+ ],+ }),+ [mode, tokens],+ );++ return <ThirdPartyChart data={data} options={chartOptions} />;+}`,+ },+ ],+ },+ {+ id: 'non-css-best-practices',+ title: 'Non-CSS Processing Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use the returned `tokens` object as a memo dependency; it is stable until the active theme or mode changes.',+ 'Use data visualization tokens such as `--color-data-categorical-blue` for chart series instead of reusing arbitrary UI colors.',+ 'Prefer CSS variables for SVG elements when possible (`fill="var(--color-accent)"`); use token resolver APIs when an API requires a string value in JavaScript.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Use token resolver APIs for ordinary DOM styling. Use CSS variables, StyleX tokens, xstyle, or library aliases instead.',+ 'Assume the returned values reflect every CSS cascade override. They resolve tokens for the current theme and mode; local media-surface overrides and arbitrary CSS overrides may not be represented in the returned map.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/other-libraries.doc.mjs b/packages/cli/assets/docs/tree/other-libraries.doc.mjsnew file mode 100644index 0000000000..6db25ce5c0--- /dev/null+++ b/packages/cli/assets/docs/tree/other-libraries.doc.mjs@@ -0,0 +1,218 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling-libraries/other-libraries`: Panda, Chakra, MUI,+ * Emotion, styled-components, UnoCSS, and the interop checklist.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'other-libraries',+ title: 'Other Libraries',+ placement: {parent: 'namespace:styling-libraries', slot: 'guides', order: 30},+ category: 'guide',+ description:+ 'Panda, Chakra, MUI, Emotion, styled-components, Theme UI, UnoCSS, and the interop checklist.',+ keywords: [+ 'UnoCSS',+ 'semantic tokens',+ 'palette',+ ],++ sections: [+ {+ id: 'semantic-token-systems',+ title: 'Panda, Chakra, and Other Semantic Token Systems',+ content: [+ {+ type: 'prose',+ text: 'Libraries like Panda CSS and Chakra UI have first-class semantic token objects. Put system CSS variables at the leaves of those objects so product code can use the library\'s semantic names while the system still owns the values.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'Semantic token aliases',+ code: `semanticTokens: {+ colors: {+ text: {+ primary: {value: 'var(--color-text-primary)'},+ secondary: {value: 'var(--color-text-secondary)'},+ },+ background: {+ surface: {value: 'var(--color-background-surface)'},+ body: {value: 'var(--color-background-body)'},+ },+ border: {+ default: {value: 'var(--color-border)'},+ },+ },+},+tokens: {+ spacing: {+ 4: {value: 'var(--spacing-4)'},+ },+ radii: {+ container: {value: 'var(--radius-container)'},+ },+}`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Panda-style usage',+ code: `<section+ className={css({+ bg: 'background.surface',+ color: 'text.primary',+ borderColor: 'border.default',+ p: '4',+ rounded: 'container',+ })}+/>`,+ },+ {+ type: 'prose',+ text: 'If a semantic-token library needs to generate its own light/dark CSS from raw values, align its mode selector with Theme (`data-theme="light|dark"`) and generate that adapter from system theme data. Otherwise it can drift from nested or runtime themes.',+ },+ ],+ },+ {+ title: 'MUI and Palette-Based Themes',+ content: [+ {+ type: 'prose',+ text: '`MUI` expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'MUI palette mapped to system vars',+ code: `const theme = createTheme({+ cssVariables: true,+ colorSchemes: {+ light: {+ palette: {+ primary: {main: 'var(--color-accent)'},+ background: {+ default: 'var(--color-background-body)',+ paper: 'var(--color-background-surface)',+ },+ text: {+ primary: 'var(--color-text-primary)',+ secondary: 'var(--color-text-secondary)',+ },+ divider: 'var(--color-border)',+ },+ },+ dark: {+ palette: {+ primary: {main: 'var(--color-accent)'},+ background: {+ default: 'var(--color-background-body)',+ paper: 'var(--color-background-surface)',+ },+ text: {+ primary: 'var(--color-text-primary)',+ secondary: 'var(--color-text-secondary)',+ },+ divider: 'var(--color-border)',+ },+ },+ },+});`,+ },+ {+ type: 'prose',+ text: 'If MUI owns color mode in an app, generate the light and dark palette values from system theme data and keep Theme mode synchronized. If Theme owns color mode, keep both MUI schemes pointing at the same system CSS variables.',+ },+ ],+ },+ {+ id: 'css-in-js',+ title: 'Emotion, styled-components, Theme UI, and Styled System',+ content: [+ {+ type: 'prose',+ text: 'Runtime CSS-in-JS libraries such as `Emotion` and `styled-components` usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'Generic CSS-in-JS theme object',+ code: `const appTheme = {+ colors: {+ textPrimary: 'var(--color-text-primary)',+ textSecondary: 'var(--color-text-secondary)',+ surface: 'var(--color-background-surface)',+ border: 'var(--color-border)',+ accent: 'var(--color-accent)',+ },+ spacing: {+ 4: 'var(--spacing-4)',+ },+ radius: {+ container: 'var(--radius-container)',+ },+};`,+ },+ {+ type: 'prose',+ text: 'Avoid rebuilding CSS-in-JS theme objects with raw color values on every mode switch. CSS variables let the class names stay the same while the browser resolves the active values.',+ },+ ],+ },+ {+ id: 'unocss',+ title: 'UnoCSS and Custom Utility Systems',+ content: [+ {+ type: 'prose',+ text: 'Utility generators such as UnoCSS can put system variables in their theme config or shortcuts. Keep classes semantic (`bg-surface`, `text-primary`) and let the values point at system tokens.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'UnoCSS-style config',+ code: `export default defineConfig({+ theme: {+ colors: {+ surface: 'var(--color-background-surface)',+ primary: 'var(--color-text-primary)',+ border: 'var(--color-border)',+ accent: 'var(--color-accent)',+ },+ spacing: {+ 4: 'var(--spacing-4)',+ },+ },+ shortcuts: {+ 'astryx-card': 'bg-surface text-primary border border-border rounded-lg p-4',+ },+});`,+ },+ {+ type: 'prose',+ text: 'Static utility extractors cannot see dynamically constructed class names. Prefer explicit class strings or the library\'s safelist/source-registration mechanism.',+ },+ ],+ },+ {+ title: 'Interop Checklist',+ content: [+ {+ type: 'list',+ style: 'ordered',+ items: [+ 'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `astryx theme build` or published `/built` theme imports plus `theme.css`.',+ 'Choose one owner for color mode. Theme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.',+ 'Map the external library\'s semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.',+ 'Use {@link namespace:tokens} and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',+ 'Use token resolver APIs only for non-CSS APIs that need resolved values.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/responsive.doc.mjs b/packages/cli/assets/docs/tree/responsive.doc.mjsindex 8f0ef9be81..16eba48764 100644--- a/packages/cli/assets/docs/tree/responsive.doc.mjs+++ b/packages/cli/assets/docs/tree/responsive.doc.mjs@@ -16,14 +16,10 @@ export const docs = {description:'Decide what each region does as width changes: divide, reveal, resize, or swap.',keywords: [- 'responsive','breakpoints','useMediaQuery',- 'mobileNav',- 'MobileNav','Dialog','BottomSheet',- 'contentWidth','contract',],diff --git a/packages/cli/assets/docs/tree/scaffold.doc.mjs b/packages/cli/assets/docs/tree/scaffold.doc.mjsindex 75a2a3d192..6feb9661fa 100644--- a/packages/cli/assets/docs/tree/scaffold.doc.mjs+++ b/packages/cli/assets/docs/tree/scaffold.doc.mjs@@ -18,14 +18,9 @@ export const docs = {keywords: ['shell','navigation',- 'AppShell',- 'SideNav',- 'TopNav',- 'MobileNav','frame','region','width budget',- 'contentWidth',],sections: [diff --git a/packages/cli/assets/docs/tree/side-panels.doc.mjs b/packages/cli/assets/docs/tree/side-panels.doc.mjsindex 2c7bb65550..4aa4d79b51 100644--- a/packages/cli/assets/docs/tree/side-panels.doc.mjs+++ b/packages/cli/assets/docs/tree/side-panels.doc.mjs@@ -22,7 +22,6 @@ export const docs = {'ResizeHandle','useResizable','EmptyState',- 'hasDivider','isScrollable','detail panel','split view',diff --git a/packages/cli/assets/docs/tree/structure.doc.mjs b/packages/cli/assets/docs/tree/structure.doc.mjsindex c962e5a07c..fa63abbeba 100644--- a/packages/cli/assets/docs/tree/structure.doc.mjs+++ b/packages/cli/assets/docs/tree/structure.doc.mjs@@ -23,10 +23,6 @@ export const docs = {'List','containers','rows',- 'Heading',- 'Text',- 'weight',- 'color','secondary','Divider',],diff --git a/packages/cli/assets/docs/tree/styling-advanced.doc.mjs b/packages/cli/assets/docs/tree/styling-advanced.doc.mjsnew file mode 100644index 0000000000..7f8c91c3aa--- /dev/null+++ b/packages/cli/assets/docs/tree/styling-advanced.doc.mjs@@ -0,0 +1,159 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling/styling-advanced`: compound component styling,+ * data-attribute selectors, deprecated bare classes, and what not to do.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'styling-advanced',+ title: 'Advanced',+ placement: {parent: 'namespace:styling', slot: 'guides', order: 20},+ category: 'guide',+ description:+ 'Compound component styling, data-attribute selectors, deprecated bare prop/state classes, and common anti-patterns.',+ keywords: [+ 'compound',+ 'data attributes',+ 'deprecated',+ 'selector',+ 'astryx-button',+ 'data-variant',+ ],++ sections: [+ {+ title: 'Compound Components',+ content: [+ {+ type: 'prose',+ text: 'Complex components are composed from smaller components. Each sub-component accepts its own xstyle, className, and rest props. You style the parts individually; there\'s no single "drill into sub-part" prop.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Dialog with individually styled parts',+ code: `import * as stylex from '@stylexjs/stylex';++const overrides = stylex.create({+ dialog: { maxWidth: 500 },+ content: { gap: 'var(--spacing-4)' },+});++<Dialog isOpen={isOpen} onOpenChange={close} xstyle={overrides.dialog}>+ <Layout+ header={+ <LayoutHeader hasDivider>+ <Heading level={2}>Edit Profile</Heading>+ </LayoutHeader>+ }+ content={+ <LayoutContent xstyle={overrides.content}>+ <TextInput label="Name" value={name} onChange={setName} />+ </LayoutContent>+ }+ footer={+ <LayoutFooter hasDivider>+ <Button label="Cancel" variant="secondary" onClick={close} />+ <Button label="Save" variant="primary" onClick={save} />+ </LayoutFooter>+ }+ />+</Dialog>`,+ },+ {+ type: 'prose',+ text: 'The pattern: the parent component (Dialog) controls structure and behavior, child components (Layout, Header, Button) control their own appearance. Style each piece where it lives.',+ },+ ],+ },+ {+ id: 'preferred-selector-surface-data-attributes',+ title: 'Data attribute selectors',+ content: [+ {+ type: 'prose',+ text: 'When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',+ },+ {+ type: 'code',+ lang: 'css',+ code: `.my-app .astryx-button[data-variant="primary"] {+ /* primary buttons in this app context */+}++.my-app .astryx-button[data-variant="primary"][data-size="sm"] {+ /* small primary buttons */+}++.my-app .astryx-heading[data-level="2"] {+ /* level 2 headings; numeric values stay literal in data attrs */+}`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'What components reflect',+ code: `// <Button variant="primary" size="sm" />+// preferred selector attrs: data-variant="primary" data-size="sm"++// <Card variant="elevated" />+// preferred selector attrs: data-variant="elevated"++// <Heading level={2} />+// preferred selector attrs: data-level="2"`,+ },+ {+ type: 'prose',+ text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run {@link generic:author-a-theme} for component theming.',+ },+ ],+ },+ {+ id: 'deprecated-classes',+ title: 'Deprecated: Bare Prop and State Classes',+ content: [+ {+ type: 'prose',+ text: 'Astryx still emits the deprecated bare classes (`.primary`, `.sm`, `.level-2`, `.checked`) and will remove them in a later release. Use data attributes for new CSS; `astryx upgrade --from <old version> --apply` rewrites qualified selectors in `.css` files.',+ },+ {+ type: 'code',+ lang: 'css',+ code: `/* The upgrade preserves old consumer classes and adds the v0.6 prop match */+.my-app .astryx-button:is(.primary, [data-variant="primary"]) {+ /* primary buttons or a consumer-supplied .primary class */+}++/* Numeric values stay literal in data attributes */+.my-app .astryx-heading:is(.level-2, [data-level="2"]) {+ /* level 2 headings or a consumer-supplied .level-2 class */+}`,+ },+ {+ type: 'prose',+ text: 'The upgrade rewrites a selector only when an `.astryx-*` component class qualifies it, turning the old class into an `:is(...)` union of that class and the data attributes it stood for. The union keeps the selector\'s specificity and your own `className` matches, and keeps matching once the bare classes are gone; the `.astryx-*` classes themselves stay. It leaves unqualified classes (a bare `.primary`), unknown classes, and selectors in JavaScript or TypeScript alone: migrate those by hand, and only where they target Astryx.',+ },+ ],+ },+ {+ title: 'What NOT to Do',+ content: [+ {+ type: 'list',+ style: 'dont',+ items: [+ 'style={{}} on raw <div> wrappers. Use xstyle on the component directly.',+ 'Hardcoded colors (#fff, rgb(...)). Use var(--color-*) tokens or Tailwind semantic classes (text-primary, bg-surface).',+ 'Hardcoded spacing (16px, 1rem). Use var(--spacing-*) tokens or Tailwind spacing utilities (p-4, gap-3).',+ 'Wrapping a component in a <div> just to add margin. Use xstyle with stylex.create on the component.',+ 'Using !important. If styles aren\'t applying, check specificity; xstyle is merged last.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/styling-basics.doc.mjs b/packages/cli/assets/docs/tree/styling-basics.doc.mjsnew file mode 100644index 0000000000..4844f2591c--- /dev/null+++ b/packages/cli/assets/docs/tree/styling-basics.doc.mjs@@ -0,0 +1,181 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling/styling-basics`: overview of styling approaches,+ * xstyle prop, Tailwind integration, className/style props, and rest props.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'styling-basics',+ title: 'Basics',+ placement: {parent: 'namespace:styling', slot: 'guides', order: 10},+ category: 'guide',+ description:+ 'Overview of styling approaches, xstyle prop, Tailwind integration, className/style props, and rest props.',+ keywords: [+ 'style',+ 'rest props',+ 'data-testid',+ 'ref',+ ],++ sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'Style components with `xstyle` (StyleX), `className` (Tailwind or your own CSS), or a styling library aliased to Astryx tokens. All of them resolve to the same tokens.',+ },+ {+ type: 'table',+ headers: ['Approach', 'Use for', 'Example'],+ rows: [+ ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', '`const styles = stylex.create(...); <Button xstyle={styles.save} />`'],+ ['Tailwind utilities', 'Page layout, wrappers, and utility styling', '`className="flex gap-3 p-4"`'],+ ['className', 'Integrating with external CSS or Tailwind on components', '`className="my-card shadow-lg"`'],+ ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "`colors.surface = 'var(--color-background-surface)'`"],+ ],+ },+ {+ type: 'prose',+ text: 'Theming and dark mode work whichever you choose. For external styling libraries, see {@link namespace:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',+ },+ ],+ },+ {+ title: 'xstyle Prop',+ content: [+ {+ type: 'prose',+ text: 'Every component accepts an `xstyle` prop for style customization. It accepts StyleX styles created via `stylex.create()`, not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Simple overrides',+ code: `import * as stylex from '@stylexjs/stylex';++const overrides = stylex.create({+ card: { maxWidth: 400, marginBlock: 16 },+ saveButton: { alignSelf: 'flex-end' },+});++<Card xstyle={overrides.card} />+<Button label="Save" xstyle={overrides.saveButton} />`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Pseudo-classes and conditional styles',+ code: `import * as stylex from '@stylexjs/stylex';++const overrides = stylex.create({+ card: {+ boxShadow: {+ default: 'none',+ ':hover': { '@media (hover: hover)': '0 4px 12px rgba(0,0,0,0.1)' },+ },+ },+});++<Card xstyle={overrides.card}>...</Card>`,+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ 'All xstyle values must come from stylex.create()',+ 'Pseudo-classes (:hover, :focus-visible) are supported inside stylex.create',+ 'All :hover styles MUST use @media (hover: hover) guard',+ 'For non-StyleX styling (Tailwind, external CSS), use className instead',+ ],+ },+ ],+ },+ {+ title: 'Tailwind Integration',+ content: [+ {+ type: 'prose',+ text: 'The package ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.',+ },+ {+ type: 'prose',+ text: 'For the imports and the cascade-layer order to put in your global CSS, see {@link generic:tailwind}.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Tailwind utilities alongside components',+ code: `<div className="text-primary bg-surface rounded-lg p-4 flex gap-3">+ <Button label="Save" variant="primary" />+ <Button label="Cancel" variant="secondary" />+</div>`,+ },+ {+ type: 'prose',+ text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, see {@link namespace:styling-libraries}.',+ },+ ],+ },+ {+ title: 'className and style Props',+ content: [+ {+ type: 'prose',+ text: 'Every component also accepts standard `className` and `style` props. `className` is appended after the component\'s own classes. `style` is merged after StyleX inline styles, so consumer values win on conflict.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'className with Tailwind utilities',+ code: `<Card className="shadow-lg hover:shadow-xl transition-shadow">+ ...+</Card>+<Button label="Save" className="my-app-save-btn" />`,+ },+ {+ type: 'prose',+ text: 'For layout and wrapper styling, Tailwind utilities on className work well. For component-specific overrides (padding, colors, borders), prefer xstyle; it integrates with StyleX deduplication and the component\'s internal style pipeline.',+ },+ ],+ },+ {+ title: 'Rest Props (Prop Drilling)',+ content: [+ {+ type: 'prose',+ text: 'Components extend HTML attributes and spread rest props onto their root DOM element. This means data-* attributes, aria-* attributes, event handlers, and other HTML props pass through automatically.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Data attributes, event handlers, and ARIA',+ code: `<Card+ data-testid="user-card"+ data-user-id={user.id}+ onMouseEnter={handleHover}+ aria-label="User profile card"+>+ ...+</Card>`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Ref forwarding',+ code: `const cardRef = useRef<HTMLDivElement>(null);+<Card ref={cardRef}>...</Card>`,+ },+ {+ type: 'prose',+ text: 'A few HTML attributes are intentionally omitted from the base type (contentEditable, dangerouslySetInnerHTML). children is not in the base type either; components that accept children declare it explicitly, so slot-based components don\'t silently drop JSX children.',+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/styling-libraries.doc.mjs b/packages/cli/assets/docs/tree/styling-libraries.doc.mjsnew file mode 100644index 0000000000..4c5a733bd3--- /dev/null+++ b/packages/cli/assets/docs/tree/styling-libraries.doc.mjs@@ -0,0 +1,30 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling-libraries`: the styling-libraries namespace.+ * Groups guides for CSS/StyleX, Tailwind, other semantic-token libraries,+ * and non-CSS token processing.+ */++/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */+export const docs = {+ type: 'namespace',+ name: 'styling-libraries',+ title: 'Styling Library Interop',+ summary:+ 'Integrate Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, and non-CSS renderers with system tokens.',+ keywords: [+ 'Tailwind',+ 'StyleX',+ 'Panda',+ 'Chakra',+ 'MUI',+ 'Emotion',+ 'styled-components',+ 'CSS Modules',+ 'interop',+ ],+ slots: {+ guides: {title: 'Guides', accepts: {kinds: ['generic']}},+ },+};diff --git a/packages/cli/assets/docs/tree/styling.doc.mjs b/packages/cli/assets/docs/tree/styling.doc.mjsnew file mode 100644index 0000000000..984e69e662--- /dev/null+++ b/packages/cli/assets/docs/tree/styling.doc.mjs@@ -0,0 +1,29 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling`: the styling namespace. Groups guides for+ * styling basics (xstyle, className, rest props), advanced patterns+ * (compounds, data attrs, deprecated), and tokens + StyleX setup.+ */++/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */+export const docs = {+ type: 'namespace',+ name: 'styling',+ title: 'Styling Components',+ summary:+ 'Customize component appearance: xstyle, Tailwind, className, rest props, compound components, data attribute selectors, tokens, and StyleX setup.',+ keywords: [+ 'styling',+ 'xstyle',+ 'className',+ 'override',+ 'customize',+ 'css',+ 'StyleX',+ 'tokens',+ ],+ slots: {+ guides: {title: 'Guides', accepts: {kinds: ['generic']}},+ },+};diff --git a/packages/cli/assets/docs/tree/tailwind.doc.mjs b/packages/cli/assets/docs/tree/tailwind.doc.mjsnew file mode 100644index 0000000000..33d7ea3d47--- /dev/null+++ b/packages/cli/assets/docs/tree/tailwind.doc.mjs@@ -0,0 +1,65 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling-libraries/tailwind`: the Tailwind v4 bridge,+ * cascade layer order, and utility-class usage backed by system tokens.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'tailwind',+ title: 'Tailwind',+ placement: {parent: 'namespace:styling-libraries', slot: 'guides', order: 20},+ category: 'guide',+ description:+ 'The Tailwind v4 bridge, cascade layer order, and utility-class usage backed by system tokens.',+ keywords: [+ 'tailwind-theme.css',+ 'utility classes',+ 'preflight',+ ],++ sections: [+ {+ title: 'Tailwind',+ content: [+ {+ type: 'prose',+ text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme reference inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme without emitting competing runtime declarations.',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css',+ code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;++@import "tailwindcss/theme.css" layer(theme);+@import "tailwindcss/preflight.css" layer(base);+@import "@astryxdesign/core/reset.css";+@import "@astryxdesign/core/astryx.css";+@import "@astryxdesign/theme-neutral/theme.css";+@import "@astryxdesign/core/tailwind-theme.css";+@import "tailwindcss/utilities.css" layer(utilities);`,+ },+ {+ type: 'prose',+ text: 'Pre-declare every layer before any imports. This keeps reset lowest, Tailwind preflight above reset, component/theme styles in the middle, and Tailwind utilities last so utility classes on `className` can intentionally override component defaults.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Tailwind classes backed by system tokens',+ code: `<section className="rounded-lg border border-border bg-surface p-4 text-primary shadow-md">+ <Button label="Save" variant="primary" />+</section>`,+ },+ {+ type: 'prose',+ text: 'The Tailwind bridge is the concrete example of the general interop pattern: expose another library\'s semantic API, but point the values at system token variables.',+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs b/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjsnew file mode 100644index 0000000000..519ad5ea62--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs@@ -0,0 +1,128 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling/tokens-and-setup`: using design tokens in custom+ * styles and configuring a StyleX compiler for swizzled components.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'tokens-and-setup',+ title: 'Tokens & Setup',+ placement: {parent: 'namespace:styling', slot: 'guides', order: 30},+ category: 'guide',+ description:+ 'Using design tokens in custom styles and configuring a StyleX compiler for swizzled components.',+ keywords: [+ 'StyleX setup',+ 'swizzle',+ 'webpack',+ 'Vite',+ 'Next.js',+ ],++ sections: [+ {+ title: 'Design Tokens',+ content: [+ {+ type: 'prose',+ text: 'When writing custom styles, use design tokens instead of hardcoded values. Tokens are CSS custom properties that adapt to the active theme and color mode. The system provides tokens for spacing, color, radius, shadow, typography, and size.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Using tokens in stylex.create',+ code: `import * as stylex from '@stylexjs/stylex';++const styles = stylex.create({+ surface: {+ padding: 'var(--spacing-4)',+ borderRadius: 'var(--radius-container)',+ backgroundColor: 'var(--color-background-surface)',+ },+});++<Card xstyle={styles.surface} />`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Using typed token imports in stylex.create',+ code: `import {colorVars, spacingVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';++const styles = stylex.create({+ highlight: {+ backgroundColor: colorVars['--color-accent-muted'],+ padding: spacingVars['--spacing-3'],+ borderRadius: radiusVars['--radius-element'],+ },+});`,+ },+ {+ type: 'prose',+ text: 'Both approaches work: var() strings or typed imports from tokens.stylex. The typed imports give autocomplete and catch typos at build time.',+ },+ {+ type: 'prose',+ text: 'See {@link namespace:tokens} for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See {@link generic:author-a-theme} for how to override tokens via defineTheme.',+ },+ ],+ },+ {+ id: 'stylex-setup',+ title: 'StyleX Build Setup (required for swizzled components)',+ content: [+ {+ type: 'prose',+ text: 'Astryx components ship pre-compiled, so consuming the published package needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',+ },+ {+ type: 'table',+ headers: ['Bundler', 'StyleX plugin'],+ rows: [+ ['Webpack', '@stylexjs/webpack-plugin'],+ ['Vite / Rollup', '@stylexjs/rollup-plugin (or a community Vite plugin)'],+ ['Babel (any bundler)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],+ ['Next.js (App Router, SWC)', 'An SWC-based transform; see the Next.js note below'],+ ],+ },+ {+ type: 'prose',+ text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.',+ },+ {+ type: 'prose',+ text: 'The repo\'s `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.',+ },+ {+ type: 'code',+ lang: 'js',+ label: 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',+ code: `import stylexPlugin from '@stylexswc/nextjs-plugin';++export default stylexPlugin({+ rsOptions: {+ // Resolve @astryxdesign/core's StyleX so swizzled component source compiles.+ aliases: {'@/*': ['./src/*']},+ unstable_moduleResolution: {type: 'commonJS'},+ },+})({+ // your existing Next.js config+});`,+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ 'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',+ 'A Babel config turns off SWC in Next.js; skip it if you need `next/font`.',+ 'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-border.doc.mjs b/packages/cli/assets/docs/tree/tokens-border.doc.mjsnew file mode 100644index 0000000000..2986f82fa1--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-border.doc.mjs@@ -0,0 +1,46 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-border",+ "title": "Border Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 60+ },+ "category": "foundations",+ "description": "Border width for card and input borders.",+ "sections": [+ {+ "title": "Border Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Border width for card and input borders."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--border-width",+ "1px"+ ]+ ]+ }+ ],+ "previewType": "border-line"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-color.doc.dense.mjs b/packages/cli/assets/docs/tree/tokens-color.doc.dense.mjsnew file mode 100644index 0000000000..afe57e9ccf--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-color.doc.dense.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsDense = {+ description: 'semantic colors, support light-dark() auto switching.',+ sections: [+ { section: 'Color Tokens', title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-color.doc.mjs b/packages/cli/assets/docs/tree/tokens-color.doc.mjsnew file mode 100644index 0000000000..1a3c9ce6ae--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-color.doc.mjs@@ -0,0 +1,438 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-color",+ "title": "Color Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 10+ },+ "category": "foundations",+ "description": "Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching.",+ "sections": [+ {+ "title": "Color Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Light",+ "Dark"+ ],+ "rows": [+ [+ "--color-accent",+ "#0064E0",+ "#2694FE"+ ],+ [+ "--color-accent-muted",+ "#0082FB33",+ "#0082FB3F"+ ],+ [+ "--color-on-accent",+ "#FFFFFF",+ "#FFFFFF"+ ],+ [+ "--color-neutral",+ "rgba(5, 54, 89, 0.1)",+ "rgba(223, 226, 229, 0.2)"+ ],+ [+ "--color-background-surface",+ "#FFFFFF",+ "#1F1F22"+ ],+ [+ "--color-background-body",+ "#F1F4F7",+ "#111112"+ ],+ [+ "--color-overlay",+ "#01122866",+ "#11111299"+ ],+ [+ "--color-overlay-hover",+ "#0536590C",+ "#FFFFFF0C"+ ],+ [+ "--color-overlay-pressed",+ "#05365919",+ "#FFFFFF19"+ ],+ [+ "--color-background-muted",+ "#0536590C",+ "#1111127F"+ ],+ [+ "--color-text-primary",+ "#0A1317",+ "#DFE2E5"+ ],+ [+ "--color-text-secondary",+ "#4E606F",+ "#AAAFB5"+ ],+ [+ "--color-text-disabled",+ "#A4B0BC",+ "#6F747C"+ ],+ [+ "--color-text-accent",+ "#0064E0",+ "#3E9EFB"+ ],+ [+ "--color-on-dark",+ "#FFFFFF",+ "#FFFFFF"+ ],+ [+ "--color-on-light",+ "#000000",+ "#000000"+ ],+ [+ "--color-icon-accent",+ "#0064E0",+ "#2694FE"+ ],+ [+ "--color-icon-primary",+ "#0A1317",+ "#DFE2E5"+ ],+ [+ "--color-icon-secondary",+ "#4E606F",+ "#AAAFB5"+ ],+ [+ "--color-icon-disabled",+ "#A4B0BC",+ "#6F747C"+ ],+ [+ "--color-background-card",+ "#FFFFFF",+ "#1F1F22"+ ],+ [+ "--color-background-popover",+ "#FFFFFF",+ "#28292C"+ ],+ [+ "--color-background-inverted",+ "#0A1317",+ "#FFFFFF"+ ],+ [+ "--color-background-error-inverted",+ "#AA071E",+ "#E3193B"+ ],+ [+ "--color-success",+ "#0D8626",+ "#0D8626"+ ],+ [+ "--color-success-muted",+ "#0B991F33",+ "#0B991F3F"+ ],+ [+ "--color-on-success",+ "#FFFFFF",+ "#FFFFFF"+ ],+ [+ "--color-error",+ "#E3193B",+ "#F5394F"+ ],+ [+ "--color-error-muted",+ "#E3193B33",+ "#F5394F3F"+ ],+ [+ "--color-on-error",+ "#FFFFFF",+ "#FFFFFF"+ ],+ [+ "--color-warning",+ "#E9AF08",+ "#F2C00B"+ ],+ [+ "--color-warning-muted",+ "#E2A40033",+ "#E2A4003F"+ ],+ [+ "--color-on-warning",+ "#0A1317",+ "#0A1317"+ ],+ [+ "--color-border",+ "#05365919",+ "#F2F4F619"+ ],+ [+ "--color-border-emphasized",+ "#CCD3DB",+ "#494D53"+ ],+ [+ "--color-skeleton",+ "#CCD3DB",+ "#5A5E66"+ ],+ [+ "--color-track",+ "#CCD3DB",+ "#5A5E66"+ ],+ [+ "--color-shadow",+ "rgba(5, 54, 89, 0.1)",+ "rgba(0, 0, 0, 0.3)"+ ],+ [+ "--color-tint-hover",+ "black",+ "white"+ ],+ [+ "--color-background-blue",+ "#0171E333",+ "#0171E333"+ ],+ [+ "--color-border-blue",+ "#0064E0",+ "#2694FE"+ ],+ [+ "--color-icon-blue",+ "#0064E0",+ "#2694FE"+ ],+ [+ "--color-text-blue",+ "#042F97",+ "#AFD7FF"+ ],+ [+ "--color-background-cyan",+ "#03A7D733",+ "#03A7D733"+ ],+ [+ "--color-border-cyan",+ "#089DD0",+ "#0171A4"+ ],+ [+ "--color-icon-cyan",+ "#00ACC1",+ "#26C6DA"+ ],+ [+ "--color-text-cyan",+ "#014975",+ "#A1EEF9"+ ],+ [+ "--color-background-gray",+ "#0A131733",+ "#666A724C"+ ],+ [+ "--color-border-gray",+ "#647685",+ "#748695"+ ],+ [+ "--color-icon-gray",+ "#4E606F",+ "#AAAFB5"+ ],+ [+ "--color-text-gray",+ "#0A1317",+ "#E7EAED"+ ],+ [+ "--color-background-green",+ "#24BB5E33",+ "#24BB5E33"+ ],+ [+ "--color-border-green",+ "#0D8626",+ "#0B991F"+ ],+ [+ "--color-icon-green",+ "#0D8626",+ "#26A756"+ ],+ [+ "--color-text-green",+ "#09441F",+ "#A5F690"+ ],+ [+ "--color-background-orange",+ "#F2790233",+ "#F2790233"+ ],+ [+ "--color-border-orange",+ "#EB6E00",+ "#B34A01"+ ],+ [+ "--color-icon-orange",+ "#E9690B",+ "#FB8C00"+ ],+ [+ "--color-text-orange",+ "#6B2203",+ "#FDB876"+ ],+ [+ "--color-background-pink",+ "#E638B333",+ "#E638B333"+ ],+ [+ "--color-border-pink",+ "#F351C0",+ "#C02294"+ ],+ [+ "--color-icon-pink",+ "#C2185B",+ "#EC407A"+ ],+ [+ "--color-text-pink",+ "#650053",+ "#FEADE3"+ ],+ [+ "--color-background-purple",+ "#7952FF33",+ "#7952FF33"+ ],+ [+ "--color-border-purple",+ "#9081FF",+ "#7340FE"+ ],+ [+ "--color-icon-purple",+ "#5B08D8",+ "#7952FF"+ ],+ [+ "--color-text-purple",+ "#3E0697",+ "#B3B0FE"+ ],+ [+ "--color-background-red",+ "#E3193B33",+ "#E3193B33"+ ],+ [+ "--color-border-red",+ "#E3193B",+ "#F5394F"+ ],+ [+ "--color-icon-red",+ "#D31130",+ "#E3193B"+ ],+ [+ "--color-text-red",+ "#7B0210",+ "#FFB2B8"+ ],+ [+ "--color-background-teal",+ "#0DB7AF33",+ "#0DB7AF33"+ ],+ [+ "--color-border-teal",+ "#08A3A3",+ "#08767D"+ ],+ [+ "--color-icon-teal",+ "#009688",+ "#26A69A"+ ],+ [+ "--color-text-teal",+ "#083943",+ "#40DCCD"+ ],+ [+ "--color-background-yellow",+ "#E2A40033",+ "#E2A40033"+ ],+ [+ "--color-border-yellow",+ "#C58600",+ "#B47700"+ ],+ [+ "--color-icon-yellow",+ "#FBC02D",+ "#FFEE58"+ ],+ [+ "--color-text-yellow",+ "#753F07",+ "#FBCE03"+ ]+ ]+ }+ ],+ "previewType": "swatch"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-color.doc.zh.mjs b/packages/cli/assets/docs/tree/tokens-color.doc.zh.mjsnew file mode 100644index 0000000000..caa6727263--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-color.doc.zh.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsZh = {+ description: '语义化颜色,支持 light-dark() 自动切换模式。',+ sections: [+ { section: 'Color Tokens', title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色,支持 light-dark() 自动切换模式。' }, null, null, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-data.doc.mjs b/packages/cli/assets/docs/tree/tokens-data.doc.mjsnew file mode 100644index 0000000000..0e0ba1e883--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-data.doc.mjs@@ -0,0 +1,323 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-data",+ "title": "Data Visualization Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 20+ },+ "category": "foundations",+ "description": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import their public StyleX variables from @astryxdesign/core/theme/dataTokens.stylex.",+ "sections": [+ {+ "title": "Data Visualization Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import their public StyleX variables from @astryxdesign/core/theme/dataTokens.stylex."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Light",+ "Dark"+ ],+ "rows": [+ [+ "--color-data-categorical-blue",+ "#0171E3",+ "#0171E3"+ ],+ [+ "--color-data-categorical-orange",+ "#EB6E00",+ "#EB6E00"+ ],+ [+ "--color-data-categorical-purple",+ "#6B1EFD",+ "#6B1EFD"+ ],+ [+ "--color-data-categorical-green",+ "#0B991F",+ "#0B991F"+ ],+ [+ "--color-data-categorical-pink",+ "#F351C0",+ "#F351C0"+ ],+ [+ "--color-data-categorical-cyan",+ "#0171A4",+ "#0171A4"+ ],+ [+ "--color-data-categorical-red",+ "#F5394F",+ "#F5394F"+ ],+ [+ "--color-data-categorical-teal",+ "#08A3A3",+ "#08A3A3"+ ],+ [+ "--color-data-categorical-brown",+ "#965E03",+ "#965E03"+ ],+ [+ "--color-data-categorical-indigo",+ "#6F8AFF",+ "#6F8AFF"+ ],+ [+ "--color-data-neutral",+ "#8494A3",+ "#8C939B"+ ],+ [+ "--color-data-blue-5",+ "#02165E",+ "#02165E"+ ],+ [+ "--color-data-blue-4",+ "#004CBC",+ "#004CBC"+ ],+ [+ "--color-data-blue-3",+ "#2694FE",+ "#2694FE"+ ],+ [+ "--color-data-blue-2",+ "#78BEFF",+ "#78BEFF"+ ],+ [+ "--color-data-blue-1",+ "#DBECFF",+ "#DBECFF"+ ],+ [+ "--color-data-shamrock-5",+ "#0B603D",+ "#0B603D"+ ],+ [+ "--color-data-shamrock-4",+ "#138546",+ "#138546"+ ],+ [+ "--color-data-shamrock-3",+ "#24BB5E",+ "#24BB5E"+ ],+ [+ "--color-data-shamrock-2",+ "#8EF7AA",+ "#8EF7AA"+ ],+ [+ "--color-data-shamrock-1",+ "#D6FEE4",+ "#D6FEE4"+ ],+ [+ "--color-data-orange-5",+ "#A13F04",+ "#A13F04"+ ],+ [+ "--color-data-orange-4",+ "#D66100",+ "#D66100"+ ],+ [+ "--color-data-orange-3",+ "#FD9537",+ "#FD9537"+ ],+ [+ "--color-data-orange-2",+ "#FDB876",+ "#FDB876"+ ],+ [+ "--color-data-orange-1",+ "#FFE6CF",+ "#FFE6CF"+ ],+ [+ "--color-data-pink-5",+ "#8E1073",+ "#8E1073"+ ],+ [+ "--color-data-pink-4",+ "#D123A1",+ "#D123A1"+ ],+ [+ "--color-data-pink-3",+ "#F989D3",+ "#F989D3"+ ],+ [+ "--color-data-pink-2",+ "#FEADE3",+ "#FEADE3"+ ],+ [+ "--color-data-pink-1",+ "#FCE3F4",+ "#FCE3F4"+ ],+ [+ "--color-data-purple-5",+ "#3E0697",+ "#3E0697"+ ],+ [+ "--color-data-purple-4",+ "#6B1EFD",+ "#6B1EFD"+ ],+ [+ "--color-data-purple-3",+ "#9081FF",+ "#9081FF"+ ],+ [+ "--color-data-purple-2",+ "#B3B0FE",+ "#B3B0FE"+ ],+ [+ "--color-data-purple-1",+ "#E8E8FB",+ "#E8E8FB"+ ],+ [+ "--color-data-red-5",+ "#9D0519",+ "#9D0519"+ ],+ [+ "--color-data-red-4",+ "#D31130",+ "#D31130"+ ],+ [+ "--color-data-red-3",+ "#FB7D87",+ "#FB7D87"+ ],+ [+ "--color-data-red-2",+ "#FFB2B8",+ "#FFB2B8"+ ],+ [+ "--color-data-red-1",+ "#FEE4E6",+ "#FEE4E6"+ ],+ [+ "--color-data-teal-5",+ "#08767D",+ "#08767D"+ ],+ [+ "--color-data-teal-4",+ "#0C9293",+ "#0C9293"+ ],+ [+ "--color-data-teal-3",+ "#0DB7AF",+ "#0DB7AF"+ ],+ [+ "--color-data-teal-2",+ "#6CE6D8",+ "#6CE6D8"+ ],+ [+ "--color-data-teal-1",+ "#D7FCF8",+ "#D7FCF8"+ ],+ [+ "--color-data-yellow-5",+ "#8A5001",+ "#8A5001"+ ],+ [+ "--color-data-yellow-4",+ "#D69804",+ "#D69804"+ ],+ [+ "--color-data-yellow-3",+ "#FBCE03",+ "#FBCE03"+ ],+ [+ "--color-data-yellow-2",+ "#FCEC85",+ "#FCEC85"+ ],+ [+ "--color-data-yellow-1",+ "#FDF6BA",+ "#FDF6BA"+ ],+ [+ "--color-data-gray-5",+ "#25363F",+ "#333338"+ ],+ [+ "--color-data-gray-4",+ "#5D6C7B",+ "#666A72"+ ],+ [+ "--color-data-gray-3",+ "#AFB9C4",+ "#B2B8BE"+ ],+ [+ "--color-data-gray-2",+ "#CCD3DB",+ "#D0D3D6"+ ],+ [+ "--color-data-gray-1",+ "#F1F4F7",+ "#F2F4F6"+ ]+ ]+ }+ ],+ "previewType": "swatch"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-duration.doc.mjs b/packages/cli/assets/docs/tree/tokens-duration.doc.mjsnew file mode 100644index 0000000000..917328cf73--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-duration.doc.mjs@@ -0,0 +1,78 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-duration",+ "title": "Duration Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 100+ },+ "category": "foundations",+ "description": "Motion duration primitives. Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous). Min/max variants derive from base × ratio.",+ "sections": [+ {+ "title": "Duration Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Motion duration primitives. Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous). Min/max variants derive from base × ratio."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--duration-fast-min",+ "130ms"+ ],+ [+ "--duration-fast",+ "175ms"+ ],+ [+ "--duration-fast-max",+ "230ms"+ ],+ [+ "--duration-medium-min",+ "310ms"+ ],+ [+ "--duration-medium",+ "410ms"+ ],+ [+ "--duration-medium-max",+ "550ms"+ ],+ [+ "--duration-slow-min",+ "730ms"+ ],+ [+ "--duration-slow",+ "975ms"+ ],+ [+ "--duration-slow-max",+ "1300ms"+ ]+ ]+ }+ ],+ "previewType": "duration-bar"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-ease.doc.mjs b/packages/cli/assets/docs/tree/tokens-ease.doc.mjsnew file mode 100644index 0000000000..ed95f3bde5--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-ease.doc.mjs@@ -0,0 +1,46 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-ease",+ "title": "Easing Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 110+ },+ "category": "foundations",+ "description": "Easing curves for animations and transitions.",+ "sections": [+ {+ "title": "Easing Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Easing curves for animations and transitions."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--ease-standard",+ "cubic-bezier(0.24, 1, 0.4, 1)"+ ]+ ]+ }+ ],+ "previewType": "easing-curve"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-focus.doc.mjs b/packages/cli/assets/docs/tree/tokens-focus.doc.mjsnew file mode 100644index 0000000000..8b9c9fe8db--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-focus.doc.mjs@@ -0,0 +1,57 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-focus",+ "title": "Focus Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 70+ },+ "category": "foundations",+ "description": "The keyboard focus ring, shared by every component that draws one. Override these to restyle focus across the system.",+ "sections": [+ {+ "title": "Focus Tokens",+ "content": [+ {+ "type": "prose",+ "text": "The keyboard focus ring, shared by every component that draws one. Override these to restyle focus across the system."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--focus-outline-width",+ "2px"+ ],+ [+ "--focus-outline-style",+ "solid"+ ],+ [+ "--focus-outline-color",+ "var(--color-accent)"+ ],+ [+ "--focus-outline-offset",+ "3px"+ ]+ ]+ }+ ]+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-font-weight.doc.mjs b/packages/cli/assets/docs/tree/tokens-font-weight.doc.mjsnew file mode 100644index 0000000000..2e974188d1--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-font-weight.doc.mjs@@ -0,0 +1,58 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-font-weight",+ "title": "Font Weight Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 140+ },+ "category": "foundations",+ "description": "Font weight values for body, emphasis, and headings.",+ "sections": [+ {+ "title": "Font Weight Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Font weight values for body, emphasis, and headings."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--font-weight-normal",+ "400"+ ],+ [+ "--font-weight-medium",+ "500"+ ],+ [+ "--font-weight-semibold",+ "600"+ ],+ [+ "--font-weight-bold",+ "700"+ ]+ ]+ }+ ],+ "previewType": "font-sample"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-radius.doc.dense.mjs b/packages/cli/assets/docs/tree/tokens-radius.doc.dense.mjsnew file mode 100644index 0000000000..3aa49eaf21--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-radius.doc.dense.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsDense = {+ description: 'border radius tokens.',+ sections: [+ { section: 'Radius Tokens', title: 'Radius', content: [null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-radius.doc.mjs b/packages/cli/assets/docs/tree/tokens-radius.doc.mjsnew file mode 100644index 0000000000..0f6bf4923f--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-radius.doc.mjs@@ -0,0 +1,70 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-radius",+ "title": "Radius Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 80+ },+ "category": "foundations",+ "description": "Numeric scale based on a 4dp base unit. Tokens scale with the theme's radius multiplier; --radius-none and --radius-full are fixed.",+ "sections": [+ {+ "title": "Radius Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Numeric scale based on a 4dp base unit. Tokens scale with the theme's radius multiplier; --radius-none and --radius-full are fixed."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--radius-none",+ "0px"+ ],+ [+ "--radius-inner",+ "4px"+ ],+ [+ "--radius-element",+ "8px"+ ],+ [+ "--radius-container",+ "12px"+ ],+ [+ "--radius-page",+ "28px"+ ],+ [+ "--radius-chat",+ "28px"+ ],+ [+ "--radius-full",+ "9999px"+ ]+ ]+ }+ ],+ "previewType": "radius-box"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-radius.doc.zh.mjs b/packages/cli/assets/docs/tree/tokens-radius.doc.zh.mjsnew file mode 100644index 0000000000..6bdce113b5--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-radius.doc.zh.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsZh = {+ description: '圆角令牌。',+ sections: [+ { section: 'Radius Tokens', title: '圆角令牌', content: [null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-shadow.doc.dense.mjs b/packages/cli/assets/docs/tree/tokens-shadow.doc.dense.mjsnew file mode 100644index 0000000000..09958ff348--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-shadow.doc.dense.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsDense = {+ description: 'shadow and elevation tokens.',+ sections: [+ { section: 'Shadow Tokens', title: 'Elevation', content: [null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-shadow.doc.mjs b/packages/cli/assets/docs/tree/tokens-shadow.doc.mjsnew file mode 100644index 0000000000..423716dac0--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-shadow.doc.mjs@@ -0,0 +1,74 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-shadow",+ "title": "Shadow Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 90+ },+ "category": "foundations",+ "description": "Elevation shadows (low to med to high) and inset shadows for input state rings.",+ "sections": [+ {+ "title": "Shadow Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Elevation shadows (low to med to high) and inset shadows for input state rings."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--shadow-low",+ "0px 1px 1px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 8px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"+ ],+ [+ "--shadow-med",+ "0px 1px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 12px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"+ ],+ [+ "--shadow-high",+ "0px 2px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 8px 24px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.3))"+ ],+ [+ "--shadow-inset-hover",+ "inset 0px 0px 0px 2px light-dark(rgba(5, 54, 89, 0.15), rgba(223, 226, 229, 0.2))"+ ],+ [+ "--shadow-inset-selected",+ "inset 0px 0px 0px 2px rgba(1, 113, 227, 0.5)"+ ],+ [+ "--shadow-inset-success",+ "inset 0px 0px 0px 2px rgba(38, 167, 86, 0.3)"+ ],+ [+ "--shadow-inset-warning",+ "inset 0px 0px 0px 2px rgba(226, 164, 0, 0.3)"+ ],+ [+ "--shadow-inset-error",+ "inset 0px 0px 0px 2px rgba(227, 25, 59, 0.3)"+ ]+ ]+ }+ ],+ "previewType": "shadow-box"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-shadow.doc.zh.mjs b/packages/cli/assets/docs/tree/tokens-shadow.doc.zh.mjsnew file mode 100644index 0000000000..f4d442702a--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-shadow.doc.zh.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsZh = {+ description: '阴影令牌。',+ sections: [+ { section: 'Shadow Tokens', title: '阴影令牌', content: [null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-size.doc.dense.mjs b/packages/cli/assets/docs/tree/tokens-size.doc.dense.mjsnew file mode 100644index 0000000000..275b9ce1d2--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-size.doc.dense.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsDense = {+ description: 'control heights for buttons/inputs/selectors.',+ sections: [+ { section: 'Size Tokens', title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-size.doc.mjs b/packages/cli/assets/docs/tree/tokens-size.doc.mjsnew file mode 100644index 0000000000..d7d42f7d85--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-size.doc.mjs@@ -0,0 +1,54 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-size",+ "title": "Size Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 50+ },+ "category": "foundations",+ "description": "Control heights for consistent sizing across buttons, inputs, and selectors.",+ "sections": [+ {+ "title": "Size Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Control heights for consistent sizing across buttons, inputs, and selectors."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--size-element-sm",+ "28px"+ ],+ [+ "--size-element-md",+ "32px"+ ],+ [+ "--size-element-lg",+ "36px"+ ]+ ]+ }+ ],+ "previewType": "size-bar"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-size.doc.zh.mjs b/packages/cli/assets/docs/tree/tokens-size.doc.zh.mjsnew file mode 100644index 0000000000..dd9d15a036--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-size.doc.zh.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsZh = {+ description: '控制按钮、输入框和选择器的一致高度。',+ sections: [+ { section: 'Size Tokens', title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-spacing.doc.dense.mjs b/packages/cli/assets/docs/tree/tokens-spacing.doc.dense.mjsnew file mode 100644index 0000000000..90c77ae7da--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-spacing.doc.dense.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsDense = {+ description: 'padding/gap/margin spacing scale.',+ sections: [+ { section: 'Spacing Tokens', title: 'Spacing', content: [{ type: 'prose', text: 'padding/gap/margin scale. gap props take steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.' }, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-spacing.doc.mjs b/packages/cli/assets/docs/tree/tokens-spacing.doc.mjsnew file mode 100644index 0000000000..506e3e0168--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-spacing.doc.mjs@@ -0,0 +1,102 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-spacing",+ "title": "Spacing Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 40+ },+ "category": "foundations",+ "description": "Spacing scale used for padding, gap, and margin. Component gap props map spacing steps to these tokens.",+ "sections": [+ {+ "title": "Spacing Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Spacing scale used for padding, gap, and margin. Component gap props map spacing steps to these tokens."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--spacing-0",+ "0px"+ ],+ [+ "--spacing-0-5",+ "2px"+ ],+ [+ "--spacing-1",+ "4px"+ ],+ [+ "--spacing-1-5",+ "6px"+ ],+ [+ "--spacing-2",+ "8px"+ ],+ [+ "--spacing-3",+ "12px"+ ],+ [+ "--spacing-4",+ "16px"+ ],+ [+ "--spacing-5",+ "20px"+ ],+ [+ "--spacing-6",+ "24px"+ ],+ [+ "--spacing-7",+ "28px"+ ],+ [+ "--spacing-8",+ "32px"+ ],+ [+ "--spacing-9",+ "36px"+ ],+ [+ "--spacing-10",+ "40px"+ ],+ [+ "--spacing-11",+ "44px"+ ],+ [+ "--spacing-12",+ "48px"+ ]+ ]+ }+ ],+ "previewType": "spacing-bar"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-spacing.doc.zh.mjs b/packages/cli/assets/docs/tree/tokens-spacing.doc.zh.mjsnew file mode 100644index 0000000000..656b80fdf5--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-spacing.doc.zh.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsZh = {+ description: '用于内边距、间距和外边距的刻度。',+ sections: [+ { section: 'Spacing Tokens', title: '间距令牌', content: [{ type: 'prose', text: '用于内边距、间距和外边距的刻度。组件 gap 属性接受步长 0、0.5、1、1.5、2、3、4、5、6、8、10。' }, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-syntax.doc.mjs b/packages/cli/assets/docs/tree/tokens-syntax.doc.mjsnew file mode 100644index 0000000000..4364e41eba--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-syntax.doc.mjs@@ -0,0 +1,98 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-syntax",+ "title": "Syntax Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 30+ },+ "category": "foundations",+ "description": "Code highlighting colors used by CodeBlock. Each defaults to a palette token, so syntax colors follow the theme; defineTheme({syntax}) sets a syntax theme instead.",+ "sections": [+ {+ "title": "Syntax Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Code highlighting colors used by CodeBlock. Each defaults to a palette token, so syntax colors follow the theme; defineTheme({syntax}) sets a syntax theme instead."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--color-syntax-keyword",+ "var(--color-text-accent)"+ ],+ [+ "--color-syntax-string",+ "var(--color-text-green)"+ ],+ [+ "--color-syntax-comment",+ "var(--color-text-secondary)"+ ],+ [+ "--color-syntax-number",+ "var(--color-text-orange)"+ ],+ [+ "--color-syntax-function",+ "var(--color-text-blue)"+ ],+ [+ "--color-syntax-type",+ "var(--color-text-purple)"+ ],+ [+ "--color-syntax-variable",+ "var(--color-text-primary)"+ ],+ [+ "--color-syntax-operator",+ "var(--color-text-cyan)"+ ],+ [+ "--color-syntax-constant",+ "var(--color-text-orange)"+ ],+ [+ "--color-syntax-tag",+ "var(--color-text-red)"+ ],+ [+ "--color-syntax-attribute",+ "var(--color-text-teal)"+ ],+ [+ "--color-syntax-property",+ "var(--color-text-cyan)"+ ],+ [+ "--color-syntax-punctuation",+ "var(--color-text-secondary)"+ ],+ [+ "--color-syntax-background",+ "var(--color-background-muted)"+ ]+ ]+ }+ ],+ "previewType": "swatch"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-text-size.doc.mjs b/packages/cli/assets/docs/tree/tokens-text-size.doc.mjsnew file mode 100644index 0000000000..c7587074ca--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-text-size.doc.mjs@@ -0,0 +1,90 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-text-size",+ "title": "Font Size Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 130+ },+ "category": "foundations",+ "description": "Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base).",+ "sections": [+ {+ "title": "Font Size Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base)."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--font-size-4xs",+ "0.375rem"+ ],+ [+ "--font-size-3xs",+ "0.4375rem"+ ],+ [+ "--font-size-2xs",+ "0.5rem"+ ],+ [+ "--font-size-xs",+ "0.625rem"+ ],+ [+ "--font-size-sm",+ "0.75rem"+ ],+ [+ "--font-size-base",+ "0.875rem"+ ],+ [+ "--font-size-lg",+ "1.0625rem"+ ],+ [+ "--font-size-xl",+ "1.25rem"+ ],+ [+ "--font-size-2xl",+ "1.5rem"+ ],+ [+ "--font-size-3xl",+ "1.8125rem"+ ],+ [+ "--font-size-4xl",+ "2.1875rem"+ ],+ [+ "--font-size-5xl",+ "2.625rem"+ ]+ ]+ }+ ],+ "previewType": "font-sample"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-type-scale.doc.mjs b/packages/cli/assets/docs/tree/tokens-type-scale.doc.mjsnew file mode 100644index 0000000000..f6af33ec5f--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-type-scale.doc.mjs@@ -0,0 +1,210 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-type-scale",+ "title": "Type Scale Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 150+ },+ "category": "foundations",+ "description": "Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme.",+ "sections": [+ {+ "title": "Type Scale Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--text-heading-1-size",+ "var(--font-size-2xl)"+ ],+ [+ "--text-heading-1-weight",+ "var(--font-weight-semibold)"+ ],+ [+ "--text-heading-1-leading",+ "1.3333"+ ],+ [+ "--text-heading-2-size",+ "var(--font-size-xl)"+ ],+ [+ "--text-heading-2-weight",+ "var(--font-weight-semibold)"+ ],+ [+ "--text-heading-2-leading",+ "1.4"+ ],+ [+ "--text-heading-3-size",+ "var(--font-size-lg)"+ ],+ [+ "--text-heading-3-weight",+ "var(--font-weight-semibold)"+ ],+ [+ "--text-heading-3-leading",+ "1.4118"+ ],+ [+ "--text-heading-4-size",+ "var(--font-size-base)"+ ],+ [+ "--text-heading-4-weight",+ "var(--font-weight-semibold)"+ ],+ [+ "--text-heading-4-leading",+ "1.4286"+ ],+ [+ "--text-heading-5-size",+ "var(--font-size-sm)"+ ],+ [+ "--text-heading-5-weight",+ "var(--font-weight-semibold)"+ ],+ [+ "--text-heading-5-leading",+ "1.6667"+ ],+ [+ "--text-heading-6-size",+ "var(--font-size-xs)"+ ],+ [+ "--text-heading-6-weight",+ "var(--font-weight-semibold)"+ ],+ [+ "--text-heading-6-leading",+ "1.6"+ ],+ [+ "--text-body-size",+ "var(--font-size-base)"+ ],+ [+ "--text-body-weight",+ "var(--font-weight-normal)"+ ],+ [+ "--text-body-leading",+ "1.4286"+ ],+ [+ "--text-large-size",+ "var(--font-size-lg)"+ ],+ [+ "--text-large-weight",+ "var(--font-weight-semibold)"+ ],+ [+ "--text-large-leading",+ "1.4118"+ ],+ [+ "--text-label-size",+ "var(--font-size-base)"+ ],+ [+ "--text-label-weight",+ "var(--font-weight-medium)"+ ],+ [+ "--text-label-leading",+ "1.4286"+ ],+ [+ "--text-code-size",+ "var(--font-size-base)"+ ],+ [+ "--text-code-weight",+ "var(--font-weight-normal)"+ ],+ [+ "--text-code-leading",+ "1.4286"+ ],+ [+ "--text-supporting-size",+ "var(--font-size-sm)"+ ],+ [+ "--text-supporting-weight",+ "var(--font-weight-normal)"+ ],+ [+ "--text-supporting-leading",+ "1.6667"+ ],+ [+ "--text-display-1-size",+ "var(--font-size-5xl)"+ ],+ [+ "--text-display-1-weight",+ "var(--font-weight-normal)"+ ],+ [+ "--text-display-1-leading",+ "1.2381"+ ],+ [+ "--text-display-2-size",+ "var(--font-size-4xl)"+ ],+ [+ "--text-display-2-weight",+ "var(--font-weight-normal)"+ ],+ [+ "--text-display-2-leading",+ "1.2571"+ ],+ [+ "--text-display-3-size",+ "var(--font-size-3xl)"+ ],+ [+ "--text-display-3-weight",+ "var(--font-weight-normal)"+ ],+ [+ "--text-display-3-leading",+ "1.2414"+ ]+ ]+ }+ ],+ "previewType": "font-sample"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-typography.doc.mjs b/packages/cli/assets/docs/tree/tokens-typography.doc.mjsnew file mode 100644index 0000000000..50b42417b6--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-typography.doc.mjs@@ -0,0 +1,54 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-typography",+ "title": "Font Family Tokens",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 120+ },+ "category": "foundations",+ "description": "Font family stacks for body, code, and heading text.",+ "sections": [+ {+ "title": "Font Family Tokens",+ "content": [+ {+ "type": "prose",+ "text": "Font family stacks for body, code, and heading text."+ },+ {+ "type": "table",+ "headers": [+ "Token",+ "Value"+ ],+ "rows": [+ [+ "--font-family-body",+ "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"+ ],+ [+ "--font-family-code",+ "\"SF Mono\", Monaco, Consolas, monospace"+ ],+ [+ "--font-family-heading",+ "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"+ ]+ ]+ }+ ],+ "previewType": "font-sample"+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-usage.doc.dense.mjs b/packages/cli/assets/docs/tree/tokens-usage.doc.dense.mjsnew file mode 100644index 0000000000..51b2d08b51--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-usage.doc.dense.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsDense = {+ description: 'import/use token vars in StyleX.',+ sections: [+ { section: 'Usage in StyleX', title: 'StyleX Usage', content: [null, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens-usage.doc.mjs b/packages/cli/assets/docs/tree/tokens-usage.doc.mjsnew file mode 100644index 0000000000..35e3924c23--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-usage.doc.mjs@@ -0,0 +1,36 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ "type": "generic",+ "name": "tokens-usage",+ "title": "Usage in StyleX",+ "placement": {+ "parent": "namespace:tokens",+ "slot": "guides",+ "order": 160+ },+ "category": "foundations",+ "description": "How to import and use token variables in StyleX styles.",+ "sections": [+ {+ "title": "Usage in StyleX",+ "content": [+ {+ "type": "code",+ "lang": "tsx",+ "label": "Using token imports",+ "code": "import * as stylex from '@stylexjs/stylex';\nimport {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';\nimport {dataVars} from '@astryxdesign/core/theme/dataTokens.stylex';\n\nconst styles = stylex.create({\n card: {\n padding: spacingVars['--spacing-4'],\n backgroundColor: colorVars['--color-background-surface'],\n borderRadius: radiusVars['--radius-container'],\n },\n series: {\n color: dataVars['--color-data-categorical-blue'],\n },\n button: {\n height: sizeVars['--size-element-md'],\n },\n});"+ },+ {+ "type": "prose",+ "text": "See {@link namespace:styling} for how to apply tokens via xstyle, className, and compound component patterns. See {@link generic:author-a-theme} for overriding tokens with defineTheme."+ }+ ]+ }+ ]+};diff --git a/packages/cli/assets/docs/tree/tokens-usage.doc.zh.mjs b/packages/cli/assets/docs/tree/tokens-usage.doc.zh.mjsnew file mode 100644index 0000000000..988ee9f97f--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens-usage.doc.zh.mjs@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */++export const docsZh = {+ description: '如何在 StyleX 样式中导入和使用令牌变量。',+ sections: [+ { section: 'Usage in StyleX', title: 'StyleX 用法', content: [null, null] },+ ],+};diff --git a/packages/cli/assets/docs/tree/tokens.doc.mjs b/packages/cli/assets/docs/tree/tokens.doc.mjsnew file mode 100644index 0000000000..5c5551ddd9--- /dev/null+++ b/packages/cli/assets/docs/tree/tokens.doc.mjs@@ -0,0 +1,28 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Run: node scripts/generate-token-docs.mjs+// Total: 258 tokens across 15 categories.++/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */+export const docs = {+ "type": "namespace",+ "name": "tokens",+ "title": "All Tokens",+ "summary": "Complete reference for color, data visualization, syntax, spacing, size, border, focus, radius, shadow, motion, and typography tokens.",+ "keywords": [+ "design tokens",+ "css variables",+ "custom properties"+ ],+ "slots": {+ "guides": {+ "title": "Token Categories",+ "accepts": {+ "kinds": [+ "generic"+ ]+ }+ }+ }+};diff --git a/packages/cli/assets/docs/tree/type-scale.doc.mjs b/packages/cli/assets/docs/tree/type-scale.doc.mjsnew file mode 100644index 0000000000..127be39399--- /dev/null+++ b/packages/cli/assets/docs/tree/type-scale.doc.mjs@@ -0,0 +1,147 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs typography/type-scale`: line height, semantic type scale,+ * display text, headings and text components, and custom type scales.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'type-scale',+ title: 'Type Scale',+ placement: {parent: 'namespace:typography', slot: 'guides', order: 20},+ category: 'foundations',+ description:+ 'Line height, semantic type scale tokens, display text, Heading and Text components, and custom type scales via defineTheme.',+ keywords: [+ 'line height',+ 'leading',+ 'defineTheme',+ 'base',+ 'ratio',+ ],++ sections: [+ {+ 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 matters: 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, so you should never need to set line-height manually.',+ },+ ],+ },+ {+ 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 Text and Heading. Use the component props rather than composing raw font tokens.',+ },+ {+ type: 'token-ref',+ topic: 'tokens',+ section: 'Type Scale Tokens',+ },+ ],+ },+ {+ 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), since 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 type prop on Heading to apply display styling while preserving the correct HTML element: `<Heading level={1} type="display-1">` gives you display-1 styling with an `<h1>` tag, so screen readers see the correct document outline.',+ },+ ],+ },+ {+ id: 'usage',+ title: 'Headings and text',+ content: [+ {+ type: 'prose',+ text: 'Use `Heading` for document structure and `Text` for everything else; each maps its props to the type scale tokens.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Heading for document structure',+ code: `import {Heading} from '@astryxdesign/core';++// Heading levels map to semantic tokens: level 1 → --text-heading-1-*+<Heading level={1}>Page Title</Heading>+<Heading level={2}>Section</Heading>+<Heading level={3}>Subsection</Heading>++// Display type for hero/marketing headings — level sets the HTML element+<Heading level={1} type="display-1">Hero Title</Heading>+<Heading level={2} type="display-2">$1.2M Revenue</Heading>++// Override the accessibility level when visual ≠ document hierarchy+<Heading level={2} accessibilityLevel={3}>+ Sidebar Section+</Heading>`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Text for body, label, and display text',+ code: `import {Text} from '@astryxdesign/core';++<Text type="body">Body text at the base scale.</Text>+<Text type="large">Emphasized body text.</Text>+<Text type="label">Form label</Text>+<Text type="supporting">Helper text, timestamps, metadata.</Text>+<Text type="code">{'const x = 1;'}</Text>++// Display without heading semantics (data callouts, decorative)+<Text type="display-2">$1.2M Revenue</Text>`,+ },+ ],+ },+ {+ id: 'custom-type-scale',+ title: 'Custom type scale',+ content: [+ {+ type: 'prose',+ text: 'Change the whole ramp with `base` and `ratio` in `defineTheme`; every font size and line height recomputes from them.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Customizing the type scale via defineTheme',+ code: `import {defineTheme} from '@astryxdesign/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+ },+});`,+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/tree/typography-best-practices.doc.mjs b/packages/cli/assets/docs/tree/typography-best-practices.doc.mjsnew file mode 100644index 0000000000..b1f5d36e8f--- /dev/null+++ b/packages/cli/assets/docs/tree/typography-best-practices.doc.mjs@@ -0,0 +1,55 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs typography/typography-best-practices`: do/don't rules+ * for using the type scale, headings, and semantic tokens.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'typography-best-practices',+ title: 'Best Practices',+ placement: {parent: 'namespace:typography', slot: 'guides', order: 30},+ category: 'foundations',+ description:+ 'Do/don\'t rules for using the type scale, headings, display text, and semantic tokens.',+ keywords: [+ 'best practices',+ 'accessibility',+ 'heading levels',+ 'font-size',+ ],++ sections: [+ {+ title: 'Best Practices',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use Heading for document headings and Text 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. Or better, use `<Heading level={1} type="display-1">` which handles both semantics and styling.',+ '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 Heading when the visual hierarchy doesn\u0027t 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 to 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\u0027re 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/assets/docs/tree/typography.doc.mjs b/packages/cli/assets/docs/tree/typography.doc.mjsnew file mode 100644index 0000000000..e840ae0f15--- /dev/null+++ b/packages/cli/assets/docs/tree/typography.doc.mjs@@ -0,0 +1,29 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs typography`: the typography namespace. Groups guides for+ * font setup, the type scale, and best practices.+ */++/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */+export const docs = {+ type: 'namespace',+ name: 'typography',+ title: 'Typography',+ summary:+ 'Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.',+ keywords: [+ 'typography',+ 'font',+ 'fonts',+ 'type scale',+ 'heading',+ 'text',+ 'weight',+ 'line-height',+ 'display',+ ],+ slots: {+ guides: {title: 'Guides', accepts: {kinds: ['generic']}},+ },+};diff --git a/packages/cli/assets/docs/typography.doc.mjs b/packages/cli/assets/docs/typography.doc.mjsdeleted file mode 100644index 66c7b1d6c5..0000000000--- a/packages/cli/assets/docs/typography.doc.mjs+++ /dev/null@@ -1,286 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */--export const docs = {- name: 'typography',- title: 'Typography',- category: 'foundations',- description:- 'Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.',- keywords: ['font', 'fonts', 'font size'],- tokenCategory: 'typography',-- sections: [- // ── Overview ────────────────────────────────────────────────────────────- {- title: 'Overview',- category: 'foundations',- content: [- {- type: 'prose',- text: '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',- category: 'foundations',- 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',- },- ],- },-- // ── Custom Fonts ────────────────────────────────────────────────────────- {- id: 'loading-custom-fonts',- title: 'Custom fonts',- category: 'foundations',- content: [- {- type: 'prose',- text: 'Astryx never loads font files. defineTheme and the built CSS only set font-family: naming a webfont (Fraunces, JetBrains Mono, and so on) makes every browser look for it, and quietly fall back when the app has not loaded it. `astryx theme build` warns when a theme names families that are neither CSS generics nor common system fonts and prints the snippet to add; loading the font is always the app\'s job.',- },- {- type: 'code',- lang: 'html',- label: 'Google Fonts: add to your document <head>',- code: `<link rel="preconnect" href="https://fonts.googleapis.com" />-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />-<link- rel="stylesheet"- href="https://fonts.googleapis.com/css2?family=Fraunces:wght@400;600;700&family=JetBrains+Mono&display=swap"-/>`,- },- {- type: 'code',- lang: 'css',- label: 'Self-hosted: one @font-face per family and weight',- code: `@font-face {- font-family: 'Fraunces';- src: url('/fonts/fraunces.woff2') format('woff2');- font-weight: 400 700; /* variable-font range, or one weight per file */- font-display: swap; /* fallback text stays visible while the font loads */-}`,- },- {- type: 'prose',- text: "Always pair a webfont with a real fallback stack (metric-similar system fonts plus a generic) so text stays readable before the font loads and wherever it never does: defineTheme({typography: {heading: {family: 'Fraunces', fallbacks: 'Georgia, serif'}}}).",- },- ],- },-- // ── Font Sizes ──────────────────────────────────────────────────────────- {- title: 'Font Sizes',- category: 'foundations',- 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',- category: 'foundations',- 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',- category: 'foundations',- 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 matters: 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, so you should never need to set line-height manually.',- },- ],- },-- // ── Type Scale ──────────────────────────────────────────────────────────- {- title: 'Type Scale',- category: 'foundations',- 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 Text and Heading. Use the component props rather than composing raw font tokens.',- },- {- type: 'token-ref',- topic: 'tokens',- section: 'Type Scale Tokens',- },- ],- },-- // ── Display Text ────────────────────────────────────────────────────────- {- title: 'Display Text',- category: 'foundations',- 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), since 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 type prop on Heading to apply display styling while preserving the correct HTML element: `<Heading level={1} type="display-1">` gives you display-1 styling with an `<h1>` tag, so screen readers see the correct document outline.',- },- ],- },-- // ── Headings and text ───────────────────────────────────────────────────- {- id: 'usage',- title: 'Headings and text',- category: 'foundations',- content: [- {- type: 'prose',- text: 'Use `Heading` for document structure and `Text` for everything else; each maps its props to the type scale tokens.',- },- {- type: 'code',- lang: 'tsx',- label: 'Heading for document structure',- code: `import {Heading} from '@astryxdesign/core';--// Heading levels map to semantic tokens: level 1 → --text-heading-1-*-<Heading level={1}>Page Title</Heading>-<Heading level={2}>Section</Heading>-<Heading level={3}>Subsection</Heading>--// Display type for hero/marketing headings — level sets the HTML element-<Heading level={1} type="display-1">Hero Title</Heading>-<Heading level={2} type="display-2">$1.2M Revenue</Heading>--// Override the accessibility level when visual ≠ document hierarchy-<Heading level={2} accessibilityLevel={3}>- Sidebar Section-</Heading>`,- },- {- type: 'code',- lang: 'tsx',- label: 'Text for body, label, and display text',- code: `import {Text} from '@astryxdesign/core';--<Text type="body">Body text at the base scale.</Text>-<Text type="large">Emphasized body text.</Text>-<Text type="label">Form label</Text>-<Text type="supporting">Helper text, timestamps, metadata.</Text>-<Text type="code">{'const x = 1;'}</Text>--// Display without heading semantics (data callouts, decorative)-<Text type="display-2">$1.2M Revenue</Text>`,- },- ],- },-- // ── Custom type scale ───────────────────────────────────────────────────- {- id: 'custom-type-scale',- title: 'Custom type scale',- category: 'foundations',- content: [- {- type: 'prose',- text: 'Change the whole ramp with `base` and `ratio` in `defineTheme`; every font size and line height recomputes from them.',- },- {- type: 'code',- lang: 'tsx',- label: 'Customizing the type scale via defineTheme',- code: `import {defineTheme} from '@astryxdesign/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',- category: 'foundations',- content: [- {- type: 'list',- style: 'do',- items: [- 'Use Heading for document headings and Text 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. Or better, use `<Heading level={1} type="display-1">` which handles both semantics and styling.',- '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 Heading when the visual hierarchy doesn\u0027t 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 to 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\u0027re 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/assets/theme.template.ts b/packages/cli/assets/theme.template.tsindex 030a538d58..83e3b907a1 100644--- a/packages/cli/assets/theme.template.ts+++ b/packages/cli/assets/theme.template.ts@@ -131,7 +131,8 @@ export const myTheme = defineTheme({* values, and the rendered DOM is the final word.** Reference: `astryx docs color` for what each semantic role means,- * `astryx docs tokens` for every colour token and its light/dark default.+ * `astryx docs tokens/tokens-color` for every colour token and its light/dark+ * default.*/color: {accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard'},@@ -183,8 +184,8 @@ export const myTheme = defineTheme({// A string applies to both colour modes; a [light, dark] tuple compiles to// CSS light-dark(). List only what you want to change.//- // `astryx docs tokens` PRINTS THE WHOLE TABLE — every token with its light- // and dark default. Read it before hand-writing colours: most of what you+ // `astryx docs tokens/tokens-color` PRINTS THE WHOLE TABLE — every colour token+ // with its light and dark default (`astryx docs tokens` lists every category). Read it before hand-writing colours: most of what you// want already has a semantic name, and the defaults tell you what you are// moving away from.//diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjsindex c848a51311..d11180dd4a 100644--- a/packages/cli/clients/cli/commands/docs.test.mjs+++ b/packages/cli/clients/cli/commands/docs.test.mjs@@ -98,8 +98,7 @@ describe('migration docs', () => {const output = console.log.mock.calls.map(c => c[0]).join('\n');expect(output).toContain('Migration Guide');- expect(output).toContain('Recommended Order');- expect(output).toContain('Map shadcn and Radix Primitives');+ expect(output).toContain('migration');});});diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjsindex bfa87dfb3a..192b21a3da 100644--- a/packages/cli/foundation/agent-docs/agent-docs.mjs+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs@@ -26,6 +26,7 @@ import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';import {getCliInvocation} from '../env/package-manager.mjs';import {discoverComponents} from '../discovery/component-discovery.mjs';import {Project} from '../config/project.mjs';+import {cliRootNamespaceNames} from '../doc-compiler/tree.mjs';import {humanLog} from '../response/json.mjs';import {ERROR_CODES} from '../response/error-codes.mjs';import {@@ -487,6 +488,7 @@ export function generateCompressedIndex(.map(f => f.match(/^([\w-]+)\.doc\.mjs$/)).filter(/** @returns {m is RegExpMatchArray} */ (m) => m != null).map(m => m[1])+ .concat(cliRootNamespaceNames()).sort(): []);if (resolvedTopics.length > 0) {@@ -555,7 +557,18 @@ export async function renderAgentDocsBlock(`Cannot render agent docs because integration ${packageLabel} has invalid agentDocs: ${invalidAgentDocs.__agentDocsError}`,);}- const topics = (await project.docs()).names();+ const catalog = await project.docs();+ // Every name `astryx docs <name>` opens: the flat topics, and each root+ // namespace of the docs tree (a topic split into guides keeps its name).+ const topics = [+ ...catalog.names(),+ ...cliRootNamespaceNames(),+ ...catalog.treeInputs.flatMap(inputs =>+ inputs.namespaces+ .filter(input => !input.doc?.placement?.parent)+ .map(input => input.doc.name),+ ),+ ];const agentDocs = project.loadedIntegrations.flatMap(integration => {const append = integration.agentDocs?.append ?? [];if (append.length === 0) return [];diff --git a/packages/cli/foundation/config/project.test.mjs b/packages/cli/foundation/config/project.test.mjsindex bda0cb8608..d33b1e61c0 100644--- a/packages/cli/foundation/config/project.test.mjs+++ b/packages/cli/foundation/config/project.test.mjs@@ -432,7 +432,7 @@ describe('Project discovery', () => {package: '@acme/widgets',});// The CLI's own topics are still there.- expect(catalog.resolve('tokens').package).toBe('@astryxdesign/cli');+ expect(catalog.resolve('color').package).toBe('@astryxdesign/cli');expect(await project.issues()).toEqual([]);});diff --git a/packages/cli/foundation/discovery/docs-discovery.test.mjs b/packages/cli/foundation/discovery/docs-discovery.test.mjsindex a746c5ecf9..361387e8a5 100644--- a/packages/cli/foundation/discovery/docs-discovery.test.mjs+++ b/packages/cli/foundation/discovery/docs-discovery.test.mjs@@ -65,7 +65,7 @@ describe('discoverBuiltinTopics', () => {it("finds the CLI's own topics and not their localization overlays", () => {const topics = discoverBuiltinTopics();expect(Object.keys(topics).length).toBeGreaterThan(0);- expect(topics.tokens).toMatch(/assets[/\\]docs[/\\]tokens\.doc\.mjs$/);+ expect(topics.color).toMatch(/assets[/\\]docs[/\\]color\.doc\.mjs$/);for (const name of Object.keys(topics)) {expect(name).not.toMatch(/\.(zh|dense)$/);}diff --git a/packages/cli/foundation/doc-compiler/bundle.mjs b/packages/cli/foundation/doc-compiler/bundle.mjsindex d1b31a5d35..21755e7813 100644--- a/packages/cli/foundation/doc-compiler/bundle.mjs+++ b/packages/cli/foundation/doc-compiler/bundle.mjs@@ -118,10 +118,61 @@ export async function compileDocs(project, {lang = null} = {}) {);}}+ // Guides placed in a namespace, lowered, so a token reference to the+ // namespace (a flat topic split into guides, such as `tokens`) reads them+ // in placement order as one topic, as the docs API does.+ /** @type {Map<string, Array<{order: number, node: CompiledReferenceNode}>>} */+ const placedGuides = new Map();+ for (const input of inputs) {+ if (+ input.root !== 'tree' ||+ (await treeDocType(input.file)) !== 'generic'+ ) {+ continue;+ }+ const topic = await loadTopicInput(+ {+ name: input.name,+ package: input.owner,+ path: input.file,+ extensions: [],+ tree: true,+ },+ lang,+ );+ if ('error' in topic.base || 'overlayError' in topic.base) continue;+ const parent = /^namespace:(.+)$/u.exec(+ topic.base.doc?.placement?.parent ?? '',+ )?.[1];+ if (!parent) continue;+ try {+ const node = lowerReferenceTopic(topic);+ const list = placedGuides.get(parent.toLowerCase()) ?? [];+ list.push({order: topic.base.doc.placement.order ?? 0, node});+ placedGuides.set(parent.toLowerCase(), list);+ } catch {+ // Reported where the guide itself is compiled below.+ }+ }/** @param {string} name */const lowerTarget = async name => {const target = catalog.resolve(name);- return target ? (topics.get(target.name.toLowerCase()) ?? null) : null;+ if (target) return topics.get(target.name.toLowerCase()) ?? null;+ const guides = placedGuides.get(name.toLowerCase());+ if (!guides) return null;+ const ordered = [...guides].sort((a, b) => a.order - b.order);+ /** @type {Record<string, string>} */+ const sourceTitles = {};+ for (const {node} of ordered) {+ for (const [key, title] of Object.entries(node.sourceTitles)) {+ sourceTitles[key] ??= title;+ }+ }+ return /** @type {any} */ ({+ id: name,+ doc: {sections: ordered.flatMap(({node}) => node.doc.sections)},+ sourceTitles,+ });};/** @type {Array<CompiledDocNode | CompiledReferenceNode>} */diff --git a/packages/cli/foundation/doc-compiler/split-topic-keywords.test.mjs b/packages/cli/foundation/doc-compiler/split-topic-keywords.test.mjsnew file mode 100644index 0000000000..405a64a36e--- /dev/null+++ b/packages/cli/foundation/doc-compiler/split-topic-keywords.test.mjs@@ -0,0 +1,73 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A topic split into a namespace of guides indexes each term once, a+ * policy of the docs split itself (no spec clause states it). Below the CLI's own+ * root namespaces (every one but `cli`, its command and API reference), a+ * guide's search keywords are its own: none repeats a keyword its namespace,+ * a sibling, or a guide of another split topic declares. A term several+ * guides share belongs to their namespace, or to none.+ */++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';++const TREE_DIR = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../assets/docs/tree',+);++/** @returns {Promise<Map<string, any>>} every CLI tree doc, by name */+async function treeDocs() {+ /** @type {Map<string, any>} */+ const docs = new Map();+ for (const file of fs.readdirSync(TREE_DIR)) {+ if (!/^[\w-]+\.doc\.mjs$/.test(file)) continue;+ const {docs: doc} = await import(path.join(TREE_DIR, file));+ docs.set(doc.name, doc);+ }+ return docs;+}++/** @param {any} doc @returns {string | null} */+const parentOf = doc =>+ /^namespace:(.+)$/.exec(doc.placement?.parent ?? '')?.[1] ?? null;++describe('the keywords of a split topic', () => {+ it("are each declared once, and a guide's are its own", async () => {+ const docs = await treeDocs();+ /** @param {string} name */+ const rootOf = name => {+ let doc = docs.get(name);+ while (doc && parentOf(doc)) doc = docs.get(parentOf(doc));+ return doc?.name;+ };+ const roots = [...docs.values()]+ .filter(doc => doc.type === 'namespace' && !parentOf(doc) && doc.name !== 'cli')+ .map(doc => doc.name);+ expect(roots).toContain('layout');++ /** @type {Map<string, any[]>} */+ const owners = new Map();+ for (const doc of docs.values()) {+ if (!roots.includes(rootOf(doc.name))) continue;+ const own = new Set((doc.keywords ?? []).map(k => String(k).toLowerCase()));+ for (const keyword of own) {+ owners.set(keyword, [...(owners.get(keyword) ?? []), doc]);+ }+ }+ const repeats = [...owners]+ .filter(([, holders]) => holders.length > 1 && holders.some(d => d.type !== 'namespace'))+ .map(([keyword, holders]) => `${keyword}: ${holders.map(d => d.name).join(', ')}`);+ expect(repeats).toEqual([]);+ });++ it('are not repeated inside one doc', async () => {+ for (const doc of (await treeDocs()).values()) {+ const keywords = (doc.keywords ?? []).map(k => String(k).toLowerCase());+ expect(new Set(keywords).size, doc.name).toBe(keywords.length);+ }+ });+});diff --git a/packages/cli/foundation/doc-compiler/tree.mjs b/packages/cli/foundation/doc-compiler/tree.mjsindex c30c9ba570..6ba428c548 100644--- a/packages/cli/foundation/doc-compiler/tree.mjs+++ b/packages/cli/foundation/doc-compiler/tree.mjs@@ -744,6 +744,28 @@ export function treeDocFiles(dir = TREE_DOCS_DIR) {.map(file => path.join(dir, file));}+/**+ * The names of the CLI's own root namespaces (spec:AST-046 FR7): each is read+ * with `astryx docs <name>`, as a flat topic is, though no topic file has its+ * name. Read from the namespace files' text, without loading them, so a+ * synchronous caller (the agent docs block) lists them beside the flat topics.+ * A topic split into a namespace keeps its name in every such list.+ * @param {string} [dir]+ * @returns {string[]}+ */+export function cliRootNamespaceNames(dir = TREE_DOCS_DIR) {+ /** @type {string[]} */+ const names = [];+ for (const file of treeDocFiles(dir)) {+ const text = fs.readFileSync(file, 'utf8');+ if (!/["']?type["']?\s*:\s*["']namespace["']/u.test(text)) continue;+ if (/["']?placement["']?\s*:/u.test(text)) continue;+ const name = /["']?name["']?\s*:\s*["']([\w-]+)["']/u.exec(text)?.[1];+ if (name) names.push(name);+ }+ return names.sort(byText);+}+/*** The CLI's own tree inputs: the namespace docs and guides under* assets/docs/tree, and, unless left out, every typed self-doc with itsdiff --git a/packages/cli/foundation/doc-compiler/tree.test.mjs b/packages/cli/foundation/doc-compiler/tree.test.mjsindex e124071560..372c143844 100644--- a/packages/cli/foundation/doc-compiler/tree.test.mjs+++ b/packages/cli/foundation/doc-compiler/tree.test.mjs@@ -495,7 +495,7 @@ describe("the CLI's own docs tree", () => {async () => {const tree = await loadDocsTree({fresh: true});expect(tree.diagnostics).toEqual([]);- expect(tree.roots().map(node => node.route)).toEqual(['cli', 'layout']);+ expect(tree.roots().map(node => node.route)).toEqual(['cli', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);// Every slot child is a node one level below the namespace that places// it, and every node but the root is placed. Read from the tree, so a// restructure of the guides does not need this test edited.@@ -518,10 +518,11 @@ describe("the CLI's own docs tree", () => {}}expect(misplaced).toEqual([]);+ const roots = new Set(tree.roots().map(node => node.route));expect(nodes.map(node => node.route)- .filter(route => route !== 'cli' && route !== 'layout' && !placed.has(route)),+ .filter(route => !roots.has(route) && !placed.has(route)),).toEqual([]);// The reference groups the CLI generates from its own typed docs.expect(diff --git a/packages/cli/test/__golden__/docs-list.json b/packages/cli/test/__golden__/docs-list.jsonindex 99291efaa2..48ff4078d6 100644--- a/packages/cli/test/__golden__/docs-list.json+++ b/packages/cli/test/__golden__/docs-list.json@@ -15,11 +15,41 @@"description": "Commands, programmatic APIs, integration authoring, and output contracts.","package": "@astryxdesign/cli"},+ {+ "topic": "internationalization",+ "description": "Set the active locale, load catalogs, coexist with your own i18n library, handle RTL, and test translations.",+ "package": "@astryxdesign/cli"+ },{"topic": "layout","description": "Build an app layout outside-in: scaffold the regions, structure the content, tune the spacing, then adapt across widths.","package": "@astryxdesign/cli"},+ {+ "topic": "migration",+ "description": "Migrate an existing Tailwind, shadcn, or Radix app to the design system incrementally — setup, component replacement, and verification.",+ "package": "@astryxdesign/cli"+ },+ {+ "topic": "styling",+ "description": "Customize component appearance: xstyle, Tailwind, className, rest props, compound components, data attribute selectors, tokens, and StyleX setup.",+ "package": "@astryxdesign/cli"+ },+ {+ "topic": "styling-libraries",+ "description": "Integrate Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, and non-CSS renderers with system tokens.",+ "package": "@astryxdesign/cli"+ },+ {+ "topic": "tokens",+ "description": "Complete reference for color, data visualization, syntax, spacing, size, border, focus, radius, shadow, motion, and typography tokens.",+ "package": "@astryxdesign/cli"+ },+ {+ "topic": "typography",+ "description": "Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.",+ "package": "@astryxdesign/cli"+ },{"topic": "unorganized","description": "Every topic that no section places yet. Each keeps its own name; open one by it.",diff --git a/scripts/check-theme-template.test.mjs b/scripts/check-theme-template.test.mjsindex 5f66664ba6..45827ce403 100644--- a/scripts/check-theme-template.test.mjs+++ b/scripts/check-theme-template.test.mjs@@ -33,13 +33,13 @@ import path from 'node:path';import {createHash} from 'node:crypto';import {fileURLToPath} from 'node:url';import {describe, it, expect} from 'vitest';+import {docs} from '../packages/cli/api/docs/docs.mjs';const __dirname = path.dirname(fileURLToPath(import.meta.url));const REPO_ROOT = path.resolve(__dirname, '..');const TEMPLATE = path.join(REPO_ROOT, 'packages/cli/assets/theme.template.ts');const THEME_SRC = path.join(REPO_ROOT, 'packages/core/src/theme');const CORE_SRC = path.join(REPO_ROOT, 'packages/core/src');-const DOCS_DIR = path.join(REPO_ROOT, 'packages/cli/assets/docs');const NEUTRAL_PALETTE = path.join(REPO_ROOT,'packages/themes/neutral/src/neutralPalettes.ts',@@ -160,13 +160,20 @@ function themingTargets() {return {targets, publicVars};}-/** Doc topics `astryx docs <topic>` can print. */-function docTopics() {- return fs- .readdirSync(DOCS_DIR)- .map(f => f.match(/^([\w-]+)\.doc\.mjs$/))- .filter(Boolean)- .map(m => m[1]);+/**+ * Whether `astryx docs <route>` prints something: a flat topic, or a node of+ * the docs tree (a namespace such as `tokens`, or a guide such as+ * `tokens/tokens-color`), resolved the way the command resolves it.+ * @param {string} route+ * @returns {Promise<boolean>}+ */+async function docsRouteExists(route) {+ try {+ await docs(route, undefined, {index: true});+ return true;+ } catch {+ return false;+ }}// ---------------------------------------------------------------------------@@ -364,14 +371,19 @@ describe('theme template stays in sync with the theme system', () => {).toEqual([]);});- it('cites only doc topics that exist', () => {- const topics = new Set(docTopics());+ it('cites only doc topics that exist', async () => {const cited = [...new Set(- [...template.matchAll(/astryx docs ([a-z-]+)/g)].map(m => m[1]),+ [...template.matchAll(/astryx docs ([a-z-]+(?:\/[a-z-]+)*)/g)].map(+ m => m[1],+ ),),];- const dead = cited.filter(t => !topics.has(t));+ expect(cited.length).toBeGreaterThan(0);+ const dead = [];+ for (const route of cited) {+ if (!(await docsRouteExists(route))) dead.push(route);+ }expect(dead,`The template tells authors to run \`astryx docs ${dead.join('`, `astryx docs ')}\`, ` +diff --git a/scripts/generate-token-docs.mjs b/scripts/generate-token-docs.mjsindex 58d4ca99a9..ead4d4d878 100644--- a/scripts/generate-token-docs.mjs+++ b/scripts/generate-token-docs.mjs@@ -3,19 +3,27 @@/*** @file generate-token-docs.mjs- * @description Generates packages/cli/assets/docs/tokens.doc.mjs from the sources- * of truth: packages/core/src/theme/tokens.stylex.ts, plus the domain tokens in+ * @description Generates the tokens namespace (tree/tokens.doc.mjs), one child+ * guide per token category (tree/tokens-<key>.doc.mjs), and a hand-written+ * usage guide (tree/tokens-usage.doc.mjs), from the sources of truth:+ * packages/core/src/theme/tokens.stylex.ts, plus the domain tokens in* packages/core/src/theme/domainTokens/dataTokens.ts (data visualization) and* packages/core/src/theme/syntax/tokens.ts (code syntax).*- * Run: node scripts/generate-token-docs.mjs- * CI: `node scripts/generate-token-docs.mjs --check` fails on drift.+ * The namespace carries the topic's search keywords; a guide adds none of+ * its own, so search indexes each guide by its title, description, and text,+ * as it indexed the topic's sections. Each token is written once, in its+ * category's guide. A token reference+ * (`{type: 'token-ref', topic: 'tokens', section: 'Color Tokens'}`) resolves+ * through the tokens namespace to the guide that holds the table.*- * Reads the *Defaults export objects from those files, groups them by- * category, and writes a ReferenceDoc-shaped .doc.mjs file.+ * Run: node scripts/generate-token-docs.mjs+ * CI: `node scripts/generate-token-docs.mjs --check` fails on drift, and on a+ * generated tokens guide (or its translation overlay) that no category+ * writes any more.*/-import {readFileSync, writeFileSync} from 'node:fs';+import {readFileSync, readdirSync, unlinkSync, writeFileSync} from 'node:fs';import {resolve, dirname} from 'node:path';import {fileURLToPath} from 'node:url';@@ -30,7 +38,7 @@ const SYNTAX_TOKENS_SRC = resolve(ROOT,'packages/core/src/theme/syntax/tokens.ts',);-const TOKENS_DOC = resolve(ROOT, 'packages/cli/assets/docs/tokens.doc.mjs');+const TREE_DIR = resolve(ROOT, 'packages/cli/assets/docs/tree');// ---------------------------------------------------------------------------// 1. Parse token groups from source@@ -94,6 +102,15 @@ function lightDarkRow(name, value) {return [name, value, value];}+/**+ * Convert a camelCase key to a kebab-case file-safe slug.+ * @param {string} key+ * @returns {string}+ */+function keyToSlug(key) {+ return key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();+}+/** Map of group name → { exportName, file?, title, description, headers } */const groups = [{@@ -246,16 +263,24 @@ const groups = [];// ----------------------------------------------------------------------------// 2. Build sections+// 2. Build per-category child docs and collect sections for overview// ----------------------------------------------------------------------------const sections = [];+const totalTokens = groups.reduce(+ (sum, g) => sum + extractDefaults(g.exportName, g.file).length,+ 0,+);++/** @type {Array<{slug: string, output: string, path: string, tokenCount: number}>} */+const childFiles = [];+let order = 10;for (const group of groups) {const pairs = extractDefaults(group.exportName, group.file);if (pairs.length === 0) continue;const rows = pairs.map(([name, value]) => group.formatRow(name, value));+ const slug = `tokens-${keyToSlug(group.key)}`;/** @type {import('@astryxdesign/cli/authoring').ReferenceContentBlock[]} */const content = [@@ -265,18 +290,91 @@ for (const group of groups) {const section = {title: group.title, content};if (group.previewType) section.previewType = group.previewType;- sections.push(section);++ const childDoc = {+ type: 'generic',+ name: slug,+ title: group.title,+ placement: {parent: 'namespace:tokens', slot: 'guides', order},+ category: 'foundations',+ description: group.description,+ sections: [section],+ };++ const childOutput = `\+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Source: packages/core/src/theme/tokens.stylex.ts,+// dataTokens.stylex.ts, and syntax/tokens.ts+// Run: node scripts/generate-token-docs.mjs++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = ${JSON.stringify(childDoc, null, 2)};+`;++ childFiles.push({+ slug,+ output: childOutput,+ path: resolve(TREE_DIR, `${slug}.doc.mjs`),+ tokenCount: pairs.length,+ });++ order += 10;}-// Add a usage section at the end (hand-written, not generated)-sections.push({+// ---------------------------------------------------------------------------+// 3. Build the namespace doc+// ---------------------------------------------------------------------------++const namespaceDoc = {+ type: 'namespace',+ name: 'tokens',+ title: 'All Tokens',+ summary:+ 'Complete reference for color, data visualization, syntax, spacing, size, border, focus, radius, shadow, motion, and typography tokens.',+ keywords: ['design tokens', 'css variables', 'custom properties'],+ slots: {+ guides: {title: 'Token Categories', accepts: {kinds: ['generic']}},+ },+};++const namespaceOutput = `\+// Copyright (c) Meta Platforms, Inc. and affiliates.++// AUTO-GENERATED — do not edit manually.+// Run: node scripts/generate-token-docs.mjs+// Total: ${totalTokens} tokens across ${groups.length} categories.++/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */+export const docs = ${JSON.stringify(namespaceDoc, null, 2)};+`;++const namespacePath = resolve(TREE_DIR, 'tokens.doc.mjs');++// ---------------------------------------------------------------------------+// 4. Build a usage child (hand-written content, generated file)+// ---------------------------------------------------------------------------++const usageSlug = 'tokens-usage';+const usageDoc = {+ type: 'generic',+ name: usageSlug,title: 'Usage in StyleX',- content: [+ placement: {parent: 'namespace:tokens', slot: 'guides', order},+ category: 'foundations',+ description:+ 'How to import and use token variables in StyleX styles.',+ sections: [{- type: 'code',- lang: 'tsx',- label: 'Using token imports',- code: `import * as stylex from '@stylexjs/stylex';+ title: 'Usage in StyleX',+ content: [+ {+ type: 'code',+ lang: 'tsx',+ label: 'Using token imports',+ code: `import * as stylex from '@stylexjs/stylex';import {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';import {dataVars} from '@astryxdesign/core/theme/dataTokens.stylex';@@ -293,75 +391,108 @@ const styles = stylex.create({height: sizeVars['--size-element-md'],},});`,- },- {- type: 'prose',- text: 'See {@link generic:styling} for how to apply tokens via xstyle, className, and compound component patterns. See {@link generic:author-a-theme} for overriding tokens with defineTheme.',+ },+ {+ type: 'prose',+ text: 'See {@link namespace:styling} for how to apply tokens via xstyle, className, and compound component patterns. See {@link generic:author-a-theme} for overriding tokens with defineTheme.',+ },+ ],},],-});--// ----------------------------------------------------------------------------// 3. Write output (or check for drift)-// -----------------------------------------------------------------------------const isCheck = process.argv.includes('--check');--// Count total tokens for the header comment-const totalTokens = groups.reduce(- (sum, g) => sum + extractDefaults(g.exportName, g.file).length,- 0,-);+};-const output = `\+const usageOutput = `\// Copyright (c) Meta Platforms, Inc. and affiliates.// AUTO-GENERATED — do not edit manually.-// Source: packages/core/src/theme/tokens.stylex.ts,-// dataTokens.stylex.ts, and syntax/tokens.ts// Run: node scripts/generate-token-docs.mjs-// Total: ${totalTokens} tokens across ${groups.length} categories./** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */-export const docs = ${JSON.stringify(- {- name: 'tokens',- title: 'All Tokens',- category: 'foundations',- description:- 'Complete reference for color, data visualization, syntax, spacing, size, border, focus, radius, shadow, motion, and typography tokens.',- // Words readers search for that the titles do not use (`astryx search`).- keywords: ['design tokens', 'css variables', 'custom properties'],- sections,- },- null,- 2,-)};+export const docs = ${JSON.stringify(usageDoc, null, 2)};`;+const usagePath = resolve(TREE_DIR, `${usageSlug}.doc.mjs`);++// ---------------------------------------------------------------------------+// 5. Write output (or check for drift)+// ---------------------------------------------------------------------------++const isCheck = process.argv.includes('--check');++/** @type {Array<{path: string, output: string, label: string}>} */+const allFiles = [+ {path: namespacePath, output: namespaceOutput, label: 'tree/tokens.doc.mjs (namespace)'},+ ...childFiles.map(f => ({+ path: f.path,+ output: f.output,+ label: `tree/${f.slug}.doc.mjs (${f.tokenCount} tokens)`,+ })),+ {path: usagePath, output: usageOutput, label: `tree/${usageSlug}.doc.mjs (usage)`},+];++// A generated tokens guide no category writes any more (a renamed or removed+// category), or a translation overlay whose guide is gone: a reader would+// still find it, so check mode fails on it and a write removes it.+const written = new Set(allFiles.map(f => f.path));+const treeFiles = readdirSync(TREE_DIR).filter(file =>+ /^tokens(?:-[\w-]+)?\.doc(?:\.(?:dense|zh))?\.mjs$/.test(file),+);+const orphanGuides = treeFiles+ .filter(file => /\.doc\.mjs$/.test(file))+ .map(file => resolve(TREE_DIR, file))+ .filter(+ filePath =>+ !written.has(filePath) &&+ readFileSync(filePath, 'utf-8').includes('AUTO-GENERATED'),+ );+const orphans = [+ ...orphanGuides,+ ...treeFiles+ .filter(file => /\.doc\.(?:dense|zh)\.mjs$/.test(file))+ .map(file => resolve(TREE_DIR, file))+ .filter(filePath => {+ const base = filePath.replace(/\.doc\.(?:dense|zh)\.mjs$/, '.doc.mjs');+ return orphanGuides.includes(base) || !treeFiles.includes(base.slice(TREE_DIR.length + 1));+ }),+];+if (isCheck) {- // CI mode: compare generated output to existing file- let existing = '';- try {- existing = readFileSync(TOKENS_DOC, 'utf-8');- } catch {+ let failed = false;+ for (const filePath of orphans) {console.error(- '✗ tokens.doc.mjs does not exist. Run: node scripts/generate-token-docs.mjs',+ `✗ ${filePath.slice(ROOT.length + 1)} is not written by any token category. Run: node scripts/generate-token-docs.mjs`,);- process.exit(1);+ failed = true;}- if (existing !== output) {- console.error(- '✗ tokens.doc.mjs is out of date. Run: node scripts/generate-token-docs.mjs',- );- process.exit(1);+ for (const {path: filePath, output, label} of allFiles) {+ let existing = '';+ try {+ existing = readFileSync(filePath, 'utf-8');+ } catch {+ console.error(`✗ ${label} does not exist. Run: node scripts/generate-token-docs.mjs`);+ failed = true;+ continue;+ }+ if (existing !== output) {+ console.error(`✗ ${label} is out of date. Run: node scripts/generate-token-docs.mjs`);+ failed = true;+ }}- console.log(`✓ tokens.doc.mjs is up to date (${totalTokens} tokens)`);+ if (failed) process.exit(1);+ console.log(`✓ All token docs are up to date (${totalTokens} tokens, ${allFiles.length} files)`);} else {- writeFileSync(TOKENS_DOC, output);- const lineCount = output.split('\n').length;+ for (const {path: filePath, output} of allFiles) {+ writeFileSync(filePath, output);+ }+ for (const filePath of orphans) {+ unlinkSync(filePath);+ console.log(` removed ${filePath.slice(ROOT.length + 1)}`);+ }console.log(- `✓ Generated ${TOKENS_DOC} (${totalTokens} tokens, ${lineCount} lines)`,+ `✓ Generated ${allFiles.length} token doc files (${totalTokens} tokens)`,);+ for (const {label} of allFiles) {+ console.log(` ${label}`);+ }}diff --git a/scripts/split-topic-consumers.test.mjs b/scripts/split-topic-consumers.test.mjsnew file mode 100644index 0000000000..5b5c32c3a0--- /dev/null+++ b/scripts/split-topic-consumers.test.mjs@@ -0,0 +1,85 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Every repo consumer that lists or reads doc topics by name still finds+ * a topic after it is split into a docs-tree namespace: a+ * root namespace answers `astryx docs <name>` as the flat topic did, so no+ * list, generated file, or check may treat it as missing. The docsite's own+ * page check lives in apps/docsite (route-resolution.test.ts); the theme+ * template's citations are checked in check-theme-template.test.mjs.+ */++import {execFileSync} from 'node:child_process';+import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import {docs} from '../packages/cli/api/docs/docs.mjs';+import {cliRootNamespaceNames} from '../packages/cli/foundation/doc-compiler/tree.mjs';+import {generateCompressedIndex} from '../packages/cli/foundation/agent-docs/agent-docs.mjs';++const REPO_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '..',+);+const SLOW = 60_000;++/** The CLI's root namespaces other than `cli`, its command and API reference. */+const splitTopics = cliRootNamespaceNames().filter(name => name !== 'cli');++describe('consumers of a topic split into a namespace', () => {+ it('finds the split topics', () => {+ expect(splitTopics).toContain('layout');+ });++ it(+ 'opens each one with astryx docs <name>',+ async () => {+ for (const name of splitTopics) {+ const read = await docs(name);+ expect(read, name).toMatchObject({+ type: 'docs.node',+ data: {kind: 'namespace', route: name},+ });+ }+ },+ SLOW,+ );++ it('lists each one in the agent docs block, as a flat topic is listed', () => {+ const line = generateCompressedIndex('1.0.0')+ .split('\n')+ .find(l => l.trimStart().startsWith('docs <topic>'));+ // The block names a few key topics; each one that is a split topic must+ // still appear, so a split never drops it from every AGENTS.md.+ for (const key of ['getting-started', 'principles', 'tokens', 'theme']) {+ expect(line, key).toContain(key);+ }+ });++ it(+ 'keeps every split foundation topic in the sandbox doc preview',+ () => {+ const script = path.join(+ REPO_ROOT,+ 'apps/sandbox/scripts/generate-foundation-docs.mjs',+ );+ const output = path.join(+ REPO_ROOT,+ 'apps/sandbox/src/generated/foundationDocs.json',+ );+ fs.mkdirSync(path.dirname(output), {recursive: true});+ execFileSync(process.execPath, [script], {cwd: REPO_ROOT, stdio: 'pipe'});+ const preview = JSON.parse(fs.readFileSync(output, 'utf8'));+ for (const [name, doc] of Object.entries(preview)) {+ if (name.startsWith('__')) continue;+ expect(doc.sections.length, name).toBeGreaterThan(0);+ }+ for (const name of splitTopics.filter(n => n in preview)) {+ expect(preview[name].title, name).toBeTruthy();+ }+ expect(Object.keys(preview)).toContain('typography');+ },+ SLOW,+ );+});