@mhmo91/schmancy 0.9.3 → 0.9.5

package/skills/schmancy/directives.md

@@ -0,0 +1,298 @@
+# Schmancy Directives — AI Reference
+
+## What Are Directives?
+
+Lit directives that snap onto any element to add behavior. No components to wrap, no CSS to write — just `${directiveName()}` in your template.
+
+```typescript
+import { magnetic, cursorGlow, gravity, reveal } from '@mhmo91/schmancy/directives'
+```
+
+---
+
+## Physics & Interaction (6 directives)
+
+### `magnetic` — Elements lean toward the cursor
+```html
+<schmancy-button ${magnetic()}>Submit</schmancy-button>
+<schmancy-icon-button ${magnetic({ strength: 6, radius: 120 })}>add</schmancy-icon-button>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `strength` | 4 | Max displacement in px |
+| `radius` | 100 | Activation radius in px |
+
+Embedded in: `schmancy-button`, `schmancy-icon-button`, `schmancy-filter-chip`, `schmancy-details` (summary)
+
+### `cursorGlow` — Light follows cursor across a surface
+```html
+<schmancy-surface type="glass" ${cursorGlow()}>content</schmancy-surface>
+<div ${cursorGlow({ radius: 300, intensity: 0.2, color: 'var(--schmancy-sys-color-secondary-default)' })}>
+  hero panel
+</div>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `radius` | 200 | Glow radius in px |
+| `color` | primary | CSS color value |
+| `intensity` | 0.12 | Opacity 0-1 |
+
+Embedded in: `schmancy-card` (interactive), `schmancy-dialog`
+
+### `livingBorder` — Animated gradient light traces element edges
+```html
+<schmancy-card ${livingBorder()}>content</schmancy-card>
+<div ${livingBorder({ duration: 4000, onHover: true, color: 'var(--schmancy-sys-color-secondary-default)' })}>
+  hero panel
+</div>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `duration` | 3000 | Rotation speed in ms |
+| `width` | 1 | Border width in px |
+| `color` | primary | Glow color |
+| `spread` | 6 | Glow spread in px |
+| `onHover` | false | Only animate on hover |
+
+### `gravity` — Elements fall into place with mass-based bounce
+```html
+<!-- Single element drops in -->
+<schmancy-card ${gravity()}>content</schmancy-card>
+
+<!-- Staggered list — each item falls 50ms after the previous -->
+${repeat(items, item => item.id, (item, i) => html`
+  <div ${gravity({ stagger: 50 * i, mass: 0.8 })}>...</div>
+`)}
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `mass` | 1.0 | 0.5 (bouncy) to 2.0 (heavy) |
+| `distance` | 30 | Fall distance in px |
+| `delay` | 0 | Delay before falling in ms |
+| `stagger` | 0 | Per-item stagger in ms |
+
+Only animates once. Re-triggers on reconnect (route change, cache toggle).
+
+### `depthOfField` — Progressive blur on background content
+```html
+<main ${depthOfField({ active: this.dialogOpen, maxBlur: 8 })}>
+  page content that blurs when dialog opens
+</main>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `active` | required | Boolean — blur when true |
+| `maxBlur` | 8 | Max blur radius in px |
+| `duration` | 400 | Transition duration in ms |
+
+### `longPress` — Press-and-hold gesture detection
+```html
+<div ${longPress(() => this.showContextMenu())}>Hold me</div>
+<div ${longPress(() => this.showMenu(), { duration: 800, movementThreshold: 15 })}>
+  Custom timing
+</div>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `duration` | 500 | Time before trigger in ms |
+| `movementThreshold` | 10 | Max movement in px before cancel |
+
+---
+
+## Visual Effects (3 directives)
+
+### `nebula` — Surreal dimensional rift loading effect
+```html
+<div ${nebula()}>Content with cosmic loading effect</div>
+<div ${nebula({ active: this.loading, temperature: -0.5, speed: 1.5 })}>
+  Cool-toned, faster nebula
+</div>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `active` | true | Show/hide the effect |
+| `intensity` | 1 | Brightness 0-1 |
+| `speed` | 1 | Animation speed multiplier |
+| `temperature` | 0 | -1 (cool/blue) to 1 (warm/pink) |
+| `particleCount` | 30 | Quantum particle count |
+| `autoHideDuration` | 3000 | Auto-dim after ms (0 = never) |
+| `background` | true | Render behind content |
+
+### `liquid` — Apple Liquid Glass effect (pure CSS)
+```html
+<div ${liquid()}>Glass panel</div>
+<div ${liquid({ intensity: 'strong', active: this.isActive })}>
+  Thick glass
+</div>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `active` | true | Toggle effect on/off |
+| `intensity` | 'medium' | 'light', 'medium', or 'strong' |
+
+Zero DOM mutation — applies only inline styles.
+
+### `ripple` — Material-style ink ripple on click
+```html
+<div ${ripple()}>Click me</div>
+```
+No options. Ripple appears at click position, fades out in 600ms.
+
+---
+
+## Text Animation (3 directives)
+
+### `animateText` — 5 text animation modes
+```html
+<span ${animateText({ animation: 'blur-reveal', stagger: 60 })}>Hello world</span>
+<span ${animateText({ animation: 'cyber-glitch', preset: 'snappy' })}>GLITCH</span>
+<span ${animateText({ animation: 'fade-up' })}>Fade up</span>
+```
+| Animation | Description |
+|-----------|-------------|
+| `typewriter` | Characters appear one by one |
+| `fade-up` | Whole element fades up |
+| `word-reveal` | Words appear one by one from below |
+| `blur-reveal` | Words deblur + scale in |
+| `cyber-glitch` | Characters pop in with overshoot |
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `animation` | required | Animation type |
+| `preset` | 'snappy' | Spring preset: smooth, snappy, bouncy, gentle |
+| `stagger` | 50 | Ms between characters/words |
+| `text` | element content | Explicit text (for Lit bindings) |
+| `restart` | false | Re-animate on viewport re-entry |
+
+Waits for element visibility before starting.
+
+### `cycleText` — Cycle through child elements with transitions
+```html
+<span ${cycleText({ transition: 'slide', hold: 1500 })}>
+  <span>First</span>
+  <span>Second</span>
+  <span>Third</span>
+</span>
+
+<!-- Add mode: accumulates items -->
+<span ${cycleText({ mode: 'add', transition: 'typewriter' })}>
+  <span>guests</span>
+  <span>kitchen</span>
+  <span>team</span>
+</span>
+<!-- Shows: "guests" → "guests, kitchen" → "guests, kitchen, team" → clears → repeat -->
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `transition` | 'fade' | 'fade', 'slide', or 'typewriter' |
+| `hold` | 2000 | Display time per item in ms |
+| `mode` | 'replace' | 'replace' or 'add' (accumulate) |
+| `separator` | ', ' | Separator in add mode |
+
+### `typewriter` — Phrase cycling with typing/deleting + sound
+```html
+<div ${typewriter(['Trustless', 'Permissionless', 'Transparent'])}>
+  <span class="typed"></span>
+</div>
+<div ${typewriter(['Fast', 'Typing'], { typeSpeed: 50, sound: true })}>
+  <span class="typed"></span>
+</div>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `typeSpeed` | 50 | Ms per character typed |
+| `deleteSpeed` | 30 | Ms per character deleted |
+| `pauseDuration` | 1500 | Pause after typing in ms |
+| `loop` | true | Loop through phrases |
+| `sound` | true | Web Audio typing sounds |
+| `cursor` | false | Show blinking cursor |
+
+---
+
+## Show/Hide (2 directives)
+
+### `reveal` — Spring-physics show/hide with zero layout shift
+```html
+<div ${reveal(this.isVisible)}>Content</div>
+<div ${reveal(this.isOpen, { preset: 'bouncy', maxHeight: '200px' })}>
+  Bouncy reveal
+</div>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `preset` | 'smooth' | smooth, snappy, bouncy, gentle |
+| `maxHeight` | '10rem' | Max height when revealed |
+
+Element stays in DOM (no layout shift). Uses Blackbird spring physics.
+
+### `intersect` — Simplified IntersectionObserver
+```html
+<!-- Fire once when visible (lazy load) -->
+<img ${intersect(() => this.loadImage(), { once: true })} />
+
+<!-- Enter/exit callbacks -->
+<video ${intersect({ onEnter: () => this.play(), onExit: () => this.pause() })}>
+```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `once` | false | Fire only once then disconnect |
+| `threshold` | 0 | Visibility threshold |
+| `rootMargin` | '0px' | Observer root margin |
+| `delay` | 0 | Delay before callback in ms |
+
+---
+
+## Interaction (3 directives)
+
+### `drag` & `drop` — HTML5 drag and drop with FLIP animations
+```html
+${repeat(items, item => item.id, item => html`
+  <div ${drag(item.id)} ${drop(item.id)} @drop=${this.handleReorder}>
+    ${item.name}
+  </div>
+`)}
+```
+
+### `color` — Dynamic background/text color
+```html
+<div ${color({ bgColor: '#ff0000', color: 'white' })}>Colored</div>
+```
+
+---
+
+## Reactive Utilities
+
+### `reducedMotion$` — Reactive reduced-motion preference
+```typescript
+import { reducedMotion$ } from '@mhmo91/schmancy/directives'
+
+if (reducedMotion$.value) return // skip animation
+
+// Or subscribe reactively
+reducedMotion$.subscribe(reduced => {
+  // User toggled reduced motion mid-session
+})
+```
+
+### `fromResizeObserver` — RxJS wrapper for ResizeObserver
+```typescript
+import { fromResizeObserver } from '@mhmo91/schmancy/directives'
+
+fromResizeObserver(element).pipe(
+  takeUntil(this.disconnecting)
+).subscribe(entries => {
+  const { width, height } = entries[0].contentRect
+})
+```
+
+---
+
+## Performance Notes
+
+- All physics directives respect `prefers-reduced-motion` reactively
+- `magnetic` and `cursorGlow` cache `getBoundingClientRect` on mouseenter (not per-frame)
+- `gravity` only animates once — parent re-renders don't re-trigger
+- `livingBorder` shares a single `<style>` element across all instances
+- `nebula` uses a singleton IntersectionObserver + pauses off-screen animations
+- All directives use `Subject` + `takeUntil` for subscription cleanup
+- All directives implement `reconnected()` for cache/conditional rendering survival

package/skills/schmancy/discovery.md

@@ -0,0 +1,67 @@
+# Schmancy Discovery
+
+> Event-based component and element discovery across shadow DOM boundaries. No DOM traversal — just broadcast and race.
+
+## Why
+Web components hide inside shadow DOM. Traversing with `querySelector` + `shadowRoot` everywhere is fragile. Discovery broadcasts a "where are you?" event; components respond with themselves.
+
+## API
+```typescript
+import {
+  discover,
+  discoverComponent,
+  discoverAnyComponent,
+  discoverElement,
+  discoverAllElements,
+} from '@mhmo91/schmancy'
+```
+
+### `discover(query, timeout?)`
+Smart auto-detect. Routes to `discoverElement` for CSS selectors (`#`, `.`, `[`) and `discoverComponent` for tag names.
+```typescript
+discover<SchmancyNavigationRail>('schmancy-navigation-rail').subscribe(el => el?.select('home'))
+discover('#hero-card').subscribe(el => el?.focus())
+```
+
+### `discoverComponent(tag, timeout = 100)`
+Broadcasts `{tag}-where-are-you`; first responder wins.
+```typescript
+discoverComponent<SchmancyDialog>('schmancy-dialog')
+  .subscribe(dialog => dialog?.open())
+```
+
+### `discoverAnyComponent(...tags)`
+Race between multiple tags — first to respond wins.
+```typescript
+discoverAnyComponent('schmancy-navigation-rail', 'schmancy-navigation-bar')
+  .subscribe(nav => nav?.select(route))
+```
+
+### `discoverElement(selector, timeout = 150)`
+Finds any element by CSS selector across shadow DOM. Uses a request ID + universal `schmancy-discover` event. Every `$LitElement` responds if it finds a match in its shadow root.
+```typescript
+discoverElement('[data-section="pricing"]').subscribe(section => section?.scrollIntoView())
+```
+
+### `discoverAllElements(selector, timeout = 150)`
+Collects **all** matching responses within the timeout window.
+```typescript
+discoverAllElements('.flagged').subscribe(all => console.log(all.length))
+```
+
+## How the Handshake Works
+1. Caller creates a unique `requestId` and broadcasts `schmancy-discover` on `window` with `{ selector, requestId }`.
+2. Every `$LitElement` listens for this event (wired up in the base class).
+3. Any matching element dispatches `schmancy-discover-response` with `{ requestId, element }`.
+4. Caller collects responses for the timeout window and emits via RxJS.
+
+## Pattern in Base Class
+Every `$LitElement` inherits auto-response: `discover<T>(tag)` (method on the component) and `{tagName}-where-are-you`/`{tagName}-here-i-am` events. See [mixins.md](./mixins.md).
+
+## When to Use
+- Cross-shadow coordination between unrelated components.
+- Imperatively focusing or driving a far-away UI piece from a handler.
+
+## When NOT to Use
+- Same-tree data flow — use `@provide`/`@consume` (Lit context) or Schmancy [`store`](./store.md).
+- Parent-to-child directly — just use `this.renderRoot.querySelector()`.

