@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/access-gate/index.ts

@@ -0,0 +1,6 @@
+import './access-gate.css';
+import AccessGate from './access-gate.svelte';
+
+export default AccessGate;
+export type { AccessGateProps, AccessGateVariant } from './access-gate.types.ts';
+export { AccessGate };

package/src/components/accordion/README.md

@@ -27,10 +27,11 @@ The leaf remains importable individually for à-la-carte builds — see
 
 <!-- generated:props:start -->
 
-| Prop       | Type      | Required | Default | Description                                               |
-| ---------- | --------- | -------- | ------- | --------------------------------------------------------- |
-| `class`    | `string`  | no       | —       | Additional CSS class merged with `.cinder-accordion`.     |
-| `multiple` | `boolean` | no       | `false` | When true, multiple items may be expanded simultaneously. |
+| Prop       | Type       | Required | Default | Description                                                                                        |
+| ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional CSS class merged with `.cinder-accordion`.                                              |
+| `multiple` | `boolean`  | no       | `false` | When true, multiple items may be expanded simultaneously.                                          |
+| `children` | `(opaque)` | yes      | —       | AccordionItem children. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/accordion/accordion.examples.json

@@ -8,7 +8,7 @@
       "title": "Basic accordion",
       "description": "Single-select: opening one item closes the others. Uses the Accordion namespace API.",
       "featured": true,
