@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/faceted-filter-bar/faceted-filter-bar.svelte

@@ -23,6 +23,7 @@
 </script>
 
 <script lang="ts">
+  import { tick } from 'svelte';
   import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
   import SearchField from '../search-field/search-field.svelte';
   import Chip from '../chip/chip.svelte';
@@ -50,6 +51,7 @@
   }: FacetedFilterBarProps = $props();
 
   const searchId = $derived(`${generatedId}-search`);
+  let rootElement: HTMLDivElement | undefined = $state();
 
   // Internal uncontrolled search value when searchQuery is not provided.
   let internalSearchQuery = $state('');
@@ -68,13 +70,21 @@
     return appliedFilters.find((filter) => filter.key === key)?.value ?? '';
   }
 
+  function resolveFilterDisplayValue(key: string, value: string): string {
+    const facet = facets.find((candidate) => candidate.key === key);
+    if (facet?.type !== 'select') return value;
+    return facet.options.find((option) => option.value === value)?.label ?? value;
+  }
+
   const hasAppliedFilters = $derived(appliedFilters.length > 0 || currentSearchQuery.length > 0);
   const totalActiveCount = $derived(appliedFilters.length);
 
   // Live region summary message — always in DOM, content changes when filters change.
   const summaryMessage = $derived.by(() => {
     if (totalActiveCount === 0) return '';
-    const parts = appliedFilters.map((filter) => `${filter.label}: ${filter.value}`);
+    const parts = appliedFilters.map(
+      (filter) => `${filter.label}: ${resolveFilterDisplayValue(filter.key, filter.value)}`,
+    );
     return `${totalActiveCount} active filter${totalActiveCount === 1 ? '' : 's'}: ${parts.join(', ')}`;
   });
 
@@ -85,8 +95,21 @@
     onsearchchange?.(value);
   }
 
