@lostgradient/cinder 0.1.1 → 0.3.0

package/components.json

@@ -3,7 +3,7 @@
   "manifestVersion": 1,
   "package": {
     "name": "@lostgradient/cinder",
-    "version": "0.1.1",
+    "version": "0.3.0",
     "framework": "svelte",
     "frameworkVersionRange": ">=5.55.0 <6",
     "classPrefix": "cinder-",
@@ -64,6 +64,41 @@
     "tabs": ["tabs", "segmented-control"]
   },
   "components": [
+    {
+      "name": "AccessGate",
+      "id": "access-gate",
+      "import": "@lostgradient/cinder/access-gate",
+      "exportName": "AccessGate",
+      "category": "feedback",
+      "status": "alpha",
+      "purpose": "Authorization-scope gate that keeps unavailable actions visible with an accessible reason or replaces locked sections with a scope-required placeholder.",
+      "tags": ["feedback", "authorization", "permission"],
+      "useWhen": [
+        "Showing a mutating action that the current user cannot activate because an application authorization scope is missing.",
+        "Replacing a panel, tab, or administrative section with a lock state that names the missing scope or permission."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Checking browser permissions, media capabilities, or feature support — use capability-gate instead."
+        },
+        {
+          "reason": "Resolving roles, scopes, or policies — compute granted in application code and pass the boolean in."
+        }
+      ],
+      "related": ["capability-gate", "button", "callout", "empty-state"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/access-gate/schema",
+        "variables": "@lostgradient/cinder/access-gate/variables",
+        "examples": "@lostgradient/cinder/access-gate/examples"
+      },
+      "a11y": {
+        "notes": [
+          "Denied inline gates render content inert before hydration, then disable controls, remove them from sequential focus, and wire the reason through aria-describedby."
+        ]
+      }
+    },
     {
       "name": "Accordion",
       "id": "accordion",
@@ -78,8 +113,14 @@
         "Letting the consumer expand one or multiple panels at once via the multiple prop."
       ],
       "avoidWhen": [
-        "Switching between mutually exclusive views of the same region — use tabs instead.",
-        "Hiding a single optional region — use a plain disclosure or details element."
+        {
+          "reason": "Switching between mutually exclusive views of the same region.",
+          "alternative": "tabs"
+        },
+        {
+          "reason": "Hiding a single optional region — reach for a plain disclosure instead.",
+          "alternative": "collapsible"
+        }
       ],
       "related": ["accordion-item", "tabs", "tree"],
       "hasConstraints": false,
@@ -88,6 +129,28 @@
         "schema": "@lostgradient/cinder/accordion/schema",
         "variables": "@lostgradient/cinder/accordion/variables",
         "examples": "@lostgradient/cinder/accordion/examples"
+      },
+      "a11y": {
+        "pattern": "WAI-ARIA Accordion",
+        "keyboard": [
+          {
+            "keys": "Tab",
+            "action": "Moves focus to the next focusable element (accordion header buttons are in the natural tab order)."
+          },
+          {
+            "keys": "Shift + Tab",
+            "action": "Moves focus to the previous focusable element."
+          },
+          {
+            "keys": "Enter / Space",
+            "action": "When focus is on a header button, toggles the associated panel open or closed."
+          }
+        ],
+        "notes": [
+          "Each trigger is a native button exposing aria-expanded and aria-controls, so screen readers announce open/closed state.",
+          "Panels intentionally omit role=\"region\" to keep the page's landmark list clean.",
+          "Disabled items set the native disabled attribute on their trigger, removing them from the tab order."
+        ]
       }
     },
     {
@@ -104,7 +167,9 @@
         "Disabling a single section while leaving siblings interactive via the disabled prop."
       ],
       "avoidWhen": [
-        "Standing alone outside an accordion — it requires the accordion context to function."
+        {
+          "reason": "Standing alone outside an accordion — it requires the accordion context to function."
+        }
       ],
       "related": ["accordion"],
       "hasConstraints": false,
@@ -128,8 +193,12 @@
         "Calling out a transient condition the user must notice immediately within a specific region."
       ],
       "avoidWhen": [
-        "Communicating a page- or app-wide notice that persists across views — use a banner instead.",
-        "Providing supplemental commentary or guidance inline with content — use a callout instead."
+        {
+          "reason": "Communicating a page- or app-wide notice that persists across views — use a banner instead."
+        },
+        {
+          "reason": "Providing supplemental commentary or guidance inline with content — use a callout instead."
+        }
       ],
       "related": ["banner", "callout", "toast-region"],
       "hasConstraints": false,
@@ -154,8 +223,12 @@
         "Presenting a destructive or high-risk message that needs an explicit OK action."
       ],
       "avoidWhen": [
-        "Asking a reversible yes/no question — use confirm-dialog.",
-        "Collecting rich form input — compose modal instead."
+        {
+          "reason": "Asking a reversible yes/no question — use confirm-dialog."
+        },
+        {
+          "reason": "Collecting rich form input — compose modal instead."
+        }
       ],
       "related": ["modal", "confirm-dialog", "drawer"],
       "hasConstraints": false,
@@ -180,8 +253,12 @@
         "Comparing cumulative or stacked contribution over an ordered domain."
       ],
       "avoidWhen": [
-        "Exact point comparison matters more than area magnitude — use line-chart instead.",
-        "Comparing discrete category totals — use bar-chart instead."
+        {
+          "reason": "Exact point comparison matters more than area magnitude — use line-chart instead."
+        },
+        {
+          "reason": "Comparing discrete category totals — use bar-chart instead."
+        }
       ],
       "related": ["line-chart", "bar-chart", "table", "stat"],
       "hasConstraints": false,
@@ -206,8 +283,12 @@
         "You need a generic ratio wrapper for iframe, video, canvas, or custom content rather than an image-specific primitive."
       ],
       "avoidWhen": [
-        "The child already owns its sizing contract and should determine its own height naturally.",
-        "Supporting legacy browsers that lack native aspect-ratio support."
+        {
+          "reason": "The child already owns its sizing contract and should determine its own height naturally."
+        },
+        {
+          "reason": "Supporting legacy browsers that lack native aspect-ratio support."
+        }
       ],
       "related": ["image", "card"],
       "hasConstraints": false,
@@ -232,7 +313,9 @@
         "Keeping the user's text as the committed value while suggestions remain optional hints."
       ],
       "avoidWhen": [
-        "Requiring the final value to come from a fixed option list — use combobox instead."
+        {
+          "reason": "Requiring the final value to come from a fixed option list — use combobox instead."
+        }
       ],
       "related": ["combobox", "search-field", "popover"],
       "hasConstraints": false,
@@ -256,7 +339,11 @@
         "Representing a person or account next to their name or activity.",
         "Displaying initials when no avatar image is available."
       ],
-      "avoidWhen": ["Showing a small status or count indicator — use badge or status-dot instead."],
+      "avoidWhen": [
+        {
+          "reason": "Showing a small status or count indicator — use badge or status-dot instead."
+        }
+      ],
       "related": ["badge", "status-dot", "image"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -280,8 +367,12 @@
         "Summarizing a bounded set of people with a visible overflow count."
       ],
       "avoidWhen": [
-        "Rendering a single person — use avatar instead.",
-        "Showing status, counts, or metadata labels unrelated to people — use badge, chip, or status-dot instead."
+        {
+          "reason": "Rendering a single person — use avatar instead."
+        },
+        {
+          "reason": "Showing status, counts, or metadata labels unrelated to people — use badge, chip, or status-dot instead."
+        }
       ],
       "related": ["avatar", "badge", "tooltip", "status-dot"],
       "hasConstraints": false,
@@ -306,9 +397,15 @@
         "Building a loading state that dims the full viewport while an async operation runs."
       ],
       "avoidWhen": [
-        "Interrupting the user for a decision — use modal or alert-dialog which manage focus and Escape automatically.",
-        "Showing a side panel — use drawer instead.",
-        "Showing structured content in a dialog — use modal, drawer, or sheet, which render their own native `<dialog>::backdrop` scrim."
+        {
+          "reason": "Interrupting the user for a decision — use modal or alert-dialog which manage focus and Escape automatically."
+        },
+        {
+          "reason": "Showing a side panel — use drawer instead."
+        },
+        {
+          "reason": "Showing structured content in a dialog — use modal, drawer, or sheet, which render their own native `<dialog>::backdrop` scrim."
+        }
       ],
       "related": ["modal", "drawer", "sheet"],
       "hasConstraints": false,
@@ -333,8 +430,12 @@
         "Displaying a numeric count next to an icon or title."
       ],
       "avoidWhen": [
-        "The label must be interactive or removable — use chip instead.",
-        "Showing only a colored dot for presence — use status-dot instead."
+        {
+          "reason": "The label must be interactive or removable — use chip instead."
+        },
+        {
+          "reason": "Showing only a colored dot for presence — use status-dot instead."
+        }
       ],
       "related": ["chip", "status-dot"],
       "hasConstraints": false,
@@ -359,8 +460,12 @@
         "Pinning a non-urgent message above page content that should remain readable until acknowledged."
       ],
       "avoidWhen": [
-        "Announcing an urgent, time-sensitive message — use alert so assistive tech reads it immediately.",
-        "Highlighting an inline aside next to related prose — use callout instead."
+        {
+          "reason": "Announcing an urgent, time-sensitive message — use alert so assistive tech reads it immediately."
+        },
+        {
+          "reason": "Highlighting an inline aside next to related prose — use callout instead."
+        }
       ],
       "related": ["alert", "callout", "toast-region"],
       "hasConstraints": false,
@@ -384,8 +489,12 @@
         "Showing stacked contribution across known categories."
       ],
       "avoidWhen": [
-        "Showing a continuous ordered trend — use line-chart instead.",
-        "Showing magnitude under a trend — use area-chart instead."
+        {
+          "reason": "Showing a continuous ordered trend — use line-chart instead."
+        },
+        {
+          "reason": "Showing magnitude under a trend — use area-chart instead."
+        }
       ],
       "related": ["line-chart", "area-chart", "table", "stat"],
       "hasConstraints": false,
@@ -410,8 +519,12 @@
         "Letting the user jump back to any ancestor view in one click."
       ],
       "avoidWhen": [
-        "Switching between sibling sections at the same level — use navigation-bar or tabs.",
-        "Showing an ordered task progression — use steps instead."
+        {
+          "reason": "Switching between sibling sections at the same level — use navigation-bar or tabs."
+        },
+        {
+          "reason": "Showing an ordered task progression — use steps instead."
+        }
       ],
       "related": ["navigation-bar", "side-navigation", "steps"],
       "hasConstraints": false,
@@ -436,8 +549,12 @@
         "Rendering a link that should look and behave like a button by passing href."
       ],
       "avoidWhen": [
-        "Toggling a binary on or off state — use toggle instead.",
-        "Selecting one of a small fixed set of options — use segmented-control instead."
+        {
+          "reason": "Toggling a binary on or off state — use toggle instead."
+        },
+        {
+          "reason": "Selecting one of a small fixed set of options — use segmented-control instead."
+        }
       ],
       "related": ["button-group", "copy-button"],
       "hasConstraints": true,
@@ -463,8 +580,12 @@
         "Visually joining multiple buttons into a single segmented bar without implying selection."
       ],
       "avoidWhen": [
-        "Selecting exactly one option from a fixed set — use segmented-control instead.",
-        "Rendering a single button — use button on its own."
+        {
+          "reason": "Selecting exactly one option from a fixed set — use segmented-control instead."
+        },
+        {
+          "reason": "Rendering a single button — use button on its own."
+        }
       ],
       "related": ["button", "segmented-control"],
       "hasConstraints": false,
@@ -489,8 +610,12 @@
         "Calling out a tip, note, or caveat that belongs next to the content it qualifies."
       ],
       "avoidWhen": [
-        "Announcing a transient or urgent status — use alert or banner instead.",
-        "Communicating a page-wide system message — use banner so it reads as a landmark region."
+        {
+          "reason": "Announcing a transient or urgent status — use alert or banner instead."
+        },
+        {
+          "reason": "Communicating a page-wide system message — use banner so it reads as a landmark region."
+        }
       ],
       "related": ["alert", "banner"],
       "hasConstraints": false,
@@ -500,6 +625,36 @@
         "variables": "@lostgradient/cinder/callout/variables"
       }
     },
+    {
+      "name": "CapabilityGate",
+      "id": "capability-gate",
+      "import": "@lostgradient/cinder/capability-gate",
+      "exportName": "CapabilityGate",
+      "category": "feedback",
+      "status": "alpha",
+      "purpose": "Present feature availability and next action for browser permission or support states, with accessible status text and focus management.",
+      "tags": ["feedback", "permission", "notice"],
+      "useWhen": [
+        "Surfacing that a feature requires a browser permission such as microphone or notifications.",
+        "Communicating that a feature is unsupported in the current browser with a clear fallback path."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Performing the actual feature detection or permission request — wire that in userland."
+        },
+        {
+          "reason": "Storing permission state — CapabilityGate is a pure presentation component."
+        }
+      ],
+      "related": ["alert", "banner", "callout", "modal"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/capability-gate/schema",
+        "variables": "@lostgradient/cinder/capability-gate/variables",
+        "examples": "@lostgradient/cinder/capability-gate/examples"
+      }
+    },
     {
       "name": "Card",
       "id": "card",
@@ -514,8 +669,12 @@
         "Composing a list of comparable items where each needs its own framed region."
       ],
       "avoidWhen": [
-        "Rendering a bare visual surface without slotted regions — use surface instead.",
-        "Presenting a single key metric — use stat or stat-group instead."
+        {
+          "reason": "Rendering a bare visual surface without slotted regions — use surface instead."
+        },
+        {
+          "reason": "Presenting a single key metric — use stat or stat-group instead."
+        }
       ],
       "related": ["surface", "stat", "stacked-list-item", "section-heading"],
       "hasConstraints": false,
@@ -540,8 +699,12 @@
         "Building an AI assistant or support thread where conversation state is modeled as a transcript of role-tagged messages."
       ],
       "avoidWhen": [
-        "Rendering a one-off message list — compose lighter primitives directly instead of pulling the full suite.",
-        "The transcript is read-only and needs no composer — a simple list of message bubbles is a better fit."
+        {
+          "reason": "Rendering a one-off message list — compose lighter primitives directly instead of pulling the full suite."
+        },
+        {
+          "reason": "The transcript is read-only and needs no composer — a simple list of message bubbles is a better fit."
+        }
       ],
       "related": ["markdown-editor"],
       "hasConstraints": false,
