@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/color-field/README.md

@@ -60,24 +60,24 @@ Moving the component across forms at runtime is not supported in v1.
 
 <!-- generated:props:start -->
 
-| Prop             | Type                                      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                 |
-| ---------------- | ----------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `alpha`          | `boolean`                                 | no       | —       | Accept and emit alpha when the parsed value has partial alpha. When `false` (default), `#RRGGBBAA` and `rgba()`/`hsla()` inputs are parsed but alpha is stripped on emit.                                                                                                                                                                   |
-| `ariaLabel`      | `string`                                  | no       | —       | Accessible label applied directly to the inner `<input>` when no `FormField` wraps it.                                                                                                                                                                                                                                                      |
-| `ariaLabelledby` | `string`                                  | no       | —       | Id of an external element that labels the inner `<input>`.                                                                                                                                                                                                                                                                                  |
-| `class`          | `string`                                  | no       | —       | Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`).                                                                                                                                                                                                                                                          |
-| `defaultValue`   | `string`                                  | no       | —       | Initial value when uncontrolled. Accepts any allowed `formats` input.                                                                                                                                                                                                                                                                       |
-| `disabled`       | `boolean`                                 | no       | —       | Disable the input.                                                                                                                                                                                                                                                                                                                          |
-| `enterBehavior`  | `"commit-then-submit"` \| `"commit-only"` | no       | —       | Commit-on-Enter behavior. Default `'commit-then-submit'`: - `'commit-then-submit'`: Enter commits the value, then lets the form's native submission proceed via `requestSubmit`. - `'commit-only'`: Enter commits and `preventDefault()`s, suppressing form submission (useful in dialogs / multi-field flows where Enter must not submit). |
-| `errorMessage`   | `string`                                  | no       | —       | Override the default parse-failure error message.                                                                                                                                                                                                                                                                                           |
-| `formats`        | (`"hex"` \| `"rgb"` \| `"hsl"`)[]         | no       | —       | Accepted _input_ formats. Defaults to `['hex', 'rgb', 'hsl']`. Output is always hex.                                                                                                                                                                                                                                                        |
-| `id`             | `string`                                  | yes      | —       | Inner `<input>` id. Required (mirrors Input).                                                                                                                                                                                                                                                                                               |
-| `name`           | `string`                                  | no       | —       | Form field name. When set, the hidden mirror input contributes the current committed hex value to native form submission.                                                                                                                                                                                                                   |
-| `placeholder`    | `string`                                  | no       | —       | Placeholder text for the inner `<input>`.                                                                                                                                                                                                                                                                                                   |
-| `readonly`       | `boolean`                                 | no       | —       | Render the inner `<input>` as read-only.                                                                                                                                                                                                                                                                                                    |
-| `required`       | `boolean`                                 | no       | —       | Mark the input as required for form submission and a11y.                                                                                                                                                                                                                                                                                    |
-| `value`          | `string`                                  | no       | —       | Controlled value as a hex string. One-way: parent sets, child reads. Not bindable — use `onchange` to observe commits. Accepts any color string the configured `formats` allow when set externally.                                                                                                                                         |
-| `onchange`       | `(opaque)`                                | no       | —       | Fires on successful blur-time commit when the canonical hex actually changes. Value callback by repo convention — not forwarded to the inner native `<input>`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                   |
+| Prop              | Type                                      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                 |
+| ----------------- | ----------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alpha`           | `boolean`                                 | no       | —       | Accept and emit alpha when the parsed value has partial alpha. When `false` (default), `#RRGGBBAA` and `rgba()`/`hsla()` inputs are parsed but alpha is stripped on emit.                                                                                                                                                                   |
+| `aria-label`      | `string`                                  | no       | —       | Accessible label applied directly to the inner `<input>` when no `FormField` wraps it.                                                                                                                                                                                                                                                      |
+| `aria-labelledby` | `string`                                  | no       | —       | Id of an external element that labels the inner `<input>`.                                                                                                                                                                                                                                                                                  |
+| `class`           | `string`                                  | no       | —       | Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`).                                                                                                                                                                                                                                                          |
+| `defaultValue`    | `string`                                  | no       | —       | Initial value when uncontrolled. Accepts any allowed `formats` input.                                                                                                                                                                                                                                                                       |
+| `disabled`        | `boolean`                                 | no       | —       | Disable the input.                                                                                                                                                                                                                                                                                                                          |
+| `enterBehavior`   | `"commit-then-submit"` \| `"commit-only"` | no       | —       | Commit-on-Enter behavior. Default `'commit-then-submit'`: - `'commit-then-submit'`: Enter commits the value, then lets the form's native submission proceed via `requestSubmit`. - `'commit-only'`: Enter commits and `preventDefault()`s, suppressing form submission (useful in dialogs / multi-field flows where Enter must not submit). |
+| `errorMessage`    | `string`                                  | no       | —       | Override the default parse-failure error message.                                                                                                                                                                                                                                                                                           |
+| `formats`         | (`"hex"` \| `"rgb"` \| `"hsl"`)[]         | no       | —       | Accepted _input_ formats. Defaults to `['hex', 'rgb', 'hsl']`. Output is always hex.                                                                                                                                                                                                                                                        |
+| `id`              | `string`                                  | yes      | —       | Inner `<input>` id. Required (mirrors Input).                                                                                                                                                                                                                                                                                               |
+| `name`            | `string`                                  | no       | —       | Form field name. When set, the hidden mirror input contributes the current committed hex value to native form submission.                                                                                                                                                                                                                   |
+| `placeholder`     | `string`                                  | no       | —       | Placeholder text for the inner `<input>`.                                                                                                                                                                                                                                                                                                   |
+| `readonly`        | `boolean`                                 | no       | —       | Render the inner `<input>` as read-only.                                                                                                                                                                                                                                                                                                    |
+| `required`        | `boolean`                                 | no       | —       | Mark the input as required for form submission and a11y.                                                                                                                                                                                                                                                                                    |
+| `value`           | `string`                                  | no       | —       | Controlled value as a hex string. One-way: parent sets, child reads. Not bindable — use `onchange` to observe commits. Accepts any color string the configured `formats` allow when set externally.                                                                                                                                         |
+| `onchange`        | `(opaque)`                                | no       | —       | Fires on successful blur-time commit when the canonical hex actually changes. Value callback by repo convention — not forwarded to the inner native `<input>`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                   |
 
 <!-- generated:props:end -->
 

package/src/components/color-field/color-field.svelte

@@ -36,8 +36,8 @@
     readonly = false,
     name,
     placeholder,
-    ariaLabel,
-    ariaLabelledby,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
     errorMessage,
     enterBehavior = 'commit-then-submit',
     onchange,

package/src/components/color-field/color-field.types.ts

@@ -35,9 +35,9 @@ export type ColorFieldProps = {
   /** Placeholder text for the inner `<input>`. */
   placeholder?: string;
   /** Accessible label applied directly to the inner `<input>` when no `FormField` wraps it. */
-  ariaLabel?: string;
+  'aria-label'?: string;
   /** Id of an external element that labels the inner `<input>`. */
-  ariaLabelledby?: string;
+  'aria-labelledby'?: string;
   /** Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`). */
   class?: string;
   /** Override the default parse-failure error message. */