-  function handleFilterRemove(key: string): void {
+  async function handleFilterRemove(key: string): Promise<void> {
+    const filterIndex = appliedFilters.findIndex((filter) => filter.key === key);
+    const facetFallbackKey = appliedFilters[filterIndex]?.key;
     onfilterremove?.(key);
+    await tick();
+
+    const removeButtons = Array.from(
+      rootElement?.querySelectorAll<HTMLButtonElement>('.cinder-chip__remove') ?? [],
+    );
+    const nextRemoveButton = removeButtons[Math.min(filterIndex, removeButtons.length - 1)];
+    const facetSelect = facetFallbackKey
+      ? document.getElementById(`${generatedId}-facet-${facetFallbackKey}`)
+      : null;
+    const searchInput = document.getElementById(searchId);
+    (nextRemoveButton ?? facetSelect ?? searchInput)?.focus();
   }
 
   function handleClearAll(): void {
@@ -102,6 +125,7 @@
 </script>
 
 <div
+  bind:this={rootElement}
   {...rest}
   class={classNames('cinder-faceted-filter-bar', className)}
   role="search"
@@ -125,7 +149,7 @@
         {@const selectFacet = facet as SelectFacet}
         <div class="cinder-faceted-filter-bar__facet">
           <label
-            class="cinder-faceted-filter-bar__facet-label cinder-sr-only"
+            class="cinder-faceted-filter-bar__facet-label"
             for={`${generatedId}-facet-${selectFacet.key}`}
           >
             {selectFacet.label}
@@ -165,10 +189,11 @@
   {#if hasAppliedFilters}
     <div class="cinder-faceted-filter-bar__chips" aria-label="Active filter controls">
       {#each appliedFilters as filter (filter.key)}
+        {@const displayValue = resolveFilterDisplayValue(filter.key, filter.value)}
         <Chip
           mode="removable"
-          label={`${filter.label}: ${filter.value}`}
-          removeAriaLabel={`Remove filter: ${filter.label}: ${filter.value}`}
+          label={`${filter.label}: ${displayValue}`}
+          removeAriaLabel={`Remove filter: ${filter.label}: ${displayValue}`}
           {disabled}
           onremove={() => handleFilterRemove(filter.key)}
         />
@@ -179,6 +204,7 @@
         size="sm"
         class="cinder-faceted-filter-bar__clear-all"
         {disabled}
+        aria-label="Clear all filters"
         onclick={handleClearAll}
       >
         Clear all

package/src/components/file-upload/file-upload.css

@@ -18,9 +18,9 @@
     background: var(--cinder-file-upload-background);
     padding: var(--cinder-space-4);
     transition:
-      border-color 150ms ease,
-      background-color 150ms ease,
-      box-shadow 150ms ease;
+      border-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      background-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      box-shadow var(--cinder-duration-fast) var(--cinder-ease-standard);
   }
 
   .cinder-file-upload__dropzone[data-drag-active] {
@@ -35,7 +35,7 @@
   }
 
   .cinder-file-upload__dropzone:focus-within {
-    outline: 2px solid transparent;
+    outline: var(--cinder-ring-width) solid transparent;
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
@@ -169,7 +169,7 @@
     block-size: 100%;
     background: var(--cinder-file-upload-progress-fill);
     inline-size: calc(clamp(0, var(--cinder-file-upload-progress, 0), 100) * 1%);
-    transition: inline-size 150ms ease;
+    transition: inline-size var(--cinder-duration-fast) var(--cinder-ease-standard);
   }
 
   .cinder-file-upload__error {

package/src/components/file-upload/file-upload.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "file-upload",
+  "import": "@lostgradient/cinder/file-upload",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic file upload",
+      "description": "Drag-and-drop file picker with acceptance and rejection feedback.",
+      "code": "<script lang=\"ts\">\n  import { FileUpload } from '@lostgradient/cinder/file-upload';\n  import type { RejectedFile } from '@lostgradient/cinder/file-upload';\n  import { FormField } from '@lostgradient/cinder/form-field';\n\n  let acceptedNames = $state<string[]>([]);\n  let rejectedMessages = $state<string[]>([]);\n\n  // A single drop/pick can include both valid and invalid files — FileUpload\n  // fires `onchange` (accepted) AND `onreject` (rejected) for the same batch.\n  // Each handler updates only its own list so a mixed batch shows both results.\n  function handleChange(files: File[]) {\n    acceptedNames = files.map((file) => file.name);\n  }\n\n  function handleReject(rejected: RejectedFile[]) {\n    rejectedMessages = rejected.map((entry) => entry.message);\n  }\n</script>\n\n<!-- Compose with FormField so the file input has an associated <label>. -->\n<FormField id=\"attachment\" label=\"Attachment\" description=\"Images or PDF, up to 5 MB.\">\n  <FileUpload\n    id=\"attachment\"\n    accept=\"image/*,.pdf\"\n    multiple\n    maxSize={5 * 1024 * 1024}\n    onchange={handleChange}\n    onreject={handleReject}\n  />\n</FormField>\n\n{#if acceptedNames.length > 0}\n  <p style=\"margin-top: 0.5rem; color: var(--cinder-color-success-fg);\">\n    Accepted: {acceptedNames.join(', ')}\n  </p>\n{/if}\n\n{#if rejectedMessages.length > 0}\n  <p style=\"margin-top: 0.5rem; color: var(--cinder-color-danger-fg);\">\n    {rejectedMessages.join('; ')}\n  </p>\n{/if}\n"
+    }
+  ]
+}

package/src/components/floating-action-button/README.md

@@ -25,15 +25,15 @@ Circular button representing the single most important action on a screen.
 
 <!-- generated:props:start -->
 
-| Prop       | Type                                        | Required | Default     | Description                                                                                                                                                                                                                            |
-| ---------- | ------------------------------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`                                    | no       | —           | Custom class merged with `.cinder-fab`.                                                                                                                                                                                                |
-| `color`    | `"primary"` \| `"secondary"` \| `"surface"` | no       | `"primary"` | Color palette.                                                                                                                                                                                                                         |
-| `disabled` | `boolean`                                   | no       | `false`     | When true, disables the button and prevents interaction.                                                                                                                                                                               |
-| `href`     | `string`                                    | no       | —           | Render as an anchor `<a>` element with this href.                                                                                                                                                                                      |
-| `size`     | `"sm"` \| `"md"` \| `"lg"`                  | no       | `"md"`      | Size of the FAB.                                                                                                                                                                                                                       |
-| `variant`  | `"filled"` \| `"extended"`                  | no       | `"filled"`  | Visual variant. `filled` = circle, `extended` = pill.                                                                                                                                                                                  |
-| `children` | `(opaque)`                                  | no       | —           | The icon (or icon + label for extended variant). Always provide `aria-label` when the FAB renders an icon without visible text — i.e. the `filled` variant. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop       | Type                                        | Required | Default     | Description                                                                                                                                                                                                                        |
+| ---------- | ------------------------------------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`                                    | no       | —           | Custom class merged with `.cinder-fab`.                                                                                                                                                                                            |
+| `disabled` | `boolean`                                   | no       | `false`     | When true, disables the button and prevents interaction.                                                                                                                                                                           |
+| `href`     | `string`                                    | no       | —           | Render as an anchor `<a>` element with this href.                                                                                                                                                                                  |
+| `shape`    | `"filled"` \| `"extended"`                  | no       | `"filled"`  | Shape. `filled` = circle, `extended` = pill.                                                                                                                                                                                       |
+| `size`     | `"sm"` \| `"md"` \| `"lg"`                  | no       | `"md"`      | Size of the FAB.                                                                                                                                                                                                                   |
+| `variant`  | `"primary"` \| `"secondary"` \| `"surface"` | no       | `"primary"` | Color palette.                                                                                                                                                                                                                     |
+| `children` | `(opaque)`                                  | no       | —           | The icon (or icon + label for extended shape). Always provide `aria-label` when the FAB renders an icon without visible text — i.e. the `filled` shape. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/floating-action-button/floating-action-button.css

@@ -80,11 +80,11 @@
     font-size: var(--cinder-text-xs);
   }
 
