@spaethtech/svelte-ui 0.3.1-dev.5.6aa9d2d → 0.3.1-dev.7.3dc4fbb

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

@@ -0,0 +1,116 @@
+---
+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 — **`@spaethtech/svelte-ui`** — never a deep `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 */
+```
+
+## 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)} />
+```
+
+## 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" }}`.
+
+## 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` `ButtonDropdown` `Input` `Select` `List` `TextArea` `Checkbox` `Toggle` `Rating`
+- **Specialized inputs:** `PasswordInput` `EmailInput` `SearchInput` `NumberInput`
+- **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`
+- **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**
+  (query-language parser/AST, `createGrid`, `DataGrid<T>`, `DataSet`).
+- **Overlays:** `Dialog` `Popup` `Menu` · `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
+- **Navigation:** `TabStrip` `SideBarMenu`
+- **Feedback:** `Alert` `Banner` `Badge` `Toaster` + `toast`
+- **Layout:** `Card` `CardHeader` `CardBody` `CardFooter`
+- **Display / theme:** `NotesEditor` `ThemeSelector`
+- **Types / utils:** `Variant` `Size` `TabDefinition` (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

@@ -0,0 +1,303 @@
+---
+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-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-text`). Canonical order:
+`neutral · primary · secondary · success · info · warning · danger · ghost`.
+
+- `ghost` — borderless, transparent, hover-tint only (the minimal control).
+- `neutral` — the _uncoloured_ variant (mixes from `--ui-color-text`): **solid** in solid contexts
+  (Button/Toggle/Banner → black-on-white / white-on-black), a **tint** in soft contexts (Badge/Alert).
+- (`plain` was removed — it's now `ghost`. Old bordered-`ghost` → `neutral`.)
+
+### 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-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` one is text@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**.
+`--ui-border-color-strong`/`-strong-hover` have been **REMOVED** (migrate any consumer use to
+`color-mix(in srgb, var(--ui-color-secondary) 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)
+                                (--ui-border-color-strong/-strong-hover were REMOVED — use the
+                                 `--ui-tint-border` / `--ui-tint-border-hover` scheme instead)
+```
+
+### 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;
+}
+```
+
+### 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 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 is why scoped
+   themes and the switcher-on-`<html>` rule work, and why a switcher on `<body>` breaks them.
+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);
+  /* 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 */
+}
+```
+
+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.
+
+## 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)

package/CLAUDE.md

@@ -0,0 +1,248 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the svelte-ui component library.
+
+## Before every commit (REQUIRED)
+
+This library is consumed by multiple external projects (each with its own Claude Code agent) that
+adopt changes by reading our docs — **not** by reverse-engineering our git log. So a change is not
+"done" until its documentation is too. Before you commit, ensure ALL of these are current:
+
+- **`CHANGELOG.md`** — add/extend the entry. Any **breaking** change (renamed/removed token, changed
+  variant look, removed prop) MUST get a `### Migration` block with a **runnable codemod** (grep +
+  sed/perl) and a verify step, and bumps the MINOR version (pre-1.0). Silent visual breaks especially
+  — note them explicitly (they aren't `svelte-check` errors).
+- **Skills** (`.claude/skills/**`, esp. `themes`) — the source of truth for the token/variant/theming
+  model. Keep token names, the variant taxonomy, and examples in sync.
+- **Docs** (`docs/*.md`) and any **component spec** — keep API tables, code examples, and CSS-variable
+  references matching the code.
+
+If a commit changes the token surface, a variant, a prop, or a component's behaviour, the matching
+doc/skill/CHANGELOG edit goes in the SAME commit (or the commit isn't ready).
+
+## Project Overview
+
+**svelte-ui** is a reusable Svelte 5 (runes) component library styled with Tailwind CSS v4 and MDI
+icons (via `unplugin-icons`). All components are theme-aware using CSS variables, and most consume
+the shared `variant` (color/style) and `size` (sm/md/lg) axes.
+
+## Quick Reference
+
+### Interactive Commands
+
+- `/specify <name>` - Create component specification interactively
+- `/implement <name>` - Implement component from specification
+- `/validate <name>` - Validate implementation against specification
+
+### Documentation
+
+- `docs/components.md` - Complete component list and details
+- `docs/usage.md` - Code examples for all components
+- `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.
+
+### Tech Stack
+
+- Svelte 5 with runes (`$state`, `$props`, `$bindable`)
+- TypeScript with strict typing
+- Tailwind CSS v4 (peer dependency)
+- MDI icons via `unplugin-icons` + `@iconify-json/mdi` (peer deps) — rendered into snippets (`~icons/mdi/*`)
+
+### Project Structure
+
+```
+src/lib/components/
+├── ComponentName/           # Colocated components
+│   ├── ComponentName.svelte
+│   ├── ComponentName.spec.md
+│   ├── ComponentName.test.ts
+│   └── index.ts
+└── SimpleComponent.svelte  # Non-colocated components
+```
+
+## Development Workflow
+
+### Spec-Driven Development
+
+1. **Write spec first**: Use `/specify` or create `.spec.md`
+2. **Implement**: Use `/implement` or code to match spec
+3. **Validate**: Use `/validate` to ensure compliance
+
+### Key Principles
+
+- **Always check existing patterns** before implementing
+- **Use colocated structure** for new components
+- **Follow TypeScript discriminated unions** for variant props
+- **Ensure theme compatibility** with CSS variables
+- **Test edge cases** defined in specifications
+
+### Building & Testing
+
+```bash
+npm run dev       # Development server
+npm run package   # Build library (the publishable artifact)
+npm run check     # TypeScript validation
+npm run test      # Run Playwright tests
+```
+
+### Publish Workflow (changes to `src/lib/**`)
+
+The lib is published to npm as **`@spaethtech/svelte-ui`**; downstream apps consume
+it from the registry and adopt changes with `npm update`. The `dist/` artifact
+consumers resolve against is built by **CI at publish time** (the `prepack` script) and
+is NOT tracked by git — **never commit `dist/`**. You do not hand-build/hand-publish;
+pushing the right git ref does it. Full detail (OIDC auth, provenance-off rationale, the
+dev channel) lives in the README "Releasing" section and `.github/workflows/publish.yml`.
+
+Two ways a `src/lib` change reaches consumers:
+
+1. **Release → `latest`** (deliberate, versioned):
+   1. Edit `src/lib/**`; `npm run check`.
+   2. Roll `CHANGELOG.md` `[Unreleased]` into the new version heading (pre-1.0:
+      breaking changes bump the **MINOR** — see the top-of-file commit rules).
+   3. `npm version <patch|minor|major>` — bumps `package.json` + lockfile and creates
+      the `vX.Y.Z` git tag.
+   4. `git push && git push --tags` — the **tag** triggers CI, which type-checks, builds
+      `dist/`, and `npm publish`es under `latest`. (Versions are **immutable** — don't
+      tag until the CHANGELOG/version are right.)
+   5. Consumers get it via `npm update` (within their caret range), or by bumping the
+      range for a new minor.
+
+2. **Dev / canary → `dev`** (automatic): **every push to `main`** publishes a prerelease
+   under the `dev` dist-tag (`<next-patch>-dev.<run>.<sha>`). Consumers opt in with
+   `npm install @spaethtech/svelte-ui@dev` to try unreleased work. `latest` and caret
+   ranges (`^0.3.0`) are untouched, so this never leaks into a normal install.
+
+**Local verification / co-development.** To exercise a change in a consumer *before* it's
+on `latest`: after pushing to `main`, install the freshly-published `@dev` build there; or
+link a local checkout with a `file:` dep (`"@spaethtech/svelte-ui": "file:../svelte-ui"`)
+and run `npm run package` here to rebuild the `dist/` the consumer resolves against
+(`npm run dev:linked` does package-watch + the demo). When you can't run the consumer,
+**say so** — `npm run check` here is not a substitute for running the actual code.
+
+`npm run build` also runs `vite build` for the demo site (heavier) — use `npm run package`
+for just the library artifact.
+
+### Live UI Testing
+
+**IMPORTANT**: Drive the running demo site when working on UI components — verify behavior in a real
+browser, don't rely on `svelte-check` alone.
+
+Development server runs at `http://localhost:5173/` (`npm run dev`).
+
+Use the **`/playwright-cli`** workflow for browser-driven testing (navigation, snapshots/screenshots,
+console inspection, interaction). Point it at the dev server URL and the relevant component demo
+route (e.g. `/tabstrip`). The old Chrome DevTools MCP (`.mcp.json` + `chrome-devtools-mcp`) has been
+removed in favor of this.
+
+### Demo pages (`src/routes/<component>/`)
+
+The **`demo` skill** (`.claude/skills/demo/`) is the source of truth for building/maintaining a
+component's demo route: section structure, the readonly monospace `<TextArea>` code-sample
+convention, the rule that **code samples are complete & runnable** (include the data array + bound
+state + `'svelte-ui'` import, not just the `<Component/>` tag), and using library components (not raw
+`<input>`/`<textarea>`) for demo controls. Read it before editing a route page. (`docs/*` is
+consumer-facing; the working convention lives in the skill.)
+
+## Composition Standard (ABSOLUTE)
+
+Compound components are built **exclusively** from our own core/compound components — **never** raw
+`<button>` / `<select>` / `<input>` / `<textarea>`. e.g. DataTable's icon controls + pagination use
+`<Button variant="plain" size="sm">`, per-page uses `<Select size="sm">`; Query is built on `<Input>`
+with its clear/help actions as `<Button>`. A raw interactive element inside a compound component is a bug.
+
+Two shared **cross-cutting axes** every sizeable/themeable component consumes (mirror each other):
+
+- **`variant`** (`types/variants.ts`) — color/style: `primary` `secondary` `danger` `info` `success`
+  `warning` `ghost` `plain`. `plain` = borderless/transparent, for dense icon controls.
+- **`size`** (`types/sizes.ts`) — `sm` (24px) · `md` (32px, **default**) · `lg` (40px), tied to
+  `--ui-height-sm` / `--ui-height` / `--ui-height-lg` (`--ui-height-touch` 44px is a separate token
+  for explicit touch targets, not `lg`). Each component maps `size` to its height/text/padding/icon,
+  the same way it maps `variant` to colors.
+
+## Component Guidelines
+
+### Accessibility
+
+- All interactive components need keyboard support
+- Use proper ARIA attributes
+- Focus states with `:focus-visible`
+- Support screen readers
+
+### Styling
+
+- Use Tailwind utility classes
+- **Theme colors via `var(--ui-color-*)`** — every token is `--ui-*`-prefixed; there are NO
+  unprefixed `--color-*` and NO per-component (`--dt-*`) tokens (both removed). Interactive
+  surfaces (hover/section/pressed) use the shared `--ui-color-hover|surface|active` tints, which
+  mix from `--ui-accent`. Full model + rules: the **`themes` skill** (`.claude/skills/themes/`).
+- Consistent heights: `--ui-height` (32px); `--ui-height-sm|lg|touch` for the other tiers
+- Padding/gap is per-component (a `Record<Size,string>` class map), **not** a token
+
+### Performance
+
+- Minimal DOM nodes
+- Efficient re-renders with Svelte 5 runes
+- Lazy loading for heavy components
+- Proper cleanup in `$effect` returns
+
+## Common Patterns
+
+### Icon Usage
+
+```svelte
+import IconHome from '~icons/mdi/home';
+<!-- Render into a component's `icon` snippet — the lib sizes + colors it. -->
+<Button title="Home">{#snippet icon()}<IconHome />{/snippet}</Button>
+```
+
+### Theme-Aware Colors
+
+```svelte
+class="text-[var(--ui-color-text)] bg-[var(--ui-color-background)]"
+```
+
+For hover/section/pressed surfaces use the shared tints, not ad-hoc `color-mix`:
+
+```svelte
+class="[background-color:var(--ui-color-surface)] hover:[background-color:var(--ui-color-hover)]"
+```
+
+### Component Props Interface
+
+```typescript
+import type { Variant } from "../types/variants.js"; // shared color/style axis
+import type { Size } from "../types/sizes.js"; // shared sm/md/lg axis
+interface Props {
+  value?: string;
+  variant?: Variant;
+  size?: Size;
+  children?: Snippet;
+}
+let { value = "", variant = "secondary", size = "md", children }: Props = $props();
+```
+
+## Known Issues (do not "fix" in code)
+
+- **White / outline-less `text`/`grab`/`grabbing`/`crosshair` cursor on Windows** is a Chromium +
+  Windows **Multiplane Overlay (MPO)** GPU bug (common on AMD), NOT a svelte-ui bug. It's
+  independent of `color-scheme`, hydration, and CSS, and reproduces across unrelated sites. Do
+  **not** attempt a component-code workaround (a custom `cursor:` harms every healthy user and
+  can't be feature-detected). Client fix: DWM `OverlayTestMode=5` + reboot. Full write-up and
+  links in README "Known issues" (crbug 40239916 / 339818333).
+
+## Important Notes
+
+- **Peer dependencies only** - no runtime dependencies
+- **Test files excluded** from npm package automatically
+- **Documentation in docs/** - Component reference, examples, theme variables
+- **Interactive commands** - Use `/specify`, `/implement`, `/validate` for workflow
+
+For detailed information, see the documentation files in the `docs/` folder.