wizz-method 1.4.0 → 1.5.0

package/src/skills-lib/taste-skill/references/design-systems.md

@@ -0,0 +1,267 @@
+> taste-skill reference file. Loaded on demand from the SKILL.md index.
+> Cross-references like "Section N" map to sibling files via the index table in ../SKILL.md.
+
+## 2. BRIEF → DESIGN SYSTEM MAP
+
+Once you have the design read (Section 0) and dials (Section 1), pick the right foundation. Do not invent CSS for things that have an official package. Do not pretend an aesthetic trend is an official system.
+
+### 2.A When to reach for a real design system (use official packages)
+| Brief reads as… | Reach for | Why |
+|---|---|---|
+| Microsoft / enterprise SaaS / dashboards | `@fluentui/react-components` or `@fluentui/web-components` | Official Fluent UI, Microsoft tokens, accessibility done |
+| Google-ish UI, Material-flavored product | `@material/web` + Material 3 tokens | Official, theme-able via Material Theming |
+| IBM-style B2B / enterprise analytics | `@carbon/react` + `@carbon/styles` | Official Carbon, mature data-density patterns |
+| Shopify app surfaces | `polaris.js` web components / Polaris React | Required for Shopify admin UI |
+| Atlassian / Jira-style product | `@atlaskit/*` + `@atlaskit/tokens` | Official Atlassian DS |
+| GitHub-style devtool / community page | `@primer/css` or `@primer/react-brand` | Official Primer; Brand variant for marketing |
+| Public-sector UK service | `govuk-frontend` | Legally / regulatorily expected |
+| US public-sector / trust-first | `uswds` | Same |
+| Fast local-business / agency MVP | Bootstrap 5.3 | Boring, fast, works |
+| Modern accessible React foundation | `@radix-ui/themes` | Primitives + polished theme |
+| Modern SaaS where you own the components | shadcn/ui (`npx shadcn@latest add ...`) | You own the code, easy to customise; never ship default state |
+| Tailwind-based modern SaaS / AI marketing | Tailwind v4 utilities + `dark:` variant | Default for indie + small team builds |
+
+**Honesty rule:** if the brief reads as one of the systems above, install and use the **official** package. Do not recreate its CSS by hand. Do not import a system's tokens but then override 90% of them.
+
+**One system per project.** Do not mix Fluent React with Carbon in the same tree. Do not import shadcn/ui components into a Material 3 app.
+
+### 2.B When the brief is an aesthetic, not a system
+For these directions, there is **no single official package**. Build with native CSS + Tailwind + a maintained component library. Be honest in code comments about what is borrowed inspiration vs. official material.
+
+| Aesthetic | Honest implementation |
+|---|---|
+| Glassmorphism / "frosted glass" | `backdrop-filter`, layered borders, highlight overlays. Provide solid-fill fallback for `prefers-reduced-transparency`. |
+| Bento (Apple-style tile grids) | CSS Grid with mixed cell sizes. No single library owns this. |
+| Brutalism | Native CSS, monospace, raw borders. No library. |
+| Editorial / magazine | Serif type, asymmetric grid, generous whitespace. No library. |
+| Dark tech / hacker | Mono + accent neon, terminal motifs. No library. |
+| Aurora / mesh gradients | SVG or layered radial gradients. No library. |
+| Kinetic typography | Native CSS animations, scroll-driven animations, GSAP for hijacks. No library. |
+| **Apple Liquid Glass** | Apple documents this for Apple platforms only. **There is no official `liquid-glass.css`.** Web implementations are approximations using `backdrop-filter` + layered borders + highlights. Label clearly as approximation. |
+
+---
+
+# APPENDICES - Real Source-Backed Reference Material
+
+The sections below are vendored reference content. They give the agent real install commands, real canonical doc links, and real working starter snippets for each design system named in Section 2. Use them to ground decisions in production reality, not training-data fiction.
+
+## Appendix A - Install Commands per Design System
+
+```bash
+# Material Web (Material 3)
+npm install @material/web
+
+# Fluent UI React (v9)
+npm install @fluentui/react-components
+
+# Fluent UI Web Components (framework-free)
+npm install @fluentui/web-components @fluentui/tokens
+
+# IBM Carbon
+npm install @carbon/react @carbon/styles
+
+# Radix Themes
+npm install @radix-ui/themes
+
+# shadcn/ui (open code, owned components)
+npx shadcn@latest init
+npx shadcn@latest add button card badge separator input
+
+# Primer CSS (GitHub product/devtool UI)
+npm install --save @primer/css
+
+# Primer Brand (GitHub marketing UI)
+npm install @primer/react-brand
+
+# GOV.UK Frontend
+npm install govuk-frontend
+
+# USWDS (US Web Design System)
+npm install uswds
+
+# Atlassian Design System (Atlaskit)
+yarn add @atlaskit/css-reset @atlaskit/tokens @atlaskit/button @atlaskit/badge @atlaskit/section-message @atlaskit/card
+
+# Bootstrap 5.3
+npm install bootstrap
+
+# Shopify Polaris Web Components (Shopify apps only)
+# Add this to your app HTML head:
+#   <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
+#   <script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
+```
+
+## Appendix B - Canonical Sources (read these before reinventing)
+
+### Material Web
+- https://github.com/material-components/material-web
+- https://material-web.dev/theming/material-theming/
+- https://m3.material.io/develop/web
+
+### Fluent UI
+- https://fluent2.microsoft.design/get-started/develop
+- https://fluent2.microsoft.design/components/web/react/
+- https://github.com/microsoft/fluentui
+- https://learn.microsoft.com/en-us/fluent-ui/web-components/
+
+### Carbon
+- https://carbondesignsystem.com/
+- https://github.com/carbon-design-system/carbon
+- https://carbondesignsystem.com/developing/react-tutorial/overview/
+- https://carbondesignsystem.com/developing/web-components-tutorial/overview/
+
+### Shopify Polaris
+- https://shopify.dev/docs/api/app-home/web-components
+- https://github.com/Shopify/polaris-react
+- https://polaris-react.shopify.com/components
+
+### Atlassian
+- https://atlassian.design/get-started/develop
+- https://atlassian.design/components/button/examples
+- https://atlaskit.atlassian.com/packages/design-system/button/example/disabled
+- https://atlassian.design/tokens/design-tokens
+
+### Primer
+- https://primer.style/
+- https://github.com/primer/css
+- https://github.com/primer/brand
+
+### GOV.UK
+- https://design-system.service.gov.uk/components/button/
+- https://design-system.service.gov.uk/styles/layout/
+- https://github.com/alphagov/govuk-frontend
+
+### USWDS
+- https://designsystem.digital.gov/documentation/developers/
+- https://designsystem.digital.gov/components/button/
+- https://designsystem.digital.gov/components/card/
+- https://github.com/uswds/uswds
+
+### Bootstrap
+- https://getbootstrap.com/docs/5.3/layout/grid/
+- https://getbootstrap.com/docs/5.3/components/card/
+
+### Tailwind
+- https://tailwindcss.com/docs/dark-mode
+- https://tailwindcss.com/blog/tailwindcss-v4
+
+### Radix
+- https://www.radix-ui.com/themes/docs/components/theme
+- https://www.radix-ui.com/themes/docs/components/card
+- https://github.com/radix-ui/themes
+
+### shadcn/ui
+- https://ui.shadcn.com/docs
+- https://ui.shadcn.com/docs/components/card
+- https://github.com/shadcn-ui/ui
+
+### Native CSS / W3C standards
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/backdrop-filter
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations
+- https://drafts.csswg.org/scroll-animations-1/
+
+### Apple Liquid Glass (Apple platforms only)
+- https://developer.apple.com/design/human-interface-guidelines/materials
+- https://developer.apple.com/documentation/TechnologyOverviews/liquid-glass
+- https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass
+- https://developer.apple.com/documentation/SwiftUI/Material
+
+---
+
+## Appendix C - Apple Liquid Glass: Honest Web Approximation
+
+Do **not** treat random CSS snippets as official Apple Liquid Glass.
+
+### What is official
+Apple documents Liquid Glass inside Apple's Human Interface Guidelines and Developer Documentation for **Apple platforms**. It is a dynamic material used across Apple platform UI. Apple's native implementation belongs to Apple platform APIs and system components, **not a public web CSS package**.
+
+Relevant official docs:
+- Apple Human Interface Guidelines → Materials
+- Apple Developer Documentation → Liquid Glass
+- Apple Developer Documentation → Adopting Liquid Glass
+- SwiftUI → Material
+
+### What is NOT official
+There is no `liquid-glass.css` from Apple for normal websites.
+
+A web approximation can use:
+- `backdrop-filter`
+- transparent backgrounds
+- layered borders
+- highlight overlays
+- gradients
+- motion
+- strong contrast fallbacks
+
+But that is **web glassmorphism / frosted-glass approximation**, not official Apple Liquid Glass. Label it as such in comments.
+
+### Safer web approximation skeleton
+
+```css
+.liquid-glass-web-approx {
+  position: relative;
+  isolation: isolate;
+  overflow: hidden;
+  border-radius: 999px;
+  border: 1px solid rgb(255 255 255 / .32);
+  background:
+    linear-gradient(135deg, rgb(255 255 255 / .30), rgb(255 255 255 / .08)),
+    rgb(255 255 255 / .12);
+  backdrop-filter: blur(24px) saturate(180%) contrast(1.05);
+  -webkit-backdrop-filter: blur(24px) saturate(180%) contrast(1.05);
+  box-shadow:
+    inset 0 1px 0 rgb(255 255 255 / .48),
+    inset 0 -1px 0 rgb(255 255 255 / .12),
+    0 18px 60px rgb(0 0 0 / .18);
+}
+
+.liquid-glass-web-approx::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  border-radius: inherit;
+  background:
+    radial-gradient(circle at 20% 0%, rgb(255 255 255 / .55), transparent 34%),
+    linear-gradient(90deg, rgb(255 255 255 / .18), transparent 42%, rgb(255 255 255 / .14));
+  pointer-events: none;
+}
+
+.liquid-glass-web-approx::after {
+  content: "";
+  position: absolute;
+  inset: 1px;
+  border-radius: inherit;
+  border: 1px solid rgb(255 255 255 / .14);
+  pointer-events: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  .liquid-glass-web-approx {
+    border-color: rgb(255 255 255 / .18);
+    background:
+      linear-gradient(135deg, rgb(255 255 255 / .16), rgb(255 255 255 / .04)),
+      rgb(15 23 42 / .42);
+    box-shadow:
+      inset 0 1px 0 rgb(255 255 255 / .22),
+      0 18px 60px rgb(0 0 0 / .42);
+  }
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  .liquid-glass-web-approx {
+    background: rgb(255 255 255 / .96);
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+  }
+}
+```
+
+**Important:** `prefers-reduced-transparency` has uneven browser support; test it. Always provide enough contrast even without blur.
+
+---
+
+**End of appendices.** Install commands above are reality anchors. The Apple Liquid Glass skeleton is a labeled approximation, not an Apple-issued package. For canonical docs per design system, consult the system's official docs (links in Section 2 plus Appendix B).

