Skip to content

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

TypeScript

feat(cli): frame-first layout guidance — docs layout topic, agent rules, principles anti-patterns (#3315)

David Petersen8adfe3973200
diff --git a/.changeset/layout-guidance-docs.md b/.changeset/layout-guidance-docs.md
new file mode 100644
index 0000000000..b49e5165f1
--- /dev/null
+++ b/.changeset/layout-guidance-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Add frame-first layout guidance: new `astryx docs layout` topic (shell choice, region budgets, app archetypes, cards-vs-rows policy, responsive contracts), layout rules in the generated agent cheat sheet, and layout anti-patterns in `docs principles`.
+
+@thedjpetersen
diff --git a/packages/cli/docs/layout.doc.dense.mjs b/packages/cli/docs/layout.doc.dense.mjs
new file mode 100644
index 0000000000..3997f32445
--- /dev/null
+++ b/packages/cli/docs/layout.doc.dense.mjs
@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
+
+export const docsDense = {
+ description:
+ 'frame-first app layout: shell choice, region budgets, cards vs rows',
+ sections: [
+ {
+ title: 'Frame First',
+ content: [
+ {
+ type: 'prose',
+ text: 'decide frame before content. content-first (Card-wrapped sections in a scroll column) = prototype look.',
+ },
+ {
+ 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',
+ ],
+ },
+ null,
+ ],
+ },
+ {
+ title: 'App Archetypes',
+ content: [
+ {
+ type: 'prose',
+ text: 'container choice tracks archetype, not preference.',
+ },
+ null,
+ {
+ type: 'prose',
+ text: 'start from matching template (astryx template --list), study with --skeleton.',
+ },
+ ],
+ },
+ {
+ title: 'Cards vs Rows',
+ content: [
+ {
+ 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.',
+ },
+ {
+ 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',
+ ],
+ },
+ {
+ 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',
+ ],
+ },
+ ],
+ },
+ {
+ title: 'Panels and Inspectors',
+ content: [
+ {
+ type: 'prose',
+ text: 'master-detail: row select opens fixed-width inspector (LayoutPanel end slot + width budget + resizable/useResizable). overlay content <=1024px, do not compress.',
+ },
+ null,
+ ],
+ },
+ {
+ title: 'Responsive Contract',
+ content: [
+ {
+ type: 'prose',
+ text: 'declare breakpoint behavior as comment at frame root: which regions collapse/overlay/drop at which widths.',
+ },
+ null,
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/docs/layout.doc.mjs b/packages/cli/docs/layout.doc.mjs
new file mode 100644
index 0000000000..aed1824aa2
--- /dev/null
+++ b/packages/cli/docs/layout.doc.mjs
@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+ name: 'layout',
+ title: 'Layout',
+ category: 'guide',
+ description:
+ 'Frame-first app layout: choosing a shell, budgeting regions, and when to use cards vs rows.',
+
+ sections: [
+ {
+ title: 'Frame First',
+ 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.',
+ },
+ {
+ 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)',
+ ],
+ },
+ {
+ 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>`,
+ },
+ ],
+ },
+ {
+ title: 'App Archetypes',
+ content: [
+ {
+ 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.',
+ },
+ {
+ 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: 'prose',
+ text: 'Start from a template that matches the archetype (`npx astryx template --list`), then study its structure with `--skeleton` before customizing.',
+ },
+ ],
+ },
+ {
+ title: 'Cards vs Rows',
+ content: [
+ {
+ 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.',
+ },
+ {
+ 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',
+ ],
+ },
+ {
+ 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',
+ ],
+ },
+ ],
+ },
+ {
+ title: 'Panels and Inspectors',
+ content: [
+ {
+ 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.',
+ },
+ {
+ 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>`,
+ },
+ ],
+ },
+ {
+ title: 'Responsive Contract',
+ content: [
+ {
+ 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.',
+ },
+ {
+ 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`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/docs/principles.doc.dense.mjs b/packages/cli/docs/principles.doc.dense.mjs
index 2fb3f0c3de..6cceb54b0a 100644
--- a/packages/cli/docs/principles.doc.dense.mjs
+++ b/packages/cli/docs/principles.doc.dense.mjs
@@ -6,9 +6,9 @@ export const docsDense = {
description: 'core design principles + rules for the design system',
sections: [
{ title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
- { title: 'Rules', content: [{ type: 'list', items: ['use components', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
+ { title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
{ title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
- { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'read docs before inventing props'] }] },
+ { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
{ title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
],
};
diff --git a/packages/cli/docs/principles.doc.mjs b/packages/cli/docs/principles.doc.mjs
index 40e36400dc..1b20c98e74 100644
--- a/packages/cli/docs/principles.doc.mjs
+++ b/packages/cli/docs/principles.doc.mjs
@@ -39,6 +39,8 @@ export const docs = {
style: 'ordered',
items: [
'Use components for everything they cover',
+ 'Layout is frame-first: pick the shell and budget regions before writing content (see \`npx astryx docs 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 \`npx astryx docs styling\`)',
'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
'CSS custom properties for colors, not hex values',
@@ -74,6 +76,8 @@ 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 \`npx astryx docs 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/docs/principles.doc.zh.mjs b/packages/cli/docs/principles.doc.zh.mjs
index 1c4b3f3818..977e916930 100644
--- a/packages/cli/docs/principles.doc.zh.mjs
+++ b/packages/cli/docs/principles.doc.zh.mjs
@@ -6,9 +6,9 @@ export const docsZh = {
description: 'XDS 核心设计原则和规则。',
sections: [
{ title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },
- { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },
+ { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 astryx docs layout)', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },
{ title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
- { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要自创属性。先阅读组件文档'] }] },
+ { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 astryx docs layout)', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
{ title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },
],
};
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index 14160340ca..2bb9b25c25 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -180,6 +180,9 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
// Rules — the top error-preventers.
lines.push('RULES:');
lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
+ lines.push('- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).');
+ lines.push('- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.');
+ lines.push('- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.');
// Styling guidance tailored to the project's configured system — never
// recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
// utilities need Tailwind). Tokens are always the source of truth.