@mhmo91/schmancy 0.9.4 → 0.9.5

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "schmancy",
+  "description": "Claude Code support for the @mhmo91/schmancy web-component UI library. Provides foundations (routing, store, base class, theme, directives), component API lookup for 60+ tags, and overlay service patterns ($dialog, $notify, schmancyContentDrawer).",
+  "version": "0.1.0",
+  "author": {
+    "name": "samwaai",
+    "url": "https://github.com/samwaai"
+  },
+  "homepage": "https://github.com/samwaai/schmancy",
+  "repository": "https://github.com/samwaai/schmancy",
+  "license": "Apache-2.0",
+  "keywords": ["lit", "web-components", "ui", "schmancy", "tailwind", "rxjs"]
+}

package/README.md

@@ -13,6 +13,16 @@ import '@mhmo91/schmancy'
 import { magnetic, cursorGlow, gravity } from '@mhmo91/schmancy/directives'
 ```
 
+## Use with Claude Code
+
+Schmancy ships a Claude Code plugin. In any Claude Code session, run:
+
+```
+/plugin install https://github.com/samwaai/schmancy
+```
+
+Claude now knows every Schmancy component, foundation pattern, and convention in your project. The skill activates automatically when you work on schmancy code — no CLAUDE.md edits, no symlinks.
+
 ## Quick Start
 
 ```html
@@ -38,12 +48,12 @@ import { magnetic, cursorGlow, gravity } from '@mhmo91/schmancy/directives'
 
 Schmancy is organized in four layers:
 
-- **Foundations** — [Area](./ai/area.md) · [Store](./ai/store.md) · [Mixins ($LitElement)](./ai/mixins.md) · [Theme](./ai/theme.md) · [Directives](./ai/directives.md)
-- **Atoms** — [Typography](./ai/typography.md) · [Icons](./ai/icons.md) · [Button](./ai/button.md) · [Surface](./ai/surface.md) · [Divider](./ai/divider.md) · [Avatar](./ai/avatar.md)
+- **Foundations** — [Area](./skills/schmancy/area.md) · [Store](./skills/schmancy/store.md) · [Mixins ($LitElement)](./skills/schmancy/mixins.md) · [Theme](./skills/schmancy/theme.md) · [Directives](./skills/schmancy/directives.md)
+- **Atoms** — [Typography](./skills/schmancy/typography.md) · [Icons](./skills/schmancy/icons.md) · [Button](./skills/schmancy/button.md) · [Surface](./skills/schmancy/surface.md) · [Divider](./skills/schmancy/divider.md) · [Avatar](./skills/schmancy/avatar.md)
 - **Composites (by job)** — Forms, Navigation, Overlays, Interaction, Feedback, Display
-- **Utilities** — [Animation](./ai/animation.md) · [Audio](./ai/audio.md) · [Discovery](./ai/discovery.md) · [RxJS Utils](./ai/rxjs-utils.md) · [Utils](./ai/utils.md)
+- **Utilities** — [Animation](./skills/schmancy/animation.md) · [Audio](./skills/schmancy/audio.md) · [Discovery](./skills/schmancy/discovery.md) · [RxJS Utils](./skills/schmancy/rxjs-utils.md) · [Utils](./skills/schmancy/utils.md)
 
-**Full component index:** [ai/INDEX.md](./ai/INDEX.md) — the single-file map with every tag, service, and convention. Written primarily for AI agents; humans welcome.
+**Full component index:** [skills/schmancy/INDEX.md](./skills/schmancy/INDEX.md) — the single-file map with every tag, service, and convention. Written primarily for AI agents; humans welcome.
 
 ## Tech Stack
 

package/dist/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "schmancy",
+  "description": "Claude Code support for the @mhmo91/schmancy web-component UI library. Provides foundations (routing, store, base class, theme, directives), component API lookup for 60+ tags, and overlay service patterns ($dialog, $notify, schmancyContentDrawer).",
+  "version": "0.1.0",
+  "author": {
+    "name": "samwaai",
+    "url": "https://github.com/samwaai"
+  },
+  "homepage": "https://github.com/samwaai/schmancy",
+  "repository": "https://github.com/samwaai/schmancy",
+  "license": "Apache-2.0",
+  "keywords": ["lit", "web-components", "ui", "schmancy", "tailwind", "rxjs"]
+}

