@f-ewald/components 1.0.0 → 1.0.2

package/docs/design-language.md

@@ -0,0 +1,149 @@
+# Component design language
+
+This is the canonical visual, interaction, and accessibility contract for
+`@f-ewald/components`. `CLAUDE.md` carries the short always-on rules; this file
+defines the details used when creating or reviewing components.
+
+## Principles
+
+- Components are compact, calm, and content-first.
+- Shared UI chrome uses design tokens; data-driven visuals may use consumer
+  colors when color conveys domain meaning.
+- Every component works with no external CSS and follows inherited light/dark
+  tokens when a consumer supplies them.
+- Native semantics and keyboard behavior come before custom ARIA.
+- Pointer, keyboard, focus, disabled, loading, empty, error, and reduced-motion
+  states are part of the design—not optional polish.
+
+## Tokens and colors
+
+- Use `var(--ui-*, exact-fallback)` for reusable colors, fonts, radii, shadows,
+  and focus rings.
+- Semantic states use `primary`, `info`, `success`, `warning`, and `danger`.
+- Foregrounds on solid semantic fills use `--ui-on-accent`.
+- Elevated dark tooltips use `--ui-tooltip`; modal backdrops use
+  `--ui-overlay` and are not interchangeable.
+- Static chart axes, labels, grids, skeletons, and default series use tokenized
+  SVG CSS classes. Consumer/data-series colors remain data.
+- Plain SVG presentation attributes may use literal token fallback values when
+  CSS variables are not practical. User-provided marker/chart colors are an
+  explicit exception.
+- White map rings, image-overlay controls, avatar foregrounds, and celebratory
+  confetti may remain literal when their contrast is intentionally independent
+  of the surrounding theme.
+
+## Typography
+
+- Body/component text: `--ui-font-size` at regular weight.
+- Compact controls/labels: `--ui-font-size-sm`, usually weight 500.
+- Secondary details/keycaps: `--ui-font-size-xs`.
+- Code/keycaps: `--ui-font-mono`.
+- Section/title emphasis should normally use weight 600; reserve 700 for badges
+  or data emphasis.
+
+## Spacing and geometry
+
+- Layout spacing uses literal multiples of `0.25rem`; spacing is not tokenized.
+- Convert CSS layout pixels to rems.
+- Exceptions: 1px borders, SVG/canvas geometry, percentages, aspect ratios,
+  animation timing, and proportional calculations derived from a public size.
+- Use `--ui-radius-sm` for controls, `--ui-radius` for cards/dialogs, and an
+  intentional full pill/circle radius only for pill/avatar/marker shapes.
+- Compact controls must retain a clear hit target and must not reserve layout
+  space for optional content that is absent.
+
+## Interaction states
+
+- Interactive surfaces provide hover, active/selected, disabled, and
+  `:focus-visible` states.
+- Focus uses `--ui-focus-ring` plus a real outline fallback in forced-colors.
+- Disabled controls use native `disabled` where possible; otherwise use
+  `aria-disabled`, suppress activation, and retain understandable contrast.
+- If a whole row/tile is clickable, it must have keyboard parity and must not
+  hijack nested interactive controls.
+
+## Motion
+
+- Keep transitions between 120ms and 250ms unless the behavior itself defines a
+  duration.
+- Nonessential transitions and animations must be removed under
+  `prefers-reduced-motion: reduce`.
+- Progress spinners may become static indicators in reduced motion.
+- Components driven by timers must clean up on disconnect.
+
+## Accessibility
+
+- Prefer buttons, links, inputs, radios, and dialogs over clickable generic
+  elements.
+- Custom comboboxes expose expanded state, controlled listbox, active option,
+  explicit selection, and no-results behavior.
+- Modal/centered overlays expose a name, `role="dialog"`, `aria-modal`, initial
+  focus, Escape behavior, focus containment, and focus restoration.
+- Collapsible controls expose `aria-expanded` and `aria-controls`.
+- Charts expose a concise accessible data summary.
+- Decorative icons/keycaps inside already-labelled controls are hidden from
+  assistive technology; standalone equivalents expose their own name.
+- Do not create noisy live regions for per-second timers.
+
+## Component exceptions
+
+- Metadata-only tags may omit standalone playground sections and screenshots
+  when their full behavior is demonstrated through a parent:
+  `calendar-entry`, `gallery-item`, and `gallery-item-variant`.
+- Styleless inline formatters may omit empty `static styles`/token imports:
+  `distance-value`, `live-timer`, `relative-time`, and `roman-numeral`.
+- Domain visuals may deliberately diverge in geometry and data color, but their
+  surrounding typography, focus, motion, and accessibility still follow this
+  contract.
+
+## Playground and documentation
+
+- Visual/interactive nav links and complete sections are alphabetical and have
+  identical ID sets.
+- Every visual section includes a live representative state and a copyable
+  usage example.
+- Every public property/event/mode is exercised in its section or an explicitly
+  linked parent section.
+- Public API changes update JSDoc, generated docs, `llms.txt`, README when
+  relevant, and the changelog.
+
+## Validation tiers
+
+1. Inner loop: `npm run typecheck` and all touched component specs in one
+   Playwright invocation.
+2. Run docs once after APIs/JSDoc stabilize.
+3. Run `npm run test:design` after token/catalog/state changes.
+4. Run screenshots once after the full design batch.
+5. Run the complete package/demo/Pages gate once at task completion.
+6. Reviewer fixes rerun only affected specs/contracts, followed by one final
+   full gate.
+
+Canonical screenshot baselines are generated by the **Generate visual
+baselines** GitHub Actions workflow on the same amd64 runner image used by CI.
+Run it manually, download the `visual-baselines-linux-amd64` artifact, review
+the images, and replace `visual-tests/__screenshots__/`.
+
+For local iteration, the pinned Playwright image provides a close
+architecture-matched preview:
+
+```bash
+docker run --platform linux/amd64 --rm --ipc=host \
+  -v "$PWD":/work -v /work/node_modules -w /work \
+  mcr.microsoft.com/playwright:v1.61.1-noble \
+  bash -lc "npm ci && npm run test:visual:update"
+```
+
+The architecture pin is required on Apple-silicon hosts, but installed fonts
+still differ slightly from GitHub-hosted runners. Local Docker repeatability
+does not replace the GitHub-generated baseline check. Run
+`npm run test:visual` natively only when using a matching checked-in platform
+baseline.
+
+## Review checklist
+
+- Shared tokens use exact fallbacks; data-color exceptions are intentional.
+- Spacing follows the scale and optional content consumes no empty space.
+- Light, dark, forced-colors, and reduced-motion states remain legible.
+- Pointer and keyboard behavior are equivalent.
+- Empty/error/loading/disabled/selected states are represented where relevant.
+- The playground and tests demonstrate the changed public behavior.

