@mhmo91/schmancy 0.9.4 → 0.9.6

package/dist/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/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/dist/skills/schmancy/breadcrumb.md

@@ -0,0 +1,53 @@
+# schmancy-breadcrumb
+
+> Breadcrumb navigation with auto-inserted separators and ARIA landmark semantics.
+
+## Usage
+```html
+<schmancy-breadcrumb>
+  <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item href="/projects">Projects</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>Dashboard</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```
+
+## schmancy-breadcrumb
+
+Container. Renders a `<nav aria-label="Breadcrumb">` and inserts a separator element between each slotted item.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| separator | string | `'/'` | Character or string rendered between items. Hidden from assistive tech via `aria-hidden="true"`. |
+
+| Part | Description |
+|------|-------------|
+| separator | Each inserted separator element. Style bulk via `schmancy-breadcrumb::part(separator)`. |
+
+The host sets `aria-label="Breadcrumb"` on connection if none was already set.
+
+## schmancy-breadcrumb-item
+
+Individual crumb. Renders as `<a>` when `href` is set, otherwise `<span>`.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| href | string | `''` | When set (and `current` is false), renders as an anchor. |
+| current | boolean | `false` | Marks this item as `aria-current="page"`. Renders as a plain `<span>` even if `href` is set. |
+
+## Examples
+```html
+<!-- Custom separator -->
+<schmancy-breadcrumb separator="›">
+  <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item href="/docs">Docs</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>API</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```
+
+```html
+<!-- Two-level (just two crumbs) -->
+<schmancy-breadcrumb>
+  <schmancy-breadcrumb-item href="/users">Users</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>Jane Doe</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```

package/dist/skills/schmancy/kbd.md

@@ -0,0 +1,40 @@
+# schmancy-kbd
+
+> Render a keyboard shortcut hint. Semantically a `<kbd>` element; visually styled as a pressed key.
+
+## Usage
+```html
+Press <schmancy-kbd>⌘</schmancy-kbd> + <schmancy-kbd>K</schmancy-kbd> to search.
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| size | `'sm'\|'md'` | `'md'` | Smaller variant for inline text. |
+
+## Parts
+| Part | Description |
+|------|-------------|
+| base | The inner native `<kbd>` element. |
+
+## Examples
+```html
+<!-- Inline combo -->
+<schmancy-typography>
+  <schmancy-kbd size="sm">Shift</schmancy-kbd>
+  +
+  <schmancy-kbd size="sm">Tab</schmancy-kbd>
+  to move backwards
+</schmancy-typography>
+```
+
+```html
+<!-- Command palette shortcut -->
+<div class="flex items-center gap-2">
+  Open command palette
+  <span>
+    <schmancy-kbd>⌘</schmancy-kbd>
+    <schmancy-kbd>K</schmancy-kbd>
+  </span>
+</div>
+```

package/dist/skills/schmancy/skeleton.md

@@ -0,0 +1,40 @@
+# schmancy-skeleton
+
+> Placeholder shimmer surface shown while content loads. Reduced-motion-aware.
+
+## Usage
+```html
+<schmancy-skeleton width="12rem" height="1rem"></schmancy-skeleton>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| shape | `'rect'\|'circle'\|'text'` | `'rect'` | Visual shape. `circle` forces 50% border radius; `text` defaults height to `1em`. |
+| width | string (CSS length) | `100%` | Any CSS length (e.g. `12rem`, `50%`). |
+| height | string (CSS length) | `1rem` (or `1em` when `shape=text`) | Any CSS length. |
+| radius | string (CSS length) | `0.25rem` | Corner radius; ignored when `shape=circle`. |
+
+## Parts
+| Part | Description |
+|------|-------------|
+| surface | The shimmering inner surface. |
+
+## Accessibility
+The host sets `role="status" aria-busy="true" aria-label="Loading"` on connection, so assistive tech announces the loading region. Under `prefers-reduced-motion: reduce`, the shimmer animation is removed and a flat surface color is used.
+
+## Examples
+```html
+<!-- Single line of text -->
+<schmancy-skeleton shape="text" width="60%"></schmancy-skeleton>
+
+<!-- Avatar placeholder -->
+<schmancy-skeleton shape="circle" width="48px" height="48px"></schmancy-skeleton>
+
+<!-- Card placeholder -->
+<schmancy-card>
+  <schmancy-skeleton width="100%" height="160px" radius="0.5rem"></schmancy-skeleton>
+  <schmancy-skeleton shape="text" width="80%"></schmancy-skeleton>
+  <schmancy-skeleton shape="text" width="40%"></schmancy-skeleton>
+</schmancy-card>
+```