package/dist/skills/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: schmancy
+description: UI patterns, component APIs, and conventions for the @mhmo91/schmancy web-component library (Lit + RxJS + Tailwind). Activate whenever the user works on any <schmancy-*> tag, routing with schmancy-area, state with createContext/@select, the $LitElement base class, theme, directives, or overlay services ($dialog, $notify, schmancyContentDrawer, sheet).
+---
+
+# Schmancy
+
+Web-component UI library on Lit + RxJS + Tailwind CSS. This skill bundles the full library reference as supporting files alongside this SKILL.md.
+
+## How to use this skill
+
+All reference files live in this directory. Read by filename.
+
+1. **Start with `INDEX.md`** for the full catalog organized by job (foundations / atoms / forms / navigation / overlays / interaction / feedback / display).
+2. **Before writing any `<schmancy-X>` tag**, read `X.md`. Example: `<schmancy-button>` → `button.md`.
+3. **Before editing foundations** (routing, state, base class, theme), read the matching foundation file below.
+4. **Apply the conventions** at the end of this file.
+
+## Foundations (the framework pieces — touch first)
+
+| Piece | Read |
+|-------|------|
+| Routing (`<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()`) | `area.md` |
+| State (`createContext`, `@select`, `@selectItem`) | `store.md` |
+| Base class (`$LitElement`) | `mixins.md` |
+| Theme (`<schmancy-theme>`, `theme` service) | `theme.md` |
+| Directives (`magnetic`, `cursorGlow`, `gravity`, `reveal`, `animateText`, …) | `directives.md` |
+| Spring physics presets | `animation.md` |
+
+## Overlay services (prefer over tags)
+
+For modals, toasts, sheets, side drawers — reach for the **imperative service API** first:
+
+```typescript
+import { $dialog, $notify, schmancyContentDrawer, sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
+
+$dialog.component(new EditForm())                       // modal
+$dialog.component(new QuickPicker(), { position: e })    // anchored modal
+$notify.success('Saved'); $notify.error('Failed')        // toast
+schmancyContentDrawer.open({ component: new Detail() })  // side panel
+sheet.open({ component: new Picker(), position: SchmancySheetPosition.BOTTOM })  // bottom sheet
+```
+
+References: `dialog.md`, `notification.md`, `content-drawer.md`, `sheet.md`.
+
+Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip>`, `<schmancy-lightbox>`, `<schmancy-expand>`) only when the tag is the natural fit (anchored panels, tooltips, galleries).
+
+## Non-negotiable conventions
+
+**Component authoring**
+- Every component extends `$LitElement(style?)`. Never raw `LitElement`.
+- Every RxJS subscription ends with `.pipe(takeUntil(this.disconnecting))`.
+- Register the tag in `HTMLElementTagNameMap` for TypeScript.
+
+**State**
+- Contexts live at module scope. Many small contexts beat one monolith.
+- Gate subscriptions with `filter(() => ctx.ready)` when reading persisted contexts.
+- Storage tiers: `'memory'` (regenerable) · `'session'` (per-tab) · `'local'` (user prefs) · `'indexeddb'` (>100-entry collections).
+
+**Routing**
+- Route guards are `Observable<boolean>`, never cached booleans.
+- `when="tag-name"` must exactly match `@customElement('tag-name')`.
+- Lazy-load route components: `lazy(() => import('./page'))`.
+- After auth/permission guards, use `historyStrategy: 'replace'` or `'pop'` — never `'push'`.
+
+**Templates**
+- Lists: `repeat(items, i => i.id, tpl)`. Never `.map()`.
+- View switching: `cache(...)`.
+- Expensive work: `guard([deps], () => expensive())`.
+- Conditionals: `when(...)` / `choose(...)` / `ifDefined(...)`.
+- DOM access: `ref(createRef())`.
+- `classMap(this.classMap({...}))` must be the sole expression in `class=` — never mix with string interpolation.
+
+**Styling**
+- Colors: `--schmancy-sys-color-*` CSS vars or Tailwind theme classes. Never hardcoded hex.
+- No `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+
+**Accessibility (combobox forms)**
+```typescript
+role="combobox"
+aria-haspopup="listbox"
+aria-expanded=${this._open}
+aria-controls="listbox-id"
+```
+Plus a live region: `<div id="live-status" role="status" aria-live="polite" class="sr-only"></div>`.
+
+## Minimal app skeleton
+
+```typescript
+<schmancy-theme root scheme="dark">
+  <schmancy-surface type="solid" fill="all">
+    <schmancy-scroll>
+      <schmancy-area
+        name="root"
+        .default=${lazy(() => import('./home.page'))}
+      >
+        <schmancy-route when="home-page"
+          .component=${lazy(() => import('./home.page'))}></schmancy-route>
+
+        <schmancy-route when="app-index"
+          .component=${lazy(() => import('./app.page'))}
+          .guard=${authState$.pipe(
+            map(u => !!u),
+            takeUntil(this.disconnecting),
+          )}
+          @redirect=${() => area.push({
+            component: 'home-page', area: 'root', historyStrategy: 'replace',
+          })}></schmancy-route>
+      </schmancy-area>
+    </schmancy-scroll>
+  </schmancy-surface>
+</schmancy-theme>
+```
+
+## Workflow
+
+1. User describes a UI task.
+2. Read `INDEX.md` to find the relevant components or foundations.
+3. Read the specific `.md` files for the APIs involved.
+4. Write code that follows the conventions above.

