@mhmo91/schmancy 0.9.4 → 0.9.6

package/mixins/formField.mixin.ts

@@ -4,11 +4,17 @@ import { IBaseMixin } from './baseElement'
 import { Constructor } from './constructor'
 import { ITailwindElementMixin, TailwindElement } from './tailwind.mixin'
 
+/**
+ * Cross-realm brand used by `<schmancy-form>` to discover form fields by
+ * inheritance rather than tag-name allowlists. `Symbol.for` puts the symbol in
+ * the global registry so detection works across module realms/bundles.
+ */
+export const SCHMANCY_FORM_FIELD = Symbol.for('schmancy.form-field')
+
 /**
  * Interface defining the properties and methods that the FormFieldMixin adds.
  */
 export interface IFormFieldMixin extends Element {
-	// Properties
 	name: string
 	value: string | string[] | boolean | number | undefined
 	label: string
@@ -20,21 +26,30 @@ export interface IFormFieldMixin extends Element {
 	hint?: string
 	id: string
 
-	// Form association
 	form: HTMLFormElement | null
 
-	// Methods
 	checkValidity(): boolean
 	reportValidity(): boolean
 	setCustomValidity(message: string): void
 
-	// Event emitter helper
+	toFormEntries(): Array<[string, FormDataEntryValue]>
+	resetForm(): void
+
 	emitChange(detail: any): void
 }
 
+/** Predicate used by `<schmancy-form>` to detect mixin descendants. */
+export function isSchmancyFormField(el: unknown): el is IFormFieldMixin {
+	return !!el && typeof el === 'object' && (el as any).constructor?.[SCHMANCY_FORM_FIELD] === true
+}
+
 /**
  * A mixin that adds form field capabilities to a LitElement class.
- * This provides common form field properties, validation, and form association.
+ * Components that extend this mixin are automatically discovered and
+ * collected by `<schmancy-form>` — no tag-name registration needed.
+ *
+ * Subclasses may override `toFormEntries()` to contribute multiple
+ * name/value pairs to FormData (e.g. date-range, tag-input).
  *
  * @example
  * ```ts
@@ -47,67 +62,42 @@ export function FormFieldMixin<T extends Constructor<LitElement>>(superClass: T)
 	class FormFieldMixinClass extends superClass {
 		static formAssociated = true
 
+		/** Brand for cross-realm detection by `<schmancy-form>`. */
+		static readonly [SCHMANCY_FORM_FIELD] = true
+
 		// Element internals for form association
-		private internals: ElementInternals | undefined
+		internals: ElementInternals | undefined
+
+		/** Value snapshot captured at first render, used by `resetForm()`. */
+		protected _defaultValue: string | string[] | boolean | number | undefined = undefined
 
-		// Properties common to form fields
-		/**
-		 * The name of the form field (used for form submission)
-		 */
 		@property({ type: String })
 		name: string = ''
 
-		/**
-		 * The current value of the form field
-		 */
 		@property({ reflect: true })
 		value: string | string[] | boolean | number | undefined = ''
 
-		/**
-		 * Label text for the form field
-		 */
 		@property({ type: String })
 		label: string = ''
 
-		/**
-		 * Whether the field is required
-		 */
 		@property({ type: Boolean, reflect: true })
 		required: boolean = false
 
-		/**
-		 * Whether the field is disabled
-		 */
 		@property({ type: Boolean, reflect: true })
 		disabled: boolean = false
 
-		/**
-		 * Whether the field is read-only
-		 */
 		@property({ type: Boolean, reflect: true })
 		readonly: boolean = false
 
-		/**
-		 * Whether the field is in an error state
-		 */
 		@property({ type: Boolean, reflect: true })
 		error: boolean = false
 
-		/**
-		 * The validation message to display
-		 */
 		@property({ type: String })
 		validationMessage: string = ''
 
-		/**
-		 * Optional hint text to display below the field
-		 */
 		@property({ type: String })
 		hint?: string
 
-		/**
-		 * Unique identifier for the field
-		 */
 		@property({ reflect: true })
 		override id: string = `schmancy-field-${Date.now()}-${Math.floor(Math.random() * 1000)}`
 
@@ -120,25 +110,23 @@ export function FormFieldMixin<T extends Constructor<LitElement>>(superClass: T)
 			}
 		}
 
-		/**
-		 * Gets the form this element is associated with
-		 */
+		/** The form this element is associated with (native FACE behavior). */
 		get form(): HTMLFormElement | null {
 			return this.internals?.form ?? null
 		}
 
