@spaethtech/svelte-ui 0.3.1-dev.6.5d93a69 → 0.3.1-dev.7.3dc4fbb

package/docs/paradigm.md

@@ -0,0 +1,240 @@
+# Development Paradigm
+
+This project uses **specification-driven development** (a form of behavior-driven development) where specifications are written before implementation. This paradigm ensures clear requirements, consistent implementation, and better testing.
+
+## Workflow Overview
+
+```mermaid
+graph LR
+    A[Write Spec] --> B[Review & Approve]
+    B --> C[Implement Component]
+    C --> D[Validate Against Spec]
+    D --> E[Write Tests]
+```
+
+## Interactive Commands
+
+### `/specify <component-name>`
+
+Creates a new component specification interactively.
+
+- Prompts for purpose, API, behavior, etc.
+- Generates `.spec.md` file
+- Sets up component folder structure
+
+### `/implement <component-name>`
+
+Implements a component from its specification.
+
+- Reads existing `.spec.md` file
+- Creates Svelte component following spec
+- Optionally creates tests and demo page
+
+### `/validate <component-name>`
+
+Validates implementation against specification.
+
+- Compares implementation with spec
+- Checks acceptance criteria
+- Reports discrepancies
+- Can auto-fix issues
+
+## Manual Workflow
+
+### 1. Write Specification
+
+Create `src/lib/components/ComponentName/ComponentName.spec.md`:
+
+```markdown
+# Component Specification: ComponentName
+
+## Overview
+
+- **Purpose**: What the component does
+- **User Story**: As a [user], I want to [action] so that [benefit]
+
+## API Contract
+
+### Props
+
+- `propName` (type, required/optional): Description
+- Default values and constraints
+
+### Events
+
+- `eventName`: When triggered, payload structure
+
+### Slots
+
+- Slot name and purpose
+
+## Behavior Specifications
+
+### Visual States
+
+- Default appearance
+- Interactive states (hover, focus, active)
+- Variant appearances
+
+### User Interactions
+
+- Click behavior
+- Keyboard navigation
+- Touch interactions
+
+### Accessibility Requirements
+
+- ARIA attributes
+- Keyboard support
+- Screen reader behavior
+
+## Performance Constraints
+
+- Bundle size limits
+- Rendering performance
+- Memory usage
+
+## Edge Cases
+
+- Empty states
+- Error states
+- Boundary conditions
+
+## Acceptance Criteria
+
+- [ ] Specific, testable requirements
+- [ ] Each item should be verifiable
+- [ ] Clear pass/fail conditions
+```
+
+### 2. Implement Component
+
+Create `src/lib/components/ComponentName/ComponentName.svelte`:
+
+```svelte
+<script lang="ts">
+  // Follow the specification exactly
+  interface Props {
+    // Props as defined in spec
+  }
+
+  let {} /* props */ : Props = $props();
+</script>
+
+<!-- Implementation matching spec -->
+```
+
+### 3. Create Tests
+
+Tests use **Playwright** (the project's test runner — `npm run test`). Create
+`src/lib/components/ComponentName/ComponentName.test.ts`:
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test.describe("ComponentName - Spec Validation", () => {
+  // Test each acceptance criterion against the rendered demo page.
+  test("meets acceptance criterion 1", async ({ page }) => {
+    await page.goto("/component-name");
+    // assertions…
+  });
+});
+```
+
+### 4. Export Component
+
+Add to `src/lib/index.ts`:
+
+```typescript
+export { default as ComponentName } from "./components/ComponentName/ComponentName.svelte";
+```
+
+## Component Structure
+
+### Colocated Structure (Recommended)
+
+```
+src/lib/components/
+└── ComponentName/
+    ├── ComponentName.spec.md    # Write first
+    ├── ComponentName.svelte     # Implement second
+    ├── ComponentName.test.ts    # Test third
+    └── index.ts                 # Export
+```
+
+### Benefits
+
+1. **Clear Requirements**: Specs define exactly what to build
+2. **Consistent Implementation**: All components follow same pattern
+3. **Better Testing**: Tests validate against documented requirements
+4. **Living Documentation**: Specs serve as component documentation
+5. **Reduced Iterations**: Clear specs mean fewer revisions
+
+## Example: Badge Component
+
+### 1. Specification (Badge.spec.md)
+
+```markdown
+# Component Specification: Badge
+
+## Overview
+
+- **Purpose**: Display status indicators or labels
+- **User Story**: As a developer, I want to display badges with consistent styling
+
+## API Contract
+
+### Props
+
+- `text` (string, required): Display text
+- `variant` (string, optional): Visual style
+- `size` (string, optional): Size variant
+- `dismissible` (boolean, optional): Show dismiss button
+```
+
+### 2. Implementation (Badge.svelte)
+
+```svelte
+<script lang="ts">
+  interface Props {
+    text: string;
+    variant?: "default" | "primary" | "success";
+    size?: "sm" | "md" | "lg";
+    dismissible?: boolean;
+  }
+
+  let { text, variant = "default", size = "md", dismissible = false }: Props = $props();
+</script>
+
+<span class="badge badge-{variant} badge-{size}">
+  {text}
+  {#if dismissible}
+    <button onclick={() => dispatch("dismiss")}>×</button>
+  {/if}
+</span>
+```
+
+## Best Practices
+
+1. **Write specs before code** - Never implement without a spec
+2. **Include acceptance criteria** - Make requirements testable
+3. **Update specs when requirements change** - Keep documentation current
+4. **Use `/validate` after changes** - Ensure compliance
+5. **Reference specs in PRs** - Link implementation to requirements
+
+## Tips for Writing Good Specs
+
+- Be specific about behavior, not implementation
+- Include all edge cases
+- Define clear acceptance criteria
+- Consider accessibility from the start
+- Think about theme compatibility
+- Document performance requirements
+
+## Common Pitfalls to Avoid
+
+- Don't skip the spec phase
+- Don't implement features not in the spec
+- Don't modify specs after implementation (unless updating both)
+- Don't write vague acceptance criteria
+- Don't forget accessibility requirements

package/docs/themes.md

@@ -0,0 +1,170 @@
+# CSS Variables Reference
+
+This document describes the CSS variables in the svelte-ui theme. The source of truth is
+`src/lib/theme.css` (shipped as `@spaethtech/svelte-ui/theme.css`); this doc mirrors it. Every token is
+**`--ui-*`-prefixed** — there are no unprefixed tokens and no per-component tokens.
+
+## Overview
+
+The library themes via CSS custom properties. There are **two themes only — light (default) and
+dark**. Dark follows the system preference automatically (`@media (prefers-color-scheme: dark)`);
+force either with the `.theme-light` / `.theme-dark` classes (see `ThemeSelector`).
+
+Consumers import the theme right after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "@spaethtech/svelte-ui/theme.css";
+```
+
+## Palette — `--ui-color-*`
+
+### Core
+
+- `--ui-color-background` — main background for pages and containers
+- `--ui-color-text` — primary text color
+
+### Semantic
+
+- `--ui-color-primary` — primary brand color (blue)
+- `--ui-color-secondary` — secondary brand color (cyan)
+- `--ui-color-success` — success state (green)
+- `--ui-color-warning` — warning state (amber)
+- `--ui-color-error` — error/danger state (red) — the `danger` variant maps here
+- `--ui-color-info` — informational state (sky blue)
+
+## Interactive-surface tints — `--ui-accent` + hover / surface / active
+
+One shared tint language for every hover, section band, and pressed surface. Three steps of the
+**same** mix, from lightest to strongest:
+
+- `--ui-color-hover` — **4%** — row / option / ghost-button hover
+- `--ui-color-surface` — **8%** — header / footer / section bands (a notch darker than hover)
+- `--ui-color-active` — **12%** — pressed / held
+
+Each is `color-mix(in srgb, var(--ui-accent) N%, transparent)`. The **percentages are
+theme-independent** (identical in light and dark) — only the accent color flips.
+
+- `--ui-accent` — the color the tints mix from. **Defaults to `var(--ui-color-text)`**, so out of
+  the box these are neutral grey tints. Point it at a semantic color to tint a surface (this is how
+  a component `variant` colors its whole surface). Overriding `--ui-accent` requires the `.ui-accent`
+  re-mix class — see [Applying a theme](#theme-application) and the themes skill.
+
+## Border & radius — `--ui-border-*`
+
+- `--ui-border-radius` — `0.375rem` — corner radius for every surface (Card, Input, DataTable…)
+- `--ui-border-color` — `color-mix(in srgb, var(--ui-color-secondary) 30%, transparent)` — soft
+  internal divider (row separators, section splits)
+- `--ui-border-color-strong` — `var(--ui-color-secondary)` — prominent outer edge (Card frame,
+  Input, DataTable outer)
+- `--ui-border-color-strong-hover` — `color-mix(in srgb, var(--ui-color-secondary) 80%, black)` —
+  darker edge on hover for interactive controls
+
+## Sizing — the `size` axis (`sm` / `md` / `lg`)
+
+### Control heights
+
+- `--ui-height-sm` — `1.5rem` / 24px (`sm`)
+- `--ui-height` — `2rem` / 32px (`md`, **default**)
+- `--ui-height-lg` — `2.5rem` / 40px (`lg`)
+- `--ui-height-touch` — `2.75rem` / 44px — explicit touch target (WCAG/Apple min), **not** the `lg` size
+
+### Text
+
+- `--ui-text-sm` — `0.75rem` / 12px · `--ui-text` — `0.875rem` / 14px (default) · `--ui-text-lg` — `1rem` / 16px
+
+### Inline icons
+
+- `--ui-icon-sm` — `0.875rem` / 14px · `--ui-icon` — `1rem` / 16px (default) · `--ui-icon-lg` — `1.25rem` / 20px
+
+> Per-component **padding / gap** is NOT a token — each component maps the `size` prop to Tailwind
+> class maps (`Record<Size, string>`) internally. (The old `--ui-padding*` and `--ui-border` width
+> tokens were removed.)
+
+## Breakpoints (in `@theme`)
+
+Narrow-mobile tiers and an ultrawide tier on top of Tailwind's defaults, so `DataTable` column
+placements can target the full range:
+`4xs` 320px · `3xs` 360px · `2xs` 420px · `xs` 480px · `3xl` 1920px.
+
+## Theme values
+
+### Light (default)
+
+```css
+--ui-color-background: #ffffff;
+--ui-color-text: #111827;
+--ui-color-primary: #1d4ed8;
+--ui-color-secondary: #0891b2;
+--ui-color-success: #059669;
+--ui-color-warning: #d97706;
+--ui-color-error: #dc2626;
+--ui-color-info: #0ea5e9;
+```
+
+### Dark
+
+```css
+--ui-color-background: #111827;
+--ui-color-text: #f9fafb;
+--ui-color-primary: #2563eb;
+--ui-color-secondary: #06b6d4;
+--ui-color-success: #10b981;
+--ui-color-warning: #f59e0b;
+--ui-color-error: #ef4444;
+--ui-color-info: #06b6d4;
+```
+
+The sizing/text/icon tokens are theme-independent. The interactive tints use the same percentages
+in both themes — only `--ui-color-text` (hence `--ui-accent`) flips.
+
+## Usage in components
+
+Components reference these via Tailwind's arbitrary-value syntax:
+
+```svelte
+<!-- Text / background -->
+<div class="text-[var(--ui-color-text)] bg-[var(--ui-color-background)]">...</div>
+
+<!-- Border (color + radius tokens) -->
+<div
+  class="border [border-color:var(--ui-border-color-strong)] [border-radius:var(--ui-border-radius)]"
+>
+  ...
+</div>
+
+<!-- Hover / section / pressed surfaces — use the shared tints, not ad-hoc color-mix -->
+<div
+  class="[background-color:var(--ui-color-surface)] hover:[background-color:var(--ui-color-hover)]"
+>
+  ...
+</div>
+```
+
+For muted text or faint dividers, mix the text color: `color-mix(in srgb, var(--ui-color-text) 60%, transparent)`.
+
+## Theme application
+
+Precedence:
+
+1. Forced theme via `.theme-light` / `.theme-dark` — set on **`<html>`** by `ThemeSelector` and by
+   the pre-hydration script in `app.html`. A switcher **must** target `<html>` (documentElement),
+   never `<body>` — putting it on `<body>` leaves `<html>` on the system path and freezes the
+   accent-derived tints to the wrong theme.
+2. System preference via `@media (prefers-color-scheme: dark)`.
+3. Default light values.
+
+`ThemeSelector` manages switching (Auto / Light / Dark) and persists the choice in `localStorage`
+under `svelte-ui-theme`.
+
+**Scoped / inverse surfaces:** because the theme classes are ordinary CSS, apply one to any
+container to re-theme just that subtree — e.g. `class="theme-dark"` on a dark header sitting on a
+light page, so the components inside resolve light-on-dark and stay visible. This works because the
+tint tokens are re-defined per theme scope; see the themes skill.
+
+## Building a custom theme
+
+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).