package/dist/skills/schmancy/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: schmancy
+description: UI patterns, component APIs, and conventions for the @mhmo91/schmancy web-component library (Lit + RxJS + Tailwind). Activate whenever the user works on any <schmancy-*> tag, routing with schmancy-area, state with createContext/@select, the $LitElement base class, theme, directives, or overlay services ($dialog, $notify, schmancyContentDrawer, sheet).
+---
+
+# Schmancy
+
+Web-component UI library on Lit + RxJS + Tailwind CSS. This skill bundles the full library reference as supporting files alongside this SKILL.md.
+
+## How to use this skill
+
+All reference files live in this directory. Read by filename.
+
+1. **Start with `INDEX.md`** for the full catalog organized by job (foundations / atoms / forms / navigation / overlays / interaction / feedback / display).
+2. **Before writing any `<schmancy-X>` tag**, read `X.md`. Example: `<schmancy-button>` → `button.md`.
+3. **Before editing foundations** (routing, state, base class, theme), read the matching foundation file below.
+4. **Apply the conventions** at the end of this file.
+
+## Foundations (the framework pieces — touch first)
+
+| Piece | Read |
+|-------|------|
+| Routing (`<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()`) | `area.md` |
+| State (`createContext`, `@select`, `@selectItem`) | `store.md` |
+| Base class (`$LitElement`) | `mixins.md` |
+| Theme (`<schmancy-theme>`, `theme` service) | `theme.md` |
+| Directives (`magnetic`, `cursorGlow`, `gravity`, `reveal`, `animateText`, …) | `directives.md` |
+| Spring physics presets | `animation.md` |
+
+## Overlay services (prefer over tags)
+
+For modals, toasts, sheets, side drawers — reach for the **imperative service API** first:
+
+```typescript
+import { $dialog, $notify, schmancyContentDrawer, sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
+
+$dialog.component(new EditForm())                       // modal
+$dialog.component(new QuickPicker(), { position: e })    // anchored modal
+$notify.success('Saved'); $notify.error('Failed')        // toast
+schmancyContentDrawer.open({ component: new Detail() })  // side panel
+sheet.open({ component: new Picker(), position: SchmancySheetPosition.BOTTOM })  // bottom sheet
+```
+
+References: `dialog.md`, `notification.md`, `content-drawer.md`, `sheet.md`.
+
+Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip>`, `<schmancy-lightbox>`, `<schmancy-expand>`) only when the tag is the natural fit (anchored panels, tooltips, galleries).
+
+## Non-negotiable conventions
+
+**Component authoring**
+- Every component extends `$LitElement(style?)`. Never raw `LitElement`.
+- Every RxJS subscription ends with `.pipe(takeUntil(this.disconnecting))`.
+- Register the tag in `HTMLElementTagNameMap` for TypeScript.
+
+**State**
+- Contexts live at module scope. Many small contexts beat one monolith.
+- Gate subscriptions with `filter(() => ctx.ready)` when reading persisted contexts.
+- Storage tiers: `'memory'` (regenerable) · `'session'` (per-tab) · `'local'` (user prefs) · `'indexeddb'` (>100-entry collections).
+
+**Routing**
+- Route guards are `Observable<boolean>`, never cached booleans.
+- `when="tag-name"` must exactly match `@customElement('tag-name')`.
+- Lazy-load route components: `lazy(() => import('./page'))`.
+- After auth/permission guards, use `historyStrategy: 'replace'` or `'pop'` — never `'push'`.
+
+**Templates**
+- Lists: `repeat(items, i => i.id, tpl)`. Never `.map()`.
+- View switching: `cache(...)`.
+- Expensive work: `guard([deps], () => expensive())`.
+- Conditionals: `when(...)` / `choose(...)` / `ifDefined(...)`.
+- DOM access: `ref(createRef())`.
+- `classMap(this.classMap({...}))` must be the sole expression in `class=` — never mix with string interpolation.
+
+**Styling**
+- Colors: `--schmancy-sys-color-*` CSS vars or Tailwind theme classes. Never hardcoded hex.
+- No `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+
+**Accessibility (combobox forms)**
+```typescript
+role="combobox"
+aria-haspopup="listbox"
+aria-expanded=${this._open}
+aria-controls="listbox-id"
+```
+Plus a live region: `<div id="live-status" role="status" aria-live="polite" class="sr-only"></div>`.
+
+## Minimal app skeleton
+
+```typescript
+<schmancy-theme root scheme="dark">
+  <schmancy-surface type="solid" fill="all">
+    <schmancy-scroll>
+      <schmancy-area
+        name="root"
+        .default=${lazy(() => import('./home.page'))}
+      >
+        <schmancy-route when="home-page"
+          .component=${lazy(() => import('./home.page'))}></schmancy-route>
+
+        <schmancy-route when="app-index"
+          .component=${lazy(() => import('./app.page'))}
+          .guard=${authState$.pipe(
+            map(u => !!u),
+            takeUntil(this.disconnecting),
+          )}
+          @redirect=${() => area.push({
+            component: 'home-page', area: 'root', historyStrategy: 'replace',
+          })}></schmancy-route>
+      </schmancy-area>
+    </schmancy-scroll>
+  </schmancy-surface>
+</schmancy-theme>
+```
+
+## Workflow
+
+1. User describes a UI task.
+2. Read `INDEX.md` to find the relevant components or foundations.
+3. Read the specific `.md` files for the APIs involved.
+4. Write code that follows the conventions above.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmo91/schmancy",
-	"version": "0.9.4",
+	"version": "0.9.5",
 	"description": "UI library build with web components",
 	"main": "./dist/index.js",
 	"customElements": "custom-elements.json",