package/src/skills-lib/taste-skill/references/motion-patterns.md

@@ -0,0 +1,167 @@
+> taste-skill reference file. Loaded on demand from the SKILL.md index.
+> Cross-references like "Section N" map to sibling files via the index table in ../SKILL.md.
+
+## 5. CONTEXT-AWARE PROACTIVITY
+
+These are tools, not defaults. Use them when the design read calls for them. **None of these fire automatically.**
+
+* **Liquid Glass / Glassmorphism:** Appropriate for premium consumer, Apple-adjacent, luxury brand, or media-overlay vibes. Inappropriate for dashboards, public-sector, or "boring B2B." When used, go beyond `backdrop-blur`: add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) for physical edge refraction. Provide a solid-fill fallback under `prefers-reduced-transparency`.
+* **Magnetic Micro-physics:** Use when `MOTION_INTENSITY > 5` AND the brief reads premium / playful / agency. Implement EXCLUSIVELY with Motion's `useMotionValue` / `useTransform` outside the React render cycle. Never `useState`. See Section 3.B.
+* **Perpetual Micro-Interactions** (Pulse, Typewriter, Float, Shimmer, Carousel): Use when `MOTION_INTENSITY > 5` AND the section actively benefits from motion (status indicators, live feeds, AI-feel). **Not every card needs an infinite loop.** If a section is informational, leave it still. Apply Spring Physics (`type: "spring", stiffness: 100, damping: 20`) - no linear easing.
+* **"Motion claimed, motion shown."** If `MOTION_INTENSITY > 4`, the page must actually move: entry transitions on hero, scroll-reveal on key sections, hover physics on CTAs, at minimum. A static page that claims `MOTION_INTENSITY: 7` is broken. Conversely, if you cannot ship working motion in the available scope, drop the dial to 3 and ship a clean static page. Never half-build motion that breaks (cut-off ScrollTriggers, jumpy enters, missing cleanups).
+* **MOTION MUST BE MOTIVATED (mandatory).** Before adding any animation, ask: "what does this animation communicate?" Valid answers: hierarchy (drawing attention to the right thing), storytelling (revealing content in sequence that matches a narrative), feedback (acknowledging a user action), state transition (showing something changed). Invalid answer: "it looked cool". GSAP everywhere because GSAP is available is amateur. Each ScrollTrigger, each marquee, each pinned section needs a reason. If you cannot articulate the reason in one sentence, drop the animation.
+* **MARQUEE MAX-ONE-PER-PAGE (mandatory).** Horizontal scrolling text marquees ("logos endlessly scrolling", "manifesto scrolling sideways", "kinetic word strip") are appropriate at most ONCE per page. Two or more marquees on the same page reads as lazy filler. Pick the one section where the marquee actually serves the content; the others get a different layout.
+* **GSAP Sticky-Stack Pattern (when scroll-stack is used).** A "card stack on scroll" must be a REAL sticky-stack, not a sequential reveal list. See Section 5.A below for the canonical code skeleton. Common failure: trigger fires halfway through scroll instead of pinning at viewport top. Fix: `start: "top top"` not `start: "top center"` or `"top 80%"`.
+* **GSAP Horizontal-Pan Pattern (when horizontal scroll-hijack is used).** See Section 5.B below for the canonical skeleton. Common failure: animation starts before the section is pinned, so the user sees half a slide. Same fix: `start: "top top"`, pin the wrapper, scrub the inner track.
+
+### 5.A Sticky-Stack - Canonical Skeleton
+
+```tsx
+"use client";
+import { useRef, useEffect } from "react";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useReducedMotion } from "motion/react";
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function StickyStack({ cards }: { cards: React.ReactNode[] }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const reduce = useReducedMotion();
+
+  useEffect(() => {
+    if (reduce || !ref.current) return;
+    const ctx = gsap.context(() => {
+      const cardEls = gsap.utils.toArray<HTMLElement>(".stack-card");
+      cardEls.forEach((card, i) => {
+        if (i === cardEls.length - 1) return;
+        ScrollTrigger.create({
+          trigger: card,
+          start: "top top",                              // pin at viewport top
+          endTrigger: cardEls[cardEls.length - 1],
+          end: "top top",
+          pin: true,
+          pinSpacing: false,
+        });
+        gsap.to(card, {
+          scale: 0.92,
+          opacity: 0.55,
+          ease: "none",
+          scrollTrigger: {
+            trigger: cardEls[i + 1],
+            start: "top bottom",
+            end: "top top",
+            scrub: true,
+          },
+        });
+      });
+    }, ref);
+    return () => ctx.revert();
+  }, [reduce]);
+
+  return (
+    <div ref={ref} className="relative">
+      {cards.map((card, i) => (
+        <div
+          key={i}
+          className="stack-card sticky top-0 min-h-[100dvh] flex items-center justify-center"
+        >
+          {card}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Critical points: `start: "top top"`, `pin: true`, every card except the last is pinned, the scale/opacity transform is driven by the NEXT card's scroll trigger (so previous card shrinks as next one arrives).
+
+### 5.B Horizontal-Pan - Canonical Skeleton
+
+```tsx
+"use client";
+import { useRef, useEffect } from "react";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useReducedMotion } from "motion/react";
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function HorizontalPan({ children }: { children: React.ReactNode }) {
+  const wrap = useRef<HTMLDivElement>(null);
+  const track = useRef<HTMLDivElement>(null);
+  const reduce = useReducedMotion();
+
+  useEffect(() => {
+    if (reduce || !wrap.current || !track.current) return;
+    const ctx = gsap.context(() => {
+      const distance = track.current!.scrollWidth - window.innerWidth;
+      gsap.to(track.current, {
+        x: -distance,
+        ease: "none",
+        scrollTrigger: {
+          trigger: wrap.current,
+          start: "top top",                              // pin starts when section top hits viewport top
+          end: () => `+=${distance}`,                    // scroll distance = track width minus viewport
+          pin: true,
+          scrub: 1,
+          invalidateOnRefresh: true,
+        },
+      });
+    }, wrap);
+    return () => ctx.revert();
+  }, [reduce]);
+
+  return (
+    <section ref={wrap} className="relative overflow-hidden">
+      <div ref={track} className="flex h-[100dvh] items-center">
+        {children}
+      </div>
+    </section>
+  );
+}
+```
+
+Critical points: `start: "top top"`, `pin: true`, `end: "+=${distance}"` (scroll length = horizontal travel needed), `scrub: 1`. The wrapper is pinned, the inner track slides horizontally as the user scrolls vertically.
+
+### 5.C Scroll-Reveal Stagger - Canonical Skeleton (lighter alternative)
+
+For simple "items appear as they enter viewport" (no pinning), prefer Motion's `whileInView` over GSAP - lighter, no ScrollTrigger needed:
+
+```tsx
+"use client";
+import { motion, useReducedMotion } from "motion/react";
+
+export function RevealStagger({ items }: { items: string[] }) {
+  const reduce = useReducedMotion();
+  return (
+    <ul className="grid gap-6">
+      {items.map((item, i) => (
+        <motion.li
+          key={item}
+          initial={reduce ? false : { opacity: 0, y: 24 }}
+          whileInView={{ opacity: 1, y: 0 }}
+          viewport={{ once: true, amount: 0.3 }}
+          transition={{
+            duration: 0.6,
+            delay: i * 0.06,
+            ease: [0.16, 1, 0.3, 1],
+          }}
+        >
+          {item}
+        </motion.li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Use this for: feature lists, testimonial grids, logo walls, anything that just needs "enter on scroll." Save GSAP for actual pin/scrub work.
+
+### 5.D Forbidden Animation Patterns
+
+* **`window.addEventListener("scroll", ...)`** is banned. It runs on every scroll frame, jank-prone, no batching. Use Motion's `useScroll()`, GSAP's `ScrollTrigger`, IntersectionObserver, or CSS `scroll-driven animations` (`animation-timeline: view()`).
+* **Custom scroll progress calculations using `window.scrollY`** in React state. Same reason. Re-renders on every frame.
+* **`requestAnimationFrame` loops that touch React state.** Use motion values (`useMotionValue` + `useTransform`) instead.
+* **Layout Transitions:** Use Motion's `layout` and `layoutId` props for visible state changes (re-ordering lists, expanding modals, shared elements between routes). Do not wrap static content in `layout` props "for safety" - it costs measurement work.
+* **Staggered Orchestration:** Use `staggerChildren` (Motion) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) for reveal moments where sequence matters. For `staggerChildren`, parent (`variants`) and children MUST share the same Client Component tree.

package/src/skills-lib/taste-skill/references/pattern-vocabulary.md

@@ -0,0 +1,78 @@
+> taste-skill reference file. Loaded on demand from the SKILL.md index.
+> Cross-references like "Section N" map to sibling files via the index table in ../SKILL.md.
+
+## 10. REFERENCE VOCABULARY (Pattern Names the Agent Should Know)
+
+This is a vocabulary, not a library. The agent should KNOW these pattern names to communicate about them, design with them in mind, and reach for them when the design read calls for them. **Implementations and code sketches live in the Block Library (Section 12), which is populated iteratively.**
+
+### Hero Paradigms
+* **Asymmetric Split Hero** - Text on one side, asset on the other, generous white space.
+* **Editorial Manifesto Hero** - Large type, no asset, almost-poster.
+* **Video / Media Mask Hero** - Type cut out as mask over video background.
+* **Kinetic-Type Hero** - Animated typography as the primary visual.
+* **Curtain-Reveal Hero** - Hero parts on scroll like a curtain.
+* **Scroll-Pinned Hero** - Hero stays pinned while content scrolls behind.
+
+### Navigation & Menus
+* **Mac OS Dock Magnification** - Edge nav, icons scale fluidly on hover.
+* **Magnetic Button** - Pulls toward cursor.
+* **Gooey Menu** - Sub-items detach like viscous liquid.
+* **Dynamic Island** - Morphing pill for status / alerts.
+* **Contextual Radial Menu** - Circular menu expanding at click point.
+* **Floating Speed Dial** - FAB springing into curved secondary actions.
+* **Mega Menu Reveal** - Full-screen dropdown, stagger-fade content.
+
+### Layout & Grids
+* **Bento Grid** - Asymmetric tile grouping (Apple Control Center).
+* **Masonry Layout** - Staggered grid, no fixed row height.
+* **Chroma Grid** - Borders / tiles with subtle animating gradients.
+* **Split-Screen Scroll** - Two halves sliding in opposite directions.
+* **Sticky-Stack Sections** - Sections that pin and stack on scroll.
+
+### Cards & Containers
+* **Parallax Tilt Card** - 3D tilt tracking mouse coordinates.
+* **Spotlight Border Card** - Borders illuminate under cursor.
+* **Glassmorphism Panel** - Frosted glass with inner refraction.
+* **Holographic Foil Card** - Iridescent rainbow shift on hover.
+* **Tinder Swipe Stack** - Physical card stack, swipe-away.
+* **Morphing Modal** - Button expands into its own dialog.
+
+### Scroll Animations
+* **Sticky Scroll Stack** - Cards stick and physically stack.
+* **Horizontal Scroll Hijack** - Vertical scroll → horizontal pan.
+* **Locomotive / Sequence Scroll** - Video / 3D sequence tied to scrollbar.
+* **Zoom Parallax** - Central background image zooming on scroll.
+* **Scroll Progress Path** - SVG line drawing along scroll.
+* **Liquid Swipe Transition** - Page transition like viscous liquid.
+
+### Galleries & Media
+* **Dome Gallery** - 3D panoramic gallery.
+* **Coverflow Carousel** - 3D carousel with angled edges.
+* **Drag-to-Pan Grid** - Boundless draggable canvas.
+* **Accordion Image Slider** - Narrow strips expanding on hover.
+* **Hover Image Trail** - Mouse leaves popping image trail.
+* **Glitch Effect Image** - RGB-channel shift on hover.
+
+### Typography & Text
+* **Kinetic Marquee** - Endless text bands reversing on scroll.
+* **Text Mask Reveal** - Massive type as transparent window to video.
+* **Text Scramble Effect** - Matrix-style decoding on load / hover.
+* **Circular Text Path** - Text curving along spinning circle.
+* **Gradient Stroke Animation** - Outlined text with running gradient.
+* **Kinetic Typography Grid** - Letters dodging the cursor.
+
+### Micro-Interactions & Effects
+* **Particle Explosion Button** - CTA shatters into particles on success.
+* **Liquid Pull-to-Refresh** - Reload indicator like detaching droplets.
+* **Skeleton Shimmer** - Shifting light reflection across placeholders.
+* **Directional Hover-Aware Button** - Fill enters from cursor's exact side.
+* **Ripple Click Effect** - Wave from click coordinates.
+* **Animated SVG Line Drawing** - Vectors drawing themselves in real time.
+* **Mesh Gradient Background** - Organic lava-lamp blobs.
+* **Lens Blur Depth** - Background UI blurred to focus foreground action.
+
+### Animation Library Choice
+* **Motion (`motion/react`)** - default for UI / Bento / state-change motion.
+* **GSAP + ScrollTrigger** - for full-page scrolltelling and scroll hijacks. Isolate in dedicated leaf components with `useEffect` cleanup.
+* **Three.js / WebGL** - for canvas backgrounds and 3D scenes. Same isolation rule.
+* **NEVER mix GSAP / Three.js with Motion in the same component tree.** They fight over the same frames.

package/src/skills-lib/taste-skill/references/performance-a11y.md

@@ -0,0 +1,33 @@
+> taste-skill reference file. Loaded on demand from the SKILL.md index.
+> Cross-references like "Section N" map to sibling files via the index table in ../SKILL.md.
+
+## 6. PERFORMANCE & ACCESSIBILITY GUARDRAILS
+
+### 6.A Hardware Acceleration
+* Animate ONLY `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`.
+* Use `will-change: transform` sparingly - only on elements that will actually animate.
+
+### 6.B Reduced Motion (mandatory)
+* **Any motion above `MOTION_INTENSITY > 3` MUST honor `prefers-reduced-motion`.** This is non-negotiable.
+* In Motion: wrap with `useReducedMotion()` and degrade to static.
+* In CSS: gate animations behind `@media (prefers-reduced-motion: no-preference)` or provide an override block under `@media (prefers-reduced-motion: reduce)` that disables.
+* Infinite loops, parallax, scroll-hijack, and magnetic physics MUST collapse to static / instant under reduced motion.
+
+### 6.C Dark Mode (mandatory for any consumer-facing page)
+* Design for **both modes from the start**. Never ship light-only or dark-only without explicit user instruction.
+* Use Tailwind `dark:` variant OR CSS variables for tokens. Pick one strategy per project.
+* **Do not prescribe specific dark-mode colors here.** The brief decides. Maintain visual hierarchy, brand identity, and WCAG AA contrast (AAA for body) across both modes.
+* Respect `prefers-color-scheme: dark`. Default to system preference unless the brand insists on one mode.
+
+### 6.D Core Web Vitals Targets
+* **LCP** < 2.5s. Hero image must be `next/image priority` or preloaded.
+* **INP** < 200ms. Heavy work off main thread.
+* **CLS** < 0.1. Reserve space for images, fonts, embeds.
+* Run Lighthouse before declaring a page done.
+
+### 6.E DOM Cost
+* Apply grain / noise filters EXCLUSIVELY to fixed, `pointer-events-none` pseudo-elements (e.g., `fixed inset-0 z-[60] pointer-events-none`). NEVER on scrolling containers - continuous GPU repaints destroy mobile FPS.
+* Be aware of bundle size. Motion is not tiny. Three.js is large. Lazy-load anything that's not above-the-fold.
+
+### 6.F Z-Index Restraint
+NEVER spam arbitrary `z-50` or `z-10`. Use z-index strictly for systemic layer contexts (sticky navbars, modals, overlays, grain). Document the z-index scale in a project constants file.

package/src/skills-lib/taste-skill/references/preflight-checklist.md

@@ -0,0 +1,73 @@
+> taste-skill reference file. Loaded on demand from the SKILL.md index.
+> Cross-references like "Section N" map to sibling files via the index table in ../SKILL.md.
+
+## 14. FINAL PRE-FLIGHT CHECK
+
+Run this matrix before outputting code. This is the last filter.
+
+**THIS IS NOT OPTIONAL. Run every box. If any box fails, the output is not done.**
+
+- [ ] **Brief inference** declared (Section 0.B one-liner)?
+- [ ] **Dial values** explicit and reasoned from the brief, not silently using baseline?
+- [ ] **Design system** chosen from Section 2 if applicable, or aesthetic labeled honestly?
+- [ ] **Redesign mode** detected and audit performed (if applicable, Section 11)?
+- [ ] **ZERO em-dashes (`—`) anywhere on the page.** Headlines, eyebrows, pills, body, quotes, attribution, captions, buttons, alt text. Zero. (Section 9.G - non-negotiable.)
+- [ ] **Page Theme Lock**: ONE theme (light, dark, or auto) for the whole page. No section flips to inverted mode mid-page (Section 4.11)?
+- [ ] **Color Consistency Lock**: one accent color used identically across all sections (Section 4.2)?
+- [ ] **Shape Consistency Lock**: one corner-radius system applied consistently (Section 4.4)?
+- [ ] **Button Contrast Check**: every CTA text is readable against its background (no white-on-white, WCAG AA 4.5:1)?
+- [ ] **CTA Button Wrap**: no CTA label wraps to 2+ lines at desktop?
+- [ ] **Form Contrast Check**: form inputs, placeholders, focus rings, labels all pass WCAG AA against the section background?
+- [ ] **Serif discipline**: if a serif is used, it is NOT Fraunces or Instrument_Serif (or it is, with explicit brand justification)? Different serif from your previous project?
+- [ ] **Premium-consumer palette check**: if the brief is premium-consumer (cookware / wellness / artisan / luxury), the palette is NOT the AI-default beige+brass+oxblood+espresso family? Different family from your previous premium-consumer project?
+- [ ] **Italic descender clearance**: every italic word with `y g j p q` has `leading-[1.1]` min + `pb-1` reserve?
+- [ ] **Hero fits the viewport**: headline ≤ 2 lines, subtext ≤ 20 words AND ≤ 4 lines, CTA visible without scroll, font scale planned around image?
+- [ ] **Hero top padding**: max `pt-24` at desktop, hero content does not float halfway down the viewport?
+- [ ] **Hero stack discipline**: max 4 text elements in hero (eyebrow OR brand strip, headline, subtext, CTAs)? No tiny tagline below CTAs, no trust micro-strip in hero?
+- [ ] **EYEBROW COUNT (mechanical)**: count instances of `uppercase tracking` micro-labels above section headlines across all components. Count ≤ ceil(sectionCount / 3)? Hero counts as 1.
+- [ ] **Split-Header Ban**: no "left big headline + right small explainer paragraph" pattern as a section header (vertical stack instead)?
+- [ ] **Zigzag Alternation Cap**: no 3+ consecutive sections with the same image+text-split layout?
+- [ ] **No Duplicate CTA Intent**: no two CTAs with the same intent ("Get in touch" + "Let's talk" both on page = Fail)?
+- [ ] **Logo wall = logo only**: no industry / category labels printed below logos?
+- [ ] **Bento Background Diversity**: at least 2-3 bento cells have real visual variation (image, gradient, pattern), not all white-on-white text cards?
+- [ ] **"Used by / Trusted by" logo wall** lives UNDER the hero, not inside it, uses REAL SVG logos (Simple Icons / devicon) or generated SVG marks, NOT plain text wordmarks?
+- [ ] **Copy Self-Audit**: every visible string re-read, no grammatically-broken or AI-hallucinated phrases ("free on its past" type) shipped?
+- [ ] **Motion motivated**: every animation can be justified in one sentence (hierarchy / storytelling / feedback / state transition), no GSAP-for-show?
+- [ ] **Marquee max-one-per-page**: no two horizontal marquees on the same page?
+- [ ] **Navigation on ONE line** at desktop, height ≤ 80px?
+- [ ] **Section-Layout-Repetition** check: no two sections share the same layout family (at least 4 different families across 8 sections)?
+- [ ] **Bento has rhythm AND exact cell count** (N items → N cells, no empty cells in middle or at end)?
+- [ ] **Long lists use the right UI component** (not default `<ul>` with `divide-y` for > 5 items - see Section 4.9 alternatives)?
+- [ ] **Real images used** (gen-tool first, then Picsum-seed, then explicit placeholder slots) - NO div-based fake screenshots, NO hand-rolled decorative SVGs, NO pure-text minimalism?
+- [ ] **No pills/labels overlaid on images** (no `Plate · Brand`, no `Field notes - journal`)?
+- [ ] **No photo-credit captions as decoration** (`Field study no. 12 · Ines Caetano`)?
+- [ ] **No version footers** (`v1.4.2`, `Build 0048`) on marketing pages?
+- [ ] **No micro-meta-sentences** under eyebrows ("Each of these is a feature we ship today...")?
+- [ ] **No decoration text strip at hero bottom** (`BRAND. MOTION. SPATIAL.`)?
+- [ ] **No floating top-right sub-text** in section headings?
+- [ ] **No scoring/progress bars with filled background tracks** as comparison visuals?
+- [ ] **No locale / city-name / time / weather strips** unless brief is genuinely globally-distributed or place-focused?
+- [ ] **No scroll cues** (`Scroll`, `↓ scroll`, `Scroll to explore`)?
+- [ ] **No version labels in hero** (V0.6, BETA, INVITE-ONLY) unless the brief is a launch?
+- [ ] **No section-numbering eyebrows** (`00 / INDEX`, `001 · Capabilities`, `06 · how it works`)?
+- [ ] **No decorative dots** (zero by default, only for real semantic state)?
+- [ ] **No `border-t` + `border-b` on every row** of long lists / spec tables?
+- [ ] **Content density** sane: no 20-row data tables, no fake-precise specs without justification, ≤ 25-word sub-paragraphs by default?
+- [ ] **Quotes ≤ 3 lines** of body, attribution clean (no em-dash)?
+- [ ] **Motion claimed = motion shown**: if `MOTION_INTENSITY > 4`, page actually animates, not just claimed?
+- [ ] **GSAP sticky-stack / horizontal-pan** implemented per Section 5.A / 5.B canonical skeleton (`start: "top top"`, `pin: true`, correct scrub)?
+- [ ] **No `window.addEventListener('scroll')`** - using Motion `useScroll()` / ScrollTrigger / IntersectionObserver / CSS scroll-driven animations only?
+- [ ] **Reduced motion** wrapped for everything `MOTION_INTENSITY > 3`?
+- [ ] **Dark mode** tokens defined and tested in both modes?
+- [ ] **Mobile collapse** explicit (`w-full`, `px-4`, `max-w-7xl mx-auto`) for high-variance layouts?
+- [ ] **Viewport stability**: `min-h-[100dvh]`, never `h-screen`?
+- [ ] **`useEffect` animations** have strict cleanup functions?
+- [ ] **Empty / loading / error** states provided?
+- [ ] **Cards omitted** in favor of spacing where possible?
+- [ ] **Icons** from an allowed library only (Phosphor / HugeIcons / Radix / Tabler), no hand-rolled SVG paths?
+- [ ] **Motion** isolated in client-leaf components with `'use client'` at the top, memoized?
+- [ ] **No AI Tells** from Section 9 (Inter as default, AI-purple, three-equal cards, Jane Doe, Acme, "Quietly in use at")?
+- [ ] **Core Web Vitals** plausibly hit (LCP < 2.5s, INP < 200ms, CLS < 0.1)?
+- [ ] **One design system** per project (no Material + shadcn mixed)?
+
+If a single checkbox cannot be honestly ticked, the page is not done. Fix it before delivering.