@3fn/core 14.1.0 → 15.0.0

package/dist/consumer-canonical/skills/impeccable/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: impeccable-dp
+description: Design creation and critique skill adapted for DesignerPunk. Uses MCP queries for context instead of static files. Covers interface design, visual direction, critique, audit, polish, and all Impeccable commands filtered through DesignerPunk's token system and design philosophy.
+version: 1.1.0
+upstream-merge: Impeccable v3.5.0 (2026-06-01)
+license: Apache 2.0. Adapted from Impeccable by Paul Bakaus (Apache 2.0). See NOTICE.md for attribution.
+---
+
+Designs and iterates production-grade frontend interfaces using DesignerPunk's design language. Real working code, committed design choices, exceptional craft — filtered through DesignerPunk's mathematical token system and behavioral contracts.
+
+## Setup
+
+Before any design work:
+1. Load design philosophy context via MCP queries (see Context Loading below).
+2. Identify the register (brand or product) from Product MCP.
+3. Load the matching register reference (`brand-dp.md` or `product-dp.md`).
+4. If a specific command is invoked (e.g., `craft`, `shape`, `audit`), load its reference file.
+
+### Context Loading (replaces load-context.mjs)
+
+Query DesignerPunk's MCP infrastructure for design context:
+
+```
+1. Application MCP: get_design_philosophy()    → north star, description, characteristics
+2. Application MCP: get_design_rules()         → named constraints with rationale
+3. Application MCP: get_design_guidance()      → categorized do's and don'ts
+4. Application MCP: get_color_strategy()       → four-tier color vocabulary
+5. Product MCP: get_product_overview()         → register, platforms, description
+6. Product MCP: get_brand_context()            → personality, voice, anti-references (if configured)
+```
+
+If Application MCP is unavailable: proceed with token-only guidance. Note limitation.
+If design philosophy is not authored: proceed with DesignerPunk token semantics and component contracts. Note limitation.
+If brand context is not configured: use register defaults from the register reference file.
+
+### Register
+
+Every design task is **brand** (marketing, landing, portfolio, presentation: design IS the product) or **product** (app UI, dashboard, settings, tool: design SERVES the product).
+
+Determine from Product MCP's `get_product_overview()` register field. If not set, infer from the surface being designed:
+- Brand signals: `/`, `/about`, hero sections, marketing content, presentations
+- Product signals: `/app/*`, `/dashboard`, `/settings`, forms, data tables, authenticated surfaces
+
+Load the matching reference: `reference/brand-dp.md` or `reference/product-dp.md`.
+
+## DesignerPunk Design Laws
+
+These override Impeccable's shared design laws where they conflict:
+
+### Spacing
+- **8px baseline grid** for layout (NOT 4pt). Typography on 4px sub-grid. All elements cumulatively align to multiples of 8.
+- Use semantic spacing tokens: `space.grouped.*`, `space.related.*`, `space.separated.*`, `space.sectioned.*`, `space.inset.*`
+- `space075` (6) and `space125` (10) are valid for typographic alignment.
+
+### Color
+- Use DesignerPunk's semantic color tokens (`color.action.primary`, `color.feedback.error.*`, etc.)
+- Semantic roles: cyan=action, purple=tech/data, pink=error, yellow=attention, green=success, orange=warning, teal=info
+- Glow effects for surface layering with complementary color pairings
+- Mode-neutral: both light and dark must feel intentionally DesignerPunk
+
+### Typography
+- **Rajdhani** (display/headings), **Figtree** (body/UI), **Commit Mono** (code/data/tokens)
+- Do NOT apply Impeccable's font selection procedure or reflex-reject list. Fonts are system-defined.
+- Weight contrast for hierarchy within families, not font switching.
+- Cap body at 65-75ch.
+
+### Motion
+- Expo-out on web/Android. Spring physics on iOS.
+- No bounce. No elastic on web/Android. (iOS spring is the exception.)
+- `prefers-reduced-motion` on everything.
+
+### Elevation
+- Surface lightness progression for depth (not shadow intensity)
+- Shadows tinted toward blue or gray (warm-light-cool-shadow principle)
+- Glow effects for accent emphasis (same-hue glow, complementary pairings)
+
+### Absolute Bans
+
+Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
+
+- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
+- **Gradient text.** `background-clip: text` combined with a gradient background. Use a single solid color. Emphasis via weight or size.
+- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
+- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché.
+- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly.
+- **Modal as first thought.** Modals are interruptions. Use inline expansion, drawers, or navigation first.
+- **The cream / sand / beige body background.** The whole warm-neutral band (OKLCH L 0.84–0.97, C < 0.06, hue 40–100) reads as cream/sand/paper/parchment regardless of what you call it. Token names like `--paper`, `--cream`, `--sand`, `--bone`, `--flour`, `--linen`, `--parchment`, `--wheat`, `--biscuit`, `--ivory` are tells in themselves. If the brief says "warm" or "editorial," DO NOT translate that into a near-white warm-tinted bg. Pick: (a) a saturated brand color as the body, (b) a true off-white at chroma 0 (or chroma toward the brand's own hue, not toward warmth-by-default), or (c) a darker mid-tone tinted neutral that's clearly the brand's own. "Warmth" is carried by accent + typography + imagery, not by body bg.
+- **Numbered section markers as default scaffolding (01 / 02 / 03).** Putting `01 · About / 02 · Process / 03 · Pricing` above every section is the eyebrow trope one tier deeper. Numbers earn their place when the section actually IS a sequence (a real process, an ordered flow, a typed timeline) and the order carries information the reader needs. One deliberate numbered sequence on one page is voice; numbered eyebrows on every section across the site is AI grammar.
+- **Text that overflows its container.** Long heading words plus large clamp scales plus narrow grids cause headline overflow on tablet/mobile. Test the heading copy at every breakpoint; if it overflows, reduce the clamp max or rewrite the copy. The viewport is part of the design.
+- **Tiny uppercase tracked eyebrow above every section.** The 2023-era kicker (small all-caps text with wide tracking, "ABOUT" "PROCESS" "PRICING" above each heading) is the saturated AI scaffold; it appears on 55–95% of generations regardless of brief, which is the definition of a tell. One named kicker as a deliberate brand system is voice; an eyebrow on every section is AI grammar. Frequency is the detector: if more than one section on the page has an eyebrow, you're scaffolding by reflex.
+
+### Conflict Resolution
+
+When Impeccable's domain references conflict with DesignerPunk:
+```
+Priority 1: DesignerPunk token values
+Priority 2: DesignerPunk named design rules
+Priority 3: DesignerPunk behavioral contracts
+Priority 4: Impeccable domain knowledge (universal principles)
+Priority 5: Impeccable taste opinions (where DP is silent)
+```
+
+Note conflicts in output: `[CONFLICT] Impeccable recommends X. DesignerPunk uses Y. → Applying DesignerPunk (Priority N).`
+
+## Design guidance
+
+Produce ready-to-ship, production-grade code, not prototypes or starting points. Take no shortcuts unless the user asks for them (when in doubt, ask). Don't stop until arriving at a complete implementation (beautiful, responsive, fast, precise, bug-free, on brand). Take attention to detail seriously: every page, section or component crafted is battle tested.
+
+### General rules
+
+#### Color
+
+- **Verify contrast.** Body text must hit ≥4.5:1 against its background; large text (≥18px or bold ≥14px) needs ≥3:1. Placeholder text needs the same 4.5:1, not the muted-gray default. The most common failure: muted gray body text on a tinted near-white. If the contrast is even close, bump the body color toward the ink end of the ramp; light gray "for elegance" is the single biggest reason AI designs feel hard to read.
+- Gray text on a colored background looks washed out. Use a darker shade of the background's own hue, or a transparency of the text color.
+
+#### Typography
+
+- Hero / display heading ceiling: clamp() max ≤ 6rem (~96px). Above that the page is shouting, not designing.
+- Display heading letter-spacing floor: ≥ -0.04em. Anything tighter and letters touch; cramped, not "designed".
+- Use `text-wrap: balance` on h1–h3 for even line lengths; `text-wrap: pretty` on long prose to reduce orphans.
+- Cap font-family count at 3 (display + body + optional mono). More than 3 reads as indecision, not richness. One well-tuned family with weight contrast usually beats three competing typefaces.
+- Don't pair fonts that are similar but not identical (two geometric sans-serifs, two humanist sans-serifs). Pair on a contrast axis (serif + sans, geometric + humanist) or use one family in multiple weights.
+- No all-caps body copy. Reserve uppercase for short labels (≤4 words), section eyebrows (used sparingly per the Absolute bans), and badges. Sentences in ALL CAPS are unreadable at body sizes.
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
+
+#### Layout
+
+- Vary spacing for rhythm.
+- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
+- Build a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip). Never arbitrary values like 999 or 9999.
+
+#### Motion
+
+- Staggering the items within one list is legitimate. The tell is the uniform reflex (one identical entrance applied to every section), not motion itself; each reveal should fit what it reveals. Suppressing the reflex is never a reason to ship a page with no motion at all.
+- Reveal animations must enhance an already-visible default. Don't gate content visibility on a class-triggered transition; transitions pause on hidden tabs and headless renderers, so the reveal never fires and the section ships blank.
+- Premium motion materials are not just transform/opacity. Blur, backdrop-filter, clip-path, mask, and shadow/glow are part of the palette when they materially improve the effect and stay smooth.
+
+#### Interaction
+
+- Dropdowns rendered with `position: absolute` inside an `overflow: hidden` or `overflow: auto` container will be clipped. Use the native `<dialog>` / popover API, `position: fixed`, or a portal to escape the stacking context.
+
+### Copy
+
+- Every word earns its place. No restated headings, no intros that repeat the title.
+- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
+- **No aphoristic-cadence body copy as a default voice.** Don't fall into the rhythm of "serious statement, then punchy short negation" as the page's recurring voice. If three or more section copy blocks on the page land on a short rebuttal-shaped sentence, rewrite. Specific, not aphoristic.
+- **No marketing buzzwords.** The streamline / empower / supercharge / leverage / unleash / transform / seamless / world-class / enterprise-grade / next-generation / cutting-edge / game-changer / mission-critical family of phrases. Pick a specific noun and a verb that describes what the product literally does.
+- Button labels: verb + object. "Save changes" beats "OK"; "Delete project" beats "Yes". The label should say what will happen.
+- Link text needs standalone meaning. "View pricing plans" beats "Click here"; screen readers announce links out of context.
+
+### The AI slop test
+
+If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the Absolute Bans above. Register-specific failures live in each register reference.
+
+**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette from the category alone, it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's reflex-reject aesthetic lanes (in `reference/brand-dp.md`) list catches the currently-saturated families.
+
+### New projects only (brand register)
+
+When no prior design system or committed brand colors exist:
+
+#### Color strategy vocabulary
+
+Pick a **color strategy** before picking colors. Four steps on the commitment axis:
+
+- **Restrained**: tinted neutrals + one accent ≤10%. Product register default; brand minimalism.
+- **Committed**: one saturated color carries 30–60% of the surface. Brand register default for identity-driven pages.
+- **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+- **Drenched**: the surface IS the color. Brand heroes, campaign pages. Break-Glass Rule applies.
+
+This vocabulary is queryable via `get_color_strategy()` from the Application MCP.
+
+## Commands
+
+All commands from Impeccable are available, adapted for DesignerPunk context:
+
+| Command | Category | Description | Reference |
+|---------|----------|-------------|-----------|
+| `craft` | Build | Shape, then build end-to-end | reference/craft.md |
+| `shape` | Build | Plan UX/UI before code | reference/shape.md |
+| `extract` | Build | Pull reusable tokens/components (governance-aware) | reference/extract-dp.md |
+| `critique` | Evaluate | UX design review | reference/critique.md |
+| `audit` | Evaluate | Technical quality checks | reference/audit.md |
+| `polish` | Refine | Final quality pass | reference/polish.md |
+| `bolder` | Refine | Amplify safe designs | reference/bolder.md |
+| `quieter` | Refine | Tone down aggressive designs | reference/quieter.md |
+| `distill` | Refine | Strip to essence | reference/distill.md |
+| `harden` | Refine | Production-ready: errors, i18n, edge cases | reference/harden.md |
+| `onboard` | Refine | First-run flows, empty states | reference/onboard.md |
+| `animate` | Enhance | Add purposeful motion | reference/animate.md |
+| `colorize` | Enhance | Add strategic color | reference/colorize.md |
+| `typeset` | Enhance | Improve typography | reference/typeset.md |
+| `layout` | Enhance | Fix spacing and hierarchy | reference/layout.md |
+| `delight` | Enhance | Add personality | reference/delight.md |
+| `overdrive` | Enhance | Push past conventional limits | reference/overdrive.md |
+| `clarify` | Fix | Improve UX copy | reference/clarify.md |
+| `adapt` | Fix | Adapt for different devices | reference/adapt.md |
+| `optimize` | Fix | Performance improvements | reference/optimize.md |
+| `live` | Iterate | Visual variant mode in browser | reference/live.md |
+
+**Excluded commands:** `teach` and `document` (replaced by MCP authoring workflow).
+
+### Routing Rules
+
+1. **No argument**: Make the recommendation context-aware instead of showing a static menu. Gather signals, then lead with 2–3 highest-value commands with a one-line rationale each, followed by the full command table as fallback. **Never auto-run a command; the recommendation is a suggestion the user confirms.**
+
+   **Signal gathering** (run once, in parallel where possible):
+   - `get_product_overview()` → register, platforms, product status
+   - `find_screens({ status: "in-progress" })` → active work surfaces
+   - `find_screens({ status: "blocked" })` → blocked work
+   - `git status` (shell) → dirty files, recent changes
+
+   **Reasoning heuristics** (no score to obey; reason over the signals):
+   - Active in-progress screens with no prior critique → `critique` scoped to that surface.
+   - `git status` shows changed markup/style files → `audit` or `polish` scoped to those files specifically, naming them.
+   - Product has screens but no design philosophy authored → `shape` to establish visual direction.
+   - Brand register surface with no committed color strategy → `colorize` or `craft` with color strategy as focus.
+   - Recent implementation work complete → `polish` for final quality pass.
+   - No clear signal from any source → fall back to the full command table grouped by category. Ask what to do.
+
+   Keep it to 2–3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
+
+2. **First word matches a command**: Load its reference file and follow instructions. Everything after the command name is the target.
+3. **First word doesn't match, but intent clearly maps to one command** (e.g., "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
+4. **No clear command match**: General design invocation. Apply setup, DesignerPunk design laws, register reference, and the full argument as context.
+
+## DesignerPunk-Specific Additions
+
+Beyond Impeccable's standard flow, always:
+- Validate component composition via `validate_assembly()` and `check_composition()`
+- Select components via `find_components()` and `get_prop_guidance()`
+- Reference behavioral contracts for state coverage (not just a checklist)
+- Declare color strategy tier for every surface
+- Check named design rules as constraints during implementation
+- Run anti-slop checks (first-order and second-order category-reflex)

