@spaethtech/svelte-ui 0.18.1-dev.92.355f4cd → 0.18.1-dev.94.031fb33

package/CLAUDE.md

@@ -41,12 +41,25 @@ the shared `variant` (color/style) and `size` (sm/md/lg) axes.
 - `docs/themes.md` - CSS variables and theming guide
 - `docs/paradigm.md` - Development paradigm and workflow
 
-**Consumer-facing surfaces that ship in the npm package** (via the `files` whitelist — `dist` + these):
-`CLAUDE.md`, `docs/`, and two skills — **`.claude/skills/svelte-ui`** (how to USE the library) and
-**`.claude/skills/themes`** (theming). Consumers symlink those two skills into their own
-`.claude/skills/` so their Claude Code agents can invoke them. Keep both accurate when the component
-set / axes / token model change. The other skills (`demo`, `playwright-cli`) are internal-only and are
-NOT shipped.
+**Consumer-facing surfaces.** The npm package ships (via the `files` whitelist) `dist`, `CLAUDE.md`
+and `docs/` only. The two **consumer skills** are no longer bundled in the tarball — they are
+**published to the private `spaethtech/claude-plugins` marketplace** as the **`svelte-ui`** plugin, so
+a consumer installs them with `claude plugin install svelte-ui@spaethtech-plugins` (then restarts the
+session) instead of symlinking. They arrive namespaced: **`svelte-ui:usage`** (how to USE the library —
+source: `.claude/skills/svelte-ui/`) and **`svelte-ui:themes`** (theming — source:
+`.claude/skills/themes/`). Keep both accurate when the component set / axes / token model change, then
+**republish** (see "Publishing skills" below). The other skills (`demo`, `playwright-cli`) are
+internal-only and are NOT published.
+
+**Publishing skills (after editing `.claude/skills/svelte-ui` or `.claude/skills/themes`).** This
+repo is a marketplace publishing project — its `.claude-plugin/plugin.json` (the card) +
+`.claude-plugin/skills.json` (maps `svelte-ui`→`usage`, `themes`→`themes`) drive
+`~/claude-plugins/bin/skills.sh`. A skill edit only reaches consumers after a **version bump +
+republish**: `~/claude-plugins/bin/skills.sh bump [patch|minor|major] --project .`, commit + push this
+repo, then `~/claude-plugins/bin/skills.sh publish --project .` (dry-run first). Consumers update by
+version, so a republish without a bump is refused. `minor` for a real capability change, `major` only
+if a published skill is renamed/removed (breaks invoke-by-name). See
+`plugins/marketplace/skills/publishing/SKILL.md` in the marketplace for the full contract.
 
 ### Tech Stack
 

package/docs/themes.md

@@ -172,7 +172,7 @@ tint tokens are re-defined per theme scope; see the themes skill.
 This page documents the token _surface_. For the authoring side — swapping palette/sizing, tinting
 by variant (`--ui-accent` + `.ui-accent`), scoping/inverse surfaces, the custom-property freeze
 rule, the self-reference trap, and bridging to another design system (DaisyUI, shadcn, …) — see the
-themes skill: [`.claude/skills/themes/SKILL.md`](../.claude/skills/themes/SKILL.md).
+**`svelte-ui:themes`** skill (install with `claude plugin install svelte-ui@spaethtech-plugins`).
 
 > **Any scope that overrides `--ui-color-*` must also restate `--ui-color-neutral`** (and re-derive
 > `--ui-border-color`). Neutral borders/surfaces derive from `--ui-color-neutral`, which — by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.18.1-dev.92.355f4cd",
+  "version": "0.18.1-dev.94.031fb33",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"
@@ -35,9 +35,7 @@
     "!dist/**/*.test.*",
     "!dist/**/*.spec.*",
     "CLAUDE.md",