-		/**
-		 * Lifecycle method called when properties change
-		 */
+		protected firstUpdated(changedProps: PropertyValueMap<any>): void {
+			super.firstUpdated?.(changedProps)
+			if (this._defaultValue === undefined) this._defaultValue = this.value
+		}
+
 		protected willUpdate(changedProps: PropertyValueMap<any>): void {
 			super.willUpdate(changedProps)
 
-			// Update form value when value changes
 			if (changedProps.has('value')) {
 				this.internals?.setFormValue(this.value as string | File | FormData | null)
 			}
 
-			// Update validation state when error or validation message changes
 			if (changedProps.has('error') || changedProps.has('validationMessage')) {
 				if (this.error && this.validationMessage) {
 					this.internals?.setValidity({ customError: true }, this.validationMessage)
@@ -146,37 +134,87 @@ export function FormFieldMixin<T extends Constructor<LitElement>>(superClass: T)
 					this.internals?.setValidity({})
 				}
 			}
+
+			// Broadcast standard field states for consumer CSS: :state(invalid),
+			// :state(required), :state(disabled), :state(readonly).
+			if (changedProps.has('error')) {
+				if (this.error) this.internals?.states.add('invalid')
+				else this.internals?.states.delete('invalid')
+			}
+			if (changedProps.has('required')) {
+				if (this.required) this.internals?.states.add('required')
+				else this.internals?.states.delete('required')
+			}
+			if (changedProps.has('disabled')) {
+				if (this.disabled) this.internals?.states.add('disabled')
+				else this.internals?.states.delete('disabled')
+			}
+			if (changedProps.has('readonly')) {
+				if (this.readonly) this.internals?.states.add('readonly')
+				else this.internals?.states.delete('readonly')
+			}
+		}
+
+		/**
+		 * Native FACE lifecycle — called by the browser when the owning form
+		 * is reset. Delegates to `resetForm()` so subclasses have one
+		 * override point for both programmatic and user-initiated resets.
+		 */
+		formResetCallback(): void {
+			this.resetForm()
+		}
+
+		/** Native FACE lifecycle — called when the form's disabled state changes. */
+		formDisabledCallback(disabled: boolean): void {
+			this.disabled = disabled
+		}
+
+		/**
+		 * Native FACE lifecycle — restore value after bfcache / form autofill.
+		 */
+		formStateRestoreCallback(state: string | File | FormData | null): void {
+			if (state == null) return
+			this.value = state as any
+		}
+
+		/** Override to customize reset behavior; default restores `_defaultValue`. */
+		resetForm(): void {
+			this.value = this._defaultValue ?? ''
+			this.error = false
+			this.validationMessage = ''
+			this.internals?.setValidity({})
 		}
 
 		/**
-		 * Checks if the field is valid without showing validation UI
+		 * Contribute entries to a parent FormData. Default: a single
+		 * `[name, value]` pair when `name` is set and value is meaningful.
+		 * Override for multi-entry controls (e.g. date range).
 		 */
+		toFormEntries(): Array<[string, FormDataEntryValue]> {
+			if (!this.name || this.disabled) return []
+			const v = this.value
+			if (v === undefined || v === null || v === '') return []
+			if (Array.isArray(v)) return v.map(item => [this.name, String(item)] as [string, FormDataEntryValue])
+			if (typeof v === 'boolean') return v ? [[this.name, 'on']] : []
+			return [[this.name, String(v)]]
+		}
+
 		checkValidity(): boolean {
 			if (this.disabled) return true
-
 			if (this.required && (this.value === '' || this.value === undefined || this.value === null)) {
 				this.error = true
 				this.validationMessage = 'This field is required'
 				return false
 			}
-
-			return true
+			return this.internals?.checkValidity() ?? true
 		}
 
-		/**
-		 * Reports validity and shows validation UI if invalid
-		 */
 		reportValidity(): boolean {
 			const isValid = this.checkValidity()
-			if (!isValid) {
-				this.internals?.reportValidity()
-			}
+			if (!isValid) this.internals?.reportValidity()
 			return isValid
 		}
 
-		/**
-		 * Sets a custom validation message
-		 */
 		setCustomValidity(message: string): void {
 			this.validationMessage = message
 			this.error = message !== ''
@@ -187,11 +225,7 @@ export function FormFieldMixin<T extends Constructor<LitElement>>(superClass: T)
 			}
 		}
 