package/dist/consumer-canonical/skills/impeccable/detector-exclusions.md

@@ -0,0 +1,42 @@
+# Detector Exclusions
+
+**Purpose**: Rules to exclude when running the Impeccable detector in DesignerPunk context.
+**Mechanism**: Pass excluded rule IDs via `--exclude` flag or filter from JSON output post-hoc.
+
+---
+
+## Excluded Rules
+
+None currently excluded. Add rules here when an upstream detector rule conflicts with an intentional DesignerPunk pattern.
+
+### Format
+
+```
+| Rule ID | Reason for Exclusion | Date Added |
+|---------|---------------------|------------|
+| example-rule-id | Conflicts with DesignerPunk pattern X | 2026-06-01 |
+```
+
+---
+
+## How to Exclude
+
+The detector does not currently support a `--exclude` flag natively. Until upstream adds one, exclusions are applied by filtering JSON output:
+
+```bash
+# Run detector in JSON mode
+node .kiro/skills/impeccable/scripts/detect.mjs --json <target>
+
+# Filter excluded rules (example with jq)
+node .kiro/skills/impeccable/scripts/detect.mjs --json <target> | jq '[.[] | select(.antipattern != "excluded-rule-id")]'
+```
+
+When invoking the detector during `audit`, Leonardo filters findings against this exclusion list before reporting results.
+
+---
+
+## Governance
+
+- **Adding exclusions**: Requires rationale explaining why the DesignerPunk pattern is intentional
+- **Removing exclusions**: When upstream updates a rule to accommodate our pattern, remove the exclusion
+- **Wholesale replacement**: When updating `scripts/detector/` from upstream, this exclusion list is preserved (it lives outside the detector directory)

