@astryxdesign/cli 0.1.2-canary.04e71b2 → 0.1.2-canary.05be2c6

package/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,
+      ],
+    },
+  ],
+};

package/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`,
+        },
+      ],
+    },
+  ],
+};

package/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' }] },
   ],
 };

package/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',
           ],
         },

package/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 查看完整参考' }] },
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.2-canary.04e71b2",
+  "version": "0.1.2-canary.05be2c6",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.04e71b2",
-    "@astryxdesign/lab": "0.1.2-canary.04e71b2",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.04e71b2",
+    "@astryxdesign/core": "0.1.2-canary.05be2c6",
+    "@astryxdesign/lab": "0.1.2-canary.05be2c6",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.05be2c6",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.04e71b2",
-    "@astryxdesign/lab": "0.1.2-canary.04e71b2",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.04e71b2",
+    "@astryxdesign/core": "0.1.2-canary.05be2c6",
+    "@astryxdesign/lab": "0.1.2-canary.05be2c6",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.05be2c6",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/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.

package/templates/pages/kanban-board/page.tsx

@@ -0,0 +1,729 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {
+  Layout,
+  LayoutHeader,
+  LayoutContent,
+  HStack,
+  VStack,
+} from '@astryxdesign/core/Layout';
+import {Text, Heading} from '@astryxdesign/core/Text';
+import {Card} from '@astryxdesign/core/Card';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Button} from '@astryxdesign/core/Button';
+import {IconButton} from '@astryxdesign/core/IconButton';
+import {Icon} from '@astryxdesign/core/Icon';
+import {StatusDot} from '@astryxdesign/core/StatusDot';
+import {EmptyState} from '@astryxdesign/core/EmptyState';
+import {MoreMenu} from '@astryxdesign/core/MoreMenu';
+import {Selector} from '@astryxdesign/core/Selector';
+import {Tooltip} from '@astryxdesign/core/Tooltip';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Toolbar} from '@astryxdesign/core/Toolbar';
+import {Section} from '@astryxdesign/core/Section';
+
+import {
+  PlusIcon,
+  MagnifyingGlassIcon,
+  ArrowsUpDownIcon,
+  FunnelIcon,
+  ArrowPathIcon,
+  CheckCircleIcon,
+  InboxIcon,
+  InformationCircleIcon,
+  ClipboardDocumentCheckIcon,
+} from '@heroicons/react/24/outline';
+
+// ============= TYPES =============
+
+type ColumnId = 'todo' | 'in-progress' | 'in-review' | 'done';
+type Priority = 'high' | 'medium' | 'low';
+
+interface WorkItem {
+  id: string;
+  column: ColumnId;
+  ref: string;
+  priority: Priority;
+  title: string;
+  description: string;
+  lastEdited: string;
+  dueDate: string;
+}
+
+interface ColumnMeta {
+  id: ColumnId;
+  title: string;
+  variant: 'neutral' | 'accent' | 'warning' | 'success';
+  tooltip: string;
+  emptyTitle: string;
+  emptyDescription: string;
+  emptyIcon: typeof InboxIcon;
+}
+
+// Where a dragged card will land: a column and an insertion index within it
+// (measured against the cards remaining after the dragged card is removed).
+interface DropTarget {
+  column: ColumnId;
+  index: number;
+}
+
+// Live state of an in-progress pointer drag. Coordinates are in viewport space.
+interface DragState {
+  id: string;
+  width: number;
+  height: number;
+  offsetX: number;
+  offsetY: number;
+  pointerX: number;
+  pointerY: number;
+  target: DropTarget | null;
+}
+
+// ============= DATA =============
+
+const COLUMNS: ColumnMeta[] = [
+  {
+    id: 'todo',
+    title: 'To-do',
+    variant: 'neutral',
+    tooltip: 'Items assigned to this sprint, waiting to be picked up.',
+    emptyTitle: 'To-do is empty',
+    emptyDescription: 'Items pulled into this sprint appear here.',
+    emptyIcon: InboxIcon,
+  },
+  {
+    id: 'in-progress',
+    title: 'In progress',
+    variant: 'accent',
+    tooltip: 'Items currently in progress.',
+    emptyTitle: 'Nothing in progress',
+    emptyDescription: 'Items being worked on appear here.',
+    emptyIcon: ArrowPathIcon,
+  },
+  {
+    id: 'in-review',
+    title: 'In review',
+    variant: 'warning',
+    tooltip: 'Items waiting for your review.',
+    emptyTitle: 'Nothing in review',
+    emptyDescription: 'Items awaiting your review appear here.',
+    emptyIcon: ClipboardDocumentCheckIcon,
+  },
+  {
+    id: 'done',
+    title: 'Done',
+    variant: 'success',
+    tooltip: 'Items that have been handled.',
+    emptyTitle: 'Nothing done yet',
+    emptyDescription: 'Completed items appear here.',
+    emptyIcon: CheckCircleIcon,
+  },
+];
+
+const PRIORITY_META: Record<
+  Priority,
+  {label: string; variant: 'error' | 'warning' | 'teal'}
+> = {
+  high: {label: 'High', variant: 'error'},
+  medium: {label: 'Medium', variant: 'warning'},
+  low: {label: 'Low', variant: 'teal'},
+};
+
+const INITIAL_ITEMS: WorkItem[] = [
+  {
+    id: 't1',
+    column: 'todo',
+    ref: 'Task 4821',
+    priority: 'low',
+    title: 'Draft project kickoff brief',
+    description:
+      'Write a short brief outlining goals, scope, and success criteria for the upcoming project.',
+    lastEdited: '2h ago',
+    dueDate: 'Jul 8',
+  },
+  {
+    id: 't2',
+    column: 'todo',
+    ref: 'Task 4842',
+    priority: 'low',
+    title: 'Collect feedback from stakeholders',
+    description:
+      'Gather input from key stakeholders and summarize the main themes for the next review.',
+    lastEdited: '1d ago',
+    dueDate: 'Jul 11',
+  },
+  {
+    id: 'p1',
+    column: 'in-progress',
+    ref: 'Task 4825',
+    priority: 'high',
+    title: 'Design the landing page layout',
+    description:
+      'Create a first-pass layout for the landing page and share it for early feedback.',
+    lastEdited: '18m ago',
+    dueDate: 'Jul 3',
+  },
+  {
+    id: 'p2',
+    column: 'in-progress',
+    ref: 'Task 4833',
+    priority: 'medium',
+    title: 'Set up the project workspace',
+    description:
+      'Configure the shared workspace and invite the team so everyone has access.',
+    lastEdited: '5m ago',
+    dueDate: 'Jul 4',
+  },
+  {
+    id: 'r1',
+    column: 'done',
+    ref: 'Task 4788',
+    priority: 'low',
+    title: 'Write the weekly status update',
+    description:
+      'Summarize progress, blockers, and next steps in a short update for the team.',
+    lastEdited: 'Yesterday',
+    dueDate: 'Jul 1',
+  },
+  {
+    id: 'r2',
+    column: 'done',
+    ref: 'Task 4789',
+    priority: 'high',
+    title: 'Prepare the demo walkthrough',
+    description:
+      'Put together a short walkthrough covering the main features for the demo.',
+    lastEdited: '3d ago',
+    dueDate: 'Jun 30',
+  },
+  {
+    id: 'r3',
+    column: 'done',
+    ref: 'Task 4790',
+    priority: 'medium',
+    title: 'Review and merge open changes',
+    description:
+      'Go through the pending changes, leave comments, and merge the ones that are ready.',
+    lastEdited: '4d ago',
+    dueDate: 'Jun 28',
+  },
+];
+
+// Pointer travel (px) before a press is promoted to a drag, so taps and clicks
+// on card controls still register normally.
+const DRAG_THRESHOLD = 5;
+
+// Shared width for every board column, so they stay visually aligned.
+const COLUMN_WIDTH = 300;
+
+// ============= STYLES =============
+
+const styles = stylex.create({
+  boardColumns: {
+    overflowX: 'auto',
+    overflowY: 'hidden',
+    height: '100%',
+    padding: 'var(--spacing-4)',
+  },
+  columnShell: {
+    flexShrink: 0,
+    flexBasis: COLUMN_WIDTH,
+    height: '100%',
+  },
+  card: {
+    cursor: 'grab',
+    userSelect: 'none',
+    touchAction: 'none',
+    transition: 'box-shadow 120ms ease',
+    ':hover': {
+      boxShadow: 'var(--shadow-med)',
+    },
+  },
+  // The dragged card is lifted out of flow and follows the pointer. It ignores
+  // pointer events so hit-testing reads the columns underneath it.
+  floating: {
+    position: 'fixed',
+    insetBlockStart: 0,
+    insetInlineStart: 0,
+    pointerEvents: 'none',
+    cursor: 'grabbing',
+    boxShadow: 'var(--shadow-high)',
+    zIndex: 1000,
+  },
+  floatingAt: (x: number, y: number, width: number) => ({
+    width,
+    transform: `translate(${x}px, ${y}px)`,
+  }),
+  // Placeholder marking the landing slot; matches the dragged card's height.
+  ghost: (height: number) => ({
+    height,
+    borderRadius: 'var(--radius-container)',
+    backgroundColor: 'var(--color-background-muted)',
+  }),
+  toolbarDivider: {
+    height: 'auto',
+    marginBlock: 'var(--spacing-1)',
+    alignSelf: 'stretch',
+  },
+  columnEmptyState: {
+    paddingBlock: 'var(--spacing-10)',
+  },
+});
+
+// ============= CARD BODY =============
+
+// Shared card contents, rendered both in the column list and inside the
+// floating drag clone so the two stay pixel-identical.
+function BoardCardBody({
+  item,
+  onMove,
+}: {
+  item: WorkItem;
+  onMove: (id: string, to: ColumnId) => void;
+}) {
+  const priority = PRIORITY_META[item.priority];
+  const moveTargets = COLUMNS.filter(c => c.id !== item.column).map(c => ({
+    label: `Move to ${c.title}`,
+    onClick: () => onMove(item.id, c.id),
+  }));
+
+  return (
+    <VStack gap={2}>
+      <HStack hAlign="between" vAlign="start">
+        <HStack gap={1} vAlign="center" wrap="wrap">
+          <Badge label={item.ref} variant="neutral" />
+          <Badge label={priority.label} variant={priority.variant} />
+        </HStack>
+        <MoreMenu
+          label="Work item actions"
+          size="sm"
+          items={[
+            {label: 'Open', onClick: () => {}},
+            {label: 'Assign to me', onClick: () => {}},
+            {type: 'divider'},
+            ...moveTargets,
+          ]}
+        />
+      </HStack>
+
+      <VStack gap={1}>
+        <Heading level={4}>{item.title}</Heading>
+        <Text type="supporting" color="secondary" maxLines={2}>
+          {item.description}
+        </Text>
+      </VStack>
+
+      <Text type="supporting" color="secondary">
+        Edited {item.lastEdited} · Due {item.dueDate}
+      </Text>
+    </VStack>
+  );
+}
+
+// ============= BOARD CARD =============
+
+function BoardCard({
+  item,
+  cardRef,
+  onPointerDown,
+  onMove,
+}: {
+  item: WorkItem;
+  cardRef: (el: HTMLDivElement | null) => void;
+  onPointerDown: (e: ReactPointerEvent, id: string) => void;
+  onMove: (id: string, to: ColumnId) => void;
+}) {
+  return (
+    <Card
+      ref={cardRef}
+      padding={3}
+      xstyle={styles.card}
+      onPointerDown={e => onPointerDown(e, item.id)}>
+      <BoardCardBody item={item} onMove={onMove} />
+    </Card>
+  );
+}
+
+// ============= BOARD COLUMN =============
+
+function BoardColumn({
+  meta,
+  count,
+  contentRef,
+  children,
+}: {
+  meta: ColumnMeta;
+  count: number;
+  contentRef: (el: HTMLDivElement | null) => void;
+  children: ReactNode;
+}) {
+  return (
+    <Card variant="muted" padding={0} xstyle={styles.columnShell}>
+      <Layout
+        height="fill"
+        header={
+          <LayoutHeader hasDivider padding={3}>
+            <HStack hAlign="between" vAlign="center">
+              <HStack gap={2} vAlign="center">
+                <StatusDot
+                  variant={meta.variant}
+                  label={`${meta.title} status`}
+                />
+                <Heading level={4}>{meta.title}</Heading>
+                <Tooltip content={meta.tooltip}>
+                  <Icon
+                    icon={InformationCircleIcon}
+                    size="sm"
+                    color="secondary"
+                  />
+                </Tooltip>
+              </HStack>
+              <Text type="supporting" color="secondary" hasTabularNumbers>
+                {count}
+              </Text>
+            </HStack>
+          </LayoutHeader>
+        }
+        content={
+          <LayoutContent ref={contentRef} padding={2}>
+            {children ?? (
+              <EmptyState
+                isCompact
+                xstyle={styles.columnEmptyState}
+                icon={
+                  <Icon icon={meta.emptyIcon} size="lg" color="secondary" />
+                }
+                title={meta.emptyTitle}
+                description={meta.emptyDescription}
+              />
+            )}
+          </LayoutContent>
+        }
+      />
+    </Card>
+  );
+}
+
+// ============= MAIN =============
+
+export default function KanbanBoardTemplate() {
+  const [items, setItems] = useState<WorkItem[]>(INITIAL_ITEMS);
+  const [sprint, setSprint] = useState('003');
+  const [drag, setDrag] = useState<DragState | null>(null);
+
+  // Live element registries for pointer hit-testing (kept out of render state).
+  const columnEls = useRef(new Map<ColumnId, HTMLElement>());
+  const cardEls = useRef(new Map<string, HTMLElement>());
+  const columnRefCbs = useRef(
+    new Map<ColumnId, (el: HTMLDivElement | null) => void>(),
+  );
+  const cardRefCbs = useRef(
+    new Map<string, (el: HTMLDivElement | null) => void>(),
+  );
+  const teardownRef = useRef<(() => void) | null>(null);
+
+  // Stable ref callbacks so registering an element never churns across renders.
+  const getColumnRef = (id: ColumnId) => {
+    let cb = columnRefCbs.current.get(id);
+    if (!cb) {
+      cb = el => {
+        if (el) {columnEls.current.set(id, el);}
+        else {columnEls.current.delete(id);}
+      };
+      columnRefCbs.current.set(id, cb);
+    }
+    return cb;
+  };
+
+  const getCardRef = (id: string) => {
+    let cb = cardRefCbs.current.get(id);
+    if (!cb) {
+      cb = el => {
+        if (el) {cardEls.current.set(id, el);}
+        else {cardEls.current.delete(id);}
+      };
+      cardRefCbs.current.set(id, cb);
+    }
+    return cb;
+  };
+
+  const itemsByColumn = useMemo(() => {
+    const map: Record<ColumnId, WorkItem[]> = {
+      todo: [],
+      'in-progress': [],
+      'in-review': [],
+      done: [],
+    };
+    for (const item of items) {
+      map[item.column].push(item);
+    }
+    return map;
+  }, [items]);
+
+  const moveItem = (id: string, to: ColumnId) => {
+    setItems(prev =>
+      prev.map(item => (item.id === id ? {...item, column: to} : item)),
+    );
+  };
+
+  // Resolve the pointer position to a column + insertion index, ignoring the
+  // card being dragged so the math is against the cards that stay in place.
+  const computeTarget = (
+    px: number,
+    py: number,
+    draggedId: string,
+  ): DropTarget | null => {
+    for (const [colId, el] of Array.from(columnEls.current.entries())) {
+      const r = el.getBoundingClientRect();
+      if (px < r.left || px > r.right || py < r.top || py > r.bottom) {continue;}
+
+      const ids = itemsByColumn[colId]
+        .filter(it => it.id !== draggedId)
+        .map(it => it.id);
+
+      let index = ids.length;
+      for (let i = 0; i < ids.length; i++) {
+        const cardEl = cardEls.current.get(ids[i]);
+        if (!cardEl) {continue;}
+        const cr = cardEl.getBoundingClientRect();
+        if (py < cr.top + cr.height / 2) {
+          index = i;
+          break;
+        }
+      }
+      return {column: colId, index};
+    }
+    return null;
+  };
+
+  // Rebuild the flat item list so the dragged card lands at the resolved slot
+  // while every other card keeps its relative order.
+  const commitDrag = (id: string, target: DropTarget) => {
+    setItems(prev => {
+      const moved = prev.find(it => it.id === id);
+      if (!moved) {return prev;}
+
+      const rest = prev.filter(it => it.id !== id);
+      const updated: WorkItem = {...moved, column: target.column};
+      const colItems = rest.filter(it => it.column === target.column);
+      const anchor = colItems[target.index];
+
+      if (!anchor) {return [...rest, updated];}
+      const at = rest.indexOf(anchor);
+      return [...rest.slice(0, at), updated, ...rest.slice(at)];
+    });
+  };
+
+  const onCardPointerDown = (e: ReactPointerEvent, id: string) => {
+    if (e.button !== 0) {return;}
+    // Let the card's own controls (the actions menu) handle the press.
+    if (
+      (e.target as HTMLElement).closest(
+        'button, [role="menuitem"], [role="menu"]',
+      )
+    ) {
+      return;
+    }
+
+    const el = cardEls.current.get(id);
+    if (!el) {return;}
+
+    const rect = el.getBoundingClientRect();
+    const startX = e.clientX;
+    const startY = e.clientY;
+    const offsetX = startX - rect.left;
+    const offsetY = startY - rect.top;
+    const {width, height} = rect;
+
+    let started = false;
+    let target: DropTarget | null = null;
+
+    const onMove = (ev: PointerEvent) => {
+      if (
+        !started &&
+        Math.abs(ev.clientX - startX) + Math.abs(ev.clientY - startY) <
+          DRAG_THRESHOLD
+      ) {
+        return;
+      }
+      started = true;
+      target = computeTarget(ev.clientX, ev.clientY, id);
+      setDrag({
+        id,
+        width,
+        height,
+        offsetX,
+        offsetY,
+        pointerX: ev.clientX,
+        pointerY: ev.clientY,
+        target,
+      });
+    };
+
+    const onUp = () => {
+      teardownRef.current?.();
+      if (started && target) {commitDrag(id, target);}
+      setDrag(null);
+    };
+
+    const teardown = () => {
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onUp);
+      teardownRef.current = null;
+    };
+    teardownRef.current = teardown;
+
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onUp);
+  };
+
+  const draggedItem = drag ? items.find(it => it.id === drag.id) : undefined;
+  const isDragging = drag !== null;
+
+  // Suppress selection while dragging and detach listeners on unmount.
+  useEffect(() => {
+    if (!isDragging) {return;}
+    const previous = document.body.style.userSelect;
+    document.body.style.userSelect = 'none';
+    return () => {
+      document.body.style.userSelect = previous;
+    };
+  }, [isDragging]);
+
+  useEffect(() => () => teardownRef.current?.(), []);
+
+  // Card nodes for a column, or null when the column should show its empty
+  // state. A dashed ghost box marks the landing slot during a drag.
+  const renderColumnCards = (colId: ColumnId): ReactNode => {
+    const colItems = itemsByColumn[colId];
+    const visible = drag ? colItems.filter(it => it.id !== drag.id) : colItems;
+    const ghostTarget =
+      drag && drag.target && drag.target.column === colId ? drag : null;
+
+    if (visible.length === 0 && !ghostTarget) {return null;}
+
+    const nodes: ReactNode[] = visible.map(it => (
+      <BoardCard
+        key={it.id}
+        item={it}
+        cardRef={getCardRef(it.id)}
+        onPointerDown={onCardPointerDown}
+        onMove={moveItem}
+      />
+    ));
+
+    if (ghostTarget && ghostTarget.target) {
+      const index = Math.min(ghostTarget.target.index, nodes.length);
+      nodes.splice(
+        index,
+        0,
+        <VStack key="drag-ghost" xstyle={styles.ghost(ghostTarget.height)} />,
+      );
+    }
+
+    return <VStack gap={2}>{nodes}</VStack>;
+  };
+
+  return (
+    <Section height="100dvh">
+      <Layout
+        height="fill"
+        header={
+          <LayoutHeader hasDivider padding={4}>
+            <Toolbar
+              label="Board actions"
+              gap={2}
+              startContent={
+                <>
+                  <Heading level={3}>Sprint Board</Heading>
+                  <Badge label={items.length} variant="neutral" />
+                </>
+              }
+              endContent={
+                <HStack gap={2}>
+                  <Selector
+                    label="Sprint"
+                    width={200}
+                    isLabelHidden
+                    value={sprint}
+                    onChange={setSprint}
+                    options={[
+                      {value: '003', label: 'Sprint 003'},
+                      {value: '002', label: 'Sprint 002'},
+                      {value: '001', label: 'Sprint 001'},
+                    ]}
+                  />
+                  <Divider
+                    variant="strong"
+                    orientation="vertical"
+                    xstyle={styles.toolbarDivider}
+                  />
+                  <HStack gap={1} vAlign="center">
+                    <IconButton
+                      icon={<Icon icon={ArrowsUpDownIcon} size="sm" />}
+                      label="Sort"
+                    />
+                    <IconButton
+                      icon={<Icon icon={FunnelIcon} size="sm" />}
+                      label="Filter"
+                    />
+                    <IconButton
+                      icon={<Icon icon={MagnifyingGlassIcon} size="sm" />}
+                      label="Search"
+                    />
+                  </HStack>
+                  <Button
+                    label="Add task"
+                    variant="primary"
+                    icon={<Icon icon={PlusIcon} size="sm" />}
+                  />
+                </HStack>
+              }
+            />
+          </LayoutHeader>
+        }
+        content={
+          <LayoutContent padding={0}>
+            <HStack gap={4} xstyle={styles.boardColumns}>
+              {COLUMNS.map(meta => (
+                <BoardColumn
+                  key={meta.id}
+                  meta={meta}
+                  count={itemsByColumn[meta.id].length}
+                  contentRef={getColumnRef(meta.id)}>
+                  {renderColumnCards(meta.id)}
+                </BoardColumn>
+              ))}
+            </HStack>
+          </LayoutContent>
+        }
+      />
+      {drag && draggedItem ? (
+        <Card
+          padding={3}
+          xstyle={[
+            styles.floating,
+            styles.floatingAt(
+              drag.pointerX - drag.offsetX,
+              drag.pointerY - drag.offsetY,
+              drag.width,
+            ),
+          ]}>
+          <BoardCardBody item={draggedItem} onMove={() => {}} />
+        </Card>
+      ) : null}
+    </Section>
+  );
+}

package/templates/pages/kanban-board/template.doc.mjs

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'page',
+  name: 'Kanban Board',
+  displayName: 'Kanban Board',
+  description:
+    'Task board with color-coded status columns, draggable task cards, priority tags, and metadata',
+  isReady: true,
+  category: 'Tools - Kanban Board',
+};