-    "docs",
-    ".claude/skills/themes",
-    ".claude/skills/svelte-ui"
+    "docs"
   ],
   "sideEffects": [
     "**/*.css"

package/.claude/skills/svelte-ui/SKILL.md

@@ -1,309 +0,0 @@
----
-name: svelte-ui
-description: How to build UIs with the @spaethtech/svelte-ui component library in a CONSUMER project — one-time setup (theme.css + Tailwind @source + unplugin-icons), the import + MDI-icon-snippet patterns, the shared variant/size axes, the composition standard (use library components, never raw <button>/<select>/<input>), and the component catalog. Use whenever adding or editing UI that uses @spaethtech/svelte-ui components. For palette/token/theming/inverse-surface work, use the companion `themes` skill instead.
----
-
-# Using @spaethtech/svelte-ui
-
-A **Svelte 5 (runes)** component library styled with **Tailwind CSS v4** and **MDI icons**. Every
-component is theme-aware via CSS variables and most consume the shared `variant` + `size` axes.
-Import from the package name — the **`@spaethtech/svelte-ui`** barrel, or a **per-component subpath**
-(`@spaethtech/svelte-ui/button`) — never a raw `dist/` path.
-
-> Depth lives in the package's shipped docs (`node_modules/@spaethtech/svelte-ui/docs/*.md`) and this
-> repo's `CLAUDE.md`. Theming (tokens, dark mode, inverse surfaces, brand bridging) → the **`themes`**
-> skill. This skill is the usage mental-model + patterns; read the docs for full per-component APIs.
-
-## One-time setup (per consumer project)
-
-Peer deps (not bundled): `svelte@^5`, `tailwindcss@^4`, `unplugin-icons@^23`, `@iconify-json/mdi@^1`.
-
-**1. Vite — add the icon resolver** (`vite.config.ts`), because the package ships bare `~icons/mdi/*`
-imports that resolve at the consumer's build time:
-
-```ts
-import Icons from "unplugin-icons/vite";
-export default defineConfig({
-  plugins: [/* sveltekit(), tailwindcss(), */ Icons({ compiler: "svelte" })],
-});
-```
-
-**2. CSS** (`app.css`, Tailwind v4) — import the theme and scan the dist so Tailwind emits the classes
-the components use:
-
-```css
-@import "tailwindcss";
-@import "@spaethtech/svelte-ui/theme.css";
-@source "../node_modules/@spaethtech/svelte-ui/dist"; /* path relative to this file */
-```
-
-> **Missing borders/styles after `npm update`?** Two causes: (1) the `@source` line above is absent or
-> its path is wrong, so Tailwind never emits the components' (arbitrary) classes — fix the glob. (2) A
-> version bumped a class string (e.g. 0.17 rewrote the neutral border classes), and Tailwind's build
-> **cached** the old scan — restart the dev server / clear the Vite+Tailwind cache and rebuild. If a
-> border resolves to the wrong colour (not missing), it's a **theme** issue — see the `themes` skill's
-> "restate `--ui-color-neutral` per scope" note.
-
-## Import & basic use
-
-```svelte
-<script>
-  import { Button, Input, Select } from "@spaethtech/svelte-ui";
-  let name = $state("");
-</script>
-
-<Input bind:value={name} placeholder="Name" />
-<Button text="Save" variant="primary" onclick={() => save(name)} />
-```
-
-### Barrel vs. per-component subpaths (dev cold-start / memory)
-
-Two import styles, both resolving to the same source (identical output, identical HMR-into-lib):
-
-- **Barrel** — `import { Button, Input } from "@spaethtech/svelte-ui"`. Convenient, but importing
-  *anything* from the barrel pulls *all* 71 component `.svelte` files into the dev compile graph (Vite
-  doesn't tree-shake a barrel in `dev`), so the dev server compiles the whole library on cold start.
-  Prod builds tree-shake normally, so this is a dev-time cost only.
-- **Per-component subpath** — `import Button from "@spaethtech/svelte-ui/button"`. Kebab-case of the
-  component name (`DataTable` → `/data-table`, `SideBarMenu` → `/side-bar-menu`, `DatePicker` →
-  `/date-picker`; multi-export folders keep their group, e.g. `Avatar`/`AvatarGroup` at `/avatar`).
-  Only the components you actually import get compiled. **On a memory-constrained dev host, prefer
-  subpaths exclusively** — it's the single biggest lever on svelte-ui's cold-start footprint.
-
-Non-component runtime **values** have their own component-free entries so they don't drag the barrel
-in either: **`@spaethtech/svelte-ui/utils`** (`toast`, `anchored`/`tooltip`, `setUiI18n`/`uiI18n`,
-`responsiveClasses`, …) and **`@spaethtech/svelte-ui/data`** (`createGrid`, query AST). **Types** are
-free from anywhere — `import type { Variant } from "@spaethtech/svelte-ui"` is erased at compile time
-and pulls no components, so type-only imports may stay on the barrel.
-
-```svelte
-<script>
-  import Button from "@spaethtech/svelte-ui/button";
-  import DataTable from "@spaethtech/svelte-ui/data-table";
-  import { toast } from "@spaethtech/svelte-ui/utils";
-  import { createGrid } from "@spaethtech/svelte-ui/data";
-  import type { Variant } from "@spaethtech/svelte-ui"; // type-only ⇒ free, no compile
-</script>
-```
-
-## Localization (i18n) — opt-in
-
-Components render their own microcopy (aria-labels, titles, "per page", "No results", month names…)
-through a message registry with **English defaults**. Do nothing → identical English output. To
-localize, call **`setUiI18n`** ONCE near the app root (a layout); partial `messages` merge over the
-defaults, so translate a subset and the rest stays English. `locale` also feeds the date components'
-`Intl.*` formatting (falls back to `navigator.language` when unset; a per-instance `locale` prop still
-overrides).
-
-```svelte
-<script>
-  import { setUiI18n } from "@spaethtech/svelte-ui";
-  import { getLocale } from "$lib/paraglide/runtime";
-  import { m } from "$lib/paraglide/messages";
-  setUiI18n({
-    locale: () => getLocale(),                       // getter ⇒ reactive; or a plain string
-    messages: () => ({
-      dismiss: m.ui_dismiss(),
-      selectAll: m.ui_select_all(),
-      rowRange: ({ start, end, total }) => m.ui_row_range({ start, end, total }), // "1–10 of 247"
-      removeFile: ({ name }) => m.ui_remove_file({ name }),
-      // …any subset of `UiMessages`
-    }),
-  });
-</script>
-```
-
-Parameterized entries are functions (`rowRange`, `removeFile`) — 1:1 with Paraglide's `m.key(params)`.
-Values may be plain or getters (getters make components re-render on locale change; plain is fine for
-per-navigation locale). Full key list: the `UiMessages` type; `defaultUiMessages` is the English source.
-Strings already exposed as PROPS (`Select placeholder`, `EmptyState title`, `CommandPalette empty`…) you
-localize directly on the component. **Authoring rule (this repo):** every new user-facing string a
-component renders must go through `uiI18n().messages` + `defaultUiMessages`, never a bare literal.
-
-## The two shared axes (mirror each other)
-
-- **`variant`** — color/style: `primary` `secondary` `danger` `info` `success` `warning` `ghost`
-  `plain` (`neutral` on some components). `plain` = borderless/transparent, for dense icon controls.
-- **`size`** — `sm` (24px) · `md` (32px, **default**) · `lg` (40px). Consistent height across every
-  sizeable component, so a `Button`, `Input`, and `Select` at the same `size` line up.
-
-Both accept a responsive map too, e.g. `size={{ base: "sm", md: "lg" }}`.
-
-## Field chrome (label / help / error)
-
-Every field-shaped control — `Input`, `Select`, `TextArea`, `Checkbox`, `Toggle`, and the specialized
-inputs — renders its own label + help/error frame from a shared set of props. **Don't hand-wrap fields
-in `<label>` + hint spans** — use these:
-
-- **`label`** (string) — rendered **above** the control, left-aligned. Uniform for *every* control
-  (checkbox/toggle labels sit above too), so a row of mixed controls at the same `size` lines up
-  pixel-perfect. For any other placement, omit `label` and bring your own `<label>`.
-- **`aside`** (Snippet) — right-aligned in the label row: a char count, status badge, link, button.
-- **`error`** (string | Snippet) — inline error row; also flips the error border + `aria-invalid`.
-  String is rendered as `{@html}`.
-- **`description`** (string | Snippet) — muted help row below the error (they coexist). String is
-  `{@html}` — **author-controlled markup only**, never untrusted input (use the Snippet form for that).
-- **`required`** — appends `*` to the label + sets `aria-required`.
-- **`id`** — auto-generated if omitted; wires `<label for>` + `aria-describedby`.
-
-`label`/aria wiring is automatic. Omit all of them and the field renders bare, exactly as a plain
-control.
-
-```svelte
-<Input
-  label="Slug"
-  description="Lowercase, hyphens only."
-  error={slugTaken ? "That slug is already taken." : null}
-  bind:value={slug}
-/>
-
-<!-- Mixed controls in a grid all align on the same label row + control baseline: -->
-<div class="grid grid-cols-4 gap-4 items-start">
-  <Input label="Name" bind:value={name} />
-  <Select label="Role" {options} bind:value={role} />
-  <Toggle label="Notifications" bind:checked={notify} />
-  <Checkbox label="Agree" bind:checked={agree} required />
-</div>
-```
-
-**Validation vs. error:** the built-in `validate={(v) => true | "message"}` (on Input/TextArea)
-surfaces through the **native validity tooltip** (shown on form submit); the controlled **`error`**
-prop is the inline row. Both flip the field's error border.
-
-**Groups:** for a set of radios/checkboxes/toggles under one legend, wrap them in **`FieldGroup`**
-(same `label`/`description`/`error`/`required` vocab on a `<fieldset>`, plus `columns` — a number or
-responsive map; default 1 = stacked, higher lays items across equal auto-placed columns — and `gap`,
-a number or `{ x, y }`). For non-field content, **`Grid`** is the same auto-placement as a plain
-primitive (`columns` + `gap`, any children). Inside a
-group, item labels render **inline** (right of the control). For a radio group, `bind:value` on the
-`FieldGroup` (+ optional `name`) and the child `<Radio>`s share it automatically — no `bind:group`:
-
-```svelte
-<FieldGroup label="Delivery" bind:value={method} name="method">
-  <Radio value="email" label="Email" />
-  <Radio value="sms" label="SMS" />
-</FieldGroup>
-```
-
-## Icons — no `<Icon>` component
-
-Import an MDI icon component from `~icons/mdi/*` and render it into a component's **`icon` snippet**;
-the library sizes and colors it to match `size`/`variant`:
-
-```svelte
-<script>
-  import { Button } from "@spaethtech/svelte-ui";
-  import IconHome from "~icons/mdi/home";
-</script>
-
-<Button title="Home" variant="plain">{#snippet icon()}<IconHome />{/snippet}</Button>
-```
-
-## Composition standard (important)
-
-Build UI out of these components — **never** raw `<button>` / `<select>` / `<input>` / `<textarea>`
-for things the library covers. A raw interactive element where a library component fits is a bug: you
-lose the theme, the axes, focus states, and a11y. Compound pieces are already composed this way
-(e.g. DataTable's controls are `<Button variant="plain">` + `<Select size="sm">`).
-
-## Toasts
-
-Mount `<Toaster />` once at the app root, then push from anywhere with `toast.success(...)` /
-`toast.error(...)` / etc. — no prop plumbing:
-
-```svelte
-<script>
-  import { Toaster, toast } from "@spaethtech/svelte-ui";
-</script>
-<Toaster />
-<Button text="Go" onclick={() => toast.success("Saved")} />
-```
-
-## Component catalog
-
-All from `@spaethtech/svelte-ui` (see the shipped `docs/components.md` + `docs/usage.md` for props +
-examples):
-
-- **Form:** `Button` `ButtonGroup` `Input` `Select` `Combobox` `Slider` `List` `TextArea` `Checkbox`
-  `Toggle` `Radio` `Rating` (display `average`/`count`, OR `interactive` + `bind:value` star picker
-  with `allowHalf`, click/hover/arrow-keys) · **`Combobox`** (free-text autocomplete — arbitrary value + suggestions,
-  client `options` or async `suggest`; vs `Select` which is a closed choice. Composes Input + Popup.) ·
-  **`TokenInput`** (multi-value entry — Enter/comma adds a removable `Chip` token, Backspace-on-empty
-  removes; `bind:values`, `max`, `allowDuplicates`; FieldChrome.) · **`FileUpload`** (drag-drop + click
-  dropzone; `bind:files`, `accept`/`multiple`/`maxSize`, image thumbnails, `progress` map → `Progress`
-  bar; FieldChrome.) · **`Slider`** (draggable number/range; `range` dual-thumb, `min`/`max`/`step`,
-  `showValue`/`format`; FieldChrome + `variant`/`size`; keyboard + `role="slider"`) · **`FieldGroup`**
-  (fieldset wrapper for radio/checkbox/toggle sets) · **`ButtonGroup`**
-  (joined row/`col` of `<Button>`s as one unit — an action toolbar or a **controlled** segmented
-  selector; `items` of `ButtonGroupItem` {`value`,`text`,`icon`,`variant`,`disabled`,`loading`,`href`/
-  `target`,`menu`,`menuOnly`,`onclick`} or a presentational default slot; `select`
-  `'none'|'single'|'multi'` with `bind:value`/`bind:values`; selected = variant-swap to filled,
-  unselected = `ghost`; the group owns the frame. An item `menu` (`MenuItem[]`) makes a **split
-  button** (action + caret); add `menuOnly` for a caret-only **menu-trigger** cell (e.g. an
-  `[action][▾]` pair = a plain item + a `menuOnly` item). This replaces the old `ButtonDropdown`. Not
-  a form field — for legend/`name`/submit use `FieldGroup`; for view switching use `TabStrip`.)
-- **Specialized inputs:** `PasswordInput` `EmailInput` `SearchInput` `NumberInput` (formatting +
-  `percent`/`stepper`/`clamp`/`liveFormat`) `PhoneInput` (stores E.164; dep-free, inject
-  `parse`/`format` for per-country)
-- **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`.
-  For a start–end range use **`DatePicker range`** (`bind:value` = `{ start, end }`) — it composes
-  `Calendar mode="range"`.
-- **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**
-  (query-language parser/AST via `parseQuery`, `createGrid`, `DataGrid<T>`, `DataSet`). For a
-  **client-held array**, use **`localFetch(rows, columns, opts?)`** as the grid's `fetch` — it parses
-  the query, filters via **`matchesRow(row, ast)`** (the in-memory AST evaluator: cmp/and/or/not/
-  match/in/range/search, honouring column `id`/`searchable`/`sortKey`), then sorts + paginates. Only a
-  remote/DB backend needs to compile the AST itself; do NOT hand-roll a "strip `$` + substring" filter.
-  `createGrid` also takes **`selectableRow: (row) => boolean`** — rows returning `false` are locked out
-  of selection (disabled checkbox, excluded from select-all, never in `grid.selected`), so
-  `bulkActions(selected)` never sees them; don't filter locked ids in the handler.
-  · **`Pagination`** (standalone
-  pager styled like the DataTable footer: tinted band, per-page `Select`, range total, and a
-  `First·Prev·[page]/N·Next·Last` stepper whose indicator is an editable `NumberInput` quick-jump;
-  `bind:page`/`bind:perPage`, `total`, `perPageOptions`, `showEdges`/`showTotal`, `borderless`;
-  `variant` tints band+hover only; built from `Button`+`Select`+`NumberInput`).
-- **Overlays:** `Dialog` (pure modal shell — BYO content; `width`/`height` take any CSS value;
-  `onShow(ctx)`/`onHide(ctx)` control focus — set `ctx.autoFocus` to a selector/element/`false`,
-  `ctx.restoreFocus` likewise) · `ConfirmDialog` (title + message + Confirm/Cancel, built on Dialog)
-  · **`Drawer`** (edge-anchored sliding panel / "sheet"; `side` left/right/top/bottom, `size` CSS
-  length, `bind:open`, `dismissible`/`backdrop`; same modal mechanics as Dialog — a pure shell, put a
-  Card inside) · `Popup` `Menu` · **`ContextMenu`** (right-click menu at the pointer; `items` MenuItem[]; on `Menu`) · **`CommandPalette`** (⌘K/Ctrl+K fuzzy command launcher; `bind:open`, `commands` Command[] {`label`,`keywords`,`group`,`icon`,`shortcut`,`disabled`,`onrun`}, global `hotkey` default `"mod+k"`; ↑/↓/Enter/Esc; on `Input`+`Kbd`) · `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
-- **Navigation:** **`Tree`** (hierarchical expandable tree — `items` of `TreeNode`; `bind:expanded`/`selected`; roving-tabindex keyboard; ARIA `tree`) · **`Breadcrumbs`** (trail of `BreadcrumbItem` {`label`,`href`,`onclick`,`icon`}; last =
-  current page; `maxItems` collapses the middle to a `⋯` Menu; `separator` slot) · `TabStrip` (tabs;
-  `size`/`variant`, `gap`/`pad` bordered spacer cells, `height` for a
-  fixed-height bar with bottom-aligned tabs, `activeSurface` to flow the active tab into the content
-  below) · **`SideBarMenu`** (data-driven vertical nav: `items`/`bottomItems` of `SideBarMenuItem`
-  {`icon`,`label`,`link`,`badge`,`children`,`onclick`,`popout`,`reload`,`trailing` snippet,`activeMatch`};
-  responsive `modes` map + `iconHoverExpand`; `variant` tints only hover/active; `size`; `side`;
-  `interactMode` `'hover'|'click'` popouts; `currentPath` active-match (per-item `activeMatch` for
-  query-keyed/exact rules); `bind:open`/`bind:api`/`bind:activeMode`; `publishWidthVar` → CSS width var;
-  popouts expose `data-sbm-popout`/`data-open`)
-- **Feedback:** `Alert` `Banner` `Badge` `Toaster` + `toast` · **`Kbd`** (keyboard keycap; `text`/`keys` combo) · **`Spinner`** (indeterminate loading
-  ring; `variant`/`size`, omit `variant` to inherit `currentColor`. `Button` has a `loading` prop that
-  renders one in place of its icon and blocks interaction.) · **`Progress`** (horizontal bar;
-  determinate `value`/`max` or `indeterminate` sweep; `variant`/`size` = 4/8/12px; `label`/`showValue`.)
-  · **`Skeleton`** (neutral loading placeholder; `shape` text/rect/circle, `lines`, `width`/`height`,
-  `animate` shimmer. No `variant` — it's absent-content, not a themed surface. Compose to sketch a card.)
-- **Layout:** `Card` `CardHeader` `CardBody` `CardFooter` · **`Grid`** (auto-placed equal-cell grid;
-  `columns` + `gap`) · **`ScrollArea`** (themed thin-scrollbar container; `orientation`, `maxHeight`, `variant` thumb) · **`Splitter`** (two resizable panes + draggable divider; `bind:size` %, `orientation`, keyboard) · **`Carousel`** (sliding viewport; `items` + `slide` snippet, `bind:index`, `autoplay`, controls + dots) · **`Stat`** (metric/KPI card — `label`/`value`/`delta` up-down + `icon`; on `Card`) · **`Timeline`** (vertical event list — `items` of `TimelineItem` {`title`,`time`,`description`,`icon`,`variant`}) · **`Divider`** (thin `role="separator"` rule; `orientation` h/v, optional inline
-  `label`+`labelAlign`; `--ui-border-color`)
-- **Flow:** **`Stepper`** (linear multi-step indicator — `steps` of `StepItem` {`label`,`description`,
-  `icon`}, `bind:current`, `orientation` h/v, `onstep` clickable; done/current/upcoming markers +
-  connectors. Panels + Next/Back are the consumer's.)
-- **Disclosure:** **`Disclosure`** (one expand/collapse section; `title`/`header`, `bind:open`, panel
-  stays mounted so state is preserved) · **`Accordion`** (coordinated group — `multiple` single/multi,
-  `bind:value`; children are `<Disclosure value="…">`, no per-item `bind:open`)
-- **Display / theme:** **`EmptyState`** (zero-data placeholder — icon + title + description + `action`) · **`Chip`** (interactive pill — `selected` toggle fill, `removable` ×/`onremove`,
-  `onclick`/`href`, `icon`; the interactive counterpart to display-only `Badge`) · **`Avatar`** (image →
-  `name` initials → `icon` → glyph fallback; `size`, `variant` fill, `shape`, `status` dot) +
-  **`AvatarGroup`** (overlapped stack; `items`+`max` → `+N`) ·
-  `NotesEditor` · `ThemeSelector` (Auto/Light/Dark Select) · `ThemeToggle`
-  (compact ☀/☾ icon button, same persisted state)
-- **Types / utils:** `Variant` `Size` `TabDefinition` `MenuItem` `ButtonGroupItem` `ButtonGroupSelect`
-  (types), `responsiveClasses` / `resolveScalar`, `BREAKPOINT_PX`.
-
-## Adopting updates
-
-The lib is versioned on npm. Pin a caret range (`^x.y.z`) and `npm update` for fixes; a `dev` dist-tag
-tracks the newest `main` build (`npm install @spaethtech/svelte-ui@dev`) for testing unreleased work.
-Pre-1.0, a **minor** bump can be breaking — check the package's `CHANGELOG.md` before bumping the range.

package/.claude/skills/themes/SKILL.md

@@ -1,357 +0,0 @@
----
-name: themes
-description: How svelte-ui theming works and how to build/consume a theme — the --ui-* token surface, the --ui-accent interactive-tint system + variants, light/dark application, scoped "inverse" surfaces, the custom-property freeze rule, and bridging to another design system. Use when swapping palette/sizing, tinting a surface by variant, putting components on an inverse (dark-on-light / light-on-dark) surface, or bridging svelte-ui to DaisyUI/shadcn/brand tokens.
----
-
-# Theming svelte-ui
-
-svelte-ui themes via **plain CSS custom properties** — no Sass, no JS theme object, no
-compile step. Every component reads a small set of **`--ui-*`** tokens; redefine those and
-every component follows. Two built-in themes, **light** (default) and **dark**, follow the
-system preference and can be forced with the `.theme-light` / `.theme-dark` classes.
-
-Authoritative source: [`src/lib/theme.css`](../../src/lib/theme.css). Everything below reflects
-that file — if they ever disagree, the file wins and this skill is stale.
-
-## The token surface — everything is `--ui-*`
-
-There are **no unprefixed tokens** and **no component-scoped tokens**. Components consume the
-shared vars directly. (The old `--color-*` palette, `--ui-padding*`/`--ui-border` density, and
-per-component `--dt-*`/`--card-*` namespaces have all been removed — don't reintroduce them.)
-
-### Palette — `--ui-color-*`
-
-```
---ui-color-background   --ui-color-text      --ui-color-neutral
---ui-color-primary      --ui-color-secondary
---ui-color-success      --ui-color-warning
---ui-color-error        --ui-color-info
-```
-
-These are the only palette colours a component references. The `variant` axis
-(`types/variants.ts` → `variantToken`) maps each `Variant` to one of these (`danger`→`error`; the two
-non-accent variants `neutral` and `ghost` → **`--ui-color-neutral`**). Canonical order:
-`neutral · primary · secondary · success · info · warning · danger · ghost`.
-
-**`neutral` is the default/undefined variant** — every sizeable/themeable component defaults to
-`variant="neutral"`, so out of the box the whole library is **monochrome**; a colour appears only when
-you set an explicit `variant`. **`--ui-color-neutral`** is the themeable neutral base: it **defaults to
-`var(--ui-color-text)`** (so it flips opposite `--ui-color-background` per theme, and a border mixed
-toward `transparent` always reads against the background), but a theme can override it **independently
-of body text** to recolour every neutral border/surface at once. Every neutral border/divider — and
-`--ui-border-color` — derives from it, so it's the single knob for "the colour of all neutral borders".
-
-- `ghost` — borderless, transparent, hover-tint only (the minimal control). For the box-shaped
-  **fields** (Input/Select/TextArea) this also drives the **field background**: `ghost` → transparent,
-  every other variant → `--ui-color-background` (so a field reads as a field on any surface).
-- `neutral` — the _uncoloured_, **default** variant (mixes from `--ui-color-neutral`, which defaults to
-  `--ui-color-text`): **solid** in solid contexts (Button/Toggle/Banner → black-on-white /
-  white-on-black), a **tint** in soft/bordered contexts (Badge/Alert/Input/Card frame).
-- (`plain` was removed — it's now `ghost`. Old bordered-`ghost` → `neutral`.)
-
-Field **help/error text** uses no new token: the muted `description` row is an inline
-`color-mix(in srgb, var(--ui-color-text) ~65%, transparent)`, and the `error` row uses
-`--ui-color-error`.
-
-### Interactive-surface tints — `--ui-accent` + hover/surface/active
-
-One tint language for every hover / section / pressed surface, three steps of the SAME mix:
-
-```
---ui-color-hover      4%   row / option / ghost-button hover      (lightest)
---ui-color-surface    8%   header / footer / section bands        (a notch darker)
---ui-color-active    12%   pressed / held                         (strongest)
-```
-
-Each is `color-mix(in srgb, var(--ui-accent) N%, transparent)`. The percentages are
-**theme-independent** (identical in light and dark); only the accent colour flips. `--ui-accent`
-**defaults to `--ui-color-text`**, so out of the box these are neutral grey tints. Point
-`--ui-accent` at a semantic colour and all three follow — that is how a **variant tints a whole
-surface** (see the accent system below).
-
-### Tinted-surface scale — `--ui-tint-*`
-
-A variant-_tinted_ surface (a Badge chip, a Card frame, a `filled` Alert) mixes the component's OWN
-variant token at shared strengths, so every tinted surface is calculated identically:
-
-```
---ui-tint-soft         12%   soft resting fill        (Badge fill, Alert `filled`)
---ui-tint-divider      30%   soft internal divider    (CardHeader/CardFooter separators; the default
-                                                        NEUTRAL divider is `--ui-border-color`)
---ui-tint-border       50%   bordered surface, REST   (Badge/Alert/Banner ring · Card/DataTable/Input/
-                                                        TextArea frame · Button outline)
---ui-tint-border-hover 80%   bordered field, HOVER    (Input/TextArea/Card/DataTable/Button — the
-                                                        stronger step on hover/focus)
---ui-tint-strong       80%   foreground text          (Badge)
-```
-
-e.g. `color-mix(in srgb, var(<variant-token>) var(--ui-tint-soft), transparent)`. A `primary` badge is
-primary@these; a `neutral` (default) one is **`--ui-color-neutral`**@these. Theme-independent (a theme
-MAY override them to tune the whole tint language). **Every bordered surface uses ONE calc** —
-`--ui-tint-border` at rest, `--ui-tint-border-hover` on hover/focus, from the variant token — with **no
-`secondary` special case**. A default (neutral) frame is therefore `--ui-color-neutral` @ these; a
-default divider is `--ui-color-neutral` @ `--ui-tint-divider` (= `--ui-border-color`). Internal
-**dividers** use the softer `--ui-tint-divider` (30%) tier, likewise one calc per variant — so a
-divider always reads lighter than the frame at any variant. `--ui-border-color-strong`/`-strong-hover`
-have been **REMOVED** (migrate to `color-mix(in srgb, var(--ui-color-neutral) var(--ui-tint-border),
-transparent)`, hover → `--ui-tint-border-hover`). (Distinct from the interactive tints above, which mix
-from `--ui-accent`.)
-
-### The `borderless` prop (border-colour swap, never a border-width change)
-
-Every surface/framed component (`Button`, `Badge`, `Banner`, `Alert`, `Card`, `Input`, `DataTable`)
-takes a **`borderless`** boolean. The border is **always 1px** — only its _colour_ moves, so toggling
-it can't shift the box by a pixel:
-
-- `borderless={true}` → border-colour = the component's **own background** (ring hidden, space kept).
-- `borderless={false}` → border-colour = the **standard tint-border** (`--ui-tint-border` at rest,
-  `--ui-tint-border-hover` on hover/focus for the interactive fields) — the same calc for every surface.
-
-Defaults differ by component (fill-y things default `true`: Button/Badge/Banner; framed things default
-`false`: Alert/Card/Input/DataTable). One consequence worth knowing: a **`ghost` Button with
-`borderless={false}`** is the **outline button** (transparent fill + a `--ui-color-text` tint edge) —
-there is deliberately no separate `outline`/`ghost-bordered` variant. Toggle/Checkbox intentionally do
-NOT take `borderless`.
-
-### Border / radius — `--ui-border-*`
-
-```
---ui-border-radius              corner radius — ONE fixed value for every rectangular surface; NOT
-                                scaled by `size`, no -sm/-lg (pills use rounded-full)
---ui-border-color               soft internal divider (row separators, section splits) — NEUTRAL:
-                                `--ui-color-neutral` @ `--ui-tint-divider` (30%). Repeated per theme
-                                scope so it re-resolves per theme + survives @theme tree-shaking.
-                                (--ui-border-color-strong/-strong-hover were REMOVED — use the
-                                 `--ui-tint-border` / `--ui-tint-border-hover` scheme instead)
---ui-color-neutral              the neutral/undefined-variant base colour; defaults to
-                                `var(--ui-color-text)`. Override to recolour ALL neutral borders +
-                                surfaces at once, independent of body text + the variant colours.
-```
-
-**One hue, two weights.** All *neutral* borders share the `--ui-color-neutral` hue; only the tint
-weight differs by role — **divider** `--ui-tint-divider` (30%, `--ui-border-color`) vs **frame**
-`--ui-tint-border` (50%). A `variant`-set border tints from that variant's token instead (a `secondary`
-Card = cyan border) — that's intended; the neutral default is what's monochrome.
-
-### Density / text / icon — the `size` axis
-
-```
---ui-height-sm / --ui-height / --ui-height-lg     control square heights (sm/md/lg)
---ui-height-touch                                  explicit 44px touch target (not a size tier)
---ui-text-sm / --ui-text / --ui-text-lg            per-size text
---ui-icon-sm / --ui-icon / --ui-icon-lg            per-size inline icons
-```
-
-The `sm/md/lg` triplets are tied to the `size` prop on every sized component — override one
-tier and every component on that tier shifts. (Per-component _padding/gap_ is NOT a token; it's
-a `Record<Size,string>` Tailwind class map inside each component.)
-
-### Breakpoints (in `@theme`)
-
-Narrow-mobile tiers `4xs` 320 / `3xs` 360 / `2xs` 420 / `xs` 480 and ultrawide `3xl` 1920, on
-top of Tailwind's defaults — so `DataTable` column placements can target the full range.
-
-## The accent / variant system
-
-`--ui-color-hover/surface/active` mix from `--ui-accent`. To tint a surface, override
-`--ui-accent` — **but you must also RE-MIX** the three tokens where you override it, via the
-`.ui-accent` class:
-
-```html
-<!-- a DataTable, but any surface works the same -->
-<div class="ui-accent" style="--ui-accent: var(--ui-color-primary)">…</div>
-```
-
-`.ui-accent` (defined in `theme.css`) redefines hover/surface/active from the local
-`--ui-accent`. Setting `--ui-accent` **alone is not enough** — see the freeze rule below for
-why. The reference consumer is **`<DataTable variant="…">`**: its root always carries
-`.ui-accent` and, when a `variant` is passed, sets `--ui-accent: var(<variantToken>)`, tinting
-row hover + header/footer bands with that colour. No variant → neutral grey.
-
-### Implementing `variant` tinting in a component (author recipe)
-
-Every themed component does this the **same** way (DataTable / List / Menu / CardBody / TabStrip).
-Follow it exactly — do **not** invent a new mechanism:
-
-1. Resolve the variant to its colour token and build an inline-`style` string that sets the shared
-   `--ui-accent` — **only for a real accent** (greyscale variants resolve to `--ui-color-text`, the
-   default, so leave `--ui-accent` unset):
-   ```svelte
-   const accentVar = $derived(variant ? `--ui-accent: var(${variantToken[variant]});` : '');
-   ```
-2. Put `.ui-accent` on the component root and apply the style: `class="ui-accent …" style={accentVar}`.
-3. Everywhere you need the variant colour, read **`var(--ui-accent)`** from a **static** Tailwind
-   class — the accent tints (`--ui-color-surface/hover/active`) automatically; for text/borders read
-   `var(--ui-accent)` directly, e.g. `[color:var(--ui-accent)]`,
-   `[border-color:color-mix(in_srgb,var(--ui-accent)_var(--ui-tint-border),transparent)]`.
-
-**Two hard rules — both are silent failures, not `svelte-check` errors:**
-
-- **NEVER a per-component custom property.** No `--ui-tab-border`, `--dt-*`, `--card-*`, etc. The
-  variant colour lives in the shared `--ui-accent`; components only ever _read_ it. (See "Extending
-  upstream" — lift a hard-coded value into a shared `--ui-*` token, never a component namespace.)
-- **NEVER build a Tailwind class by interpolating a token/value at runtime.** Tailwind only emits
-  arbitrary-property CSS for class strings it finds **literally in source**. A runtime-built
-  `` `[--ui-accent:var(${token})]` `` or `` `[border-color:${x}]` `` is never scanned → the class
-  applies at runtime but **no CSS backs it**, so it silently does nothing (every variant falls back to
-  neutral). Two consequences: dynamic custom-prop values go through inline **`style`** (step 1), and
-  repeated `color-mix(…var(--ui-accent)…)` classes are written out **in full**, per state, not
-  factored into a `const` and interpolated.
-
-## Applying a theme
-
-### Light / dark, and the switcher rule
-
-`.theme-light` / `.theme-dark` are set on **`<html>` (documentElement)** — matching the
-pre-hydration script in `app.html` and the system `@media (prefers-color-scheme)` fallback. A
-theme switcher **must toggle the class on `documentElement`, never `<body>`** (`ThemeSelector`
-does this). Putting it on `<body>` leaves `<html>` on the system path and freezes the
-accent-derived tints to the wrong theme (see below).
-
-### Global palette override (whole app)
-
-Set `--ui-color-*` at `:root` after importing the theme:
-
-```css
-@import "tailwindcss";
-@import "svelte-ui/theme.css";
-:root {
-  --ui-color-primary: #ff6600;
-  --ui-color-background: #0d1117;
-  --ui-color-text: #e6edf3;
-  --ui-color-neutral: var(--ui-color-text); /* ≥0.17 — restate so neutral borders track your text */
-}
-```
-
-A bare `:root` override like this works because `--ui-color-neutral` (declared at `:root` in
-`theme.css`) re-resolves on `:root`. But the moment you override the palette in a **more specific
-scope** (`.theme-*`, a branding class, an inverse-surface subtree), you MUST restate
-`--ui-color-neutral` + `--ui-border-color` in that scope too (freeze rule).
-
-### Scoped override / **inverse surfaces** (a subtree)
-
-Because the theme classes are ordinary CSS, apply one to **any container** to re-theme just
-that subtree. This is the blessed pattern for an **inverse surface** — e.g. a dark header on a
-light page, where component text/icons would otherwise be dark-on-dark and invisible:
-
-```svelte
-<header class="theme-dark bg-black">
-  <Button variant="primary">…</Button>
-  <!-- text/icons resolve LIGHT → visible -->
-  <ThemeSelector />
-</header>
-```
-
-Every svelte-ui component inside inherits the subtree's tokens (text flips to light, hover/
-surface/active/accent all re-mix for the dark surface). **Prefer this over a per-component
-`inverse` prop** — one class covers the whole subtree, composes at any depth, and adds no API
-surface. For a single control, put the class on its nearest wrapper. This only works correctly
-because the tint tokens are defined **per theme scope** (the freeze rule) — without that,
-`.theme-dark` on a subtree would leave hover/surface frozen to `:root`.
-
-## The custom-property freeze rule (the mechanic behind everything above)
-
-A custom property whose value contains `var(...)` is resolved **at the element where it is
-DEFINED**, then inherited already-resolved. A descendant that overrides the referenced variable
-does **not** retroactively re-resolve it. Verified: `--m: color-mix(var(--acc)…)` at `:root`
-with `--acc` overridden on a child stays the `:root` colour; redefining `--m` in the child's
-scope picks up the child's `--acc`.
-
-Two consequences baked into `theme.css`:
-
-1. **Tints AND neutral-derived tokens are repeated in EVERY theme scope** (`:root`, `@media
-(prefers-color-scheme:dark) :root`, `.theme-light`, `.theme-dark`) rather than defined once at
-   `:root` — so they re-resolve against whichever theme (and `--ui-accent`) is in scope. This
-   covers `--ui-color-hover/surface/active` **and** `--ui-color-neutral` + `--ui-border-color`
-   (both derive from `--ui-color-text`). This is why scoped themes and the switcher-on-`<html>`
-   rule work, why a switcher on `<body>` breaks them, and why **any custom scope that overrides the
-   palette must also restate `--ui-color-neutral`/`--ui-border-color`** (see Building a custom theme).
-2. **Overriding `--ui-accent` requires the `.ui-accent` re-mix class** — the override alone
-   can't re-tint tokens computed higher up.
-
-Also: these tints are **plain `:root`/class CSS, not `@theme`**. Tailwind v4 only emits an
-`@theme` variable that backs a recognised utility; it never looks inside arbitrary classes like
-`[background-color:var(--ui-color-hover)]`, so an `@theme` home would get them tree-shaken out
-of the final bundle (the symptom: hover works off the SSR critical CSS during load, then dies).
-
-## The self-reference trap
-
-CSS silently invalidates a custom property that resolves to a `var()` of **itself**:
-
-```css
-/* WRONG — becomes guaranteed-invalid/unset; components reading it lose their colour */
-.theme-x {
-  --ui-color-success: var(--ui-color-success);
-}
-```
-
-To keep an inherited value, **omit the line entirely** — `--ui-*` already inherits from the
-outer scope. Only list a token when you want a _different_ value. If the outer scope doesn't
-define it at all, either import `svelte-ui/theme.css` globally so `:root` has the full palette,
-or give a literal value in the wrapper.
-
-## Building a custom theme / bridging another design system
-
-The common case isn't picking colours from scratch — it's **aliasing svelte-ui's `--ui-*`
-tokens to a palette already loaded in the host** (DaisyUI, shadcn, MUI, brand vars). Because
-custom properties resolve at use-time, the host system's cascade applies automatically.
-
-```css
-/* scoped bridge onto a host's tokens */
-.theme-myapp {
-  --ui-color-background: var(--color-base-100); /* host token */
-  --ui-color-text: var(--color-base-content);
-  /* REQUIRED in ANY scope that overrides the palette: the neutral base + the divider it derives
-   * do NOT re-resolve across scopes (freeze rule), so restate them here — otherwise neutral
-   * borders/surfaces freeze to `:root`'s colour (wrong hue, or invisible on a dark brand). */
-  --ui-color-neutral: var(--ui-color-text);
-  --ui-border-color: color-mix(in srgb, var(--ui-color-neutral) var(--ui-tint-divider), transparent);
-  /* only list what differs — the rest inherit; NEVER self-reference (see the trap) */
-  --ui-height-sm: 1.75rem;
-  --ui-height: 2.25rem;
-  --ui-height-lg: 2.75rem; /* match host control heights */
-}
-```
-
-> **Upgrading an existing theme to ≥ 0.17:** `--ui-color-neutral` is new (it's what all *neutral*
-> borders/surfaces derive from). A pre-0.17 custom theme scope defines the palette but not this token,
-> so after upgrading, neutral borders (Card/Input frames, Menu, DataTable/SideBarMenu edges…) render
-> with the wrong colour or vanish. **Add `--ui-color-neutral` (and re-derive `--ui-border-color`) to
-> every scope where you override `--ui-color-*`.**
-
-Apply globally at `:root` (svelte-ui _is_ the design system) or scoped on a wrapper subtree
-(svelte-ui opted into per route/component while the rest of the app uses the host system).
-
-## Extending upstream instead of forking
-
-If a component hard-codes something you need to theme, **lift it into a shared `--ui-*` token
-in `theme.css`** with the current literal as the default (zero visual diff), then reference the
-token from the component via arbitrary-value syntax (`[background-color:var(--ui-color-surface)]`).
-Do **not** add a new component-scoped namespace — the `--dt-*`-style per-component tokens were
-removed in favour of the shared surface language (`--ui-color-hover/surface/active`, `--ui-accent`).
-Verify light + dark before/after.
-
-## Consumer note (Shearwood Creek)
-
-SC consumes these `--ui-*` tokens **directly** — there is no `--color-*`/`--border-*` alias
-layer (it was removed). Per-tenant branding overrides `--ui-color-primary`/`--ui-color-secondary`
-at `html.theme-light,html.theme-dark` (see SC `$lib/branding.ts`); neutrals and semantic colours
-stay theme-controlled. **≥ 0.17:** those branding scopes must also set
-`--ui-color-neutral: var(--ui-color-text);` (and re-derive `--ui-border-color`) — the freeze rule
-means the scope's `--ui-color-text` override won't otherwise reach the neutral borders, so they'd
-freeze to `:root` (wrong hue / invisible on a dark tenant).
-
-## Authoring checklist
-
-1. Scope: global (`:root`) or wrapped (`.theme-myname` / an inverse-surface container).
-2. Palette: only list `--ui-color-*` that differ; inherit the rest (no self-reference).
-3. Density: override `--ui-height*` only if controls must differ; most themes inherit.
-4. Accent/variant: to tint a surface, set `--ui-accent` **and** add `.ui-accent`.
-5. Light + dark: test both (`prefers-color-scheme`) if you don't pin values.
-6. Hit a hard-code? Extend `theme.css` + the component with a shared token first.
-
-## Reference
-
-- Source of truth — [`src/lib/theme.css`](../../src/lib/theme.css)
-- Variant → colour map — [`src/lib/types/variants.ts`](../../src/lib/types/variants.ts)
-- Public token docs — [`docs/themes.md`](../../docs/themes.md)