@sableui/react 0.0.0-stage → 0.1.1

package/dist/ios/styles.css

@@ -0,0 +1,77 @@
+@import 'konsta/react/theme.css';
+@import './chrome.css';
+@source './**/*.{ts,tsx,js,mjs}';
+/* Import after Tailwind in the native document only. */
+/*
+ * Chrome follows the Sable preset. When Sable's styles are loaded in this
+ * document (the recommended setup), every value below resolves from the active
+ * preset and mode, so `data-sable-theme` on <html> themes the native chrome and
+ * Sable content together. Without them, the iOS system values apply.
+ * NativeApp's `tokens` prop sets the same semantic names inline to override.
+ */
+.ios-prototype {
+  --ios-canvas: var(--background, #f2f2f7); --ios-ink: var(--foreground, #1c1c1e); --ios-secondary: var(--muted-foreground, #636366);
+  --ios-panel: var(--card, #fff); --ios-primary-ink: var(--primary-foreground, #fff);
+  --ios-display: var(--font-display, var(--font-sans, inherit)); --ios-title-weight: var(--type-title-weight, 600);
+  --color-primary: var(--primary, var(--k-color-primary));
+  --color-ios-primary-shade: color-mix(in srgb, var(--color-primary) 85%, var(--ios-ink));
+  --color-ios-light-surface: var(--ios-canvas); --color-ios-dark-surface: var(--ios-canvas);
+  --color-ios-light-surface-1: var(--ios-panel); --color-ios-dark-surface-1: var(--ios-panel);
+  --color-ios-light-surface-1-shade: var(--muted, #f1f1f5); --color-ios-dark-surface-1-tint: var(--muted, #444447);
+  /* Geometry of the standard 402×874 phone. Retune together for other sizes. */
+  /* The page margin native titles, search and inset lists sit on: align content to it (px-(--ios-inset)). */
+  --ios-inset: 16px;
+  --ios-motion: 300ms; --ios-safe-top: 62px; --ios-header-height: 154px; --ios-tabbar-bottom: 28px; --ios-content-bottom: 110px;
+  font-family: var(--font-sans, system-ui, sans-serif); color: var(--ios-ink); background: var(--ios-canvas); height: 100dvh; overflow: hidden;
+}
+.ios-prototype.dark {
+  --ios-canvas: var(--background, #000); --ios-ink: var(--foreground, #f2f2f7); --ios-secondary: var(--muted-foreground, #aeaeb2);
+  --ios-panel: var(--card, #1c1c1e); --ios-primary-ink: var(--primary-foreground, #fff);
+}
+/*
+ * Sable and Konsta share Tailwind's spacing and radius names. Sable's preset
+ * and density rescale them; native chrome keeps iOS geometry, so the chrome
+ * pins Tailwind's defaults. Sable content placed beside it keeps the preset's.
+ */
+.ios-prototype :is(.k-navbar, .k-tabbar, .k-toolbar, .ios-sheet-grabber, .ios-sheet-heading) {
+  --spacing: 0.25rem; --theme-radius-xs: 0.125rem; --theme-radius-sm: 0.25rem; --theme-radius-md: 0.375rem; --theme-radius-lg: 0.5rem; --theme-radius-xl: 0.75rem;
+}
+/* The system status bar: time and icons centred on the island's midline, each in
+   the space beside it, in the system font (it never takes the app's). */
+.ios-status-bar { position: absolute; inset: 0 0 auto; height: var(--ios-safe-top); display: grid; grid-template-columns: 1fr 84px 1fr; grid-template-rows: 35px; align-content: start; align-items: center; padding: 11px 16px 0; z-index: 40; pointer-events: none; font: 600 17px/1 -apple-system, "SF Pro Text", system-ui, sans-serif; letter-spacing: -0.02em; }
+.ios-status-bar > span:first-child { justify-self: center; font-variant-numeric: tabular-nums; }
+/* The smaller island of current Pro phones. */
+.ios-island { width: 84px; height: 35px; border-radius: 18px; background: #000; }
+.ios-status-icons { justify-self: center; display: flex; align-items: center; gap: 5px; }
+.ios-home-indicator { position: absolute; z-index: 100; bottom: 8px; left: 50%; transform: translateX(-50%); width: 134px; height: 5px; border-radius: 4px; background: var(--ios-ink); pointer-events: none; }
+.ios-navigation-stack { position: absolute; inset: 0; }
+.ios-route { position: relative; height: 100%; animation: ios-route-enter var(--ios-motion) cubic-bezier(.2,.8,.2,1); }
+.ios-navigation-stack[data-direction='pop'] .ios-route { animation-name: ios-route-back; }
+.ios-route[hidden], .ios-navigation-stack[hidden] { display: none; }
+.ios-route > .k-page { height: 100%; padding-bottom: var(--ios-content-bottom); scrollbar-width: none; }
+.ios-route > .k-page::-webkit-scrollbar { display: none; }
+/* A screen's content starts a step below its title, as iOS spaces a large title from the first section. */
+.ios-prototype .k-page > .k-navbar + * { margin-block-start: 12px; }
+/* Touch targets on native chrome; Sable content keeps its preset's control sizes. */
+.ios-prototype :is(.k-navbar, .k-tabbar, .ios-sheet-heading) :is(button, a) { min-height: 44px; }
+/* Headings take focus on navigation for screen readers; that is not a ring to show. */
+.ios-prototype [tabindex='-1']:focus { outline: none; }
+.ios-prototype :focus-visible { outline: 3px solid var(--color-primary); outline-offset: 2px; }
+.ios-prototype .native-tabbar { position: absolute; }
+.ios-prototype .native-tabbar > .k-glass { width: 100%; }
+.ios-sheet-dialog { position: fixed; inset: 0; padding: 0; border: 0; width: 100%; max-width: none; height: 100%; max-height: none; background: transparent; color: var(--ios-ink); overflow: hidden; }
+.ios-sheet-dialog::backdrop { background: #0005; }
+.ios-sheet { border-radius: 32px 32px 0 0; background: var(--ios-canvas); transition-duration: var(--ios-motion); padding-bottom: 34px; }
+.ios-sheet-grabber { display: flex; margin-inline: auto; width: 80px; touch-action: none; }
+.ios-grabber-mark { width: 36px; height: 5px; border-radius: 4px; background: var(--ios-secondary); }
+.ios-sheet-heading { display: flex; align-items: center; justify-content: space-between; padding-inline: 20px; }
+.ios-sheet-heading h2 { font-size: 22px; font-weight: 700; }
+.ios-sheet-heading > button { width: auto; flex-shrink: 0; }
+.ios-sheet::after { content: ''; position: absolute; bottom: 8px; left: 50%; transform: translateX(-50%); width: 134px; height: 5px; border-radius: 4px; background: var(--ios-ink); }
+.ios-sheet-content { height: calc(100% - 88px); overflow-y: auto; scrollbar-width: none; padding: 16px 20px; }
+.ios-visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+@keyframes ios-route-enter { from { opacity: .7; transform: translateX(28px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes ios-route-back { from { opacity: .7; transform: translateX(-16px); } to { opacity: 1; transform: translateX(0); } }
+.ios-prototype[data-reduced-motion] *, .ios-prototype[data-reduced-motion] *::before, .ios-prototype[data-reduced-motion] *::after { animation-duration: 0s !important; transition-duration: 0s !important; }
+@media (prefers-reduced-motion: reduce) { .ios-prototype *, .ios-prototype *::before, .ios-prototype *::after { animation-duration: 0s !important; transition-duration: 0s !important; } }
+@media (prefers-reduced-transparency: reduce) { .ios-prototype { --ios-glass-tint: 1 !important; } }

package/dist/layout/index.d.ts

@@ -0,0 +1,280 @@
+import * as react from 'react';
+import { ComponentPropsWithRef, ElementType, HTMLAttributes, ReactNode } from 'react';
+
+/** The device safe-area edges (notch, home indicator, rounded corners). */
+type Edge = "top" | "bottom" | "left" | "right";
+
+/**
+ * Purpose-named content widths (resolve to theme tokens). Pick by ROLE, not size.
+ * Cap text measure (`prose`) separately from layout width.
+ * - `prose`   65ch  — long-form reading text (post body, descriptions, articles)
+ * - `form`    480px — narrow single-column forms, auth, dialogs
+ * - `feed`    640px — single-column timeline / reading feed
+ * - `content` 896px — general content + settings/admin panes (some 2-up fields)
+ * - `wide`    1280px — dashboards, tables, multi-column grids
+ * - `full`    1536px — full-bleed safety ceiling
+ * - `ultrawide` 1800px — legacy; prefer `full`
+ */
+type RegionMax = "prose" | "form" | "feed" | "content" | "wide" | "full" | "ultrawide";
+interface RegionProps extends ComponentPropsWithRef<"div"> {
+    /** Semantic element to render (e.g. "main", "section", "nav"). Default "div". */
+    as?: ElementType;
+    /** Apply the fluid horizontal page inset (`--page-inset`). Default true. */
+    inset?: boolean;
+    /**
+     * Opt-in centered max-width cap: a purpose-named region ("prose" | "form" |
+     * "feed" | "content" | "wide" | "full") or any raw CSS length (e.g. "56rem").
+     * Omit for fully fluid, edge-to-edge (the default).
+     */
+    max?: RegionMax | (string & {});
+    /** Full-bleed: edge to edge with no inset. Overrides `inset`. */
+    bleed?: boolean;
+    /**
+     * Apply `env(safe-area-inset-*)` padding — for fixed or native-shell surfaces.
+     * `true` pads top + bottom (the legacy behavior); pass an edge array
+     * (`["top"]`, `["bottom"]`, …) to target specific edges, mirroring `SafeArea`.
+     */
+    safeArea?: boolean | Edge[];
+}
+/**
+ * The page region. Fluid-first: full width with a fluid page inset, NOT a
+ * centered fixed-width container. Reach for `max` only when a specific region
+ * (a reading column, a settings pane) genuinely needs a cap.
+ */
+declare function Region({ as, inset, max, bleed, safeArea, className, style, children, ref, ...rest }: RegionProps): react.JSX.Element;
+
+type Align$1 = "start" | "center" | "end" | "stretch";
+type Justify$1 = "start" | "center" | "end" | "between" | "around";
+interface StackProps extends ComponentPropsWithRef<"div"> {
+    /** Vertical gap. Number = rhythm units (×8px; fractions ok); string = raw CSS. Default 2 (16px). */
+    gap?: number | string;
+    align?: Align$1;
+    justify?: Justify$1;
+}
+/** Vertical flow on the 8px rhythm. The default container for stacked content. */
+declare function Stack({ gap, align, justify, className, style, children, ref, ...rest }: StackProps): react.JSX.Element;
+
+interface PageProps extends RegionProps {
+    /**
+     * Vertical gap between the stacked page sections. Number = rhythm units
+     * (×8px); string = raw CSS. @default 4 (32px)
+     */
+    gap?: StackProps["gap"];
+    /** Cross-axis alignment of the stacked sections. @default "stretch" */
+    align?: StackProps["align"];
+}
+/**
+ * Page — a route shell. A `Region` (fluid page inset, opt-in `max` cap, optional
+ * `safeArea`) whose children flow as vertically-rhythmic sections (a `Stack`).
+ * Replaces the repeated `<Region><Stack>…</Stack></Region>` wrapper around
+ * create / settings / admin routes.
+ *
+ * Distinct from `AppShell` (the app frame the page lives inside) and `PageHeader`
+ * (the heading block at the top of a page) — `Page` is the content region itself.
+ *
+ *   <Page max="feed" gap={4}>…</Page>
+ *   <Page as="main" max="wide">…</Page>
+ *   <Page bleed>…</Page>
+ */
+declare function Page({ gap, align, children, ...regionProps }: PageProps): react.JSX.Element;
+declare namespace Page {
+    var displayName: string;
+}
+
+/** A breakpoint name, or `base` for the default (mobile-first) value. */
+type Breakpoint = "base" | "sm" | "md" | "lg" | "xl" | "2xl";
+/** A static value, or a per-breakpoint map (`{ base, sm, md, lg, xl, "2xl" }`). */
+type Responsive<T> = T | Partial<Record<Breakpoint, T>>;
+
+interface GridProps extends ComponentPropsWithRef<"div"> {
+    /**
+     * Fixed column count — a number, or a breakpoint map (`{ base: 2, md: 4, lg: 6 }`)
+     * for fewer columns on small screens. Ignored when `minItemWidth` is set.
+     * Default 12.
+     */
+    cols?: Responsive<number>;
+    /**
+     * Make cells "breathe": `repeat(auto-fit, minmax(minItemWidth, 1fr))`.
+     * The grid grows/wraps responsively without breakpoints. e.g. "16rem".
+     */
+    minItemWidth?: string;
+    /** Gap between cells. Number = rhythm units (×8px); string = raw CSS. Default `--grid-gutter`. */
+    gap?: number | string;
+}
+/**
+ * CSS Grid layout primitive. Three modes: a fixed `cols` count, a responsive
+ * `cols` breakpoint map (fewer columns on small screens), or `minItemWidth`
+ * auto-fit cells that breathe with no breakpoints at all.
+ */
+declare function Grid({ cols, minItemWidth, gap, className, style, children, ref, ...rest }: GridProps): react.JSX.Element;
+
+interface ColumnsProps extends ComponentPropsWithRef<"div"> {
+    /**
+     * Number of columns in the track — a number, or a breakpoint map for fewer
+     * columns on small screens (`{ base: 2, md: 6, lg: 12 }`). Default
+     * `--grid-columns` (12).
+     */
+    count?: Responsive<number>;
+    /**
+     * Gap between columns and rows. Number = rhythm units (×8px); string = raw
+     * CSS. Default `--grid-gutter`. The column gap is capped so the `count - 1`
+     * gaps together never exceed 75% of the track's width (see `columnGap`).
+     */
+    gap?: number | string;
+}
+interface ColProps extends ComponentPropsWithRef<"div"> {
+    /** Columns to span — a number, or a breakpoint map (`{ base: 12, md: 8, lg: 7 }`). Default 1. */
+    span?: Responsive<number>;
+    /** 1-based column to start at — a number or a breakpoint map. */
+    start?: Responsive<number>;
+}
+/**
+ * An explicit N-column track (default 12). `count` accepts a breakpoint map so
+ * the track itself can thin out on small screens (e.g. 2 → 6 → 12). Pair with
+ * `Col` for spans. The track template resolves through the `[data-sable-grid-cols]`
+ * rules in `styles.css`, mobile-first.
+ */
+declare function Columns({ count, gap, className, style, children, ref, ...rest }: ColumnsProps): react.JSX.Element;
+/**
+ * A cell spanning `span` columns within a `Columns` track. `span` and `start`
+ * accept either a number or a breakpoint map for responsive layouts:
+ *
+ *   <Col span={{ base: 12, md: 8, lg: 7 }} />
+ *
+ * The per-breakpoint values are emitted as inline CSS custom properties and
+ * resolved mobile-first by the `[data-sable-col]` rules in `styles.css`, so any
+ * span value works without the consuming app's Tailwind scanning a class.
+ */
+declare function Col({ span, start, className, style, children, ref, ...rest }: ColProps): react.JSX.Element;
+
+type Align = "start" | "center" | "end" | "stretch" | "baseline";
+type Justify = "start" | "center" | "end" | "between" | "around";
+interface RowProps extends ComponentPropsWithRef<"div"> {
+    /** Horizontal gap. Number = rhythm units (×8px; fractions ok); string = raw CSS. Default 2 (16px). */
+    gap?: number | string;
+    align?: Align;
+    justify?: Justify;
+    wrap?: boolean;
+}
+/** Horizontal flow. Inline rows of controls, toolbars, action clusters. */
+declare function Row({ gap, align, justify, wrap, className, style, children, ref, ...rest }: RowProps): react.JSX.Element;
+
+interface SpacerProps {
+    /** Fixed size in rhythm units (×8px; fractions ok). Ignored when `grow`. */
+    size?: number;
+    /** Axis the fixed size applies to. Default "vertical". */
+    axis?: "vertical" | "horizontal";
+    /** Flex-grow to push siblings apart (fills available space). */
+    grow?: boolean;
+    className?: string;
+}
+/** Explicit space on the rhythm, or a flexible `grow` pusher between siblings. */
+declare function Spacer({ size, axis, grow, className }: SpacerProps): react.JSX.Element;
+
+interface CenterProps extends ComponentPropsWithRef<"div"> {
+    /** Cap width: a named region ("prose" | "feed" | "wide" | "ultrawide") or any raw CSS length. */
+    max?: string;
+}
+/** Horizontally center a block, optionally capping its width (commonly "prose"). */
+declare function Center({ max, className, style, children, ref, ...rest }: CenterProps): react.JSX.Element;
+
+interface AspectBoxProps extends HTMLAttributes<HTMLDivElement> {
+    /** Width / height ratio. Default 16/9. Reserves space so late media never shifts layout. */
+    ratio?: number;
+}
+/** Reserves grid space via aspect-ratio — async/media content loads without layout shift. */
+declare function AspectBox({ ratio, className, style, children, ...rest }: AspectBoxProps): react.JSX.Element;
+
+interface BleedProps extends ComponentPropsWithRef<"div"> {
+}
+/**
+ * Bleed — lets content escape a width-capped or inset ancestor and span the full
+ * width of its layout container: a profile cover, a hero band, or full-bleed
+ * media inside a `max`-capped `Region` / `Page`.
+ *
+ * It uses container-query width units (`width: 100cqw` + `margin-inline: calc(50%
+ * - 50cqw)`), so it spans the nearest query container rather than the raw
+ * viewport. `AppShell`'s content region is a container (`container-type:
+ * inline-size`), so a Bleed inside it fills the content area and stops at a fixed
+ * left `Sidebar` instead of bleeding under it. With no container ancestor (a
+ * full-bleed app, or `Bleed` used standalone) `cqw` resolves against the viewport,
+ * so behavior is unchanged there. Nest a `Region` / `Center` inside to re-inset.
+ *
+ *   <Region max="feed">
+ *     <Bleed><ProfileCover /></Bleed>
+ *     …
+ *   </Region>
+ */
+declare function Bleed({ className, style, children, ref, ...rest }: BleedProps): react.JSX.Element;
+declare namespace Bleed {
+    var displayName: string;
+}
+
+type Collapse = "sm" | "md" | "lg" | "xl";
+interface SplitPaneProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+    /** The leading / larger pane (e.g. the media column). */
+    primary: ReactNode;
+    /** The trailing / supporting pane (e.g. the detail column). */
+    secondary: ReactNode;
+    /**
+     * Breakpoint at/above which the two panes sit side by side; below it they
+     * stack (primary on top). @default "lg"
+     */
+    collapseBelow?: Collapse;
+    /**
+     * Primary:secondary width ratio when side by side, as `"a/b"` fr units.
+     * @default "1/1"  (e.g. "2/1", "3/2")
+     */
+    ratio?: string;
+    /** Gap between panes. Number = rhythm units (×8px); string = raw CSS. Default `--grid-gutter`. */
+    gap?: number | string;
+}
+/**
+ * SplitPane — a responsive two-pane layout. At/above `collapseBelow` the panes
+ * sit side by side at `ratio`; below it they stack (primary first). Owns the
+ * structural pattern behind list/detail and media/detail pages, so a route stops
+ * hand-building a desktop two-column layout plus a separate mobile stack.
+ *
+ * The breakpoint switch + ratio resolve through the `[data-sable-split]` rules in
+ * `styles.css` (inline CSS custom properties), so any `ratio` works.
+ *
+ * `collapseBelow` is **viewport-relative**, not container-relative: it asks how
+ * wide the window is, not how wide this SplitPane is. Dropped inside a narrow
+ * column — a sidebar, a modal, one cell of a Grid — it will happily stay
+ * side-by-side in 300px because the window is 1440px. The same caveat applies to
+ * the breakpoint maps on `Grid cols`, `Columns`, and `Col`. When a block has to
+ * adapt to the space it actually occupies, reach for `Grid minItemWidth`, which
+ * is intrinsically container-driven and needs no query at all.
+ *
+ *   <SplitPane collapseBelow="lg" ratio="3/2" primary={<Media />} secondary={<Details />} />
+ */
+declare function SplitPane({ primary, secondary, collapseBelow, ratio, gap, className, style, ref, ...rest }: SplitPaneProps): react.JSX.Element;
+declare namespace SplitPane {
+    var displayName: string;
+}
+
+interface SafeAreaProps extends ComponentPropsWithRef<"div"> {
+    /** Which edges get `env(safe-area-inset-*)` padding. Default all four. */
+    edges?: Edge[];
+}
+/** Pads for device safe-areas (notch, home indicator) on fixed/native surfaces. */
+declare function SafeArea({ edges, className, style, children, ref, ...rest }: SafeAreaProps): react.JSX.Element;
+
+interface GridOverlayProps {
+    /** Number of column bands. Default `--grid-columns` (12). */
+    columns?: number;
+    /** Gap between bands. Default `--grid-gutter`. */
+    gap?: string;
+    /** Align bands to the fluid page inset. Default true. */
+    inset?: boolean;
+    /** Toggle visibility. Default true. */
+    show?: boolean;
+    className?: string;
+}
+/**
+ * Dev/docs structure visualizer — overlays the column grid so the layout's
+ * skeleton is legible. Place inside a `position: relative` container.
+ */
+declare function GridOverlay({ columns, gap, inset, show, className, }: GridOverlayProps): react.JSX.Element | null;
+
+export { AspectBox, type AspectBoxProps, Bleed, type BleedProps, type Breakpoint, Center, type CenterProps, Col, type ColProps, Columns, type ColumnsProps, Grid, GridOverlay, type GridOverlayProps, type GridProps, Page, type PageProps, Region, type RegionMax, type RegionProps, type Responsive, Row, type RowProps, SafeArea, type SafeAreaProps, Spacer, type SpacerProps, SplitPane, type SplitPaneProps, Stack, type StackProps };

package/dist/layout/index.js

@@ -0,0 +1,2 @@
+export { AspectBox, Bleed, Center, Col, Columns, Grid, GridOverlay, Page, Region, Row, SafeArea, Spacer, SplitPane, Stack } from '../chunk-3IWZYBGH.js';
+import '../chunk-SRQWQUTW.js';

package/dist/meta-6dUzgC6M.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Machine-readable component metadata — the AI-readable surface of the system.
+ * Each component ships a `<name>.meta.ts` exporting one `ComponentMeta`. These
+ * aggregate into `registry.json` and are what other agents read to understand
+ * the component's contract. Keep meta in sync with the component.
+ */
+interface PropMeta {
+    name: string;
+    type: string;
+    default?: string;
+    description: string;
+    /**
+     * Set when the prop is deprecated: what to use instead. The registry
+     * contract refuses "deprecated" in prose without it, so an agent reads a
+     * field rather than interpreting a sentence.
+     */
+    deprecated?: string;
+}
+interface ExampleMeta {
+    label: string;
+    /** A self-contained JSX snippet demonstrating the example. */
+    code: string;
+}
+interface BestPracticeMeta {
+    /** Whether this is positive guidance or an anti-pattern to avoid. */
+    guidance: "do" | "dont";
+    /** Short design guidance focused on when and how to use the component. */
+    description: string;
+}
+interface AnatomyMeta {
+    /** Visible or structural part name, e.g. "Label", "Trigger", "Content". */
+    name: string;
+    /** Whether the part is required for the component to make sense. */
+    required: boolean;
+    /** The role this part plays in the composed UI. */
+    description: string;
+}
+interface UsageMeta {
+    /** What the component is for and when to reach for it. */
+    description: string;
+    /** Do/don't guidance for designers, developers, and AI agents. */
+    bestPractices?: BestPracticeMeta[];
+    /** Structural parts that make up the component. */
+    anatomy?: AnatomyMeta[];
+}
+/**
+ * The four roles motion plays in a component. Every component fills the slots
+ * that apply to it and explicitly declines the ones that don't.
+ *
+ * The vocabulary exists because the motion rules were entirely PROHIBITIVE:
+ * `raw-duration`, `builtin-animate`, the bare-colour-transition rule and
+ * `unknown-motion` all fire on motion that is present and wrong, and not one of
+ * them can fire on motion that is absent. A component with no motion passed every gate
+ * in the system. That is precisely the shape an agent optimises into — it writes
+ * what is checked — so the catalog filled up with correct, static components and
+ * motion became a thing a human had to ask for by name, every time.
+ *
+ *   arrival     how it enters the page or becomes visible
+ *   response    what it does under the pointer — hover, press, focus
+ *   transition  how it moves between its own states (open/closed, on/off)
+ *   activity    what it does while working, indeterminately
+ *
+ * The slots are deliberately about the USER'S experience of the component, not
+ * about CSS mechanism, so "which slots apply here" is answerable from the
+ * component's purpose before a line of it is written.
+ */
+type MotionSlot = "arrival" | "response" | "transition" | "activity";
+interface MotionMeta {
+    /** Which of the four roles this entry covers. */
+    slot: MotionSlot;
+    /**
+     * The motion recipe that fills it — `motion-interactive`, `motion-pop`,
+     * `motion-disclosure`, … — validated against the recipes the package
+     * actually ships, so a renamed recipe cannot rot here silently.
+     *
+     * Two literals are sanctioned besides a recipe name:
+     *
+     *   "none"    the slot does NOT apply here, and this is the only way to say so
+     *   "custom"  the slot is filled outside the recipe layer — a rAF loop, a
+     *             canvas, a Base UI transition — because no CSS utility can
+     *             express it. ThinkingOrb draws a point cloud per frame; there is
+     *             no recipe that could ever cover it, and forcing it to claim
+     *             `"none"` would file a component that never stops moving under
+     *             "does not animate".
+     *
+     * Both still require a `why`, as does a filled slot. An unfilled slot is
+     * either a considered decision or an oversight, and the difference has to be
+     * legible to the next reader; a `"custom"` with no explanation is just an
+     * opt-out with extra steps. This mirrors `design-lint-disable … -- <reason>`:
+     * the exception is allowed, the silent exception is not.
+     */
+    recipe: string;
+    /**
+     * The anatomy part it applies to ("Trigger", "Panel", "root"). Motion that
+     * cannot name what moves is usually motion nobody checked.
+     */
+    part: string;
+    /**
+     * Why this slot resolves this way here. Not a restatement of the recipe —
+     * `"motion-pop on the panel"` says nothing a reader could not already see.
+     * State what the motion is FOR: what the user would misread without it.
+     */
+    why: string;
+}
+interface RelatedMeta {
+    /** Components commonly composed with, compared to, or preferred over this one. */
+    components?: string[];
+    /** Canonical page patterns that show this component in context. */
+    patterns?: string[];
+}
+/**
+ * A composed child component exported alongside the root (e.g. ProgressTrack,
+ * SelectItem) — a separate element in JSX, NOT a prop of the root. Keeping
+ * these out of `props` is what tells a consumer to write
+ * `<Progress><ProgressTrack/></Progress>` rather than
+ * `<Progress ProgressTrack={{…}}/>`.
+ */
+interface SubcomponentMeta {
+    /** Exported component name, e.g. "ProgressTrack". */
+    name: string;
+    /** The props it accepts (same shorthand style as PropMeta.type). */
+    type: string;
+    description: string;
+}
+/**
+ * Machine-readable metadata for a page pattern — a canonical full-page
+ * composition in `src/patterns/`. The pattern's *source* is the contract: the
+ * registry generator extracts the code after the `// ---pattern-code---` marker
+ * verbatim, so what ships in `registry.json → patterns` always compiles.
+ */
+interface PatternMeta {
+    /** Pattern name, e.g. "SettingsPage". */
+    name: string;
+    /** One-line summary. */
+    summary: string;
+    /** When to reach for this shell — and when not to. */
+    intent: string;
+    /** Canonical decisions the pattern encodes (region cap, rhythm, hierarchy). */
+    notes?: string[];
+    /** Accessibility notes. */
+    a11y?: string[];
+}
+interface ComponentMeta {
+    /** Public component name, e.g. "Button". Must be an actual export. */
+    name: string;
+    /**
+     * Set when `name` labels a SYSTEM rather than a single importable value —
+     * `Toast` is `ToastProvider` + `toast()` + parts, and nothing is exported as
+     * plain `Toast`. The build otherwise requires `name` to exist in the package's
+     * export surface, because the catalog is the API as far as an agent is
+     * concerned and `import { Error }` (for `ErrorState`) was written by every
+     * agent that read it. Declaring this is a visible claim that the name is a
+     * family label; do not reach for it to silence an ordinary mismatch.
+     */
+    system?: boolean;
+    /** One-line summary. */
+    summary: string;
+    /** Search terms and synonyms agents/users might use to discover it. */
+    keywords?: string[];
+    /** Usage guidance: intent, do/don'ts, and anatomy. */
+    usage?: UsageMeta;
+    /** Related components and patterns for composition/choice guidance. */
+    related?: RelatedMeta;
+    /** Maturity. */
+    /**
+     * Maturity.
+     *
+     * `deprecated` exists because it had to: `CategoryPill` announced
+     * "DEPRECATED" in its summary prose while carrying `status: "stable"`, since
+     * the union had no way to say otherwise. An agent reading the contract would
+     * have used it without hesitation. A deprecated component MUST also name its
+     * replacement in `supersededBy` — build-registry enforces both directions, so
+     * prose and status cannot disagree again.
+     */
+    status: "stable" | "beta" | "planned" | "deprecated";
+    /**
+     * What to use instead. Required when `status` is `deprecated`, and meaningless
+     * otherwise — a deprecation with no forward path just strands the reader.
+     */
+    supersededBy?: string;
+    /** Public props of the root component only — never subcomponents. */
+    props: PropMeta[];
+    /**
+     * Composed child components, if any. A component that lists subcomponents
+     * must also ship at least one example showing the composed JSX form.
+     */
+    subcomponents?: SubcomponentMeta[];
+    /** Variant axis → allowed values. */
+    variants?: Record<string, string[]>;
+    /** Semantic tokens the component reads (for theming audits). */
+    tokensUsed: string[];
+    /**
+     * How the component moves, one entry per applicable motion slot.
+     *
+     * Ordering follows the slot vocabulary (arrival → response → transition →
+     * activity), which is also the order a user encounters them.
+     */
+    motion?: MotionMeta[];
+    /** Accessibility notes. */
+    a11y?: string[];
+    /** Usage examples. */
+    examples: ExampleMeta[];
+}
+
+export type { AnatomyMeta as A, BestPracticeMeta as B, ComponentMeta as C, ExampleMeta as E, MotionMeta as M, PatternMeta as P, RelatedMeta as R, SubcomponentMeta as S, UsageMeta as U, MotionSlot as a, PropMeta as b };

package/dist/patterns/index.d.ts

@@ -0,0 +1,36 @@
+import * as react from 'react';
+import { P as PatternMeta } from '../meta-6dUzgC6M.js';
+
+declare function AuthPage(): react.JSX.Element;
+
+declare const authPageMeta: PatternMeta;
+
+declare function BrandLandingPage(): react.JSX.Element;
+
+declare const brandLandingPageMeta: PatternMeta;
+
+declare function ChatPanel(): react.JSX.Element;
+
+declare const chatPanelMeta: PatternMeta;
+
+declare function DashboardPage(): react.JSX.Element;
+
+declare const dashboardPageMeta: PatternMeta;
+
+declare function FeedPage(): react.JSX.Element;
+
+declare const feedPageMeta: PatternMeta;
+
+declare function LandingPage(): react.JSX.Element;
+
+declare const landingPageMeta: PatternMeta;
+
+declare function ListDetailPage(): react.JSX.Element;
+
+declare const listDetailPageMeta: PatternMeta;
+
+declare function SettingsPage(): react.JSX.Element;
+
+declare const settingsPageMeta: PatternMeta;
+
+export { AuthPage, BrandLandingPage, ChatPanel, DashboardPage, FeedPage, LandingPage, ListDetailPage, SettingsPage, authPageMeta, brandLandingPageMeta, chatPanelMeta, dashboardPageMeta, feedPageMeta, landingPageMeta, listDetailPageMeta, settingsPageMeta };