@lostgradient/cinder 0.1.1 → 0.3.0

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;
@@ -71,14 +75,64 @@
     pointer-events: none;
   }
 
-  /*
- * SVG focus indicator: drop-shadow renders a visible ring around the focused
- * element on any background. Matches line-chart and area-chart.
- */
-  .cinder-bar-chart__focus-target:focus-visible {
-    stroke: var(--cinder-accent);
+  .cinder-bar-chart__focus-target:focus-visible:not([data-cinder-focus-ring-active='true']) {
+    fill: transparent;
+    stroke: var(--cinder-ring-color);
+    stroke-width: var(--cinder-ring-width);
+    vector-effect: non-scaling-stroke;
+    filter: none;
+  }
+
+  .cinder-bar-chart__focus-ring-layer {
+    pointer-events: none;
+  }
+
+  .cinder-bar-chart__focus-ring,
+  .cinder-bar-chart__focus-ring-halo,
+  .cinder-bar-chart__focus-ring-connector,
+  .cinder-bar-chart__focus-ring-dot {
+    fill: none;
+    pointer-events: none;
+    vector-effect: non-scaling-stroke;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
+  .cinder-bar-chart__focus-ring {
+    stroke: var(--cinder-ring-color);
     stroke-width: var(--cinder-ring-width);
-    filter: drop-shadow(0 0 var(--cinder-ring-width) var(--cinder-ring-color));
+    filter: none;
+  }
+
+  .cinder-bar-chart__focus-ring-halo {
+    stroke: var(--cinder-ring-offset-color);
+    stroke-width: calc(
+      var(--cinder-ring-width) + var(--cinder-ring-offset) + var(--cinder-ring-offset)
+    );
+    filter: none;
+  }
+
+  @media (forced-colors: active) {
+    .cinder-bar-chart__focus-ring-halo {
+      display: none;
+    }
+
+    .cinder-bar-chart__focus-ring,
+    .cinder-bar-chart__focus-ring-connector,
+    .cinder-bar-chart__focus-ring-dot {
+      fill: none;
+      stroke: ButtonText;
+      stroke-width: var(--cinder-ring-width);
+      filter: none;
+    }
+
+    .cinder-bar-chart__focus-target:focus-visible:not([data-cinder-focus-ring-active='true']) {
+      fill: transparent;
+      stroke: ButtonText;
+      stroke-width: var(--cinder-ring-width);
+      vector-effect: non-scaling-stroke;
+      filter: none;
+    }
   }
 
   .cinder-bar-chart__tick-label {

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

@@ -24,7 +24,12 @@
     dataTableClass,
     formatNumericValue,
     legendVisible,
+    type ChartTarget,
   } from '../../_internal/chart/chart-utilities.ts';
+  import {
+    DEFAULT_CHART_FOCUS_RING_STROKE_PADDING,
+    createBarFocusRingGeometry,
+  } from '../../_internal/chart/chart-focus-ring.ts';
   import { ChartInteraction } from '../../_internal/chart/chart-interaction.svelte.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import type { BarChartProps } from './bar-chart.types.ts';
@@ -96,6 +101,28 @@
       ? `${rootId}-table-guidance`
       : undefined,
   );
+  const focusedTarget = $derived.by(() => {
+    const currentTarget = interaction.focusedTarget;
+    if (!currentTarget) return undefined;
+    return model.targets.find((target) => target.id === currentTarget.id);
+  });
+  let keyboardFocusModality = $state(false);
+  let focusVisibleTargetId = $state<string>();
+  const focusRingTarget = $derived(
+    keyboardFocusModality && focusedTarget && focusVisibleTargetId === focusedTarget.id
+      ? focusedTarget
+      : undefined,
+  );
+  const barFocusRing = $derived(
+    focusRingTarget
+      ? createBarFocusRingGeometry({
+          target: focusRingTarget,
+          plotWidth: model.geometry.plotWidth,
+          plotHeight: model.geometry.plotHeight,
+          strokePadding: DEFAULT_CHART_FOCUS_RING_STROKE_PADDING,
+        })
+      : null,
+  );
 
   $effect(() => {
     assertValidNonNegativeInteger(
@@ -109,8 +136,44 @@
   $effect(() => {
     interaction.clearStaleTargets(loading, model.empty, model.targets);
   });
+
+  function rememberKeyboardFocusModality(event: KeyboardEvent): void {
+    if (
+      event.key === 'Tab' ||
+      event.key === 'Home' ||
+      event.key === 'End' ||
+      event.key.startsWith('Arrow')
+    ) {
+      keyboardFocusModality = true;
+    }
+  }
+
+  function clearKeyboardFocusModality(): void {
+    keyboardFocusModality = false;
+    focusVisibleTargetId = undefined;
+  }
+
+  function handleTargetFocus(target: ChartTarget): void {
+    interaction.focusedTarget = target;
+    focusVisibleTargetId = keyboardFocusModality ? target.id : undefined;
+  }
+
+  function handleTargetBlur(): void {
+    interaction.focusedTarget = undefined;
+    focusVisibleTargetId = undefined;
+  }
+
+  function handleTargetKeydown(event: KeyboardEvent): void {
+    rememberKeyboardFocusModality(event);
+    interaction.activateByKeyboard(event, rootElement!, model.targets, keyboardEnabled);
+  }
 </script>
 
+<svelte:window
+  onkeydown={rememberKeyboardFocusModality}
+  onpointerdown={clearKeyboardFocusModality}
+/>
+
 <figure
   {...rest}
   bind:this={rootElement}
@@ -160,7 +223,7 @@
         <title id="{rootId}-svg-title">{label}</title>
       {/if}
       <g transform={`translate(${model.geometry.marginLeft}, ${model.geometry.marginTop})`}>
-        {#each model.yTicks as tick, index}
+        {#each model.yTicks as tick, index (tick)}
           <!--
             Bar chart tick positions depend on orientation:
             - Vertical: y-axis labels appear left of the chart (same as line/area).
@@ -197,9 +260,13 @@
             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.label)}
+        {#each model.categoryTicks as tick (tick.categoryKey)}
           <!--
             Category axis labels differ by orientation:
             - Vertical: labels appear below bars (middle-anchored x, no baseline).
@@ -266,23 +333,41 @@
                 tabindex="0"
                 role="button"
                 data-cinder-target-id={target.id}
+                data-cinder-series-id={target.seriesId}
+                data-cinder-focus-ring-active={barFocusRing && focusRingTarget?.id === target.id
+                  ? 'true'
+                  : undefined}
                 aria-label={`${target.seriesLabel}, ${target.xLabel}, ${target.valueLabel}`}
                 aria-describedby={interaction.activeTarget?.id === target.id
                   ? `${rootId}-tooltip`
                   : undefined}
-                onfocus={() => (interaction.focusedTarget = target)}
-                onblur={() => (interaction.focusedTarget = undefined)}
-                onkeydown={(event) =>
-                  interaction.activateByKeyboard(
-                    event,
-                    rootElement!,
-                    model.targets,
-                    keyboardEnabled,
-                  )}
+                onfocus={() => handleTargetFocus(target)}
+                onblur={handleTargetBlur}
+                onkeydown={handleTargetKeydown}
               />
             {/each}
           {/if}
         {/if}
+        {#if barFocusRing}
+          <g class="cinder-bar-chart__focus-ring-layer" aria-hidden="true">
+            <rect
+              class="cinder-bar-chart__focus-ring-halo"
+              x={barFocusRing.x}
+              y={barFocusRing.y}
+              width={barFocusRing.width}
+              height={barFocusRing.height}
+              rx={barFocusRing.radius}
+            />
+            <rect
+              class="cinder-bar-chart__focus-ring"
+              x={barFocusRing.x}
+              y={barFocusRing.y}
+              width={barFocusRing.width}
+              height={barFocusRing.height}
+              rx={barFocusRing.radius}
+            />
+          </g>
+        {/if}
       </g>
     </svg>
     {#if interaction.activeTarget}<div
@@ -313,8 +398,8 @@
         ></thead
       >
       <tbody>
-        {#each model.tableRows as row}
-          {#each row.values as value}
+        {#each model.tableRows as row (row.categoryKey)}
+          {#each row.values as value (value.seriesId)}
             <tr
               ><th scope="row">{row.categoryLabel}</th><td>{value.seriesLabel}</td><td
                 >{value.valueLabel}</td

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

@@ -194,8 +194,8 @@
  * ---------------------------------------- */
 
   .cinder-button[data-cinder-variant='primary'] {
-    /* Ring uses the dedicated --cinder-ring-color (not the bright fill-accent):
-       the L=0.72 accent is the button face, so an accent ring would be invisible
+    /* Ring uses the dedicated --cinder-ring-color (not the fill-accent):
+       the accent is the button face, so an accent ring would be invisible
        against it and fail WCAG 1.4.11 (3:1) against the page. */
     --_cinder-button-ring: var(--cinder-ring-color);
     background: var(--cinder-accent);
@@ -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;
   }
@@ -423,7 +430,9 @@
  * hover paint when both states are active on hover-capable devices. Unwrapped
  * so they fire on tap. */
   .cinder-button[data-cinder-variant='primary']:active:not(:disabled):not([aria-disabled='true']) {
-    background: var(--cinder-accent-active);
+    /* Use the gentler on-fill pressed token so the --cinder-accent-contrast label stays AA-legible
+       on the pressed fill (the general --cinder-accent-active would drop the label below 4.5:1). */
+    background: var(--cinder-accent-active-on-fill);
   }
 
   .cinder-button[data-cinder-variant='secondary']:active:not(:disabled):not(

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",
@@ -25,6 +25,7 @@
       "id": "primary",
       "title": "Primary button",
       "description": "The default button variant.",
+      "featured": true,
       "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n</script>\n\n<Button label=\"Click me\" />\n"
     },
     {

package/src/components/button/button.svelte

@@ -48,6 +48,9 @@
     'aria-busy': consumerAriaBusy,
     'aria-label': ariaLabel,
     'aria-labelledby': ariaLabelledBy,
+    'aria-expanded': ariaExpanded,
+    'aria-controls': ariaControls,
+    'aria-haspopup': ariaHaspopup,
     ...rest
   }: ButtonProps = $props();
 
@@ -98,6 +101,9 @@
     | 'aria-busy'
     | 'aria-label'
     | 'aria-labelledby'
+    | 'aria-expanded'
+    | 'aria-controls'
+    | 'aria-haspopup'
   >;
   const buttonAttributes = rest as Omit<
     HTMLButtonAttributes,
@@ -109,6 +115,9 @@
     | 'aria-busy'
     | 'aria-label'
     | 'aria-labelledby'
+    | 'aria-expanded'
+    | 'aria-controls'
+    | 'aria-haspopup'
   >;
 
   // Branch-specific prop reads stay `$derived` because they extract a *value* off `rest`
@@ -212,6 +221,9 @@
     aria-busy={resolvedAriaBusy}
     aria-label={resolvedAriaLabel}
     aria-labelledby={resolvedAriaLabelledBy}
+    aria-expanded={ariaExpanded}
+    aria-controls={ariaControls}
+    aria-haspopup={ariaHaspopup}
     onclick={handleClick}
   >
     {@render buttonContent()}
@@ -227,6 +239,9 @@
     aria-busy={resolvedAriaBusy}
     aria-label={resolvedAriaLabel}
     aria-labelledby={resolvedAriaLabelledBy}
+    aria-expanded={ariaExpanded}
+    aria-controls={ariaControls}
+    aria-haspopup={ariaHaspopup}
     onclick={handleClick}
   >
     {@render buttonContent()}

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

@@ -0,0 +1,60 @@
+# CapabilityGate
+
+Present feature availability and next action for browser permission or support states, with accessible status text and focus management.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { CapabilityGate } from '@lostgradient/cinder/capability-gate';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- 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.
+
+### Avoid When
+
+- Performing the actual feature detection or permission request — wire that in userland.
+- Storing permission state — CapabilityGate is a pure presentation component.
+
+## Props
+
+<!-- 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       | —          | 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 -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->