@@ -13,7 +13,6 @@
 			"types": "./types/mixins/index.d.ts",
 			"default": "./mixins/index.ts"
 		},
-		"./ai/*": "./ai/*",
 		"./*": {
 			"types": "./types/src/*/index.d.ts",
 			"default": "./dist/*.js"
@@ -37,7 +36,8 @@
 		"types",
 		"src",
 		"mixins",
-		"ai",
+		".claude-plugin",
+		"skills",
 		"custom-elements.json",
 		"README.md"
 	],

package/skills/schmancy/INDEX.md

@@ -0,0 +1,72 @@
+# Schmancy — Documentation Index
+
+A Web Component UI library on Lit + RxJS + Tailwind CSS.
+
+## Foundations
+
+The framework pieces — touch before components.
+
+- [Area](./area.md) — `<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()` for routing.
+- [Store](./store.md) — `createContext`, `@select`, `@selectItem`, storage backends.
+- [Mixins](./mixins.md) — `$LitElement` base class.
+- [Theme](./theme.md) — `<schmancy-theme>`, color scheme, CSS variables.
+- [Directives](./directives.md) — Lit directives for physics, effects, text, visibility, interaction.
+- [Animation](./animation.md) — Spring presets (`SPRING_SMOOTH`, etc.), `createAnimation`.
+
+## Components by job
+
+### Display
+[Typography](./typography.md) · [Icons](./icons.md) · [Avatar](./avatar.md) · [Divider](./divider.md) · [Badge](./badge.md) · [Code Highlight](./code-highlight.md) · [Typewriter](./typewriter.md) · [JSON](./json.md) · [Iframe](./iframe.md) · [Map](./map.md) · [Charts](./charts.md)
+
+### Surfaces & layout
+[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Page](./page.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md)
+
+### Forms
+[Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Radio Group](./radio-group.md) · [Chips](./chips.md) · [Date Range](./date-range.md) · [Date Range Inline](./date-range-inline.md) · [Range](./range.md) · [Extra (Country/Timezone)](./extra.md)
+
+### Navigation
+[Nav Drawer](./nav-drawer.md) · [Tabs](./tabs.md) · [Navigation Bar](./navigation-bar.md) · [Navigation Rail](./navigation-rail.md) · [Steps](./steps.md) · [Teleport](./teleport.md) · [Theme Button](./theme-button.md)
+
+### Overlays
+[Dialog](./dialog.md) · [Sheet](./sheet.md) · [Notification](./notification.md) · [Menu](./menu.md) · [Dropdown](./dropdown.md) · [Tooltip](./tooltip.md) · [Lightbox](./lightbox.md) · [Expand](./expand.md)
+
+### Interactive
+[Button](./button.md) · [List](./list.md) · [Details](./details.md) · [Table](./table.md) · [Tree](./tree.md) · [Slider](./slider.md) · [QR Scanner](./qr-scanner.md)
+
+### Feedback
+[Progress](./progress.md) · [Busy](./busy.md) · [Connectivity](./connectivity.md) · [Delay](./delay.md)
+
+### Domain
+[Mailbox](./mailbox.md)
+
+## Services (imperative APIs)
+
+| Service | Purpose |
+|---------|---------|
+| `area` | Route navigation (see [area](./area.md)) |
+| `$dialog` | Open dialogs (see [dialog](./dialog.md)) |
+| `$notify` | Toast notifications (see [notification](./notification.md)) |
+| `schmancyContentDrawer` | Side panel (see [content-drawer](./content-drawer.md)) |
+| `theme` | Theme state, `fullscreen$` (see [theme](./theme.md)) |
+| `sound` | Audio feedback (see [audio](./audio.md)) |
+| `overlayStack` | Z-index coordinator (see [utils](./utils.md)) |
+| `windowManager` | Window registry (see [window](./window.md)) |
+
+## Utilities
+
+[Discovery](./discovery.md) — cross-shadow component lookup.
+[RxJS Utils](./rxjs-utils.md) — `waitForElement`, `waitUntil`, `mutationObserver`.
+[Utils](./utils.md) — `similarity`, `numbers`, `overlayStack`, `intersection$`, `hashContent`.
+[Audio](./audio.md) — synthesized feedback sounds.
+
+## Conventions
+
+- Lists use `repeat(items, item => item.id, tpl)`.
+- View switching uses `cache(...)`.
+- Expensive work uses `guard([deps], fn)`.
+- DOM access uses `ref(createRef())`.
+- Conditionals use `when(...)`, `choose(...)`, `ifDefined(...)`.
+- All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- Don't use `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+- Colors come from `--schmancy-sys-color-*` CSS vars or Tailwind theme classes.
+- `classMap(...)` must be the sole expression in `class=`; never mix with string interpolation.