package/dist/skills/schmancy/splash-screen.md

@@ -0,0 +1,60 @@
+# schmancy-splash-screen
+
+> Full-viewport splash overlay that fades out once ready; consumer supplies the visuals.
+
+## Usage
+```html
+<schmancy-splash-screen min-duration="1200">
+  <my-logo slot="splash"></my-logo>
+  <my-app></my-app>
+</schmancy-splash-screen>
+```
+
+The `splash` slot holds the overlay content (logo, animation, whatever). The default slot is the real app, revealed after the splash dismisses. The overlay is empty by default — no built-in spinner, no hidden dependencies. Bring your own visuals.
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| minDuration | number | `1500` | Minimum ms the splash stays visible (prevents flash on fast loads). |
+| auto | boolean | `false` | When true, dismiss on the `minDuration` timer alone. When false, also wait for a `ready` signal. |
+| initiallyHidden | boolean | `false` | When true, the splash starts hidden. Use with `show()` for imperative control (e.g. between route transitions). |
+
+## Methods
+| Method | Description |
+|--------|-------------|
+| `ready()` | Signal that the app is ready — dismisses once `minDuration` has also elapsed. |
+| `show()` | Force the splash back on (e.g. re-show between route transitions). |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| schmancy-splash-done | `void` | Fires when the splash finishes dismissing. |
+
+## CSS custom properties
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--schmancy-splash-background` | `var(--schmancy-sys-color-surface-containerLowest, #000)` | Splash layer background. |
+| `--schmancy-splash-transition` | `500ms` | Fade duration. |
+
+## Examples
+```html
+<!-- Wait for explicit ready signal (default) -->
+<schmancy-splash-screen min-duration="800">
+  <img slot="splash" src="/logo.svg" />
+  <main-app></main-app>
+</schmancy-splash-screen>
+```
+
+```typescript
+// Imperative: signal ready when data loads
+const splash = document.querySelector('schmancy-splash-screen')!
+dataStore.loaded$.subscribe(() => splash.ready())
+```
+
+```html
+<!-- Auto mode: dismisses purely on the timer -->
+<schmancy-splash-screen min-duration="1200" auto>
+  <schmancy-typography type="display" token="lg" slot="splash">Welcome</schmancy-typography>
+  <app-shell></app-shell>
+</schmancy-splash-screen>
+```

package/dist/skills/schmancy/switch.md

@@ -0,0 +1,58 @@
+# schmancy-switch
+
+> Binary on/off control. Form-associated, ARIA `role="switch"`. Use for immediate state changes; use `<schmancy-checkbox>` for form selections.
+
+## Usage
+```html
+<schmancy-switch name="notifications" label="Email notifications" @change=${(e) => handle(e.detail.value)}>
+</schmancy-switch>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| checked | boolean | `false` | Current on/off state. Reflected as attribute. |
+| name | string | `''` | Form submission name. |
+| value | string | `'on'` | Value submitted when checked. |
+| label | string | `''` | ARIA label on the inner button; also used by axe. |
+| required | boolean | `false` | Must be on for form validity. |
+| disabled | boolean | `false` | Disables interaction. |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: boolean }` | Fires when the state toggles (via click or Enter/Space). |
+
+## Parts
+| Part | Description |
+|------|-------------|
+| track | Background track element. |
+| thumb | Moving thumb element. |
+
+## States
+| State | When |
+|-------|------|
+| `:state(checked)` | While the switch is on. Target via `schmancy-switch:state(checked) { … }`. |
+
+## Form association
+Uses `ElementInternals` — participates in `<form>` submission natively. Contributes `name=value` when checked; omitted when unchecked. `formResetCallback` restores the initial `checked` attribute. `formDisabledCallback` propagates `<fieldset disabled>`.
+
+## Examples
+```html
+<!-- Inside a form -->
+<schmancy-form>
+  <schmancy-switch name="marketing" label="Marketing emails"></schmancy-switch>
+  <schmancy-switch name="product" label="Product updates" checked></schmancy-switch>
+  <schmancy-button type="submit">Save</schmancy-button>
+</schmancy-form>
+```
+
+```html
+<!-- Required toggle (must be on to submit) -->
+<schmancy-switch name="agree" label="I agree" required></schmancy-switch>
+```
+
+```html
+<!-- Custom submitted value -->
+<schmancy-switch name="mode" value="dark" label="Dark mode"></schmancy-switch>
+```

package/dist/skills/schmancy/tooltip.md

@@ -0,0 +1,38 @@
+# tooltip (directive)
+
+> Lit directive that adds a positioned tooltip to any element on hover/focus. The `<schmancy-tooltip>` component was removed — use this directive.
+
+## Usage
+```typescript
+import { tooltip } from '@mhmo91/schmancy'
+
+html`<button ${tooltip('Click to save')}>Save</button>`
+```
+
+## Parameters
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| text | string | required | Tooltip text content |
+| options.position | `'top'\|'right'\|'bottom'\|'left'` | `'top'` | Tooltip placement |
+| options.delay | number | `300` | Show delay in ms |
+| options.showArrow | boolean | `true` | Show arrow indicator |
+
+## Examples
+```html
+<!-- Bottom positioned -->
+<schmancy-icon-button ${tooltip('Delete item', { position: 'bottom' })}>
+  delete
+</schmancy-icon-button>
+
+<!-- No delay, no arrow -->
+<span ${tooltip('Status: Active', { delay: 0, showArrow: false })}>
+  Active
+</span>
+
+<!-- Right positioned -->
+<div ${tooltip('More info here', { position: 'right' })}>
+  Hover me
+</div>
+```
+
+Uses Floating UI for smart positioning with automatic flipping when near viewport edges. Accessible via `aria-describedby`. Closes on Escape key.

package/dist/skills/schmancy/visually-hidden.md

@@ -0,0 +1,41 @@
+# schmancy-visually-hidden
+
+> Hide content visually while keeping it in the accessibility tree. For screen-reader-only labels, supplemental descriptions, and live-region text.
+
+## Usage
+```html
+<button>
+  <schmancy-icon>close</schmancy-icon>
+  <schmancy-visually-hidden>Close dialog</schmancy-visually-hidden>
+</button>
+```
+
+## Why not `display: none` / `visibility: hidden` / `aria-hidden`?
+Those remove content from assistive tech too. `<schmancy-visually-hidden>` uses the WCAG-recommended clip pattern, so screen readers still read the content while sighted users don't see it.
+
+## Properties
+None. Pure wrapper.
+
+## Examples
+```html
+<!-- Icon-only button label -->
+<schmancy-icon-button>
+  <schmancy-icon>delete</schmancy-icon>
+  <schmancy-visually-hidden>Delete item</schmancy-visually-hidden>
+</schmancy-icon-button>
+```
+
+```html
+<!-- Additional context for links -->
+<a href="/article/42">
+  Read more
+  <schmancy-visually-hidden>about quarterly earnings</schmancy-visually-hidden>
+</a>
+```
+
+```html
+<!-- Live region announcements -->
+<schmancy-visually-hidden role="status" aria-live="polite">
+  ${this.status}
+</schmancy-visually-hidden>
+```

package/dist/skills/skeleton.md

@@ -0,0 +1,40 @@
+# schmancy-skeleton
+
+> Placeholder shimmer surface shown while content loads. Reduced-motion-aware.
+
+## Usage
+```html
+<schmancy-skeleton width="12rem" height="1rem"></schmancy-skeleton>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| shape | `'rect'\|'circle'\|'text'` | `'rect'` | Visual shape. `circle` forces 50% border radius; `text` defaults height to `1em`. |
+| width | string (CSS length) | `100%` | Any CSS length (e.g. `12rem`, `50%`). |
+| height | string (CSS length) | `1rem` (or `1em` when `shape=text`) | Any CSS length. |
+| radius | string (CSS length) | `0.25rem` | Corner radius; ignored when `shape=circle`. |
+
+## Parts
+| Part | Description |
+|------|-------------|
+| surface | The shimmering inner surface. |
+
+## Accessibility
+The host sets `role="status" aria-busy="true" aria-label="Loading"` on connection, so assistive tech announces the loading region. Under `prefers-reduced-motion: reduce`, the shimmer animation is removed and a flat surface color is used.
+
+## Examples
+```html
+<!-- Single line of text -->
+<schmancy-skeleton shape="text" width="60%"></schmancy-skeleton>
+
+<!-- Avatar placeholder -->
+<schmancy-skeleton shape="circle" width="48px" height="48px"></schmancy-skeleton>
+
+<!-- Card placeholder -->
+<schmancy-card>
+  <schmancy-skeleton width="100%" height="160px" radius="0.5rem"></schmancy-skeleton>
+  <schmancy-skeleton shape="text" width="80%"></schmancy-skeleton>
+  <schmancy-skeleton shape="text" width="40%"></schmancy-skeleton>
+</schmancy-card>
+```

package/dist/skills/splash-screen.md

@@ -0,0 +1,60 @@
+# schmancy-splash-screen
+
+> Full-viewport splash overlay that fades out once ready; consumer supplies the visuals.
+
+## Usage
+```html
+<schmancy-splash-screen min-duration="1200">
+  <my-logo slot="splash"></my-logo>
+  <my-app></my-app>
+</schmancy-splash-screen>
+```
+
+The `splash` slot holds the overlay content (logo, animation, whatever). The default slot is the real app, revealed after the splash dismisses. The overlay is empty by default — no built-in spinner, no hidden dependencies. Bring your own visuals.
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| minDuration | number | `1500` | Minimum ms the splash stays visible (prevents flash on fast loads). |
+| auto | boolean | `false` | When true, dismiss on the `minDuration` timer alone. When false, also wait for a `ready` signal. |
+| initiallyHidden | boolean | `false` | When true, the splash starts hidden. Use with `show()` for imperative control (e.g. between route transitions). |
+
+## Methods
+| Method | Description |
+|--------|-------------|
+| `ready()` | Signal that the app is ready — dismisses once `minDuration` has also elapsed. |
+| `show()` | Force the splash back on (e.g. re-show between route transitions). |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| schmancy-splash-done | `void` | Fires when the splash finishes dismissing. |
+
+## CSS custom properties
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--schmancy-splash-background` | `var(--schmancy-sys-color-surface-containerLowest, #000)` | Splash layer background. |
+| `--schmancy-splash-transition` | `500ms` | Fade duration. |
+
+## Examples
+```html
+<!-- Wait for explicit ready signal (default) -->
+<schmancy-splash-screen min-duration="800">
+  <img slot="splash" src="/logo.svg" />
+  <main-app></main-app>
+</schmancy-splash-screen>
+```
+
+```typescript
+// Imperative: signal ready when data loads
+const splash = document.querySelector('schmancy-splash-screen')!
+dataStore.loaded$.subscribe(() => splash.ready())
+```
+
+```html
+<!-- Auto mode: dismisses purely on the timer -->
+<schmancy-splash-screen min-duration="1200" auto>
+  <schmancy-typography type="display" token="lg" slot="splash">Welcome</schmancy-typography>
+  <app-shell></app-shell>
+</schmancy-splash-screen>
+```