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.mdnew file mode 100644index 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`.++@thedjpetersendiff --git a/packages/cli/docs/layout.doc.dense.mjs b/packages/cli/docs/layout.doc.dense.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.