package/src/components/color-swatch-picker/color-swatch-picker.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "color-swatch-picker",
+  "import": "@lostgradient/cinder/color-swatch-picker",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic color swatch picker",
+      "description": "Keyboard-navigable preset palette constrained to brand colors.",
+      "code": "<script lang=\"ts\">\n  import { ColorSwatchPicker } from '@lostgradient/cinder/color-swatch-picker';\n\n  const palette = [\n    { color: '#ef4444', name: 'Red' },\n    { color: '#f97316', name: 'Orange' },\n    { color: '#eab308', name: 'Yellow' },\n    { color: '#22c55e', name: 'Green' },\n    { color: '#3b82f6', name: 'Blue' },\n    { color: '#8b5cf6', name: 'Violet' },\n  ];\n\n  let selected = $state('#3b82f6');\n</script>\n\n<ColorSwatchPicker\n  colors={palette}\n  value={selected}\n  label=\"Accent color\"\n  onchange={(color) => (selected = color)}\n/>\n<p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">Selected: {selected}</p>\n"
+    }
+  ]
+}

package/src/components/color-swatch-picker/color-swatch-picker.svelte

@@ -15,7 +15,7 @@
 </script>
 
 <script lang="ts">
-  import type { ColorSwatchPickerProps } from './color-swatch-picker.types.ts';
+  import type { ColorSwatch, ColorSwatchPickerProps } from './color-swatch-picker.types.ts';
   import { tick, untrack } from 'svelte';
 
   import { classNames } from '../../utilities/class-names.ts';