package/docs/distribution-chart.md

@@ -45,7 +45,11 @@ _None._
 
 | Custom property |
 | --- |
+| `--ui-border` |
 | `--ui-danger` |
+| `--ui-font` |
 | `--ui-font-size-sm` |
+| `--ui-primary` |
 | `--ui-radius-sm` |
+| `--ui-surface-muted` |
 | `--ui-text-muted` |

package/docs/dropdown-button.md

@@ -52,6 +52,7 @@ _None._
 | `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size-sm` |
+| `--ui-on-accent` |
 | `--ui-primary` |
 | `--ui-primary-hover` |
 | `--ui-radius-sm` |

package/docs/frame-box.md

@@ -38,6 +38,8 @@ _None._
 | Custom property |
 | --- |
 | `--ui-border` |
+| `--ui-font` |
+| `--ui-font-size-xs` |
 | `--ui-radius-sm` |
 | `--ui-surface` |
 | `--ui-text-muted` |

package/docs/kbd-hint.md

@@ -0,0 +1,42 @@
+# `<kbd-hint>`
+
+Renders a keyboard shortcut as one boxed keycap per `+`-separated token.
+Modifier keys are platform-aware: `Mod` becomes Command on macOS and
+Control elsewhere. Keycaps derive their presentation from `currentColor`,
+so the hint works inside neutral and accent-colored controls.
+
+## Install
+
+```js
+import "@f-ewald/components/kbd-hint.js";
+```
+
+## Usage
+
+```html
+<kbd-hint keys="Mod+K"></kbd-hint>
+<kbd-hint keys="Mod+Shift+Enter" platform="mac"></kbd-hint>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `keys` | `keys` | `string` | `""` | Shortcut as case-insensitive, `+`-separated tokens, e.g. `"Mod+Enter"`. |
+| `platform` | `platform` | `KbdPlatform` | `"auto"` | Platform override; `auto` detects macOS from the browser. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-font-mono` |
+| `--ui-font-size-xs` |
+| `--ui-radius-sm` |