-  .cinder-fab[data-cinder-size='sm'][data-cinder-variant='filled'] {
+  .cinder-fab[data-cinder-size='sm'][data-cinder-shape='filled'] {
     inline-size: var(--cinder-space-10);
   }
 
-  .cinder-fab[data-cinder-size='sm'][data-cinder-variant='extended'] {
+  .cinder-fab[data-cinder-size='sm'][data-cinder-shape='extended'] {
     padding-inline: var(--cinder-space-4);
   }
 
@@ -93,11 +93,11 @@
     font-size: var(--cinder-text-sm);
   }
 
-  .cinder-fab[data-cinder-size='md'][data-cinder-variant='filled'] {
+  .cinder-fab[data-cinder-size='md'][data-cinder-shape='filled'] {
     inline-size: var(--cinder-space-12);
   }
 
-  .cinder-fab[data-cinder-size='md'][data-cinder-variant='extended'] {
+  .cinder-fab[data-cinder-size='md'][data-cinder-shape='extended'] {
     padding-inline: var(--cinder-space-6);
   }
 
@@ -106,51 +106,51 @@
     font-size: var(--cinder-text-lg);
   }
 
-  .cinder-fab[data-cinder-size='lg'][data-cinder-variant='filled'] {
+  .cinder-fab[data-cinder-size='lg'][data-cinder-shape='filled'] {
     inline-size: var(--cinder-space-16);
   }
 
-  .cinder-fab[data-cinder-size='lg'][data-cinder-variant='extended'] {
+  .cinder-fab[data-cinder-size='lg'][data-cinder-shape='extended'] {
     padding-inline: var(--cinder-space-8);
   }
 
   /* ----------------------------------------
-   * Color variants
+   * Color variants (via variant prop)
    * ---------------------------------------- */
 
   /* primary — accent fill with contrast foreground */
-  .cinder-fab[data-cinder-color='primary'] {
+  .cinder-fab[data-cinder-variant='primary'] {
     --_cinder-fab-ring: var(--cinder-ring-on-accent);
     background: var(--cinder-accent);
     color: var(--cinder-accent-contrast);
   }
 
-  .cinder-fab[data-cinder-color='primary']:disabled,
-  .cinder-fab[data-cinder-color='primary'][aria-disabled='true'] {
+  .cinder-fab[data-cinder-variant='primary']:disabled,
+  .cinder-fab[data-cinder-variant='primary'][aria-disabled='true'] {
     background: var(--cinder-surface-inset);
     color: var(--cinder-text-disabled);
   }
 
   /* secondary — surface-raised background with standard text */
-  .cinder-fab[data-cinder-color='secondary'] {
+  .cinder-fab[data-cinder-variant='secondary'] {
     background: var(--cinder-surface-raised);
     color: var(--cinder-text);
   }
 
-  .cinder-fab[data-cinder-color='secondary']:disabled,
-  .cinder-fab[data-cinder-color='secondary'][aria-disabled='true'] {
+  .cinder-fab[data-cinder-variant='secondary']:disabled,
+  .cinder-fab[data-cinder-variant='secondary'][aria-disabled='true'] {
     background: var(--cinder-surface-inset);
     color: var(--cinder-text-disabled);
   }
 
   /* surface — neutral surface color, suited for floating above content */
-  .cinder-fab[data-cinder-color='surface'] {
+  .cinder-fab[data-cinder-variant='surface'] {
     background: var(--cinder-surface);
     color: var(--cinder-text);
   }
 
-  .cinder-fab[data-cinder-color='surface']:disabled,
-  .cinder-fab[data-cinder-color='surface'][aria-disabled='true'] {
+  .cinder-fab[data-cinder-variant='surface']:disabled,
+  .cinder-fab[data-cinder-variant='surface'][aria-disabled='true'] {
     background: var(--cinder-surface-inset);
     color: var(--cinder-text-disabled);
   }
@@ -168,15 +168,15 @@
       --_cinder-fab-elevation: var(--cinder-shadow-lg);
     }
 
-    .cinder-fab[data-cinder-color='primary']:hover:not(:disabled):not([aria-disabled='true']) {
+    .cinder-fab[data-cinder-variant='primary']:hover:not(:disabled):not([aria-disabled='true']) {
       background: var(--cinder-accent-hover);
     }
 
-    .cinder-fab[data-cinder-color='secondary']:hover:not(:disabled):not([aria-disabled='true']) {
+    .cinder-fab[data-cinder-variant='secondary']:hover:not(:disabled):not([aria-disabled='true']) {
       background: var(--cinder-surface-hover);
     }
 
-    .cinder-fab[data-cinder-color='surface']:hover:not(:disabled):not([aria-disabled='true']) {
+    .cinder-fab[data-cinder-variant='surface']:hover:not(:disabled):not([aria-disabled='true']) {
       background: var(--cinder-surface-hover);
     }
   }
@@ -184,15 +184,15 @@
   /* :active placed after hover media so press feedback fires on tap as well.
      Uses the gentler on-fill pressed token so the --cinder-accent-contrast label stays
      AA-legible on the pressed fill (see --cinder-accent-active-on-fill in tokens-base.css). */
-  .cinder-fab[data-cinder-color='primary']:active:not(:disabled):not([aria-disabled='true']) {
+  .cinder-fab[data-cinder-variant='primary']:active:not(:disabled):not([aria-disabled='true']) {
     background: var(--cinder-accent-active-on-fill);
   }
 
-  .cinder-fab[data-cinder-color='secondary']:active:not(:disabled):not([aria-disabled='true']) {
+  .cinder-fab[data-cinder-variant='secondary']:active:not(:disabled):not([aria-disabled='true']) {
     background: var(--cinder-surface-pressed);
   }
 
-  .cinder-fab[data-cinder-color='surface']:active:not(:disabled):not([aria-disabled='true']) {
+  .cinder-fab[data-cinder-variant='surface']:active:not(:disabled):not([aria-disabled='true']) {
     background: var(--cinder-surface-pressed);
   }
 

package/src/components/floating-action-button/floating-action-button.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Floating Action Button",
       "description": "A circular primary-action button. Always provide aria-label for icon-only (filled) usage. Wrap in a fixed/sticky container to position it on the page.",
-      "code": "<script lang=\"ts\">\n  import { FloatingActionButton } from '@lostgradient/cinder/floating-action-button';\n</script>\n\n<div style=\"display: flex; align-items: center; gap: 1.5rem; flex-wrap: wrap;\">\n  <!-- Primary filled FAB (default) -->\n  <FloatingActionButton aria-label=\"Add item\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Secondary color -->\n  <FloatingActionButton color=\"secondary\" aria-label=\"Edit\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <path d=\"M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7\" />\n      <path d=\"M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Surface color -->\n  <FloatingActionButton color=\"surface\" aria-label=\"Share\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <circle cx=\"18\" cy=\"5\" r=\"3\" />\n      <circle cx=\"6\" cy=\"12\" r=\"3\" />\n      <circle cx=\"18\" cy=\"19\" r=\"3\" />\n      <line x1=\"8.59\" y1=\"13.51\" x2=\"15.42\" y2=\"17.49\" />\n      <line x1=\"15.41\" y1=\"6.51\" x2=\"8.59\" y2=\"10.49\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Extended variant with icon + label -->\n  <FloatingActionButton variant=\"extended\" aria-label=\"Compose new message\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"20\"\n      height=\"20\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n    Compose\n  </FloatingActionButton>\n\n  <!-- Small size -->\n  <FloatingActionButton size=\"sm\" aria-label=\"Add small\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"16\"\n      height=\"16\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Large size -->\n  <FloatingActionButton size=\"lg\" aria-label=\"Add large\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"32\"\n      height=\"32\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Link FAB -->\n  <FloatingActionButton href=\"/new\" aria-label=\"Create new item\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Disabled FAB -->\n  <FloatingActionButton disabled aria-label=\"Add (unavailable)\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { FloatingActionButton } from '@lostgradient/cinder/floating-action-button';\n</script>\n\n<div style=\"display: flex; align-items: center; gap: 1.5rem; flex-wrap: wrap;\">\n  <!-- Primary filled FAB (default) -->\n  <FloatingActionButton aria-label=\"Add item\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Secondary variant -->\n  <FloatingActionButton variant=\"secondary\" aria-label=\"Edit\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <path d=\"M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7\" />\n      <path d=\"M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Surface variant -->\n  <FloatingActionButton variant=\"surface\" aria-label=\"Share\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <circle cx=\"18\" cy=\"5\" r=\"3\" />\n      <circle cx=\"6\" cy=\"12\" r=\"3\" />\n      <circle cx=\"18\" cy=\"19\" r=\"3\" />\n      <line x1=\"8.59\" y1=\"13.51\" x2=\"15.42\" y2=\"17.49\" />\n      <line x1=\"15.41\" y1=\"6.51\" x2=\"8.59\" y2=\"10.49\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Extended shape with icon + label -->\n  <FloatingActionButton shape=\"extended\" aria-label=\"Compose new message\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"20\"\n      height=\"20\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n    Compose\n  </FloatingActionButton>\n\n  <!-- Small size -->\n  <FloatingActionButton size=\"sm\" aria-label=\"Add small\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"16\"\n      height=\"16\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Large size -->\n  <FloatingActionButton size=\"lg\" aria-label=\"Add large\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"32\"\n      height=\"32\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Link FAB -->\n  <FloatingActionButton href=\"/new\" aria-label=\"Create new item\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n\n  <!-- Disabled FAB -->\n  <FloatingActionButton disabled aria-label=\"Add (unavailable)\">\n    <svg\n      xmlns=\"http://www.w3.org/2000/svg\"\n      width=\"24\"\n      height=\"24\"\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      stroke-width=\"2\"\n      stroke-linecap=\"round\"\n      stroke-linejoin=\"round\"\n      aria-hidden=\"true\"\n    >\n      <line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\" />\n      <line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\" />\n    </svg>\n  </FloatingActionButton>\n</div>\n"
     }
   ]
 }

package/src/components/floating-action-button/floating-action-button.svelte

@@ -13,9 +13,9 @@
    */
   export type {
     FloatingActionButtonProps,
+    FloatingActionButtonShape,
     FloatingActionButtonSize,
     FloatingActionButtonVariant,
-    FloatingActionButtonColor,
   } from './floating-action-button.types.ts';
 </script>
 
@@ -27,9 +27,9 @@
   import type { FloatingActionButtonProps } from './floating-action-button.types.ts';
 
   const {
-    variant = 'filled',
+    shape = 'filled',
     size = 'md',
-    color = 'primary',
+    variant = 'primary',
     disabled = false,
     children,
     class: customClassName,
@@ -52,9 +52,9 @@
   const mergedClassName = $derived(classNames('cinder-fab', customClassName));
 
   const dataAttributes = $derived({
-    'data-cinder-variant': variant,
+    'data-cinder-shape': shape,
     'data-cinder-size': size,
-    'data-cinder-color': color,
+    'data-cinder-variant': variant,
   });
 
   // Normalize ARIA label props: empty strings suppress accessible name fallback without
@@ -89,9 +89,9 @@
     const hasAriaLabelledBy = resolvedAriaLabelledBy !== undefined;
 
     // Filled FABs are icon-only by design — they require an accessible name.
-    if (variant === 'filled' && !hasAriaLabel && !hasAriaLabelledBy) {
+    if (shape === 'filled' && !hasAriaLabel && !hasAriaLabelledBy) {
       devWarn(
-        '[cinder/FloatingActionButton] filled variant requires aria-label or aria-labelledby — the icon alone does not provide an accessible name.',
+        '[cinder/FloatingActionButton] filled shape requires aria-label or aria-labelledby — the icon alone does not provide an accessible name.',
       );
     }
 

package/src/components/floating-action-button/floating-action-button.types.ts

@@ -2,14 +2,15 @@ import type { Snippet } from 'svelte';
 import type { HTMLAnchorAttributes, HTMLButtonAttributes } from 'svelte/elements';
 
 /**
- * Visual variant of the FAB.
+ * Visual palette of the FAB.
  *
- * `filled` renders a circle with equal width and height — the classic FAB shape.
- * `extended` renders a pill with auto-width that accommodates icon + label side by side.
+ * - `primary` — uses the primary accent color (solid fill, contrast foreground).
+ * - `secondary` — uses the surface-raised background with standard text color.
+ * - `surface` — uses the neutral surface color, suited for floating over content.
  *
- * @default `"filled"`
+ * @default `"primary"`
  */
-export type FloatingActionButtonVariant = 'filled' | 'extended';
+export type FloatingActionButtonVariant = 'primary' | 'secondary' | 'surface';
 
 /**
  * Size of the FAB. Controls the diameter (`filled`) or height (`extended`).
@@ -19,30 +20,29 @@ export type FloatingActionButtonVariant = 'filled' | 'extended';
 export type FloatingActionButtonSize = 'sm' | 'md' | 'lg';
 
 /**
- * Color palette of the FAB.
+ * Shape of the FAB.
  *
- * - `primary` — uses the primary accent color (solid fill, contrast foreground).
- * - `secondary` — uses the surface-raised background with standard text color.
- * - `surface` — uses the neutral surface color, suited for floating over content.
+ * `filled` renders a circle with equal width and height — the classic FAB shape.
+ * `extended` renders a pill with auto-width that accommodates icon + label side by side.
  *
- * @default `"primary"`
+ * @default `"filled"`
  */
-export type FloatingActionButtonColor = 'primary' | 'secondary' | 'surface';
+export type FloatingActionButtonShape = 'filled' | 'extended';
 
 type SharedBase = {
-  /** Visual variant. `filled` = circle, `extended` = pill with icon + label. */
-  variant?: FloatingActionButtonVariant;
+  /** Shape. `filled` = circle, `extended` = pill with icon + label. */
+  shape?: FloatingActionButtonShape;
   /** Size — controls diameter for filled, height for extended. */
   size?: FloatingActionButtonSize;
-  /** Color palette. */
-  color?: FloatingActionButtonColor;
+  /** Color palette (primary, secondary, or surface). */
+  variant?: FloatingActionButtonVariant;
   /** When true, disables the button and prevents interaction. */
   disabled?: boolean;
   /** Custom class merged with `.cinder-fab`. */
   class?: string;
   /**
-   * The icon (or icon + label for extended variant). Always provide `aria-label` when
-   * the FAB renders an icon without visible text — i.e. the `filled` variant.
+   * The icon (or icon + label for extended shape). Always provide `aria-label` when
+   * the FAB renders an icon without visible text — i.e. the `filled` shape.
    */
   children?: Snippet;
 };
@@ -62,7 +62,7 @@ type FloatingActionButtonLink = SharedBase & Omit<HTMLAnchorAttributes, 'class'>
 /**
  * Props for the FloatingActionButton component.
  *
- * Icon-only usage (i.e. `variant="filled"`) requires an accessible name via
+ * Icon-only usage (i.e. `shape="filled"`) requires an accessible name via
  * `aria-label` or `aria-labelledby`. The component emits a dev-mode warning when
  * neither is present.
  */
@@ -74,10 +74,10 @@ export type FloatingActionButtonProps = FloatingActionButtonOnly | FloatingActio
  */
 export interface FloatingActionButtonSchemaProps {
   /**
-   * Visual variant. `filled` = circle, `extended` = pill.
+   * Shape. `filled` = circle, `extended` = pill.
    * @default "filled"
    */
-  variant?: FloatingActionButtonVariant;
+  shape?: FloatingActionButtonShape;
   /**
    * Size of the FAB.
    * @default "md"
@@ -87,7 +87,7 @@ export interface FloatingActionButtonSchemaProps {
    * Color palette.
    * @default "primary"
    */
-  color?: FloatingActionButtonColor;
+  variant?: FloatingActionButtonVariant;
   /**
    * When true, disables the button and prevents interaction.
    * @default false

package/src/components/floating-action-button/index.ts

@@ -3,8 +3,8 @@ import FloatingActionButton from './floating-action-button.svelte';
 
 export default FloatingActionButton;
 export type {
-  FloatingActionButtonColor,
   FloatingActionButtonProps,
+  FloatingActionButtonShape,
   FloatingActionButtonSize,
   FloatingActionButtonVariant,
 } from './floating-action-button.types.ts';

package/src/components/form-field/form-field.css

@@ -30,19 +30,9 @@
     cursor: not-allowed;
   }
 
-  /* ----------------------------------------
- * Required marker
- * ---------------------------------------- */
-
-  .cinder-form-field__required {
-    display: inline-block;
-    width: 6px;
-    height: 6px;
-    border-radius: 50%;
-    background-color: var(--cinder-danger);
-    flex-shrink: 0;
-    align-self: center;
-  }
+  /* The required marker is the shared `.cinder-_required-marker` partial
+     (styles/components/_field-label.css) so the asterisk can never drift
+     between FormField, Label, and the inline control labels. */
 
   /* ----------------------------------------
  * Supporting text

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

@@ -79,7 +79,10 @@
   >
     {label}
     {#if required}
-      <span class="cinder-form-field__required" aria-hidden="true"></span>
+      <!-- Visible asterisk conveys "required" by shape, not color alone (WCAG
+           1.4.1). aria-hidden so the accessible name stays clean — the field's
+           own `required`/`aria-required` attribute is the single AT signal. -->
+      <span class="cinder-_required-marker" aria-hidden="true">*</span>
     {/if}
   </label>
 

package/src/components/image/image.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "image",
+  "import": "@lostgradient/cinder/image",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic image",
+      "description": "Responsive image with lazy loading and an explicit aspect ratio.",
+      "code": "<script lang=\"ts\">\n  import { Image } from '@lostgradient/cinder/image';\n</script>\n\n<Image\n  src=\"https://picsum.photos/seed/cinder/600/338\"\n  alt=\"A randomly selected placeholder photograph\"\n  ratio=\"16/9\"\n  width={600}\n  height={338}\n/>\n"
+    }
+  ]
+}

package/src/components/input/README.md

@@ -16,21 +16,22 @@ Single-line text input with support for labels, addons, validation states, and h
 
 <!-- generated:props:start -->
 
-| Prop                  | Type                                                                                                | Required | Default | Description                                                                                                                |
-| --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `description`         | `string`                                                                                            | no       | —       | Helper text rendered below the input and associated via `aria-describedby`.                                                |
-| `disabled`            | `boolean`                                                                                           | no       | —       | When true, disables the input, matching the native `disabled` attribute.                                                   |
-| `error`               | `string`                                                                                            | no       | —       | Error message rendered below the input; also sets `aria-invalid` on the input.                                             |
-| `id`                  | `string`                                                                                            | yes      | —       | HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required.                         |
-| `label`               | `string`                                                                                            | no       | —       | Visible label text rendered above the input and linked via `for`/`id`.                                                     |
-| `leadingInteractive`  | `boolean`                                                                                           | no       | —       | When true, the leading adornment is interactive and included in the accessibility tree. Default `false`.                   |
-| `required`            | `boolean`                                                                                           | no       | —       | Marks the input as required for form validation, matching the native `required` attribute.                                 |
-| `trailingInteractive` | `boolean`                                                                                           | no       | —       | When true, the trailing adornment is interactive and included in the accessibility tree. Default `false`.                  |
-| `type`                | `"number"` \| `"date"` \| `"email"` \| `"password"` \| `"search"` \| `"tel"` \| `"text"` \| `"url"` | no       | —       | Input type controlling the browser's built-in validation and keyboard. Default `"text"`.                                   |
-| `class`               | `(opaque)`                                                                                          | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `leading`             | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `trailing`            | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `value`               | `(opaque)`                                                                                          | yes      | —       | Bindable current text value of the input. Not expressible in JSON Schema; see the component types for the signature.       |
+| Prop                  | Type                                                                                                | Required | Default | Description                                                                                                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`         | `string`                                                                                            | no       | —       | Helper text rendered below the input and associated via `aria-describedby`.                                                                                                             |
+| `disabled`            | `boolean`                                                                                           | no       | —       | When true, disables the input, matching the native `disabled` attribute.                                                                                                                |
+| `error`               | `string`                                                                                            | no       | —       | Error message rendered below the input; also sets `aria-invalid` on the input.                                                                                                          |
+| `id`                  | `string`                                                                                            | yes      | —       | HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required.                                                                                      |
+| `label`               | `string`                                                                                            | no       | —       | Visible label text rendered above the input and linked via `for`/`id`.                                                                                                                  |
+| `leadingInteractive`  | `boolean`                                                                                           | no       | —       | When true, the leading adornment is interactive and included in the accessibility tree. Default `false`.                                                                                |
+| `required`            | `boolean`                                                                                           | no       | —       | Marks the input as required for form validation, matching the native `required` attribute.                                                                                              |
+| `trailingInteractive` | `boolean`                                                                                           | no       | —       | When true, the trailing adornment is interactive and included in the accessibility tree. Default `false`.                                                                               |
+| `type`                | `"number"` \| `"date"` \| `"email"` \| `"password"` \| `"search"` \| `"tel"` \| `"text"` \| `"url"` | no       | —       | Input type controlling the browser's built-in validation and keyboard. Default `"text"`.                                                                                                |
+| `class`               | `(opaque)`                                                                                          | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                 |
+| `leading`             | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                              |
+| `onValueChange`       | `(opaque)`                                                                                          | no       | —       | Intercept a proposed value before the bindable value is written. Return a replacement value to transform it. Not expressible in JSON Schema; see the component types for the signature. |
+| `trailing`            | `(opaque)`                                                                                          | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                              |
+| `value`               | `(opaque)`                                                                                          | yes      | —       | Bindable current text value of the input. Not expressible in JSON Schema; see the component types for the signature.                                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/input/input.examples.json

@@ -13,7 +13,7 @@
       "id": "sign-in",
       "title": "Sign-in composition",
       "description": "Composition of FormField + Input + Button with a top-of-form Alert auth-error region. Demonstrates the required autocomplete values and the assertive announcement pattern via role=\"alert\".",
-      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n  import { Button } from '@lostgradient/cinder/button';\n  import { FormField } from '@lostgradient/cinder/form-field';\n  import { Input } from '@lostgradient/cinder/input';\n  let email = $state('');\n  let password = $state('');\n  let authError = $state<string | undefined>(undefined);\n  let submitting = $state(false);\n\n  function handleSignIn() {\n    if (submitting) return;\n    // Clear any prior error so a re-submit re-announces by re-mounting the Alert\n    // rather than mutating its text (assistive tech announces on mount of role=\"alert\").\n    authError = undefined;\n    submitting = true;\n\n    // Static example: simulate an auth failure. A real implementation would\n    // POST { email, password } and redirect on success.\n    setTimeout(() => {\n      authError = 'Email or password is incorrect.';\n      submitting = false;\n    }, 600);\n  }\n</script>\n\n<form\n  novalidate\n  aria-labelledby=\"sign-in-heading\"\n  style=\"display: flex; flex-direction: column; gap: 1rem;\"\n  onsubmit={(event) => {\n    event.preventDefault();\n    handleSignIn();\n  }}\n>\n  <h2 id=\"sign-in-heading\">Sign in</h2>\n\n  <!--\n    Top-of-form auth-error region.\n    Alert's role=\"alert\" implies aria-live=\"assertive\" and aria-atomic=\"true\".\n    We intentionally do NOT add an explicit aria-live attribute (see alert.test.ts:\n    \"has role=alert on root element and does not set an explicit aria-live\").\n    Mounting the Alert in response to submit triggers the assertive announcement.\n  -->\n  {#if authError}\n    <Alert variant=\"error\">\n      {authError}\n    </Alert>\n  {/if}\n\n  <FormField id=\"sign-in-email\" label=\"Email\" required>\n    <!-- autocomplete=\"email\" — the identifier is an email address.\n         Use \"username\" instead when the field collects an opaque handle. -->\n    <Input\n      id=\"sign-in-email\"\n      type=\"email\"\n      bind:value={email}\n      autocomplete=\"email\"\n      required\n      placeholder=\"you@example.com\"\n    />\n  </FormField>\n\n  <FormField id=\"sign-in-password\" label=\"Password\" required>\n    <!-- autocomplete=\"current-password\" — required for password managers to\n         recognize this as a sign-in form and offer saved credentials. -->\n    <Input\n      id=\"sign-in-password\"\n      type=\"password\"\n      bind:value={password}\n      autocomplete=\"current-password\"\n      required\n    />\n  </FormField>\n\n  <Button type=\"submit\" variant=\"primary\" loading={submitting}>\n    {submitting ? 'Signing in…' : 'Sign in'}\n  </Button>\n</form>\n"
+      "code": "<script lang=\"ts\">\n  import { Alert } from '@lostgradient/cinder/alert';\n  import { Button } from '@lostgradient/cinder/button';\n  import { FormField } from '@lostgradient/cinder/form-field';\n  import { Input } from '@lostgradient/cinder/input';\n  let email = $state('');\n  let password = $state('');\n  let authError = $state<string | undefined>(undefined);\n  let submitting = $state(false);\n\n  function handleSignIn() {\n    if (submitting) return;\n    // Clear any prior error so a re-submit re-announces by re-mounting the Alert\n    // rather than mutating its text (assistive tech announces on mount of role=\"alert\").\n    authError = undefined;\n    submitting = true;\n\n    // Static example: simulate an auth failure. A real implementation would\n    // POST { email, password } and redirect on success.\n    setTimeout(() => {\n      authError = 'Email or password is incorrect.';\n      submitting = false;\n    }, 600);\n  }\n</script>\n\n<form\n  novalidate\n  aria-labelledby=\"sign-in-heading\"\n  style=\"display: flex; flex-direction: column; gap: 1rem;\"\n  onsubmit={(event) => {\n    event.preventDefault();\n    handleSignIn();\n  }}\n>\n  <h2 id=\"sign-in-heading\">Sign in</h2>\n\n  <!--\n    Top-of-form auth-error region.\n    Alert's role=\"alert\" implies aria-live=\"assertive\" and aria-atomic=\"true\".\n    We intentionally do NOT add an explicit aria-live attribute (see alert.test.ts:\n    \"has role=alert on root element and does not set an explicit aria-live\").\n    Mounting the Alert in response to submit triggers the assertive announcement.\n  -->\n  {#if authError}\n    <Alert variant=\"danger\">\n      {authError}\n    </Alert>\n  {/if}\n\n  <FormField id=\"sign-in-email\" label=\"Email\" required>\n    <!-- autocomplete=\"email\" — the identifier is an email address.\n         Use \"username\" instead when the field collects an opaque handle. -->\n    <Input\n      id=\"sign-in-email\"\n      type=\"email\"\n      bind:value={email}\n      autocomplete=\"email\"\n      required\n      placeholder=\"you@example.com\"\n    />\n  </FormField>\n\n  <FormField id=\"sign-in-password\" label=\"Password\" required>\n    <!-- autocomplete=\"current-password\" — required for password managers to\n         recognize this as a sign-in form and offer saved credentials. -->\n    <Input\n      id=\"sign-in-password\"\n      type=\"password\"\n      bind:value={password}\n      autocomplete=\"current-password\"\n      required\n    />\n  </FormField>\n\n  <Button type=\"submit\" variant=\"primary\" loading={submitting}>\n    {submitting ? 'Signing in…' : 'Sign in'}\n  </Button>\n</form>\n"
     },
     {
       "id": "types",