@@ -43,6 +43,31 @@
   let internalValue = $state(untrack(() => defaultValue) ?? '');
   const selected = $derived(value ?? internalValue);
 
+  // Deduplicate swatches by color (first occurrence wins) so the keyed {#each}
+  // never receives duplicate keys and Svelte cannot throw each_key_duplicate.
+  // A dev warning is emitted when duplicates are found so the data author can fix
+  // their input, but the component continues to render the deduplicated list.
+  const renderableColors = $derived.by(() => {
+    const seen = new Set<string>();
+    const result: ColorSwatch[] = [];
+    let hasDuplicates = false;
+    for (const swatch of colors) {
+      if (seen.has(swatch.color)) {
+        hasDuplicates = true;
+      } else {
+        seen.add(swatch.color);
+        result.push(swatch);
+      }
+    }
+    if (hasDuplicates) {
+      devWarn(
+        '[ColorSwatchPicker] Duplicate color values detected in palette. ' +
+          'Only the first matching swatch will be shown as selected. Duplicates were removed.',
+      );
+    }
+    return result;
+  });
+
   // Track focus index driven by user interaction. null = derive from selection.
   let userFocusIndex = $state<number | null>(null);
 
@@ -53,25 +78,25 @@
   });
 
   const effectiveFocusIndex = $derived.by(() => {
-    if (colors.length === 0) return -1;
+    if (renderableColors.length === 0) return -1;
 
     // 1. User-driven focus if it points to a valid, non-item-disabled option.
     if (
       userFocusIndex !== null &&
-      userFocusIndex < colors.length &&
-      !colors[userFocusIndex]?.disabled
+      userFocusIndex < renderableColors.length &&
+      !renderableColors[userFocusIndex]?.disabled
     ) {
       return userFocusIndex;
     }
 
     // 2. Currently selected swatch if it exists and is not item-disabled.
-    const selectedIndex = colors.findIndex((s) => s.color === selected);
-    if (selectedIndex !== -1 && !colors[selectedIndex]?.disabled) {
+    const selectedIndex = renderableColors.findIndex((s) => s.color === selected);
+    if (selectedIndex !== -1 && !renderableColors[selectedIndex]?.disabled) {
       return selectedIndex;
     }
 
     // 3. First non-item-disabled option.
-    const firstEnabled = colors.findIndex((s) => !s.disabled);
+    const firstEnabled = renderableColors.findIndex((s) => !s.disabled);
     if (firstEnabled !== -1) return firstEnabled;
 
     // 4. First option in DOM order (ensures the control always has a tab stop).
@@ -82,19 +107,19 @@
   let liRefs: (HTMLLIElement | null)[] = $state([]);
 
   // Index of the first swatch (by DOM order) matching `selected` — for aria-selected.
-  const selectedIndex = $derived(colors.findIndex((s) => s.color === selected));
+  const selectedIndex = $derived(renderableColors.findIndex((s) => s.color === selected));
 
   function isItemDisabledForRoving(index: number): boolean {
-    return colors[index]?.disabled === true;
+    return renderableColors[index]?.disabled === true;
   }
 
   function isInteractive(index: number): boolean {
-    return !disabled && !colors[index]?.disabled;
+    return !disabled && !renderableColors[index]?.disabled;
   }
 
   function selectSwatch(index: number): void {
     if (!isInteractive(index)) return;
-    const swatch = colors[index];
+    const swatch = renderableColors[index];
     if (!swatch) return;
     internalValue = swatch.color;
     onchange?.(swatch.color);
@@ -112,7 +137,7 @@
       return;
     }
 
-    const newIndex = handleRovingKeydown(event, effectiveFocusIndex, colors.length, {
+    const newIndex = handleRovingKeydown(event, effectiveFocusIndex, renderableColors.length, {
       vertical: true,
       horizontal: layout === 'grid',
       isDisabled: isItemDisabledForRoving,
@@ -133,17 +158,6 @@
     userFocusIndex = index;
     selectSwatch(index);
   }
-
-  // Warn in dev mode when duplicate colors appear in the palette.
-  $effect(() => {
-    const colorValues = colors.map((c) => c.color);
-    if (new Set(colorValues).size !== colorValues.length) {
-      devWarn(
-        '[ColorSwatchPicker] Duplicate color values detected in palette. ' +
-          'Only the first matching swatch will be shown as selected.',
-      );
-    }
-  });
 </script>
 
 <ul
@@ -157,7 +171,7 @@
   data-cinder-layout={layout}
   onkeydown={handleKeydown}
 >
-  {#each colors as swatch, index (swatch.color + index)}
+  {#each renderableColors as swatch, index (swatch.color)}
     {@const isSelected = index === selectedIndex}
     {@const isDisabled = swatch.disabled === true}
     {@const contrastColor = pickContrastColor(swatch.color)}

package/src/components/combobox/README.md

@@ -21,13 +21,14 @@ Filterable dropdown that combines a text input with a selectable option list.
 | `aria-describedby`  | `string`   | no       | —       | External element id(s) to compose into `aria-describedby`. Composed after the component-generated description and error ids, matching the field-control contract in Select. Useful for tooltip ids, counter ids, or any external hint. |
 | `class`             | `string`   | no       | —       | Additional class names merged with `.cinder-combobox`.                                                                                                                                                                                 |
 | `description`       | `string`   | no       | —       | Helper text displayed below the input; wired via aria-describedby.                                                                                                                                                                     |
-| `disabled`          | `boolean`  | no       | —       | Disables the combobox.                                                                                                                                                                                                                 |
+| `disabled`          | `boolean`  | no       | —       | Disables the combobox. Inherited from a wrapping FormField when unset.                                                                                                                                                                 |
 | `error`             | `string`   | no       | —       | Validation error message; sets aria-invalid="true".                                                                                                                                                                                    |
 | `id`                | `string`   | yes      | —       | Unique identifier — required for label association and ARIA wiring.                                                                                                                                                                    |
 | `inputValue`        | `string`   | no       | —       | Free-text input value (the text the user has typed). Bindable.                                                                                                                                                                         |
 | `label`             | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                                                                                                                                            |
 | `maxVisibleOptions` | `number`   | no       | —       | Hard cap on visible filtered options. Default 200.                                                                                                                                                                                     |
 | `placeholder`       | `string`   | no       | —       | Placeholder when no value is selected.                                                                                                                                                                                                 |
+| `required`          | `boolean`  | no       | —       | Marks the field required: renders the required marker on the label and sets `aria-required` on the input. Inherited from a wrapping FormField when unset.                                                                              |
 | `filter`            | `(opaque)` | no       | —       | Custom synchronous filter. Receives an option and the current input value; returns true to keep. Defaults to case-insensitive substring match on label. Not expressible in JSON Schema; see the component types for the signature.     |
 | `options`           | `(opaque)` | yes      | —       | Full set of options to filter. The sole inference source for T. Not expressible in JSON Schema; see the component types for the signature.                                                                                             |
 | `value`             | `(opaque)` | no       | —       | Currently selected value. Bindable. `''` when nothing is selected. Not expressible in JSON Schema; see the component types for the signature.                                                                                          |

package/src/components/combobox/combobox.svelte

@@ -19,12 +19,8 @@
   import type { ComboboxOption, ComboboxProps } from './combobox.types.ts';
   import { untrack } from 'svelte';
 
-  import {
-    ariaInvalid,
-    composeDescribedBy,
-    describeId,
-    errorId as buildErrorId,
-  } from '../../_internal/field-control.ts';
+  import { resolveFieldControl } from '../../_internal/field-control.ts';
+  import { getFormFieldContext } from '../../_internal/form-field-context.ts';
   import { pushEscapeHandler } from '../../_internal/overlay.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import Popover from '../popover/popover.svelte';
@@ -39,17 +35,38 @@
     filter,
     description,
     error,
-    disabled = false,
+    disabled,
+    required,
     maxVisibleOptions = 200,
     class: className,
     'aria-describedby': consumerDescribedBy,
   }: ComboboxProps<T> = $props();
 
+  const context = getFormFieldContext();
+  const field = $derived(
+    resolveFieldControl({
+      id,
+      generatedId: id,
+      context,
+      hasDescription: !!description,
+      hasError: !!error,
+      localIdNamespace: 'combobox',
+      consumerDescribedBy,
+      required,
+      disabled,
+    }),
+  );
+  const resolvedDisabled = $derived(field.disabled);
+  const resolvedRequired = $derived(field.required);
+  const describedBy = $derived(field.describedBy);
+
   const listboxId = $derived(`${id}-listbox`);
-  const descriptionId = $derived(describeId(id, !!description));
-  // errId only included in aria-describedby when error is active.
-  const errId = $derived(buildErrorId(id, !!error));
-  const describedBy = $derived(composeDescribedBy(descriptionId, errId, consumerDescribedBy));
+  const descriptionId = $derived(field.ownDescriptionId);
+  // Stable id for the always-in-DOM error live region when no error is active.
+  // Mirrors Select: avoids colliding with a wrapping FormField's error id.
+  const stableLocalErrorId = $derived(
+    context?.errorId === `${field.id}-error` ? `${field.id}-combobox-error` : `${field.id}-error`,
+  );
 
   const defaultFilter = (option: ComboboxOption<T>, query: string): boolean => {
     if (!query) return true;
@@ -125,7 +142,7 @@
   // top handler, so this combobox consumes Escape and `preventDefault()`s it
   // before the parent overlay ever sees the key — Escape dismisses just the
   // combobox, never the enclosing overlay.
-  function handleEscape(event?: KeyboardEvent): void {
+  function handleEscape(event: KeyboardEvent | undefined = undefined): void {
     const wasOpen = open;
     open = false;
     // Restore the committed label whenever the live text drifted from it.
@@ -159,7 +176,7 @@
   }
 
   function handleFocus() {
-    if (!disabled) open = true;
+    if (!resolvedDisabled) open = true;
   }
 
   function handleBlur(event: FocusEvent) {
@@ -226,8 +243,11 @@
 
 <div class={classNames('cinder-combobox', className)}>
   {#if label}
-    <label for={id} class="cinder-combobox__label" data-disabled={disabled || undefined}>
+    <label for={id} class="cinder-combobox__label" data-disabled={resolvedDisabled || undefined}>
       {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </label>
   {/if}
 
@@ -241,14 +261,15 @@
       autocomplete="off"
       autocorrect="off"
       spellcheck="false"
-      {disabled}
+      disabled={resolvedDisabled}
       {placeholder}
       value={inputValue}
       aria-autocomplete="list"
       aria-expanded={open}
       aria-controls={listboxId}
       aria-activedescendant={activeOptionId}
-      aria-invalid={ariaInvalid(!!error)}
+      aria-invalid={field.ariaInvalid}
+      aria-required={resolvedRequired || undefined}
       aria-describedby={describedBy}
       oninput={handleInput}
       onfocus={handleFocus}
@@ -325,7 +346,7 @@
 
   <!-- Always in DOM for the same reason — live region must pre-exist before text is injected. -->
   <p
-    id="{id}-error"
+    id={field.ownErrorId ?? stableLocalErrorId}
     class="cinder-combobox__error"
     aria-live="polite"
     data-cinder-error={!!error || undefined}

package/src/components/combobox/combobox.types.ts

@@ -56,8 +56,14 @@ export type ComboboxProps<T extends string = string> = {
   description?: string;
   /** Validation error message; sets aria-invalid="true". */
   error?: string;
-  /** Disables the combobox. */
+  /** Disables the combobox. Inherited from a wrapping FormField when unset. */
   disabled?: boolean;
+  /**
+   * Marks the field required: renders the required marker on the label and
+   * sets `aria-required` on the input. Inherited from a wrapping FormField
+   * when unset.
+   */
+  required?: boolean;
   /** Hard cap on visible filtered options. Default 200. */
   maxVisibleOptions?: number;
   /**

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

@@ -16,17 +16,19 @@ Individual selectable row within a command palette or dropdown command list.
 
 <!-- generated:props:start -->
 
-| Prop            | Type                   | Required | Default | Description                                                                                                                               |
-| --------------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`         | `string`               | no       | —       | Class merged with `.cinder-command-item`.                                                                                                 |
-| `description`   | `string`               | no       | —       | Optional secondary text shown below the main label.                                                                                       |
-| `disabled`      | `boolean`              | no       | —       | When true, the item is skipped by arrow keys and cannot be activated.                                                                     |
-| `selectionMode` | `"item"` \| `"parent"` | no       | —       | The item owns activation. This is the default CommandPalette mode.                                                                        |
-| `value`         | `string`               | yes      | —       | Submitted value; surfaced through the registration record.                                                                                |
-| `children`      | `(opaque)`             | yes      | —       | Main label content. Not expressible in JSON Schema; see the component types for the signature.                                            |
-| `leading`       | `(opaque)`             | no       | —       | Leading content (icon, avatar). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature.     |
-| `onselect`      | `(opaque)`             | no       | —       | Invoked when the item is activated inside CommandPalette. Not expressible in JSON Schema; see the component types for the signature.      |
-| `trailing`      | `(opaque)`             | no       | —       | Trailing content (kbd hint, badge). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop               | Type                   | Required | Default | Description                                                                                                                               |
+| ------------------ | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `accessibleLabel`  | `string`               | no       | —       | Accessible name for the option when the rendered row contains secondary text or rich content.                                             |
+| `class`            | `string`               | no       | —       | Class merged with `.cinder-command-item`.                                                                                                 |
+| `description`      | `string`               | no       | —       | Optional secondary text shown below the main label.                                                                                       |
+| `disabled`         | `boolean`              | no       | —       | When true, the item is skipped by arrow keys and cannot be activated.                                                                     |
+| `keyboardShortcut` | `string`               | no       | —       | Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`.                                                                     |
+| `selectionMode`    | `"item"` \| `"parent"` | no       | —       | The item owns activation. This is the default CommandPalette mode.                                                                        |
+| `value`            | `string`               | yes      | —       | Submitted value; surfaced through the registration record.                                                                                |
+| `children`         | `(opaque)`             | yes      | —       | Main label content. Not expressible in JSON Schema; see the component types for the signature.                                            |
+| `leading`          | `(opaque)`             | no       | —       | Leading content (icon, avatar). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature.     |
+| `onselect`         | `(opaque)`             | no       | —       | Invoked when the item is activated inside CommandPalette. Not expressible in JSON Schema; see the component types for the signature.      |
+| `trailing`         | `(opaque)`             | no       | —       | Trailing content (kbd hint, badge). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/command-item/command-item.css

@@ -29,6 +29,16 @@
   .cinder-command-item[data-cinder-active] {
     background: var(--cinder-accent);
     color: var(--cinder-accent-contrast);
+    /* Keyboard-cursor ring for WCAG 1.4.11 (non-text contrast, ≥3:1). The ring
+       sits ON the accent fill, so it must contrast against --cinder-accent — NOT
+       against a neutral surface. --cinder-ring-color is engineered for ~4.5:1
+       against near-white surfaces and collapses to ~1.1–1.3:1 on the accent fill
+       (invisible), which is why the shared _floating-surface.css ring works there
+       (it sits on a neutral hover surface) but cannot be reused here verbatim.
+       --cinder-accent-contrast is the only token already proven to clear AA on the
+       accent fill (it is the text color on this fill; check-token-contrast.test.ts
+       gates it), giving ~6.5:1 (light) / ~7.8:1 (dark) for the ring. */
+    box-shadow: inset 0 0 0 1px var(--cinder-accent-contrast);
   }
 
   @media (forced-colors: active) {

package/src/components/command-item/command-item.svelte

@@ -36,6 +36,8 @@
     selectionMode = 'item',
     disabled = false,
     description,
+    accessibleLabel,
+    keyboardShortcut,
     leading,
     trailing,
     children,
@@ -77,6 +79,13 @@
   };
 
   const isActive = $derived(itemId !== null && commandList.activeItemId === itemId);
+  const normalizedAccessibleLabel = $derived(normalizeOptionalAttribute(accessibleLabel));
+  const normalizedKeyboardShortcut = $derived(normalizeOptionalAttribute(keyboardShortcut));
+
+  function normalizeOptionalAttribute(value: string | undefined): string | undefined {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+  }
 
   function handlePointerEnter() {
     if (!disabled && itemId !== null) {
@@ -104,6 +113,8 @@
   class={classNames('cinder-command-item', className)}
   aria-selected={isActive}
   aria-disabled={disabled || undefined}
+  aria-label={normalizedAccessibleLabel}
+  aria-keyshortcuts={normalizedKeyboardShortcut}
   data-cinder-active={isActive ? '' : undefined}
   data-cinder-disabled={disabled || undefined}
   onpointerenter={handlePointerEnter}

package/src/components/command-item/command-item.types.ts

@@ -7,6 +7,10 @@ type CommandItemBaseProps = {
   disabled?: boolean;
   /** Optional secondary text shown below the main label. */
   description?: string;
+  /** Accessible name for the option when the rendered row contains secondary text or rich content. */
+  accessibleLabel?: string | undefined;
+  /** Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`. */
+  keyboardShortcut?: string | undefined;
   /** Leading content (icon, avatar). Rendered with aria-hidden. */
   leading?: Snippet;
   /** Trailing content (kbd hint, badge). Rendered with aria-hidden. */