@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/assets/docs/layout.doc.mjs

@@ -34,9 +34,40 @@ export const docs = {
       ],
     },
     {
+      id: 'scaffold',
       title: 'Scaffold',
       content: [
-        {type: 'heading', level: 3, text: 'Shell'},
+        {
+          type: 'prose',
+          text: 'Pick the shell, budget each region, and choose navigation, before any content exists. Shell and Navigation cover each step; these rules hold for both.',
+        },
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Decide the frame, region width budgets, and fill or capped before any content exists',
+            'State the reason for the navigation choice, or inherit the template pairing',
+            'Reserve raw px for structural widths; interior spacing uses tokens',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Build content-first and wrap each section in a Card, producing a padded scroll column',
+            'Stretch prose, forms, or lists across a wide region instead of capping with contentWidth',
+            'SideNav when the nav is really filters or controls, or must hold wide elements like breadcrumbs',
+            'TopNav when top-slot ownership is unclear, or the hierarchy is deep or still growing',
+            'Both bars when the ecosystem layer is thin, so the second only wastes space',
+            'Deviate from the template navigation pairing without a stated reason',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'shell',
+      title: 'Shell',
+      content: [
         {
           type: 'prose',
           text: 'Pick the shell and budget its regions before any content exists. Structural widths are the one place raw px belongs; everything inside them uses the spacing scale.',
@@ -75,8 +106,12 @@ export const docs = {
           type: 'prose',
           text: 'Verify: every region has a width budget, a fill-or-capped decision, and a container policy written down before any content exists.',
         },
-
-        {type: 'heading', level: 3, text: 'Navigation'},
+      ],
+    },
+    {
+      id: 'navigation',
+      title: 'Navigation',
+      content: [
         {
           type: 'prose',
           text: 'When the frame leaves navigation open, default to SideNav: it absorbs destinations you have not planned yet. App type and destination count are guiding indicators, not determining rules.',
@@ -108,35 +143,47 @@ export const docs = {
           type: 'prose',
           text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the template to start from; scaffold it and the pairing is already wired up.',
         },
-
-        {type: 'heading', level: 3, text: 'Best practices'},
+      ],
+    },
+    {
+      id: 'structure',
+      title: 'Structure',
+      content: [
+        {
+          type: 'prose',
+          text: 'Rank the content in each region, then pick the weakest container that groups it. Type hierarchy, Card or rows, Headers and footers, and Side panels cover each step; these rules hold for all of them.',
+        },
         {
           type: 'list',
           style: 'do',
           items: [
-            'Decide the frame, region width budgets, and fill or capped before any content exists',
-            'State the reason for the navigation choice, or inherit the template pairing',
-            'Reserve raw px for structural widths; interior spacing uses tokens',
+            'One lead per region; rank with weight and color; one primary action',
+            'Leave body copy at its defaults; demote by weight and color, not size',
+            'Default to Section; use the weakest container that reads as a group',
+            'Render collections as rows (Table or List), edge-to-edge with dividers',
+            'Open a fixed-width side panel on select; let it yield width at narrow sizes',
           ],
         },
         {
           type: 'list',
           style: 'dont',
           items: [
-            'Build content-first and wrap each section in a Card, producing a padded scroll column',
-            'Stretch prose, forms, or lists across a wide region instead of capping with contentWidth',
-            'SideNav when the nav is really filters or controls, or must hold wide elements like breadcrumbs',
-            'TopNav when top-slot ownership is unclear, or the hierarchy is deep or still growing',
-            'Both bars when the ecosystem layer is thin, so the second only wastes space',
-            'Deviate from the template navigation pairing without a stated reason',
+            'Grey and shrink body copy, so a whole region reads as secondary metadata',
+            'The disabled color for content; it fails contrast and is for disabled controls',
+            'Card soup: each record wrapped in its own Card instead of rendered as rows',
+            'Cards inside Cards, or full-width Cards stacked as page structure',
+            'A header or footer rebuilt inside the body, where it scrolls away with the rows',
+            'Flexbox soup: nested ad-hoc flexboxes instead of Grid, Layout, Section, or FormLayout',
+            'Two competing primary actions in one region',
+            'Badge as decoration; use StatusDot or Token for status and metadata',
           ],
         },
       ],
     },
     {
-      title: 'Structure',
+      id: 'type-hierarchy',
+      title: 'Type hierarchy',
       content: [
-        {type: 'heading', level: 3, text: 'Type hierarchy'},
         {
           type: 'prose',
           text: 'Give every region one lead, then rank the rest with weight and color rather than size. Content uses two text colors, primary and secondary, and nothing dimmer: body copy needs no props at all.',
@@ -170,8 +217,12 @@ export const docs = {
           type: 'prose',
           text: 'Squint test: blurred, you read lead, then support, then groups, in that order. If everything reads at once, raise contrast with weight and color, not borders and not smaller text.',
         },
-
-        {type: 'heading', level: 3, text: 'Containers'},
+      ],
+    },
+    {
+      id: 'containers',
+      title: 'Card or rows',
+      content: [
         {
           type: 'prose',
           text: 'Reach for the weakest container that reads as a group, and escalate only when it fails. Weakest to strongest:',
@@ -202,8 +253,12 @@ export const docs = {
           type: 'prose',
           text: 'Decision test: records render as rows, Table for columnar and List for single-line; a self-contained widget or hard boundary is a Card; everything else is a Section.',
         },
-
-        {type: 'heading', level: 3, text: 'Headers and footers'},
+      ],
+    },
+    {
+      id: 'headers-and-footers',
+      title: 'Headers and footers',
+      content: [
         {
           type: 'prose',
           text: 'A region can pin a header or footer while its body scrolls. Both are Layout slots, and padding set once on Layout reaches all three, so header, body, and footer share one content line.',
@@ -235,8 +290,12 @@ export const docs = {
           type: 'prose',
           text: 'Verify: scroll the body. The header and footer stay put, their dividers run full-bleed, and all three still share one left content line.',
         },
-
-        {type: 'heading', level: 3, text: 'Side panels'},
+      ],
+    },
+    {
+      id: 'side-panels',
+      title: 'Side panels',
+      content: [
         {
           type: 'prose',
           text: 'Master-detail: selecting a row opens a fixed-width side panel instead of navigating away.',
@@ -278,41 +337,45 @@ end={
         },
         {
           type: 'prose',
-          text: 'Verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.',
+          text: 'Verify: at narrow widths the panel yields width instead of squeezing content (see Responsive contract), and only one element between the regions draws a border.',
+        },
+      ],
+    },
+    {
+      id: 'spacing',
+      title: 'Spacing',
+      content: [
+        {
+          type: 'prose',
+          text: 'Hold one content line per region, then tune gaps and density. Alignment, Rhythm, and Density and size cover each step; these rules hold for all of them.',
         },
-
-        {type: 'heading', level: 3, text: 'Best practices'},
         {
           type: 'list',
           style: 'do',
           items: [
-            'One lead per region; rank with weight and color; one primary action',
-            'Leave body copy at its defaults; demote by weight and color, not size',
-            'Default to Section; use the weakest container that reads as a group',
-            'Render collections as rows (Table or List), edge-to-edge with dividers',
-            'Open a fixed-width side panel on select; let it yield width at narrow sizes',
+            'Let the container own padding; children zero their own margins',
+            'Hold one content line per region: text on the line, hover backgrounds bleed to the edge',
+            'Hold one padding token across a region header, body, and footer',
+            'Contrast tight and generous gaps so grouping reads without borders',
+            'One control size per row; match density to use frequency',
           ],
         },
         {
           type: 'list',
           style: 'dont',
           items: [
-            'Grey and shrink body copy, so a whole region reads as secondary metadata',
-            'The disabled color for content; it fails contrast and is for disabled controls',
-            'Card soup: each record wrapped in its own Card instead of rendered as rows',
-            'Cards inside Cards, or full-width Cards stacked as page structure',
-            'A header or footer rebuilt inside the body, where it scrolls away with the rows',
-            'Flexbox soup: nested ad-hoc flexboxes instead of Grid, Layout, Section, or FormLayout',
-            'Two competing primary actions in one region',
-            'Badge as decoration; use StatusDot or Token for status and metadata',
+            'Double padding: a component indented past its Section heading (keep one inset owner)',
+            'Raw px for interior spacing; tokens only, px is for structural widths',
+            'One repeated gap everywhere, which flattens grouping',
+            'Mixed control sizes in a single row',
           ],
         },
       ],
     },
     {
-      title: 'Spacing',
+      id: 'alignment',
+      title: 'Alignment',
       content: [
-        {type: 'heading', level: 3, text: 'Alignment'},
         {
           type: 'prose',
           text: 'The container owns padding and child gaps; children zero their margins, and interior spacing is always a token. Pick one content line per region and hold it constant, not the padding: `container_inset = content_line - component_intrinsic_inset`.',
@@ -342,8 +405,12 @@ end={
           type: 'prose',
           text: 'Verify: draw one vertical line down the left of the region. Every label touches it; only hover and selected backgrounds cross it.',
         },
-
-        {type: 'heading', level: 3, text: 'Rhythm'},
+      ],
+    },
+    {
+      id: 'rhythm',
+      title: 'Rhythm',
+      content: [
         {
           type: 'prose',
           text: 'Grouping comes from contrast between tight and generous gaps, not one repeated value. If every gap is the same step, proximity does no work.',
@@ -375,8 +442,12 @@ end={
           type: 'prose',
           text: 'Verify: with every border removed, you can still name the groups from spacing alone. If you cannot, the intervals are too uniform. Form fields are the exception: FormLayout owns their spacing.',
         },
-
-        {type: 'heading', level: 3, text: 'Density and size'},
+      ],
+    },
+    {
+      id: 'density',
+      title: 'Density and size',
+      content: [
         {
           type: 'prose',
           text: 'Match density to how often a region is used, and give every control in a row the same size so heights share a baseline.',
@@ -403,35 +474,40 @@ end={
           type: 'prose',
           text: 'Verify: every interactive element in a row shares one size, and that size is paired with the density of the region it sits in.',
         },
-
-        {type: 'heading', level: 3, text: 'Best practices'},
+      ],
+    },
+    {
+      id: 'breakpoints',
+      title: 'Breakpoints',
+      content: [
+        {
+          type: 'prose',
+          text: 'Decide what each region does as width changes. Responsive contract covers it; these rules hold for every region.',
+        },
         {
           type: 'list',
           style: 'do',
           items: [
-            'Let the container own padding; children zero their own margins',
-            'Hold one content line per region: text on the line, hover backgrounds bleed to the edge',
-            'Hold one padding token across a region header, body, and footer',
-            'Contrast tight and generous gaps so grouping reads without borders',
-            'One control size per row; match density to use frequency',
+            'Write the contract down for every region before you call the layout done',
+            'Decide per region whether it is revealed, resized, or swapped at each width',
+            'Drop a region rather than let it compete for width it does not have',
           ],
         },
         {
           type: 'list',
           style: 'dont',
           items: [
-            'Double padding: a component indented past its Section heading (keep one inset owner)',
-            'Raw px for interior spacing; tokens only, px is for structural widths',
-            'One repeated gap everywhere, which flattens grouping',
-            'Mixed control sizes in a single row',
+            'Hold three regions at a width where none of them has usable space',
+            'Shrink every region uniformly instead of swapping or dropping one',
+            'Wire a breakpoint in CSS that the contract comment never mentions',
           ],
         },
       ],
     },
     {
-      title: 'Breakpoints',
+      id: 'responsive-contract',
+      title: 'Responsive contract',
       content: [
-        {type: 'heading', level: 3, text: 'Responsive contract'},
         {
           type: 'prose',
           text: 'Lock what each region does as width changes, and pair every line of the contract with the prop or hook that enforces it.',
@@ -468,26 +544,6 @@ const isNarrow = useMediaQuery('(max-width: 1024px)');
           type: 'prose',
           text: 'Verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
         },
-
-        {type: 'heading', level: 3, text: 'Best practices'},
-        {
-          type: 'list',
-          style: 'do',
-          items: [
-            'Write the contract down for every region before you call the layout done',
-            'Decide per region whether it is revealed, resized, or swapped at each width',
-            'Drop a region rather than let it compete for width it does not have',
-          ],
-        },
-        {
-          type: 'list',
-          style: 'dont',
-          items: [
-            'Hold three regions at a width where none of them has usable space',
-            'Shrink every region uniformly instead of swapping or dropping one',
-            'Wire a breakpoint in CSS that the contract comment never mentions',
-          ],
-        },
       ],
     },
   ],

package/assets/docs/migration.doc.mjs

@@ -30,12 +30,12 @@ export const docs = {
           type: 'list',
           style: 'ordered',
           items: [
-            'Install the design system and run init so the project has package scripts, theme CSS, and agent docs.',
+            '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).',
             '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, Tabs, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.',
+            'Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, TabList, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.',
             '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.',
@@ -69,13 +69,13 @@ astryx component TextInput`,
         },
         {
           type: 'prose',
-          text: 'Use --dense when pasting output into an AI coding tool, and use --json when building automated migration reports.',
+          text: 'For a shorter read to paste into an AI coding tool, add `--detail brief` (one line per section) or `--detail compact`. Use `--json` when building automated migration reports.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Dense and JSON modes',
-          code: `astryx docs migration --dense
+          label: 'Short and JSON modes',
+          code: `astryx docs migration --full --detail brief
 astryx component Button --json`,
         },
       ],
@@ -110,21 +110,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. design system reset and theme CSS should load before Tailwind utilities so migrated components keep design system defaults while legacy utility classes still work.',
-        },
-        {
-          type: 'code',
-          lang: 'css',
-          label: 'Tailwind v4 coexistence',
-          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);`,
+          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}.',
         },
         {
           type: 'prose',
@@ -149,7 +135,8 @@ export function AppRoot({children}: {children: React.ReactNode}) {
       ],
     },
     {
-      title: 'Cascade Layer Safety',
+      id: 'cascade-layer-safety',
+      title: 'Why resets break cascade layers',
       content: [
         {
           type: 'prose',
@@ -166,6 +153,16 @@ export function AppRoot({children}: {children: React.ReactNode}) {
           code: `/* was: @import "./legacy-reset.css";  (unlayered: beats every layer) */
 @import "./legacy-reset.css" layer(reset);`,
         },
+        {
+          type: 'prose',
+          text: 'Before building screens, check every stylesheet against Cascade layer audit.',
+        },
+      ],
+    },
+    {
+      id: 'layer-audit',
+      title: 'Cascade layer audit',
+      content: [
         {
           type: 'prose',
           text: 'Audit the layers around the design system with this checklist before building screens.',
@@ -310,6 +307,7 @@ if (getComputedStyle(button).paddingInline === '0px') {
       ],
     },
     {
+      id: 'command-palette',
       title: 'Command Palette, Settings, and Theme',
       content: [
         {

package/assets/docs/motion.doc.mjs

@@ -33,6 +33,10 @@ export const docs = {
       title: 'Duration',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'Nine duration tokens in fast, medium, and slow bands.',
+        },
         {
           type: 'token-ref',
           topic: 'tokens',
@@ -44,6 +48,10 @@ export const docs = {
       title: 'Easing',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'One easing curve, `--ease-standard`.',
+        },
         {
           type: 'token-ref',
           topic: 'tokens',
@@ -101,19 +109,24 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Some users experience motion sensitivity; animation that feels polished to one person can cause discomfort for another. Components should honor the operating system\'s reduced motion setting. When it\'s enabled, replace animations with instant state changes.',
+          text: 'Some users experience motion sensitivity; animation that feels polished to one person can cause discomfort for another. Astryx components already switch to instant changes when the OS reduced-motion setting is on. Do the same in your own animations with `@media (prefers-reduced-motion: reduce)`.',
         },
       ],
     },
     {
-      title: 'Usage',
+      id: 'usage',
+      title: 'Animate with motion tokens',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'Set transition durations and easing from the motion tokens, so a theme that retunes motion retunes your animations too.',
+        },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Applying motion tokens',
-          code: `import {durationVars, easeVars} from '@astryxdesign/core';
+          code: `import {durationVars, easeVars} from '@astryxdesign/core/theme/tokens.stylex';
 
 const styles = stylex.create({
   fadeIn: {

package/assets/docs/principles.doc.dense.mjs

@@ -5,10 +5,10 @@
 export const docsDense = {
   description: 'core design principles + rules for the design system',
   sections: [
-    { 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 astryx docs tokens for full reference' }] },
+    { 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 generic: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: '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 generic: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}' }] },
   ],
 };

package/assets/docs/principles.doc.mjs

@@ -34,6 +34,10 @@ export const docs = {
       title: 'Rules',
   category: 'guide',
       content: [
+        {
+          type: 'prose',
+          text: 'Eight rules that keep app code on-system.',
+        },
         {
           type: 'list',
           style: 'ordered',
@@ -68,6 +72,10 @@ export const docs = {
       title: 'Anti-Patterns',
   category: 'guide',
       content: [
+        {
+          type: 'prose',
+          text: 'Patterns that break theming, routing, or layout, and what to use instead.',
+        },
         {
           type: 'list',
           style: 'dont',

package/assets/docs/principles.doc.zh.mjs

@@ -3,12 +3,12 @@
 /** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
 
 export const docsZh = {
-  description: 'XDS 核心设计原则和规则。',
+  description: 'Astryx 核心设计原则和规则。',
   sections: [
-    { 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: '运行 astryx docs tokens 查看完整参考' }] },
+    { section: 'Design Philosophy', title: '设计哲学', content: [{ type: 'prose', text: '一个注重一致性、适应性和开发者体验的设计系统。核心理念：' }, { type: 'list', items: ['组件优于原始元素 — 优先使用 Astryx 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },
+    { section: 'Rules', title: '规则', content: [{ type: 'prose', text: '让应用代码保持在设计系统之内的八条规则。' }, { type: 'list', items: ['所有支持的场景都使用 Astryx 组件', '布局采用框架优先：先选定外壳并规划区域尺寸，再编写内容（见 {@link generic: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: 'Anti-Patterns', title: '反模式', content: [{ type: 'prose', text: '会破坏主题、路由或布局的写法，以及应改用的做法。' }, { type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架，密集数据用行渲染（见 {@link generic:layout}）', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
+    { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '完整令牌参考见 {@link generic:tokens}。' }] },
   ],
 };

package/assets/docs/shape.doc.mjs

@@ -25,6 +25,10 @@ export const docs = {
       title: 'Radius Scale',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'Seven radius tokens, from 0px to 9999px.',
+        },
         {
           type: 'token-ref',
           topic: 'tokens',
@@ -38,14 +42,15 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'When a rounded container has padding, inner elements need a smaller radius to appear concentric. Components like Card handle this automatically; the inner radius is computed as max(0, outerRadius - padding).',
+          text: 'Inside a padded, rounded container, give nested elements a radius of outer radius minus padding so the curves stay concentric. Card does not do this for your content.',
         },
         {
           type: 'code',
           lang: 'css',
           label: 'Concentric radius formula',
-          code: `/* Automatic in Astryx Card */
---card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
+          code: `.inner {
+  border-radius: max(0px, calc(var(--radius-container) - var(--spacing-4)));
+}`,
         },
       ],
     },

package/assets/docs/spacing.doc.mjs

@@ -8,6 +8,7 @@ export const docs = {
   category: 'foundations',
   description:
     'Spacing scale tokens for padding, gap, and margin: the rhythmic foundation of design system layouts.',
+  keywords: ['padding', 'margin', 'gap'],
   tokenCategory: 'spacing',
 
   sections: [
@@ -25,6 +26,10 @@ export const docs = {
       title: 'Scale',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'Fifteen spacing tokens, from 0px to 48px.',
+        },
         {
           type: 'token-ref',
           topic: 'tokens',
@@ -38,7 +43,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Most components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX.',
+          text: 'Stack, HStack, VStack, Grid, Toolbar, OverflowList, and ChatMessageList take a `gap` step: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, or 10 (×4px). Carousel takes the steps from 0 to 4. For custom layouts, use the spacing tokens in StyleX.',
         },
         {
           type: 'code',
@@ -48,7 +53,7 @@ export const docs = {
 <Stack gap={4}>{/* 16px gap */}</Stack>
 
 // Via StyleX tokens (custom layouts)
-import {spacingVars} from '@astryxdesign/core';
+import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
 
 const styles = stylex.create({
   custom: {