@loworbitstudio/visor 1.5.0 → 1.6.0

package/dist/visor-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-06-04T00:42:59.544Z",
+  "generated_at": "2026-06-11T14:53:30.668Z",
   "components": {
     "accessibility-specimen": {
       "category": "specimen",
@@ -164,15 +164,16 @@
         "variant": [
           "default",
           "compact",
-          "timeline"
+          "timeline",
+          "compact-3col"
         ]
       },
       "props": [
         {
           "name": "variant",
-          "type": "'default' | 'compact' | 'timeline'",
+          "type": "'default' | 'compact' | 'timeline' | 'compact-3col'",
           "default": "default",
-          "description": "Display mode. Default is padded rows with borders, compact is denser, timeline adds a connecting rail between leading indicators."
+          "description": "Display mode. Default is padded rows with borders, compact is denser, timeline adds a connecting rail between leading indicators, compact-3col pins timestamp to the leftmost column with [time][dot][text] layout."
         },
         {
           "name": "children",
@@ -182,6 +183,7 @@
       ],
       "dependencies": [],
       "tokens_used": [
+        "--af-time-col",
         "--border-default",
         "--border-muted",
         "--font-size-sm",
@@ -378,6 +380,7 @@
         "class-variance-authority"
       ],
       "tokens_used": [
+        "--badge-text-transform",
         "--border-default",
         "--border-focus",
         "--color-neutral-600",
@@ -899,6 +902,12 @@
           "default": "false",
           "description": "Render inline (non-sticky) instead of fixed to the viewport bottom."
         },
+        {
+          "name": "flat",
+          "type": "boolean",
+          "default": "false",
+          "description": "Render flat — no shadow, no border-radius, border-top only. Use inside table cards or panels where the floating card look is wrong."
+        },
         {
           "name": "label",
           "type": "(count: number) => React.ReactNode",
@@ -1039,7 +1048,7 @@
         "--interactive-secondary-text",
         "--motion-duration-150",
         "--motion-easing-default",
-        "--opacity-50",
+        "--opacity-40",
         "--primary",
         "--radius-md",
         "--spacing-2",
@@ -1538,6 +1547,12 @@
               "type": "\"primary\" | \"neutral\"",
               "default": "\"neutral\"",
               "description": "Tone for the count pill. \"neutral\" uses muted surface; \"primary\" uses accent surface. Auto re-tones on selected state."
+            },
+            {
+              "name": "selectedTreatment",
+              "type": "\"accent\" | \"neutral\"",
+              "default": "\"accent\"",
+              "description": "Selected-state visual treatment. \"accent\" (default) uses accent-tinted bg + accent border + link text. \"neutral\" uses --surface-card bg + neutral border + primary text; the count pill renders as a solid mint pill (--surface-success-default) when selected. Use in editorial/admin contexts where accent bleed is undesirable.\n"
             }
           ]
         }
@@ -1549,6 +1564,7 @@
       "tokens_used": [
         "--border-default",
         "--border-focus",
+        "--border-strong",
         "--focus-ring-offset",
         "--focus-ring-width",
         "--font-body",
@@ -1570,6 +1586,8 @@
         "--surface-card",
         "--surface-interactive-hover",
         "--surface-muted",
+        "--surface-success-default",
+        "--text-inverse",
         "--text-link",
         "--text-primary",
         "--text-secondary"
@@ -2642,7 +2660,7 @@
           "name": "density",
           "type": "\"compact\" | \"default\" | \"editorial\"",
           "default": "\"default\"",
-          "description": "Vertical row padding step. Maps to a `data-density` attribute on the root, which sets the `--dt-row-py` custom property the table's cells consume. `\"compact\"` = 8px (sub-content density: long lists, narrow viewports). `\"default\"` = 12px (current behaviour; backward-compatible with consumers that don't pass the prop). `\"editorial\"` = 20px (generous; each row reads as a card; high-design admin patterns). Themes can override per-density values without forking the component by targeting `[data-density=\"…\"]` from their own selector.\n"
+          "description": "Vertical row padding step. Maps to a `data-density` attribute on the root, which sets the `--dt-row-py` custom property the table's cells consume. `\"compact\"` = 8px (sub-content density: long lists, narrow viewports). `\"default\"` = 12px (current behaviour; backward-compatible with consumers that don't pass the prop). `\"editorial\"` = 20px (generous; each row reads as a card; high-design admin patterns) — column headers also receive the editorial treatment: uppercase, `--font-size-xs` (~11px), `--text-tertiary` color, and `letter-spacing: 0.08em`. Themes can override per-density values without forking the component by targeting `[data-density=\"…\"]` from their own selector.\n"
         },
         {
           "name": "rowTone",
@@ -2663,6 +2681,7 @@
       "tokens_used": [
         "--border-default",
         "--border-strong",
+        "--data-table-sort-bar-radius",
         "--dt-row-py",
         "--focus-ring-color",
         "--focus-ring-offset",
@@ -2674,6 +2693,7 @@
         "--line-height-tight",
         "--motion-duration-fast",
         "--motion-easing-standard",
+        "--radius-lg",
         "--radius-md",
         "--radius-sm",
         "--spacing-1",
@@ -3969,6 +3989,103 @@
       ],
       "example": "<Image\n  src=\"/photos/hero.jpg\"\n  alt=\"Mountain landscape\"\n  aspectRatio=\"video\"\n/>\n\n<Image\n  src={user.avatar}\n  alt={user.name}\n  aspectRatio=\"square\"\n  objectFit=\"cover\"\n  fallback={<span>No photo</span>}\n/>\n"
     },