@@ -552,6 +715,66 @@
         "examples": "@lostgradient/cinder/chat/examples"
       }
     },
+    {
+      "name": "ChatConversationHeader",
+      "id": "chat-conversation-header",
+      "import": "@lostgradient/cinder/chat-conversation-header",
+      "exportName": "ChatConversationHeader",
+      "category": "domain",
+      "status": "domain-suite",
+      "purpose": "Header primitive for the active Chat conversation, composed as a sibling above Chat rather than inside it.",
+      "tags": ["chat", "conversation", "header"],
+      "useWhen": [
+        "Showing the active conversation title, participants, status, and export controls above a Chat transcript.",
+        "Building a multi-conversation chat layout where the list, header, and Chat surface are composed as siblings."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Rendering the conversation switcher — use chat-conversation-list."
+        },
+        {
+          "reason": "Rendering the transcript body and composer — use chat."
+        }
+      ],
+      "related": ["chat", "chat-conversation-list"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/chat-conversation-header/schema",
+        "variables": "@lostgradient/cinder/chat-conversation-header/variables",
+        "examples": "@lostgradient/cinder/chat-conversation-header/examples"
+      }
+    },
+    {
+      "name": "ChatConversationList",
+      "id": "chat-conversation-list",
+      "import": "@lostgradient/cinder/chat-conversation-list",
+      "exportName": "ChatConversationList",
+      "category": "domain",
+      "status": "domain-suite",
+      "purpose": "Conversation navigation list for switching among Chat transcripts without embedding the list inside Chat.",
+      "tags": ["chat", "conversation", "navigation"],
+      "useWhen": [
+        "Rendering a multi-conversation chat sidebar beside one active Chat transcript.",
+        "Showing unread counts and last-message previews for compatible conversation snapshots."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Rendering the message transcript itself — use chat for the active conversation surface."
+        },
+        {
+          "reason": "Building app-wide primary navigation — use side-navigation or navigation-bar."
+        }
+      ],
+      "related": ["chat", "chat-conversation-header", "side-navigation"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/chat-conversation-list/schema",
+        "variables": "@lostgradient/cinder/chat-conversation-list/variables",
+        "examples": "@lostgradient/cinder/chat-conversation-list/examples"
+      }
+    },
     {
       "name": "Checkbox",
       "id": "checkbox",
@@ -566,8 +789,12 @@
         "Representing a parent state that aggregates child selections via indeterminate."
       ],
       "avoidWhen": [
-        "Flipping a single setting on or off with immediate effect — use toggle instead.",
-        "Picking exactly one option from a small fixed set — use RadioGroup or segmented-control instead."
+        {
+          "reason": "Flipping a single setting on or off with immediate effect — use toggle instead."
+        },
+        {
+          "reason": "Picking exactly one option from a small fixed set — use RadioGroup or segmented-control instead."
+        }
       ],
       "related": ["checkbox-group", "radio-group", "toggle", "segmented-control"],
       "hasConstraints": false,
@@ -591,7 +818,11 @@
         "Presenting several unrelated checkboxes that share a common heading or validation message.",
         "Cascading a disabled state to every child checkbox via native fieldset propagation."
       ],
-      "avoidWhen": ["Picking exactly one option from a fixed set — use radio-group instead."],
+      "avoidWhen": [
+        {
+          "reason": "Picking exactly one option from a fixed set — use radio-group instead."
+        }
+      ],
       "related": ["checkbox", "radio-group", "form-field"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -614,8 +845,12 @@
         "Offering a small toggleable option inside a group of choices."
       ],
       "avoidWhen": [
-        "Showing a numeric count, short status, or compact category annotation next to another element — use badge instead.",
-        "Picking one of a small fixed set — use segmented-control instead."
+        {
+          "reason": "Showing a numeric count, short status, or compact category annotation next to another element — use badge instead."
+        },
+        {
+          "reason": "Picking one of a small fixed set — use segmented-control instead."
+        }
       ],
       "related": ["badge", "status-dot"],
       "hasConstraints": false,
@@ -626,6 +861,59 @@
         "examples": "@lostgradient/cinder/chip/examples"
       }
     },
+    {
+      "name": "ChoiceGrid",
+      "id": "choice-grid",
+      "import": "@lostgradient/cinder/choice-grid",
+      "exportName": "ChoiceGrid",
+      "category": "form",
+      "status": "alpha",
+      "purpose": "Responsive grid of large selectable choices with roving keyboard focus, selection state, and optional correct/incorrect/pending feedback for quiz and assessment surfaces.",
+      "tags": ["form", "selection", "quiz", "assessment"],
+      "useWhen": [
+        "Presenting a small fixed set of large selectable answers where all options should stay visible (quiz or assessment surfaces).",
+        "Building a touch-friendly selector grid with stable cell dimensions that must not shift when feedback states are applied."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Selecting from a long dynamic list — use combobox or select instead."
+        },
+        {
+          "reason": "Choosing one of two to five short values in a compact inline context — use segmented-control instead."
+        }
+      ],
+      "related": ["choice-grid-item", "segmented-control", "radio-group", "checkbox-group"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/choice-grid/schema",
+        "variables": "@lostgradient/cinder/choice-grid/variables",
+        "examples": "@lostgradient/cinder/choice-grid/examples"
+      }
+    },
+    {
+      "name": "ChoiceGridItem",
+      "id": "choice-grid-item",
+      "import": "@lostgradient/cinder/choice-grid-item",
+      "exportName": "ChoiceGridItem",
+      "category": "form",
+      "status": "alpha",
+      "purpose": "Selectable answer tile used inside a ChoiceGrid; carries selected, disabled, correct, incorrect, and pending states without shifting cell dimensions.",
+      "tags": ["form", "selection", "quiz"],
+      "useWhen": ["Composing individual answer choices inside a ChoiceGrid parent."],
+      "avoidWhen": [
+        {
+          "reason": "Used outside a ChoiceGrid — this leaf requires the parent context."
+        }
+      ],
+      "related": ["choice-grid"],
+      "hasConstraints": false,
+      "hasExamples": false,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/choice-grid-item/schema",
+        "variables": "@lostgradient/cinder/choice-grid-item/variables"
+      }
+    },
     {
       "name": "ClickAwayListener",
       "id": "click-away-listener",
@@ -638,7 +926,11 @@
       "useWhen": [
         "Building a custom inline-edit field, custom dropdown, or any overlay that should close on outside interaction."
       ],
-      "avoidWhen": ["Using Popover, Dropdown, or Modal — those handle click-away internally."],
+      "avoidWhen": [
+        {
+          "reason": "Using Popover, Dropdown, or Modal — those handle click-away internally."
+        }
+      ],
       "related": ["focus-trap", "popover", "portal"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -662,8 +954,12 @@
         "Letting the reader copy a snippet to the clipboard via the copyable prop."
       ],
       "avoidWhen": [
-        "Annotating a single inline keystroke or shortcut — use kbd instead.",
-        "Rendering rich prose that happens to include code — embed it in markdown instead."
+        {
+          "reason": "Annotating a single inline keystroke or shortcut — use kbd instead."
+        },
+        {
+          "reason": "Rendering rich prose that happens to include code — embed it in markdown instead."
+        }
       ],
       "related": ["kbd", "copy-button"],
       "hasConstraints": false,
@@ -688,7 +984,9 @@
         "You need controlled or uncontrolled show/hide with an accessible toggle."
       ],
       "avoidWhen": [
-        "Coordinating multiple sections where opening one may close others — use accordion."
+        {
+          "reason": "Coordinating multiple sections where opening one may close others — use accordion."
+        }
       ],
       "related": ["accordion", "accordion-item"],
       "hasConstraints": false,
@@ -713,8 +1011,12 @@
         "Pairing with color-picker for combined visual selection and text-based entry."
       ],
       "avoidWhen": [
-        "Letting users graze visually across a color space — use color-picker instead.",
-        "Constraining selection to a fixed brand palette — use color-swatch-picker instead."
+        {
+          "reason": "Letting users graze visually across a color space — use color-picker instead."
+        },
+        {
+          "reason": "Constraining selection to a fixed brand palette — use color-swatch-picker instead."
+        }
       ],
       "related": ["color-picker", "color-swatch-picker", "input", "form-field"],
       "hasConstraints": false,
@@ -739,7 +1041,9 @@
         "Composing a custom color with a fallback palette of preset swatches."
       ],
       "avoidWhen": [
-        "Constraining selection to a fixed brand palette — use color-swatch-picker instead."
+        {
+          "reason": "Constraining selection to a fixed brand palette — use color-swatch-picker instead."
+        }
       ],
       "related": ["color-swatch-picker", "input"],
       "hasConstraints": false,
@@ -764,7 +1068,9 @@
         "Pairing with color-picker as a shortcut for common values."
       ],
       "avoidWhen": [
-        "Letting users author arbitrary colors across the spectrum — use color-picker instead."
+        {
+          "reason": "Letting users author arbitrary colors across the spectrum — use color-picker instead."
+        }
       ],
       "related": ["color-picker"],
       "hasConstraints": false,
@@ -788,8 +1094,12 @@
         "Letting users narrow options by substring while still requiring a constrained selection."
       ],
       "avoidWhen": [
-        "Picking from a short fixed list with no need to filter — use select instead.",
-        "Querying remote data or accepting free-text submissions — use search-field instead."
+        {
+          "reason": "Picking from a short fixed list with no need to filter — use select instead."
+        },
+        {
+          "reason": "Querying remote data or accepting free-text submissions — use search-field instead."
+        }
       ],
       "related": ["select", "search-field", "dropdown"],
       "hasConstraints": false,
@@ -814,8 +1124,12 @@
         "Composing a custom palette layout via children rather than the items prop."
       ],
       "avoidWhen": [
-        "Used outside a command-palette or command-menu ancestor — the component throws at construction.",
-        "Rendering a generic dropdown choice — use dropdown-item instead."
+        {
+          "reason": "Used outside a command-palette or command-menu ancestor — the component throws at construction."
+        },
+        {
+          "reason": "Rendering a generic dropdown choice — use dropdown-item instead."
+        }
       ],
       "related": ["command-palette", "command-menu", "dropdown-item"],
       "hasConstraints": false,
@@ -839,8 +1153,12 @@
         "Building slash-command insertion flows where the host owns text replacement."
       ],
       "avoidWhen": [
-        "Exposing a global app launcher — use command-palette instead.",
-        "Selecting from a static form option list — use combobox instead."
+        {
+          "reason": "Exposing a global app launcher — use command-palette instead."
+        },
+        {
+          "reason": "Selecting from a static form option list — use combobox instead."
+        }
       ],
       "related": ["command-palette", "command-item", "popover", "combobox"],
       "hasConstraints": false,
@@ -865,8 +1183,12 @@
         "Letting users search across heterogeneous results such as commands, pages, and records in one input."
       ],
       "avoidWhen": [
-        "Picking a single value bound to a form field — use combobox instead.",
-        "Showing a contextual action menu attached to a trigger — use dropdown instead."
+        {
+          "reason": "Picking a single value bound to a form field — use combobox instead."
+        },
+        {
+          "reason": "Showing a contextual action menu attached to a trigger — use dropdown instead."
+        }
       ],
       "related": ["combobox", "dropdown", "command-item"],
       "hasConstraints": false,
@@ -891,8 +1213,12 @@
         "Asking the user to confirm a discrete decision with two clear outcomes."
       ],
       "avoidWhen": [
-        "Collecting structured input or multiple fields — compose a modal with form controls instead.",
-        "Announcing a non-blocking result — use toast-region or banner."
+        {
+          "reason": "Collecting structured input or multiple fields — compose a modal with form controls instead."
+        },
+        {
+          "reason": "Announcing a non-blocking result — use toast-region or banner."
+        }
       ],
       "related": ["modal", "drawer", "sheet"],
       "hasConstraints": false,
@@ -917,7 +1243,9 @@
         "Giving operators an at-a-glance health signal for a long-lived transport."
       ],
       "avoidWhen": [
-        "Communicating generic semantic state with no realtime connection backing it — status-dot is the lower-level primitive."
+        {
+          "reason": "Communicating generic semantic state with no realtime connection backing it — status-dot is the lower-level primitive."
+        }
       ],
       "related": ["status-dot", "spinner"],
       "hasConstraints": false,
@@ -941,7 +1269,9 @@
         "Constraining a section of a page to a named content width without app-shell chrome."
       ],
       "avoidWhen": [
-        "Building an app shell with header, breadcrumbs, or action regions — write a hand-rolled page scaffold directly."
+        {
+          "reason": "Building an app shell with header, breadcrumbs, or action regions — write a hand-rolled page scaffold directly."
+        }
       ],
       "related": ["aspect-ratio"],
       "hasConstraints": false,
@@ -966,8 +1296,12 @@
         "Opening a menu from a pointer location instead of a visible dropdown trigger."
       ],
       "avoidWhen": [
-        "The menu should open from a button — use dropdown.",
-        "Showing arbitrary rich content rather than menu actions — use popover."
+        {
+          "reason": "The menu should open from a button — use dropdown."
+        },
+        {
+          "reason": "Showing arbitrary rich content rather than menu actions — use popover."
+        }
       ],
       "related": ["dropdown", "dropdown-menu", "dropdown-item"],
       "hasConstraints": false,
@@ -992,8 +1326,12 @@
         "Pairing pointer-positioned menu behavior with dropdown menu items."
       ],
       "avoidWhen": [
-        "Used outside context-menu — it requires the ContextMenu provider.",
-        "Opening a normal click menu from a visible button — use dropdown-trigger."
+        {
+          "reason": "Used outside context-menu — it requires the ContextMenu provider."
+        },
+        {
+          "reason": "Opening a normal click menu from a visible button — use dropdown-trigger."
+        }
       ],
       "related": ["context-menu", "dropdown-trigger"],
       "hasConstraints": false,
@@ -1017,8 +1355,12 @@
         "Pairing with code-block so readers can grab the rendered source."
       ],
       "avoidWhen": [
-        "Triggering a generic non-clipboard action — use button instead.",
-        "Copying long-form rich content that needs format preservation — handle clipboard logic directly."
+        {
+          "reason": "Triggering a generic non-clipboard action — use button instead."
+        },
+        {
+          "reason": "Copying long-form rich content that needs format preservation — handle clipboard logic directly."
+        }
       ],
       "related": ["button", "code-block"],
       "hasConstraints": false,