package/skills/schmancy/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: schmancy
+description: UI patterns, component APIs, and conventions for the @mhmo91/schmancy web-component library (Lit + RxJS + Tailwind). Activate whenever the user works on any <schmancy-*> tag, routing with schmancy-area, state with createContext/@select, the $LitElement base class, theme, directives, or overlay services ($dialog, $notify, schmancyContentDrawer, sheet).
+---
+
+# Schmancy
+
+Web-component UI library on Lit + RxJS + Tailwind CSS. This skill bundles the full library reference as supporting files alongside this SKILL.md.
+
+## How to use this skill
+
+All reference files live in this directory. Read by filename.
+
+1. **Start with `INDEX.md`** for the full catalog organized by job (foundations / atoms / forms / navigation / overlays / interaction / feedback / display).
+2. **Before writing any `<schmancy-X>` tag**, read `X.md`. Example: `<schmancy-button>` → `button.md`.
+3. **Before editing foundations** (routing, state, base class, theme), read the matching foundation file below.
+4. **Apply the conventions** at the end of this file.
+
+## Foundations (the framework pieces — touch first)
+
+| Piece | Read |
+|-------|------|
+| Routing (`<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()`) | `area.md` |
+| State (`createContext`, `@select`, `@selectItem`) | `store.md` |
+| Base class (`$LitElement`) | `mixins.md` |
+| Theme (`<schmancy-theme>`, `theme` service) | `theme.md` |
+| Directives (`magnetic`, `cursorGlow`, `gravity`, `reveal`, `animateText`, …) | `directives.md` |
+| Spring physics presets | `animation.md` |
+
+## Overlay services (prefer over tags)
+
+For modals, toasts, sheets, side drawers — reach for the **imperative service API** first:
+
+```typescript
+import { $dialog, $notify, schmancyContentDrawer, sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
+
+$dialog.component(new EditForm())                       // modal
+$dialog.component(new QuickPicker(), { position: e })    // anchored modal
+$notify.success('Saved'); $notify.error('Failed')        // toast
+schmancyContentDrawer.open({ component: new Detail() })  // side panel
+sheet.open({ component: new Picker(), position: SchmancySheetPosition.BOTTOM })  // bottom sheet
+```
+
+References: `dialog.md`, `notification.md`, `content-drawer.md`, `sheet.md`.
+
+Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip>`, `<schmancy-lightbox>`, `<schmancy-expand>`) only when the tag is the natural fit (anchored panels, tooltips, galleries).
+
+## Non-negotiable conventions
+
+**Component authoring**
+- Every component extends `$LitElement(style?)`. Never raw `LitElement`.
+- Every RxJS subscription ends with `.pipe(takeUntil(this.disconnecting))`.
+- Register the tag in `HTMLElementTagNameMap` for TypeScript.
+
+**State**
+- Contexts live at module scope. Many small contexts beat one monolith.
+- Gate subscriptions with `filter(() => ctx.ready)` when reading persisted contexts.
+- Storage tiers: `'memory'` (regenerable) · `'session'` (per-tab) · `'local'` (user prefs) · `'indexeddb'` (>100-entry collections).
+
+**Routing**
+- Route guards are `Observable<boolean>`, never cached booleans.
+- `when="tag-name"` must exactly match `@customElement('tag-name')`.
+- Lazy-load route components: `lazy(() => import('./page'))`.
+- After auth/permission guards, use `historyStrategy: 'replace'` or `'pop'` — never `'push'`.
+
+**Templates**
+- Lists: `repeat(items, i => i.id, tpl)`. Never `.map()`.
+- View switching: `cache(...)`.
+- Expensive work: `guard([deps], () => expensive())`.
+- Conditionals: `when(...)` / `choose(...)` / `ifDefined(...)`.
+- DOM access: `ref(createRef())`.
+- `classMap(this.classMap({...}))` must be the sole expression in `class=` — never mix with string interpolation.
+
+**Styling**
+- Colors: `--schmancy-sys-color-*` CSS vars or Tailwind theme classes. Never hardcoded hex.
+- No `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+
+**Accessibility (combobox forms)**
+```typescript
+role="combobox"
+aria-haspopup="listbox"
+aria-expanded=${this._open}
+aria-controls="listbox-id"
+```
+Plus a live region: `<div id="live-status" role="status" aria-live="polite" class="sr-only"></div>`.
+
+## Minimal app skeleton
+
+```typescript
+<schmancy-theme root scheme="dark">
+  <schmancy-surface type="solid" fill="all">
+    <schmancy-scroll>
+      <schmancy-area
+        name="root"
+        .default=${lazy(() => import('./home.page'))}
+      >
+        <schmancy-route when="home-page"
+          .component=${lazy(() => import('./home.page'))}></schmancy-route>
+
+        <schmancy-route when="app-index"
+          .component=${lazy(() => import('./app.page'))}
+          .guard=${authState$.pipe(
+            map(u => !!u),
+            takeUntil(this.disconnecting),
+          )}
+          @redirect=${() => area.push({
+            component: 'home-page', area: 'root', historyStrategy: 'replace',
+          })}></schmancy-route>
+      </schmancy-area>
+    </schmancy-scroll>
+  </schmancy-surface>
+</schmancy-theme>
+```
+
+## Workflow
+
+1. User describes a UI task.
+2. Read `INDEX.md` to find the relevant components or foundations.
+3. Read the specific `.md` files for the APIs involved.
+4. Write code that follows the conventions above.

