@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/json-schema-editor/property-list.svelte

@@ -8,16 +8,19 @@
     path: string;
     depth?: number;
     readonly?: boolean;
+    onvalidationerrorcount?: ((count: number) => void) | undefined;
     onchange: (properties: Record<string, JsonSchemaValue>, required: string[]) => void;
   };
 </script>
 
 <script lang="ts">
+  import { onDestroy } from 'svelte';
   import Alert from '../alert/alert.svelte';
   import Button from '../button/button.svelte';
   import Chip from '../chip/chip.svelte';
   import Input from '../input/input.svelte';
   import PropertyEditor from './property-editor.svelte';
+  import { calculatePropertyValidationErrorCount } from './property-list-validation.ts';
 
   let {
     idPrefix,
@@ -26,6 +29,7 @@
     path,
     depth = 0,
     readonly = false,
+    onvalidationerrorcount,
     onchange,
   }: PropertyListProps = $props();
 
@@ -36,6 +40,23 @@
   let draftNames = $state<Record<string, string>>({});
   let renameError = $state<string | null>(null);
   let expanded = $state<Record<string, boolean>>({});
+  let childValidationCounts = $state<Record<string, number>>({});
+
+  const validationErrorCount = $derived(
+    calculatePropertyValidationErrorCount(
+      propertyNames,
+      childValidationCounts,
+      renameError !== null,
+    ),
+  );
+
+  $effect(() => {
+    onvalidationerrorcount?.(validationErrorCount);
+  });
+
+  onDestroy(() => {
+    onvalidationerrorcount?.(0);
+  });
 
   function getDraftName(key: string): string {
     return draftNames[key] ?? key;
@@ -79,6 +100,11 @@
       expanded[draft] = true;
       delete expanded[oldKey];
     }
+    const childCount = childValidationCounts[oldKey];
+    if (childCount !== undefined) {
+      const { [oldKey]: _removedChildCount, ...remainingChildCounts } = childValidationCounts;
+      childValidationCounts = { ...remainingChildCounts, [draft]: childCount };
+    }
     onchange(next, nextRequired);
   }
 
@@ -89,9 +115,26 @@
     const nextRequired = required.filter((name) => name !== key);
     delete draftNames[key];
     delete expanded[key];
+    const { [key]: _removedChildCount, ...remainingChildCounts } = childValidationCounts;
+    childValidationCounts = remainingChildCounts;
     onchange(next, nextRequired);
   }
 
