@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/avatar-group/avatar-group.types.ts

@@ -20,6 +20,11 @@ export type AvatarGroupItem = {
 export type AvatarGroupProps = AvatarGroupRootAttributes & {
   /** Collaborators to render in the stack. */
   avatars: AvatarGroupItem[];
+  /**
+   * Accessible name for the avatar stack list.
+   * @default "Collaborators"
+   */
+  label?: string;
   /**
    * Maximum visible avatars before overflow.
    * @default 5
@@ -55,6 +60,11 @@ export type AvatarGroupProps = AvatarGroupRootAttributes & {
 export interface AvatarGroupSchemaProps {
   /** Collaborators to render in the stack. */
   avatars: AvatarGroupItem[];
+  /**
+   * Accessible name for the avatar stack list.
+   * @default "Collaborators"
+   */
+  label?: string;
   /**
    * Maximum visible avatars before overflow.
    * @default 5

package/src/components/backdrop/README.md

@@ -27,15 +27,15 @@ Full-viewport fixed scrim primitive for custom overlay patterns such as loading
 
 <!-- generated:props:start -->
 
-| Prop                 | Type       | Required | Default | Description                                                                                                                                          |
-| -------------------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`              | `string`   | no       | —       | Additional class names merged onto the root element.                                                                                                 |
-| `invisible`          | `boolean`  | no       | `false` | When true the backdrop is transparent but still captures pointer events, enabling click-to-close without dimming content behind it.                  |
-| `lockScroll`         | `boolean`  | no       | `true`  | Lock body scroll while the backdrop is open (counted lock — safe to nest with other overlays). Set false when the consumer manages scrolling itself. |
-| `open`               | `boolean`  | yes      | —       | Whether the backdrop is visible and active.                                                                                                          |
-| `transitionDuration` | `number`   | no       | —       | Enter/leave animation duration in milliseconds. Collapses to 0 under `prefers-reduced-motion`. Overrides the default when provided.                  |
-| `children`           | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                           |
-| `onclick`            | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                           |
+| Prop                 | Type       | Required | Default | Description                                                                                                                                                |
+| -------------------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`              | `string`   | no       | —       | Additional class names merged onto the root element.                                                                                                       |
+| `invisible`          | `boolean`  | no       | `false` | When true the backdrop is transparent but still captures pointer events, enabling click-to-close without dimming content behind it.                        |
+| `lockScroll`         | `boolean`  | no       | `true`  | Lock body scroll while the backdrop is open (counted lock — safe to nest with other overlays). Set false when the consumer manages scrolling itself.       |
+| `open`               | `boolean`  | yes      | —       | Whether the backdrop is visible and active.                                                                                                                |
+| `transitionDuration` | `number`   | no       | —       | Enter/leave animation duration in milliseconds. Collapses to 0 under `prefers-reduced-motion`. Overrides the default when provided.                        |
+| `children`           | `(opaque)` | no       | —       | Optional content rendered above the scrim (e.g. a Spinner for a loading state). Not expressible in JSON Schema; see the component types for the signature. |
+| `onclick`            | `(opaque)` | no       | —       | Click handler — use this to wire click-to-close on the scrim. Not expressible in JSON Schema; see the component types for the signature.                   |
 
 <!-- generated:props:end -->
 

package/src/components/badge/README.md

@@ -18,12 +18,13 @@ Use Badge for attached counts, statuses, and compact annotations; use `Chip mode
 
 <!-- generated:props:start -->
 
-| Prop      | Type                                                                              | Required | Default     | Description                                                                                                     |
-| --------- | --------------------------------------------------------------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
-| `class`   | `string`                                                                          | no       | —           | Custom class merged with `.cinder-badge`.                                                                       |
-| `mono`    | `boolean`                                                                         | no       | `false`     | Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels. |
-| `size`    | `"xs"` \| `"sm"` \| `"md"`                                                        | no       | `"md"`      | Size of the badge.                                                                                              |
-| `variant` | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"` | no       | `"neutral"` | Visual style.                                                                                                   |
+| Prop       | Type                                                                              | Required | Default     | Description                                                                                                                                                                                                                                                               |
+| ---------- | --------------------------------------------------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`                                                                          | no       | —           | Custom class merged with `.cinder-badge`.                                                                                                                                                                                                                                 |
+| `mono`     | `boolean`                                                                         | no       | `false`     | Render the badge label in a monospace font. Useful for version strings, error codes, or other technical labels.                                                                                                                                                           |
+| `size`     | `"xs"` \| `"sm"` \| `"md"`                                                        | no       | `"md"`      | Size of the badge.                                                                                                                                                                                                                                                        |
+| `variant`  | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"` | no       | `"neutral"` | Visual style.                                                                                                                                                                                                                                                             |
+| `children` | `(opaque)`                                                                        | yes      | —           | Badge content — intentionally required. A badge without content is semantically meaningless. The render site uses optional chaining (`children?.()`) as a runtime safety net for JS consumers. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/badge/badge.css

@@ -48,7 +48,7 @@
  * ---------------------------------------- */
 
   .cinder-badge[data-cinder-variant='neutral'] {
-    background: var(--cinder-surface-inset);
+    background: color-mix(in oklch, var(--cinder-surface-inset), var(--cinder-surface) 40%);
     color: var(--cinder-text);
     border-color: var(--cinder-border);
   }

package/src/components/banner/README.md

@@ -21,9 +21,9 @@ Full-width announcement strip for page-level alerts, promotions, or system messa
 | `class`       | `string`                                             | no       | —       | Extra classes appended to the root element. Pass via the explicit `class` prop — it is excluded from rest-prop spread, so writing `class="x"` inside spread attributes will not reach the root. |
 | `dismissible` | `boolean`                                            | no       | —       | Whether the banner shows a dismiss (×) button. Default `true`.                                                                                                                                  |
 | `variant`     | `"info"` \| `"success"` \| `"warning"` \| `"danger"` | no       | —       | Visual + semantic variant. Default `'info'`.                                                                                                                                                    |
-| `actions`     | `(opaque)`                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                      |
-| `children`    | `(opaque)`                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                      |
-| `onDismiss`   | `(opaque)`                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                      |
+| `actions`     | `(opaque)`                                           | no       | —       | Optional trailing CTA region (e.g., "Renew now" button). Not expressible in JSON Schema; see the component types for the signature.                                                             |
+| `children`    | `(opaque)`                                           | yes      | —       | Banner body content. Not expressible in JSON Schema; see the component types for the signature.                                                                                                 |
+| `onDismiss`   | `(opaque)`                                           | no       | —       | Called after the dismiss button is clicked. Use to persist state. Not expressible in JSON Schema; see the component types for the signature.                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/bar-chart/README.md

@@ -29,22 +29,24 @@ Responsive SVG bar chart for grouped or stacked category comparisons.
 | Prop                       | Type                                                                      | Required | Default | Description                                                                                                                                                       |
 | -------------------------- | ------------------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `categoryKey`              | `string`                                                                  | yes      | —       | Category field name. Runtime validation requires every row to contain a string, number, or Date category.                                                         |
-| `class`                    | `string`                                                                  | no       | —       |                                                                                                                                                                   |
+| `class`                    | `string`                                                                  | no       | —       | Custom class applied to the root element.                                                                                                                         |
 | `data`                     | `object`[]                                                                | yes      | —       | JSON-safe data rows. Schema cannot express dynamic categoryKey/valueKey relationships; runtime validation narrows value-key fields to number, null, or undefined. |
-| `dataTableCaption`         | `string`                                                                  | no       | —       |                                                                                                                                                                   |
-| `dataTableVisibility`      | `"screen-reader-only"` \| `"visible"` \| `"hidden"`                       | no       | —       |                                                                                                                                                                   |
-| `description`              | `string`                                                                  | no       | —       |                                                                                                                                                                   |
-| `height`                   | `number`                                                                  | no       | —       |                                                                                                                                                                   |
-| `hiddenSeriesIds`          | `string`[]                                                                | no       | —       |                                                                                                                                                                   |
-| `label`                    | `string`                                                                  | yes      | —       |                                                                                                                                                                   |
-| `legendPosition`           | `"top"` \| `"bottom"` \| `"none"`                                         | no       | —       |                                                                                                                                                                   |
-| `loading`                  | `boolean`                                                                 | no       | —       |                                                                                                                                                                   |
-| `maximumInteractivePoints` | `number`                                                                  | no       | —       |                                                                                                                                                                   |
-| `mode`                     | `"grouped"` \| `"stacked"`                                                | no       | —       |                                                                                                                                                                   |
-| `orientation`              | `"vertical"` \| `"horizontal"`                                            | no       | —       |                                                                                                                                                                   |
+| `dataTableCaption`         | `string`                                                                  | no       | —       | Custom data table caption; falls back to `label`.                                                                                                                 |
+| `dataTableVisibility`      | `"screen-reader-only"` \| `"visible"` \| `"hidden"`                       | no       | —       | Controls data table visibility. Default `screen-reader-only`.                                                                                                     |
+| `description`              | `string`                                                                  | no       | —       | Optional description rendered below the label.                                                                                                                    |
+| `height`                   | `number`                                                                  | no       | —       | Pixel height of the chart viewport. Default `280`.                                                                                                                |
+| `hiddenSeriesIds`          | `string`[]                                                                | no       | —       | IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`.                                                                  |
+| `label`                    | `string`                                                                  | yes      | —       | Accessible label for the chart. Required for screen readers.                                                                                                      |
+| `legendPosition`           | `"top"` \| `"bottom"` \| `"none"`                                         | no       | —       | Where to render the series legend relative to the chart. Default `top`.                                                                                           |
+| `loading`                  | `boolean`                                                                 | no       | —       | Whether the chart is in a loading state. Default `false`.                                                                                                         |
+| `maximumInteractivePoints` | `number`                                                                  | no       | —       | Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`.                                                                |
+| `mode`                     | `"grouped"` \| `"stacked"`                                                | no       | —       | Grouped or stacked bar layout. Default `grouped`.                                                                                                                 |
+| `orientation`              | `"vertical"` \| `"horizontal"`                                            | no       | —       | Bar orientation. Default `vertical`.                                                                                                                              |
 | `series`                   | { color?: `string`; id: `string`; label: `string`; valueKey: `string` }[] | yes      | —       | Series value keys. Schema cannot prove every valueKey exists on every row; runtime validation enforces it.                                                        |
-| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                | no       | —       |                                                                                                                                                                   |
-| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                | no       | —       |                                                                                                                                                                   |
+| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                | no       | —       | Configuration for the x-axis label and tick count.                                                                                                                |
+| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                | no       | —       | Configuration for the y-axis label and tick count.                                                                                                                |
+| `empty`                    | `(opaque)`                                                                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                        |
+| `loadingContent`           | `(opaque)`                                                                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                        |
 
 <!-- generated:props:end -->
 

package/src/components/bar-chart/bar-chart.css

@@ -56,6 +56,10 @@
     rx: 3;
   }
 
+  .cinder-bar-chart__bar[data-cinder-active] {
+    filter: brightness(1.15);
+  }
+
   .cinder-bar-chart__crosshair {
     stroke: var(--cinder-text-muted);
     stroke-dasharray: 4 4;

package/src/components/bar-chart/bar-chart.svelte

@@ -260,6 +260,10 @@
             aria-hidden="true"
             data-cinder-series={bar.seriesId}
             data-cinder-category={bar.categoryLabel}
+            data-cinder-active={interaction.activeTarget?.seriesId === bar.seriesId &&
+            interaction.activeTarget?.xLabel === bar.categoryLabel
+              ? ''
+              : undefined}
           />
         {/each}
         {#each model.categoryTicks as tick (tick.categoryKey)}

package/src/components/bar-chart/bar-chart.types.ts

@@ -25,17 +25,29 @@ export type BarChartProps = ChartSharedProps & {
 };
 
 export type BarChartSchemaProps = {
+  /** Accessible label for the chart. Required for screen readers. */
   label: string;
+  /** Optional description rendered below the label. */
   description?: string;
+  /** Pixel height of the chart viewport. Default `280`. */
   height?: number;
+  /** Configuration for the x-axis label and tick count. */
   xAxis?: ChartAxisSchemaConfiguration;
+  /** Configuration for the y-axis label and tick count. */
   yAxis?: ChartAxisSchemaConfiguration;
+  /** Where to render the series legend relative to the chart. Default `top`. */
   legendPosition?: ChartLegendPosition;
+  /** IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`. */
   hiddenSeriesIds?: string[];
+  /** Whether the chart is in a loading state. Default `false`. */
   loading?: boolean;
+  /** Custom data table caption; falls back to `label`. */
   dataTableCaption?: string;
+  /** Controls data table visibility. Default `screen-reader-only`. */
   dataTableVisibility?: ChartDataTableVisibility;
+  /** Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`. */
   maximumInteractivePoints?: number;
+  /** Custom class applied to the root element. */
   class?: string;
   /** JSON-safe data rows. Schema cannot express dynamic categoryKey/valueKey relationships; runtime validation narrows value-key fields to number, null, or undefined. */
   data: BarChartSchemaDatum[];
@@ -43,6 +55,8 @@ export type BarChartSchemaProps = {
   categoryKey: string;
   /** Series value keys. Schema cannot prove every valueKey exists on every row; runtime validation enforces it. */
   series: BarChartSchemaSeries[];
+  /** Bar orientation. Default `vertical`. */
   orientation?: BarChartOrientation;
+  /** Grouped or stacked bar layout. Default `grouped`. */
   mode?: BarChartMode;
 };

package/src/components/button/README.md

@@ -18,16 +18,19 @@ When `href` is set, the component renders as `<a>`; otherwise it renders as `<bu
 
 <!-- generated:props:start -->
 
-| Prop        | Type                                                                                                       | Required | Default       | Description                                                              |
-| ----------- | ---------------------------------------------------------------------------------------------------------- | -------- | ------------- | ------------------------------------------------------------------------ |
-| `class`     | `string`                                                                                                   | no       | —             | Custom class merged with `.cinder-button`.                               |
-| `fullWidth` | `boolean`                                                                                                  | no       | `false`       | Expand to container width.                                               |
-| `href`      | `string`                                                                                                   | no       | —             | Render as an anchor `<a>` element with this href.                        |
-| `iconOnly`  | `boolean`                                                                                                  | no       | `false`       | Render the button with only an icon. Requires an accessible name source. |
-| `label`     | `string`                                                                                                   | no       | —             | Visible text label. Must be non-empty if provided.                       |
-| `loading`   | `boolean`                                                                                                  | no       | `false`       | Disable the button and show a spinner.                                   |
-| `size`      | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`                                                             | no       | `"md"`        | Size of the button.                                                      |
-| `variant`   | `"primary"` \| `"secondary"` \| `"soft"` \| `"danger"` \| `"soft-danger"` \| `"ghost"` \| `"ghost-danger"` | no       | `"secondary"` | Visual style.                                                            |
+| Prop           | Type                                                                                                       | Required | Default       | Description                                                                                                                                                                                                                                         |
+| -------------- | ---------------------------------------------------------------------------------------------------------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`                                                                                                   | no       | —             | Custom class merged with `.cinder-button`.                                                                                                                                                                                                          |
+| `fullWidth`    | `boolean`                                                                                                  | no       | `false`       | Expand to container width.                                                                                                                                                                                                                          |
+| `href`         | `string`                                                                                                   | no       | —             | Render as an anchor `<a>` element with this href.                                                                                                                                                                                                   |
+| `iconOnly`     | `boolean`                                                                                                  | no       | `false`       | Render the button with only an icon. Requires an accessible name source.                                                                                                                                                                            |
+| `label`        | `string`                                                                                                   | no       | —             | Visible text label. Must be non-empty if provided.                                                                                                                                                                                                  |
+| `loading`      | `boolean`                                                                                                  | no       | `false`       | Disable the button and show a spinner.                                                                                                                                                                                                              |
+| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`                                                             | no       | `"md"`        | Size of the button.                                                                                                                                                                                                                                 |
+| `variant`      | `"primary"` \| `"secondary"` \| `"soft"` \| `"danger"` \| `"soft-danger"` \| `"ghost"` \| `"ghost-danger"` | no       | `"secondary"` | Visual style.                                                                                                                                                                                                                                       |
+| `children`     | `(opaque)`                                                                                                 | no       | —             | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                          |
+| `leadingIcon`  | `(opaque)`                                                                                                 | no       | —             | DECORATIVE icon rendered before the label/children. Always wrapped in aria-hidden. If the icon conveys meaning, supply accessible text via `label`/`aria-label` instead. Not expressible in JSON Schema; see the component types for the signature. |
+| `trailingIcon` | `(opaque)`                                                                                                 | no       | —             | DECORATIVE icon rendered after the label/children. Always wrapped in aria-hidden. Same accessible-name guidance as `leadingIcon`. Not expressible in JSON Schema; see the component types for the signature.                                        |
 
 <!-- generated:props:end -->
 

package/src/components/button/button.css

@@ -235,6 +235,13 @@
 
   .cinder-button[data-cinder-variant='ghost'] {
     background: transparent;
+    /* --cinder-text-muted is intentional for the ghost variant — it reads as
+     * intentionally de-emphasised (visually secondary to primary/secondary actions)
+     * while still meeting WCAG 1.4.3 AA (4.5:1) against the typical page surfaces
+     * in both themes: light-dark oklch(32% 0.014 245 / 82% 0.02 245) clears 4.5:1
+     * against --cinder-surface (L≈98.5%/20%) and --cinder-surface-raised (L≈100%/26%).
+     * Switching to --cinder-text (L≈20%/92%) would meet a higher bar but remove
+     * the visual hierarchy distinction from secondary buttons. */
     color: var(--cinder-text-muted);
     border-color: transparent;
   }

package/src/components/button/button.examples.json

@@ -13,7 +13,7 @@
       "id": "icon-only",
       "title": "Icon-only buttons",
       "description": "Icon-only buttons keep the visual surface compact while still carrying an accessible name through label or aria-label.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n</script>\n\n<div class=\"example-preview-row\">\n  <Button iconOnly={true} label=\"Close\" variant=\"ghost\" data-testid=\"button-ghost-icon-only-rest\">\n    {#snippet leadingIcon()}\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        stroke-width=\"2\"\n        stroke-linecap=\"round\"\n        stroke-linejoin=\"round\"\n        aria-hidden=\"true\"\n      >\n        <line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\" />\n        <line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\" />\n      </svg>\n    {/snippet}\n  </Button>\n\n  <Button\n    iconOnly={true}\n    label=\"Delete\"\n    variant=\"ghost-danger\"\n    data-testid=\"button-ghost-danger-icon-only-rest\"\n  >\n    {#snippet leadingIcon()}\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        stroke-width=\"2\"\n        stroke-linecap=\"round\"\n        stroke-linejoin=\"round\"\n        aria-hidden=\"true\"\n      >\n        <polyline points=\"3 6 5 6 21 6\" />\n        <path d=\"M19 6l-1 14H6L5 6\" />\n        <path d=\"M10 11v6\" />\n        <path d=\"M14 11v6\" />\n        <path d=\"M9 6V4h6v2\" />\n      </svg>\n    {/snippet}\n  </Button>\n\n  <Button iconOnly={true} label=\"Search\" variant=\"secondary\">\n    {#snippet leadingIcon()}\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        stroke-width=\"2\"\n        stroke-linecap=\"round\"\n        stroke-linejoin=\"round\"\n        aria-hidden=\"true\"\n      >\n        <circle cx=\"11\" cy=\"11\" r=\"8\" />\n        <line x1=\"21\" y1=\"21\" x2=\"16.65\" y2=\"16.65\" />\n      </svg>\n    {/snippet}\n  </Button>\n</div>\n\n<div class=\"example-preview-row\">\n  <Button\n    disabled={true}\n    iconOnly={true}\n    label=\"Disabled close\"\n    variant=\"ghost\"\n    data-testid=\"button-ghost-icon-only-disabled\"\n  >\n    {#snippet leadingIcon()}\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        stroke-width=\"2\"\n        stroke-linecap=\"round\"\n        stroke-linejoin=\"round\"\n        aria-hidden=\"true\"\n      >\n        <line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\" />\n        <line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\" />\n      </svg>\n    {/snippet}\n  </Button>\n\n  <Button\n    disabled={true}\n    iconOnly={true}\n    label=\"Disabled delete\"\n    variant=\"ghost-danger\"\n    data-testid=\"button-ghost-danger-icon-only-disabled\"\n  >\n    {#snippet leadingIcon()}\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        stroke-width=\"2\"\n        stroke-linecap=\"round\"\n        stroke-linejoin=\"round\"\n        aria-hidden=\"true\"\n      >\n        <polyline points=\"3 6 5 6 21 6\" />\n        <path d=\"M19 6l-1 14H6L5 6\" />\n        <path d=\"M10 11v6\" />\n        <path d=\"M14 11v6\" />\n        <path d=\"M9 6V4h6v2\" />\n      </svg>\n    {/snippet}\n  </Button>\n\n  <Button\n    href=\"#disabled-close\"\n    aria-disabled=\"true\"\n    iconOnly={true}\n    label=\"Unavailable close link\"\n    variant=\"ghost\"\n    data-testid=\"button-ghost-icon-only-aria-disabled-link\"\n  >\n    {#snippet leadingIcon()}\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        stroke-width=\"2\"\n        stroke-linecap=\"round\"\n        stroke-linejoin=\"round\"\n        aria-hidden=\"true\"\n      >\n        <line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\" />\n        <line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\" />\n      </svg>\n    {/snippet}\n  </Button>\n\n  <Button\n    href=\"#disabled-delete\"\n    aria-disabled=\"true\"\n    iconOnly={true}\n    label=\"Unavailable delete link\"\n    variant=\"ghost-danger\"\n    data-testid=\"button-ghost-danger-icon-only-aria-disabled-link\"\n  >\n    {#snippet leadingIcon()}\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        stroke-width=\"2\"\n        stroke-linecap=\"round\"\n        stroke-linejoin=\"round\"\n        aria-hidden=\"true\"\n      >\n        <polyline points=\"3 6 5 6 21 6\" />\n        <path d=\"M19 6l-1 14H6L5 6\" />\n        <path d=\"M10 11v6\" />\n        <path d=\"M14 11v6\" />\n        <path d=\"M9 6V4h6v2\" />\n      </svg>\n    {/snippet}\n  </Button>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n</script>\n\n<div class=\"example-preview-column\">\n  <div class=\"example-preview-row\">\n    <Button iconOnly={true} label=\"Close\" variant=\"ghost\" data-testid=\"button-ghost-icon-only-rest\">\n      {#snippet leadingIcon()}\n        <svg\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          stroke-width=\"2\"\n          stroke-linecap=\"round\"\n          stroke-linejoin=\"round\"\n          aria-hidden=\"true\"\n        >\n          <line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\" />\n          <line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\" />\n        </svg>\n      {/snippet}\n    </Button>\n\n    <Button\n      iconOnly={true}\n      label=\"Delete\"\n      variant=\"ghost-danger\"\n      data-testid=\"button-ghost-danger-icon-only-rest\"\n    >\n      {#snippet leadingIcon()}\n        <svg\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          stroke-width=\"2\"\n          stroke-linecap=\"round\"\n          stroke-linejoin=\"round\"\n          aria-hidden=\"true\"\n        >\n          <polyline points=\"3 6 5 6 21 6\" />\n          <path d=\"M19 6l-1 14H6L5 6\" />\n          <path d=\"M10 11v6\" />\n          <path d=\"M14 11v6\" />\n          <path d=\"M9 6V4h6v2\" />\n        </svg>\n      {/snippet}\n    </Button>\n\n    <Button iconOnly={true} label=\"Search\" variant=\"secondary\">\n      {#snippet leadingIcon()}\n        <svg\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          stroke-width=\"2\"\n          stroke-linecap=\"round\"\n          stroke-linejoin=\"round\"\n          aria-hidden=\"true\"\n        >\n          <circle cx=\"11\" cy=\"11\" r=\"8\" />\n          <line x1=\"21\" y1=\"21\" x2=\"16.65\" y2=\"16.65\" />\n        </svg>\n      {/snippet}\n    </Button>\n  </div>\n\n  <div class=\"example-preview-row\">\n    <Button\n      disabled={true}\n      iconOnly={true}\n      label=\"Disabled close\"\n      variant=\"ghost\"\n      data-testid=\"button-ghost-icon-only-disabled\"\n    >\n      {#snippet leadingIcon()}\n        <svg\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          stroke-width=\"2\"\n          stroke-linecap=\"round\"\n          stroke-linejoin=\"round\"\n          aria-hidden=\"true\"\n        >\n          <line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\" />\n          <line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\" />\n        </svg>\n      {/snippet}\n    </Button>\n\n    <Button\n      disabled={true}\n      iconOnly={true}\n      label=\"Disabled delete\"\n      variant=\"ghost-danger\"\n      data-testid=\"button-ghost-danger-icon-only-disabled\"\n    >\n      {#snippet leadingIcon()}\n        <svg\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          stroke-width=\"2\"\n          stroke-linecap=\"round\"\n          stroke-linejoin=\"round\"\n          aria-hidden=\"true\"\n        >\n          <polyline points=\"3 6 5 6 21 6\" />\n          <path d=\"M19 6l-1 14H6L5 6\" />\n          <path d=\"M10 11v6\" />\n          <path d=\"M14 11v6\" />\n          <path d=\"M9 6V4h6v2\" />\n        </svg>\n      {/snippet}\n    </Button>\n\n    <Button\n      href=\"#disabled-close\"\n      aria-disabled=\"true\"\n      iconOnly={true}\n      label=\"Unavailable close link\"\n      variant=\"ghost\"\n      data-testid=\"button-ghost-icon-only-aria-disabled-link\"\n    >\n      {#snippet leadingIcon()}\n        <svg\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          stroke-width=\"2\"\n          stroke-linecap=\"round\"\n          stroke-linejoin=\"round\"\n          aria-hidden=\"true\"\n        >\n          <line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\" />\n          <line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\" />\n        </svg>\n      {/snippet}\n    </Button>\n\n    <Button\n      href=\"#disabled-delete\"\n      aria-disabled=\"true\"\n      iconOnly={true}\n      label=\"Unavailable delete link\"\n      variant=\"ghost-danger\"\n      data-testid=\"button-ghost-danger-icon-only-aria-disabled-link\"\n    >\n      {#snippet leadingIcon()}\n        <svg\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          stroke-width=\"2\"\n          stroke-linecap=\"round\"\n          stroke-linejoin=\"round\"\n          aria-hidden=\"true\"\n        >\n          <polyline points=\"3 6 5 6 21 6\" />\n          <path d=\"M19 6l-1 14H6L5 6\" />\n          <path d=\"M10 11v6\" />\n          <path d=\"M14 11v6\" />\n          <path d=\"M9 6V4h6v2\" />\n        </svg>\n      {/snippet}\n    </Button>\n  </div>\n</div>\n"
     },
     {
       "id": "loading",

package/src/components/button-group/README.md

@@ -16,13 +16,13 @@ Clusters related action buttons into a unified visual group with shared borders.
 
 <!-- generated:props:start -->
 
-| Prop          | Type                           | Required | Default | Description                                                                                                                |
-| ------------- | ------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`                       | no       | —       | Additional class merged with `.cinder-button-group`.                                                                       |
-| `label`       | `string`                       | no       | —       |                                                                                                                            |
-| `labelledBy`  | `string`                       | no       | —       |                                                                                                                            |
-| `orientation` | `"horizontal"` \| `"vertical"` | no       | —       | Orientation of the visual collapse. Default: 'horizontal'.                                                                 |
-| `children`    | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop          | Type                           | Required | Default | Description                                                                                                                                       |
+| ------------- | ------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`                       | no       | —       | Additional class merged with `.cinder-button-group`.                                                                                              |
+| `label`       | `string`                       | no       | —       | Inline accessible name for the group, applied as `aria-label`. Provide exactly one of `label` or `labelledBy`.                                    |
+| `labelledBy`  | `string`                       | no       | —       | The `id` of a visible heading element that already names the group, applied as `aria-labelledby`. Provide exactly one of `label` or `labelledBy`. |
+| `orientation` | `"horizontal"` \| `"vertical"` | no       | —       | Orientation of the visual collapse. Default: 'horizontal'.                                                                                        |
+| `children`    | `(opaque)`                     | yes      | —       | Buttons (or split-button compositions) to render inside the group. Not expressible in JSON Schema; see the component types for the signature.     |
 
 <!-- generated:props:end -->
 

package/src/components/button-group/button-group.types.ts

@@ -20,4 +20,15 @@ type ButtonGroupBase = Omit<
  * Exactly one must be provided.
  */
 export type ButtonGroupProps = ButtonGroupBase &
-  ({ label: string; labelledBy?: never } | { label?: never; labelledBy: string });
+  (
+    | {
+        /** Inline accessible name for the group, applied as `aria-label`. Provide exactly one of `label` or `labelledBy`. */
+        label: string;
+        labelledBy?: never;
+      }
+    | {
+        label?: never;
+        /** The `id` of a visible heading element that already names the group, applied as `aria-labelledby`. Provide exactly one of `label` or `labelledBy`. */
+        labelledBy: string;
+      }
+  );

package/src/components/callout/README.md

@@ -21,8 +21,8 @@ Inline highlight block for tips, warnings, or contextual notes within content fl
 | `class`    | `string`                                             | no       | —       | Extra classes appended to the root element. Pass via the explicit `class` prop — it is excluded from rest-prop spread, so writing `class="x"` inside spread attributes will not reach the root.                                                                                                                                                                                                                                                                                                                                                                     |
 | `title`    | `string`                                             | no       | —       | Optional title rendered as a `<p class="cinder-callout__title">`. Rendered as a paragraph rather than a heading element so the callout does not inject an entry into the document outline. If a callout genuinely participates in the outline (e.g. it titles a standalone section), wrap it in a `<section>` with its own heading rather than promoting this prop to `<h*>`. When supplied and no `aria-label` or `aria-labelledby` is passed on rest props, the title also becomes the `aria-label` of the root `<aside>` so the landmark has an accessible name. |
 | `variant`  | `"info"` \| `"success"` \| `"warning"` \| `"danger"` | no       | —       | Visual + semantic variant. Default `'info'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `children` | `(opaque)`                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `icon`     | `(opaque)`                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `children` | `(opaque)`                                           | yes      | —       | Callout body content. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `icon`     | `(opaque)`                                           | no       | —       | Optional decorative icon rendered inside an `aria-hidden` wrapper. The icon is a second visual channel alongside variant color — it helps satisfy WCAG 1.4.1 (Use of Color) by ensuring the variant is conveyed by more than color alone. The accessible meaning still lives in `title` and/or `children`; the icon must not be the only carrier of information. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                         |
 
 <!-- generated:props:end -->
 

package/src/components/capability-gate/README.md

@@ -26,20 +26,20 @@ Present feature availability and next action for browser permission or support s
 
 <!-- generated:props:start -->
 
-| Prop               | Type                                                                                                                 | Required | Default    | Description                                                                                                                |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`            | `string`                                                                                                             | no       | —          | Additional class names merged with `.cinder-capability-gate`.                                                              |
-| `dismissAction`    | `string`                                                                                                             | no       | —          | Label for the dismiss action.                                                                                              |
-| `fallbackAction`   | `string`                                                                                                             | no       | —          | Label for the fallback action.                                                                                             |
-| `fallbackHref`     | `string`                                                                                                             | no       | —          | Href for a fallback link.                                                                                                  |
-| `feature`          | `string`                                                                                                             | yes      | —          | The feature being gated.                                                                                                   |
-| `primaryAction`    | `string`                                                                                                             | no       | —          | Label for the primary action button.                                                                                       |
-| `state`            | `"supported"` \| `"unsupported"` \| `"permission-needed"` \| `"permission-denied"` \| `"loading"` \| `"unavailable"` | yes      | —          | Current availability state.                                                                                                |
-| `variant`          | `"inline"` \| `"banner"` \| `"callout"`                                                                              | no       | `"inline"` | Presentation variant.                                                                                                      |
-| `children`         | `(opaque)`                                                                                                           | no       | —          | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onDismiss`        | `(opaque)`                                                                                                           | no       | —          | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onFallbackAction` | `(opaque)`                                                                                                           | no       | —          | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onPrimaryAction`  | `(opaque)`                                                                                                           | no       | —          | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop               | Type                                                                                                                 | Required | Default    | Description                                                                                                                                      |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`            | `string`                                                                                                             | no       | —          | Additional class names merged with `.cinder-capability-gate`.                                                                                    |
+| `dismissAction`    | `string`                                                                                                             | no       | —          | Label for the dismiss action.                                                                                                                    |
+| `fallbackAction`   | `string`                                                                                                             | no       | —          | Label for the fallback action.                                                                                                                   |
+| `fallbackHref`     | `string`                                                                                                             | no       | —          | Href for a fallback link.                                                                                                                        |
+| `feature`          | `string`                                                                                                             | yes      | —          | The feature being gated.                                                                                                                         |
+| `primaryAction`    | `string`                                                                                                             | no       | —          | Label for the primary action button.                                                                                                             |
+| `state`            | `"supported"` \| `"unsupported"` \| `"permission-needed"` \| `"permission-denied"` \| `"loading"` \| `"unavailable"` | yes      | —          | Current availability state.                                                                                                                      |
+| `variant`          | `"inline"` \| `"banner"` \| `"callout"`                                                                              | no       | `"inline"` | Presentation variant.                                                                                                                            |
+| `children`         | `(opaque)`                                                                                                           | no       | —          | Custom content rendered below the status text and before the actions. Not expressible in JSON Schema; see the component types for the signature. |
+| `onDismiss`        | `(opaque)`                                                                                                           | no       | —          | Called when the gate is dismissed. Not expressible in JSON Schema; see the component types for the signature.                                    |
+| `onFallbackAction` | `(opaque)`                                                                                                           | no       | —          | Called when the fallback action button is activated. Not expressible in JSON Schema; see the component types for the signature.                  |
+| `onPrimaryAction`  | `(opaque)`                                                                                                           | no       | —          | Called when the primary action button is activated. Not expressible in JSON Schema; see the component types for the signature.                   |
 
 <!-- generated:props:end -->
 

package/src/components/capability-gate/capability-gate.css

@@ -125,7 +125,10 @@
     margin-inline-start: auto;
   }
 
-  .cinder-capability-gate__dismiss:hover {
-    color: var(--cinder-text);
+  @media (hover: hover) {
+    .cinder-capability-gate__dismiss:hover {
+      background-color: var(--cinder-surface-hover);
+      color: var(--cinder-text);
+    }
   }
 }

package/src/components/card/README.md

@@ -19,14 +19,14 @@ Surface container for grouping related content and actions into a distinct visua
 | Prop                 | Type                            | Required | Default | Description                                                                                                                                 |
 | -------------------- | ------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bodyTone`           | `"default"` \| `"muted"`        | no       | —       | Body surface treatment. `muted` renders a grey/inset body region.                                                                           |
-| `description`        | `string`                        | no       | —       |                                                                                                                                             |
+| `description`        | `string`                        | no       | —       | Optional subheading rendered as a paragraph below the title inside the header.                                                              |
 | `edgeToEdgeOnMobile` | `boolean`                       | no       | —       | Remove side borders/radius and bleed to the viewport edge on narrow screens.                                                                |
 | `footerTone`         | `"default"` \| `"muted"`        | no       | —       | Footer surface treatment. `muted` renders a grey/inset footer region.                                                                       |
 | `headingLevel`       | `2` \| `3` \| `4` \| `5` \| `6` | no       | —       | Heading level for the generated title. Defaults to `3`. Set this so the card title nests correctly within the surrounding document outline. |
 | `padding`            | `"none"` \| `"default"`         | no       | —       | Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image).                                                   |
-| `title`              | `string`                        | no       | —       |                                                                                                                                             |
+| `title`              | `string`                        | no       | —       | Primary heading text rendered inside the card's header region.                                                                              |
 | `variant`            | `"card"` \| `"well"`            | no       | —       | Visual container style. `card` is raised; `well` is flatter and inset.                                                                      |
-| `children`           | `(opaque)`                      | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |
+| `children`           | `(opaque)`                      | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |
 | `class`              | `(opaque)`                      | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                     |
 | `footer`             | `(opaque)`                      | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |
 | `header`             | `(opaque)`                      | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                  |

package/src/components/card/card.types.ts

@@ -39,12 +39,14 @@ type CardWithHeader = CardBase & {
 };
 /** Card with a title/description string API — simpler for standard cards. */
 type CardWithTitle = CardBase & {
+  /** Primary heading text rendered inside the card's header region. */
   title: string;
   /**
    * Heading level for the generated title. Defaults to `3`. Set this so the
    * card title nests correctly within the surrounding document outline.
    */
   headingLevel?: CardHeadingLevel;
+  /** Optional subheading rendered as a paragraph below the title inside the header. */
   description?: string;
   children: Snippet;
   footer?: Snippet;

package/src/components/chart.types.ts

@@ -39,17 +39,29 @@ export type ChartCartesianSeries = {
 };
 
 export type ChartSharedProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Accessible label for the chart. Required for screen readers. */
   label: string;
+  /** Optional description rendered below the label. */
   description?: string;
+  /** Pixel height of the chart viewport. Default `280`. */
   height?: number;
+  /** Configuration for the x-axis label and tick formatting. */
   xAxis?: ChartAxisConfiguration;
+  /** Configuration for the y-axis label and tick formatting. */
   yAxis?: ChartAxisConfiguration;
+  /** Where to render the series legend relative to the chart. Default `top`. */
   legendPosition?: ChartLegendPosition;
+  /** IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`. */
   hiddenSeriesIds?: string[];
+  /** Whether the chart is in a loading state. Default `false`. */
   loading?: boolean;
+  /** Custom data table caption; falls back to `label`. */
   dataTableCaption?: string;
+  /** Controls data table visibility. Default `screen-reader-only`. */
   dataTableVisibility?: ChartDataTableVisibility;
+  /** Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`. */
   maximumInteractivePoints?: number;
+  /** Custom class applied to the root element. */
   class?: string;
   empty?: Snippet;
   loadingContent?: Snippet;