An open source design system that's fully customizable and agent ready
TypeScript
docs(layout): rewrite as an outside-in build sequence with tiered guidance (#5164)
Ernest33ba2b6a81b0
diff --git a/apps/docsite/src/components/docs/ReferenceDocView.tsx b/apps/docsite/src/components/docs/ReferenceDocView.tsxindex 199de94b30..c7bf76ed2b 100644--- a/apps/docsite/src/components/docs/ReferenceDocView.tsx+++ b/apps/docsite/src/components/docs/ReferenceDocView.tsx@@ -84,12 +84,16 @@ function buildOutline(sections: DocSection[]): {return {sectionIds, blockIds, outline};}-function isBestPracticesSection(section: DocSection): boolean {- return section.content.every(- b => b.type === 'list' && (b.style === 'do' || b.style === 'dont'),+function isGuidanceList(block: DocSection['content'][number] | undefined) {+ return (+ block?.type === 'list' && (block.style === 'do' || block.style === 'dont'));}+function isBestPracticesSection(section: DocSection): boolean {+ return section.content.every(isGuidanceList);+}+function BestPracticesSection({section,id,@@ -162,6 +166,28 @@ export function ReferenceDocView({);}}+ // A run of do/dont lists is one badge table, so guidance+ // keeps its Do/Don't label outside all-guidance sections.+ if (isGuidanceList(block)) {+ if (isGuidanceList(section.content[blockIndex - 1])) {+ return null;+ }+ const items: {guidance: boolean; description: string}[] =+ [];+ for (let j = blockIndex; j < section.content.length; j++) {+ const run = section.content[j];+ if (!isGuidanceList(run)) {break;}+ for (const item of run.items ?? []) {+ items.push({+ guidance: run.style === 'do',+ description: item,+ });+ }+ }+ return (+ <BestPracticesBlock key={blockIndex} items={items} />+ );+ }return (<ContentBlockRenderer key={blockIndex} block={block} />);diff --git a/packages/cli/assets/docs/layout.doc.dense.mjs b/packages/cli/assets/docs/layout.doc.dense.mjsindex ba5f6f33cf..7e5a25fe9d 100644--- a/packages/cli/assets/docs/layout.doc.dense.mjs+++ b/packages/cli/assets/docs/layout.doc.dense.mjs@@ -4,91 +4,336 @@export const docsDense = {description:- 'frame-first app layout: shell choice, region budgets, cards vs rows',+ 'outside-in app layout: scaffold -> structure -> spacing -> breakpoints.',sections: [{- section: 'Frame First',- title: 'Frame First',+ section: 'Overview',+ title: 'Overview',content: [{type: 'prose',- text: 'decide frame before content. content-first (Card-wrapped sections in a scroll column) = prototype look.',+ 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: [- 'pick frame: AppShell (nav apps) | Layout+LayoutPanel+LayoutContent (multi-pane tools) | plain column (docs/forms)',- 'budget regions in px first: side nav 240-280, rail 64-72, inspector 340-420, facet rail 220-260',- 'container policy per region: dense data = rows; dashboards/galleries = card grids',- 'write responsive contract up front',+ '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',],},- null,+ {+ type: 'prose',+ text: 'decides layout, not component APIs. npx astryx build "<idea>" = closest template for your app type. npx astryx component <Name> = props.',+ },],},{- section: 'App Archetypes',- title: 'App Archetypes',+ section: 'Scaffold',+ title: 'Scaffold',content: [+ // Shell+ null,{type: 'prose',- text: 'container choice tracks archetype, not preference.',+ 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.',+ },+ // Navigation+ null,+ {+ 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: 'start from matching template (astryx template --list), study with --skeleton.',+ text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the closest template, --skeleton shows the pairing wired up.',+ },+ // Best practices+ null,+ {+ 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: 'Cards vs Rows',- title: 'Cards vs Rows',+ section: 'Structure',+ title: 'Structure',content: [+ // Type hierarchy+ null,+ {+ 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.',+ },+ // Containers+ null,+ {+ 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.',+ },+ // Headers and footers+ null,+ {+ 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.',+ },+ // Side panels+ null,+ {+ 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: 'Card = widget container, NOT list-item wrapper. dense/scannable/selectable data = rows: Table (columnar) or List/Item (single-line), edge-to-edge, 32-40px rows, dividers.',+ 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.',},+ // Best practices+ null,{type: 'list',items: [- 'Table+plugins: hosts, deployments, monitors, users',- 'List/Item rows: issues, files, conversations',- 'Card: KPI tiles, chart panels, gallery entries, settings groups',- 'EmptyState for zero-match',+ '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: [- 'no Card-wrapped list items (card soup)',- 'no stacked full-width Cards as page structure',- 'no Cards in Cards',- 'no decorative Badge: counts/enums only; StatusDot/Token for status',+ '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: 'Panels and Inspectors',- title: 'Panels and Inspectors',+ section: 'Spacing',+ title: 'Spacing',content: [+ // Alignment+ null,+ {+ 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: 'master-detail: row select opens fixed-width inspector (LayoutPanel end slot + width budget + resizable/useResizable). overlay content <=1024px, do not compress.',+ text: 'verify: draw one vertical line down the left. every label touches it; only hover/selected backgrounds cross it.',},+ // Rhythmnull,+ {+ 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.',+ },+ // Density and size+ null,+ {+ 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.',+ },+ // Best practices+ null,+ {+ 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: 'Responsive Contract',- title: 'Responsive Contract',+ section: 'Breakpoints',+ title: 'Breakpoints',content: [+ // Responsive contract+ null,{type: 'prose',- text: 'declare breakpoint behavior as comment at frame root: which regions collapse/overlay/drop at which widths.',+ 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.',+ },+ // Best practices+ null,+ {+ 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',+ ],+ },],},],diff --git a/packages/cli/assets/docs/layout.doc.mjs b/packages/cli/assets/docs/layout.doc.mjsindex 985a6cf971..81dbe72198 100644--- a/packages/cli/assets/docs/layout.doc.mjs+++ b/packages/cli/assets/docs/layout.doc.mjs@@ -7,152 +7,486 @@ export const docs = {title: 'Layout',category: 'guide',description:- 'Frame-first app layout: choosing a shell, budgeting regions, and when to use cards vs rows.',+ 'Build an app layout outside-in: scaffold the regions, structure the content, tune the spacing, then adapt across widths.',sections: [{- title: 'Frame First',+ title: 'Overview',content: [{type: 'prose',- text: 'Decide the frame before writing any content. Real applications are built top-down: pick the shell, name its regions, give each region an explicit size budget, then fill regions with content. Content-first layout (writing sections and wrapping each one in a Card) produces a padded scroll column that reads as a prototype, not a product.',+ 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: [- 'Pick the frame: AppShell (top nav and/or side nav apps), Layout + LayoutPanel + LayoutContent (multi-pane tools like explorers and consoles), or a plain content column (documents, marketing, forms)',- 'Budget regions in px before filling them: side nav 240–280, icon rail 64–72, detail/inspector panel 340–420, filter/facet rail 220–260',- 'Decide the container policy per region: dense data renders as rows; widget dashboards and galleries render as card grids (see Cards vs Rows)',- 'Write the responsive contract up front: which regions collapse, overlay, or drop at which breakpoints (see Responsive Contract)',+ '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: 'code',- lang: 'tsx',- label: 'A three-region tool frame',- code: `// Frame: nav 256 | content flex | inspector 380 (resizable)-<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>} contentPadding={0}>- <Layout>- <LayoutContent>{/* dense list or table, edge-to-edge */}</LayoutContent>- <LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider>- {/* inspector for the selected row */}- </LayoutPanel>- </Layout>-</AppShell>`,+ 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.',},],},{- title: 'App Archetypes',+ title: 'Scaffold',content: [+ {type: 'heading', level: 3, text: 'Shell'},{type: 'prose',- text: 'Match the frame and container policy to the kind of app you are building. These recipes are distilled from product-scale apps built with the design system; container choice tracks the archetype, not personal preference.',+ 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: 'table',- headers: ['Archetype', 'Frame', 'Container policy'],- rows: [- [- 'Tracker / work tool (issues, tickets, CRM)',- 'AppShell + SideNav; inspector LayoutPanel on select',- 'Rows only. Grouped edge-to-edge lists, zero cards',- ],- [- 'Console / observability (metrics, logs, deploys)',- 'AppShell + SideNav or TopNav + TabList',- 'Card grid for dashboard widgets; Table for everything else',- ],- [- 'Messaging / feed',- 'Column frame: rail + sidebar + stream + panel',- 'Rows and bubbles. No cards in the stream',- ],- [- 'Media library / gallery',- 'AppShell + TopNav; grid content',- 'Card grid (ClickableCard) with dense metadata rows in detail views',- ],- [- 'Settings / forms',- 'AppShell + SideNav or settings template',- 'Sections with FormLayout; Card only to group dangerous or billing actions',- ],+ 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.',+ },++ {type: 'heading', level: 3, text: 'Navigation'},{type: 'prose',- text: 'Start from a template that matches the archetype (`npx astryx template --list`), then study its structure with `--skeleton` before customizing.',+ 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 closest template, and its `--skeleton` shows the pairing already wired up.',+ },++ {type: 'heading', level: 3, text: 'Best practices'},+ {+ 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',+ ],},],},{- title: 'Cards vs Rows',+ title: 'Structure',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.',+ },+ {+ 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.',+ },++ {type: 'heading', level: 3, text: 'Containers'},+ {+ 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.',+ },++ {type: 'heading', level: 3, text: 'Headers and footers'},+ {+ 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.',+ },++ {type: 'heading', level: 3, text: 'Side panels'},+ {+ 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: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data (anything the user scans, filters, or selects) belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',+ 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.',},++ {type: 'heading', level: 3, text: 'Best practices'},{type: 'list',style: 'do',items: [- 'Table (with selection/sorting plugins) for columnar records: hosts, deployments, monitors, users',- 'List/Item rows for scannable single-line records: issues, files, conversations',- 'Card for self-contained widgets: KPI tiles, chart panels, gallery entries, settings groups',- 'EmptyState inside the region when a filter matches nothing',+ '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: [- 'Wrapping each list item in a Card (card soup)',- 'Stacking full-width Cards as a substitute for page structure',- 'Nesting Cards inside Cards',- 'Using Badge as decoration: reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',+ '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: 'Panels and Inspectors',+ title: 'Spacing',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`.',+ },+ {+ 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.',+ },++ {type: 'heading', level: 3, text: 'Rhythm'},+ {+ 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.',+ },++ {type: 'heading', level: 3, text: 'Density and size'},{type: 'prose',- text: 'Master-detail is the backbone of tool UIs: selecting a row opens a fixed-width inspector panel rather than navigating away. Use LayoutPanel in the end slot with an explicit width budget; add resizable (useResizable) for user control, and let the panel overlay the content region below ~1024px instead of compressing it.',+ 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: 'Inspector that overlays at narrow widths',- code: `<LayoutPanel- width={380}- hasDivider- isScrollable- label="Details"- resizable={{minSizePx: 320, maxSizePx: 480, autoSaveId: 'inspector'}}>- {selected ? <DetailFields item={selected} /> : <EmptyState title="Nothing selected" />}-</LayoutPanel>`,+ 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.',+ },++ {type: 'heading', level: 3, text: 'Best practices'},+ {+ 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',+ ],},],},{- title: 'Responsive Contract',+ title: 'Breakpoints',content: [+ {type: 'heading', level: 3, text: 'Responsive contract'},{type: 'prose',- text: 'Declare breakpoint behavior as a contract before building, and keep it in a comment at the frame root. A typical contract: full frame above 1024px; inspector panels overlay the content column at 1024px and below; the side nav collapses into MobileNav at 768px and below. Deciding this up front keeps every region change intentional instead of emergent.',+ 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 comment at the frame root',- code: `// Responsive contract:-// > 1024px nav 256 | content | inspector 380-// <= 1024px inspector overlays content (position: absolute, end-aligned)-// <= 768px nav collapses into MobileNav drawer; toolbar actions wrap`,+ 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.',+ },++ {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',+ ],},],},diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjsindex 3c05987fa4..7b2aadfcde 100644--- a/packages/core/src/Layout/Layout.doc.mjs+++ b/packages/core/src/Layout/Layout.doc.mjs@@ -93,6 +93,24 @@ export const docs = {description: 'Height behavior: fill the container or grow with content.',default: "'fill'",},+ {+ name: 'contentWidth',+ type: 'number | string',+ description:+ 'Maximum width of the content within each slot (header, content, footer, panels), centered when narrower than the available space. Dividers stay full-bleed. Numbers are pixels, strings are used as-is (e.g. `60ch`). Common page widths: 640 for forms, settings, and text-focused pages; 960 for content pages and wider layouts.',+ },+ {+ name: 'padding',+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',+ description:+ "Padding at the layout's outer edges using the spacing scale.",+ },+ {+ name: 'defaultHasDividers',+ type: 'boolean',+ description:+ "Default divider visibility for LayoutHeader and LayoutFooter children. Headers and footers that don't pass `hasDivider` use this value; when unset, nested layouts inherit from their parent context.",+ },],components: [{name: 'LayoutHeader'},