@@ -1029,6 +1371,36 @@
         "examples": "@lostgradient/cinder/copy-button/examples"
       }
     },
+    {
+      "name": "DataGrid",
+      "id": "data-grid",
+      "import": "@lostgradient/cinder/data-grid",
+      "exportName": "DataGrid",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "ARIA data grid foundation for spreadsheet-like datasets with explicit row identity, column sizing, keyboard navigation, range selection, and pinning metadata.",
+      "tags": ["grid", "data", "spreadsheet"],
+      "useWhen": [
+        "Rendering interactive tabular data that will need grid behavior such as selection, virtualization, resizing, or editing.",
+        "You need role=grid semantics instead of native table semantics."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "You only need a semantic read-only table — use DataTable or the Table family instead."
+        },
+        {
+          "reason": "You need resize handles, drag-to-reorder controls, or editing today — DataGrid does not provide them yet."
+        }
+      ],
+      "related": ["data-table", "table"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/data-grid/schema",
+        "variables": "@lostgradient/cinder/data-grid/variables",
+        "examples": "@lostgradient/cinder/data-grid/examples"
+      }
+    },
     {
       "name": "DataList",
       "id": "data-list",
@@ -1044,8 +1416,12 @@
         "Showing a dedicated empty state when the collection has no items."
       ],
       "avoidWhen": [
-        "Presenting key-value metadata for a single entity — use description-list instead.",
-        "Rendering tabular data with rows and columns — use table instead."
+        {
+          "reason": "Presenting key-value metadata for a single entity — use description-list instead."
+        },
+        {
+          "reason": "Rendering tabular data with rows and columns — use table instead."
+        }
       ],
       "related": ["stacked-list-item", "description-list", "table"],
       "hasConstraints": false,
@@ -1056,6 +1432,73 @@
         "examples": "@lostgradient/cinder/data-list/examples"
       }
     },
+    {
+      "name": "DataTable",
+      "id": "data-table",
+      "import": "@lostgradient/cinder/data-table",
+      "exportName": "DataTable",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Data-driven convenience wrapper over the compositional Table family that renders a full semantic table from a columns array and a rows array.",
+      "tags": ["table", "data"],
+      "useWhen": [
+        "Rendering a structured dataset where columns and rows are known at runtime (e.g. API responses, config-driven dashboards).",
+        "You want correct scope=col / scope=row semantics and aria-sort wiring without writing Table.Header / Table.Body manually."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "You need custom cell rendering, interactive cells, nested components, or column spanning — use the compositional Table family directly."
+        },
+        {
+          "reason": "You need row selection — DataTable does not expose a selection prop; use Table with selectable instead."
+        }
+      ],
+      "related": [
+        "table",
+        "table-header",
+        "table-body",
+        "table-row",
+        "table-cell",
+        "table-header-cell"
+      ],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/data-table/schema",
+        "variables": "@lostgradient/cinder/data-table/variables",
+        "examples": "@lostgradient/cinder/data-table/examples"
+      }
+    },
+    {
+      "name": "DateRangeField",
+      "id": "date-range-field",
+      "import": "@lostgradient/cinder/date-range-field",
+      "exportName": "DateRangeField",
+      "category": "form",
+      "status": "stable",
+      "purpose": "Controlled start/end date range picker with preset shortcuts and validation feedback for time-window filtering.",
+      "tags": ["form", "date", "filter"],
+      "useWhen": [
+        "Filtering a list or dashboard by a start and end date (e.g. created between, updated between).",
+        "Offering common presets (last 7 days, last 24 hours) alongside a manual date range."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "A single date is sufficient — use a plain date input instead."
+        },
+        {
+          "reason": "Date-time precision (hours/minutes/timezone) is required — this v1 is date-only."
+        }
+      ],
+      "related": ["input", "form-field", "chip", "segmented-control"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/date-range-field/schema",
+        "variables": "@lostgradient/cinder/date-range-field/variables",
+        "examples": "@lostgradient/cinder/date-range-field/examples"
+      }
+    },
     {
       "name": "DescriptionList",
       "id": "description-list",
@@ -1070,7 +1513,9 @@
         "Switching between stacked and inline term layouts via the variant prop."
       ],
       "avoidWhen": [
-        "Iterating over a homogenous collection of records — use data-list or table instead."
+        {
+          "reason": "Iterating over a homogenous collection of records — use data-list or table instead."
+        }
       ],
       "related": ["data-list", "table"],
       "hasConstraints": false,
@@ -1095,8 +1540,12 @@
         "Annotating a list of files or pull requests with line-change counts as part of the diff-viewer suite."
       ],
       "avoidWhen": [
-        "Rendering the actual hunked diff content — pair with diff-viewer for the full document comparison.",
-        "Generic numeric badges that have nothing to do with diffs — reach for stat or badge instead."
+        {
+          "reason": "Rendering the actual hunked diff content — pair with diff-viewer for the full document comparison."
+        },
+        {
+          "reason": "Generic numeric badges that have nothing to do with diffs — reach for stat or badge instead."
+        }
       ],
       "related": ["diff-viewer"],
       "hasConstraints": false,
@@ -1121,8 +1570,12 @@
         "Building a review workflow that needs hunked, line-anchored Markdown diffs out of the box as a heavyweight suite."
       ],
       "avoidWhen": [
-        "Showing only a counts summary — use diff-statistics on its own for a lightweight presentation.",
-        "Diffing non-Markdown source code where syntax-aware highlighting matters more than prose-aware rendering."
+        {
+          "reason": "Showing only a counts summary — use diff-statistics on its own for a lightweight presentation."
+        },
+        {
+          "reason": "Diffing non-Markdown source code where syntax-aware highlighting matters more than prose-aware rendering."
+        }
       ],
       "related": ["diff-statistics", "code-block"],
       "hasConstraints": false,
@@ -1147,8 +1600,12 @@
         "Splitting a row of inline controls (e.g. a button-group toolbar) with a vertical rule."
       ],
       "avoidWhen": [
-        "The split between sections deserves a heading — use section-heading instead.",
-        "Wrapping the entire viewport edge — use surface or page-layout instead."
+        {
+          "reason": "The split between sections deserves a heading — use section-heading instead."
+        },
+        {
+          "reason": "Wrapping the entire viewport edge — use surface or a hand-rolled page scaffold instead."
+        }
       ],
       "related": ["surface", "section-heading"],
       "hasConstraints": false,
@@ -1173,8 +1630,12 @@
         "Presenting long-form content that benefits from a side panel without leaving the current view."
       ],
       "avoidWhen": [
-        "Interrupting the user for a focused decision — use modal so the surface is centered and task-scoped.",
-        "Anchoring a small surface to a trigger — use popover or sheet instead."
+        {
+          "reason": "Interrupting the user for a focused decision — use modal so the surface is centered and task-scoped."
+        },
+        {
+          "reason": "Anchoring a small surface to a trigger — use popover or sheet instead."
+        }
       ],
       "related": ["modal", "sheet", "popover"],
       "hasConstraints": false,
@@ -1199,8 +1660,12 @@
         "Building a custom dropdown layout from dropdown-trigger, dropdown-menu, dropdown-item, dropdown-label, and dropdown-separator parts."
       ],
       "avoidWhen": [
-        "Selecting a value from a list of options — use select or combobox instead.",
-        "Showing supplementary content rather than a menu of choices — use popover."
+        {
+          "reason": "Selecting a value from a list of options — use select or combobox instead."
+        },
+        {
+          "reason": "Showing supplementary content rather than a menu of choices — use popover."
+        }
       ],
       "related": [
         "dropdown-trigger",
@@ -1231,8 +1696,12 @@
         "Pairing dropdown-label with a role='group' container inside dropdown-menu."
       ],
       "avoidWhen": [
-        "Rendering a clickable row — use dropdown-item.",
-        "Separating sections without a group label — use dropdown-separator."
+        {
+          "reason": "Rendering a clickable row — use dropdown-item."
+        },
+        {
+          "reason": "Separating sections without a group label — use dropdown-separator."
+        }
       ],
       "related": [
         "dropdown",
@@ -1262,8 +1731,12 @@
         "Composing menu rows that should close the parent dropdown after selection unless closeOnSelect is disabled."
       ],
       "avoidWhen": [
-        "Used outside a dropdown context — it requires the dropdown provider and will throw otherwise.",
-        "Grouping a static heading row above menu items — use dropdown-label."
+        {
+          "reason": "Used outside a dropdown context — it requires the dropdown provider and will throw otherwise."
+        },
+        {
+          "reason": "Grouping a static heading row above menu items — use dropdown-label."
+        }
       ],
       "related": ["dropdown", "dropdown-menu", "dropdown-label", "dropdown-separator"],
       "hasConstraints": false,
@@ -1287,8 +1760,12 @@
         "Providing a visual section title above a cluster of dropdown-item rows."
       ],
       "avoidWhen": [
-        "Rendering a selectable row — use dropdown-item.",
-        "Visually dividing groups without a heading — use dropdown-separator."
+        {
+          "reason": "Rendering a selectable row — use dropdown-item."
+        },
+        {
+          "reason": "Visually dividing groups without a heading — use dropdown-separator."
+        }
       ],
       "related": ["dropdown", "dropdown-menu", "dropdown-item", "dropdown-separator"],
       "hasConstraints": false,
@@ -1312,8 +1789,12 @@
         "Composing a dropdown's body from dropdown-item, dropdown-label, and dropdown-separator children."
       ],
       "avoidWhen": [
-        "Used outside a dropdown context — it requires the dropdown provider and will throw otherwise.",
-        "Showing arbitrary non-menu content — use popover."
+        {
+          "reason": "Used outside a dropdown context — it requires the dropdown provider and will throw otherwise."
+        },
+        {
+          "reason": "Showing arbitrary non-menu content — use popover."
+        }
       ],
       "related": [
         "dropdown",
@@ -1343,8 +1824,12 @@
         "Marking a boundary between primary actions and destructive or secondary actions in a menu."
       ],
       "avoidWhen": [
-        "Labeling a section of items — use dropdown-label so the group has an accessible heading.",
-        "Rendering an interactive row — use dropdown-item."
+        {
+          "reason": "Labeling a section of items — use dropdown-label so the group has an accessible heading."
+        },
+        {
+          "reason": "Rendering an interactive row — use dropdown-item."
+        }
       ],
       "related": ["dropdown", "dropdown-menu", "dropdown-label", "dropdown-item"],
       "hasConstraints": false,
@@ -1367,7 +1852,11 @@
         "Opening a dropdown-menu from a button styled to match cinder's form controls.",
         "Pairing with dropdown to expose a custom menu from a labelled affordance."
       ],
-      "avoidWhen": ["Triggering a discrete action with no menu — use button instead."],
+      "avoidWhen": [
+        {
+          "reason": "Triggering a discrete action with no menu — use button instead."
+        }
+      ],
       "related": ["dropdown", "dropdown-menu"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -1390,8 +1879,12 @@
         "Replacing a primary content region after a filter or search returns no results."
       ],
       "avoidWhen": [
-        "Indicating that data is still loading — use skeleton or spinner instead.",
-        "Reporting a transient error — use alert, banner, or toast-region."
+        {
+          "reason": "Indicating that data is still loading — use skeleton or spinner instead."
+        },
+        {
+          "reason": "Reporting a transient error — use alert, banner, or toast-region."
+        }
       ],
       "related": ["skeleton", "spinner"],
       "hasConstraints": false,
@@ -1402,6 +1895,66 @@
         "examples": "@lostgradient/cinder/empty-state/examples"
       }
     },
+    {
+      "name": "EventStreamViewer",
+      "id": "event-stream-viewer",
+      "import": "@lostgradient/cinder/event-stream-viewer",
+      "exportName": "EventStreamViewer",
+      "category": "data-display",
+      "status": "beta",
+      "purpose": "Dense append-only log of timestamped events with follow-latest scrolling, severity tones, expandable JSON details, and copy actions.",
+      "tags": ["log", "stream", "events"],
+      "useWhen": [
+        "Displaying real-time or historical operational events such as workflow steps, job logs, or webhook traces.",
+        "Showing an append-only diagnostic stream with filtering, copy, and structured detail expansion."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Showing a social activity feed or notification timeline — use feed instead."
+        },
+        {
+          "reason": "Rendering paginated historical records with sorting — use data-table instead."
+        }
+      ],
+      "related": ["feed", "timeline", "json-viewer", "connection-indicator", "copy-button"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/event-stream-viewer/schema",
+        "variables": "@lostgradient/cinder/event-stream-viewer/variables",
+        "examples": "@lostgradient/cinder/event-stream-viewer/examples"
+      }
+    },
+    {
+      "name": "FacetedFilterBar",
+      "id": "faceted-filter-bar",
+      "import": "@lostgradient/cinder/faceted-filter-bar",
+      "exportName": "FacetedFilterBar",
+      "category": "form",
+      "status": "beta",
+      "purpose": "Composed filtering toolbar with search, select facets, applied-filter chips, and clear-all for dense operational list views.",
+      "tags": ["form", "filter"],
+      "useWhen": [
+        "Filtering a list or table by multiple dimensions such as status, category, and queue simultaneously.",
+        "Showing applied filters as removable chips so users can see and undo active constraints."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "A single search field or one select is sufficient — compose SearchField or Select directly."
+        },
+        {
+          "reason": "Filtering navigates to a new page — the bar owns no routing or persistence."
+        }
+      ],
+      "related": ["search-field", "chip", "select", "toolbar"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/faceted-filter-bar/schema",
+        "variables": "@lostgradient/cinder/faceted-filter-bar/variables",
+        "examples": "@lostgradient/cinder/faceted-filter-bar/examples"
+      }
+    },
     {
       "name": "Feed",
       "id": "feed",
@@ -1415,7 +1968,11 @@
         "Rendering an activity log, audit trail, or notification timeline.",
         "Announcing newly appended entries to assistive technology via the live prop."
       ],
-      "avoidWhen": ["Displaying a one-off transient notice — use toast-region or banner instead."],
+      "avoidWhen": [
+        {
+          "reason": "Displaying a one-off transient notice — use toast-region or banner instead."
+        }
+      ],
       "related": ["feed-event"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -1439,7 +1996,9 @@
         "Switching between an icon-led and a connector-led visual treatment via the variant prop."
       ],
       "avoidWhen": [
-        "Standing alone outside a feed — it expects the feed list semantics around it."
+        {
+          "reason": "Standing alone outside a feed — it expects the feed list semantics around it."
+        }
       ],
       "related": ["feed"],
       "hasConstraints": false,
@@ -1462,7 +2021,11 @@
         "Collecting one or more files while keeping the native picker available for keyboard and assistive-technology users.",
         "Showing per-file upload progress or rejection errors below a prominent dropzone surface."
       ],
-      "avoidWhen": ["You only need a hidden native file input with no custom UI."],
+      "avoidWhen": [
+        {
+          "reason": "You only need a hidden native file input with no custom UI."
+        }
+      ],
       "related": ["form-field", "progress", "input"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -1482,8 +2045,12 @@
       "tags": ["action", "button"],
       "useWhen": ["One action dominates the page purpose (compose, add, create)."],
       "avoidWhen": [
-        "Multiple equally-important actions exist — use a toolbar or button group.",
-        "You need it pinned to the viewport — it doesn't position itself; wrap it in your own fixed/sticky container."
+        {
+          "reason": "Multiple equally-important actions exist — use a toolbar or button group."
+        },
+        {
+          "reason": "You need it pinned to the viewport — it doesn't position itself; wrap it in your own fixed/sticky container."
+        }
       ],
       "related": ["button", "toolbar"],
       "hasConstraints": false,
@@ -1507,7 +2074,11 @@
         "Building non-native overlays or popovers that need contained keyboard focus.",
         "Reusing the same focus-management behavior across custom floating surfaces."
       ],
-      "avoidWhen": ["The surface already uses native dialog focus trapping."],
+      "avoidWhen": [
+        {
+          "reason": "The surface already uses native dialog focus trapping."
+        }
+      ],
       "related": ["modal", "drawer", "sheet", "popover"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -1531,7 +2102,9 @@
         "Forwarding shared required, disabled, and error state to an opted-in child control."
       ],
       "avoidWhen": [
-        "Grouping multiple related controls under one heading — use form-section instead."
+        {
+          "reason": "Grouping multiple related controls under one heading — use form-section instead."
+        }
       ],
       "related": ["form-section", "label", "input"],
       "hasConstraints": false,
@@ -1555,7 +2128,11 @@
         "Splitting a long form into labelled segments such as \"Account\" or \"Billing\".",
         "Rendering a fieldset with a legend for a set of tightly related inputs."
       ],
-      "avoidWhen": ["Wrapping a single control with its label and error — use form-field instead."],
+      "avoidWhen": [
+        {
+          "reason": "Wrapping a single control with its label and error — use form-field instead."
+        }
+      ],
       "related": ["form-field", "section-heading"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -1565,6 +2142,62 @@
         "examples": "@lostgradient/cinder/form-section/examples"
       }
     },
+    {
+      "name": "Grid",
+      "id": "grid",
+      "import": "@lostgradient/cinder/grid",
+      "exportName": "Grid",
+      "category": "layout",
+      "status": "beta",
+      "purpose": "CSS grid container for explicit columns, intrinsic auto-fill layouts, and two-dimensional placement.",
+      "tags": ["layout", "grid"],
+      "useWhen": [
+        "Building form layouts, card grids, or dashboards that need two-dimensional placement.",
+        "Creating intrinsic responsive grids by passing minItemWidth."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Presenting homogeneous gallery tiles - use grid-list instead.",
+          "alternative": "grid-list"
+        },
+        {
+          "reason": "Packing variable-height content into waterfall columns - use masonry instead.",
+          "alternative": "masonry"
+        }
+      ],
+      "related": ["grid-item", "grid-list", "masonry"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/grid/schema",
+        "variables": "@lostgradient/cinder/grid/variables",
+        "examples": "@lostgradient/cinder/grid/examples"
+      }
+    },
+    {
+      "name": "GridItem",
+      "id": "grid-item",
+      "import": "@lostgradient/cinder/grid-item",
+      "exportName": "GridItem",
+      "category": "layout",
+      "status": "beta",
+      "purpose": "Optional placement child for Grid that controls column and row spans or explicit track placement.",
+      "tags": ["layout", "grid"],
+      "useWhen": ["A child in a grid needs to span tracks or start at a specific track."],
+      "avoidWhen": [
+        {
+          "reason": "Every child can use default grid auto-placement - render plain children inside Grid instead.",
+          "alternative": "grid"
+        }
+      ],
+      "related": ["grid"],
+      "hasConstraints": false,
+      "hasExamples": false,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/grid-item/schema",
+        "variables": "@lostgradient/cinder/grid-item/variables"
+      }
+    },
     {
       "name": "GridList",
       "id": "grid-list",
@@ -1579,8 +2212,12 @@
         "Constraining tile minimum widths per breakpoint via the minColumnWidth prop."
       ],
       "avoidWhen": [
-        "Comparing rows of structured data — use table instead.",
-        "Stacking dense list rows vertically — use stacked-list-item instead."
+        {
+          "reason": "Comparing rows of structured data — use table instead."
+        },
+        {
+          "reason": "Stacking dense list rows vertically — use stacked-list-item instead."
+        }
       ],
       "related": ["grid-list-item", "table"],
       "hasConstraints": false,
@@ -1604,7 +2241,11 @@
         "Rendering a single card cell inside a grid-list parent.",
         "Turning the tile into an anchor by passing href."
       ],
-      "avoidWhen": ["Standing alone outside a grid-list — it inherits the grid layout context."],
+      "avoidWhen": [
+        {
+          "reason": "Standing alone outside a grid-list — it inherits the grid layout context."
+        }
+      ],
       "related": ["grid-list"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -1627,8 +2268,12 @@
         "Revealing supplementary preview content on pointer hover or keyboard focus without moving focus."
       ],
       "avoidWhen": [
-        "The floating content contains focusable controls — use popover.",
-        "The trigger needs a short accessible description — use tooltip."
+        {
+          "reason": "The floating content contains focusable controls — use popover."
+        },
+        {
+          "reason": "The trigger needs a short accessible description — use tooltip."
+        }
       ],
       "related": ["tooltip", "popover"],
       "hasConstraints": false,
@@ -1653,8 +2298,12 @@
         "Supplying a placeholder while loading and a fallback when the source errors."
       ],
       "avoidWhen": [
-        "Representing a person or account — use avatar instead.",
-        "Rendering a decorative icon — use an icon component instead."
+        {
+          "reason": "Representing a person or account — use avatar instead."
+        },
+        {
+          "reason": "Rendering a decorative icon — use an icon component instead."
+        }
       ],
       "related": ["avatar"],
       "hasConstraints": false,
@@ -1678,8 +2327,12 @@
         "Composing inside a form-field with leading or trailing adornments."
       ],
       "avoidWhen": [
-        "Collecting multi-line prose — use textarea instead.",
-        "Collecting a numeric value with stepping controls — use number-input instead."
+        {
+          "reason": "Collecting multi-line prose — use textarea instead."
+        },
+        {
+          "reason": "Collecting a numeric value with stepping controls — use number-input instead."
+        }
       ],
       "related": ["textarea", "number-input", "search-field", "form-field"],
       "hasConstraints": true,
@@ -1691,6 +2344,32 @@
         "constraints": "@lostgradient/cinder/input/constraints"
       }
     },
+    {
+      "name": "InvocationRuleBuilder",
+      "id": "invocation-rule-builder",
+      "import": "@lostgradient/cinder/invocation-rule-builder",
+      "exportName": "InvocationRuleBuilder",
+      "category": "form",
+      "status": "alpha",
+      "purpose": "Render and edit conditional automation rules composed of conditions and actions.",
+      "tags": ["automation", "rules"],
+      "useWhen": [
+        "Building a UI for configuring which agents or services run based on event conditions."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "You need to execute, validate, or persist rules — cinder owns none of that logic."
+        }
+      ],
+      "related": ["capability-gate", "steps", "review-editor"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/invocation-rule-builder/schema",
+        "variables": "@lostgradient/cinder/invocation-rule-builder/variables",
+        "examples": "@lostgradient/cinder/invocation-rule-builder/examples"
+      }
+    },
     {
       "name": "JsonSchemaEditor",
       "id": "json-schema-editor",
@@ -1705,7 +2384,9 @@
         "Reviewing schema changes against a baseline via the built-in diff view."
       ],
       "avoidWhen": [
-        "Editing arbitrary free-form JSON with no schema semantics — use a plain code editor instead."
+        {
+          "reason": "Editing arbitrary free-form JSON with no schema semantics — use a plain code editor instead."
+        }
       ],
       "related": ["markdown-editor", "review-editor"],
       "hasConstraints": false,
@@ -1730,15 +2411,20 @@
         "Rendering a JSON-serializable value with predictable initial-collapse behavior and no virtualization needs."
       ],
       "avoidWhen": [
-        "The payload is large enough to need search, filter, or virtualization — compose a custom viewer instead.",
-        "Showing arbitrary source code rather than a JSON value — code-block is the right surface for that."
+        {
+          "reason": "The payload is large enough to need search, filter, or virtualization — compose a custom viewer instead."
+        },
+        {
+          "reason": "Showing arbitrary source code rather than a JSON value — code-block is the right surface for that."
+        }
       ],
       "related": ["code-block", "tree"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/json-viewer/schema",
-        "variables": "@lostgradient/cinder/json-viewer/variables"
+        "variables": "@lostgradient/cinder/json-viewer/variables",
+        "examples": "@lostgradient/cinder/json-viewer/examples"
       }
     },
     {
@@ -1755,8 +2441,12 @@
         "Consumers own card rendering and need cinder to manage reorder affordances and change metadata."
       ],
       "avoidWhen": [
-        "Showing a single ordered list — use sortable-list instead.",
-        "Sorting by computed fields rather than direct manual placement."
+        {
+          "reason": "Showing a single ordered list — use sortable-list instead."
+        },
+        {
+          "reason": "Sorting by computed fields rather than direct manual placement."
+        }
       ],
       "related": ["sortable-list", "grid-list", "data-list"],
       "hasConstraints": false,
@@ -1780,7 +2470,11 @@
         "Calling out a keyboard shortcut inline within prose or a tooltip.",
         "Composing chorded shortcuts by rendering multiple kbd elements side by side."
       ],
-      "avoidWhen": ["Displaying a block of source code — use code-block instead."],
+      "avoidWhen": [
+        {
+          "reason": "Displaying a block of source code — use code-block instead."
+        }
+      ],
       "related": ["code-block"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -1790,6 +2484,33 @@
         "examples": "@lostgradient/cinder/kbd/examples"
       }
     },
+    {
+      "name": "KeyboardShortcuts",
+      "id": "keyboard-shortcuts",
+      "import": "@lostgradient/cinder/keyboard-shortcuts",
+      "exportName": "KeyboardShortcuts",
+      "category": "typography",
+      "status": "alpha",
+      "purpose": "Grouped keyboard-shortcut reference that renders key combos via Kbd with accessible labels not reliant only on visual keycaps.",
+      "tags": ["shortcut", "keyboard"],
+      "useWhen": [
+        "Displaying a reference panel of keyboard shortcuts grouped by feature area.",
+        "Embedding a shortcut table inside a modal, sheet, popover, or help page."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Showing a single inline shortcut hint — use shortcut-hint instead."
+        }
+      ],
+      "related": ["kbd", "shortcut-hint", "modal", "sheet", "popover"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/keyboard-shortcuts/schema",
+        "variables": "@lostgradient/cinder/keyboard-shortcuts/variables",
+        "examples": "@lostgradient/cinder/keyboard-shortcuts/examples"
+      }
+    },
     {
       "name": "Label",
       "id": "label",
@@ -1804,7 +2525,9 @@
         "Matching the disabled or required visual treatment of cinder inputs on a custom control."
       ],
       "avoidWhen": [
-        "Labelling a built-in input that already renders its own label prop — pass label instead."
+        {
+          "reason": "Labelling a built-in input that already renders its own label prop — pass label instead."
+        }
       ],
       "related": ["form-field", "input", "checkbox", "radio-group"],
       "hasConstraints": false,
@@ -1828,8 +2551,12 @@
         "Comparing several metric series on the same numeric axis."
       ],
       "avoidWhen": [
-        "Comparing discrete category totals — use bar-chart instead.",
-        "Showing cumulative filled trends — use area-chart instead."
+        {
+          "reason": "Comparing discrete category totals — use bar-chart instead."
+        },
+        {
+          "reason": "Showing cumulative filled trends — use area-chart instead."
+        }
       ],
       "related": ["area-chart", "bar-chart", "table", "stat"],
       "hasConstraints": false,
@@ -1850,7 +2577,11 @@
       "purpose": "Inline text link with consistent focus ring and underline behavior.",
       "tags": ["typography", "link"],
       "useWhen": ["Embedding a navigable link inside body text or prose content."],
-      "avoidWhen": ["Navigating between pages in a sidebar or nav bar — use NavigationItem."],
+      "avoidWhen": [
+        {
+          "reason": "Navigating between pages in a sidebar or nav bar — use NavigationItem."
+        }
+      ],
       "related": ["navigation-item", "button", "breadcrumbs"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -1873,7 +2604,9 @@
         "Streaming results into a long list and you want the next page to load as the user approaches the end."
       ],
       "avoidWhen": [
-        "The dataset is bounded and benefits from discrete jumps — use `Pagination` instead."
+        {
+          "reason": "The dataset is bounded and benefits from discrete jumps — use `Pagination` instead."
+        }
       ],
       "related": ["pagination"],
       "hasConstraints": false,
@@ -1898,8 +2631,12 @@
         "Building writing surfaces that need an editor handle for programmatic mark or block manipulation as part of the heavyweight suite."
       ],
       "avoidWhen": [
-        "Authoring a simple plain-text note — a textarea is dramatically lighter than the Milkdown bundle.",
-        "The surface needs inline review threads on top of the editor — use review-editor for that composition."
+        {
+          "reason": "Authoring a simple plain-text note — a textarea is dramatically lighter than the Milkdown bundle."
+        },
+        {
+          "reason": "The surface needs inline review threads on top of the editor — use review-editor for that composition."
+        }
       ],
       "related": ["review-editor", "code-block"],
       "hasConstraints": false,
@@ -1910,6 +2647,97 @@
         "examples": "@lostgradient/cinder/markdown-editor/examples"
       }
     },