package/dist/consumer-canonical/skills/impeccable/reference/adapt.md

@@ -0,0 +1,190 @@
+> **Additional context needed**: target platforms/devices and usage contexts.
+
+Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
+
+
+---
+
+## Assess Adaptation Challenge
+
+Understand what needs adaptation and why:
+
+1. **Identify the source context**:
+   - What was it designed for originally? (Desktop web? Mobile app?)
+   - What assumptions were made? (Large screen? Mouse input? Fast connection?)
+   - What works well in current context?
+
+2. **Understand target context**:
+   - **Device**: Mobile, tablet, desktop, TV, watch, print?
+   - **Input method**: Touch, mouse, keyboard, voice, gamepad?
+   - **Screen constraints**: Size, resolution, orientation?
+   - **Connection**: Fast wifi, slow 3G, offline?
+   - **Usage context**: On-the-go vs desk, quick glance vs focused reading?
+   - **User expectations**: What do users expect on this platform?
+
+3. **Identify adaptation challenges**:
+   - What won't fit? (Content, navigation, features)
+   - What won't work? (Hover states on touch, tiny touch targets)
+   - What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
+
+**CRITICAL**: Adaptation is rethinking the experience for the new context, not scaling pixels.
+
+## Plan Adaptation Strategy
+
+Create context-appropriate strategy:
+
+### Mobile Adaptation (Desktop → Mobile)
+
+**Layout Strategy**:
+- Single column instead of multi-column
+- Vertical stacking instead of side-by-side
+- Full-width components instead of fixed widths
+- Bottom navigation instead of top/side navigation
+
+**Interaction Strategy**:
+- Touch targets 44x44px minimum (not hover-dependent)
+- Swipe gestures where appropriate (lists, carousels)
+- Bottom sheets instead of dropdowns
+- Thumbs-first design (controls within thumb reach)
+- Larger tap areas with more spacing
+
+**Content Strategy**:
+- Progressive disclosure (don't show everything at once)
+- Prioritize primary content (secondary content in tabs/accordions)
+- Shorter text (more concise)
+- Larger text (16px minimum)
+
+**Navigation Strategy**:
+- Hamburger menu or bottom navigation
+- Reduce navigation complexity
+- Sticky headers for context
+- Back button in navigation flow
+
+### Tablet Adaptation (Hybrid Approach)
+
+**Layout Strategy**:
+- Two-column layouts (not single or three-column)
+- Side panels for secondary content
+- Master-detail views (list + detail)
+- Adaptive based on orientation (portrait vs landscape)
+
+**Interaction Strategy**:
+- Support both touch and pointer
+- Touch targets 44x44px but allow denser layouts than phone
+- Side navigation drawers
+- Multi-column forms where appropriate
+
+### Desktop Adaptation (Mobile → Desktop)
+
+**Layout Strategy**:
+- Multi-column layouts (use horizontal space)
+- Side navigation always visible
+- Multiple information panels simultaneously
+- Fixed widths with max-width constraints (don't stretch to 4K)
+
+**Interaction Strategy**:
+- Hover states for additional information
+- Keyboard shortcuts
+- Right-click context menus
+- Drag and drop where helpful
+- Multi-select with Shift/Cmd
+
+**Content Strategy**:
+- Show more information upfront (less progressive disclosure)
+- Data tables with many columns
+- Richer visualizations
+- More detailed descriptions
+
+### Print Adaptation (Screen → Print)
+
+**Layout Strategy**:
+- Page breaks at logical points
+- Remove navigation, footer, interactive elements
+- Black and white (or limited color)
+- Proper margins for binding
+
+**Content Strategy**:
+- Expand shortened content (show full URLs, hidden sections)
+- Add page numbers, headers, footers
+- Include metadata (print date, page title)
+- Convert charts to print-friendly versions
+
+### Email Adaptation (Web → Email)
+
+**Layout Strategy**:
+- Narrow width (600px max)
+- Single column only
+- Inline CSS (no external stylesheets)
+- Table-based layouts (for email client compatibility)
+
+**Interaction Strategy**:
+- Large, obvious CTAs (buttons not text links)
+- No hover states (not reliable)
+- Deep links to web app for complex interactions
+
+## Implement Adaptations
+
+Apply changes systematically:
+
+### Responsive Breakpoints
+
+Choose appropriate breakpoints:
+- Mobile: 320px-767px
+- Tablet: 768px-1023px
+- Desktop: 1024px+
+- Or content-driven breakpoints (where design breaks)
+
+### Layout Adaptation Techniques
+
+- **CSS Grid/Flexbox**: Reflow layouts automatically
+- **Container Queries**: Adapt based on container, not viewport
+- **`clamp()`**: Fluid sizing between min and max
+- **Media queries**: Different styles for different contexts
+- **Display properties**: Show/hide elements per context
+
+### Touch Adaptation
+
+- Increase touch target sizes (44x44px minimum)
+- Add more spacing between interactive elements
+- Remove hover-dependent interactions
+- Add touch feedback (ripples, highlights)
+- Consider thumb zones (easier to reach bottom than top)
+
+### Content Adaptation
+
+- Use `display: none` sparingly (still downloads)
+- Progressive enhancement (core content first, enhancements on larger screens)
+- Lazy loading for off-screen content
+- Responsive images (`srcset`, `picture` element)
+
+### Navigation Adaptation
+
+- Transform complex nav to hamburger/drawer on mobile
+- Bottom nav bar for mobile apps
+- Persistent side navigation on desktop
+- Breadcrumbs on smaller screens for context
+
+**IMPORTANT**: Test on real devices. Device emulation in DevTools is helpful but not perfect.
+
+**NEVER**:
+- Hide core functionality on mobile (if it matters, make it work)
+- Assume desktop = powerful device (consider accessibility, older machines)
+- Use different information architecture across contexts (confusing)
+- Break user expectations for platform (mobile users expect mobile patterns)
+- Forget landscape orientation on mobile/tablet
+- Use generic breakpoints blindly (use content-driven breakpoints)
+- Ignore touch on desktop (many desktop devices have touch)
+
+## Verify Adaptations
+
+Test thoroughly across contexts:
+
+- **Real devices**: Test on actual phones, tablets, desktops
+- **Different orientations**: Portrait and landscape
+- **Different browsers**: Safari, Chrome, Firefox, Edge
+- **Different OS**: iOS, Android, Windows, macOS
+- **Different input methods**: Touch, mouse, keyboard
+- **Edge cases**: Very small screens (320px), very large screens (4K)
+- **Slow connections**: Test on throttled network
+
+When the adaptation feels native to each context, hand off to `/impeccable polish` for the final pass.

package/dist/consumer-canonical/skills/impeccable/reference/animate.md

@@ -0,0 +1,194 @@
+> **Additional context needed**: performance constraints.
+
+Add motion that conveys state, gives feedback, and clarifies hierarchy. Cut motion that exists only for decoration. Animation fatigue is a real cost; spend the budget on the moments that need it.
+
+---
+
+## Register
+
+Brand: motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions. The saturated AI default is fade-and-rise reveals on every scrolled section; that's a tell, not a choreography. Reserve scroll-triggered motion for moments that earn it.
+
+Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
+
+---
+
+## Assess Animation Opportunities
+
+Analyze where motion would improve the experience:
+
+1. **Identify static areas**:
+   - **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.)
+   - **Jarring transitions**: Instant state changes that feel abrupt (show/hide, page loads, route changes)
+   - **Unclear relationships**: Spatial or hierarchical relationships that aren't obvious
+   - **Lack of delight**: Functional but joyless interactions
+   - **Missed guidance**: Opportunities to direct attention or explain behavior
+
+2. **Understand the context**:
+   - What's the personality? (Playful vs serious, energetic vs calm)
+   - What's the performance budget? (Mobile-first? Complex page?)
+   - Who's the audience? (Motion-sensitive users? Power users who want speed?)
+   - What matters most? (One hero animation vs many micro-interactions?)
+
+If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+
+**CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
+
+## Plan Animation Strategy
+
+Create a purposeful animation plan:
+
+- **Hero moment**: What's the ONE signature animation? (Page load? Hero section? Key interaction?)
+- **Feedback layer**: Which interactions need acknowledgment?
+- **Transition layer**: Which state changes need smoothing?
+- **Delight layer**: Where can we surprise and delight?
+
+**IMPORTANT**: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments.
+
+## Implement Animations
+
+Add motion systematically across these categories:
+
+### Entrance Animations
+- **List rhythm**: Sibling stagger is legitimate for cards-in-a-grid or list-items-appearing. Whole-section fade-on-scroll is not a list and is not legitimate. Cap total stagger time: 10 items at 50ms each = 500ms total. For more items, reduce per-item delay or cap the staggered count.
+  Use CSS custom properties for clean stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"`, `style="--i: 1"`, etc. on each item.
+- **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
+- **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management
+
+### Micro-interactions
+- **Button feedback**:
+  - Hover: Subtle scale (1.02-1.05), color shift, shadow increase
+  - Click: Quick scale down then up (0.95 → 1), ripple effect
+  - Loading: Spinner or pulse state
+- **Form interactions**:
+  - Input focus: Border color transition, slight scale or glow
+  - Validation: Shake on error, check mark on success, smooth color transitions
+- **Toggle switches**: Smooth slide + color transition (200-300ms)
+- **Checkboxes/radio**: Check mark animation, ripple effect
+- **Like/favorite**: Scale + rotation, particle effects, color transition
+
+### State Transitions
+- **Show/hide**: Fade + slide (not instant), appropriate timing (200-300ms)
+- **Expand/collapse**: Height transition with overflow handling, icon rotation
+- **Loading states**: Skeleton screen fades, spinner animations, progress bars
+- **Success/error**: Color transitions, icon animations, gentle scale pulse
+- **Enable/disable**: Opacity transitions, cursor changes
+
+### Navigation & Flow
+- **Page transitions**: Crossfade between routes, shared element transitions
+- **Tab switching**: Slide indicator, content fade/slide
+- **Carousel/slider**: Smooth transforms, snap points, momentum
+- **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators
+
+### Feedback & Guidance
+- **Hover hints**: Tooltip fade-ins, cursor changes, element highlights
+- **Drag & drop**: Lift effect (shadow + scale), drop zone highlights, smooth repositioning
+- **Copy/paste**: Brief highlight flash on paste, "copied" confirmation
+- **Focus flow**: Highlight path through form or workflow
+
+### Delight Moments
+- **Empty states**: Subtle floating animations on illustrations
+- **Completed actions**: Confetti, check mark flourish, success celebrations
+- **Easter eggs**: Hidden interactions for discovery
+- **Contextual animation**: Weather effects, time-of-day themes, seasonal touches
+
+## Technical Implementation
+
+Use appropriate techniques for each animation:
+
+### Timing & Easing
+
+**Duration: the 100/300/500 rule.** Timing matters more than easing for "feels right":
+
+| Duration | Use Case | Examples |
+|----------|----------|----------|
+| **100–150ms** | Instant feedback | Button press, toggle, color change |
+| **200–300ms** | State changes | Menu open, tooltip, hover state |
+| **300–500ms** | Layout changes | Accordion, modal, drawer |
+| **500–800ms** | Entrance animations | Page load, hero reveal |
+
+**Easing curves (use these, not CSS defaults):**
+```css
+/* Recommended: natural deceleration */
+--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth */
+--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
+--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */
+
+/* AVOID: feel dated and tacky */
+/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
+/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */
+```
+
+**Exit animations are faster than entrances.** Use ~75% of enter duration.
+
+### CSS Animations
+```css
+/* Prefer for simple, declarative animations */
+- transitions for state changes
+- @keyframes for complex sequences
+- transform and opacity for reliable movement
+- blur, filters, masks, clip paths, shadows, and color shifts for premium atmospheric effects when verified smooth
+```
+
+### JavaScript Animation
+```javascript
+/* Use for complex, interactive animations */
+- Web Animations API for programmatic control
+- Framer Motion for React
+- GSAP for complex sequences
+```
+
+### Performance
+- **Motion materials**: Transform and opacity are reliable defaults, not the whole palette. Match material to effect:
+  - Transform / opacity: movement, press feedback, simple reveals, list choreography
+  - Blur / filter / backdrop-filter: focus pulls, depth, glass or lens effects, softened entrances
+  - Clip-path / masks: wipes, reveals, editorial cropping, product-like transitions
+  - Shadow / glow / color filters: energy, affordance, focus, warmth, active state
+  - Grid-template-rows or FLIP-style transforms: expanding and reflowing layout without animating `height` directly
+- **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
+- **will-change**: Add sparingly for known expensive animations only (e.g. on `:hover` or an `.animating` class), never preemptively across the whole page
+- **Scroll triggers**: Use Intersection Observer instead of scroll event listeners; unobserve after the animation fires once
+- **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
+- **Monitor FPS**: Ensure 60fps on target devices
+
+### Accessibility
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+**NEVER**:
+- Use bounce or elastic easing curves; they feel dated and draw attention to the animation itself
+- Animate layout properties casually (`width`, `height`, `top`, `left`, margins) when transform, FLIP, or grid-based techniques would work
+- Use durations over 500ms for feedback (it feels laggy)
+- Animate without purpose (every animation needs a reason)
+- Ignore `prefers-reduced-motion` (this is an accessibility violation)
+- Animate everything (animation fatigue makes interfaces feel exhausting)
+- Block interaction during animations unless intentional
+
+## Verify Quality
+
+Test animations thoroughly:
+
+- **Smooth at 60fps**: No jank on target devices
+- **Feels natural**: Easing curves feel organic, not robotic
+- **Appropriate timing**: Not too fast (jarring) or too slow (laggy)
+- **Reduced motion works**: Animations disabled or simplified appropriately
+- **Doesn't block**: Users can interact during/after animations
+- **Adds value**: Makes interface clearer or more delightful
+
+When the motion clarifies state instead of decorating it, hand off to `/impeccable polish` for the final pass.
+
+### Perceived Performance
+
+Nobody cares how fast your site *is*, only how fast it feels. The 80ms threshold: anything under ~80ms feels instant because our brains buffer sensory input for that long to synchronize perception. Target this for micro-interactions.
+
+- **Preemptive start**: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening.
+- **Early completion**: Show content progressively, don't wait for everything (progressive images, streaming HTML, skeleton fade-ins).
+- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Use for low-stakes actions (likes, follows). Avoid for payments or destructive operations.
+- **Easing affects perceived duration**: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily. Ease-out feels satisfying for entrances.
+- **Caution**: Too-fast responses can decrease perceived value for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening.