@mhmo91/schmancy 0.9.3 → 0.9.5

package/skills/schmancy/area.md

@@ -0,0 +1,141 @@
+# Area — Routing
+
+Schmancy's client-side router. Three pieces:
+
+| Piece | Role |
+|-------|------|
+| `<schmancy-area name="...">` | Named region that renders one route at a time |
+| `<schmancy-route when="tag">` | Declares which component can render in an area |
+| `area.push(...)` | Imperative navigation |
+
+Areas can be nested to compose shell-plus-sub-view layouts.
+
+## Example
+
+```html
+<schmancy-area name="root" .default=${lazy(() => import('./pages/home.page'))}>
+  <schmancy-route when="home-page"
+    .component=${lazy(() => import('./pages/home.page'))}></schmancy-route>
+
+  <schmancy-route when="app-index"
+    .component=${lazy(() => import('./app/app.page'))}
+    .guard=${authState$.pipe(
+      map(u => !!u && !u.isAnonymous),
+      takeUntil(this.disconnecting),
+    )}
+    @redirect=${() => area.push({
+      component: 'home-page',
+      area: 'root',
+      historyStrategy: 'replace',
+    })}></schmancy-route>
+</schmancy-area>
+```
+
+## `schmancy-area` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string (required) | Area identifier used in `area.push({ area })` |
+| `default` | `RouteComponent \| string` | Fallback when no route matches |
+
+## `schmancy-route` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `when` | string (required) | Must match a `@customElement('tag')` tag name |
+| `component` | `RouteComponent` (required) | Class, tag name, or `lazy()` wrapper |
+| `guard` | `Observable<boolean>` | When emits `false`, blocks and dispatches `redirect` event |
+| `exact` | boolean | Strict-equality matching |
+
+## `area` service
+
+```typescript
+import { area } from '@mhmo91/schmancy'
+
+area.push({
+  area: 'root',
+  component: 'app-index',
+  params?: { id: '123' },
+  historyStrategy?: 'push' | 'replace' | 'silent',
+})
+```
+
+`historyStrategy`:
+- `'push'` (default) — adds a browser-history entry
+- `'replace'` — overwrites the current entry (use after guards or redirects)
+- `'silent'` — changes the area without touching history
+
+### Subscribe to route state
+
+```typescript
+area.on('root').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(route => { /* route.component, route.params */ })
+
+area.params<{ id: string }>('detail').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(params => this.loadItem(params.id))
+```
+
+## Lazy loading
+
+```typescript
+import { lazy } from '@mhmo91/schmancy'
+const HomePage = lazy(() => import('./home.page'))
+
+// Optional preload
+html`<button @mouseenter=${() => HomePage.preload()}>Home</button>`
+```
+
+## Guards
+
+`guard` is an Observable<boolean>.
+
+- Emits `true` → route renders.
+- Emits `false` → route dispatches a `redirect` event. Handle it with `area.push(...)`.
+
+Auth guard:
+
+```typescript
+<schmancy-route when="app-index"
+  .component=${lazy(() => import('./app'))}
+  .guard=${authState$.pipe(
+    map(u => !!u),
+    takeUntil(this.disconnecting),
+  )}
+  @redirect=${() => area.push({
+    component: 'home-page', area: 'root', historyStrategy: 'replace',
+  })}></schmancy-route>
+```
+
+Compound guard (multiple streams):
+
+```typescript
+.guard=${combineLatest([permissions$, orgContext.$]).pipe(
+  takeUntil(this.disconnecting),
+  map(([perms, org]) => perms.includes('billing.view') && org?.billing?.configured),
+)}
+```
+
+## Nested areas
+
+Areas nest by rendering an inner `<schmancy-area>` inside a route component. A common shape is an outer area for "signed-in vs. not" and an inner area for sub-views of the signed-in shell.
+
+```html
+<!-- outer -->
+<schmancy-area name="root">
+  <schmancy-route when="app-index" .component=${AppShell}></schmancy-route>
+</schmancy-area>
+
+<!-- inner (inside AppShell.render()) -->
+<schmancy-area name="app" default="home-page">
+  <schmancy-route when="home-page" .component=${...}></schmancy-route>
+  <schmancy-route when="settings-page" .component=${...}></schmancy-route>
+</schmancy-area>
+```
+
+## Rules
+
+- `when="tag-name"` must match `@customElement('tag-name')` exactly.
+- Guards emit `false` → always use `historyStrategy: 'replace'` in the `@redirect` handler.
+- Every subscription in guards / route state uses `takeUntil(this.disconnecting)`.

package/skills/schmancy/audio.md

@@ -0,0 +1,69 @@
+# Schmancy Audio
+
+> Emotional sound service — synthesizes short, empathetic sounds via Web Audio API keyed on feelings (joyful, tense, calm, etc.). No assets. No external players. Just tones + puffs generated on demand.
+
+## Usage
+```typescript
+import { sound } from '@mhmo91/schmancy'
+
+sound.play('joyful')     // trigger a feeling sound
+sound.setVolume(0.2)     // 0..1
+sound.setMuted(true)
+sound.resetTheme()       // back to defaults
+```
+
+## Feelings
+Organized by emotional category:
+
+| Category | Feelings |
+|----------|----------|
+| Happy | `joyful`, `content`, `excited`, `grateful`, `proud`, `loved` |
+| Sad | `sad`, `disappointed`, `hurt`, `lonely`, `melancholy` |
+| Anxious | `worried`, `nervous`, `overwhelmed`, `tense` |
+| Angry | `frustrated`, `angry`, `annoyed` |
+| Tired | `tired`, `drained`, `bored` |
+| Calm | `calm`, `peaceful`, `relaxed`, `focused` |
+| Connected | `connected`, `supported`, `welcomed` |
+| Mixed | `confused`, `nostalgic`, `bittersweet` |
+
+(See `mood-audio.types.ts` for the authoritative list.)
+
+## Observable API
+```typescript
+sound.theme$.subscribe(theme => console.log(theme?.name ?? 'default'))
+sound.volume$.subscribe(v => {})
+sound.muted$.subscribe(m => {})
+```
+
+## Settings Persistence
+Volume, mute, and custom theme persist to `localStorage` under key `schmancy-sound-settings` (via `createContext`).
+
+## AI-Generated Themes
+```typescript
+import type { SoundTheme } from '@mhmo91/schmancy'
+
+const customTheme: SoundTheme = {
+  name: 'ocean',
+  sounds: {
+    joyful: { puffs: [...], tones: [...] },
+    // partial override — falls through to defaults for anything omitted
+  }
+}
+
+sound.setTheme(customTheme)
+```
+
+Each `FeelingSound` consists of:
+- **puffs** — short bursts (air/noise, e.g. `{ startTime, duration, frequency, volume }`)
+- **tones** — oscillators (`sine`/`triangle`/`square`/`sawtooth` with envelope)
+
+## Built-in Feedback Hooks
+Other Schmancy components play these automatically:
+- [`schmancy-connectivity-status`](./connectivity.md) on offline/online.
+- Some success/error paths in notifications and dialogs via the `$sounds` legacy helper.
+
+## Legacy API
+- `$sounds` — older generator exported for compatibility.
+- `EmotionalSoundGenerator` — underlying class.
+
+Prefer `sound` for new code.

package/skills/schmancy/autocomplete.md

@@ -0,0 +1,53 @@
+# schmancy-autocomplete
+
+> Searchable input with fuzzy filtering, single/multi-select, and inline chip display.
+
+## Usage
+```html
+<schmancy-autocomplete label="Assignee" placeholder="Search...">
+  <schmancy-option value="alice" label="Alice"></schmancy-option>
+  <schmancy-option value="bob" label="Bob"></schmancy-option>
+</schmancy-autocomplete>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Selected value (single) or comma-separated (multi) |
+| values | string[] | `[]` | Selected values (multi-select) |
+| label | string | `''` | Label text |
+| placeholder | string | `''` | Placeholder text |
+| name | string | `''` | Form submission name |
+| required | boolean | `false` | Whether selection is required |
+| multi | boolean | `false` | Enable multi-select with inline chips |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
+| maxHeight | string | `'300px'` | Max dropdown height |
+| debounceMs | number | `200` | Search debounce in ms |
+| similarityThreshold | number | `0.3` | Minimum fuzzy match score (0-1) |
+| error | boolean | `false` | Error state |
+| validationMessage | string | `''` | Validation message |
+| description | string | `''` | Screen reader description |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string \| string[], values?: string[] }` | When selection changes |
+
+## Examples
+```html
+<!-- Multi-select with chips -->
+<schmancy-autocomplete label="Skills" multi placeholder="Type to search...">
+  <schmancy-option value="ts" label="TypeScript"></schmancy-option>
+  <schmancy-option value="lit" label="Lit"></schmancy-option>
+  <schmancy-option value="rxjs" label="RxJS"></schmancy-option>
+</schmancy-autocomplete>
+
+<!-- Single select, auto-selects best match on blur -->
+<schmancy-autocomplete label="City" placeholder="Search city..."
+  @change=${(e) => console.log(e.detail.value)}>
+  <schmancy-option value="berlin" label="Berlin"></schmancy-option>
+  <schmancy-option value="munich" label="Munich"></schmancy-option>
+</schmancy-autocomplete>
+```
+
+Children must be `<schmancy-option>` elements. In multi mode, selected items appear as removable chips.

package/skills/schmancy/avatar.md

@@ -0,0 +1,47 @@
+# schmancy-avatar
+
+> Avatar component displaying initials, image, or icon with color themes, shapes, and status indicators.
+
+## Usage
+```html
+<schmancy-avatar initials="JD" color="primary"></schmancy-avatar>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| initials | string | `''` | Text initials (max 2 characters) |
+| src | string | `''` | Image URL |
+| icon | string | `''` | Material icon name |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'\|'xl'` | `'md'` | Avatar size (20-64px) |
+| color | `'primary'\|'secondary'\|'tertiary'\|'success'\|'error'\|'neutral'` | `'primary'` | Color theme |
+| shape | `'circle'\|'square'` | `'circle'` | Avatar shape |
+| bordered | boolean | `false` | Show border ring |
+| status | `'online'\|'offline'\|'busy'\|'away'\|'none'` | `'none'` | Status indicator dot |
+
+## Size Reference
+| Token | Size | Description |
+|-------|------|-------------|
+| xxs | 20px | Ultra-compact |
+| xs | 24px | Compact |
+| sm | 32px | Small |
+| md | 40px | Default |
+| lg | 48px | Large |
+| xl | 64px | Extra large |
+
+## Examples
+```html
+<!-- Image avatar with status -->
+<schmancy-avatar src="/photos/alice.jpg" size="lg" status="online"></schmancy-avatar>
+
+<!-- Icon avatar -->
+<schmancy-avatar icon="group" color="secondary" shape="square"></schmancy-avatar>
+
+<!-- Bordered initials -->
+<schmancy-avatar initials="AB" color="tertiary" bordered></schmancy-avatar>
+
+<!-- Default (person icon) -->
+<schmancy-avatar size="sm" color="neutral"></schmancy-avatar>
+```
+
+Priority: `src` (image) > `initials` > `icon` > default person icon.

package/skills/schmancy/badge.md

@@ -0,0 +1,41 @@
+# schmancy-badge
+
+> Versatile badge for status indicators, labels, and counts with color variants and shapes.
+
+## Usage
+```html
+<schmancy-badge color="success">Active</schmancy-badge>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| color | `'primary'\|'secondary'\|'tertiary'\|'success'\|'warning'\|'error'\|'neutral'\|'surface'` | `'primary'` | Color variant |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Badge size |
+| shape | `'rounded'\|'pill'\|'square'` | `'pill'` | Badge shape |
+| outlined | boolean | `false` | Outlined style (transparent background) |
+| icon | string | `''` | Material icon name |
+| pulse | boolean | `false` | Pulse animation for attention |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| default | Badge text content |
+| icon | Custom icon content |
+
+## Examples
+```html
+<!-- Outlined badge -->
+<schmancy-badge color="error" outlined>Overdue</schmancy-badge>
+
+<!-- With icon -->
+<schmancy-badge color="success" icon="check_circle">Verified</schmancy-badge>
+
+<!-- Pulsing notification badge -->
+<schmancy-badge color="error" size="sm" pulse>3</schmancy-badge>
+
+<!-- Square shape -->
+<schmancy-badge color="neutral" shape="square">Draft</schmancy-badge>
+```
+
+**Tag aliases:** `<sch-badge>` (backward compatible)

package/skills/schmancy/boat.md

@@ -0,0 +1,47 @@
+# schmancy-boat
+
+> Draggable floating FAB that expands into a panel. Great for persistent assistant/chat panels.
+
+> **Note:** `schmancy-window` is the evolved successor with more capabilities (resize, maximize, multi-window registry). Prefer `schmancy-window` for new code unless you want the simpler FAB-to-panel model.
+
+## Usage
+```html
+<schmancy-boat id="assistant" icon="smart_toy" label="Assistant">
+  <div slot="header">Assistant</div>
+  <div class="p-4">Panel body content</div>
+</schmancy-boat>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | `'default'` | Unique identifier (persists drag position in localStorage) |
+| `icon` | string | — | Material icon for the FAB state |
+| `label` | string | — | Label text in FAB state |
+| `open` | boolean | `false` | Panel open/closed (reflected) |
+| `corner` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Anchor corner |
+| `expandedWidth` | string | responsive | e.g. `'320px'` |
+| `lowered` | boolean | `false` | Lower shadow in FAB state |
+
+## Getter / Setter
+```typescript
+boat.state = 'expanded' | 'collapsed'   // equivalent to open = true/false
+boat.state                              // current state
+boat.expand() / boat.close()
+```
+
+## Behavior
+- Drag to reposition. Releases snap to the nearest corner.
+- Open/close uses clip-path + `SPRING_SMOOTH` for elegant reveal.
+- Position persists in `localStorage` under `schmancy-boat-{id}`.
+- Respects `prefers-reduced-motion`.
+
+## Example
+```html
+<schmancy-boat id="chat" icon="chat" label="Chat" corner="bottom-right">
+  <span slot="header">Messages</span>
+  <schmancy-list class="p-2">
+    <!-- messages -->
+  </schmancy-list>
+</schmancy-boat>
+```

package/skills/schmancy/busy.md

@@ -0,0 +1,36 @@
+# schmancy-busy
+
+> Full-overlay busy indicator with backdrop blur. Place inside a `position: relative` container.
+
+## Usage
+```html
+<div class="relative">
+  <p>Content underneath</p>
+  ${when(loading, () => html`<schmancy-busy></schmancy-busy>`)}
+</div>
+```
+
+## Properties
+No configurable properties. Renders a centered spinner overlay.
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| default | Custom loading content (defaults to `<schmancy-spinner>`) |
+
+## Examples
+```html
+<!-- Default spinner -->
+<div class="relative h-64">
+  <schmancy-busy></schmancy-busy>
+</div>
+
+<!-- Custom loading content -->
+<div class="relative">
+  <schmancy-busy>
+    <schmancy-typography type="body" token="lg">Loading data...</schmancy-typography>
+  </schmancy-busy>
+</div>
+```
+
+The component uses `position: absolute; inset: 0` with `z-index: 50` and a subtle backdrop blur.

package/skills/schmancy/button.md

@@ -0,0 +1,59 @@
+# schmancy-button / schmancy-icon-button
+
+> Buttons with embedded `magnetic` directive, glow hover shadow, and spring press animation.
+
+## Usage
+```html
+<schmancy-button variant="filled" color="primary">Save</schmancy-button>
+<schmancy-icon-button icon="add"></schmancy-icon-button>
+```
+
+## Properties (schmancy-button)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'elevated' \| 'filled' \| 'filled tonal' \| 'tonal' \| 'outlined' \| 'text'` | `'text'` | Visual style |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'neutral'` | Auto | Color. Defaults to `primary` (or `secondary` for tonal) |
+| `size` | `'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Height: 24/32/40/48/56px |
+| `width` | `'full' \| 'auto'` | `'auto'` | Full-width or auto |
+| `type` | `'button' \| 'reset' \| 'submit'` | `'button'` | HTML button type |
+| `href` | `string` | `undefined` | Renders as `<a>` when set |
+| `disabled` | `boolean` | `false` | Disabled state (38% opacity) |
+
+## Properties (schmancy-icon-button)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `icon` | `string` | `undefined` | Material icon name (preferred over slot content) |
+| `size` | `'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Icon size: 12/16/20/24/24/40px |
+| `variant` | Same as button | `'text'` | Visual style |
+| `text` | `boolean` | `false` | Render slot as text label instead of icon |
+| `disabled` | `boolean` | `false` | Disabled state |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | Button label text |
+| `prefix` | Leading content (images auto-sized) |
+| `suffix` | Trailing content (images auto-sized) |
+
+## Physics
+- **magnetic** directive embedded (strength: 3, radius: 60px for button, 50px for icon-button)
+- Hover: luminous glow shadow using primary color
+- Active: spring press `scale(0.97)` / `scale(0.92)` for icon-button
+
+## Examples
+```html
+<!-- Filled primary -->
+<schmancy-button variant="filled" color="primary">Submit</schmancy-button>
+
+<!-- Outlined error with icon prefix -->
+<schmancy-button variant="outlined" color="error" size="sm">
+  <schmancy-icon slot="prefix">delete</schmancy-icon>
+  Delete
+</schmancy-button>
+
+<!-- Icon button with explicit icon prop -->
+<schmancy-icon-button icon="settings" variant="tonal" size="sm"></schmancy-icon-button>
+
+<!-- Full-width submit -->
+<schmancy-button variant="filled" width="full" type="submit">Save Changes</schmancy-button>
+```

package/skills/schmancy/card.md

@@ -0,0 +1,53 @@
+# schmancy-card
+
+> Card container with luminous hover glow and spring press animation. Interactive cards get embedded `cursorGlow` directive.
+
+## Usage
+```html
+<schmancy-card type="elevated" interactive>
+  <div class="p-4">Card content</div>
+</schmancy-card>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'elevated' \| 'filled' \| 'outlined'` | `'elevated'` | Visual style |
+| `interactive` | `boolean` | `false` | Enables click, cursorGlow, keyboard nav, ripple |
+| `disabled` | `boolean` | `false` | Disables interaction |
+| `dragged` | `boolean` | `false` | Elevated drag state with extra glow |
+| `href` | `string` | `undefined` | URL navigation on click |
+| `target` | `string` | `undefined` | Link target (e.g. `_blank`) |
+| `role` | `string` | `'article'` | ARIA role (auto-switches to `button`/`link` when interactive) |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `schmancy-click` | `{ value: type }` | Fired on interactive card click |
+
+## Physics
+- **cursorGlow** directive on interactive cards (radius: 200, intensity: 0.1)
+- Hover: luminous glow + lift (`translateY(-2px)` for elevated, `-1px` for others)
+- Active: spring compress `scale(0.98)` with 100ms transition
+- Dragged: enhanced glow + `translateY(-4px)`
+
+## Examples
+```html
+<!-- Elevated clickable card -->
+<schmancy-card type="elevated" interactive>
+  <div class="p-4">
+    <h3 class="text-surface-on font-medium">Title</h3>
+    <p class="text-surface-on-variant">Description</p>
+  </div>
+</schmancy-card>
+
+<!-- Outlined static card -->
+<schmancy-card type="outlined">
+  <div class="p-4">Static content</div>
+</schmancy-card>
+
+<!-- Link card -->
+<schmancy-card type="filled" interactive href="/details" target="_blank">
+  <div class="p-4">Opens in new tab</div>
+</schmancy-card>
+```

package/skills/schmancy/charts.md

@@ -0,0 +1,93 @@
+# Schmancy Charts
+
+> Canvas-rendered area chart and horizontal pill chart. Theme-aware, lazy-animated, with auto peak highlighting.
+
+## schmancy-area-chart
+
+> Smooth Catmull-Rom spline area chart with peak markers and hover tooltips.
+
+```html
+<schmancy-area-chart
+  .data=${[
+    { label: '9 AM', value: 12.4 },
+    { label: '10 AM', value: 18.9 },
+    { label: '11 AM', value: 42.1, metadata: { users: 320 } },
+    { label: '12 PM', value: 56.7 },
+  ]}
+  value-prefix="EUR "
+  value-decimals="2"
+  peak-count="2"
+  height="240"
+></schmancy-area-chart>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `ChartDataPoint[]` | `[]` | `{ label, value, metadata? }[]` |
+| `height` | number | `200` | Chart height in px |
+| `showGrid` | boolean | `true` | Background grid lines |
+| `showLabels` | boolean | `true` | X-axis labels |
+| `showTooltip` | boolean | `true` | Hover tooltip |
+| `peakCount` | number | `3` | Top-N points highlighted larger |
+| `animationDuration` | number | `800` | Entrance animation ms |
+| `animated` | boolean | `true` | Animate on first visible |
+| `valuePrefix` | string | `''` | Display prefix (e.g. `"EUR "`) |
+| `valueSuffix` | string | `''` | Display suffix (e.g. `"%"`) |
+| `valueDecimals` | number | `2` | Decimal places |
+| `theme` | `Partial<ChartTheme>` | `{}` | Override colors, stroke, radii |
+
+### ChartTheme
+| Key | Default | Description |
+|-----|---------|-------------|
+| `primaryColor` | `--schmancy-sys-color-primary` | Line + fill gradient color |
+| `gradientOpacity` | `[0.4, 0.05]` | Top/bottom fill opacity |
+| `strokeWidth` | `2` | Line thickness |
+| `pointRadius` | `4` | Normal point radius |
+| `peakRadius` | `6` | Peak point radius |
+
+## schmancy-pills
+
+> Horizontal bar chart with optional stacked segments, medal ranks, and peak/low styling.
+
+```html
+<schmancy-pills
+  .data=${[
+    { label: 'Mon', value: 1240, rank: 1 },
+    { label: 'Tue', value: 980 },
+    { label: 'Wed', value: 1830, rank: 2, segments: [
+      { label: 'Pizza', value: 1200 },
+      { label: 'Drinks', value: 630 }
+    ]},
+  ]}
+></schmancy-pills>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `PillDataPoint[]` | `[]` | Rows with optional stacked `segments` |
+| `valuePrefix` / `valueSuffix` / `valueDecimals` | — | — | Value formatting (same as area chart) |
+| `showMedals` | boolean | `true` | Show 🥇🥈🥉 for rank 1/2/3 |
+
+### PillDataPoint
+```typescript
+{
+  label: string
+  value: number
+  segments?: { label, value, color }[]  // stacked
+  isPeak?: boolean   // highlighted
+  isLow?: boolean    // muted
+  rank?: 1 | 2 | 3   // medal
+  metadata?: Record<string, unknown>
+}
+```
+
+## Behavior
+- Both charts use an IntersectionObserver to defer animation until visible.
+- Responsive — resize triggers a re-render.
+- Dark/light aware via theme CSS variables.
+
+## When to Use
+- Area chart: time-series or comparative trends.
+- Pills: ranked categorical data (leaderboards, top days, distribution).

package/skills/schmancy/checkbox.md

@@ -0,0 +1,36 @@
+# schmancy-checkbox
+
+> Checkbox with label support and form association.
+
+## Usage
+```html
+<schmancy-checkbox label="I agree to terms" @change=${(e) => handle(e.detail.value)}>
+</schmancy-checkbox>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | boolean | `false` | Whether the checkbox is checked |
+| checked | boolean | `false` | Alias for value |
+| label | string | `undefined` | Label text (alternative to slot) |
+| name | string | auto | Form submission name |
+| disabled | boolean | `false` | Whether the checkbox is disabled |
+| required | boolean | `false` | Whether the checkbox is required |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Checkbox size |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: boolean }` | When checked state changes |
+
+## Examples
+```html
+<!-- With label property -->
+<schmancy-checkbox label="Enable notifications" .value=${true}></schmancy-checkbox>
+
+<!-- With slotted label -->
+<schmancy-checkbox name="terms" required>
+  Accept <a href="/terms">terms and conditions</a>
+</schmancy-checkbox>
+```