package/skills/schmancy/animation.md

@@ -0,0 +1,64 @@
+# Blackbird Animation System
+
+> Spring physics animation presets for the Web Animations API and CSS transitions.
+
+## Spring Presets
+
+| Preset | Duration | Character | Best For |
+|--------|----------|-----------|----------|
+| `SPRING_SMOOTH` | 500ms | Apple-style, subtle overshoot | Accordions, content reveals |
+| `SPRING_SNAPPY` | 300ms | Quick, minimal overshoot | Buttons, toggles |
+| `SPRING_BOUNCY` | 600ms | Playful, noticeable overshoot | Notifications, celebrations |
+| `SPRING_GENTLE` | 700ms | Slow, no overshoot | Page transitions, modals |
+
+## Usage with Web Animations API
+```typescript
+import { createAnimation, SPRING_SMOOTH } from '@mhmo91/schmancy'
+
+const anim = createAnimation(SPRING_SMOOTH, {
+  from: { opacity: 0, transform: 'translateY(-16px)' },
+  to: { opacity: 1, transform: 'translateY(0)' }
+})
+
+element.animate(anim.keyframes, anim.options)
+```
+
+## Helper Functions
+```typescript
+import {
+  createRevealAnimation,   // Fade in + slide up
+  createDismissAnimation,  // Fade out + slide up
+  createScaleAnimation,    // Pop in/out
+  getEasing,               // Auto-detect linear() support
+  prefersReducedMotion     // Check reduced motion preference
+} from '@mhmo91/schmancy'
+
+// Reveal animation
+const reveal = createRevealAnimation(SPRING_SMOOTH, 16) // 16px distance
+element.animate(reveal.keyframes, reveal.options)
+
+// Scale animation
+const scale = createScaleAnimation(SPRING_SNAPPY, 0.9, 1)
+element.animate(scale.keyframes, scale.options)
+```
+
+## CSS Custom Properties
+```css
+/* Available after injecting ANIMATION_CSS_VARS */
+.element {
+  transition: transform var(--blackbird-duration-smooth) var(--blackbird-easing-smooth);
+}
+```
+
+## Tailwind Integration
+```typescript
+import { tailwindAnimations } from '@mhmo91/schmancy'
+// Use in tailwind.config.js extend block
+
+// Available classes:
+// ease-spring-smooth, ease-spring-snappy, ease-spring-bouncy, ease-spring-gentle
+// duration-spring-smooth, duration-spring-snappy, etc.
+// animate-blackbird-reveal, animate-blackbird-dismiss, etc.
+```
+
+All animations respect `prefers-reduced-motion: reduce` (instant transitions, no animation).