package/skills/schmancy/divider.md

@@ -0,0 +1,31 @@
+# schmancy-divider
+
+> Horizontal or vertical divider line with grow animation.
+
+## Usage
+```html
+<schmancy-divider></schmancy-divider>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| vertical | boolean | `false` | Vertical orientation (use inside flex/grid) |
+| outline | `'default'\|'variant'` | `'variant'` | Line color intensity |
+| grow | `'start'\|'end'\|'both'` | `'start'` | Animation origin direction |
+
+## Examples
+```html
+<!-- Horizontal divider -->
+<schmancy-divider></schmancy-divider>
+
+<!-- Vertical divider in a flex container -->
+<div class="flex items-stretch h-16">
+  <span>Left</span>
+  <schmancy-divider vertical></schmancy-divider>
+  <span>Right</span>
+</div>
+
+<!-- Grow from center -->
+<schmancy-divider grow="both"></schmancy-divider>
+```

package/skills/schmancy/dropdown.md

@@ -0,0 +1,47 @@
+# schmancy-dropdown
+
+> Floating dropdown with trigger slot and auto-positioned content portal.
+
+## Usage
+```html
+<schmancy-dropdown>
+  <schmancy-button slot="trigger">Open</schmancy-button>
+  <schmancy-dropdown-content>
+    <p>Dropdown content here</p>
+  </schmancy-dropdown-content>
+</schmancy-dropdown>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| open | boolean | `false` | Whether the dropdown is open |
+| placement | string | `'bottom-start'` | Floating UI placement |
+| distance | number | `8` | Offset distance in pixels |
+
+## Placement Values
+`top`, `top-start`, `top-end`, `right`, `right-start`, `right-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`
+
+## Methods
+| Method | Description |
+|--------|-------------|
+| toggle() | Toggle open/close state |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| trigger | Element that opens the dropdown on click |
+| default | Dropdown content |
+
+## Examples
+```html
+<!-- Right-aligned dropdown -->
+<schmancy-dropdown placement="bottom-end">
+  <schmancy-icon-button slot="trigger">more_vert</schmancy-icon-button>
+  <schmancy-dropdown-content>
+    <div class="p-4">Custom content</div>
+  </schmancy-dropdown-content>
+</schmancy-dropdown>
+```
+
+Content is teleported to a portal for proper z-index stacking. Closes on outside click or Escape key.

