An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): anchor dense/zh doc overlays to base sections instead of array index (#3891)
AKff5dfca6170f
diff --git a/.changeset/doc-overlay-anchors.md b/.changeset/doc-overlay-anchors.mdnew file mode 100644index 0000000000..3c76a049d4--- /dev/null+++ b/.changeset/doc-overlay-anchors.md@@ -0,0 +1,14 @@+---+'@astryxdesign/cli': patch+'@astryxdesign/core': patch+---++[fix] Anchor --dense / --zh doc overlays to their base sections (#2182)++The compressed and translated reference docs were merged into the base doc **by array position**, so an overlay whose sections were ordered differently — or which omitted one — grafted every title onto the wrong body.++The result was actively misleading. `astryx docs tokens --dense` printed the entire colour table under a heading that read `## Spacing`, above prose saying "gap props use space0-space12". An agent reading that learns spacing tokens are named `--color-*`. `docs theme --dense` lost the `Extending a Theme` and `Token Utilities` sections entirely and emitted `useTheme` twice, and `docs theme --zh` printed four headings in both Chinese and English. This is what turned a doc bug into a codegen bug: `CLAUDE.md` instructs every AI agent to run `docs tokens --dense` and `docs theme --dense` at bootstrap.++Overlay sections now name the base section they override (`section: 'Spacing Tokens'`), so order no longer matters and an overlay may cover any subset — sections it doesn't name keep their base content. A test asserts every overlay anchors to a real base section, so a future overlay cannot silently drift back.++@AKnassadiff --git a/packages/cli/docs/layout.doc.dense.mjs b/packages/cli/docs/layout.doc.dense.mjsindex 3997f32445..dd4c41e4ea 100644--- a/packages/cli/docs/layout.doc.dense.mjs+++ b/packages/cli/docs/layout.doc.dense.mjs@@ -7,6 +7,7 @@ export const docsDense = {'frame-first app layout: shell choice, region budgets, cards vs rows',sections: [{+ section: 'Frame First',title: 'Frame First',content: [{@@ -26,6 +27,7 @@ export const docsDense = {],},{+ section: 'App Archetypes',title: 'App Archetypes',content: [{@@ -40,6 +42,7 @@ export const docsDense = {],},{+ section: 'Cards vs Rows',title: 'Cards vs Rows',content: [{@@ -67,6 +70,7 @@ export const docsDense = {],},{+ section: 'Panels and Inspectors',title: 'Panels and Inspectors',content: [{@@ -77,6 +81,7 @@ export const docsDense = {],},{+ section: 'Responsive Contract',title: 'Responsive Contract',content: [{diff --git a/packages/cli/docs/principles.doc.dense.mjs b/packages/cli/docs/principles.doc.dense.mjsindex 6cceb54b0a..95dbd9f2c7 100644--- a/packages/cli/docs/principles.doc.dense.mjs+++ b/packages/cli/docs/principles.doc.dense.mjs@@ -5,10 +5,10 @@export const docsDense = {description: 'core design principles + rules for the design system',sections: [- { title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },- { title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },- { title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },- { title: 'Anti-Patterns', content: [{ 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 (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },- { title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },+ { section: 'Design Philosophy', title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },+ { section: 'Rules', title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', '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. See astryx docs styling.' }] },+ { section: 'Anti-Patterns', title: 'Anti-Patterns', content: [{ 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 (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },+ { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },],};diff --git a/packages/cli/docs/principles.doc.zh.mjs b/packages/cli/docs/principles.doc.zh.mjsindex 977e916930..926b7b719f 100644--- a/packages/cli/docs/principles.doc.zh.mjs+++ b/packages/cli/docs/principles.doc.zh.mjs@@ -5,10 +5,10 @@export const docsZh = {description: 'XDS 核心设计原则和规则。',sections: [- { title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },- { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 astryx docs layout)', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },- { title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },- { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 astryx docs layout)', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },- { title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },+ { section: 'Design Philosophy', title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },+ { section: 'Rules', title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 astryx docs layout)', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },+ { section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },+ { section: 'Anti-Patterns', title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 astryx docs layout)', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },+ { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },],};diff --git a/packages/cli/docs/theme.doc.dense.mjs b/packages/cli/docs/theme.doc.dense.mjsindex 14dc8937b2..b57da8b12e 100644--- a/packages/cli/docs/theme.doc.dense.mjs+++ b/packages/cli/docs/theme.doc.dense.mjs@@ -5,17 +5,17 @@export const docsDense = {description: 'Theme provider, custom themes, light/dark, component overrides',sections: [- { title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },- { title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },- { title: 'Props', content: [null] },- { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },- { title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },- { title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx astryx component <Name>` for details.' }, null, null, null, null] },- { title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },- { title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },- { title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },- { title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },- { title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },- { title: 'useTheme', content: [null, { type: 'prose', text: 'read-only. manage state at app level.' }] },+ { section: 'Quick Start', title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },+ { section: 'Available Themes', title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },+ { section: 'Theme Props', title: 'Props', content: [null] },+ { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },+ { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },+ { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx astryx component <Name>` for details.' }, null, null, null, null] },+ { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },+ { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },+ { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },+ { section: 'Light/Dark Mode', title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },+ { section: 'Nesting Themes', title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },+ { section: 'useTheme Hook', title: 'useTheme', content: [null, { type: 'prose', text: 'read-only. manage state at app level.' }] },],};diff --git a/packages/cli/docs/theme.doc.zh.mjs b/packages/cli/docs/theme.doc.zh.mjsindex 6a6a420836..fb1f953882 100644--- a/packages/cli/docs/theme.doc.zh.mjs+++ b/packages/cli/docs/theme.doc.zh.mjs@@ -5,15 +5,15 @@export const docsZh = {description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',sections: [- { title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS(需配合 theme.css)。' }] },- { title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题:neutral(推荐起点)、butter、chocolate、gothic(仅暗色)、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版(运行时注入)。@astryxdesign/theme-{name}/built = 优化版(配合 theme.css)。' }] },- { title: 'Theme 属性', content: [null] },- { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导(推荐)或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },- { title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置(typography、radius、motion)+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },- { title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, null] },- { title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时:useInsertionEffect 在客户端注入样式。构建:静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },- { title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'(默认)跟随系统偏好。" }, null, null] },- { title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },- { title: 'useTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式,在应用层管理状态并传递给 <Theme>。' }] },+ { section: 'Quick Start', title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS(需配合 theme.css)。' }] },+ { section: 'Available Themes', title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题:neutral(推荐起点)、butter、chocolate、gothic(仅暗色)、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版(运行时注入)。@astryxdesign/theme-{name}/built = 优化版(配合 theme.css)。' }] },+ { section: 'Theme Props', title: 'Theme 属性', content: [null] },+ { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导(推荐)或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },+ { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置(typography、radius、motion)+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },+ { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, null] },+ { section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时:useInsertionEffect 在客户端注入样式。构建:静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },+ { section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'(默认)跟随系统偏好。" }, null, null] },+ { section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },+ { section: 'useTheme Hook', title: 'useTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式,在应用层管理状态并传递给 <Theme>。' }] },],};diff --git a/packages/cli/docs/tokens.doc.dense.mjs b/packages/cli/docs/tokens.doc.dense.mjsindex 8340ffd8b1..319f06a088 100644--- a/packages/cli/docs/tokens.doc.dense.mjs+++ b/packages/cli/docs/tokens.doc.dense.mjs@@ -5,12 +5,11 @@export const docsDense = {description: 'spacing/color/radius/type/shadow token ref',sections: [- { title: 'Spacing', content: [{ type: 'prose', text: 'defined in tokens.stylex.ts. gap props use space0-space12.' }, null] },- { title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },- { title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },- { title: 'Radius', content: [null] },- { title: 'Elevation', content: [null] },- { title: 'Typography', content: [null, null, null, null] },- { title: 'StyleX Usage', content: [null, null] },+ { 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: 'defined in tokens.stylex.ts. gap props use space0-space12.' }, 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/docs/tokens.doc.zh.mjs b/packages/cli/docs/tokens.doc.zh.mjsindex 83b4875b3d..8684668050 100644--- a/packages/cli/docs/tokens.doc.zh.mjs+++ b/packages/cli/docs/tokens.doc.zh.mjs@@ -5,12 +5,11 @@export const docsZh = {description: '间距、颜色、圆角、排版和阴影设计令牌参考。',sections: [- { title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, null] },- { title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },- { title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色,支持 light-dark() 自动切换模式。' }, null, null, null] },- { title: '圆角令牌', content: [null] },- { title: '阴影令牌', content: [null] },- { title: '排版令牌', content: [null, null, null, null] },- { title: 'StyleX 用法', content: [null, null] },+ { section: 'Color Tokens', title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色,支持 light-dark() 自动切换模式。' }, null, null, null] },+ { section: 'Spacing Tokens', title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, 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/src/api/docOverlays.test.mjs b/packages/cli/src/api/docOverlays.test.mjsnew file mode 100644index 0000000000..0ee56249ea--- /dev/null+++ b/packages/cli/src/api/docOverlays.test.mjs@@ -0,0 +1,133 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Guards the --dense / --zh reference-doc overlays against drift (#2182).+ * @input packages/cli/docs/{topic}.doc.mjs and its .doc.dense.mjs / .doc.zh.mjs overlays.+ * @output Vitest failures naming any overlay section that does not anchor to a+ * real base section, or whose content overrides land on the wrong block type.+ * @position Regression gate for the docs API. Sits with the loader it guards.+ *+ * The overlays used to be applied BY ARRAY POSITION, so an overlay whose+ * sections were ordered differently from the base grafted every title onto the+ * wrong body. `docs tokens --dense` printed the entire colour table under a+ * heading that said "## Spacing", above prose reading "gap props use+ * space0-space12" — teaching any agent that spacing tokens are named+ * `--color-*`. CLAUDE.md tells every agent to run that exact command at+ * bootstrap, which is what made a doc bug into a codegen bug.+ *+ * Overlays now anchor to a base section by title, so a reordered or+ * partial overlay is correct by construction. These tests keep it that way.+ */++import {describe, it, expect} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {pathToFileURL} from 'node:url';+import {docs} from './docs.mjs';++const DOCS_DIR = path.join(import.meta.dirname, '..', '..', 'docs');++/** Every base reference doc that has at least one overlay. */+function overlayPairs() {+ const pairs = [];+ for (const file of fs.readdirSync(DOCS_DIR)) {+ const m = file.match(/^(.+)\.doc\.(dense|zh)\.mjs$/);+ if (!m) continue;+ const [, topic, variant] = m;+ pairs.push({+ topic,+ variant,+ basePath: path.join(DOCS_DIR, `${topic}.doc.mjs`),+ overlayPath: path.join(DOCS_DIR, file),+ });+ }+ return pairs;+}++async function load(p) {+ return await import(pathToFileURL(p).href);+}++describe('reference doc overlays (#2182)', () => {+ const pairs = overlayPairs();++ it('finds overlays to check', () => {+ // A rename that stops overlays being discovered must not silently pass.+ expect(pairs.length).toBeGreaterThan(0);+ });++ for (const {topic, variant, basePath, overlayPath} of pairs) {+ it(`${topic} --${variant}: every overlay section anchors to a real base section`, async () => {+ const base = await load(basePath);+ const overlayMod = await load(overlayPath);+ const overlay = overlayMod.docsDense || overlayMod.docsZh;++ const baseTitles = base.docs.sections.map(s => s.title);+ const unanchored = (overlay.sections || [])+ .filter(s => s.section == null || !baseTitles.includes(s.section))+ .map(s => s.section ?? `(no anchor) "${s.title}"`);++ expect(+ unanchored,+ `${topic}.doc.${variant}.mjs has section entries that do not name a ` ++ `base section via \`section:\`. Without an anchor the overlay is ` ++ `applied by array position, which silently grafts each title onto ` ++ `the wrong body. Base sections are: ${baseTitles.join(', ')}.`,+ ).toEqual([]);+ });++ it(`${topic} --${variant}: no base section is overridden twice`, async () => {+ const overlayMod = await load(overlayPath);+ const overlay = overlayMod.docsDense || overlayMod.docsZh;+ const anchors = (overlay.sections || []).map(s => s.section);+ const dupes = anchors.filter((a, i) => anchors.indexOf(a) !== i);+ expect(dupes, `${topic}.doc.${variant}.mjs overrides the same base section twice`).toEqual([]);+ });+ }+});++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-');+ });++ 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);+ });++ it('does not lose the Extending a Theme section from docs theme --dense', async () => {+ const dense = await docs('theme', null, {dense: true});+ const titles = dense.data.sections.map(s => s.title);+ expect(titles).toContain('Extending a Theme');+ });++ it('does not emit a duplicate useTheme heading in docs theme --dense', async () => {+ const dense = await docs('theme', null, {dense: true});+ const titles = dense.data.sections.map(s => s.title.toLowerCase());+ const useTheme = titles.filter(t => t.includes('usetheme'));+ expect(useTheme.length).toBe(1);+ });++ it('does not leak English headings into docs theme --zh', async () => {+ const zh = await docs('theme', null, {zh: true});+ const titles = zh.data.sections.map(s => s.title);+ // Every section the overlay translates must appear once, in Chinese only.+ expect(titles).not.toContain('Light/Dark Mode');+ expect(titles).toContain('亮/暗模式');+ });+});diff --git a/packages/cli/src/api/docs.mjs b/packages/cli/src/api/docs.mjsindex 8a6146492f..4230db403c 100644--- a/packages/cli/src/api/docs.mjs+++ b/packages/cli/src/api/docs.mjs@@ -38,11 +38,23 @@ async function loadReferenceDocs(docPath, {lang} = {}) {const translation = translationMod.docsZh || translationMod.docsDense;if (!translation) return docs;+ // Overlays are keyed to a base section by title (`section`), not by array+ // position. Position-keying silently grafted each overlay title onto whatever+ // base section happened to share its index, so an overlay that omitted or+ // reordered a section corrupted every section after it — `docs tokens --dense`+ // printed the colour table under a "Spacing" heading (#2182). An overlay may+ // now cover any subset of sections, in any order; sections it does not name+ // keep their base content.+ const bySection = new Map();+ for (const ts of translation.sections ?? []) {+ if (ts?.section != null) bySection.set(ts.section, ts);+ }+return {...docs,description: translation.description || docs.description,- sections: docs.sections.map((section, si) => {- const ts = translation.sections?.[si];+ sections: docs.sections.map(section => {+ const ts = bySection.get(section.title);if (!ts) return section;return {...section,diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex dc3486ed5e..4deebee913 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -616,9 +616,7 @@ export interface SubComponentDoc extends Omit<BaseDoc, 'usage'> {* in its own file inside its parent's directory.*/export type ComponentDoc =- | SingleComponentDoc- | MultiComponentDoc- | SubComponentDoc;+ SingleComponentDoc | MultiComponentDoc | SubComponentDoc;/*** Translation overlay for component documentation.@@ -781,16 +779,23 @@ export interface ReferenceDoc {export interface ReferenceTranslationDoc {/** Translated/compressed description. */description: string;- /** Section overrides. Array indices must match base doc sections. */+ /** Section overrides, keyed to base sections by `section`. Order does not+ * matter, and an overlay may cover any subset — sections it does not name+ * keep their base content. (These used to be matched by array index, which+ * meant a reordered or partial overlay grafted every title onto the wrong+ * body: `docs tokens --dense` printed the colour table under a "Spacing"+ * heading. See #2182.) */sections: {- /** Translated section title. */+ /** Title of the BASE section this entry overrides, verbatim and in English+ * (e.g. 'Spacing Tokens'). Must match a section in the base doc. */+ section: string;+ /** Translated/compressed section title, shown in place of the base title. */title: string;- /** Content block overrides. Only prose and list blocks need entries.- * Use null for blocks that don't change (code, table). */+ /** Content block overrides, by index within the anchored base section.+ * Only prose and list blocks need entries. Use null for blocks that don't+ * change (code, table). */content: (- | {type: 'prose'; text: string}- | {type: 'list'; items: string[]}- | null+ {type: 'prose'; text: string} | {type: 'list'; items: string[]} | null)[];}[];}