tembro 1.0.0

package/packages/cli/vendor/src/families/member-metadata.ts

@@ -0,0 +1,1033 @@
+import type { ComponentFamilyName } from "@/families/catalog"
+
+export type ComponentMemberMaturity = "canonical" | "member" | "transitional" | "advanced"
+
+export type ComponentMemberMetadata = {
+  component: string
+  family: ComponentFamilyName
+  section:
+    | "primitives"
+    | "presets"
+    | "form-wrappers"
+    | "wrappers"
+    | "extensions"
+    | "advanced"
+    | "transitional"
+  maturity: ComponentMemberMaturity
+  summary: string
+  useWhen: string
+}
+
+export const componentMemberMetadata: ComponentMemberMetadata[] = [
+  {
+    component: "Input",
+    family: "InputFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Primary text-entry surface with optional clear, trailing-action, and preset-friendly hooks.",
+    useWhen: "Use as the default field for text, search-like, password-like, and clearable entry before reaching for specialized formatting presets.",
+  },
+  {
+    component: "Textarea",
+    family: "InputFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Multi-line companion to Input for longer notes, descriptions, and support copy.",
+    useWhen: "Use when content should stay in the same input family, but the entry needs multi-line editing instead of a single-line field.",
+  },
+  {
+    component: "ClearableInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Ready-made Input preset that adds a built-in clear action.",
+    useWhen: "Use when teams want one-step clearing without rewiring Input clearable props by hand.",
+  },
+  {
+    component: "SearchInput",
+    family: "InputFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Search-oriented Input preset with icon, shortcut, and result-count affordances.",
+    useWhen: "Use for table filters, command surfaces, and search bars when Input needs search-specific chrome out of the box.",
+  },
+  {
+    component: "PasswordInput",
+    family: "InputFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Password-focused Input preset with reveal and hide behavior.",
+    useWhen: "Use in auth and credential forms when Input needs a secure visibility toggle without custom trailing actions.",
+  },
+  {
+    component: "NumberInput",
+    family: "InputFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Numeric Input preset with parsed value callbacks.",
+    useWhen: "Use when the same input surface should stay in place but emit parsed numeric values without relying on native spinner UX.",
+  },
+  {
+    component: "MaskedInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Formatting adapter layered on top of the base input surface.",
+    useWhen: "Use when raw and displayed values differ, such as identifiers and custom entry masks, but the control should still read like Input.",
+  },
+  {
+    component: "PhoneInput",
+    family: "InputFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Phone-number preset built on masking behavior.",
+    useWhen: "Use for phone capture when Input should keep readable formatting while storing or emitting normalized digits.",
+  },
+  {
+    component: "MoneyInput",
+    family: "InputFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Currency preset with prefix, suffix, and amount-friendly parsing behavior.",
+    useWhen: "Use for finance and pricing fields when Input needs currency context directly in the field chrome.",
+  },
+  {
+    component: "QuantityInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Numeric entry with optional step controls.",
+    useWhen: "Use for cart counts, stock edits, and compact quantity adjustments.",
+  },
+  {
+    component: "OtpInput",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Multi-cell one-time-code input.",
+    useWhen: "Use for verification and short secure code flows that benefit from per-digit focus management.",
+  },
+  {
+    component: "ColorInput",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Color picker field.",
+    useWhen: "Use when the browser-native color picker is enough for theme or label selection.",
+  },
+  {
+    component: "DateInput",
+    family: "InputFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Native date preset built on the shared input surface.",
+    useWhen: "Use for lightweight date capture where a full calendar popover is unnecessary but the field should still align with Input rhythm.",
+  },
+  {
+    component: "DateRangeInput",
+    family: "InputFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Two-field date-range preset using the same input framing.",
+    useWhen: "Use for admin filters and reports that need from/to entry without promoting a full visual calendar picker.",
+  },
+  {
+    component: "FormInput",
+    family: "InputFamily",
+    section: "form-wrappers",
+    maturity: "canonical",
+    summary: "Canonical React Hook Form wrapper for text-like inputs.",
+    useWhen: "Use as the primary RHF entry for text, search, password, number, phone, and date flows by switching the kind prop instead of learning many wrapper names.",
+  },
+  {
+    component: "FormSearchInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compatibility alias for FormInput kind=\"search\".",
+    useWhen: "Use only when migrating existing forms; prefer FormInput with kind=\"search\" for new work.",
+  },
+  {
+    component: "FormPasswordInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compatibility alias for FormInput kind=\"password\".",
+    useWhen: "Use only when migrating existing forms; prefer FormInput with kind=\"password\" for new work.",
+  },
+  {
+    component: "FormNumberInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compatibility alias for FormInput kind=\"number\".",
+    useWhen: "Use only when migrating existing forms; prefer FormInput with kind=\"number\" for new work.",
+  },
+  {
+    component: "FormPhoneInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compatibility alias for FormInput kind=\"phone\".",
+    useWhen: "Use only when migrating existing forms; prefer FormInput with kind=\"phone\" for new work.",
+  },
+  {
+    component: "FormDateInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compatibility alias for FormInput kind=\"date\".",
+    useWhen: "Use only when migrating existing forms; prefer FormInput with kind=\"date\" for new work.",
+  },
+  {
+    component: "FormDateRangeInput",
+    family: "InputFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "RHF wrapper around DateRangeInput.",
+    useWhen: "Use for filter and reporting forms that submit a plain from/to range object.",
+  },
+  {
+    component: "TagInput",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Multi-token freeform entry surface.",
+    useWhen: "Use only when a basic input or select cannot represent repeated tokens cleanly.",
+  },
+  {
+    component: "QuantityStepper",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Stepper-only quantity control.",
+    useWhen: "Use for compact increment/decrement interactions where free typing should be avoided.",
+  },
+
+  {
+    component: "Select",
+    family: "SelectFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Primary selection surface for known options, trigger chrome, and consistent option semantics.",
+    useWhen: "Use as the default choice input before reaching for remote loading, multi-selection, or keyboard-heavy local filtering members.",
+  },
+  {
+    component: "SimpleSelect",
+    family: "SelectFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compatibility helper for older static select setups.",
+    useWhen: "Use mainly when migrating existing static select call sites; prefer the base Select surface for new work.",
+  },
+  {
+    component: "AsyncSelect",
+    family: "SelectFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Remote-aware single-select member for search-driven option loading.",
+    useWhen: "Use when the select surface must load options on demand from a server or a large source while still reading like one selection flow.",
+  },
+  {
+    component: "AsyncMultiSelect",
+    family: "SelectFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Remote-aware multi-select member with inline selected tags.",
+    useWhen: "Use only when users truly need remote multi-pick behavior with visible chips; otherwise keep the simpler single-value select path.",
+  },
+  {
+    component: "Combobox",
+    family: "SelectFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Keyboard-first local filtering member related to the select family.",
+    useWhen: "Use when fast local keyboard filtering matters more than strict trigger semantics; avoid treating it as the default remote or creatable select path.",
+  },
+  {
+    component: "FormSelect",
+    family: "SelectFamily",
+    section: "form-wrappers",
+    maturity: "canonical",
+    summary: "Canonical RHF wrapper for base, static, and async select flows.",
+    useWhen: "Use as the main form entry for submitted select state, keeping simple and async modes behind one consistent wrapper contract.",
+  },
+  {
+    component: "FormAsyncSelect",
+    family: "SelectFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compatibility alias for FormSelect kind=\"async\".",
+    useWhen: "Use only when migrating existing forms; prefer FormSelect with kind=\"async\" for new work.",
+  },
+
+  {
+    component: "Card",
+    family: "CardFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Base card primitive.",
+    useWhen: "Use for neutral content framing before adopting dashboard-specific presets.",
+  },
+  {
+    component: "InfoCard",
+    family: "CardFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Reusable composed information card.",
+    useWhen: "Use for common metric and summary content where teams need a faster default than raw Card composition.",
+  },
+  {
+    component: "StatCard",
+    family: "CardFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Legacy compact stat display card.",
+    useWhen: "Use only when migrating older KPI tiles; prefer StatisticCard or InfoCard for new product surfaces.",
+  },
+  {
+    component: "StatisticCard",
+    family: "ChartFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Structured statistic card.",
+    useWhen: "Use when a metric needs trend, label, and support copy in one tile.",
+  },
+  {
+    component: "EntityCard",
+    family: "CardFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Entity-oriented card surface.",
+    useWhen: "Use for users, records, or business entities with compact metadata.",
+  },
+  {
+    component: "FileCard",
+    family: "CardFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "File preview card.",
+    useWhen: "Use for uploads, attachments, and lightweight asset lists.",
+  },
+  {
+    component: "SmartCard",
+    family: "CardFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Older card alias kept for migration compatibility.",
+    useWhen: "Use only when migrating existing surfaces; prefer Card or InfoCard for new usage.",
+  },
+
+  {
+    component: "Badge",
+    family: "BadgeFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical inline label and status marker.",
+    useWhen: "Use for metadata, status, counts, and small labels by switching tone, variant, size, and dot props.",
+  },
+  {
+    component: "Dialog",
+    family: "OverlayFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical modal dialog primitive.",
+    useWhen: "Use when a task needs focus management, blocking intent, and explicit close behavior.",
+  },
+  {
+    component: "Popover",
+    family: "OverlayFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical anchored floating content primitive.",
+    useWhen: "Use for non-blocking contextual controls, pickers, and rich anchored content.",
+  },
+  {
+    component: "DropdownMenu",
+    family: "OverlayFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical command menu primitive.",
+    useWhen: "Use for compact actions, account menus, and command lists anchored to a trigger.",
+  },
+  {
+    component: "Tooltip",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Small hover/focus explanation surface.",
+    useWhen: "Use for short helper text only; do not hide critical instructions inside a tooltip.",
+  },
+  {
+    component: "RightClickMenu",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Context menu surface for secondary pointer actions.",
+    useWhen: "Use when right-click actions supplement, not replace, visible primary actions.",
+  },
+  {
+    component: "AlertDialog",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Destructive or high-risk confirmation dialog.",
+    useWhen: "Use when an action needs explicit confirmation before it can continue.",
+  },
+  {
+    component: "ConfirmDialog",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "General confirmation dialog preset.",
+    useWhen: "Use for save, publish, and approval flows that need a reusable confirm surface.",
+  },
+  {
+    component: "ModalShell",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Dialog shell with title, description, body, footer, and size props.",
+    useWhen: "Use when repeated product modals need the same document structure.",
+  },
+  {
+    component: "SheetShell",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Side or edge sheet surface.",
+    useWhen: "Use for progressive detail panels and lightweight side workflows.",
+  },
+  {
+    component: "Drawer",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Drawer-style detail overlay.",
+    useWhen: "Use for record details and contextual edit flows that should not navigate away.",
+  },
+  {
+    component: "DialogActions",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Shared dialog footer action row.",
+    useWhen: "Use inside Dialog, ModalShell, SheetShell, or Drawer when footer buttons should align consistently.",
+  },
+  {
+    component: "FormFieldShell",
+    family: "FormFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Base shell for label, description, and validation copy.",
+    useWhen: "Use as the common structure for any custom form control that needs consistent field framing.",
+  },
+  {
+    component: "FormTextarea",
+    family: "FormFamily",
+    section: "wrappers",
+    maturity: "member",
+    summary: "RHF textarea wrapper.",
+    useWhen: "Use for multi-line text in forms that need shared field-shell behavior.",
+  },
+  {
+    component: "FormSwitch",
+    family: "FormFamily",
+    section: "wrappers",
+    maturity: "member",
+    summary: "RHF switch wrapper.",
+    useWhen: "Use for boolean toggles tied to validation and descriptive copy.",
+  },
+  {
+    component: "FormDatePicker",
+    family: "FormFamily",
+    section: "wrappers",
+    maturity: "member",
+    summary: "RHF wrapper around calendar date picker.",
+    useWhen: "Use when the form needs a richer date picker than a native date input.",
+  },
+  {
+    component: "FormDateRangePicker",
+    family: "FormFamily",
+    section: "wrappers",
+    maturity: "member",
+    summary: "RHF wrapper around calendar date range picker.",
+    useWhen: "Use when a form needs a visual range-selection experience instead of plain from/to inputs.",
+  },
+  {
+    component: "FormBuilder",
+    family: "FormFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Schema-driven form renderer.",
+    useWhen: "Use when forms must be configured dynamically or generated from backend definitions.",
+  },
+  {
+    component: "InlineEditable",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "In-place text editing surface for dense operational UIs.",
+    useWhen: "Use when editing should happen directly inside a row or card without opening a full form layout.",
+  },
+  {
+    component: "Slider",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Single-thumb visual range control for bounded numeric values.",
+    useWhen: "Use when dragging communicates the value better than typing and the range is already known.",
+  },
+  {
+    component: "RangeSlider",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Two-thumb visual control for selecting a minimum and maximum together.",
+    useWhen: "Use when one surface should own both lower and upper bounds instead of teaching two separate numeric fields.",
+  },
+  {
+    component: "Rating",
+    family: "InputFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Compact score and sentiment input with star-like selection behavior.",
+    useWhen: "Use for review, quality, or satisfaction capture when a small visual rating control is clearer than raw numbers.",
+  },
+  {
+    component: "TrendCard",
+    family: "CardFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Metric card with trend and sparkline.",
+    useWhen: "Use for dashboards where historical context is important.",
+  },
+  {
+    component: "ComparisonCard",
+    family: "CardFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Multi-column stat comparison card.",
+    useWhen: "Use when comparing interrelated metrics directly.",
+  },
+  {
+    component: "DeltaBadge",
+    family: "BadgeFamily",
+    section: "primitives",
+    maturity: "member",
+    summary: "Inline trend delta badge.",
+    useWhen: "Use to show positive/negative changes within data grids or lists.",
+  },
+  {
+    component: "HoverCard",
+    family: "OverlayFamily",
+    section: "presets",
+    maturity: "member",
+    summary: "Rich hover and focus preview card.",
+    useWhen: "Use for lightweight previews when a tooltip is too small but a popover is too heavy.",
+  },
+  {
+    component: "RepeaterField",
+    family: "FormFamily",
+    section: "wrappers",
+    maturity: "member",
+    summary: "Form array manager.",
+    useWhen: "Use when a form needs repeated dynamic field groups with add/remove actions.",
+  },
+  {
+    component: "DataTable",
+    family: "DataTableFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical tabular data surface.",
+    useWhen: "Use when rows, sorting, selection, and pagination belong in one reusable grid.",
+  },
+  {
+    component: "DataTableToolbar",
+    family: "DataTableFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Toolbar scaffold for table actions and filters.",
+    useWhen: "Use when the table needs a structured top bar instead of ad-hoc controls.",
+  },
+  {
+    component: "DataTablePagination",
+    family: "DataTableFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Pagination control for the data table.",
+    useWhen: "Use when pagination UI should remain visually aligned with the table system.",
+  },
+  {
+    component: "DataTableColumnVisibilityMenu",
+    family: "DataTableFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Hide/show columns control.",
+    useWhen: "Use after the base table experience is already clear and users truly need per-column personalization.",
+  },
+  {
+    component: "DataTableSortableHeader",
+    family: "DataTableFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Sortable header helper.",
+    useWhen: "Use when composing custom tables around the shared sort contract instead of the full canonical DataTable route.",
+  },
+  {
+    component: "DataTableRowActions",
+    family: "DataTableFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Row-level actions surface.",
+    useWhen: "Use when each row needs contextual actions without custom menu plumbing.",
+  },
+  {
+    component: "DataTableBulkActions",
+    family: "DataTableFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Bulk selection action surface.",
+    useWhen: "Use when multi-row operations should appear only after selection.",
+  },
+  {
+    component: "DataTableViewPresets",
+    family: "DataTableFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Preset view controls for table states.",
+    useWhen: "Use when users need quick switching between saved or opinionated table views.",
+  },
+  {
+    component: "createDataTableSelectColumn",
+    family: "DataTableFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Selection column factory.",
+    useWhen: "Use when custom column composition is required and you still want the standard row-selection contract.",
+  },
+  {
+    component: "createDataTableActionsColumn",
+    family: "DataTableFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Actions column factory.",
+    useWhen: "Use when a custom table still needs the shared row-actions contract without rewriting the full column definition.",
+  },
+  {
+    component: "TableExportMenu",
+    family: "DataTableFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Export helpers for tables.",
+    useWhen: "Use only after the core table experience is already clear and export is truly required.",
+  },
+  {
+    component: "TableImportButton",
+    family: "DataTableFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Import trigger tied to table workflows.",
+    useWhen: "Use only when import belongs directly beside a data table management flow.",
+  },
+  {
+    component: "Button",
+    family: "ActionFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Primary clickable action surface for product flows.",
+    useWhen: "Use as the default action trigger before reaching for grouped actions, menus, or embedded copy patterns.",
+  },
+  {
+    component: "ActionMenu",
+    family: "ActionFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Compact action list anchored to one trigger.",
+    useWhen: "Use when several related actions should sit behind one entry point instead of competing as many buttons.",
+  },
+  {
+    component: "CopyButton",
+    family: "ActionFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "One-tap copy action with built-in feedback.",
+    useWhen: "Use when copying text or IDs should behave like a small action rather than a full input field pattern.",
+  },
+  {
+    component: "ButtonGroup",
+    family: "ActionFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Grouped button layout helper.",
+    useWhen: "Use when several buttons must align together, but keep it secondary to the main Button mental model.",
+  },
+  {
+    component: "CopyField",
+    family: "ActionFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Embedded copy pattern around a displayed value.",
+    useWhen: "Use when a visible value and its copy action should stay bundled in one compact row.",
+  },
+  {
+    component: "QuickActionGrid",
+    family: "ActionFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Grid layout for several action shortcuts.",
+    useWhen: "Use when a dense dashboard block needs a small board of quick actions rather than one primary trigger.",
+  },
+  {
+    component: "Alert",
+    family: "FeedbackFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical inline product status surface.",
+    useWhen: "Use when the screen needs one clear information, success, warning, or error message with optional action copy.",
+  },
+  {
+    component: "EmptyState",
+    family: "FeedbackFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Empty-result and no-data state surface.",
+    useWhen: "Use when a view needs a structured zero-data message instead of a plain sentence.",
+  },
+  {
+    component: "LoadingState",
+    family: "FeedbackFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical loading message surface.",
+    useWhen: "Use when loading should be explained with label, description, and product framing instead of a spinner alone.",
+  },
+  {
+    component: "Progress",
+    family: "ProgressFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Progress feedback bar for completion and status tracking.",
+    useWhen: "Use when a task, upload, or rollout needs visible completion progress in the main interface.",
+  },
+  {
+    component: "ProgressCircle",
+    family: "ProgressFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Compact circular progress indicator for constrained dashboard spaces.",
+    useWhen: "Use when the same completion signal must fit inside small cards, badges, or compact status blocks.",
+  },
+  {
+    component: "ToastProvider",
+    family: "FeedbackFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Notification host for ephemeral product feedback.",
+    useWhen: "Use when transient confirmations and background outcomes should appear as toasts across the app.",
+  },
+  {
+    component: "InlineState",
+    family: "FeedbackFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Small inline status row for compact layouts.",
+    useWhen: "Use when state feedback must stay inside a dense card, list row, or side panel instead of taking a full empty-state layout.",
+  },
+  {
+    component: "LoadingOverlay",
+    family: "FeedbackFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Overlay loading mask for blocking local interaction.",
+    useWhen: "Use when a surface should stay visible but temporarily blocked while loading or submitting.",
+  },
+  {
+    component: "Spinner",
+    family: "FeedbackFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Minimal loading glyph.",
+    useWhen: "Use only when a tiny loading affordance is enough and a full LoadingState would be too heavy.",
+  },
+  {
+    component: "Skeleton",
+    family: "FeedbackFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Placeholder surface for loading content structure.",
+    useWhen: "Use when the layout should stay visible during loading and the content shape matters more than a spinner.",
+  },
+  {
+    component: "useToast",
+    family: "FeedbackFamily",
+    section: "advanced",
+    maturity: "advanced",
+    summary: "Imperative hook for dispatching toast notifications.",
+    useWhen: "Use after ToastProvider is mounted and a feature needs to trigger transient feedback from event handlers or async flows.",
+  },
+  {
+    component: "BarChart",
+    family: "ChartFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Categorical bar chart for dashboard comparisons.",
+    useWhen: "Use when values should be compared across a finite list of categories with strong scanability.",
+  },
+  {
+    component: "LineChart",
+    family: "ChartFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Trend line for time or sequential values.",
+    useWhen: "Use when change over time or ordered points is more important than isolated category comparison.",
+  },
+  {
+    component: "DonutChart",
+    family: "ChartFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Part-to-whole chart with central summary space.",
+    useWhen: "Use when a compact composition needs proportional slices and one clear total or center metric.",
+  },
+  {
+    component: "MetricGrid",
+    family: "ChartFamily",
+    section: "primitives",
+    maturity: "member",
+    summary: "Dashboard-ready metric grid for grouped KPI cards.",
+    useWhen: "Use when several related KPIs should stay aligned in one responsive summary surface.",
+  },
+  {
+    component: "ChartFrame",
+    family: "ChartFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Shared shell around chart content, title, and actions.",
+    useWhen: "Use when a chart needs consistent framing, headings, and auxiliary actions without rebuilding the outer card each time.",
+  },
+  {
+    component: "ChartLegend",
+    family: "ChartFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Legend block for chart series labels.",
+    useWhen: "Use when a chart needs explicit series mapping instead of relying on color alone.",
+  },
+  {
+    component: "Sparkline",
+    family: "ChartFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Compact micro-trend line.",
+    useWhen: "Use when a tiny trend hint should support a number without turning into a full chart section.",
+  },
+  {
+    component: "MetricTrend",
+    family: "ChartFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Metric summary with change direction and sparkline context.",
+    useWhen: "Use when a KPI should include both the current value and quick historical direction in one block.",
+  },
+  {
+    component: "Statistic",
+    family: "ChartFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Structured single KPI readout.",
+    useWhen: "Use when a single metric needs title, value, and supporting copy in a more formal statistic layout.",
+  },
+  {
+    component: "StatisticGrid",
+    family: "ChartFamily",
+    section: "extensions",
+    maturity: "member",
+    summary: "Grid layout for several structured statistics.",
+    useWhen: "Use when multiple KPI readouts should stay aligned but do not need the richer MetricGrid treatment.",
+  },
+  {
+    component: "Sidebar",
+    family: "NavigationFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Primary application sidebar for workspace navigation.",
+    useWhen: "Use when an app needs persistent primary navigation, nested sections, and account or workspace actions.",
+  },
+  {
+    component: "PageContainer",
+    family: "NavigationFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Width and page rhythm wrapper for screen content.",
+    useWhen: "Use when pages should share one consistent max-width and horizontal spacing contract.",
+  },
+  {
+    component: "Tabs",
+    family: "NavigationFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical tabbed navigation surface.",
+    useWhen: "Use when the user should switch between a small set of peer sections without leaving the page.",
+  },
+  {
+    component: "Pagination",
+    family: "NavigationFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Page navigation control for lists and tables.",
+    useWhen: "Use when records are split across pages and the user must move between indexed result sets.",
+  },
+  {
+    component: "Breadcrumbs",
+    family: "NavigationFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Hierarchical location trail.",
+    useWhen: "Use when nested pages or resources need one concise location indicator back through the product structure.",
+  },
+  {
+    component: "Wizard",
+    family: "NavigationFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Multi-step flow wrapper around a guided process.",
+    useWhen: "Use when the user must complete a sequence of connected steps with clear forward progress.",
+  },
+  {
+    component: "Section",
+    family: "NavigationFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Page section wrapper for grouped content.",
+    useWhen: "Use when page content needs local framing, but keep it secondary to the primary navigation and page-shell surfaces.",
+  },
+  {
+    component: "AnchorNav",
+    family: "NavigationFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "In-page anchor navigation.",
+    useWhen: "Use when long detail pages need local section jumping without becoming the main navigation model.",
+  },
+  {
+    component: "Stepper",
+    family: "NavigationFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Step indicator for guided flows.",
+    useWhen: "Use when a flow needs visible step progress but not the full Wizard wrapper.",
+  },
+  {
+    component: "StepperTabs",
+    family: "NavigationFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Tab-like step navigation.",
+    useWhen: "Use when sections read like steps, but the interaction still behaves closer to tabs than a full wizard.",
+  },
+  {
+    component: "SegmentedControl",
+    family: "NavigationFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Compact segment switcher for small option sets.",
+    useWhen: "Use when a short set of mutually exclusive views needs an inline switch rather than a full tab layout.",
+  },
+  {
+    component: "FileUpload",
+    family: "UploadFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Generic file upload flow with validation and file-state handling.",
+    useWhen: "Use when users should add, review, and remove uploaded files inside the same product surface.",
+  },
+  {
+    component: "ImageUpload",
+    family: "UploadFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Image-specific upload flow with preview-oriented behavior.",
+    useWhen: "Use when uploaded files are images and the product benefits from preview, replace, or image-aware affordances.",
+  },
+  {
+    component: "Checkbox",
+    family: "PrimitiveFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Canonical binary and multi-select primitive.",
+    useWhen: "Use when a list or form needs explicit toggled selection with checked, unchecked, or indeterminate states.",
+  },
+  {
+    component: "RadioGroup",
+    family: "PrimitiveFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Single-choice selection primitive across several options.",
+    useWhen: "Use when exactly one option from a short visible set should be selected at a time.",
+  },
+  {
+    component: "Switch",
+    family: "PrimitiveFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Immediate boolean toggle primitive.",
+    useWhen: "Use when turning a setting on or off should feel faster and more direct than a checkbox row.",
+  },
+  {
+    component: "Table",
+    family: "PrimitiveFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Base table markup and styling surface.",
+    useWhen: "Use when tabular content is simple enough that a full DataTable would be unnecessary.",
+  },
+  {
+    component: "Accordion",
+    family: "PrimitiveFamily",
+    section: "primitives",
+    maturity: "canonical",
+    summary: "Expandable disclosure primitive for stacked content.",
+    useWhen: "Use when dense sections should reveal more detail inline without leaving the current page context.",
+  },
+  {
+    component: "Collapse",
+    family: "PrimitiveFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Low-level collapse primitive behind accordion-like disclosure patterns.",
+    useWhen: "Use when you need raw expand-collapse behavior and do not want Accordion’s higher-level structure.",
+  },
+  {
+    component: "Calendar",
+    family: "PrimitiveFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Calendar view primitive used by richer date pickers.",
+    useWhen: "Use when a custom date-selection surface needs raw calendar control rather than the product-ready picker wrappers.",
+  },
+  {
+    component: "Divider",
+    family: "PrimitiveFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Visual separator for grouped content.",
+    useWhen: "Use when layout sections need a subtle boundary without becoming a first-level product surface.",
+  },
+  {
+    component: "Kbd",
+    family: "PrimitiveFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Keyboard shortcut token.",
+    useWhen: "Use when command surfaces and shortcuts should display consistent keycap styling inline.",
+  },
+  {
+    component: "ScrollBox",
+    family: "PrimitiveFamily",
+    section: "transitional",
+    maturity: "transitional",
+    summary: "Scrollable content wrapper with constrained height.",
+    useWhen: "Use when a panel or list needs local scrolling without teaching a larger product concept.",
+  },
+] as const