package/docs/percent-bar-chart.md

@@ -37,4 +37,7 @@ _None._
 
 ## CSS custom properties
 
-_None._
+| Custom property |
+| --- |
+| `--ui-font` |
+| `--ui-text-muted` |

package/docs/photo-gallery.md

@@ -67,6 +67,7 @@ import "@f-ewald/components/photo-gallery.js";
 | `--ui-font` |
 | `--ui-font-size` |
 | `--ui-font-size-sm` |
+| `--ui-on-accent` |
 | `--ui-overlay` |
 | `--ui-primary` |
 | `--ui-radius` |

package/docs/popover-panel.md

@@ -59,8 +59,10 @@ import "@f-ewald/components/popover-panel.js";
 | Custom property |
 | --- |
 | `--ui-border` |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size` |
+| `--ui-overlay` |
 | `--ui-radius` |
 | `--ui-radius-sm` |
 | `--ui-shadow-lg` |

package/docs/price-history-chart.md

@@ -41,4 +41,11 @@ _None._
 
 ## CSS custom properties
 
-_None._
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-font` |
+| `--ui-on-accent` |
+| `--ui-primary` |
+| `--ui-text-muted` |
+| `--ui-tooltip` |

package/docs/radio-cards.md

@@ -33,6 +33,7 @@ import "@f-ewald/components/radio-cards.js";
 | --- | --- | --- | --- | --- |
 | `options` | _(JS property only)_ | `RadioCardOption[]` | `[]` | Options to render, one card each. |
 | `value` | `value` | `string` | `""` | Currently selected value. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables every native radio in the group. |
 
 ## Events
 
@@ -49,6 +50,7 @@ _None._
 | Custom property |
 | --- |
 | `--ui-border` |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size-sm` |
 | `--ui-primary` |

package/docs/radio-pills.md

@@ -33,6 +33,7 @@ import "@f-ewald/components/radio-pills.js";
 | --- | --- | --- | --- | --- |
 | `options` | _(JS property only)_ | `RadioPillOption[]` | `[]` | Options to render, one pill each. |
 | `value` | `value` | `string` | `""` | Currently selected value. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables every native radio in the group. |
 
 ## Events
 
@@ -49,6 +50,7 @@ _None._
 | Custom property |
 | --- |
 | `--ui-border` |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size-sm` |
 | `--ui-primary` |

package/docs/reveal-button.md

@@ -21,6 +21,7 @@ import "@f-ewald/components/reveal-button.js";
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `label` | `label` | `string` | `"Reveal hidden content"` | Label shown on the button before it's clicked. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables revealing the slotted content. |
 
 ## Events
 