package/skills/schmancy/expand.md

@@ -0,0 +1,63 @@
+# schmancy-expand
+
+> Expandable/accordion component. Inline mode uses grid-template-rows transitions; portal mode teleports content to a body-level `schmancy-expand-root` with backdrop.
+
+## Usage
+```html
+<schmancy-expand summary="Details">
+  <p>Content appears when expanded.</p>
+</schmancy-expand>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `summary` | string | `''` | Summary text shown when collapsed |
+| `open` | boolean | `false` | Expansion state (reflected) |
+| `summary-padding` | string | — | CSS padding for the summary row |
+| `content-padding` | string | — | CSS padding for the body |
+| `hide-indicator` | boolean | `false` | Hide the chevron indicator |
+| `indicator-rotate` | number | `90` | Rotation angle (deg) when open |
+| `backdrop` | boolean | `true` | Show semi-transparent backdrop in portal mode |
+| `inline` | boolean | `false` | Inline expansion instead of portal (no backdrop) |
+
+## Slots
+| Slot | Purpose |
+|------|---------|
+| (default) | Expanded content |
+| `summary` | Custom summary markup (overrides `summary` property) |
+
+## Behavior
+- **Portal mode (default)**: on open, content is teleported into a body-anchored `schmancy-expand-root` with a backdrop. Click outside or press `Escape` to close.
+- **Inline mode** (`inline`): uses `grid-template-rows: 0fr → 1fr` transition inside the host — no portal, no backdrop.
+- `SPRING_SNAPPY` physics for indicator rotation.
+- Respects `prefers-reduced-motion`.
+- Broadcast event `SCHMANCY_EXPAND_REQUEST_CLOSE` on `window` closes whichever instance is currently open.
+
+## Example — inline accordion
+```html
+${repeat(this.faqs, faq => faq.id, faq => html`
+  <schmancy-expand inline .summary=${faq.question}>
+    <p>${faq.answer}</p>
+  </schmancy-expand>
+`)}
+```
+
+## Example — portal with custom summary slot
+```html
+<schmancy-expand>
+  <div slot="summary" class="flex items-center gap-2">
+    <schmancy-icon>info</schmancy-icon>
+    <schmancy-typography type="title">Advanced options</schmancy-typography>
+  </div>
+  <div class="p-4">
+    <!-- settings form -->
+  </div>
+</schmancy-expand>
+```
+
+## Programmatic Close
+```typescript
+import { SCHMANCY_EXPAND_REQUEST_CLOSE } from '@mhmo91/schmancy'
+window.dispatchEvent(new Event(SCHMANCY_EXPAND_REQUEST_CLOSE))
+```

package/skills/schmancy/extra.md

@@ -0,0 +1,59 @@
+# Schmancy Extra
+
+> Data-driven dropdowns for common localization fields. Country and timezone pickers, form-associated and autocomplete-backed.
+
+## schmancy-select-countries
+Fully autocomplete-searchable country dropdown. Form-associated (participates in `<form>` submission and validation via `ElementInternals`).
+
+```html
+<schmancy-select-countries
+  name="country"
+  label="Country"
+  placeholder="Select a country"
+  required
+  value="DE"
+  @change=${e => this.country = e.target.value}
+></schmancy-select-countries>
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | — | ISO country code (reflected) |
+| `name` | string | `''` | Form field name |
+| `label` | string | `'Country'` | Visible label |
+| `hint` | string | `'Please select a country'` | Helper text |
+| `placeholder` | string | `'Select a country'` | Placeholder in the input |
+| `required` | boolean | `false` | Validation constraint |
+
+## schmancy-select-timezones
+Same pattern as countries, backed by timezone data.
+
+```html
+<schmancy-select-timezones
+  name="timezone"
+  label="Timezone"
+  value="Europe/Berlin"
+></schmancy-select-timezones>
+```
+
+Accepts the same set of properties (`value`, `name`, `label`, `hint`, `placeholder`, `required`).
+
+## Raw Data Exports
+If you want the underlying data without the component:
+```typescript
+import countries from '@mhmo91/schmancy'   // default export from countries.data
+import timezones from '@mhmo91/schmancy'   // default export from timezones.data
+```
+
+Each countries row: `{ code, name, dialCode?, flag?, ... }`. Timezones: `{ name, offset, label, ... }`.
+
+## Form Integration
+Both use `formAssociated = true` and register with the parent `<form>`. Works with native `form.checkValidity()` and with [`schmancy-form`](./form.md).
+
+```html
+<schmancy-form @submit=${this.onSubmit}>
+  <schmancy-select-countries name="country" required></schmancy-select-countries>
+  <schmancy-select-timezones name="timezone" required></schmancy-select-timezones>
+  <schmancy-button type="submit" variant="filled">Save</schmancy-button>
+</schmancy-form>
+```

package/skills/schmancy/float.md

@@ -0,0 +1,14 @@
+# schmancy-float (deprecated alias)
+
+> Backward-compatibility alias for [`schmancy-window`](./window.md). Existing code keeps working — new code should use `schmancy-window` directly.
+
+## Migration
+```html
+<!-- Before -->
+<schmancy-float id="panel">…</schmancy-float>
+
+<!-- After -->
+<schmancy-window id="panel">…</schmancy-window>
+```
+
+All properties are identical. See [window.md](./window.md) for full API.

package/skills/schmancy/form.md

@@ -0,0 +1,49 @@
+# schmancy-form
+
+> Form container that collects data from child controls, validates, and emits submit/reset events.
+
+## Usage
+```html
+<schmancy-form @submit=${(e) => handleSubmit(e.detail)}>
+  <schmancy-input name="email" label="Email" required></schmancy-input>
+  <schmancy-button type="submit">Submit</schmancy-button>
+</schmancy-form>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| novalidate | boolean | `false` | Skip validation on submit |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| submit | FormData | Form data from all child controls |
+| reset | - | When the form is reset |
+
+## Methods
+| Method | Returns | Description |
+|--------|---------|-------------|
+| submit() | boolean | Validates and dispatches submit event. Returns false if invalid. |
+| reset() | void | Resets all child controls to default values |
+| getFormData() | FormData | Collects current form data without submitting |
+| reportValidity() | boolean | Checks and shows validation on all controls |
+
+## Examples
+```html
+<!-- Form with validation -->
+<schmancy-form @submit=${(e) => save(e.detail)} @reset=${() => clearForm()}>
+  <schmancy-input name="name" label="Name" required></schmancy-input>
+  <schmancy-select name="role" label="Role" required>
+    <schmancy-option value="admin" label="Admin"></schmancy-option>
+    <schmancy-option value="user" label="User"></schmancy-option>
+  </schmancy-select>
+  <schmancy-checkbox name="active" label="Active"></schmancy-checkbox>
+  <div class="flex gap-2">
+    <schmancy-button type="submit">Save</schmancy-button>
+    <schmancy-button type="reset">Reset</schmancy-button>
+  </div>
+</schmancy-form>
+```
+
+Submit triggers on Enter key in inputs or clicking a submit-type button.

package/skills/schmancy/icons.md

@@ -0,0 +1,44 @@
+# schmancy-icon
+
+> Material Symbols icon with configurable fill, weight, grade, variant, and size tokens.
+
+## Usage
+```html
+<schmancy-icon>settings</schmancy-icon>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| icon | string | `undefined` | Icon name (alternative to slot content, translation-safe) |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'\|string` | `'md'` | Icon size (12/16/20/24/32px or custom) |
+| fill | number (0-1) | `0` | Fill level (0=outlined, 1=filled) |
+| weight | number (100-700) | `400` | Stroke thickness |
+| grade | number (-50 to 200) | `0` | Visual weight adjustment |
+| variant | `'outlined'\|'rounded'\|'sharp'` | `'outlined'` | Icon style variant |
+
+## Size Tokens
+| Token | Size | Optical Size | Best For |
+|-------|------|-------------|----------|
+| xxs | 12px | 20 | Ultra-compact UIs |
+| xs | 16px | 20 | 32px buttons |
+| sm | 20px | 20 | 40px buttons |
+| md | 24px | 24 | Default (48px buttons) |
+| lg | 32px | 40 | 56px buttons |
+
+## Examples
+```html
+<!-- Filled icon -->
+<schmancy-icon .fill=${1}>favorite</schmancy-icon>
+
+<!-- Large rounded icon -->
+<schmancy-icon size="lg" variant="rounded">home</schmancy-icon>
+
+<!-- Custom size -->
+<schmancy-icon size="48px" .weight=${300}>search</schmancy-icon>
+
+<!-- Translation-safe (use icon property instead of slot) -->
+<schmancy-icon icon="delete"></schmancy-icon>
+```
+
+Auto-loads Google Fonts on first use. Translation-protected via `translate="no"` and `notranslate` class.