+    "infographic-bar": {
+      "category": "admin",
+      "description": "Composable continuous stat-card band. Lays out N stat-cards as a single infographic strip — outer corners rounded, inner corners square, hairline dividers, no full per-card borders.",
+      "when_to_use": [
+        "Rendering a KPI/metric row that should read as ONE continuous band, not separate bordered cards",
+        "Admin dashboard summary strips where several metrics share a single framed surface",
+        "Theme-portable metric rows that must look right in both bordered and borderless palettes"
+      ],
+      "when_not_to_use": [
+        "Showing a single metric (use StatCard directly)",
+        "Metrics that each need their own card with its own border and elevation (compose StatCards in a grid instead)",
+        "Tabular metrics across many rows (use DataTable)",
+        "Marketing feature tiles (use a marketing card pattern)"
+      ],
+      "props": [
+        {
+          "name": "stats",
+          "type": "InfographicBarStat[]",
+          "required": true,
+          "description": "Ordered stat cells, rendered left-to-right as a single continuous band. Each item is a subset of StatCardProps."
+        },
+        {
+          "name": "stats[].label",
+          "type": "React.ReactNode",
+          "required": true,
+          "description": "Small uppercase label describing the metric."
+        },
+        {
+          "name": "stats[].value",
+          "type": "React.ReactNode",
+          "required": true,
+          "description": "Prominent metric value."
+        },
+        {
+          "name": "stats[].delta",
+          "type": "StatCardDelta",
+          "description": "Change indicator with value, direction (\"up\" | \"down\" | \"flat\"), and optional label."
+        },
+        {
+          "name": "stats[].trend",
+          "type": "React.ReactNode",
+          "description": "Slot for a sparkline, chart, or icon."
+        },
+        {
+          "name": "stats[].trendPosition",
+          "type": "'header' | 'footer'",
+          "default": "footer",
+          "description": "Where the trend slot renders within the cell."
+        },
+        {
+          "name": "stats[].footer",
+          "type": "React.ReactNode",
+          "description": "Sublabel or link rendered beneath the value."
+        },
+        {
+          "name": "stats[].variant",
+          "type": "'default' | 'highlight'",
+          "default": "default",
+          "description": "Per-cell visual emphasis. Highlight tints that cell's surface."
+        },
+        {
+          "name": "stats[].valueAs",
+          "type": "'default' | 'hero' | 'compact'",
+          "default": "default",
+          "description": "Typography scale for the cell value."
+        },
+        {
+          "name": "stats[].id",
+          "type": "string",
+          "description": "Stable React key for the cell. Falls back to the array index when omitted."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md'",
+          "default": "md",
+          "description": "Dimensional density forwarded to every cell."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Additional CSS class names merged onto the band element."
+        }
+      ],
+      "dependencies": [
+        "stat-card"
+      ],
+      "tokens_used": [
+        "--border-default",
+        "--hairline",
+        "--infographic-bar-divider",
+        "--radius-lg",
+        "--shadow-xs",
+        "--stroke-width-thin",
+        "--surface-card"
+      ],
+      "example": "<InfographicBar\n  stats={[\n    { label: \"Total Revenue\", value: \"$48,120\", delta: { value: \"+12.4%\", direction: \"up\", label: \"vs last month\" } },\n    { label: \"Active Users\", value: \"892\", delta: { value: \"+3.1%\", direction: \"up\" } },\n    { label: \"Churn Rate\", value: \"3.2%\", delta: { value: \"-0.4%\", direction: \"down\" } },\n    { label: \"Signups\", value: \"412\", variant: \"highlight\" },\n  ]}\n/>\n"
+    },
     "inline": {
       "category": "layout",
       "description": "Horizontal flex container with token-driven gap, alignment, optional wrap, and `as` polymorphism.",
@@ -4425,6 +4542,73 @@
       ],
       "example": "<Marquee\n  items={['Acme Corp', 'Vercel', 'Low Orbit Studio', 'Figma', 'Notion']}\n  durationSec={20}\n  separator=\"·\"\n/>\n\n<Marquee\n  bands={[\n    { items: clients, direction: 'left', durationSec: 40, separator: '●' },\n    { items: clientsReversed, direction: 'right', durationSec: 50, separator: '○' },\n  ]}\n  pauseOnHover\n  gap=\"2.5rem\"\n/>\n"
     },
+    "matrix-table": {
+      "category": "admin",
+      "description": "A fixed assignment grid component for members×roles patterns. Sticky-left identity column, centered boolean cells (22px filled-success check when active / muted empty when not), and multi-line centered column headers (label over count) that opt out of the uppercase header treatment. No list machinery — no selection column, no sort buttons, no pagination footer.",
+      "when_to_use": [
+        "Displaying a members × roles assignment matrix in organization settings",
+        "Any fixed grid where rows are identities (users, items) and columns are boolean attributes (permissions, roles, features)",
+        "When the shape is a matrix, not a sortable/pageable list — where DataTable's list machinery would fight the layout"
+      ],
+      "when_not_to_use": [
+        "Sortable, paginated lists of records (use DataTable)",
+        "Editable grids with input cells (extend or build a dedicated grid)",
+        "Simple key-value tables (use the Table primitive directly)"
+      ],
+      "variants": {},
+      "props": [
+        {
+          "name": "columns",
+          "type": "MatrixColumn[]",
+          "required": true,
+          "description": "Column definitions. Each column has an `id`, `label`, and optional `count` sub-label rendered below the label in the header."
+        },
+        {
+          "name": "rows",
+          "type": "MatrixRow<TIdentity>[]",
+          "required": true,
+          "description": "Row data. Each row has an `id`, an `identity` value passed to `renderIdentity`, an `activeColumns` set/array of column ids that should show the active check indicator, and an optional `cells` map of per-column values. A `cells` entry (`string | boolean`) overrides `activeColumns` for that column — `true`/`false` render the boolean indicator, a `string` renders as plain text in the standard cell style."
+        },
+        {
+          "name": "renderIdentity",
+          "type": "(identity: TIdentity) => React.ReactNode",
+          "required": true,
+          "description": "Render slot for the sticky-left identity cell. Receives the row's `identity` value — typically renders a name, avatar+name, or any identity compound."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "description": "Accessible label for the table element."
+        }
+      ],
+      "dependencies": [
+        "@phosphor-icons/react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--border-default",
+        "--font-size-sm",
+        "--font-weight-medium",
+        "--font-weight-normal",
+        "--line-height-tight",
+        "--motion-duration-fast",
+        "--motion-easing-standard",
+        "--radius-full",
+        "--radius-lg",
+        "--shadow-sm",
+        "--spacing-1",
+        "--spacing-2",
+        "--spacing-3",
+        "--stroke-width-thin",
+        "--surface-card",
+        "--surface-muted",
+        "--surface-success-default",
+        "--text-inverse",
+        "--text-primary",
+        "--text-tertiary"
+      ],
+      "example": "const columns: MatrixColumn[] = [\n  { id: 'admin', label: 'Admin', count: 3 },\n  { id: 'editor', label: 'Editor', count: 5 },\n  { id: 'viewer', label: 'Viewer', count: 12 },\n]\n\nconst rows: MatrixRow<{ name: string; email: string }>[] = [\n  { id: '1', identity: { name: 'Ada Lovelace', email: 'ada@example.com' }, activeColumns: new Set(['admin', 'editor']) },\n  { id: '2', identity: { name: 'Grace Hopper', email: 'grace@example.com' }, activeColumns: ['viewer'] },\n  // Mixed string + boolean cells via `cells` (string renders as plain text):\n  { id: '3', identity: { name: 'Storage', email: '' }, activeColumns: [], cells: { admin: '50GB', editor: true, viewer: false } },\n]\n\n<MatrixTable\n  columns={columns}\n  rows={rows}\n  renderIdentity={(identity) => <span>{identity.name}</span>}\n  aria-label=\"Member role assignments\"\n/>\n"
+    },
     "menubar": {
       "category": "overlay",
       "description": "Horizontal menu bar with dropdown menus, keyboard navigation, and full a11y support.",
@@ -5001,6 +5185,11 @@
           "name": "titleFamily",
           "type": "'heading' | 'display' | string",
           "description": "Title font-family override. `\"heading\"` and `\"display\"` are tokens that map to `data-title-family` attributes; `\"display\"` resolves to `var(--font-display, var(--font-family-heading, inherit))` so themes without a display font degrade to the heading family. Any other string is forwarded as a raw CSS family on an inline `--page-header-title-family` declaration.\n"
+        },
+        {
+          "name": "leading",
+          "type": "string | number",
+          "description": "Title line-height override, forwarded as an inline `--page-header-title-leading` custom property (a unitless number like `1.05` or any CSS length). When omitted the title keeps its default line-height (tight for the standard title, `1` for the marquee scale), so existing call sites render unchanged.\n"
         }
       ],
       "dependencies": [
@@ -5021,6 +5210,7 @@
         "--line-height-relaxed",
         "--line-height-tight",
         "--page-header-title-family",
+        "--page-header-title-leading",
         "--page-header-title-size",
         "--spacing-1",
         "--spacing-2",
@@ -5758,6 +5948,86 @@
       ],
       "example": "<SectionHeader title=\"Tonight's events\" meta=\"2 events\" />\n<SectionHeader title=\"Activity\" meta=\"last hour\" />\n<SectionHeader title=\"Top promoters · 30d\" />\n"
     },
+    "section-nav": {
+      "category": "navigation",
+      "description": "A link/anchor-based section sub-navigation strip — a leading Phosphor icon + label + optional trailing count pill per item, with a static 2px primary underline on the active item. Items navigate via href (use `asChild` with `next/link` for client-side routing). Distinct from Tabs — no button triggers, no content panels, no animated indicator.",
+      "when_to_use": [
+        "A sub-navigation strip across the top of a detail view whose tabs are real routes (e.g. Organization → Detail / Roles / Invites)",
+        "When each section is its own URL and you want client-side navigation via next/link rather than in-page panel switching",
+        "When sections carry a count (member count, pending invites) you want to surface in a trailing pill"
+      ],
+      "when_not_to_use": [
+        "In-page panel switching where the content lives on the same route (use Tabs)",
+        "Top-level site navigation with brand + actions (use Navbar)",
+        "Paginated record lists (use Pagination)"
+      ],
+      "variants": {},
+      "props": [
+        {
+          "name": "label",
+          "type": "React.ReactNode",
+          "required": true,
+          "description": "The item's visible label text. (SectionNavItem)"
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "description": "Destination URL. Applied directly when not using `asChild`. (SectionNavItem)"
+        },
+        {
+          "name": "icon",
+          "type": "Icon",
+          "description": "Leading Phosphor icon component (e.g. `UsersIcon`). (SectionNavItem)"
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "description": "Optional trailing count pill value. `0` is rendered; `undefined`/`null` hides the pill. (SectionNavItem)"
+        },
+        {
+          "name": "isActive",
+          "type": "boolean",
+          "default": "false",
+          "description": "Marks the item as the current section — text-primary, 2px primary underline, primary-tinted count pill, and `aria-current=\"page\"`. (SectionNavItem)"
+        },
+        {
+          "name": "asChild",
+          "type": "boolean",
+          "default": "false",
+          "description": "Merge the item's chrome onto the immediate child element instead of rendering an `<a>`. Use with `next/link` for client-side navigation. (SectionNavItem)"
+        }
+      ],
+      "dependencies": [
+        "@radix-ui/react-slot",
+        "@phosphor-icons/react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--border-default",
+        "--border-focus",
+        "--focus-ring-offset",
+        "--focus-ring-width",
+        "--font-size-sm",
+        "--font-size-xs",
+        "--font-weight-medium",
+        "--line-height-tight",
+        "--motion-duration-fast",
+        "--motion-easing-standard",
+        "--primary",
+        "--radius-full",
+        "--radius-sm",
+        "--spacing-1",
+        "--spacing-2",
+        "--spacing-3",
+        "--stroke-width-thin",
+        "--surface-accent-subtle",
+        "--surface-muted",
+        "--text-link",
+        "--text-primary",
+        "--text-secondary"
+      ],
+      "example": "import Link from 'next/link'\nimport { UsersIcon, ShieldIcon, EnvelopeIcon } from '@phosphor-icons/react'\nimport { SectionNav, SectionNavItem } from '@/components/ui/section-nav/section-nav'\n\n<SectionNav aria-label=\"Organization sections\">\n  <SectionNavItem asChild isActive icon={UsersIcon} label=\"Detail\">\n    <Link href=\"/org/detail\" />\n  </SectionNavItem>\n  <SectionNavItem asChild icon={ShieldIcon} label=\"Roles\" count={4}>\n    <Link href=\"/org/roles\" />\n  </SectionNavItem>\n  <SectionNavItem asChild icon={EnvelopeIcon} label=\"Invites\" count={2}>\n    <Link href=\"/org/invites\" />\n  </SectionNavItem>\n</SectionNav>\n"
+    },
     "select": {
       "category": "form",
       "description": "An accessible select component built on Radix UI Select with all sub-components.",
@@ -7055,6 +7325,57 @@
       ],
       "example": "<SurfaceRow token=\"--surface-card\" name=\"Card\" />\n<SurfaceRow token=\"--surface-overlay\" name=\"Overlay\" lightText />\n"
     },
+    "surface-scale-stack": {
+      "category": "specimen",
+      "description": "Multi-tier stacked surface aggregator block. Composes ordered SurfaceRow specimens into a rounded vertical stack with an optional use-note column.",
+      "when_to_use": [
+        "Documenting a full surface scale (e.g. page → screen → panel → panel-2 → panel-3)",
+        "Design system foundation pages showing tier hierarchy",
+        "Theme validation for a complete surface token set"
+      ],
+      "when_not_to_use": [
+        "Displaying a single surface tier (use SurfaceRow)",
+        "Actual page or card surfaces (use the surface tokens directly)"
+      ],
+      "props": [
+        {
+          "name": "surfaces",
+          "type": "SurfaceScaleItem[]",
+          "description": "Ordered array of surface tiers — each with token, name, and optional note"
+        },
+        {
+          "name": "surfaces[].token",
+          "type": "string",
+          "description": "CSS custom property for the surface background (e.g. \"--surface-page\")"
+        },
+        {
+          "name": "surfaces[].name",
+          "type": "string",
+          "description": "Display name for the surface tier"
+        },
+        {
+          "name": "surfaces[].note",
+          "type": "string",
+          "description": "Optional use-note shown in the right-aligned column"
+        },
+        {
+          "name": "surfaces[].lightText",
+          "type": "boolean",
+          "default": "false",
+          "description": "When true, text renders in light colors for dark surfaces"
+        }
+      ],
+      "dependencies": [
+        "surface-row"
+      ],
+      "tokens_used": [
+        "--font-size-xs",
+        "--radius-md",
+        "--spacing-4",
+        "--text-tertiary"
+      ],
+      "example": "<SurfaceScaleStack\n  surfaces={[\n    { token: \"--surface-page\", name: \"Page\", note: \"Root canvas\" },\n    { token: \"--surface-screen\", name: \"Screen\", note: \"Full-bleed section\" },\n    { token: \"--surface-card\", name: \"Card\", note: \"Primary content card\" },\n    { token: \"--surface-raised\", name: \"Raised\", note: \"Elevated card\" },\n    { token: \"--surface-overlay\", name: \"Overlay\", note: \"Modal / sheet\", lightText: true },\n  ]}\n/>\n"
+    },
     "switch": {
       "category": "form",
       "description": "An accessible toggle switch component built on Radix UI Switch.",
@@ -7893,6 +8214,37 @@
       ],
       "example": "<TooltipProvider>\n  <Tooltip>\n    <TooltipTrigger asChild>\n      <Button variant=\"ghost\" size=\"sm\"><TrashIcon /></Button>\n    </TooltipTrigger>\n    <TooltipContent>Delete item</TooltipContent>\n  </Tooltip>\n</TooltipProvider>\n"
     },
+    "type-scale-stack": {
+      "category": "specimen",
+      "description": "Discrete N-tier type-scale aggregator that wraps an ordered list of TypeSpecimen rows in a rounded, screen-tier, borderless vertical stack.",
+      "when_to_use": [
+        "Documenting a discrete N-tier type scale on a foundation or design system page",
+        "Displaying a full project type scale (e.g. 11-tier V7 scale) as a single visual block",
+        "Theme validation for the complete set of font size tokens at once"
+      ],
+      "when_not_to_use": [
+        "Rendering actual page content (use Heading or Text)",
+        "Continuous or modular-scale rendering",
+        "Single type scale rows (use TypeSpecimen directly)"
+      ],
+      "props": [
+        {
+          "name": "steps",
+          "type": "TypeScaleStepProps[]",
+          "description": "Ordered array of type scale steps — each with token, label, sizePx, and sample"
+        }
+      ],
+      "dependencies": [
+        "type-specimen"
+      ],
+      "tokens_used": [
+        "--radius-lg",
+        "--spacing-3",
+        "--spacing-4",
+        "--surface-screen"
+      ],
+      "example": "<TypeScaleStack steps={[\n  { token: \"--font-size-xs\", label: \"xs\", sizePx: 12, sample: \"Caption / helper text\" },\n  { token: \"--font-size-sm\", label: \"sm\", sizePx: 14, sample: \"Small body text\" },\n  { token: \"--font-size-md\", label: \"md\", sizePx: 16, sample: \"Base body text\" },\n  { token: \"--font-size-lg\", label: \"lg\", sizePx: 18, sample: \"Large body text\" },\n  { token: \"--font-size-xl\", label: \"xl\", sizePx: 20, sample: \"Subsection heading\" },\n]} />\n"
+    },
     "type-specimen": {
       "category": "specimen",
       "description": "A single typography row displaying sample text at a given font-size token with weight and size metadata.",
@@ -9062,7 +9414,7 @@
     },
     "right-rail-list": {
       "category": "data-display",
-      "description": "Compact vertical list block tuned for admin dashboard side rails. Each row pairs an optional leading slot (short label, avatar, badge, status dot), a primary label (typically a link), and an optional trailing meta value (count, value, tone-tinted status word). Trailing accepts default / mint / muted / warn tones that bind to the shared semantic text tokens. Supports compact density and ul / ol / div root element variants.",
+      "description": "Compact vertical list block tuned for admin dashboard side rails. Each row pairs an optional leading slot (short label, avatar, badge, status dot), a primary label (typically a link), and an optional trailing meta value (count, value, tone-tinted status word). Trailing accepts default / mint / muted / warn tones that bind to the shared semantic text tokens. Supports compact density, xs row text size for dense rails, and ul / ol / div root element variants.",
       "components_used": [],
       "when_to_use": [
         "Side-rail summary panels in dashboards (this-week digests, top-N rankings, status callouts)",
@@ -9605,6 +9957,10 @@
         "Sign-in and sign-up pages",
         "Forgot password and reset password flows",
         "Invitation acceptance screens"
+      ],
+      "when_not_to_use": [
+        "Collecting setup preferences after the user is already signed in — use onboarding-flow",
+        "A standalone validated form that is not authentication — use form-with-validation"
       ]
     },
     "card-grid": {
@@ -9621,30 +9977,19 @@
         "Displaying a collection of items as visual tiles (projects, products, team members)",
         "When a table layout is too data-dense and card previews are more scannable",
         "Catalog or gallery pages with paginated content"
-      ]
-    },
-    "crud-table": {
-      "description": "Data table with row actions, confirmation dialog, and pagination for managing collections of records.",
-      "components_used": [
-        "table",
-        "button",
-        "dropdown-menu",
-        "dialog",
-        "alert",
-        "pagination",
-        "badge"
       ],
-      "when_to_use": [
-        "Admin pages listing and managing resources (users, orders, products)",
-        "Any collection view with create, read, update, delete operations",
-        "Data tables needing row-level actions and bulk operations"
+      "when_not_to_use": [
+        "Results driven by a search query or type-ahead — use search-results",
+        "Tabular records needing sorting and filtering rather than cards — use data-table-with-filters"
       ]
     },
     "dashboard-layout": {
-      "description": "App shell with collapsible sidebar navigation, top navbar, and content area with cards and tabs.",
+      "description": "Responsive app shell — a persistent sidebar on desktop that collapses to a Sheet drawer on mobile — with a top navbar and a content area of cards and tabs.",
       "components_used": [
         "sidebar",
+        "sheet",
         "navbar",
+        "button",
         "card",
         "tabs",
         "separator",
@@ -9652,12 +9997,17 @@
       ],
       "when_to_use": [
         "Admin dashboards and internal tools",
-        "Multi-section apps with persistent navigation",
-        "Content-heavy layouts needing sidebar + main area structure"
+        "Multi-section apps with persistent navigation that must also work on mobile",
+        "Content-heavy layouts needing sidebar + main area structure",
+        "Any app shell where the desktop sidebar should collapse to a drawer without duplicating nav markup"
+      ],
+      "when_not_to_use": [
+        "A single configuration screen rather than the whole app shell — use settings-page",
+        "Just the tabular data inside the shell — use data-table-with-filters or data-table-row-actions"
       ]
     },
     "data-table-row-actions": {
-      "description": "A data table with per-row action menus, bulk selection with a bulk action bar, confirmation dialogs, and toast feedback for destructive operations.",
+      "description": "A data table for managing collections of records (CRUD) — per-row action menus, bulk selection with a bulk action bar, confirmation dialogs, and toast feedback for destructive operations.",
       "components_used": [
         "data-table",
         "dropdown-menu",
@@ -9667,9 +10017,13 @@
         "bulk-action-bar"
       ],
       "when_to_use": [
+        "Admin pages listing and managing resources (users, orders, products)",
         "Admin lists where rows have contextual actions (edit, archive, delete)",
         "When supporting both single-row and bulk operations on the same table",
-        "Any CRUD interface where destructive actions require confirmation"
+        "Any CRUD interface (create, read, update, delete) where destructive actions require confirmation"
+      ],
+      "when_not_to_use": [
+        "Read-heavy lists whose main need is search, filtering, and sorting rather than row mutations — use data-table-with-filters"
       ]
     },
     "data-table-with-filters": {
@@ -9687,21 +10041,9 @@
         "Data-heavy pages where users need to find specific records",
         "Admin dashboards with sortable, filterable lists",
         "Search result pages with faceted filtering"
-      ]
-    },
-    "empty-state": {
-      "description": "Placeholder shown when a page, list, or search has no content to display.",
-      "components_used": [
-        "card",
-        "button",
-        "heading",
-        "text"
       ],
-      "when_to_use": [
-        "Empty lists or tables (no data yet)",
-        "Search results returning zero matches",
-        "First-time user onboarding (no content created yet)",
-        "Error states where content failed to load"
+      "when_not_to_use": [
+        "Per-row action menus, bulk selection, and confirm-on-delete on the table — use data-table-row-actions"
       ]
     },
     "form-with-validation": {
@@ -9718,6 +10060,10 @@
         "Any form collecting user input (settings, profile, onboarding)",
         "Forms needing inline validation feedback",
         "Multi-field forms with consistent spacing and error display"
+      ],
+      "when_not_to_use": [
+        "A form presented inside a modal or dialog overlay — use modal-form",
+        "A multi-step guided flow rather than a single form — use onboarding-flow"
       ]
     },
     "modal-form": {
@@ -9735,6 +10081,10 @@
         "Creating or editing a record without leaving the current page",
         "Collecting a small set of inputs (fewer than 8 fields)",
         "When the action is contextual to the parent list or table"
+      ],
+      "when_not_to_use": [
+        "A full-page or inline form that is not in an overlay — use form-with-validation",
+        "A multi-step guided flow — use onboarding-flow"
       ]
     },
     "notification-center": {
@@ -9750,10 +10100,14 @@
         "Apps with persistent in-app notifications or activity alerts",
         "When users need to review, dismiss, or act on multiple notifications at once",
         "Combining real-time toast feedback with a browsable notification history"
+      ],
+      "when_not_to_use": [
+        "A single transient confirmation after one action — use a bare Toast, not the full center",
+        "A command palette for navigation or search — use search-results"
       ]
     },
     "onboarding-flow": {
-      "description": "A step-by-step welcome flow that collects user preferences and setup choices using progress tracking, cards, and inline forms with checkbox selections.",
+      "description": "A multi-step guided flow — first-run onboarding, setup wizards, or checkout — that breaks a long or gated process into validated steps with progress tracking, cards, and inline forms.",
       "components_used": [
         "stepper",
         "progress",
@@ -9767,23 +10121,14 @@
       "when_to_use": [
         "First-run experiences after account creation",
         "Feature setup flows where configuration choices shape the initial workspace",
-        "Product tours that collect preferences before showing the main dashboard"
-      ]
-    },
-    "responsive-sidebar-layout": {
-      "description": "A full-app shell that renders a persistent sidebar on desktop and a Sheet-based drawer on mobile, sharing the same navigation content.",
-      "components_used": [
-        "sidebar",
-        "sheet",
-        "navbar",
-        "button",
-        "separator",
-        "scroll-area"
+        "Product tours that collect preferences before showing the main dashboard",
+        "Checkout or other multi-step sequences that stage a long process",
+        "When a single long form would overwhelm the user — break into logical steps",
+        "Flows where earlier steps gate or inform later steps"
       ],
-      "when_to_use": [
-        "Any multi-section app needing sidebar navigation that must work on mobile",
-        "When the desktop sidebar should collapse to a drawer without duplicating nav markup",
-        "Admin tools, dashboards, or SaaS apps requiring a responsive shell"
+      "when_not_to_use": [
+        "Login or signup itself — use auth-flow",
+        "A single validated form rather than a multi-step flow — use form-with-validation"
       ]
     },
     "search-results": {
@@ -9800,6 +10145,9 @@
         "Search pages where users need to filter and browse a large dataset",
         "When combining free-text search with faceted category filters",
         "Directory, catalog, or discovery interfaces with card-based result display"
+      ],
+      "when_not_to_use": [
+        "A static grid of cards not driven by a query — use card-grid"
       ]
     },
     "settings-page": {
@@ -9821,23 +10169,10 @@
         "User profile and account settings",
         "Application preferences and configuration",
         "Team or organization settings"
-      ]
-    },
-    "wizard-flow": {
-      "description": "A multi-step guided flow with per-step validation, progress tracking, and a linear navigation structure for complex data collection.",
-      "components_used": [
-        "stepper",
-        "field",
-        "input",
-        "button",
-        "alert",
-        "progress",
-        "separator"
       ],
-      "when_to_use": [
-        "Onboarding flows, setup wizards, or checkout sequences",
-        "When a single long form would overwhelm the user — break into logical steps",
-        "Flows where earlier steps gate or inform later steps"
+      "when_not_to_use": [
+        "The whole app shell and navigation chrome — use dashboard-layout",
+        "A single focused form rather than grouped settings sections — use form-with-validation"
       ]
     }
   },