-		/**
-		 * Helper method to emit change events using dispatchScopedEvent for instance isolation
-		 */
 		emitChange(detail: any): void {
-			// Use dispatchScopedEvent if available (from BaseElement mixin)
 			if ('dispatchScopedEvent' in this && typeof this.dispatchScopedEvent === 'function') {
 				this.dispatchScopedEvent('change', detail, { bubbles: true })
 			} else {
@@ -212,13 +246,6 @@ export function FormFieldMixin<T extends Constructor<LitElement>>(superClass: T)
 /**
  * A convenience function that composes FormFieldMixin with TailwindElement
  * to create a base class for Schmancy form components.
- *
- * @example
- * ```ts
- * class MyInput extends SchmancyFormField(css`...`) {
- *   // Your component code here
- * }
- * ```
  */
 export function SchmancyFormField<T extends CSSResult>(componentStyle?: T) {
 	return FormFieldMixin(TailwindElement(componentStyle)) as Constructor<IFormFieldMixin> &

package/mixins/tailwind.css

@@ -1,7 +1,17 @@
 @import 'tailwindcss';
+
+/* Cascade-layer order contract. Consumer (unlayered) CSS always overrides
+   library styles regardless of specificity. Library-internal tokens and
+   components live in named layers so consumers can target them precisely. */
+@layer schmancy.tokens, schmancy.base, schmancy.components;
+
+@layer schmancy.base {
 :host,
 :root {
 	font-family: var(--schmancy-font-family);
+	/* Advertise both schemes so UA form controls, scrollbars, and
+	   `light-dark()` all render correctly until a theme resolves it. */
+	color-scheme: light dark;
 }
 :host,
 :host *,
@@ -547,3 +557,4 @@
 	--ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
 	--ease-snap: cubic-bezier(0.34, 1.2, 0.64, 1);
 }
+}  /* end @layer schmancy.base */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmo91/schmancy",
-	"version": "0.9.4",
+	"version": "0.9.6",
 	"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"
 	],
@@ -53,7 +53,10 @@
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"test:ui": "vitest --ui",
-		"test:coverage": "vitest run --coverage"
+		"test:coverage": "vitest run --coverage",
+		"knip": "knip",
+		"format": "prettier --write 'src/**/*.{ts,css,scss}' 'mixins/**/*.{ts,css}'",
+		"format:check": "prettier --check 'src/**/*.{ts,css,scss}' 'mixins/**/*.{ts,css}'"
 	},
 	"author": "@mhmo91",
 	"license": "Apache-2.0",
@@ -67,53 +70,41 @@
 		"@lit-labs/virtualizer": "^2.1.1",
 		"@lit/context": "^1.1.6",
 		"@material/material-color-utilities": "^0.4.0",
-		"@material/mwc-base": "^0.27.0",
 		"@material/web": "^2.4.1",
-		"@rollup/plugin-strip": "^3.0.4",
-		"@rollup/plugin-terser": "^1.0.0",
-		"@tailwindcss/nesting": "^0.0.0-insiders.565cd3e",
 		"@types/cleave.js": "^1.4.12",
-		"@webcomponents/scoped-custom-element-registry": "^0.0.10",
-		"@webcomponents/webcomponentsjs": "^2.8.0",
 		"cleave.js": "^1.6.0",
 		"dayjs": "^1.11.20",
-		"fastest-levenshtein": "^1.0.16",
 		"highlight.js": "^11.11.1",
 		"immer": "^11.1.4",
 		"jsqr": "^1.4.0",
 		"lit": "^3.3.2",
-		"playground-elements": "^0.21.2",
 		"rxjs": "^7.8.2",
-		"tippy.js": "^6.3.7",
 		"ts-is-present": "^1.2.2",
-		"typeit": "^8.8.7",
-		"typescript": "^5.9.3",
-		"uuid": "^13.0.0",
-		"web-component-analyzer": "^2.0.0"
+		"typeit": "^8.8.7"
 	},
 	"devDependencies": {
-		"@tailwindcss/container-queries": "^0.1.1",
-		"@tailwindcss/forms": "^0.5.11",
+		"@rollup/plugin-strip": "^3.0.4",
+		"@rollup/plugin-terser": "^1.0.0",
 		"@tailwindcss/postcss": "^4.2.1",
 		"@tailwindcss/vite": "^4.2.1",
 		"@types/node": "^25.5.0",
-		"@types/uuid": "^11.0.0",
-		"@typescript-eslint/parser": "^8.57.1",
+		"@vitest/browser-playwright": "^4.1.4",
+		"@vitest/coverage-v8": "^4.1.5",
 		"@vitest/ui": "^4.1.0",
-		"autoprefixer": "^10.4.27",
-		"c8": "^11.0.0",
-		"concurrently": "^9.2.1",
-		"deepmerge": "^4.3.1",
-		"eslint": "^10.0.3",
+		"axe-core": "^4.11.3",
 		"happy-dom": "^20.8.4",
+		"knip": "^6.6.0",
+		"playwright": "^1.59.1",
 		"postcss": "^8.5.8",
 		"prettier": "^3.8.1",
 		"rollup-plugin-copy": "^3.5.0",
 		"sass": "^1.98.0",
 		"tailwindcss": "^4.2.1",
+		"ts-lit-plugin": "^2.0.2",
+		"typescript": "^5.9.3",
 		"vite": "^8.0.0",
-		"vite-plugin-sitemap": "^0.8.2",
-		"vitest": "^4.1.0"
+		"vitest": "^4.1.0",
+		"web-component-analyzer": "^2.0.0"
 	},
 	"peerDependencies": {
 		"lit": "^3.2.1",

package/skills/schmancy/INDEX.md

@@ -0,0 +1,73 @@
+# 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) · [Kbd](./kbd.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) · [Splash Screen](./splash-screen.md)
+
+### Forms
+[Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Switch](./switch.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
+[Breadcrumb](./breadcrumb.md) · [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 (directive)](./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) · [Skeleton](./skeleton.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`.
+[Visually Hidden](./visually-hidden.md) — screen-reader-only content wrapper.
+[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).