+  function setChildValidationErrorCount(key: string, count: number): void {
+    if ((childValidationCounts[key] ?? 0) === count) return;
+    if (count === 0) {
+      const { [key]: _removedChildCount, ...remainingChildCounts } = childValidationCounts;
+      childValidationCounts = remainingChildCounts;
+      return;
+    }
+    childValidationCounts = { ...childValidationCounts, [key]: count };
+  }
+
+  function toggleExpanded(key: string, isOpen: boolean): void {
+    expanded[key] = !isOpen;
+    if (isOpen) setChildValidationErrorCount(key, 0);
+  }
+
   function moveProperty(key: string, direction: -1 | 1) {
     if (readonly) return;
     const index = propertyNames.indexOf(key);
@@ -162,7 +205,7 @@
 
 <div class="cinder-jse-property-list">
   {#if renameError}
-    <Alert variant="error">{renameError}</Alert>
+    <Alert variant="danger">{renameError}</Alert>
   {/if}
 
   {#if propertyNames.length === 0}
@@ -180,13 +223,14 @@
       interactive" violation.
     -->
     <div class="cinder-jse-property-row" data-cinder-required={isRequired ? '' : undefined}>
-      <div class="cinder-jse-property-row__summary">
+      <div class="cinder-jse-property-row__summary" style={`--cinder-jse-property-depth: ${depth}`}>
         <button
           type="button"
           class="cinder-jse-property-row__trigger"
+          aria-label={`${isOpen ? 'Collapse' : 'Expand'} ${key} property`}
           aria-expanded={isOpen}
           aria-controls={panelId}
-          onclick={() => (expanded[key] = !isOpen)}
+          onclick={() => toggleExpanded(key, isOpen)}
         >
           <span class="cinder-jse-property-row__chevron" aria-hidden="true">▸</span>
           <span class="cinder-jse-property-row__name">{key}</span>
@@ -248,6 +292,7 @@
             depth={depth + 1}
             {readonly}
             value={properties[key] ?? {}}
+            onvalidationerrorcount={(count) => setChildValidationErrorCount(key, count)}
             onchange={(next) => setPropertySchema(key, next)}
           />
         </div>

package/src/components/json-viewer/README.md

@@ -16,13 +16,13 @@ Collapsible tree visualization of an arbitrary JSON value with hard depth and by
 
 <!-- generated:props:start -->
 
-| Prop           | Type       | Required | Default | Description                                                                                             |
-| -------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`   | no       | —       | Additional class names merged with `.cinder-json-viewer`.                                               |
-| `initialDepth` | `number`   | no       | —       | Initial collapse depth. Nodes deeper than this start collapsed. Default 1.                              |
-| `maxBytes`     | `number`   | no       | —       | Hard byte cap on the serialized payload. Default 1_048_576 (1 MB).                                      |
-| `maxDepth`     | `number`   | no       | —       | Hard depth cap. Nodes deeper than this never render their children. Default 50.                         |
-| `value`        | `(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                                                                                                                      |
+| -------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`   | no       | —       | Additional class names merged with `.cinder-json-viewer`.                                                                        |
+| `initialDepth` | `number`   | no       | —       | Initial collapse depth. Nodes deeper than this start collapsed. Default 1.                                                       |
+| `maxBytes`     | `number`   | no       | —       | Hard byte cap on the serialized payload. Default 1_048_576 (1 MB).                                                               |
+| `maxDepth`     | `number`   | no       | —       | Hard depth cap. Nodes deeper than this never render their children. Default 50.                                                  |
+| `value`        | `(opaque)` | yes      | —       | The value to render. Any JSON-serializable structure. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/json-viewer/_json-viewer-node.svelte

@@ -9,6 +9,9 @@
     depth: number;
     initialDepth: number;
     maxDepth: number;
+    position: number;
+    setSize: number;
+    root?: boolean;
   };
 </script>
 
@@ -17,7 +20,16 @@
   import Self from './_json-viewer-node.svelte';
   import { classNames } from '../../utilities/class-names.ts';
 
-  let { value, keyName, depth, initialDepth, maxDepth }: JsonViewerNodeProps = $props();
+  let {
+    value,
+    keyName,
+    depth,
+    initialDepth,
+    maxDepth,
+    position,
+    setSize,
+    root = false,
+  }: JsonViewerNodeProps = $props();
 
   const isObject = $derived(value !== null && typeof value === 'object');
   const isArray = $derived(Array.isArray(value));
@@ -34,10 +46,10 @@
     return Object.entries(value as Record<string, unknown>);
   });
 
-  // The key label renders in a sibling <span> outside the <button>, so a screen
-  // reader announces the toggle without any indication of which node it belongs
-  // to. Compose a distinguishing accessible name from the key (when present) and
-  // the collection shape so sibling toggles are tellable apart.
+  // The key label renders inside the <button> so the focus ring encloses the
+  // full row label + caret. The aria-label on the button provides a distinguishing
+  // accessible name from the key (when present) and the collection shape so
+  // sibling toggles are tellable apart.
   const itemCount = $derived(entries.length);
   const collectionLabel = $derived(
     `${isArray ? 'array' : 'object'}, ${itemCount} ${itemCount === 1 ? 'item' : 'items'}`,
@@ -56,17 +68,27 @@
 </script>
 
 {#if isObject && !tooDeep}
-  <span class={classNames('cinder-json-viewer__node')}>
-    {#if keyName !== undefined}
-      <span class="cinder-json-viewer__key">{keyName}:</span>
-    {/if}
+  <!-- svelte-ignore a11y_role_has_required_aria_props -->
+  <span
+    class={classNames('cinder-json-viewer__node')}
+    role="treeitem"
+    aria-expanded={!collapsed}
+    aria-label={toggleLabel}
+    aria-level={depth + 1}
+    aria-posinset={position}
+    aria-setsize={setSize}
+    tabindex={root ? 0 : -1}
+  >
     <button
       type="button"
       class="cinder-json-viewer__toggle"
-      aria-expanded={!collapsed}
       aria-label={toggleLabel}
+      tabindex="-1"
       onclick={() => (collapsed = !collapsed)}
     >
+      {#if keyName !== undefined}
+        <span class="cinder-json-viewer__key">{keyName}:</span>
+      {/if}
       <span class="cinder-json-viewer__caret" data-cinder-collapsed={collapsed || undefined}></span>
       <span class="cinder-json-viewer__brace">
         {isArray ? '[' : '{'}
@@ -79,7 +101,7 @@
       {/if}
     </button>
     {#if !collapsed}
-      <ul class="cinder-json-viewer__children">
+      <ul class="cinder-json-viewer__children" role="group">
         <!--
           For objects `k` is the property name — a stable, correct key. For arrays
           `k` is the index: JSON array elements carry no intrinsic identity, so if
@@ -87,9 +109,17 @@
           stays associated with its position rather than its value. This is an
           accepted tradeoff given arrays have no stable per-item key.
         -->
-        {#each entries as [k, v] (k)}
-          <li>
-            <Self value={v} keyName={k} depth={depth + 1} {initialDepth} {maxDepth} />
+        {#each entries as [k, v], index (k)}
+          <li role="none">
+            <Self
+              value={v}
+              keyName={k}
+              depth={depth + 1}
+              {initialDepth}
+              {maxDepth}
+              position={index + 1}
+              setSize={entries.length}
+            />
           </li>
         {/each}
       </ul>
@@ -97,14 +127,30 @@
     {/if}
   </span>
 {:else if isObject && tooDeep}
-  <span class="cinder-json-viewer__node">
+  <!-- svelte-ignore a11y_role_has_required_aria_props -->
+  <span
+    class="cinder-json-viewer__node"
+    role="treeitem"
+    tabindex={root ? 0 : -1}
+    aria-level={depth + 1}
+    aria-posinset={position}
+    aria-setsize={setSize}
+  >
     {#if keyName !== undefined}
       <span class="cinder-json-viewer__key">{keyName}:</span>
     {/if}
     <span class="cinder-json-viewer__too-deep">…</span>
   </span>
 {:else}
-  <span class="cinder-json-viewer__node">
+  <!-- svelte-ignore a11y_role_has_required_aria_props -->
+  <span
+    class="cinder-json-viewer__node"
+    role="treeitem"
+    tabindex={root ? 0 : -1}
+    aria-level={depth + 1}
+    aria-posinset={position}
+    aria-setsize={setSize}
+  >
     {#if keyName !== undefined}
       <span class="cinder-json-viewer__key">{keyName}:</span>
     {/if}

package/src/components/json-viewer/json-viewer.css

@@ -50,16 +50,33 @@
     border-radius: var(--cinder-radius-sm);
   }
 
+  @media (hover: hover) {
+    .cinder-json-viewer__toggle:hover {
+      background: var(--cinder-surface-hover);
+    }
+  }
+
   .cinder-json-viewer__toggle:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  .cinder-json-viewer__node[role='treeitem']:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    border-radius: var(--cinder-radius-sm);
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
   @media (forced-colors: active) {
     .cinder-json-viewer__toggle:focus-visible {
       outline: var(--cinder-ring-width) solid ButtonText;
       outline-offset: 3px;
     }
+
+    .cinder-json-viewer__node[role='treeitem']:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 3px;
+    }
   }
 
   .cinder-json-viewer__caret {

package/src/components/json-viewer/json-viewer.examples.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "json-viewer",
+  "import": "@lostgradient/cinder/json-viewer",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Shallow object",
+      "description": "A flat JSON object with mixed scalar values. The default initialDepth of 1 keeps the top-level keys expanded while deeper nodes start collapsed — useful for at-a-glance inspection.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    id: 'wf_3c4fce',\n    status: 'completed',\n    exitCode: 0,\n    durationMs: 1423,\n    startedAt: '2025-05-12T15:30:00Z',\n    finishedAt: '2025-05-12T15:30:01.423Z',\n    retryCount: 0,\n    triggeredBy: 'schedule',\n  };\n</script>\n\n<JsonViewer value={payload} />\n"
+    },
+    {
+      "id": "nested",
+      "title": "Nested object and array",
+      "description": "Deeply nested objects and arrays with initialDepth={2} so the second level starts expanded. Toggle nodes to drill into child collections — each branch remembers its collapsed state independently.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    workflow: {\n      id: 'wf_3c4fce',\n      name: 'Nightly ETL',\n      steps: [\n        { name: 'extract', status: 'completed', durationMs: 312 },\n        { name: 'transform', status: 'completed', durationMs: 874 },\n        { name: 'load', status: 'completed', durationMs: 237 },\n      ],\n    },\n    metadata: {\n      triggeredBy: 'schedule',\n      region: 'us-east-1',\n      tags: ['etl', 'nightly', 'production'],\n    },\n    result: {\n      rowsProcessed: 84201,\n      rowsSkipped: 3,\n      errors: [],\n    },\n  };\n</script>\n\n<JsonViewer value={payload} initialDepth={2} />\n"
+    },
+    {
+      "id": "oversized",
+      "title": "Oversized payload fallback",
+      "description": "When the serialized payload exceeds maxBytes, JsonViewer renders a fallback instead of attempting the tree. Here maxBytes={256} triggers the cap on a ~500-byte object. Use the copy or download action in the host surface to inspect the raw JSON.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    id: 'act_9f2a1b',\n    type: 'ActivityCompleted',\n    namespace: 'default',\n    workflowId: 'wf_3c4fce',\n    runId: 'run_7d8e2c',\n    activityId: 'act_9f2a1b',\n    activityType: 'ProcessBatch',\n    result: { rowsProcessed: 84201, rowsSkipped: 3, errors: [] },\n    scheduledAt: '2025-05-12T15:30:00Z',\n    startedAt: '2025-05-12T15:30:00.312Z',\n    completedAt: '2025-05-12T15:30:01.186Z',\n    workerIdentity: 'worker@node-42.us-east-1',\n  };\n</script>\n\n<JsonViewer value={payload} maxBytes={256} />\n"
+    },
+    {
+      "id": "payload-inspector",
+      "title": "Payload inspector with copy",
+      "description": "Pairing JsonViewer with CopyButton creates an operational payload inspector. A metadata header names the source event; CopyButton copies the raw JSON to the clipboard so engineers can paste into other tools. This pattern suits fault-detail and activity-result surfaces in operator UIs.",
+      "code": "<script lang=\"ts\">\n  import { CopyButton } from '@lostgradient/cinder/copy-button';\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const eventType = 'ActivityFailed';\n  const payload = {\n    activityType: 'ProcessBatch',\n    activityId: 'act_9f2a1b',\n    workflowId: 'wf_3c4fce',\n    runId: 'run_7d8e2c',\n    failure: {\n      message: 'connection refused',\n      cause: 'redis://cache.internal:6379 unreachable after 3 retries',\n      applicationFailureInfo: {\n        type: 'NetworkError',\n        nonRetryable: false,\n      },\n    },\n    attempt: 2,\n    scheduledAt: '2025-05-12T15:30:42Z',\n    startedAt: '2025-05-12T15:30:42.811Z',\n  };\n\n  const rawJson = $derived(JSON.stringify(payload, null, 2));\n</script>\n\n<div\n  style=\"border: 1px solid var(--cinder-border); border-radius: var(--cinder-radius-md); overflow: hidden;\"\n>\n  <div\n    style=\"display: flex; align-items: center; justify-content: space-between; padding: 0.5rem 0.75rem; background-color: var(--cinder-surface-raised); border-bottom: 1px solid var(--cinder-border);\"\n  >\n    <span style=\"font-size: 0.75rem; font-weight: 600; color: var(--cinder-text-subtle);\"\n      >{eventType}</span\n    >\n    <CopyButton value={rawJson} label=\"Copy raw JSON\" iconOnly />\n  </div>\n  <div style=\"padding: 0.75rem;\">\n    <JsonViewer value={payload} initialDepth={2} />\n  </div>\n</div>\n"
+    },
+    {
+      "id": "primitives",
+      "title": "Primitive and null values",
+      "description": "Each JSON primitive type — string, number, boolean, and null — rendered inline with type-specific color coding. Useful for verifying that scalar fields survive serialization round-trips.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    label: 'activity-result',\n    count: 42,\n    ratio: 0.9375,\n    active: true,\n    deprecated: false,\n    errorMessage: null,\n    emptyString: '',\n    negativeOffset: -7,\n  };\n</script>\n\n<JsonViewer value={payload} />\n"
+    }
+  ]
+}

package/src/components/json-viewer/json-viewer.svelte

@@ -48,6 +48,66 @@
 
   const unserializable = $derived(!serialized.ok);
   const tooLarge = $derived(serialized.ok && serialized.size > maxBytes);
+
+  function handleTreeKeydown(event: KeyboardEvent): void {
+    const tree = event.currentTarget as HTMLElement;
+    const items = Array.from(tree.querySelectorAll<HTMLElement>('[role="treeitem"]'));
+    const eventTarget = event.target instanceof HTMLElement ? event.target : null;
+    const current = eventTarget?.closest<HTMLElement>('[role="treeitem"]') ?? null;
+    const targetIsToggle = eventTarget?.closest('.cinder-json-viewer__toggle') !== null;
+    const currentIndex = current ? items.indexOf(current) : -1;
+
+    function focusItem(index: number): void {
+      const item = items[index];
+      item?.focus();
+    }
+
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      focusItem(Math.min(currentIndex + 1, items.length - 1));
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      focusItem(Math.max(currentIndex - 1, 0));
+    } else if (event.key === 'Home') {
+      event.preventDefault();
+      focusItem(0);
+    } else if (event.key === 'End') {
+      event.preventDefault();
+      focusItem(items.length - 1);
+    } else if (event.key === 'ArrowRight' && current && !targetIsToggle) {
+      if (current.getAttribute('aria-expanded') === 'false') {
+        event.preventDefault();
+        current.querySelector<HTMLButtonElement>('.cinder-json-viewer__toggle')?.click();
+      } else if (current.getAttribute('aria-expanded') === 'true') {
+        const firstChild = current.querySelector<HTMLElement>(
+          '.cinder-json-viewer__children [role="treeitem"]',
+        );
+        if (firstChild) {
+          event.preventDefault();
+          firstChild.focus();
+        }
+      }
+    } else if (event.key === 'ArrowLeft' && current && !targetIsToggle) {
+      if (current.getAttribute('aria-expanded') === 'true') {
+        event.preventDefault();
+        current.querySelector<HTMLButtonElement>('.cinder-json-viewer__toggle')?.click();
+      } else {
+        const parent = current.parentElement?.closest<HTMLElement>('[role="treeitem"]');
+        if (parent) {
+          event.preventDefault();
+          parent.focus();
+        }
+      }
+    } else if (
+      (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') &&
+      current &&
+      !targetIsToggle
+    ) {
+      event.preventDefault();
+      const toggle = current.querySelector<HTMLButtonElement>('.cinder-json-viewer__toggle');
+      toggle?.click();
+    }
+  }
 </script>
 
 <div class={classNames('cinder-json-viewer', className)}>
@@ -67,6 +127,8 @@
       <p>Use the consumer's download or copy action to inspect the raw JSON.</p>
     </div>
   {:else}
-    <JsonViewerNode {value} depth={0} {initialDepth} {maxDepth} />
+    <div role="tree" aria-label="JSON tree" tabindex="-1" onkeydown={handleTreeKeydown}>
+      <JsonViewerNode {value} depth={0} {initialDepth} {maxDepth} position={1} setSize={1} root />
+    </div>
   {/if}
 </div>

package/src/components/kanban-board/README.md

@@ -28,18 +28,18 @@ Controlled multi-column board for reordering cards within and across workflow co
 
 | Prop             | Type       | Required | Default | Description                                                                                                                |
 | ---------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`          | `string`   | no       | —       |                                                                                                                            |
-| `collapsible`    | `boolean`  | no       | —       |                                                                                                                            |
-| `label`          | `string`   | no       | —       |                                                                                                                            |
-| `reorderColumns` | `boolean`  | no       | —       |                                                                                                                            |
-| `card`           | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `class`          | `string`   | no       | —       | Additional class merged onto the `.cinder-kanban-board` root element.                                                      |
+| `collapsible`    | `boolean`  | no       | —       | When true, each column renders a collapse/expand button that toggles its card list.                                        |
+| `label`          | `string`   | no       | —       | Accessible label applied to the board's `<section>` root via `aria-label`.                                                 |
+| `reorderColumns` | `boolean`  | no       | —       | When true (default), columns can be reordered by dragging or keyboard. Set to false to make column order fixed.            |
+| `card`           | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `columnActions`  | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `columnHeader`   | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `columns`        | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| `columns`        | `(opaque)` | yes      | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
 | `emptyColumn`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `getCardKey`     | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `getCardLabel`   | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onchange`       | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `getCardKey`     | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `getCardLabel`   | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `onchange`       | `(opaque)` | yes      | —       | 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/kanban-board/kanban-board.css

@@ -9,6 +9,29 @@
     display: block;
     overflow-x: auto;
     padding-block-end: var(--cinder-space-2);
+    background:
+      linear-gradient(90deg, var(--cinder-surface) 30%, transparent) left center / 2rem 100%
+        no-repeat local,
+      linear-gradient(270deg, var(--cinder-surface) 30%, transparent) right center / 2rem 100%
+        no-repeat local,
+      /* cinder-allow-raw-color: structural-pattern — neutral scroll-edge shadow, not a themeable surface */
+        linear-gradient(90deg, oklch(0% 0 0 / 12%), transparent) left center / 1rem 100% no-repeat
+        scroll,
+      /* cinder-allow-raw-color: structural-pattern — neutral scroll-edge shadow, not a themeable surface */
+        linear-gradient(270deg, oklch(0% 0 0 / 12%), transparent) right center / 1rem 100% no-repeat
+        scroll;
+  }
+
+  .cinder-kanban-board__keyboard-hint {
+    margin: 0 0 var(--cinder-space-2);
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-xs);
+    opacity: 0;
+    transition: opacity var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  .cinder-kanban-board:focus-within .cinder-kanban-board__keyboard-hint {
+    opacity: 1;
   }
 
   .cinder-kanban-board__columns {
@@ -48,10 +71,24 @@
     min-inline-size: 0;
     overflow-wrap: anywhere;
     font-size: var(--cinder-text-sm);
-    font-weight: 600;
+    font-weight: var(--cinder-font-semibold);
     color: var(--cinder-text);
   }
 
+  .cinder-kanban-board__card-count {
+    display: inline-flex;
+    align-items: center;
+    margin-inline-start: var(--cinder-space-2);
+    min-block-size: 1.25rem;
+    padding-inline: var(--cinder-space-1-5);
+    border: 1px solid var(--cinder-border-muted);
+    border-radius: var(--cinder-radius-sm);
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+    white-space: nowrap;
+  }
+
   .cinder-kanban-board__column-actions {
     display: inline-flex;
     gap: var(--cinder-space-1);
@@ -63,8 +100,8 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    inline-size: 1.75rem;
-    block-size: 1.75rem;
+    inline-size: 2rem;
+    block-size: 2rem;
     padding: 0;
     border: 1px solid var(--cinder-border-muted);
     border-radius: var(--cinder-radius-sm);
@@ -73,6 +110,10 @@
     cursor: pointer;
   }
 
+  .cinder-kanban-board__column-handle svg {
+    fill: currentcolor;
+  }
+
   .cinder-kanban-board__column-handle:focus-visible,
   .cinder-kanban-board__collapse:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
@@ -81,6 +122,18 @@
       0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-ring-color);
   }
 
+  @media (forced-colors: active) {
+    .cinder-kanban-board__column-handle:focus-visible,
+    .cinder-kanban-board__collapse:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      /* 3px separates the outline from ButtonBorder (which renders in forced-colors
+         on all bordered controls and shares the ButtonText color family in HCM);
+         at 2px the ring and border can visually merge. */
+      outline-offset: 3px;
+      box-shadow: none;
+    }
+  }
+
   @media (hover: hover) {
     .cinder-kanban-board__column-handle:hover,
     .cinder-kanban-board__collapse:hover {

package/src/components/kanban-board/kanban-board.svelte

@@ -423,13 +423,13 @@
     },
   });
 
-  function cancelCardLift(itemLabel?: string): void {
+  function cancelCardLift(itemLabel: string | undefined = undefined): void {
     cardController.cancel(itemLabel);
     cardTarget = null;
     pointerColumnIndex = null;
   }
 
-  function cancelColumnLift(columnTitle?: string): void {
+  function cancelColumnLift(columnTitle: string | undefined = undefined): void {
     columnLiftedKey = null;
     columnTargetIndex = null;
     if (columnTitle) announcer.announce(`${columnTitle} column move cancelled.`);
@@ -554,6 +554,9 @@
     Press Space to lift a column, Left and Right arrows to move it, Space to drop, and Escape to
     cancel.
   </p>
+  <p class="cinder-kanban-board__keyboard-hint">
+    Space lifts. Arrow keys move. Space drops. Escape cancels.
+  </p>
 
   <div bind:this={columnsElement} class="cinder-kanban-board__columns" role="list">
     {#each visualColumns as column, columnIndex (invalidKeys ? `${column.id}-${columnIndex}` : column.id)}
@@ -587,6 +590,10 @@
             {:else}
               {column.title}
             {/if}
+            <span class="cinder-kanban-board__card-count">
+              {column.cards.length}{' '}
+              {column.cards.length === 1 ? 'card' : 'cards'}
+            </span>
           </div>
           {#if columnActions}
             <div class="cinder-kanban-board__column-actions">
@@ -597,7 +604,7 @@
             <button
               type="button"
               class="cinder-kanban-board__collapse"
-              aria-label={`${column.collapsed ? 'Expand' : 'Collapse'} ${column.title}`}
+              aria-label={`${column.collapsed ? 'Expand' : 'Collapse'} ${column.title} (${column.cards.length} ${column.cards.length === 1 ? 'card' : 'cards'})`}
               aria-expanded={!column.collapsed}
               onclick={() => toggleColumn(column)}
             >

package/src/components/kanban-board/kanban-board.types.ts

@@ -64,8 +64,12 @@ export type KanbanBoardProps<Card> = {
   columnHeader?: Snippet<[KanbanBoardColumn<Card>, KanbanBoardColumnContext<Card>]>;
   columnActions?: Snippet<[KanbanBoardColumn<Card>, KanbanBoardColumnContext<Card>]>;
   emptyColumn?: Snippet<[KanbanBoardColumn<Card>]>;
+  /** Accessible label applied to the board's `<section>` root via `aria-label`. */
   label?: string;
+  /** When true, each column renders a collapse/expand button that toggles its card list. */
   collapsible?: boolean;
+  /** When true (default), columns can be reordered by dragging or keyboard. Set to false to make column order fixed. */
   reorderColumns?: boolean;
+  /** Additional class merged onto the `.cinder-kanban-board` root element. */
   class?: string;
 };

package/src/components/kbd/README.md

@@ -16,11 +16,12 @@ A styled keyboard key element for displaying keyboard shortcuts in help text and
 
 <!-- generated:props:start -->
 
-| Prop    | Type             | Required | Default | Description                                       |
-| ------- | ---------------- | -------- | ------- | ------------------------------------------------- |
-| `class` | `string`         | no       | —       | Additional class names merged with `.cinder-kbd`. |
-| `label` | `string`         | no       | —       | Key label content.                                |
-| `size`  | `"sm"` \| `"md"` | no       | `"md"`  | Keyboard key size.                                |
+| Prop       | Type             | Required | Default | Description                                                                                   |
+| ---------- | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
+| `class`    | `string`         | no       | —       | Additional class names merged with `.cinder-kbd`.                                             |
+| `label`    | `string`         | no       | —       | Key label content.                                                                            |
+| `size`     | `"sm"` \| `"md"` | no       | `"md"`  | Keyboard key size.                                                                            |
+| `children` | `(opaque)`       | no       | —       | Key label content. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->