Skip to content

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.md
new file mode 100644
index 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.
+
+@AKnassa
diff --git a/packages/cli/docs/layout.doc.dense.mjs b/packages/cli/docs/layout.doc.dense.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.ts
index 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
)[];
}[];
}