@@ -36,8 +37,10 @@ _None._
 
 | Custom property |
 | --- |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size` |
+| `--ui-on-accent` |
 | `--ui-primary` |
 | `--ui-primary-hover` |
 | `--ui-radius-sm` |

package/docs/slide-panel.md

@@ -4,8 +4,8 @@ Generic sliding panel shell. Handles positioning, open/close animation,
 header chrome, and a close button. Body content is provided via the
 default slot; the consumer controls its own padding and overflow.
 
-Desktop: 300 px fixed right-side panel that slides from the right.
-Mobile (≤768px): bottom-sheet drawer (60vh) — reserved for future use.
+Desktop: fixed right-side panel that slides from the right.
+Mobile (≤48rem): bottom-sheet drawer (60vh) — reserved for future use.
 
 ## Install
 
@@ -46,8 +46,10 @@ import "@f-ewald/components/slide-panel.js";
 | Custom property |
 | --- |
 | `--ui-border` |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size` |
+| `--ui-radius` |
 | `--ui-radius-sm` |
 | `--ui-shadow-lg` |
 | `--ui-surface` |

package/docs/status-pill.md

@@ -38,6 +38,9 @@ _None._
 | --- |
 | `--ui-danger` |
 | `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-info` |
 | `--ui-primary` |
 | `--ui-success` |
 | `--ui-text-muted` |
+| `--ui-warning` |

package/docs/tile-grid.md

@@ -9,6 +9,12 @@ Optional `itemHref` makes whole tiles clickable (navigating via
 `location.hash`), without hijacking clicks on nested interactive elements
 (links/buttons) a tile's rendered content might contain.
 
+Optional `fileIcon` prefixes each tile with a decorative Heroicons
+"document" glyph, for grids whose items represent files — the icon never
+carries its own accessible name since the rendered tile content (e.g. a
+filename) already identifies the item. Off by default, so it consumes no
+layout space or markup for grids of non-file items.
+
 ## Install
 
 ```js
@@ -18,7 +24,7 @@ import "@f-ewald/components/tile-grid.js";
 ## Usage
 
 ```html
-<tile-grid></tile-grid>
+<tile-grid file-icon></tile-grid>
 <script type="module">
   const grid = document.querySelector("tile-grid");
   grid.items = [
@@ -37,6 +43,7 @@ import "@f-ewald/components/tile-grid.js";
 | `itemKey` | _(JS property only)_ | `(item: unknown, index: number) => string | number` | `—` | Stable identity for `items[i]`, used as the repeat-directive key. Defaults to the item's index. |
 | `renderTile` | _(JS property only)_ | `(item: unknown) => unknown` | `—` | Produces a tile's rendered content for `item`. Default: stringify. |
 | `itemHref` | _(JS property only)_ | `((item: unknown) => string | null) | null` | `null` | When set, clicking a tile (outside any nested link/button) navigates to this hash. |
+| `fileIcon` | `file-icon` | `boolean` | `false` | Prefixes each tile with a decorative "document" icon, for grids of file-like items. Off by default. |
 
 ## Events
 
@@ -51,8 +58,10 @@ _None._
 | Custom property |
 | --- |
 | `--ui-border` |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size-sm` |
 | `--ui-radius` |
 | `--ui-surface-muted` |
 | `--ui-text` |
+| `--ui-text-muted` |

package/docs/toast-notification.md

@@ -42,9 +42,12 @@ _None._
 | Custom property |
 | --- |
 | `--ui-danger` |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size` |
-| `--ui-primary` |
+| `--ui-hover-overlay` |
+| `--ui-info` |
+| `--ui-on-accent` |
 | `--ui-radius` |
 | `--ui-radius-sm` |
 | `--ui-shadow-lg` |

package/docs/ui-button.md

@@ -58,8 +58,10 @@ _None._
 | `--ui-border` |
 | `--ui-danger` |
 | `--ui-danger-hover` |
+| `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size-sm` |
+| `--ui-on-accent` |
 | `--ui-primary` |
 | `--ui-primary-hover` |
 | `--ui-radius-sm` |

package/docs/user-avatar.md

@@ -39,4 +39,5 @@ _None._
 | Custom property |
 | --- |
 | `--ui-font` |
+| `--ui-on-accent` |
 | `--ui-primary` |