@@ -9854,6 +10189,8 @@
       "radius-scale",
       "spacing-scale",
       "surface-row",
+      "surface-scale-stack",
+      "type-scale-stack",
       "type-specimen"
     ],
     "data-display": [
@@ -9879,7 +10216,9 @@
       "data-table",
       "empty-state",
       "filter-bar",
+      "infographic-bar",
       "kbd",
+      "matrix-table",
       "score-indicator",
       "stat-card",
       "stat-hero",
@@ -9913,6 +10252,7 @@
       "pagination",
       "quick-actions",
       "section-header",
+      "section-nav",
       "stepper",
       "tabs"
     ],
@@ -9988,6 +10328,163 @@
       "slide-theme-context"
     ]
   },
+  "brand_strategy": {
+    "positioning": {
+      "onliness": "The only design system that compiles a complete brand — visual and verbal — from one portable file, for humans and agents alike.",
+      "category": "design system",
+      "differentiation": "brand strategy, visual and verbal, as derivable machine-readable data"
+    },
+    "essence": [
+      "coherent",
+      "open",
+      "yours"
+    ],
+    "personality": [
+      {
+        "trait": "precise",
+        "not": "fussy"
+      },
+      {
+        "trait": "candid",
+        "not": "cold"
+      },
+      {
+        "trait": "generous",
+        "not": "indulgent"
+      },
+      {
+        "trait": "warm",
+        "not": "saccharine"
+      }
+    ],
+    "archetype": {
+      "primary": "sage",
+      "secondary": "creator",
+      "tertiary": "everyman"
+    },
+    "pillars": [
+      {
+        "id": "coherence",
+        "statement": "Every layer derives from the one above it.",
+        "governs": {
+          "tokens": [
+            "--primary",
+            "--surface-card",
+            "--text-primary"
+          ],
+          "components": [
+            "*"
+          ]
+        }
+      },
+      {
+        "id": "openness",
+        "statement": "The whole system is open — readable by humans and agents, and free to take.",
+        "governs": {
+          "surfaces": [
+            "manifest",
+            "cli",
+            "component-metadata"
+          ]
+        }
+      },
+      {
+        "id": "ownership",
+        "statement": "Copy-and-own. You hold the source; there's no lock-in, ever.",
+        "governs": {
+          "components": [
+            "*"
+          ]
+        }
+      }
+    ],
+    "voice": {
+      "traits": [
+        {
+          "name": "plainspoken",
+          "do": "Say it in one clause. Lead with the answer.",
+          "dont": "Bury the point under qualifiers and throat-clearing.",
+          "example": "Copy-and-own is just that — the source is yours. Edit anything; there's no wrapper to fight."
+        },
+        {
+          "name": "candid",
+          "do": "Name the tradeoff and the cost before the reader hits it.",
+          "dont": "Oversell, hide the sharp edges, or hedge to sound safe.",
+          "example": "Heads up — this theme fails WCAG AA on small text. Bump the contrast a notch, or keep the warning if that's intentional."
+        },
+        {
+          "name": "generous",
+          "do": "Give the why. Show the worked example. Assume the reader will go further than you did.",
+          "dont": "Gatekeep, wave at best practices, or make them read the source to understand.",
+          "example": "Fallbacks use Gray, not Slate — so an un-themed component lands on a neutral that fits your palette instead of clashing. Small thing, but it's what keeps a theme feeling whole."
+        },
+        {
+          "name": "warm",
+          "do": "Greet the reader like a peer you're glad to help. A little delight is welcome.",
+          "dont": "Go cold and transactional — or paper over it with forced cheer.",
+          "example": "Welcome — let's get your first theme on the screen. It takes about a minute."
+        }
+      ]
+    },
+    "tone": {
+      "error": {
+        "feeling": "warm, accountable, already holding the fix",
+        "example": "That didn't save — looks like the theme name's taken. Pick another and we'll keep everything else just as you left it."
+      },
+      "success": {
+        "feeling": "a real, small celebration — a little confetti is fine",
+        "example": "Saved! Your theme's live across every component — go take a look."
+      },
+      "empty": {
+        "feeling": "inviting, a friendly nudge to start",
+        "example": "Nothing here yet — let's change that. Start from a blank file, or clone one and make it yours."
+      },
+      "loading": {
+        "feeling": "unhurried and friendly, honest about the wait",
+        "example": "Compiling your tokens — just a moment…"
+      },
+      "validation-warning": {
+        "feeling": "a friend flagging a smell, never a scold",
+        "example": "Quick one — your primary and accent are nearly twins. Themes can read a little flat this close, so nudge one if it's not on purpose."
+      }
+    },
+    "lexicon": [
+      {
+        "use": "theme",
+        "avoid": "skin"
+      },
+      {
+        "use": "copy-and-own",
+        "avoid": "fork"
+      },
+      {
+        "use": "compose",
+        "avoid": "drag-and-drop"
+      },
+      {
+        "use": "token",
+        "avoid": "variable"
+      },
+      {
+        "use": "adapter",
+        "avoid": "plugin"
+      },
+      {
+        "use": "transform",
+        "avoid": "restyle"
+      },
+      {
+        "use": "portable",
+        "avoid": "exportable"
+      }
+    ],
+    "core": [
+      "positioning",
+      "essence",
+      "pillars"
+    ],
+    "visibility": "public"
+  },
   "tokens": {
     "primitives": [
       {
@@ -11357,6 +11854,20 @@
         "defaultLight": "var(--spacing-24)",
         "defaultDark": "var(--spacing-24)"
       },
+      {
+        "name": "--layout-section-padding",
+        "tier": "semantic",
+        "description": "Semantic spacing: layout-section-padding",
+        "defaultLight": "var(--spacing-24)",
+        "defaultDark": "var(--spacing-24)"
+      },
+      {
+        "name": "--layout-section-padding-mobile",
+        "tier": "semantic",
+        "description": "Semantic spacing: layout-section-padding-mobile",
+        "defaultLight": "var(--spacing-16)",
+        "defaultDark": "var(--spacing-16)"
+      },
       {
         "name": "--motion-duration-fast",
         "tier": "semantic",
@@ -12180,7 +12691,7 @@
       }
     ],
     "summary": {
-      "total": 312
+      "total": 314
     }
   }
 }