-      "code": "<script lang=\"ts\">\n  import { Accordion } from '@lostgradient/cinder/accordion';\n  let expandedIds = $state<string[]>([]);\n</script>\n\n<Accordion bind:expandedIds>\n  <Accordion.Item id=\"item-1\" title=\"What is Cinder?\">\n    Cinder is a Svelte 5 design system built for composability and accessibility.\n  </Accordion.Item>\n  <Accordion.Item id=\"item-2\" title=\"How do I install it?\">\n    Run <code>bun add @lostgradient/cinder</code> and import components from\n    <code>@lostgradient/cinder</code> or via subpath imports.\n  </Accordion.Item>\n  <Accordion.Item id=\"item-3\" title=\"Does it support SSR?\">\n    Yes — every component is SSR-safe and renders meaningful HTML before hydration.\n  </Accordion.Item>\n</Accordion>\n"
+      "code": "<script lang=\"ts\">\n  import { Accordion } from '@lostgradient/cinder/accordion';\n\n  let expandedIds = $state<string[]>([]);\n</script>\n\n<Accordion bind:expandedIds>\n  <Accordion.Item id=\"item-1\" title=\"What is Cinder?\">\n    Cinder is a Svelte 5 design system built for composability and accessibility.\n  </Accordion.Item>\n  <Accordion.Item id=\"item-2\" title=\"How do I install it?\">\n    Run <code>bun add @lostgradient/cinder</code> and import components from\n    <code>@lostgradient/cinder</code> or via subpath imports.\n  </Accordion.Item>\n  <Accordion.Item id=\"item-3\" title=\"Does it support SSR?\">\n    Yes — every component is SSR-safe and renders meaningful HTML before hydration.\n  </Accordion.Item>\n</Accordion>\n"
     },
     {
       "id": "disabled",

package/src/components/accordion/accordion.svelte

@@ -8,9 +8,16 @@
    * @tag collapsible
    * @useWhen Progressively disclosing several sections of content that share a parent heading.
    * @useWhen Letting the consumer expand one or multiple panels at once via the multiple prop.
-   * @avoidWhen Switching between mutually exclusive views of the same region — use tabs instead.
-   * @avoidWhen Hiding a single optional region — use a plain disclosure or details element.
+   * @avoidWhen Switching between mutually exclusive views of the same region. | tabs
+   * @avoidWhen Hiding a single optional region — reach for a plain disclosure instead. | collapsible
    * @related accordion-item, tabs, tree
+   * @a11yPattern WAI-ARIA Accordion
+   * @keyboardShortcut Tab | Moves focus to the next focusable element (accordion header buttons are in the natural tab order).
+   * @keyboardShortcut Shift + Tab | Moves focus to the previous focusable element.
+   * @keyboardShortcut Enter / Space | When focus is on a header button, toggles the associated panel open or closed.
+   * @a11yNote Each trigger is a native button exposing aria-expanded and aria-controls, so screen readers announce open/closed state.
+   * @a11yNote Panels intentionally omit role="region" to keep the page's landmark list clean.
+   * @a11yNote Disabled items set the native disabled attribute on their trigger, removing them from the tab order.
    */
   export type { AccordionContext, AccordionProps } from './accordion.types.ts';
 </script>

package/src/components/accordion-item/README.md

@@ -17,12 +17,13 @@ required.
 
 <!-- generated:props:start -->
 
-| Prop       | Type      | Required | Default | Description                                                |
-| ---------- | --------- | -------- | ------- | ---------------------------------------------------------- |
-| `class`    | `string`  | no       | —       | Additional CSS class merged with `.cinder-accordion-item`. |
-| `disabled` | `boolean` | no       | `false` | When true, the item cannot be toggled.                     |
-| `id`       | `string`  | yes      | —       | Unique identifier matched against Accordion's expandedIds. |
-| `title`    | `string`  | yes      | —       | Visible header label for the item.                         |
+| Prop       | Type       | Required | Default | Description                                                                                                                  |
+| ---------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional CSS class merged with `.cinder-accordion-item`.                                                                   |
+| `disabled` | `boolean`  | no       | `false` | When true, the item cannot be toggled.                                                                                       |
+| `id`       | `string`   | yes      | —       | Unique identifier matched against Accordion's expandedIds.                                                                   |
+| `title`    | `string`   | yes      | —       | Visible header label for the item.                                                                                           |
+| `children` | `(opaque)` | yes      | —       | Panel content rendered when the item is expanded. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/alert/README.md

@@ -16,11 +16,14 @@ A status message that communicates contextual feedback and can optionally be dis
 
 <!-- generated:props:start -->
 
-| Prop          | Type                                                              | Required | Default  | Description                                                                        |
-| ------------- | ----------------------------------------------------------------- | -------- | -------- | ---------------------------------------------------------------------------------- |
-| `class`       | `string`                                                          | no       | —        | Custom class merged with `.cinder-alert`.                                          |
-| `dismissible` | `boolean`                                                         | no       | `false`  | Allow the alert to be dismissed.                                                   |
-| `variant`     | `"info"` \| `"success"` \| `"warning"` \| `"error"` \| `"danger"` | no       | `"info"` | Visual style. `danger` is an accepted alias for `error` — both render identically. |
+| Prop          | Type                                                              | Required | Default  | Description                                                                                                                |
+| ------------- | ----------------------------------------------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`                                                          | no       | —        | Custom class merged with `.cinder-alert`.                                                                                  |
+| `dismissible` | `boolean`                                                         | no       | `false`  | Allow the alert to be dismissed.                                                                                           |
+| `variant`     | `"info"` \| `"success"` \| `"warning"` \| `"error"` \| `"danger"` | no       | `"info"` | Visual style. `danger` is an accepted alias for `error` — both render identically.                                         |
+| `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. |
+| `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. |
+| `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. |
 
 <!-- generated:props:end -->
 

package/src/components/alert-dialog/README.md

@@ -15,13 +15,13 @@ The key distinction between AlertDialog and ConfirmDialog is _who initiates_ the
 - ConfirmDialog is for user-initiated actions that need a safety gate. Pressing Escape means "never mind" — a safe, expected exit. This includes high-impact destructive actions the user initiated, even ones that affect other people.
 - AlertDialog is for conditions the _system_ surfaces that require the user to acknowledge before continuing. Pressing Escape would bypass acknowledgement, which is unsafe because the session state has already changed and proceeding without reading the message is incorrect.
 
-## When to use
+## Choosing this component
 
 - Session expiry, authentication loss, or network disconnection that requires the user to re-authenticate before continuing.
 - System-level errors or process failures where the user must acknowledge the condition before taking any other action.
 - Any situation where the dialog is triggered by a system event — not a user click — and dismissal by Escape or backdrop click would be incorrect because the user _must_ read and respond.
 
-## When not to use
+## Choosing something else
 
 - User-initiated destructive actions (including high-impact ones like "Delete workspace" or "Remove all collaborators") — use [`ConfirmDialog`](../confirm-dialog/README.md). Even when the action is irreversible or affects other people, Escape is a valid "never mind" because the _user_ chose to open the dialog. ConfirmDialog's cancel-button autofocus is the right affordance.
 - Rich body content (markup, lists, multiple paragraphs) — `description` is a plain-text string. For rich body, compose [`Modal`](../modal/README.md) with `role="alertdialog"` directly (see Modal's `role` prop documentation for the required companion props).
@@ -43,18 +43,18 @@ The key distinction between AlertDialog and ConfirmDialog is _who initiates_ the
 
 <!-- generated:props:start -->
 
-| Prop               | Type       | Required | Default | Description                                                                                                                |
-| ------------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `acknowledgeLabel` | `string`   | no       | —       |                                                                                                                            |
-| `cancelLabel`      | `string`   | no       | —       |                                                                                                                            |
-| `class`            | `string`   | no       | —       |                                                                                                                            |
-| `description`      | `string`   | yes      | —       |                                                                                                                            |
-| `destructive`      | `boolean`  | no       | —       |                                                                                                                            |
-| `open`             | `boolean`  | yes      | —       |                                                                                                                            |
-| `title`            | `string`   | yes      | —       |                                                                                                                            |
-| `onacknowledge`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `oncancel`         | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `triggerRef`       | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop               | Type       | Required | Default | Description                                                                                                                                                                           |
+| ------------------ | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `acknowledgeLabel` | `string`   | no       | —       | Label for the primary acknowledgement button. Default `OK`.                                                                                                                           |
+| `cancelLabel`      | `string`   | no       | —       | Label for the optional cancel button. When omitted, no cancel button is rendered.                                                                                                     |
+| `class`            | `string`   | no       | —       | Additional class names merged with the component's root class.                                                                                                                        |
+| `description`      | `string`   | yes      | —       | Explanatory paragraph displayed in the dialog body and wired to the dialog via aria-describedby.                                                                                      |
+| `destructive`      | `boolean`  | no       | —       | When true, styles the acknowledgement button as a danger action and, when a cancel button is rendered, gives it initial focus instead of the acknowledgement button. Default `false`. |
+| `open`             | `boolean`  | yes      | —       | Controls whether the alert dialog is open; bindable for controlled usage.                                                                                                             |
+| `title`            | `string`   | yes      | —       | Text rendered as the dialog's visible heading and accessible label.                                                                                                                   |
+| `onacknowledge`    | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                            |
+| `oncancel`         | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                            |
+| `triggerRef`       | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                               |
 
 <!-- generated:props:end -->
 

package/src/components/alert-dialog/alert-dialog.types.ts

@@ -1,12 +1,19 @@
 export type AlertDialogProps = {
+  /** Controls whether the alert dialog is open; bindable for controlled usage. */
   open: boolean;
+  /** Text rendered as the dialog's visible heading and accessible label. */
   title: string;
+  /** Explanatory paragraph displayed in the dialog body and wired to the dialog via aria-describedby. */
   description: string;
+  /** Label for the primary acknowledgement button. Default `OK`. */
   acknowledgeLabel?: string;
+  /** Label for the optional cancel button. When omitted, no cancel button is rendered. */
   cancelLabel?: string;
+  /** When true, styles the acknowledgement button as a danger action and, when a cancel button is rendered, gives it initial focus instead of the acknowledgement button. Default `false`. */
   destructive?: boolean;
   onacknowledge: () => void;
   oncancel?: () => void;
   triggerRef?: HTMLElement | null;
+  /** Additional class names merged with the component's root class. */
   class?: string;
 };

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

@@ -26,22 +26,24 @@ Filled SVG area chart for showing magnitude and cumulative trends across an orde
 
 <!-- generated:props:start -->
 
-| Prop                       | Type                                                                                                                   | Required | Default | Description |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
-| `class`                    | `string`                                                                                                               | no       | —       |             |
-| `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`                     | `"single"` \| `"stacked"`                                                                                              | no       | —       |             |
-| `series`                   | ({ color?: `string`; data: ({ x: `string` \| `number`; y?: `number` \| `null` })[]; id: `string`; label: `string` })[] | yes      | —       |             |
-| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       |             |
-| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       |             |
+| Prop                       | Type                                                                                                                   | Required | Default | Description                                                                                                                |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`                    | `string`                                                                                                               | no       | —       | Custom class applied to the root element.                                                                                  |
+| `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`                     | `"single"` \| `"stacked"`                                                                                              | no       | —       | Area rendering mode. Default `single`.                                                                                     |
+| `series`                   | ({ color?: `string`; data: ({ x: `string` \| `number`; y?: `number` \| `null` })[]; id: `string`; label: `string` })[] | yes      | —       | Series rendered as independent filled areas or stacked areas.                                                              |
+| `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/area-chart/area-chart.examples.json

@@ -13,6 +13,7 @@
       "id": "single-series",
       "title": "Usage area",
       "description": "A single-series area chart for product usage.",
+      "featured": true,
       "code": "<script lang=\"ts\">\n  import { AreaChart } from '@lostgradient/cinder/area-chart';\n\n  const series = [\n    {\n      id: 'usage',\n      label: 'Usage',\n      data: [\n        { x: 'Jan', y: 44 },\n        { x: 'Feb', y: 61 },\n        { x: 'Mar', y: 79 },\n      ],\n    },\n  ];\n</script>\n\n<AreaChart label=\"Product usage\" {series} />\n"
     },
     {

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

@@ -30,18 +30,32 @@ export type AreaChartSchemaSeries = {
 };
 
 export type AreaChartSchemaProps = {
+  /** 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;
+  /** Series rendered as independent filled areas or stacked areas. */
   series: AreaChartSchemaSeries[];
+  /** Area rendering mode. Default `single`. */
   mode?: AreaChartMode;
 };

package/src/components/aspect-ratio/README.md

@@ -30,12 +30,13 @@ For iframe and video embeds, make the child fill the positioned wrapper:
 
 <!-- generated:props:start -->
 
-| Prop       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default    | Description                                                             |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------- | ----------------------------------------------------------------------- |
-| `as`       | `"object"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"caption"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"label"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | `"div"`    | Element tag to render.                                                  |
-| `class`    | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —          | Additional classes merged onto the root element.                        |
-| `overflow` | `"hidden"` \| `"visible"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `"hidden"` | Overflow behavior for overflowing content.                              |
-| `ratio`    | `string` \| `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | no       | `"16/9"`   | Aspect ratio to apply. Accepts any valid native CSS aspect-ratio value. |
+| Prop       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default    | Description                                                                                                                |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `as`       | `"object"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"caption"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"label"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | `"div"`    | Element tag to render.                                                                                                     |
+| `class`    | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —          | Additional classes merged onto the root element.                                                                           |
+| `overflow` | `"hidden"` \| `"visible"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `"hidden"` | Overflow behavior for overflowing content.                                                                                 |
+| `ratio`    | `string` \| `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | no       | `"16/9"`   | Aspect ratio to apply. Accepts any valid native CSS aspect-ratio value.                                                    |
+| `children` | `(opaque)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | yes      | —          | Required content rendered inside the ratio box. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/autocomplete/README.md

@@ -18,20 +18,20 @@ Free-form text input with suggestion hints.
 
 | Prop                    | Type       | Required | Default | Description                                                                                                                |
 | ----------------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`                 | `string`   | no       | —       |                                                                                                                            |
-| `description`           | `string`   | no       | —       |                                                                                                                            |
-| `disabled`              | `boolean`  | no       | —       |                                                                                                                            |
-| `emptyMessage`          | `string`   | no       | —       |                                                                                                                            |
-| `error`                 | `string`   | no       | —       |                                                                                                                            |
-| `id`                    | `string`   | no       | —       |                                                                                                                            |
-| `label`                 | `string`   | no       | —       |                                                                                                                            |
-| `loadingMessage`        | `string`   | no       | —       |                                                                                                                            |
-| `maxVisibleSuggestions` | `number`   | no       | —       |                                                                                                                            |
-| `minQueryLength`        | `number`   | no       | —       |                                                                                                                            |
-| `placeholder`           | `string`   | no       | —       |                                                                                                                            |
-| `readonly`              | `boolean`  | no       | —       |                                                                                                                            |
-| `required`              | `boolean`  | no       | —       |                                                                                                                            |
-| `value`                 | `string`   | no       | —       |                                                                                                                            |
+| `class`                 | `string`   | no       | —       | Additional class names merged onto the root wrapper element.                                                               |
+| `description`           | `string`   | no       | —       | Helper text rendered below the input and associated via `aria-describedby`.                                                |
+| `disabled`              | `boolean`  | no       | —       | When true, disables the input and prevents interaction, matching the native `disabled` attribute.                          |
+| `emptyMessage`          | `string`   | no       | —       | Message shown in the listbox when the suggestion source returns no results. Default `"No suggestions"`.                    |
+| `error`                 | `string`   | no       | —       | Error message rendered below the input; also sets `aria-invalid` on the input.                                             |
+| `id`                    | `string`   | no       | —       | HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes.                                   |
+| `label`                 | `string`   | no       | —       | Visible label text rendered above the input and linked via `for`/`id`.                                                     |
+| `loadingMessage`        | `string`   | no       | —       | Message shown in the listbox while the suggestion source is fetching results. Default `"Loading suggestions"`.             |
+| `maxVisibleSuggestions` | `number`   | no       | —       | Maximum number of suggestions rendered in the listbox at once. Default `50`.                                               |
+| `minQueryLength`        | `number`   | no       | —       | Minimum number of characters the user must type before suggestions are requested. Default `1`.                             |
+| `placeholder`           | `string`   | no       | —       | Placeholder text shown inside the input when it is empty.                                                                  |
+| `readonly`              | `boolean`  | no       | —       | When true, the input value cannot be changed by the user, matching the native `readonly` attribute.                        |
+| `required`              | `boolean`  | no       | —       | Marks the input as required for form validation, matching the native `required` attribute.                                 |
+| `value`                 | `string`   | no       | —       | Bindable current text value of the input.                                                                                  |
 | `oncomplete`            | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `oninput`               | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `suggestionSource`      | `(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/autocomplete/autocomplete.css

@@ -58,9 +58,16 @@
     color: var(--cinder-text-muted);
   }
 
-  .cinder-autocomplete__option[data-cinder-active] {
-    background: var(--cinder-surface-raised);
-  }
+  /*
+   * The active/keyboard-highlighted row treatment is owned by the shared
+   * `.cinder-_option-row[data-cinder-active]` rules in
+   * `styles/components/_floating-surface.css`: a `--cinder-surface-hover`
+   * background plus an inset `--cinder-ring-color` ring (and a forced-colors
+   * `outline: Highlight` fallback). A component-local override here previously
+   * pinned the background to `--cinder-surface-raised` — identical to the
+   * panel — so the highlighted option was invisible in light mode. Do not
+   * reintroduce it; inherit the shared row treatment instead.
+   */
 
   .cinder-autocomplete__option-text {
     display: grid;

package/src/components/autocomplete/autocomplete.examples.json

@@ -7,13 +7,14 @@
       "id": "async",
       "title": "Async source",
       "description": "Remote-style source with a loading row and stale-request cancellation.",
-      "code": "<script lang=\"ts\">\n  import Autocomplete from '@lostgradient/cinder/autocomplete';\n\n  const cities = [\n    { value: 'Austin, Texas', description: 'United States' },\n    { value: 'Auckland, New Zealand', description: 'New Zealand' },\n    { value: 'Aurora, Colorado', description: 'United States' },\n    { value: 'Berlin, Germany', description: 'Germany' },\n    { value: 'Bristol, England', description: 'United Kingdom' },\n  ];\n\n  let value = $state('');\n\n  async function suggestionSource(query: string, context: { signal: AbortSignal }) {\n    await new Promise<void>((resolve, reject) => {\n      const timeout = setTimeout(resolve, 350);\n      context.signal.addEventListener(\n        'abort',\n        () => {\n          clearTimeout(timeout);\n          reject(new DOMException('Aborted', 'AbortError'));\n        },\n        { once: true },\n      );\n    });\n\n    return cities.filter((city) => city.value.toLowerCase().includes(query.toLowerCase()));\n  }\n</script>\n\n<Autocomplete\n  id=\"autocomplete-async\"\n  label=\"Destination city\"\n  placeholder=\"Type a city\"\n  {suggestionSource}\n  bind:value\n/>\n"
+      "code": "<script lang=\"ts\">\n  import Autocomplete from '@lostgradient/cinder/autocomplete';\n\n  const cities = [\n    { value: 'Austin, Texas', description: 'United States' },\n    { value: 'Auckland, New Zealand', description: 'New Zealand' },\n    { value: 'Aurora, Colorado', description: 'United States' },\n    { value: 'Berlin, Germany', description: 'Germany' },\n    { value: 'Bristol, England', description: 'United Kingdom' },\n  ];\n\n  let value = $state('');\n\n  async function suggestionSource(query: string, context: { signal: AbortSignal }) {\n    await new Promise<void>((resolve, reject) => {\n      const timeout = setTimeout(resolve, 350);\n      context.signal.addEventListener(\n        'abort',\n        () => {\n          clearTimeout(timeout);\n          reject(new DOMException('Aborted', 'AbortError'));\n        },\n        { once: true },\n      );\n    });\n\n    return cities.filter((city) => city.value.toLowerCase().includes(query.toLowerCase()));\n  }\n</script>\n\n<Autocomplete\n  id=\"field\"\n  label=\"Destination city\"\n  placeholder=\"Type a city\"\n  {suggestionSource}\n  bind:value\n/>\n"
     },
     {
       "id": "basic",
       "title": "Basic autocomplete",
       "description": "Free-form text stays editable while the suggestion list offers completions.",
-      "code": "<script lang=\"ts\">\n  import Autocomplete from '@lostgradient/cinder/autocomplete';\n\n  const fruits = [\n    { value: 'apple', label: 'Apple', description: 'Classic pie filling' },\n    { value: 'apricot', label: 'Apricot', description: 'Stone fruit' },\n    { value: 'banana', label: 'Banana', description: 'Tropical staple' },\n    { value: 'blackberry', label: 'Blackberry', description: 'Late-summer berry' },\n    { value: 'blueberry', label: 'Blueberry', description: 'Breakfast favorite' },\n    { value: 'grapefruit', label: 'Grapefruit', description: 'Tart citrus' },\n  ];\n\n  let value = $state('');\n</script>\n\n<Autocomplete\n  id=\"autocomplete-basic\"\n  label=\"Favorite fruit\"\n  placeholder=\"Type a fruit\"\n  suggestionSource={(query: string) =>\n    fruits.filter((fruit) => fruit.label?.toLowerCase().includes(query.toLowerCase()))}\n  bind:value\n/>\n"
+      "featured": true,
+      "code": "<script lang=\"ts\">\n  import Autocomplete from '@lostgradient/cinder/autocomplete';\n\n  const fruits = [\n    { value: 'apple', label: 'Apple', description: 'Classic pie filling' },\n    { value: 'apricot', label: 'Apricot', description: 'Stone fruit' },\n    { value: 'banana', label: 'Banana', description: 'Tropical staple' },\n    { value: 'blackberry', label: 'Blackberry', description: 'Late-summer berry' },\n    { value: 'blueberry', label: 'Blueberry', description: 'Breakfast favorite' },\n    { value: 'grapefruit', label: 'Grapefruit', description: 'Tart citrus' },\n  ];\n\n  let value = $state('');\n</script>\n\n<Autocomplete\n  id=\"field\"\n  label=\"Favorite fruit\"\n  placeholder=\"Type a fruit\"\n  suggestionSource={(query: string) =>\n    fruits.filter((fruit) => fruit.label?.toLowerCase().includes(query.toLowerCase()))}\n  bind:value\n/>\n"
     },
     {
       "id": "inside-form-field",

package/src/components/autocomplete/autocomplete.types.ts

@@ -22,20 +22,34 @@ export type AutocompleteSuggestionSource = (
 ) => AutocompleteSuggestion[] | Promise<AutocompleteSuggestion[]>;
 
 export type AutocompleteSchemaProps = {
+  /** HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. */
   id?: string;
+  /** Bindable current text value of the input. */
   value?: string;
   suggestionSource?: AutocompleteSuggestionSource;
+  /** Visible label text rendered above the input and linked via `for`/`id`. */
   label?: string;
+  /** Helper text rendered below the input and associated via `aria-describedby`. */
   description?: string;
+  /** Error message rendered below the input; also sets `aria-invalid` on the input. */
   error?: string;
+  /** Minimum number of characters the user must type before suggestions are requested. Default `1`. */
   minQueryLength?: number;
+  /** Maximum number of suggestions rendered in the listbox at once. Default `50`. */
   maxVisibleSuggestions?: number;
+  /** Placeholder text shown inside the input when it is empty. */
   placeholder?: string;
+  /** When true, disables the input and prevents interaction, matching the native `disabled` attribute. */
   disabled?: boolean;
+  /** Marks the input as required for form validation, matching the native `required` attribute. */
   required?: boolean;
+  /** When true, the input value cannot be changed by the user, matching the native `readonly` attribute. */
   readonly?: boolean;
+  /** Message shown in the listbox when the suggestion source returns no results. Default `"No suggestions"`. */
   emptyMessage?: string;
+  /** Message shown in the listbox while the suggestion source is fetching results. Default `"Loading suggestions"`. */
   loadingMessage?: string;
+  /** Additional class names merged onto the root wrapper element. */
   class?: string;
   oninput?: (value: string) => void;
   oncomplete?: (suggestion: AutocompleteSuggestion) => void;

package/src/components/avatar/README.md

@@ -16,14 +16,14 @@ Displays a user's profile photo, initials, or fallback icon at a consistent size
 
 <!-- generated:props:start -->
 
-| Prop    | Type                                           | Required | Default | Description                                                                                                     |
-| ------- | ---------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
-| `alt`   | `string`                                       | no       | —       | Alternative text for the image. Defaults to `name` when present.                                                |
-| `name`  | `string`                                       | no       | —       | Display name used to compute initials when no image is available. Also used as the default `alt` for the image. |
-| `shape` | `"circle"` \| `"square"`                       | no       | —       | Shape. Default `circle`.                                                                                        |
-| `size`  | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Size token. Default `md`.                                                                                       |
-| `src`   | `string`                                       | no       | —       | Image source. When omitted, the initials fallback renders.                                                      |
-| `class` | `(opaque)`                                     | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.         |
+| Prop    | Type                                           | Required | Default | Description                                                                                                                     |
+| ------- | ---------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `alt`   | `string`                                       | no       | —       | Alternative text for the image. Defaults to `name` when present.                                                                |
+| `name`  | `string`                                       | no       | —       | Display name used to compute initials when no image is available. Also used as the default `alt` for the image.                 |
+| `shape` | `"circle"` \| `"square"`                       | no       | —       | Shape. Default `circle`.                                                                                                        |
+| `size`  | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Size token. Default `md`.                                                                                                       |
+| `src`   | `string`                                       | no       | —       | Image source. When omitted, the initials fallback renders.                                                                      |
+| `class` | `(opaque)`                                     | no       | —       | Additional class names merged with `.cinder-avatar`. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/avatar/avatar.css

@@ -11,6 +11,7 @@
     justify-content: center;
     overflow: hidden;
     background: var(--cinder-surface-inset);
+    border: 1px solid var(--cinder-border-muted);
     color: var(--cinder-text-muted);
     font-weight: var(--cinder-font-medium);
     user-select: none;

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

@@ -7,6 +7,12 @@ export type AvatarShape = 'circle' | 'square';
  * Renders an image when `src` is supplied; falls back to initials computed
  * from `name` when the image is missing or fails to load. The `name` prop
  * is also used for the accessible name when no `alt` is supplied.
+ *
+ * When neither `src` nor `name` is provided, a decorative placeholder
+ * (`aria-hidden`) renders and the avatar has no accessible name. If such a
+ * placeholder-only avatar still needs to be announced (e.g. an "unassigned"
+ * slot), supply an `aria-label` via the forwarded rest props — it lands on
+ * the root element and names the avatar.
  */
 export type AvatarProps = HTMLAttributes<HTMLSpanElement> & {
   /** Image source. When omitted, the initials fallback renders. */

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

@@ -16,16 +16,17 @@ Overlapping collaborator stack built on Avatar, with focusable names and an over
 
 <!-- generated:props:start -->
 
-| Prop            | Type                                                | Required | Default         | Description                                                                      |
-| --------------- | --------------------------------------------------- | -------- | --------------- | -------------------------------------------------------------------------------- |
-| `avatars`       | { id?: `string`; name: `string`; src?: `string` }[] | yes      | —               | Collaborators to render in the stack.                                            |
-| `class`         | `string`                                            | no       | —               | Additional class names merged with `.cinder-avatar-group`.                       |
-| `maxVisible`    | `number`                                            | no       | `5`             | Maximum visible avatars before overflow.                                         |
-| `overflowLabel` | `string`                                            | no       | —               | Accessible label for the overflow indicator.                                     |
-| `overlap`       | `string`                                            | no       | `"0.75rem"`     | Non-negative CSS length token for the amount each item overlaps its predecessor. |
-| `shape`         | `"circle"` \| `"square"`                            | no       | `"circle"`      | Shape forwarded to each visible Avatar.                                          |
-| `size`          | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`      | no       | `"md"`          | Size token forwarded to each visible Avatar.                                     |
-| `zOrder`        | `"first-on-top"` \| `"last-on-top"`                 | no       | `"last-on-top"` | Stacking order for visible avatars.                                              |
+| Prop            | Type                                                | Required | Default           | Description                                                                      |
+| --------------- | --------------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------- |
+| `avatars`       | { id?: `string`; name: `string`; src?: `string` }[] | yes      | —                 | Collaborators to render in the stack.                                            |
+| `class`         | `string`                                            | no       | —                 | Additional class names merged with `.cinder-avatar-group`.                       |
+| `label`         | `string`                                            | no       | `"Collaborators"` | Accessible name for the avatar stack list.                                       |
+| `maxVisible`    | `number`                                            | no       | `5`               | Maximum visible avatars before overflow.                                         |
+| `overflowLabel` | `string`                                            | no       | —                 | Accessible label for the overflow indicator.                                     |
+| `overlap`       | `string`                                            | no       | `"0.75rem"`       | Non-negative CSS length token for the amount each item overlaps its predecessor. |
+| `shape`         | `"circle"` \| `"square"`                            | no       | `"circle"`        | Shape forwarded to each visible Avatar.                                          |
+| `size`          | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`      | no       | `"md"`            | Size token forwarded to each visible Avatar.                                     |
+| `zOrder`        | `"first-on-top"` \| `"last-on-top"`                 | no       | `"last-on-top"`   | Stacking order for visible avatars.                                              |
 
 <!-- generated:props:end -->
 

package/src/components/avatar-group/avatar-group.svelte

@@ -35,11 +35,26 @@
     size = 'md',
     shape = 'circle',
     overflowLabel,
+    label = 'Collaborators',
+    'aria-label': consumerAriaLabel,
     class: className,
     style,
     ...rest
   }: AvatarGroupProps = $props();
 
+  // A consumer-provided `aria-label` wins over the `label` default; destructuring
+  // it out of `rest` (rather than letting `{...rest}` spread it) lets us resolve
+  // the accessible name explicitly instead of having the hard-coded default
+  // silently clobber it after the spread. An empty or whitespace-only
+  // `aria-label` is treated as absent (rendering `aria-label=""` would suppress
+  // the accessible-name computation per ARIA §4.3.2 without naming the region),
+  // so it falls back to `label` rather than producing a nameless `role="list"`.
+  const accessibleName = $derived(
+    typeof consumerAriaLabel === 'string' && consumerAriaLabel.trim().length > 0
+      ? consumerAriaLabel
+      : label,
+  );
+
   const normalizedMaxVisible = $derived(normalizeMaxVisible(maxVisible));
   const visibleCount = $derived(Math.min(normalizedMaxVisible, avatars.length));
   const hiddenCount = $derived(Math.max(0, avatars.length - visibleCount));
@@ -121,6 +136,7 @@
   class={classNames('cinder-avatar-group', className)}
   style={rootStyle}
   role="list"
+  aria-label={accessibleName}
   data-cinder-size={size}
   data-cinder-shape={shape}
   data-cinder-z-order={zOrder}