Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: split layout into a namespace with six focused guides (#7125)

Joeya5c83ba9a66a
diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjs
index 97da2eac76..a3f622a2cc 100644
--- a/packages/cli/api/docs/docs.test.mjs
+++ b/packages/cli/api/docs/docs.test.mjs
@@ -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', 'unorganized']);
+ expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'layout', 'unorganized']);
for (const entry of res.data) {
expect((await docs(entry.topic)).type).toBe('docs.detail');
}
diff --git a/packages/cli/api/docs/index/index.test.mjs b/packages/cli/api/docs/index/index.test.mjs
index 104d4fd732..742570dd76 100644
--- a/packages/cli/api/docs/index/index.test.mjs
+++ b/packages/cli/api/docs/index/index.test.mjs
@@ -3,7 +3,7 @@
import {describe, expect, it} from 'vitest';
import {docs} from '../docs.mjs';
import {index} from './index.mjs';
-import {loadDocsCatalog} from '../_adapter.mjs';
+import {loadDocsCatalog, holdsOwnName, projectTree} from '../_adapter.mjs';
const SLOW = 60_000;
@@ -39,7 +39,11 @@ describe('docs.index leaf', () => {
it('lists keys every section can be read by', async () => {
const catalog = await loadDocsCatalog();
+ const tree = await projectTree(catalog);
for (const entry of catalog.entries()) {
+ // A flat topic whose name is now owned by a namespace (e.g. layout)
+ // cannot be read as a topic — skip it.
+ if (!holdsOwnName(tree, catalog, entry)) continue;
const {data} = await index(entry.name);
for (const {id, title} of data.sections) {
const read = await docs(entry.name, id);
diff --git a/packages/cli/assets/docs/layout.doc.dense.mjs b/packages/cli/assets/docs/layout.doc.dense.mjs
deleted file mode 100644
index 728047178c..0000000000
--- a/packages/cli/assets/docs/layout.doc.dense.mjs
+++ /dev/null
@@ -1,388 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
-
-export const docsDense = {
- description:
- 'outside-in app layout: scaffold -> structure -> spacing -> breakpoints.',
- sections: [
- {
- section: 'Overview',
- title: 'Overview',
- content: [
- {
- type: 'prose',
- text: 'build outside-in. settle the shell + region budgets before any content, then work inward. content-first drifts into a padded column of cards, each section inventing its own container.',
- },
- {
- type: 'list',
- items: [
- 'scaffold: pick shell, budget regions, choose nav',
- 'structure: rank content per region, pick the weakest container that groups it',
- 'spacing: hold one content line per region, then tune gaps + density',
- 'breakpoints: decide what each region does as width changes',
- ],
- },
- {
- type: 'prose',
- text: 'decides layout, not component APIs. npx astryx build "<idea>" = the template to start from for your app type. npx astryx component <Name> = props.',
- },
- ],
- },
- {
- section: 'Scaffold',
- title: 'Scaffold',
- content: [
- {
- type: 'prose',
- text: 'pick shell, budget regions, choose nav, before content. steps: Shell, Navigation. rules for both:',
- },
- {
- type: 'list',
- items: [
- 'decide frame + region width budgets + fill-or-capped before content',
- 'state the reason for the nav choice, or inherit template pairing',
- 'raw px for structural widths; interior = tokens',
- ],
- },
- {
- type: 'list',
- items: [
- 'build content-first, Card-wrapping each section',
- 'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
- 'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
- 'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
- 'both bars when the ecosystem layer is thin',
- 'break template nav pairing without a reason',
- ],
- },
- ],
- },
- {
- section: 'Shell',
- title: 'Shell',
- content: [
- {
- type: 'prose',
- text: 'pick the shell + budget its regions before any content exists. structural widths are the one place raw px belongs; everything inside uses the scale.',
- },
- {
- type: 'list',
- items: [
- 'pick frame: AppShell (nav apps) | Layout + LayoutPanel in a start/end slot (multi-pane tools) | plain column (docs/forms)',
- 'give every fixed region a width budget, so none negotiates for space at render time',
- 'read content to set fill vs capped: tables/charts/boards fill; prose/forms/lists cap via Layout contentWidth',
- 'set container policy (rows or card grid) before writing content',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'verify: every region has a width budget + fill-or-capped + a container policy written down before any content.',
- },
- ],
- },
- {
- section: 'Navigation',
- title: 'Navigation',
- content: [
- {
- type: 'prose',
- text: 'nav left open? default SideNav: it absorbs destinations you have not planned yet. app type + destination count are guiding indicators, not determining rules.',
- },
- {
- type: 'list',
- items: [
- 'SideNav (default): need grouping, customizable, items carry secondary actions, or must collapse. trackers, consoles, settings usually start here',
- 'TopNav: shallow nav you expect to stay shallow, context must stay visible, or control/filter-heavy page; + TabList for a 2nd level. media libraries often sit over grid content',
- 'both: a genuine suite. TopNav = ecosystem concerns (context switcher, global search), SideNav = product nav',
- 'neither: messaging/feeds use a column frame of rail, nav, stream, panel',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the template to start from; scaffold it and the pairing is wired up.',
- },
- ],
- },
- {
- section: 'Structure',
- title: 'Structure',
- content: [
- {
- type: 'prose',
- text: 'rank content per region, pick the weakest container that groups it. steps: Type hierarchy, Card or rows, Headers and footers, Side panels. rules for all:',
- },
- {
- type: 'list',
- items: [
- 'one lead per region; rank via weight+color; one primary action',
- 'leave body copy at its defaults; demote via weight+color, not size',
- 'default Section; weakest container that reads as a group',
- 'collections = rows (Table/List), edge-to-edge with dividers',
- 'side panel on select; it yields width at narrow sizes',
- ],
- },
- {
- type: 'list',
- items: [
- 'grey + shrink body copy, so a whole region reads as metadata',
- 'the disabled color for content; it fails contrast, it is for disabled controls',
- 'card soup: each record in its own Card',
- 'cards-in-cards, or full-width Cards as page structure',
- 'a header/footer rebuilt inside the body, where it scrolls away with the rows',
- 'flexbox soup instead of Grid/Layout/Section/FormLayout',
- 'two competing primary actions in one region',
- 'Badge as decoration; use StatusDot/Token for status',
- ],
- },
- ],
- },
- {
- section: 'Type hierarchy',
- title: 'Type hierarchy',
- content: [
- {
- type: 'prose',
- text: 'one lead per region, then rank with weight+color, not size. two text colors only: primary + secondary, nothing dimmer. body copy needs no props.',
- },
- {
- type: 'list',
- items: [
- 'body (default): plain Text, no type/color/size prop',
- 'lead: Heading at the level matching page depth, or body Text at a heavier weight',
- 'support: step to secondary color, not to a smaller size',
- 'meta: the supporting type, or StatusDot/Token instead of prose',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'squint test: read lead, then support, then groups, in order. everything at once = raise contrast (weight/color), not borders and not smaller text.',
- },
- ],
- },
- {
- section: 'Card or rows',
- title: 'Card or rows',
- content: [
- {
- type: 'prose',
- text: 'weakest container that reads as a group, escalate only when it fails. weakest to strongest:',
- },
- {
- type: 'list',
- items: [
- 'spacing/gap: related items inside one group. the default rhythm',
- 'Divider: peers in a dense list/toolbar, or fencing a header from a scrollable body',
- 'Section: default page-structure unit, related content under a heading. no border',
- 'Card: self-contained widget (KPI tile, chart, gallery entry) or hard boundary',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'test: records -> rows (Table columnar, List single-line); self-contained widget or hard boundary -> Card; everything else -> Section.',
- },
- ],
- },
- {
- section: 'Headers and footers',
- title: 'Headers and footers',
- content: [
- {
- type: 'prose',
- text: 'a region can pin a header/footer while its body scrolls. both are Layout slots, and padding set once on Layout reaches all three, so header/body/footer share one content line.',
- },
- {
- type: 'list',
- items: [
- 'LayoutHeader in the header slot: region title + its primary action',
- 'Toolbar instead of LayoutHeader when the header carries interactive controls',
- 'LayoutFooter in the footer slot: actions that commit the work + must stay reachable',
- 'defaultHasDividers on Layout fences both at once, rather than hasDivider per slot',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'verify: scroll the body. header + footer stay put, dividers run full-bleed, all three still share one left content line.',
- },
- ],
- },
- {
- section: 'Side panels',
- title: 'Side panels',
- content: [
- {
- type: 'prose',
- text: 'master-detail: select a row -> fixed-width side panel, no navigation away.',
- },
- {
- type: 'list',
- items: [
- 'LayoutPanel in the start or end slot of Layout, holding a fixed width budget',
- 'hasDivider fences it from content; isScrollable so long detail scrolls on its own',
- 'user-adjustable width: useResizable() + ResizeHandle on the panel inner edge. after the panel in a start slot, before it in an end slot w/ isReversed',
- 'the handle then owns the divider, so the panel sets hasDivider={false}',
- 'EmptyState when nothing is selected, so the region never collapses',
- ],
- },
- null,
- {
- type: 'prose',
- 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.',
- },
- ],
- },
- {
- section: 'Spacing',
- title: 'Spacing',
- content: [
- {
- type: 'prose',
- text: 'one content line per region, then tune gaps + density. steps: Alignment, Rhythm, Density and size. rules for all:',
- },
- {
- type: 'list',
- items: [
- 'container owns padding; children zero margins',
- 'one content line: text on line, hover bleeds to edge',
- 'one padding token across region header/body/footer',
- 'contrast tight vs generous gaps',
- 'one control size per row; density by use frequency',
- ],
- },
- {
- type: 'list',
- items: [
- 'double padding (component past its heading); keep one inset owner',
- 'raw px for interior spacing; tokens only',
- 'one repeated gap everywhere',
- 'mixed control sizes in one row',
- ],
- },
- ],
- },
- {
- section: 'Alignment',
- title: 'Alignment',
- content: [
- {
- type: 'prose',
- text: 'container owns padding + child gaps; children zero margins; interior spacing = token. one content line per region, hold the line not the padding: container_inset = content_line - component_intrinsic_inset.',
- },
- {
- type: 'list',
- items: [
- 'Text/Heading carry no inset -> container takes the full padding',
- 'List/Tab/Menu/nav items carry a small inset -> container gives up padding, component owns the line',
- 'Table cells carry a larger inset -> container gives up padding, cell owns the line',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'verify: draw one vertical line down the left. every label touches it; only hover/selected backgrounds cross it.',
- },
- ],
- },
- {
- section: 'Rhythm',
- title: 'Rhythm',
- content: [
- {
- type: 'prose',
- text: 'grouping = contrast between tight and generous gaps, not one repeated value. same step everywhere = proximity does no work.',
- },
- {
- type: 'list',
- items: [
- 'tight gaps bind: the smallest steps, inside an item or field',
- 'generous gaps separate: several steps up, between sections',
- 'reach for the in-between steps to tune cadence, not the same two values everywhere',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'verify: borders removed, you can still name the groups from spacing alone. cannot = intervals too uniform. form fields excepted: FormLayout owns their spacing.',
- },
- ],
- },
- {
- section: 'Density and size',
- title: 'Density and size',
- content: [
- {
- type: 'prose',
- text: 'density by use frequency; every control in a row shares one size so heights share a baseline.',
- },
- {
- type: 'list',
- items: [
- 'compact: high-volume, fast scan (logs, monitors, large datasets)',
- 'balanced: most Table/List surfaces',
- 'spacious: low-frequency or high-stakes rows (settings, short selection list)',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'verify: one size per row, paired with the density of the region it sits in.',
- },
- ],
- },
- {
- section: 'Breakpoints',
- title: 'Breakpoints',
- content: [
- {
- type: 'prose',
- text: 'decide what each region does as width changes. step: Responsive contract. rules:',
- },
- {
- type: 'list',
- items: [
- 'write the contract down for every region before calling the layout done',
- 'decide per region: revealed, resized, or swapped at each width',
- 'drop a region rather than let it fight for width it lacks',
- ],
- },
- {
- type: 'list',
- items: [
- '3 regions at a width where none has usable space',
- 'shrink every region uniformly instead of swapping/dropping one',
- 'a CSS breakpoint the contract comment never mentions',
- ],
- },
- ],
- },
- {
- section: 'Responsive contract',
- title: 'Responsive contract',
- content: [
- {
- type: 'prose',
- text: 'lock what each region does as width changes; pair each contract line with the prop/hook that enforces it.',
- },
- {
- type: 'list',
- items: [
- 'divide: how many regions survive at each width',
- 'reveal: which regions earn their width only when there is room, opening on demand below that',
- 'resize: content flexes, fixed regions hold their budgets, text capped by contentWidth so line length holds',
- 'swap: nav -> MobileNav at the AppShell mobileNav breakpoint; side panel -> Dialog/BottomSheet via useMediaQuery',
- ],
- },
- null,
- {
- type: 'prose',
- text: 'verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
- },
- ],
- },
- ],
-};
diff --git a/packages/cli/assets/docs/layout.doc.mjs b/packages/cli/assets/docs/layout.doc.mjs
deleted file mode 100644
index 4bec88088e..0000000000
--- a/packages/cli/assets/docs/layout.doc.mjs
+++ /dev/null
@@ -1,550 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-
-export const docs = {
- name: 'layout',
- title: 'Layout',
- category: 'guide',
- description:
- 'Build an app layout outside-in: scaffold the regions, structure the content, tune the spacing, then adapt across widths.',
-
- sections: [
- {
- title: 'Overview',
- content: [
- {
- type: 'prose',
- text: 'Build a layout outside-in. Settle the shell and its region budgets before any content exists, then work inward. Content-first layouts drift into a padded column of cards, because every section ends up inventing its own container.',
- },
- {
- type: 'list',
- style: 'ordered',
- items: [
- 'Scaffold: pick the shell, budget each region, and choose navigation',
- 'Structure: rank the content in each region, then pick the weakest container that groups it',
- 'Spacing: hold one content line per region, then tune gaps and density',
- 'Breakpoints: decide what each region does as width changes',
- ],
- },
- {
- type: 'prose',
- text: 'This guide decides layout, not component APIs. Run `npx astryx build "<idea>"` to start from the closest template for your app type, and `npx astryx component <Name>` for a component\'s props.',
- },
- ],
- },
- {
- id: 'scaffold',
- title: 'Scaffold',
- content: [
- {
- 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.',
- },
- {
- type: 'list',
- style: 'ordered',
- items: [
- 'Pick the frame: AppShell for nav apps, Layout with LayoutPanel in a start or end slot for multi-pane tools, or a plain content column for documents and forms',
- 'Give every fixed region a width budget, so no region has to negotiate for space at render time',
- 'Read the content to set fill or capped: tables, charts, and boards fill their region; prose, forms, and lists cap with Layout contentWidth so lines never over-stretch',
- 'Set each region container policy, rows or card grid, before writing content',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'A three-region tool frame',
- code: `// Recommended budgets: SideNav 240–280, icon rail 64–72,
-// side panel 340–420, filter rail 220–260.
-<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>}>
- <Layout
- content={<LayoutContent>{/* table fills its region */}</LayoutContent>}
- end={<LayoutPanel width={380} hasDivider>{/* detail */}</LayoutPanel>}
- />
-</AppShell>
-
-// Capped instead: 640 suits text and forms, 960 mixed content.
-// Dividers stay full-bleed.
-<Layout
- contentWidth={640}
- content={<LayoutContent>{/* settings form */}</LayoutContent>}
-/>`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'SideNav, the default: grouping needed, customizable nav, items with secondary actions, or nav that collapses. Trackers, consoles, and settings usually start here',
- 'TopNav: a shallow nav you expect to stay shallow, context that must stay visible, or a control- and filter-heavy page; add a TabList for a second level. Media libraries often sit here, over grid content',
- 'Both: a genuine suite, where TopNav carries ecosystem-wide concerns (context switcher, global search) and SideNav carries product nav',
- 'Neither: messaging and feeds use a column frame of rail, nav, stream, and panel',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Navigation passed to AppShell',
- code: `// Default: product nav on the side.
-<AppShell sideNav={<SideNav>{/* items */}</SideNav>} />
-
-// Shallow, stable nav on a control-heavy page.
-<AppShell topNav={<TopNav>{/* items */}</TopNav>} />
-
-// Suite: ecosystem concerns on top, product nav on the side.
-<AppShell topNav={<TopNav />} sideNav={<SideNav />} />`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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: [
- '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: [
- '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',
- ],
- },
- ],
- },
- {
- id: 'type-hierarchy',
- title: 'Type hierarchy',
- content: [
- {
- 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.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'Body, the default: plain Text with no type, color, or size prop',
- 'Lead: Heading at the level matching page depth, or body Text at a heavier weight',
- 'Support: step to the secondary color, not to a smaller size',
- 'Metadata: the supporting type, or a StatusDot or Token instead of prose',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Body copy, then one row of four ranks',
- code: `// Body copy takes no props. Text already defaults to body
-// size in the primary color.
-<Text>Credentials rotate every 90 days</Text>
-
-<HStack gap={2}>
- <Text weight="semibold">Payments API</Text>
- <StatusDot variant="success" label="Healthy" />
- <Text color="secondary">v2.14</Text>
- <Text type="supporting">edited 3h ago</Text>
-</HStack>`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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:',
- },
- {
- type: 'list',
- style: 'ordered',
- items: [
- 'spacing and gap: related items inside one group. The default rhythm',
- 'Divider: peers in a dense list or toolbar, or fencing a header from a scrollable body',
- 'Section: the default page-structure unit, related content under a heading. No border',
- 'Card: a self-contained widget (KPI tile, chart, gallery entry), or a hard boundary around critical content',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Section as the default unit',
- code: `// Records are rows in one Section, not one Card each.
-// Recommended row height: 32–40px.
-<Section padding={0}>
- <List header={<Heading level={3}>Members</Heading>} hasDividers>
- {/* ListItem per member */}
- </List>
-</Section>`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'LayoutHeader in the header slot: the region title and its primary action',
- 'Toolbar instead of LayoutHeader when the header carries interactive controls',
- 'LayoutFooter in the footer slot: actions that commit the work and must stay reachable',
- 'defaultHasDividers on Layout fences both at once, rather than hasDivider per slot',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Pinned header and footer around a scrolling body',
- code: `// padding on Layout reaches every slot, so all three align.
-<Layout
- padding={4}
- defaultHasDividers
- header={<LayoutHeader>{/* title + primary action */}</LayoutHeader>}
- content={<LayoutContent>{/* rows */}</LayoutContent>}
- footer={<LayoutFooter>{/* Save and Cancel */}</LayoutFooter>}
-/>`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'LayoutPanel in the start or end slot of Layout, holding a fixed width budget',
- 'hasDivider to fence it from the content region; isScrollable so long detail scrolls on its own',
- 'For user-adjustable width, pair useResizable() with a ResizeHandle on the panel inner edge: after the panel in a start slot, before it in an end slot with isReversed',
- 'The handle then owns the divider, so the panel sets hasDivider={false}',
- 'Render an EmptyState when nothing is selected, so the region never collapses',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Fixed panel, then the resizable form',
- code: `// Recommended panel width: 340–420.
-<Layout
- content={<LayoutContent>{/* rows */}</LayoutContent>}
- end={
- <LayoutPanel width={380} hasDivider isScrollable label="Details">
- {/* detail fields, or EmptyState when nothing is selected */}
- </LayoutPanel>
- }
-/>
-
-// Resizable: handle first in an end slot, and isReversed so
-// dragging left widens the panel.
-end={
- <>
- <ResizeHandle isReversed hasDivider resizable={panel.props}
- label="Resize details" />
- <LayoutPanel width={panel.size} hasDivider={false} />
- </>
-}`,
- },
- {
- type: 'prose',
- 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: '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',
- ],
- },
- {
- 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',
- ],
- },
- ],
- },
- {
- id: 'alignment',
- title: 'Alignment',
- content: [
- {
- 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`.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'Text and Heading carry no inset, so the container takes the full padding',
- 'List, Tab, Menu, and nav items carry a small inset, so the container gives up its padding and the component owns the line',
- 'Table cells carry a larger inset, so the container gives up its padding and the cell owns the line',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'One content line, two inset owners',
- code: `// Target content line = 16px.
-// Heading has 0 inset, so the Section takes the full padding.
-<Section padding={4}><Heading level={3}>Members</Heading></Section>
-
-// List has ~8px built in, Table cells 12–16px, so the Section
-// gives up its padding and the component owns the inset.
-<Section padding={0}><List>{/* items */}</List></Section>`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'Tight gaps bind: the smallest steps, used inside an item or field',
- 'Generous gaps separate: several steps up, used between sections',
- 'Reach for the in-between steps to tune cadence, rather than rounding everything to the same two values',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Tight inside, generous between',
- code: `// Tight binds at gap={1}–{2}, generous separates at gap={4}–{6}.
-// In-between steps tune cadence: gap={3} = 12px, gap={5} = 20px.
-<VStack gap={6}>
- <VStack gap={1}>
- <Text weight="semibold">Retention</Text>
- <Text color="secondary">Logs are kept for 30 days</Text>
- </VStack>
- <VStack gap={1}>{/* next label and value */}</VStack>
-</VStack>`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'Compact: high-volume regions scanned fast, like logs, monitors, and large datasets',
- 'Balanced: most Table and List surfaces',
- 'Spacious: low-frequency or high-stakes rows, like settings or a short selection list',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Density paired with control size',
- code: `// Pair density with one control size: compact with sm,
-// balanced with sm or md, spacious with md or lg.
-<Table data={rows} columns={columns} density="compact" hasHover />
-<Button label="Retry" size="sm" variant="ghost" />`,
- },
- {
- 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.',
- },
- ],
- },
- {
- 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: [
- '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',
- ],
- },
- ],
- },
- {
- id: 'responsive-contract',
- title: 'Responsive contract',
- content: [
- {
- 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.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'Divide: how many regions survive at each width',
- 'Reveal: which regions earn their width only when there is room, and open on demand below that',
- 'Resize: content flexes while fixed regions hold their budgets, and text stays capped by contentWidth so line length holds',
- 'Swap: navigation becomes MobileNav at the AppShell mobileNav breakpoint; the side panel becomes a Dialog or BottomSheet, driven by useMediaQuery',
- ],
- },
- {
- type: 'code',
- lang: 'tsx',
- label: 'Contract wired to props',
- code: `// Recommended thresholds: 3 regions above 1024, 2 from 768,
-// 1 below. Text reads best at 40–60 characters per line.
-// >1024 SideNav 256 | content | side panel 380
-// <=1024 panel moves to a Dialog (useMediaQuery)
-// <=768 nav collapses to MobileNav (mobileNav "md")
-const isNarrow = useMediaQuery('(max-width: 1024px)');
-
-<AppShell sideNav={<SideNav />} mobileNav={{breakpoint: 'md'}}>
- <Layout
- content={<LayoutContent>{/* rows */}</LayoutContent>}
- end={isNarrow ? undefined : <LayoutPanel width={380} hasDivider />}
- />
-</AppShell>`,
- },
- {
- type: 'prose',
- text: 'Verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
- },
- ],
- },
- ],
-};
diff --git a/packages/cli/assets/docs/principles.doc.dense.mjs b/packages/cli/assets/docs/principles.doc.dense.mjs
index 64194511d3..5d3aba0069 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 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: '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: '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: '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}' }] },
],
};
diff --git a/packages/cli/assets/docs/principles.doc.mjs b/packages/cli/assets/docs/principles.doc.mjs
index eb21bc6448..0cea0a231b 100644
--- a/packages/cli/assets/docs/principles.doc.mjs
+++ b/packages/cli/assets/docs/principles.doc.mjs
@@ -43,7 +43,7 @@ export const docs = {
style: 'ordered',
items: [
'Use components for everything they cover',
- 'Page layout is frame-first: pick the shell and budget regions before writing content (see {@link generic:layout})',
+ '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})',
@@ -84,7 +84,7 @@ export const docs = {
'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
- 'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see {@link generic:layout})',
+ 'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see {@link namespace:layout})',
'Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status',
'Inventing props. Read component docs first',
],
diff --git a/packages/cli/assets/docs/principles.doc.zh.mjs b/packages/cli/assets/docs/principles.doc.zh.mjs
index f1f28ec133..0252817a4b 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 generic:layout})', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置(见 {@link generic:styling})', '使用语义化令牌,不使用硬编码值(见 {@link generic:tokens})', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },
+ { 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: 'Anti-Patterns', title: '反模式', content: [{ type: 'prose', text: '会破坏主题、路由或布局的写法,以及应改用的做法。' }, { type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 {@link generic:layout})', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
+ { 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}。' }] },
],
};
diff --git a/packages/cli/assets/docs/tree/headers-and-footers.doc.mjs b/packages/cli/assets/docs/tree/headers-and-footers.doc.mjs
new file mode 100644
index 0000000000..9f1b553dc3
--- /dev/null
+++ b/packages/cli/assets/docs/tree/headers-and-footers.doc.mjs
@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs layout/headers-and-footers`: pin a header or footer
+ * while the body scrolls.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+ type: 'generic',
+ name: 'headers-and-footers',
+ title: 'Headers and footers',
+ placement: {parent: 'namespace:layout', slot: 'guides', order: 30},
+ category: 'guide',
+ description:
+ 'Pin a header or footer while the body scrolls, so the title and commit actions stay reachable.',
+ keywords: [
+ 'LayoutHeader',
+ 'LayoutFooter',
+ 'Toolbar',
+ 'hasDivider',
+ 'defaultHasDividers',
+ 'pinned header',
+ 'pinned footer',
+ 'scrolling body',
+ ],
+
+ sections: [
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'LayoutHeader in the header slot: the region title and its primary action',
+ 'Toolbar instead of LayoutHeader when the header carries interactive controls',
+ 'LayoutFooter in the footer slot: actions that commit the work and must stay reachable',
+ 'defaultHasDividers on Layout fences both at once, rather than hasDivider per slot',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Pinned header and footer around a scrolling body',
+ code: `// padding on Layout reaches every slot, so all three align.
+<Layout
+ padding={4}
+ defaultHasDividers
+ header={<LayoutHeader>{/* title + primary action */}</LayoutHeader>}
+ content={<LayoutContent>{/* rows */}</LayoutContent>}
+ footer={<LayoutFooter>{/* Save and Cancel */}</LayoutFooter>}
+/>`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/layout-spacing.doc.mjs b/packages/cli/assets/docs/tree/layout-spacing.doc.mjs
new file mode 100644
index 0000000000..096344ff5e
--- /dev/null
+++ b/packages/cli/assets/docs/tree/layout-spacing.doc.mjs
@@ -0,0 +1,168 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs layout/spacing`: hold one content line per region, then
+ * tune gaps and density.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+ type: 'generic',
+ name: 'layout-spacing',
+ title: 'Layout spacing',
+ placement: {parent: 'namespace:layout', slot: 'guides', order: 40},
+ category: 'guide',
+ description:
+ 'Hold one content line per region, then tune gaps and density.',
+ keywords: [
+ 'alignment',
+ 'content line',
+ 'rhythm',
+ 'gap',
+ 'density',
+ 'padding',
+ 'inset',
+ 'compact',
+ 'spacious',
+ 'FormLayout',
+ ],
+
+ sections: [
+ {
+ 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: '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',
+ ],
+ },
+ {
+ 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',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'alignment',
+ title: 'Alignment',
+ content: [
+ {
+ 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`.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Text and Heading carry no inset, so the container takes the full padding',
+ 'List, Tab, Menu, and nav items carry a small inset, so the container gives up its padding and the component owns the line',
+ 'Table cells carry a larger inset, so the container gives up its padding and the cell owns the line',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'One content line, two inset owners',
+ code: `// Target content line = 16px.
+// Heading has 0 inset, so the Section takes the full padding.
+<Section padding={4}><Heading level={3}>Members</Heading></Section>
+
+// List has ~8px built in, Table cells 12–16px, so the Section
+// gives up its padding and the component owns the inset.
+<Section padding={0}><List>{/* items */}</List></Section>`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Tight gaps bind: the smallest steps, used inside an item or field',
+ 'Generous gaps separate: several steps up, used between sections',
+ 'Reach for the in-between steps to tune cadence, rather than rounding everything to the same two values',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Tight inside, generous between',
+ code: `// Tight binds at gap={1}–{2}, generous separates at gap={4}–{6}.
+// In-between steps tune cadence: gap={3} = 12px, gap={5} = 20px.
+<VStack gap={6}>
+ <VStack gap={1}>
+ <Text weight="semibold">Retention</Text>
+ <Text color="secondary">Logs are kept for 30 days</Text>
+ </VStack>
+ <VStack gap={1}>{/* next label and value */}</VStack>
+</VStack>`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Compact: high-volume regions scanned fast, like logs, monitors, and large datasets',
+ 'Balanced: most Table and List surfaces',
+ 'Spacious: low-frequency or high-stakes rows, like settings or a short selection list',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Density paired with control size',
+ code: `// Pair density with one control size: compact with sm,
+// balanced with sm or md, spacious with md or lg.
+<Table data={rows} columns={columns} density="compact" hasHover />
+<Button label="Retry" size="sm" variant="ghost" />`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/layout.doc.mjs b/packages/cli/assets/docs/tree/layout.doc.mjs
new file mode 100644
index 0000000000..5624e0e64f
--- /dev/null
+++ b/packages/cli/assets/docs/tree/layout.doc.mjs
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs layout`: the layout namespace. A root of the docs tree
+ * that groups the outside-in layout guides: scaffold, structure,
+ * headers-and-panels, spacing, and responsive.
+ *
+ * The flat layout topic this replaces was a 22 KB monolith. Each child guide
+ * now answers one question and is findable by search on its own.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'layout',
+ title: 'Layout',
+ summary:
+ 'Build an app layout outside-in: scaffold the regions, structure the content, tune the spacing, then adapt across widths.',
+ keywords: [
+ 'layout',
+ 'scaffold',
+ 'structure',
+ 'spacing',
+ 'responsive',
+ 'AppShell',
+ 'SideNav',
+ 'TopNav',
+ ],
+ slots: {
+ guides: {title: 'Guides', accepts: {kinds: ['generic']}},
+ },
+};
diff --git a/packages/cli/assets/docs/tree/responsive.doc.mjs b/packages/cli/assets/docs/tree/responsive.doc.mjs
new file mode 100644
index 0000000000..8f0ef9be81
--- /dev/null
+++ b/packages/cli/assets/docs/tree/responsive.doc.mjs
@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs layout/responsive`: decide what each region does as
+ * width changes.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+ type: 'generic',
+ name: 'responsive',
+ title: 'Responsive',
+ placement: {parent: 'namespace:layout', slot: 'guides', order: 50},
+ category: 'guide',
+ description:
+ 'Decide what each region does as width changes: divide, reveal, resize, or swap.',
+ keywords: [
+ 'responsive',
+ 'breakpoints',
+ 'useMediaQuery',
+ 'mobileNav',
+ 'MobileNav',
+ 'Dialog',
+ 'BottomSheet',
+ 'contentWidth',
+ 'contract',
+ ],
+
+ sections: [
+ {
+ id: 'breakpoints',
+ title: 'Breakpoints',
+ content: [
+ {
+ type: 'prose',
+ text: 'Decide what each region does as width changes. Write the responsive contract down for every region before you call the layout done.',
+ },
+ {
+ 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',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'responsive-contract',
+ title: 'Responsive contract',
+ content: [
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Divide: how many regions survive at each width',
+ 'Reveal: which regions earn their width only when there is room, and open on demand below that',
+ 'Resize: content flexes while fixed regions hold their budgets, and text stays capped by contentWidth so line length holds',
+ 'Swap: navigation becomes MobileNav at the AppShell mobileNav breakpoint; the side panel becomes a Dialog or BottomSheet, driven by useMediaQuery',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Contract wired to props',
+ code: `// Recommended thresholds: 3 regions above 1024, 2 from 768,
+// 1 below. Text reads best at 40–60 characters per line.
+// >1024 SideNav 256 | content | side panel 380
+// <=1024 panel moves to a Dialog (useMediaQuery)
+// <=768 nav collapses to MobileNav (mobileNav "md")
+const isNarrow = useMediaQuery('(max-width: 1024px)');
+
+<AppShell sideNav={<SideNav />} mobileNav={{breakpoint: 'md'}}>
+ <Layout
+ content={<LayoutContent>{/* rows */}</LayoutContent>}
+ end={isNarrow ? undefined : <LayoutPanel width={380} hasDivider />}
+ />
+</AppShell>`,
+ },
+ {
+ type: 'prose',
+ text: 'Verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/scaffold.doc.mjs b/packages/cli/assets/docs/tree/scaffold.doc.mjs
new file mode 100644
index 0000000000..75a2a3d192
--- /dev/null
+++ b/packages/cli/assets/docs/tree/scaffold.doc.mjs
@@ -0,0 +1,145 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs layout/scaffold`: pick the shell, budget each region,
+ * and choose navigation — before any content exists.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+ type: 'generic',
+ name: 'scaffold',
+ title: 'Scaffold',
+ placement: {parent: 'namespace:layout', slot: 'guides', order: 10},
+ category: 'guide',
+ description:
+ 'Pick the shell, budget each region, and choose navigation, before any content exists.',
+ keywords: [
+ 'shell',
+ 'navigation',
+ 'AppShell',
+ 'SideNav',
+ 'TopNav',
+ 'MobileNav',
+ 'frame',
+ 'region',
+ 'width budget',
+ 'contentWidth',
+ ],
+
+ sections: [
+ {
+ id: 'scaffold',
+ title: 'Scaffold',
+ content: [
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'Pick the frame: AppShell for nav apps, Layout with LayoutPanel in a start or end slot for multi-pane tools, or a plain content column for documents and forms',
+ 'Give every fixed region a width budget, so no region has to negotiate for space at render time',
+ 'Read the content to set fill or capped: tables, charts, and boards fill their region; prose, forms, and lists cap with Layout contentWidth so lines never over-stretch',
+ 'Set each region container policy, rows or card grid, before writing content',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'A three-region tool frame',
+ code: `// Recommended budgets: SideNav 240–280, icon rail 64–72,
+// side panel 340–420, filter rail 220–260.
+<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>}>
+ <Layout
+ content={<LayoutContent>{/* table fills its region */}</LayoutContent>}
+ end={<LayoutPanel width={380} hasDivider>{/* detail */}</LayoutPanel>}
+ />
+</AppShell>
+
+// Capped instead: 640 suits text and forms, 960 mixed content.
+// Dividers stay full-bleed.
+<Layout
+ contentWidth={640}
+ content={<LayoutContent>{/* settings form */}</LayoutContent>}
+/>`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'SideNav, the default: grouping needed, customizable nav, items with secondary actions, or nav that collapses. Trackers, consoles, and settings usually start here',
+ 'TopNav: a shallow nav you expect to stay shallow, context that must stay visible, or a control- and filter-heavy page; add a TabList for a second level. Media libraries often sit here, over grid content',
+ 'Both: a genuine suite, where TopNav carries ecosystem-wide concerns (context switcher, global search) and SideNav carries product nav',
+ 'Neither: messaging and feeds use a column frame of rail, nav, stream, and panel',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Navigation passed to AppShell',
+ code: `// Default: product nav on the side.
+<AppShell sideNav={<SideNav>{/* items */}</SideNav>} />
+
+// Shallow, stable nav on a control-heavy page.
+<AppShell topNav={<TopNav>{/* items */}</TopNav>} />
+
+// Suite: ecosystem concerns on top, product nav on the side.
+<AppShell topNav={<TopNav />} sideNav={<SideNav />} />`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/side-panels.doc.mjs b/packages/cli/assets/docs/tree/side-panels.doc.mjs
new file mode 100644
index 0000000000..2c7bb65550
--- /dev/null
+++ b/packages/cli/assets/docs/tree/side-panels.doc.mjs
@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs layout/side-panels`: add a master-detail side panel
+ * that opens on row select instead of navigating away.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+ type: 'generic',
+ name: 'side-panels',
+ title: 'Side panels',
+ placement: {parent: 'namespace:layout', slot: 'guides', order: 35},
+ category: 'guide',
+ description:
+ 'Add a master-detail side panel that opens on row select instead of navigating away.',
+ keywords: [
+ 'LayoutPanel',
+ 'side panel',
+ 'master detail',
+ 'ResizeHandle',
+ 'useResizable',
+ 'EmptyState',
+ 'hasDivider',
+ 'isScrollable',
+ 'detail panel',
+ 'split view',
+ ],
+
+ sections: [
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'LayoutPanel in the start or end slot of Layout, holding a fixed width budget',
+ 'hasDivider to fence it from the content region; isScrollable so long detail scrolls on its own',
+ 'For user-adjustable width, pair useResizable() with a ResizeHandle on the panel inner edge: after the panel in a start slot, before it in an end slot with isReversed',
+ 'The handle then owns the divider, so the panel sets hasDivider={false}',
+ 'Render an EmptyState when nothing is selected, so the region never collapses',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Fixed panel, then the resizable form',
+ code: `// Recommended panel width: 340–420.
+<Layout
+ content={<LayoutContent>{/* rows */}</LayoutContent>}
+ end={
+ <LayoutPanel width={380} hasDivider isScrollable label="Details">
+ {/* detail fields, or EmptyState when nothing is selected */}
+ </LayoutPanel>
+ }
+/>
+
+// Resizable: handle first in an end slot, and isReversed so
+// dragging left widens the panel.
+end={
+ <>
+ <ResizeHandle isReversed hasDivider resizable={panel.props}
+ label="Resize details" />
+ <LayoutPanel width={panel.size} hasDivider={false} />
+ </>
+}`,
+ },
+ {
+ type: 'prose',
+ text: 'Verify: at narrow widths the panel yields width instead of squeezing content (see the Responsive guide), and only one element between the regions draws a border.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/structure.doc.mjs b/packages/cli/assets/docs/tree/structure.doc.mjs
new file mode 100644
index 0000000000..c962e5a07c
--- /dev/null
+++ b/packages/cli/assets/docs/tree/structure.doc.mjs
@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs layout/structure`: rank the content in each region,
+ * then pick the weakest container that groups it.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+ type: 'generic',
+ name: 'structure',
+ title: 'Structure',
+ placement: {parent: 'namespace:layout', slot: 'guides', order: 20},
+ category: 'guide',
+ description:
+ 'Rank the content in each region, then pick the weakest container that groups it.',
+ keywords: [
+ 'type hierarchy',
+ 'Card',
+ 'Section',
+ 'Table',
+ 'List',
+ 'containers',
+ 'rows',
+ 'Heading',
+ 'Text',
+ 'weight',
+ 'color',
+ 'secondary',
+ 'Divider',
+ ],
+
+ sections: [
+ {
+ id: 'structure',
+ title: 'Structure',
+ content: [
+ {
+ type: 'prose',
+ text: 'Rank the content in each region, then pick the weakest container that groups it. Type hierarchy and Card or rows cover each step; these rules hold for all of them.',
+ },
+ {
+ 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',
+ ],
+ },
+ {
+ 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',
+ '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',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'type-hierarchy',
+ title: 'Type hierarchy',
+ content: [
+ {
+ 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.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Body, the default: plain Text with no type, color, or size prop',
+ 'Lead: Heading at the level matching page depth, or body Text at a heavier weight',
+ 'Support: step to the secondary color, not to a smaller size',
+ 'Metadata: the supporting type, or a StatusDot or Token instead of prose',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Body copy, then one row of four ranks',
+ code: `// Body copy takes no props. Text already defaults to body
+// size in the primary color.
+<Text>Credentials rotate every 90 days</Text>
+
+<HStack gap={2}>
+ <Text weight="semibold">Payments API</Text>
+ <StatusDot variant="success" label="Healthy" />
+ <Text color="secondary">v2.14</Text>
+ <Text type="supporting">edited 3h ago</Text>
+</HStack>`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ {
+ 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:',
+ },
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'spacing and gap: related items inside one group. The default rhythm',
+ 'Divider: peers in a dense list or toolbar, or fencing a header from a scrollable body',
+ 'Section: the default page-structure unit, related content under a heading. No border',
+ 'Card: a self-contained widget (KPI tile, chart, gallery entry), or a hard boundary around critical content',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Section as the default unit',
+ code: `// Records are rows in one Section, not one Card each.
+// Recommended row height: 32–40px.
+<Section padding={0}>
+ <List header={<Heading level={3}>Members</Heading>} hasDividers>
+ {/* ListItem per member */}
+ </List>
+</Section>`,
+ },
+ {
+ 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.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/foundation/doc-compiler/tree.test.mjs b/packages/cli/foundation/doc-compiler/tree.test.mjs
index ed3102756c..e124071560 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']);
+ expect(tree.roots().map(node => node.route)).toEqual(['cli', 'layout']);
// 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.
@@ -521,7 +521,7 @@ describe("the CLI's own docs tree", () => {
expect(
nodes
.map(node => node.route)
- .filter(route => route !== 'cli' && !placed.has(route)),
+ .filter(route => route !== 'cli' && route !== 'layout' && !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.json
index e784dea173..99291efaa2 100644
--- a/packages/cli/test/__golden__/docs-list.json
+++ b/packages/cli/test/__golden__/docs-list.json
@@ -15,6 +15,11 @@
"description": "Commands, programmatic APIs, integration authoring, and output contracts.",
"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": "unorganized",
"description": "Every topic that no section places yet. Each keeps its own name; open one by it.",