+    {
+      "name": "Masonry",
+      "id": "masonry",
+      "import": "@lostgradient/cinder/masonry",
+      "exportName": "Masonry",
+      "category": "layout",
+      "status": "beta",
+      "purpose": "Pure CSS waterfall layout that packs variable-height children into balanced columns.",
+      "tags": ["layout", "masonry"],
+      "useWhen": [
+        "Displaying cards, images, or panels with uneven heights where CSS column order is acceptable."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Items have equal heights - use grid-list instead.",
+          "alternative": "grid-list"
+        },
+        {
+          "reason": "Left-to-right row reading order matters - use grid instead.",
+          "alternative": "grid"
+        }
+      ],
+      "related": ["grid", "grid-list"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/masonry/schema",
+        "variables": "@lostgradient/cinder/masonry/variables",
+        "examples": "@lostgradient/cinder/masonry/examples"
+      }
+    },
+    {
+      "name": "MatrixChart",
+      "id": "matrix-chart",
+      "import": "@lostgradient/cinder/matrix-chart",
+      "exportName": "MatrixChart",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Categorical × categorical heatmap for dense analytics, confusion matrices, and correlation grids.",
+      "tags": ["chart", "heatmap", "matrix", "analytics"],
+      "useWhen": [
+        "Showing density or magnitude across two categorical dimensions simultaneously.",
+        "Rendering a confusion matrix where rows are actual classes and columns are predicted classes."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Showing a continuous trend over time — use line-chart instead."
+        },
+        {
+          "reason": "Comparing discrete category totals — use bar-chart instead."
+        }
+      ],
+      "related": ["bar-chart", "line-chart", "area-chart"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/matrix-chart/schema",
+        "variables": "@lostgradient/cinder/matrix-chart/variables",
+        "examples": "@lostgradient/cinder/matrix-chart/examples"
+      }
+    },
+    {
+      "name": "MediaControls",
+      "id": "media-controls",
+      "import": "@lostgradient/cinder/media-controls",
+      "exportName": "MediaControls",
+      "category": "action",
+      "status": "alpha",
+      "purpose": "Accessible playback controls for play, pause, and replay actions with optional progress display.",
+      "tags": ["action", "media"],
+      "useWhen": [
+        "Embedding play/pause/replay controls for audio or video content.",
+        "Rendering media controls inside a toolbar or standalone on a card."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "You need waveform visualization or Web Audio integration — wire that separately."
+        },
+        {
+          "reason": "You need a full media player UI with seek scrubbing — use a dedicated player component."
+        }
+      ],
+      "related": ["button", "toolbar", "progress", "tooltip"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/media-controls/schema",
+        "variables": "@lostgradient/cinder/media-controls/variables",
+        "examples": "@lostgradient/cinder/media-controls/examples"
+      }
+    },
     {
       "name": "MenuBar",
       "id": "menu-bar",
@@ -1924,8 +2752,12 @@
         "Exposing top-level application menus that need arrow-key traversal and optional submenus."
       ],
       "avoidWhen": [
-        "Linking between routes or sections — use navigation-bar or side-navigation instead.",
-        "Showing one standalone trigger with a menu — use dropdown, dropdown-menu, and dropdown-item directly."
+        {
+          "reason": "Linking between routes or sections — use navigation-bar or side-navigation instead."
+        },
+        {
+          "reason": "Showing one standalone trigger with a menu — use dropdown, dropdown-menu, and dropdown-item directly."
+        }
       ],
       "related": ["navigation-bar", "dropdown", "dropdown-menu", "dropdown-item"],
       "hasConstraints": false,
@@ -1950,8 +2782,12 @@
         "Rendering AI agent runs, support threads, or audit logs where each entry has a speaker and a body."
       ],
       "avoidWhen": [
-        "Building a complete conversation surface with composer and scroll affordances — reach for the chat suite instead.",
-        "Communicating a single non-conversational notice — callout is more appropriate."
+        {
+          "reason": "Building a complete conversation surface with composer and scroll affordances — reach for the chat suite instead."
+        },
+        {
+          "reason": "Communicating a single non-conversational notice — callout is more appropriate."
+        }
       ],
       "related": ["chat", "callout"],
       "hasConstraints": false,
@@ -1976,10 +2812,18 @@
         "Collecting structured input (forms, multi-field workflows) inside an overlay."
       ],
       "avoidWhen": [
-        "Only a two-action confirm/cancel prompt is needed — use confirm-dialog instead.",
-        "An urgent blocking acknowledgement is needed — use alert-dialog instead.",
-        "Showing side-anchored navigation or settings — use a drawer instead.",
-        "Presenting a small contextual surface anchored to a trigger — use a popover or sheet instead."
+        {
+          "reason": "Only a two-action confirm/cancel prompt is needed — use confirm-dialog instead."
+        },
+        {
+          "reason": "An urgent blocking acknowledgement is needed — use alert-dialog instead."
+        },
+        {
+          "reason": "Showing side-anchored navigation or settings — use a drawer instead."
+        },
+        {
+          "reason": "Presenting a small contextual surface anchored to a trigger — use a popover or sheet instead."
+        }
       ],
       "related": ["confirm-dialog", "alert-dialog", "drawer", "sheet", "popover"],
       "hasConstraints": true,
@@ -2005,8 +2849,12 @@
         "Providing a responsive nav that collapses items behind a menu toggle below a breakpoint."
       ],
       "avoidWhen": [
-        "Showing the ancestor trail of the current page — use breadcrumbs instead.",
-        "Building a tall, dense sidebar of grouped sections — use side-navigation instead."
+        {
+          "reason": "Showing the ancestor trail of the current page — use breadcrumbs instead."
+        },
+        {
+          "reason": "Building a tall, dense sidebar of grouped sections — use side-navigation instead."
+        }
       ],
       "related": ["navigation-item", "breadcrumbs", "side-navigation"],
       "hasConstraints": false,
@@ -2031,8 +2879,12 @@
         "Switching the active view or section while signalling current location via aria-current."
       ],
       "avoidWhen": [
-        "Showing a hierarchical trail of ancestors — use breadcrumbs instead.",
-        "Triggering a generic action unrelated to navigation — use button instead."
+        {
+          "reason": "Showing a hierarchical trail of ancestors — use breadcrumbs instead."
+        },
+        {
+          "reason": "Triggering a generic action unrelated to navigation — use button instead."
+        }
       ],
       "related": ["navigation-bar", "side-navigation-item", "breadcrumbs", "tab"],
       "hasConstraints": false,
@@ -2056,8 +2908,12 @@
         "Needing locale-aware display formatting on top of a native number input."
       ],
       "avoidWhen": [
-        "Selecting a value within a continuous range visually — use slider instead.",
-        "Collecting free-form text or non-numeric content — use input instead."
+        {
+          "reason": "Selecting a value within a continuous range visually — use slider instead."
+        },
+        {
+          "reason": "Collecting free-form text or non-numeric content — use input instead."
+        }
       ],
       "related": ["input", "slider"],
       "hasConstraints": false,
@@ -2081,8 +2937,12 @@
         "Showing the current page in context of the total page count."
       ],
       "avoidWhen": [
-        "Switching between named sibling views — use tabs instead.",
-        "Streaming results as the user scrolls — wire up infinite scroll directly."
+        {
+          "reason": "Switching between named sibling views — use tabs instead."
+        },
+        {
+          "reason": "Streaming results as the user scrolls — wire up infinite scroll directly."
+        }
       ],
       "related": ["tabs"],
       "hasConstraints": false,
@@ -2093,6 +2953,66 @@
         "examples": "@lostgradient/cinder/pagination/examples"
       }
     },
+    {
+      "name": "PayloadInspector",
+      "id": "payload-inspector",
+      "import": "@lostgradient/cinder/payload-inspector",
+      "exportName": "PayloadInspector",
+      "category": "data-display",
+      "status": "beta",
+      "purpose": "Composed inspector for structured payloads with summary, tree, and raw views, copy actions, and size/truncation status.",
+      "tags": ["json", "inspector", "payload"],
+      "useWhen": [
+        "Inspecting workflow inputs, signal payloads, activity results, or API response bodies in a dashboard.",
+        "Displaying a structured payload with metadata like content type, source, and timestamp."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Rendering a raw code block only — use code-block directly instead."
+        },
+        {
+          "reason": "Needing search, filtering, or virtualization over large collections — compose a custom viewer."
+        }
+      ],
+      "related": ["json-viewer", "code-block", "description-list", "copy-button"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/payload-inspector/schema",
+        "variables": "@lostgradient/cinder/payload-inspector/variables",
+        "examples": "@lostgradient/cinder/payload-inspector/examples"
+      }
+    },
+    {
+      "name": "PermissionMatrix",
+      "id": "permission-matrix",
+      "import": "@lostgradient/cinder/permission-matrix",
+      "exportName": "PermissionMatrix",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Categorical permission matrix for scanning discrete access states across scopes and operations.",
+      "tags": ["matrix", "permission", "authorization", "table"],
+      "useWhen": [
+        "Showing whether scopes, roles, or policy categories grant specific operations.",
+        "Each cell represents a discrete state such as granted, denied, or not applicable."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Showing numeric density or magnitude across two categorical dimensions — use matrix-chart instead."
+        },
+        {
+          "reason": "Rendering editable permissions — use a purpose-built form or data-grid instead."
+        }
+      ],
+      "related": ["matrix-chart", "data-grid", "table"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/permission-matrix/schema",
+        "variables": "@lostgradient/cinder/permission-matrix/variables",
+        "examples": "@lostgradient/cinder/permission-matrix/examples"
+      }
+    },
     {
       "name": "PhoneInput",
       "id": "phone-input",
@@ -2107,8 +3027,12 @@
         "Letting the user pick a calling country and a national number side-by-side."
       ],
       "avoidWhen": [
-        "Collecting a free-form local number with no country context — use input type=\"tel\" instead.",
-        "Collecting an SMS verification code — use pin-input instead."
+        {
+          "reason": "Collecting a free-form local number with no country context — use input type=\"tel\" instead."
+        },
+        {
+          "reason": "Collecting an SMS verification code — use pin-input instead."
+        }
       ],
       "related": ["input", "pin-input", "form-field"],
       "hasConstraints": false,
@@ -2133,8 +3057,12 @@
         "Letting the browser autofill a one-time-code into a visually segmented control."
       ],
       "avoidWhen": [
-        "Collecting a free-form string of any length — use input instead.",
-        "Collecting a numeric value that participates in arithmetic — use number-input instead."
+        {
+          "reason": "Collecting a free-form string of any length — use input instead."
+        },
+        {
+          "reason": "Collecting a numeric value that participates in arithmetic — use number-input instead."
+        }
       ],
       "related": ["input", "number-input", "form-field"],
       "hasConstraints": false,
@@ -2159,8 +3087,12 @@
         "Presenting non-blocking supplementary controls that should dismiss on outside click or Escape."
       ],
       "avoidWhen": [
-        "Showing a short descriptive hint on hover or focus — use tooltip instead.",
-        "Interrupting the user for a focused task — use modal, drawer, or sheet so the surface is modal."
+        {
+          "reason": "Showing a short descriptive hint on hover or focus — use tooltip instead."
+        },
+        {
+          "reason": "Interrupting the user for a focused task — use modal, drawer, or sheet so the surface is modal."
+        }
       ],
       "related": ["modal", "drawer", "sheet", "tooltip"],
       "hasConstraints": false,
@@ -2185,7 +3117,9 @@
         "Building a custom anchored or modal primitive that needs to append content into document.body or a named host."
       ],
       "avoidWhen": [
-        "The content should stay in normal document flow or inherit layout from its original parent."
+        {
+          "reason": "The content should stay in normal document flow or inherit layout from its original parent."
+        }
       ],
       "related": ["popover", "modal", "drawer", "sheet"],
       "hasConstraints": false,
@@ -2196,6 +3130,36 @@
         "examples": "@lostgradient/cinder/portal/examples"
       }
     },
+    {
+      "name": "PricingCard",
+      "id": "pricing-card",
+      "import": "@lostgradient/cinder/pricing-card",
+      "exportName": "PricingCard",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Presents a single pricing plan with its name, price, feature list, and a call-to-action button.",
+      "tags": ["pricing", "plan"],
+      "useWhen": [
+        "Letting users compare and select subscription tiers or product plans.",
+        "Highlighting one tier as selected or recommended in a pricing comparison."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Showing generic grouped content without a distinct price or CTA — use card instead."
+        },
+        {
+          "reason": "Displaying a single key metric in isolation — use stat or stat-group instead."
+        }
+      ],
+      "related": ["card", "button", "stat", "stat-group"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/pricing-card/schema",
+        "variables": "@lostgradient/cinder/pricing-card/variables",
+        "examples": "@lostgradient/cinder/pricing-card/examples"
+      }
+    },
     {
       "name": "Progress",
       "id": "progress",
@@ -2210,8 +3174,12 @@
         "Showing an indeterminate work indicator when the task duration is unknown but the surface needs a progressbar role."
       ],
       "avoidWhen": [
-        "Showing a small inline busy state next to a control — use spinner.",
-        "Reserving placeholder space for incoming content — use skeleton."
+        {
+          "reason": "Showing a small inline busy state next to a control — use spinner."
+        },
+        {
+          "reason": "Reserving placeholder space for incoming content — use skeleton."
+        }
       ],
       "related": ["spinner", "skeleton"],
       "hasConstraints": false,
@@ -2235,7 +3203,11 @@
         "Picking exactly one option from a small fixed set where every choice should stay visible.",
         "Sharing a single error and description across a set of related radios."
       ],
-      "avoidWhen": ["Selecting zero or more independent options — use checkbox-group instead."],
+      "avoidWhen": [
+        {
+          "reason": "Selecting zero or more independent options — use checkbox-group instead."
+        }
+      ],
       "related": ["checkbox-group"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -2259,8 +3231,12 @@
         "Displaying an existing rating in readonly mode alongside a count or average."
       ],
       "avoidWhen": [
-        "Picking a value from a numeric continuum — use slider instead.",
-        "Capturing a binary preference — use toggle or checkbox."
+        {
+          "reason": "Picking a value from a numeric continuum — use slider instead."
+        },
+        {
+          "reason": "Capturing a binary preference — use toggle or checkbox."
+        }
       ],
       "related": ["slider", "segmented-control", "radio-group", "form-field"],
       "hasConstraints": false,
@@ -2285,8 +3261,12 @@
         "Persisting a multi-pane workspace layout without coupling the component to localStorage."
       ],
       "avoidWhen": [
-        "You only need a static two-column or stack layout with no interactive resizing.",
-        "Content should wrap naturally instead of claiming a fixed share of a measured container."
+        {
+          "reason": "You only need a static two-column or stack layout with no interactive resizing."
+        },
+        {
+          "reason": "Content should wrap naturally instead of claiming a fixed share of a measured container."
+        }
       ],
       "related": ["divider", "scroll-area"],
       "hasConstraints": false,
@@ -2311,8 +3291,12 @@
         "Threading reviewer commentary against specific selections inside a long-form document."
       ],
       "avoidWhen": [
-        "Plain authoring with no review threads — markdown-editor is the lighter primitive.",
-        "Reviewing diffs between two documents rather than annotating one — use diff-viewer instead."
+        {
+          "reason": "Plain authoring with no review threads — markdown-editor is the lighter primitive."
+        },
+        {
+          "reason": "Reviewing diffs between two documents rather than annotating one — use diff-viewer instead."
+        }
       ],
       "related": ["markdown-editor"],
       "hasConstraints": false,
@@ -2323,6 +3307,78 @@
         "examples": "@lostgradient/cinder/review-editor/examples"
       }
     },
+    {
+      "name": "RunStepTimeline",
+      "id": "run-step-timeline",
+      "import": "@lostgradient/cinder/run-step-timeline",
+      "exportName": "RunStepTimeline",
+      "category": "data-display",
+      "status": "stable",
+      "purpose": "Ordered step-by-step execution rail that visualizes async run state with per-step status, durations, retries, optional progress, and expandable detail panels.",
+      "tags": ["timeline", "progress", "execution"],
+      "useWhen": [
+        "Displaying the live or completed state of a multi-step async operation: CI jobs, workflow runs, import pipelines, or deployments.",
+        "Showing a sequence where one step is currently active and prior steps have streamed in over time."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Guiding users through an interactive wizard where they choose what to do next — use steps instead."
+        },
+        {
+          "reason": "Showing a flat timestamp-first event log without structured step state — use timeline instead."
+        }
+      ],
+      "related": ["timeline", "steps", "status-dot", "progress", "badge", "collapsible"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/run-step-timeline/schema",
+        "variables": "@lostgradient/cinder/run-step-timeline/variables",
+        "examples": "@lostgradient/cinder/run-step-timeline/examples"
+      }
+    },
+    {
+      "name": "SchemaForm",
+      "id": "schema-form",
+      "import": "@lostgradient/cinder/schema-form",
+      "exportName": "SchemaForm",
+      "category": "form",
+      "status": "beta",
+      "purpose": "Schema-driven form that renders accessible controls from JSON Schema or Standard Schema and submits one validated value object.",
+      "tags": ["form", "schema", "validation"],
+      "useWhen": [
+        "Capturing a payload whose shape is already described by a workflow, API, or Standard Schema validator.",
+        "You need callback submission and native FormData submission to expose the same validated object."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Authoring or editing a JSON Schema document — use json-schema-editor instead."
+        },
+        {
+          "reason": "You need bespoke multi-step flows or custom cross-field user interface beyond schema validation."
+        }
+      ],
+      "related": ["json-schema-editor", "form-field", "input", "select", "toggle"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/schema-form/schema",
+        "variables": "@lostgradient/cinder/schema-form/variables",
+        "examples": "@lostgradient/cinder/schema-form/examples"
+      },
+      "a11y": {
+        "pattern": "Native HTML form with labelled controls",
+        "keyboard": [
+          {
+            "keys": "Enter",
+            "action": "Submits the form from text-like controls."
+          }
+        ],
+        "notes": [
+          "Invalid submission moves focus to the first invalid field and associates each field error through aria-describedby."
+        ]
+      }
+    },
     {
       "name": "ScrollArea",
       "id": "scroll-area",
@@ -2337,8 +3393,12 @@
         "Preserving keyboard scrollability for overflow content in a card or surface."
       ],
       "avoidWhen": [
-        "Wrapping the entire page — let the document scroll natively.",
-        "Hiding overflow without scrollbars — use plain CSS overflow utilities instead."
+        {
+          "reason": "Wrapping the entire page — let the document scroll natively."
+        },
+        {
+          "reason": "Hiding overflow without scrollbars — use plain CSS overflow utilities instead."
+        }
       ],
       "related": ["surface"],
       "hasConstraints": false,
@@ -2362,13 +3422,48 @@
         "Capturing a free-text query that filters or queries a larger dataset.",
         "Surfacing a global search affordance with a visible keyboard shortcut."
       ],
-      "avoidWhen": ["Selecting from a constrained list of known options — use combobox instead."],
+      "avoidWhen": [
+        {
+          "reason": "Selecting from a constrained list of known options — use combobox instead."
+        }
+      ],
       "related": ["input", "combobox"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/search-field/schema",
-        "variables": "@lostgradient/cinder/search-field/variables"
+        "variables": "@lostgradient/cinder/search-field/variables",
+        "examples": "@lostgradient/cinder/search-field/examples"
+      }
+    },
+    {
+      "name": "SecretValueField",
+      "id": "secret-value-field",
+      "import": "@lostgradient/cinder/secret-value-field",
+      "exportName": "SecretValueField",
+      "category": "data-display",
+      "status": "beta",
+      "purpose": "Displays a masked secret (API key, token, webhook secret) with copy action and optional reveal toggle.",
+      "tags": ["clipboard", "security"],
+      "useWhen": [
+        "Showing a newly-created API key or token that the user must copy before it is gone.",
+        "Displaying an existing masked key in a settings table where the full value should stay hidden."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "The value is not sensitive and can be shown as plain text — use a code or input component."
+        },
+        {
+          "reason": "You need inline editing of the secret value — use a password input instead."
+        }
+      ],
+      "related": ["copy-button", "input", "badge"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/secret-value-field/schema",
+        "variables": "@lostgradient/cinder/secret-value-field/variables",
+        "examples": "@lostgradient/cinder/secret-value-field/examples"
       }
     },
     {
@@ -2385,8 +3480,12 @@
         "Pairing a section title with inline actions or a tab row beneath the heading."
       ],
       "avoidWhen": [
-        "Labelling a single form control or field — use label instead.",
-        "Rendering a page-wide header with primary navigation — use a hand-rolled page scaffold with a heading element."
+        {
+          "reason": "Labelling a single form control or field — use label instead."
+        },
+        {
+          "reason": "Rendering a page-wide header with primary navigation — use a hand-rolled page scaffold with a heading element."
+        }
       ],
       "related": ["card", "tab-list"],
       "hasConstraints": false,
@@ -2411,8 +3510,12 @@
         "Mixing disabled and enabled segments inside a single radiogroup/tablist where each segment carries its own metadata."
       ],
       "avoidWhen": [
-        "Building a standalone toggle button — use Button or Toggle instead.",
-        "Selecting one option from a long list — use Select or Combobox instead."
+        {
+          "reason": "Building a standalone toggle button — use Button or Toggle instead."
+        },
+        {
+          "reason": "Selecting one option from a long list — use Select or Combobox instead."
+        }
       ],
       "related": ["segmented-control", "button", "toggle"],
       "hasConstraints": false,
@@ -2436,8 +3539,12 @@
         "Picking a view filter where seeing every option beats hiding them inside a toggle or tabs control."
       ],
       "avoidWhen": [
-        "Toggling a single binary on or off — use toggle or checkbox instead.",
-        "Switching between panels of associated content — use tabs instead."
+        {
+          "reason": "Toggling a single binary on or off — use toggle or checkbox instead."
+        },
+        {
+          "reason": "Switching between panels of associated content — use tabs instead."
+        }
       ],
       "related": ["toggle", "checkbox", "tabs", "button-group"],
       "hasConstraints": false,
@@ -2462,8 +3569,12 @@
         "Composing inside a form with built-in label and aria-describedby plumbing."
       ],
       "avoidWhen": [
-        "Filtering a long list by typing — use combobox instead.",
-        "Building a custom-styled menu trigger — use dropdown instead."
+        {
+          "reason": "Filtering a long list by typing — use combobox instead."
+        },
+        {
+          "reason": "Building a custom-styled menu trigger — use dropdown instead."
+        }
       ],
       "related": ["combobox", "dropdown", "radio-group"],
       "hasConstraints": false,
@@ -2488,8 +3599,12 @@
         "Surfacing selection-scoped actions such as quote, share, or comment near the user's pointer."
       ],
       "avoidWhen": [
-        "Anchoring generic non-selection content to a trigger — use popover.",
-        "Building a general-purpose floating toolbar unrelated to text selection — compose a popover with custom controls."
+        {
+          "reason": "Anchoring generic non-selection content to a trigger — use popover."
+        },
+        {
+          "reason": "Building a general-purpose floating toolbar unrelated to text selection — compose a popover with custom controls."
+        }
       ],
       "related": ["popover"],
       "hasConstraints": false,
@@ -2500,6 +3615,36 @@
         "examples": "@lostgradient/cinder/selection-popover/examples"
       }
     },
+    {
+      "name": "ShareCard",
+      "id": "share-card",
+      "import": "@lostgradient/cinder/share-card",
+      "exportName": "ShareCard",
+      "category": "action",
+      "status": "alpha",
+      "purpose": "Compact share card with copy-link, copy-text, and native navigator.share actions, with accessible success announcements and graceful fallback when navigator.share is unavailable.",
+      "tags": ["action", "clipboard"],
+      "useWhen": [
+        "Offering a quick way to share a link or text with copy and native share options.",
+        "Presenting a result, invite link, or exported report link with sharing affordances."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Generating the share text or images — compose ShareCard with your own copy generation logic."
+        },
+        {
+          "reason": "Posting directly to social media or analytics — wire those externally."
+        }
+      ],
+      "related": ["copy-button", "card", "button"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/share-card/schema",
+        "variables": "@lostgradient/cinder/share-card/variables",
+        "examples": "@lostgradient/cinder/share-card/examples"
+      }
+    },
     {
       "name": "Sheet",
       "id": "sheet",
@@ -2514,8 +3659,12 @@
         "Showing a contextual surface that should feel anchored to the screen edge rather than centered like a modal."
       ],
       "avoidWhen": [
-        "Interrupting the user with a centered task or confirmation — use modal instead.",
-        "Showing supplementary side navigation or filters — use drawer or popover."
+        {
+          "reason": "Interrupting the user with a centered task or confirmation — use modal instead."
+        },
+        {
+          "reason": "Showing supplementary side navigation or filters — use drawer or popover."
+        }
       ],
       "related": ["modal", "drawer", "popover"],
       "hasConstraints": false,
@@ -2526,6 +3675,33 @@
         "examples": "@lostgradient/cinder/sheet/examples"
       }
     },
+    {
+      "name": "ShortcutHint",
+      "id": "shortcut-hint",
+      "import": "@lostgradient/cinder/shortcut-hint",
+      "exportName": "ShortcutHint",
+      "category": "typography",
+      "status": "alpha",
+      "purpose": "Inline shortcut hint that renders a key combo via Kbd alongside an action label, with an accessible text representation not reliant on visual keycaps alone.",
+      "tags": ["shortcut", "inline"],
+      "useWhen": [
+        "Showing a keyboard shortcut inline beside a label in a toolbar button, menu item, or tooltip.",
+        "Pairing with command-palette items to surface available shortcuts."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Displaying a full shortcut reference table — use keyboard-shortcuts instead."
+        }
+      ],
+      "related": ["kbd", "keyboard-shortcuts", "tooltip"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/shortcut-hint/schema",
+        "variables": "@lostgradient/cinder/shortcut-hint/variables",
+        "examples": "@lostgradient/cinder/shortcut-hint/examples"
+      }
+    },
     {
       "name": "SideNavigation",
       "id": "side-navigation",
@@ -2540,8 +3716,12 @@
         "Pairing with sidebar so the column collapses responsively on narrow viewports."
       ],
       "avoidWhen": [
-        "Anchoring primary navigation across the top of the page — use navigation-bar instead.",
-        "Rendering a single flat horizontal nav row — use navigation-bar instead."
+        {
+          "reason": "Anchoring primary navigation across the top of the page — use navigation-bar instead."
+        },
+        {
+          "reason": "Rendering a single flat horizontal nav row — use navigation-bar instead."
+        }
       ],
       "related": ["side-navigation-item", "side-navigation-group", "navigation-bar", "sidebar"],
       "hasConstraints": false,
@@ -2566,8 +3746,12 @@
         "Letting users collapse rarely used groups to reduce visual noise in the sidebar."
       ],
       "avoidWhen": [
-        "Used outside a side-navigation ancestor — it expects that landmark for context.",
-        "Hosting a single flat list with no grouping — place side-navigation-item entries directly."
+        {
+          "reason": "Used outside a side-navigation ancestor — it expects that landmark for context."
+        },
+        {
+          "reason": "Hosting a single flat list with no grouping — place side-navigation-item entries directly."
+        }
       ],
       "related": ["side-navigation", "side-navigation-item"],
       "hasConstraints": false,
@@ -2591,8 +3775,12 @@
         "Keeping list semantics correct so screen readers announce sidebar entry counts."
       ],
       "avoidWhen": [
-        "Placing entries in a horizontal navigation-bar — use navigation-item directly.",
-        "Rendering outside a side-navigation list — use navigation-item without the list wrapper."
+        {
+          "reason": "Placing entries in a horizontal navigation-bar — use navigation-item directly."
+        },
+        {
+          "reason": "Rendering outside a side-navigation list — use navigation-item without the list wrapper."
+        }
       ],
       "related": ["side-navigation", "side-navigation-group", "navigation-item"],
       "hasConstraints": false,
@@ -2616,8 +3804,12 @@
         "Sharing collapsed state between a side-navigation column and the rest of the app shell via context."
       ],
       "avoidWhen": [
-        "Building the page body itself rather than the surrounding shell — use a hand-rolled page scaffold instead.",
-        "Rendering navigation entries directly — place side-navigation inside the sidebar column."
+        {
+          "reason": "Building the page body itself rather than the surrounding shell — use a hand-rolled page scaffold instead."
+        },
+        {
+          "reason": "Rendering navigation entries directly — place side-navigation inside the sidebar column."
+        }
       ],
       "related": ["side-navigation", "drawer"],
       "hasConstraints": false,
@@ -2642,8 +3834,12 @@
         "Indicating progressive load of cards, rows, or media tiles where the final shape is known."
       ],
       "avoidWhen": [
-        "Indicating indeterminate background work without a known target shape — use spinner.",
-        "Communicating that a view has no data at all — use empty-state."
+        {
+          "reason": "Indicating indeterminate background work without a known target shape — use spinner."
+        },
+        {
+          "reason": "Communicating that a view has no data at all — use empty-state."
+        }
       ],
       "related": ["spinner", "empty-state", "progress"],
       "hasConstraints": false,
@@ -2654,6 +3850,36 @@
         "examples": "@lostgradient/cinder/skeleton/examples"
       }
     },
+    {
+      "name": "SkipLink",
+      "id": "skip-link",
+      "import": "@lostgradient/cinder/skip-link",
+      "exportName": "SkipLink",
+      "category": "navigation",
+      "status": "stable",
+      "purpose": "Visually hidden skip link that moves keyboard focus to a landmark element, letting keyboard and screen reader users bypass repeated navigation.",
+      "tags": ["navigation", "accessibility", "skip-link"],
+      "useWhen": [
+        "Providing a keyboard shortcut to jump past site-wide navigation directly to the main content area.",
+        "Meeting WCAG 2.4.1 (Bypass Blocks) without adding visible chrome to the layout."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "The page has no repeated navigation block — a skip link adds no value on single-panel layouts."
+        },
+        {
+          "reason": "The target region already receives focus naturally without intervention."
+        }
+      ],
+      "related": ["visually-hidden"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/skip-link/schema",
+        "variables": "@lostgradient/cinder/skip-link/variables",
+        "examples": "@lostgradient/cinder/skip-link/examples"
+      }
+    },
     {
       "name": "Slider",
       "id": "slider",
@@ -2668,8 +3894,12 @@
         "Selecting a low and high bound together via the range mode."
       ],
       "avoidWhen": [
-        "Entering a precise numeric value typed by the user — use number-input instead.",
-        "Displaying read-only completion — use progress instead."
+        {
+          "reason": "Entering a precise numeric value typed by the user — use number-input instead."
+        },
+        {
+          "reason": "Displaying read-only completion — use progress instead."
+        }
       ],
       "related": ["number-input", "progress"],
       "hasConstraints": false,
@@ -2694,8 +3924,12 @@
         "Surfacing live region announcements during a reorder for accessible feedback."
       ],
       "avoidWhen": [
-        "Showing a read-only list with no reorder affordance — use grid-list instead.",
-        "Sorting by a column or computed key — sort the source array and rerender."
+        {
+          "reason": "Showing a read-only list with no reorder affordance — use grid-list instead."
+        },
+        {
+          "reason": "Sorting by a column or computed key — sort the source array and rerender."
+        }
       ],
       "related": ["grid-list"],
       "hasConstraints": false,
@@ -2705,6 +3939,127 @@
         "variables": "@lostgradient/cinder/sortable-list/variables"
       }
     },
+    {
+      "name": "Spectrogram",
+      "id": "spectrogram",
+      "import": "@lostgradient/cinder/spectrogram",
+      "exportName": "Spectrogram",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Responsive SVG time × frequency heatmap for visualizing audio spectrogram data.",
+      "tags": ["chart", "spectrogram", "signal", "audio"],
+      "useWhen": [
+        "Visualizing how frequency content of a signal changes over time (time × frequency heatmap).",
+        "Displaying pre-computed spectrogram frames from an FFT or short-time Fourier transform."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Only a single spectrum snapshot is needed — use spectrum-chart instead."
+        },
+        {
+          "reason": "Real-time live audio spectrogram is needed — feed frames as props yourself."
+        },
+        {
+          "reason": "A categorical × categorical heatmap without a time axis is needed — use matrix-chart instead."
+        }
+      ],
+      "related": ["spectrum-chart", "waveform", "matrix-chart"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/spectrogram/schema",
+        "variables": "@lostgradient/cinder/spectrogram/variables",
+        "examples": "@lostgradient/cinder/spectrogram/examples"
+      }
+    },
+    {
+      "name": "SpectrumChart",
+      "id": "spectrum-chart",
+      "import": "@lostgradient/cinder/spectrum-chart",
+      "exportName": "SpectrumChart",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Responsive SVG frequency-bin bar chart for visualizing audio spectrum magnitude data.",
+      "tags": ["chart", "spectrum", "signal", "audio"],
+      "useWhen": [
+        "Displaying pre-computed frequency-domain magnitude data from an FFT or spectrum analyzer.",
+        "Showing a static frequency response or spectrum snapshot with labelled frequency bins."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Real-time live audio spectrum is needed — feed live AnalyserNode data as props yourself."
+        },
+        {
+          "reason": "A full time × frequency heatmap is needed — use spectrogram instead."
+        },
+        {
+          "reason": "General categorical bar comparison — use bar-chart instead."
+        }
+      ],
+      "related": ["waveform", "spectrogram", "bar-chart"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/spectrum-chart/schema",
+        "variables": "@lostgradient/cinder/spectrum-chart/variables",
+        "examples": "@lostgradient/cinder/spectrum-chart/examples"
+      }
+    },
+    {
+      "name": "SpeedDial",
+      "id": "speed-dial",
+      "import": "@lostgradient/cinder/speed-dial",
+      "exportName": "SpeedDial",
+      "category": "action",
+      "status": "beta",
+      "purpose": "Floating action cluster that reveals secondary quick actions around a primary FloatingActionButton trigger.",
+      "tags": ["action", "floating"],
+      "useWhen": [
+        "One primary floating action needs a small set of closely related quick actions."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "The actions are equally important and always visible - use toolbar instead.",
+          "alternative": "toolbar"
+        },
+        {
+          "reason": "The trigger should open rich contextual content - use popover instead.",
+          "alternative": "popover"
+        }
+      ],
+      "related": ["floating-action-button", "toolbar", "popover"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/speed-dial/schema",
+        "variables": "@lostgradient/cinder/speed-dial/variables",
+        "examples": "@lostgradient/cinder/speed-dial/examples"
+      }
+    },
+    {
+      "name": "SpeedDialAction",
+      "id": "speed-dial-action",
+      "import": "@lostgradient/cinder/speed-dial-action",
+      "exportName": "SpeedDialAction",
+      "category": "action",
+      "status": "beta",
+      "purpose": "Quick-action leaf for SpeedDial that closes the owning dial after activation.",
+      "tags": ["action", "floating"],
+      "useWhen": ["Rendering a secondary quick action inside SpeedDial."],
+      "avoidWhen": [
+        {
+          "reason": "Rendering an action outside SpeedDial - use floating-action-button directly.",
+          "alternative": "floating-action-button"
+        }
+      ],
+      "related": ["speed-dial", "floating-action-button"],
+      "hasConstraints": false,
+      "hasExamples": false,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/speed-dial-action/schema",
+        "variables": "@lostgradient/cinder/speed-dial-action/variables"
+      }
+    },
     {
       "name": "Spinner",
       "id": "spinner",
@@ -2719,8 +4074,12 @@
         "Indicating inline busy state next to a control while a request resolves."
       ],
       "avoidWhen": [
-        "Reserving layout space for content with a known final shape — use skeleton.",
-        "Reporting determinate progress with a measurable percentage — use progress."
+        {
+          "reason": "Reserving layout space for content with a known final shape — use skeleton."
+        },
+        {
+          "reason": "Reporting determinate progress with a measurable percentage — use progress."
+        }
       ],
       "related": ["skeleton", "progress"],
       "hasConstraints": false,
@@ -2745,15 +4104,20 @@
         "Linking each row to a detail view by passing href."
       ],
       "avoidWhen": [
-        "Comparing tabular data across columns — use table instead.",
-        "Rendering cards in a responsive grid — use grid-list instead."
+        {
+          "reason": "Comparing tabular data across columns — use table instead."
+        },
+        {
+          "reason": "Rendering cards in a responsive grid — use grid-list instead."
+        }
       ],
       "related": ["grid-list-item", "table-row", "avatar"],
       "hasConstraints": false,
-      "hasExamples": false,
+      "hasExamples": true,
       "artifacts": {
         "schema": "@lostgradient/cinder/stacked-list-item/schema",
-        "variables": "@lostgradient/cinder/stacked-list-item/variables"
+        "variables": "@lostgradient/cinder/stacked-list-item/variables",
+        "examples": "@lostgradient/cinder/stacked-list-item/examples"
       }
     },
     {
@@ -2770,8 +4134,12 @@
         "Composing a dashboard tile alongside other Stat instances inside stat-group."
       ],
       "avoidWhen": [
-        "Conveying status with a short label or icon — use badge instead.",
-        "Showing tabular numeric breakdowns — use table or data-list instead."
+        {
+          "reason": "Conveying status with a short label or icon — use badge instead."
+        },
+        {
+          "reason": "Showing tabular numeric breakdowns — use table or data-list instead."
+        }
       ],
       "related": ["stat-group", "badge"],
       "hasConstraints": false,
@@ -2795,8 +4163,12 @@
         "Giving a cluster of stat entries a single accessible group label."
       ],
       "avoidWhen": [
-        "Rendering exactly one metric — use stat on its own.",
-        "Building a freeform card grid unrelated to numeric metrics — compose surface or grid-list directly."
+        {
+          "reason": "Rendering exactly one metric — use stat on its own."
+        },
+        {
+          "reason": "Building a freeform card grid unrelated to numeric metrics — compose surface or grid-list directly."
+        }
       ],
       "related": ["stat"],
       "hasConstraints": false,
@@ -2821,8 +4193,12 @@
         "Communicating status compactly when many indicators appear together without triggering live-region announcements."
       ],
       "avoidWhen": [
-        "Counting items or showing a numeric value — use badge instead.",
-        "Announcing a transient status change — use toast-region or alert so assistive tech reads it."
+        {
+          "reason": "Counting items or showing a numeric value — use badge instead."
+        },
+        {
+          "reason": "Announcing a transient status change — use toast-region or alert so assistive tech reads it."
+        }
       ],
       "related": ["badge"],
       "hasConstraints": false,
@@ -2847,8 +4223,12 @@
         "Showing how far the user has advanced through a known number of stages."
       ],
       "avoidWhen": [
-        "Switching between independent peer views with no order — use tabs instead.",
-        "Showing ancestor hierarchy of the current page — use breadcrumbs instead."
+        {
+          "reason": "Switching between independent peer views with no order — use tabs instead."
+        },
+        {
+          "reason": "Showing ancestor hierarchy of the current page — use breadcrumbs instead."
+        }
       ],
       "related": ["tabs", "breadcrumbs", "pagination"],
       "hasConstraints": false,
@@ -2859,6 +4239,36 @@
         "examples": "@lostgradient/cinder/steps/examples"
       }
     },
+    {
+      "name": "SubscriptionBadge",
+      "id": "subscription-badge",
+      "import": "@lostgradient/cinder/subscription-badge",
+      "exportName": "SubscriptionBadge",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Opinionated Badge variant that communicates billing subscription states with a standardized tone, icon, and human-readable label.",
+      "tags": ["billing", "subscription", "status"],
+      "useWhen": [
+        "Displaying the billing state of a subscription in a dashboard, invoice list, or account settings page.",
+        "Annotating a plan name, customer row, or invoice line with its current payment lifecycle state."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "The subscription state is not one of the six recognized values — use Badge directly with a custom label instead."
+        },
+        {
+          "reason": "You need an interactive control that lets users change the state — use a Button or Select."
+        }
+      ],
+      "related": ["badge", "status-dot", "chip"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/subscription-badge/schema",
+        "variables": "@lostgradient/cinder/subscription-badge/variables",
+        "examples": "@lostgradient/cinder/subscription-badge/examples"
+      }
+    },
     {
       "name": "Surface",
       "id": "surface",
@@ -2873,8 +4283,12 @@
         "Letting nested components adapt their styling based on the surrounding surface tone."
       ],
       "avoidWhen": [
-        "Building a self-contained content card with padding and elevation — use card instead.",
-        "Standing up a full page scaffold with header and actions — use a hand-rolled page scaffold instead."
+        {
+          "reason": "Building a self-contained content card with padding and elevation — use card instead."
+        },
+        {
+          "reason": "Standing up a full page scaffold with header and actions — use a hand-rolled page scaffold instead."
+        }
       ],
       "related": ["card"],
       "hasConstraints": false,
@@ -2899,8 +4313,12 @@
         "Pairing one-to-one with a tab-panel that shares the same value to wire aria-controls."
       ],
       "avoidWhen": [
-        "Used outside a tabs ancestor — the component throws at construction.",
-        "Rendering a generic action button — use button instead."
+        {
+          "reason": "Used outside a tabs ancestor — the component throws at construction."
+        },
+        {
+          "reason": "Rendering a generic action button — use button instead."
+        }
       ],
       "related": ["tabs", "tab-list", "tab-panel"],
       "hasConstraints": false,
@@ -2924,8 +4342,12 @@
         "Providing the accessible label or labelledby reference for the tablist landmark."
       ],
       "avoidWhen": [
-        "Used outside a tabs ancestor — the component throws at construction.",
-        "Rendering tab-panel content — keep panels as siblings outside the tab-list."
+        {
+          "reason": "Used outside a tabs ancestor — the component throws at construction."
+        },
+        {
+          "reason": "Rendering tab-panel content — keep panels as siblings outside the tab-list."
+        }
       ],
       "related": ["tabs", "tab", "tab-panel"],
       "hasConstraints": false,
@@ -2949,8 +4371,12 @@
         "Letting the tabs context drive aria-labelledby and visibility automatically from the shared value."
       ],
       "avoidWhen": [
-        "Used outside a tabs ancestor — the component throws at construction.",
-        "Rendering the tab trigger itself — use tab inside a tab-list."
+        {
+          "reason": "Used outside a tabs ancestor — the component throws at construction."
+        },
+        {
+          "reason": "Rendering the tab trigger itself — use tab inside a tab-list."
+        }
       ],
       "related": ["tabs", "tab", "tab-list"],
       "hasConstraints": false,
@@ -2974,8 +4400,12 @@
         "Coordinating column sort state across header cells via the sort prop."
       ],
       "avoidWhen": [
-        "Rendering a responsive card grid — use grid-list instead.",
-        "Listing key-value attributes of one entity — use description-list instead."
+        {
+          "reason": "Rendering a responsive card grid — use grid-list instead."
+        },
+        {
+          "reason": "Listing key-value attributes of one entity — use description-list instead."
+        }
       ],
       "related": ["table-header", "table-body", "table-row", "table-cell", "table-header-cell"],
       "hasConstraints": false,
@@ -2996,7 +4426,11 @@
       "purpose": "Body section of a table that groups data rows and establishes the body section context for nested rows.",
       "tags": ["table", "section"],
       "useWhen": ["Wrapping the data rows of a table to distinguish them from header rows."],
-      "avoidWhen": ["Wrapping header rows — use table-header instead."],
+      "avoidWhen": [
+        {
+          "reason": "Wrapping header rows — use table-header instead."
+        }
+      ],
       "related": ["table", "table-row"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -3018,7 +4452,11 @@
         "Rendering a single value inside a body row of a table.",
         "Aligning numeric or trailing-action columns via the align prop."
       ],
-      "avoidWhen": ["Rendering a column header — use table-header-cell instead."],
+      "avoidWhen": [
+        {
+          "reason": "Rendering a column header — use table-header-cell instead."
+        }
+      ],
       "related": ["table-row", "table-header-cell"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -3037,7 +4475,11 @@
       "purpose": "Header section of a table that groups column-header rows and exposes selection state to its descendants.",
       "tags": ["table", "section"],
       "useWhen": ["Wrapping the column-header row that labels each column of a table."],
-      "avoidWhen": ["Wrapping body data rows — use table-body instead."],
+      "avoidWhen": [
+        {
+          "reason": "Wrapping body data rows — use table-body instead."
+        }
+      ],
       "related": ["table", "table-header-cell"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -3059,7 +4501,11 @@
         "Labeling a column inside a table-header row.",
         "Making a column user-sortable by setting the sortable prop and supplying a column identifier."
       ],
-      "avoidWhen": ["Rendering a body data cell — use table-cell instead."],
+      "avoidWhen": [
+        {
+          "reason": "Rendering a body data cell — use table-cell instead."
+        }
+      ],
       "related": ["table-header", "table-cell"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -3081,7 +4527,11 @@
         "Grouping table-cell or table-header-cell children into a single horizontal record.",
         "Wiring per-row selection by passing the selection prop in a selectable table."
       ],
-      "avoidWhen": ["Standing alone outside a table — it requires the table section context."],
+      "avoidWhen": [
+        {
+          "reason": "Standing alone outside a table — it requires the table section context."
+        }
+      ],
       "related": ["table-body", "table-cell"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -3104,8 +4554,12 @@
         "Building the WAI-ARIA tabs pattern with shared keyboard navigation and activation rules."
       ],
       "avoidWhen": [
-        "Picking one of two to five short values inline — use segmented-control instead.",
-        "Showing ordered progress through a wizard — use steps instead."
+        {
+          "reason": "Picking one of two to five short values inline — use segmented-control instead."
+        },
+        {
+          "reason": "Showing ordered progress through a wizard — use steps instead."
+        }
       ],
       "related": ["tab", "tab-list", "tab-panel", "segmented-control"],
       "hasConstraints": false,
@@ -3130,8 +4584,12 @@
         "Letting users review and remove committed values inline before submitting a form."
       ],
       "avoidWhen": [
-        "Users must choose from a fixed option list — use combobox instead.",
-        "The value is a single free-form string rather than a list — use input instead."
+        {
+          "reason": "Users must choose from a fixed option list — use combobox instead."
+        },
+        {
+          "reason": "The value is a single free-form string rather than a list — use input instead."
+        }
       ],
       "related": ["combobox", "chip", "form-field", "input"],
       "hasConstraints": false,
@@ -3155,7 +4613,11 @@
         "Collecting multi-line prose such as comments, descriptions, or messages.",
         "Surfacing a remaining-character counter as the user types against a maxlength."
       ],
-      "avoidWhen": ["Collecting a single short line of text — use input instead."],
+      "avoidWhen": [
+        {
+          "reason": "Collecting a single short line of text — use input instead."
+        }
+      ],
       "related": ["input", "markdown-editor"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -3179,10 +4641,14 @@
         "Displaying workflow steps, audit logs, or run histories where each entry needs connector continuity or gap breaks."
       ],
       "avoidWhen": [
-        "Surfacing a real-time social or activity stream — feed is the higher-affordance composition.",
-        "Guiding users through a numbered procedural flow — steps conveys progress more clearly."
+        {
+          "reason": "Surfacing a real-time social or activity stream — feed is the higher-affordance composition."
+        },
+        {
+          "reason": "Guiding users through a numbered procedural flow — steps conveys progress more clearly."
+        }
       ],
-      "related": ["timeline-item", "feed", "steps"],
+      "related": ["feed", "steps"],
       "hasConstraints": false,
       "hasExamples": true,
       "artifacts": {
@@ -3191,30 +4657,6 @@
         "examples": "@lostgradient/cinder/timeline/examples"
       }
     },
-    {
-      "name": "TimelineItem",
-      "id": "timeline-item",
-      "import": "@lostgradient/cinder/timeline-item",
-      "exportName": "TimelineItem",
-      "category": "data-display",
-      "status": "stable",
-      "purpose": "Single event inside a timeline rail with a decorative tone marker, timestamp-first header, optional group header, and body content.",
-      "tags": ["timeline", "event"],
-      "useWhen": [
-        "Rendering one event along a timeline rail with consistent marker, header, connector, and body structure.",
-        "Coloring decorative markers by tone (info, success, warning, error) while keeping the meaningful status in title or content."
-      ],
-      "avoidWhen": [
-        "The entry lives in a social activity stream rather than a workflow rail — feed-event fits better."
-      ],
-      "related": ["timeline", "feed-event"],
-      "hasConstraints": false,
-      "hasExamples": false,
-      "artifacts": {
-        "schema": "@lostgradient/cinder/timeline-item/schema",
-        "variables": "@lostgradient/cinder/timeline-item/variables"
-      }
-    },
     {
       "name": "ToastRegion",
       "id": "toast-region",
@@ -3229,8 +4671,12 @@
         "Announcing the outcome of a background action that the user does not need to acknowledge."
       ],
       "avoidWhen": [
-        "Communicating a persistent page-level message — use banner so it stays until dismissed.",
-        "Reporting an urgent error that must remain on screen — use alert."
+        {
+          "reason": "Communicating a persistent page-level message — use banner so it stays until dismissed."
+        },
+        {
+          "reason": "Reporting an urgent error that must remain on screen — use alert."
+        }
       ],
       "related": ["alert", "banner"],
       "hasConstraints": false,
@@ -3254,8 +4700,12 @@
         "Flipping a single setting on or off with immediate effect such as notifications or dark mode."
       ],
       "avoidWhen": [
-        "Picking one option from a small fixed set — use segmented-control instead.",
-        "Collecting a deferred boolean (agreement, opt-in) in a Submit-style form — a switch implies immediate effect; use checkbox instead."
+        {
+          "reason": "Picking one option from a small fixed set — use segmented-control instead."
+        },
+        {
+          "reason": "Collecting a deferred boolean (agreement, opt-in) in a Submit-style form — a switch implies immediate effect; use checkbox instead."
+        }
       ],
       "related": ["checkbox", "segmented-control"],
       "hasConstraints": false,
@@ -3280,7 +4730,9 @@
         "Wrapping existing cinder controls such as Button, SegmentedControl, and NumberInput without adding toolbar-specific child APIs."
       ],
       "avoidWhen": [
-        "Building a static flex row of controls that should remain in ordinary Tab order — use inline, cluster, or button-group instead."
+        {
+          "reason": "Building a static flex row of controls that should remain in ordinary Tab order — use inline, cluster, or button-group instead."
+        }
       ],
       "related": ["button-group", "segmented-control", "number-input"],
       "hasConstraints": false,
@@ -3305,8 +4757,12 @@
         "Supplementing a control with a hint that should appear on hover or keyboard focus and dismiss on Escape."
       ],
       "avoidWhen": [
-        "Hosting interactive content or focusable controls — use popover instead, since tooltip content is not reachable.",
-        "Communicating the only accessible name for a control — use aria-label or visible text rather than tooltip text."
+        {
+          "reason": "Hosting interactive content or focusable controls — use popover instead, since tooltip content is not reachable."
+        },
+        {
+          "reason": "Communicating the only accessible name for a control — use aria-label or visible text rather than tooltip text."
+        }
       ],
       "related": ["popover"],
       "hasConstraints": false,
@@ -3317,6 +4773,36 @@
         "examples": "@lostgradient/cinder/tooltip/examples"
       }
     },
+    {
+      "name": "TransferList",
+      "id": "transfer-list",
+      "import": "@lostgradient/cinder/transfer-list",
+      "exportName": "TransferList",
+      "category": "form",
+      "status": "beta",
+      "purpose": "Dual-list assignment control for moving items between an available pool and a selected set.",
+      "tags": ["form", "selection"],
+      "useWhen": [
+        "Letting users build a subset from a fixed pool such as permissions, tags, or visible columns."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "The pool needs inline search or filtering - compose search controls around the lists instead."
+        },
+        {
+          "reason": "The user only needs independent checkbox choices - use checkbox-group instead.",
+          "alternative": "checkbox-group"
+        }
+      ],
+      "related": ["checkbox-group", "selection-popover", "sortable-list"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/transfer-list/schema",
+        "variables": "@lostgradient/cinder/transfer-list/variables",
+        "examples": "@lostgradient/cinder/transfer-list/examples"
+      }
+    },
     {
       "name": "Tree",
       "id": "tree",
@@ -3331,8 +4817,12 @@
         "Coordinating single- or multi-select state across all descendant tree-items via the selectionMode prop."
       ],
       "avoidWhen": [
-        "Disclosing flat sibling sections — use accordion instead.",
-        "Switching between sibling views of the same region — use tabs instead."
+        {
+          "reason": "Disclosing flat sibling sections — use accordion instead."
+        },
+        {
+          "reason": "Switching between sibling views of the same region — use tabs instead."
+        }
       ],
       "related": ["tree-item", "accordion"],
       "hasConstraints": false,
@@ -3356,7 +4846,11 @@
         "Rendering a single branch or leaf inside a tree parent.",
         "Nesting further tree-items as children to form a hierarchy."
       ],
-      "avoidWhen": ["Standing alone outside a tree — it requires the tree context and registry."],
+      "avoidWhen": [
+        {
+          "reason": "Standing alone outside a tree — it requires the tree context and registry."
+        }
+      ],
       "related": ["tree"],
       "hasConstraints": false,
       "hasExamples": false,
@@ -3377,7 +4871,11 @@
       "useWhen": [
         "Applying a named typographic style (heading, body, caption) with semantic HTML."
       ],
-      "avoidWhen": ["Rendering inline text inside a paragraph — use a plain <span> with CSS."],
+      "avoidWhen": [
+        {
+          "reason": "Rendering inline text inside a paragraph — use a plain <span> with CSS."
+        }
+      ],
       "related": ["label", "kbd"],
       "hasConstraints": false,
       "hasExamples": true,
@@ -3387,6 +4885,36 @@
         "examples": "@lostgradient/cinder/typography/examples"
       }
     },
+    {
+      "name": "VirtualList",
+      "id": "virtual-list",
+      "import": "@lostgradient/cinder/virtual-list",
+      "exportName": "VirtualList",
+      "category": "data-display",
+      "status": "beta",
+      "purpose": "Fixed-height windowing primitive for long vertical lists that renders only the visible rows plus overscan inside a native scroll container.",
+      "tags": ["list", "virtualization", "performance"],
+      "useWhen": [
+        "Rendering thousands of same-height append-only rows such as logs, event streams, or activity feeds.",
+        "You need a reusable primitive that owns native vertical scrolling but leaves row markup to a snippet."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Rows have substantially variable heights that must be measured dynamically — v1 requires a fixed itemHeight."
+        },
+        {
+          "reason": "Rendering columns or two-dimensional grids — use data-grid for grid semantics and column virtualization."
+        }
+      ],
+      "related": ["data-list", "data-table", "data-grid"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/virtual-list/schema",
+        "variables": "@lostgradient/cinder/virtual-list/variables",
+        "examples": "@lostgradient/cinder/virtual-list/examples"
+      }
+    },
     {
       "name": "VisuallyHidden",
       "id": "visually-hidden",
@@ -3401,8 +4929,12 @@
         "Implementing a skip-to-content link that appears on keyboard focus."
       ],
       "avoidWhen": [
-        "Hiding content from everyone — use the hidden attribute or display none instead.",
-        "Labelling a form control where a visible label is acceptable — use label directly."
+        {
+          "reason": "Hiding content from everyone — use the hidden attribute or display none instead."
+        },
+        {
+          "reason": "Labelling a form control where a visible label is acceptable — use label directly."
+        }
       ],
       "related": ["label"],
       "hasConstraints": false,
@@ -3412,6 +4944,36 @@
         "variables": "@lostgradient/cinder/visually-hidden/variables",
         "examples": "@lostgradient/cinder/visually-hidden/examples"
       }
+    },
+    {
+      "name": "Waveform",
+      "id": "waveform",
+      "import": "@lostgradient/cinder/waveform",
+      "exportName": "Waveform",
+      "category": "data-display",
+      "status": "alpha",
+      "purpose": "Responsive SVG rendering of time-domain audio amplitude data as a waveform path or bar display.",
+      "tags": ["chart", "waveform", "signal", "audio"],
+      "useWhen": [
+        "Visualizing pre-recorded or pre-processed audio amplitude samples in a static display.",
+        "Showing an audio waveform thumbnail or preview with mocked or pre-computed sample data."
+      ],
+      "avoidWhen": [
+        {
+          "reason": "Real-time live audio capture is needed — wire AudioContext / AnalyserNode yourself and feed samples as props."
+        },
+        {
+          "reason": "Frequency-domain data — use spectrum-chart or spectrogram instead."
+        }
+      ],
+      "related": ["spectrum-chart", "spectrogram", "bar-chart", "line-chart"],
+      "hasConstraints": false,
+      "hasExamples": true,
+      "artifacts": {
+        "schema": "@lostgradient/cinder/waveform/schema",
+        "variables": "@lostgradient/cinder/waveform/variables",
+        "examples": "@lostgradient/cinder/waveform/examples"
+      }
     }
   ]
 }