dreative 0.1.0

package/skill/dreative/skills/3d.md

@@ -0,0 +1,131 @@
+# Dreative Specialist Skill — 3D, WebGL & Shaders
+
+Load this file when `plan.skills` includes `3d`, or the brief/prompt mentions 3D,
+WebGL, three.js, shaders, particles, globes, or point clouds. DESIGN.md still
+governs everything around the canvas (layout, color, type, motion budgets).
+
+## 0. Does 3D earn its place?
+
+3D is the most expensive pixel on the web — in bytes, battery, and attention.
+It earns its place when the SUBJECT is spatial (a physical product, a device, a
+map/globe, an environment, data with real dimensionality) or when the brand brief
+explicitly buys a signature 3D moment. It does not earn its place as ambient
+decoration: a random floating torus/blob behind hero text is the 3D equivalent of
+the gradient blob — banned as a default reach. One 3D moment per page; make it the
+signature element (DESIGN.md §2) or don't ship it.
+
+Cheaper substitutes to consider first: CSS 3D transforms (`perspective` +
+`rotateX/Y` on real DOM — free, accessible, great for cards/mockups/tilt), a
+pre-rendered video/image sequence scrubbed on scroll, or a Lottie/Rive vector
+animation. If the object never needs live lighting or user-driven rotation,
+pre-render it.
+
+## 1. Stack
+
+- **React app → React Three Fiber (`@react-three/fiber`) + `@react-three/drei`.**
+  Never hand-roll a three.js imperative setup inside React. Drei gives you 80%:
+  `Environment`, `ContactShadows`, `Float`, `ScrollControls`, `Html`, `Text`,
+  `useGLTF`, `MeshTransmissionMaterial`, `Center`, `Bounds`.
+- **Non-React → three.js** with a small render-loop module; or **OGL** when the
+  scene is one shader plane and three.js is overkill.
+- Post-processing via `@react-three/postprocessing` (Bloom, DoF, Noise) — 1-2
+  effects max; the stacked-postFX look reads as demo-scene, not product.
+- Physics only if interaction demands it (`@react-three/rapier`).
+
+Lazy-load the entire 3D bundle (`next/dynamic` / `React.lazy`) with an SSR-off
+canvas and a styled poster fallback. Three.js must never be in the critical path.
+
+## 2. Scene fundamentals (where amateur scenes fail)
+
+- **Lighting is the craft.** Default: `<Environment preset="studio"|"city">` for
+  image-based lighting + ONE key directional light for shadows. Ambient light
+  alone = flat plastic. Match light temperature to the page palette.
+- **Color management:** renderer defaults in modern three are correct
+  (`outputColorSpace: SRGBColorSpace`, `ACESFilmicToneMapping`) — don't disable
+  them; DO set `toneMappingExposure` deliberately. Convert hex from the page
+  palette with `new THREE.Color(hex)` — scene colors and page colors must read as
+  one system.
+- **Ground the object:** `<ContactShadows opacity={0.4} blur={2.5}>` or a real
+  shadow plane. Floating unanchored objects read as clipart.
+- Camera: 35-50° FOV for product shots (85°+ distorts); frame with
+  `<Bounds fit clip>` or `<Center>`; subtle idle via `<Float>` or damped
+  mouse-parallax (`useFrame` + `THREE.MathUtils.damp`), amplitude ≤ 3°.
+- Materials: `meshStandardMaterial`/`meshPhysicalMaterial` with `roughness`/
+  `metalness` chosen from the real object; `MeshTransmissionMaterial` for glass
+  (expensive — one object max). Untextured default-gray = unfinished.
+
+## 3. Models
+
+- glTF/GLB only, Draco or Meshopt compressed (`gltf-transform optimize in.glb
+  out.glb --compress draco`). Budget: hero model ≤ 2-3 MB, ≤ 100k triangles.
+- `useGLTF.preload(url)`; wrap in `<Suspense>` with a poster (not a spinner).
+- No model available? Build from primitives + good materials/lighting (a laptop
+  from rounded boxes with an `Html` screen reads better than a bad download), or
+  tell the user what asset is needed — never ship an unrelated placeholder model.
+
+## 4. Shaders (the highest-leverage 100 lines)
+
+A fullscreen/plane fragment shader is the cheapest way to a signature visual:
+animated gradient meshes, flowfields, displacement on hover, image transitions.
+
+- Structure: `shaderMaterial` (drei) with `uTime`, `uMouse`, `uResolution`,
+  palette colors as `uColorA/B/C` uniforms fed FROM the page palette.
+- Vocabulary: fbm/simplex noise for organic movement (inline a noise fn; don't
+  import a library for it), `smoothstep` for banding-free ramps, domain warping
+  (`noise(p + noise(p))`) for the expensive look, `mix()` between palette colors
+  only — never rainbow hue-rotation.
+- Displace vertices in the vertex shader for cloth/terrain/blob effects; compute
+  normals or fake lighting with the noise derivative.
+- Animate `uTime` at 0.05-0.2 speed; slow reads as premium, fast as screensaver.
+- Image effects: sample two textures + a noise mask for transitions; barrel/flow
+  distortion on scroll velocity for editorial galleries.
+
+## 5. Particles and points
+
+Points/instancing, never meshes-per-particle: `<Points>` + `BufferAttribute`
+positions animated in a shader (`uTime` in the vertex shader), or
+`<Instances>`/`InstancedMesh` for repeated geometry (≤ ~10k instances). Counts:
+2-5k points desktop, halve on mobile. Particle color from the page palette at 1-2
+hues; size attenuation on; additive blending only on dark surfaces.
+
+## 6. Scroll- and layout-integration
+
+- Canvas placement: either a bounded block IN the layout (preferred — it composes
+  with the grid) or a full-bleed fixed background with content scrolling over.
+  Full-page persistent canvases with DOM scrolled on top: use drei
+  `ScrollControls` + `<Scroll html>` so 3D and DOM share one scroll.
+- Scroll-linked 3D: map scroll progress (Motion `useScroll` / ScrollTrigger /
+  drei `useScroll`) to camera position along a path or object rotation — damped
+  (`damp3`, `dampE`), never raw-set per frame.
+- DOM/3D registration (labels pinned to model parts): drei `<Html transform
+  occlude>`; keep text as real DOM for accessibility, never texture-baked type.
+- The block's `data-dreative-id` goes on the wrapper div around the Canvas.
+
+## 7. Performance & fallbacks (ship-blockers)
+
+- `<Canvas dpr={[1, 2]}>` (cap device pixel ratio), `frameloop="demand"` +
+  `invalidate()` for static-until-interacted scenes; pause the loop when the
+  canvas leaves the viewport (IntersectionObserver) and on `document.hidden`.
+- One `useFrame` per concern; no allocations inside it (reuse vectors created
+  outside). Dispose on unmount (R3F handles it; imperative three must
+  `dispose()` geometries/materials/textures).
+- Mobile: halve particle counts, drop post-processing, consider a poster image
+  below 768px — a janky 3D hero is worse than none.
+- `prefers-reduced-motion`: stop idle rotation/particle drift; render one static
+  well-lit frame (`frameloop="demand"` makes this free).
+- WebGL unavailable/context-lost → the poster fallback, never a blank block.
+- Keyboard/screen-reader: canvas gets `role="img"` + `aria-label`; any 3D-driven
+  interaction has a DOM equivalent.
+
+## 8. Recipes
+
+- **Product hero**: GLB + `Environment` + key light + `ContactShadows`, `Float`
+  idle, damped mouse parallax, scroll scrubs a 90° orbit. Poster until loaded.
+- **Gradient-mesh hero background**: one plane, fbm + domain-warp fragment shader
+  mixing 3 palette colors, `uTime` 0.08, `uMouse` warps locally. ~120 lines, no
+  model, no lighting — the best effort/impact ratio in this file.
+- **Point-cloud globe**: sphere-distributed points, shader-animated shimmer,
+  arcs as `TubeGeometry`/fat lines between coords, slow idle rotation, drag to
+  spin (damped).
+- **Scroll story**: `ScrollControls pages={4}` + camera on a `CatmullRomCurve3`
+  path, DOM copy in `<Scroll html>`, one damped lookAt target per section.

package/skill/dreative/skills/interaction.md

@@ -0,0 +1,126 @@
+# Dreative Specialist Skill — Micro-interactions & Effect Craft
+
+Load this file when `plan.skills` includes `interaction`, or the brief/prompt asks
+for hover effects, cursor work, tilt, glow, "make it feel alive/tactile/premium".
+It EXTENDS DESIGN.md §6/§9/§10 — every ban there still stands (no hover-scale on
+`<img>`, custom cursors only on explicit request, one marquee max). This skill is
+about the last 5% of feel: small, physical, consistent responses to input.
+
+## 0. The feel system
+
+Micro-interactions are a SYSTEM, not garnish. Before adding any, fix three global
+constants and apply them everywhere: one hover response vocabulary, one press
+response, one focus style. A page where every card hovers differently reads as
+assembled, not designed.
+
+- **Press** (all clickables): `active:scale-[0.98]` (buttons) or
+  `active:scale-[0.99]` (large cards) + 100ms ease-out. This single rule adds more
+  perceived quality per byte than anything else in this file.
+- **Hover** (pick ONE per element class): background tint shift, border-color
+  lift, shadow deepen (tinted to bg hue), or underline draw. 150-200ms.
+- **Focus**: `:focus-visible` ring, 2px, offset 2px, accent color — identical on
+  every interactive element, never removed.
+- Everything targets the 80ms "feels instant" threshold for input feedback.
+
+## 1. Pointer-tracking effects (the premium tier)
+
+All pointer tracking is springs/damping (Motion `useSpring` on `useMotionValue`,
+or lerp in rAF: `x += (target - x) * 0.12`) — raw 1:1 tracking feels robotic.
+Desktop-only: gate behind `@media (hover: hover) and (pointer: fine)`; touch gets
+the static design, not a broken half-effect. All of these are decoration — cap at
+1-2 distinct pointer effects per page, on the signature element's territory.
+
+- **Magnetic elements**: on pointer-move within a proximity zone, translate the
+  element toward the cursor at 15-25% of offset (buttons) with the LABEL moving
+  a further ~10% for parallax depth; spring back on leave
+  (`stiffness 150, damping 15`). Reserve for 1-2 primary CTAs or nav items.
+- **Spotlight cards**: radial-gradient that follows the pointer —
+  `background: radial-gradient(240px circle at var(--x) var(--y),
+  <accent 6-10% alpha>, transparent 65%)` on an overlay div; update CSS vars in
+  rAF. For grids, track on the CONTAINER and light borders of all cards from one
+  listener (the Aceternity/Linear look). Alpha ≤ 0.1; visible-but-subtle.
+- **3D tilt**: perspective 800-1000px, max tilt 4-8° (10°+ is 2015 flash),
+  computed from pointer offset to card center, damped; add a moving specular
+  `linear-gradient` highlight at low alpha for material realism. Cards with text:
+  ≤ 5° or readability suffers.
+- **Image distortion / lens effects** need WebGL — that's `skills/3d.md` §4
+  territory; don't fake them with CSS filters.
+
+## 2. Hover reveals and state morphs
+
+- **Underline draw**: `background-image: linear-gradient(accent, accent)` sized
+  `0% 1.5px → 100% 1.5px` on hover, 250ms expo-out, origin left. The correct link
+  hover for editorial registers.
+- **Text swap/scramble**: label slides up revealing a duplicate from below
+  (wrap in `overflow-hidden`, translateY both spans). Scramble/decode effects
+  only on dark-tech/playful briefs, ≤ 600ms, never on body copy.
+- **Card reveals**: secondary info (arrow, meta row, CTA) slides/fades in ON TOP
+  of a stable layout — the card must never change size on hover (layout shift =
+  amateur tell). Arrows translate 2-4px on hover (`group-hover:translate-x-1`),
+  they don't appear from nothing.
+- **Icon morphs**: hamburger↔close, play↔pause as two-path SVG morphs or rotated
+  strokes, 200ms. Icons that rotate/bounce on every hover = noise; icons respond
+  only when the response means something (chevron rotates because the section
+  opened).
+- Checkbox/toggle/radio: hand-styled with an SVG check that draws in
+  (`stroke-dashoffset` 200ms) — the native-looking-but-smoother tier. Toggles
+  slide with a spring, thumb squashes slightly at rest ends.
+
+## 3. Surface effects (no pointer needed)
+
+- **Glow borders**: `conic-gradient` rotating behind a masked 1px border
+  (`@property --angle` + animation, or padding-box/border-box double background).
+  One element per page, dark surfaces only, accent-hued — this is a signature
+  move, not a card default.
+- **Border beam / tracer**: an accent segment orbiting a card border via
+  `offset-path: border-box` (or rect()) — same rationing as glow.
+- **Gradient shift**: oversized `background-size: 200%` + position animation on
+  a CTA, ≤ 2 hues from the palette. Never on text (gradient text is banned).
+- **Noise/grain**: a tiled 128px PNG/data-URI at 2-4% opacity as a fixed overlay
+  can kill flat-gradient banding on brand pages; `feTurbulence` inline SVG is
+  banned (DESIGN.md §7) — use a pre-baked texture.
+- **Blend modes**: `mix-blend-mode: difference` for text crossing light/dark
+  boundaries (fixed nav over sections); `multiply/screen` to sit imagery into
+  tinted surfaces. Test in both themes; blend modes are the #1 source of
+  invisible-text bugs.
+- Shadows that feel physical: 2-3 stacked layers, tinted to the background hue,
+  y-offset ≈ blur/2 (`0 1px 2px, 0 4px 8px, 0 16px 32px` at descending alpha).
+  One elevation scale page-wide.
+
+## 4. Scroll-adjacent feel
+
+(Choreography lives in `skills/motion.md`; these are ambient behaviors.)
+
+- **Sticky nav transform**: past ~80px scroll, nav gains blur backdrop
+  (`backdrop-blur-md` + bg at 70-85% alpha + hairline border-b), height eases
+  72→60px. Drive from IntersectionObserver on a sentinel, not scroll position.
+- **Scroll progress**: thin accent bar (2px) via `scroll-timeline` /
+  `animation-timeline: scroll()`, CSS-only. Long-form articles only.
+- **Hide-on-scroll-down nav**: product register only, translate ±100% with 300ms
+  ease, 8px hysteresis so it doesn't flicker.
+
+## 5. Feedback micro-moments (product register)
+
+- Button loading: label crossfades to spinner INSIDE the button at fixed width
+  (measure or `min-w`), never a layout jump; success flashes a check 600ms before
+  reverting.
+- Copy-to-clipboard: icon morphs to check + 1.2s revert; optional 150ms
+  background pulse. No toast for copy.
+- Form errors: input border→error color + one 4px x-axis shake (3 oscillations,
+  250ms total, reduced-motion: none) + message fades in below. Shake ONCE per
+  submit, never loop.
+- Optimistic toggles (likes, stars): fill instantly with a 1→1.2→1 spring pop on
+  the icon; reconcile silently on failure with an inline note.
+- Skeletons: shaped like the real layout, shimmer via one masked gradient sweep
+  (1.4s linear infinite), same radius system as the content it becomes.
+
+## 6. Guardrails
+
+- Decorative pointer effects: max 1-2 distinct kinds per page, desktop-only,
+  `prefers-reduced-motion` disables tracking (element stays styled, static).
+- Nothing in this file may cause layout shift, block scrolling, steal focus, or
+  attach a raw `scroll`/`mousemove` listener without rAF batching + cleanup.
+- Every effect must survive keyboard use: whatever hover reveals, focus reveals.
+- Effects use palette tokens (accent/neutral), never introduce new hues.
+- If an effect can't be justified in one sentence of communication value
+  (affordance, state, hierarchy, brand voice), it's noise — cut it (DESIGN.md §6).

package/skill/dreative/skills/motion.md

@@ -0,0 +1,125 @@
+# Dreative Specialist Skill — Motion & Scroll Choreography
+
+Load this file when `plan.skills` includes `motion`, or the brief/prompt asks for
+animation, parallax, scroll storytelling, kinetic type, or "cinematic" feel.
+It EXTENDS DESIGN.md §6 (which still applies: 100/300/500 durations, ease-out
+exponential curves, reduced-motion fallbacks, no scroll listeners, no bounce).
+This file is about doing ambitious motion WELL, not about adding more of it.
+
+## 0. Pick the tool by the job, not by habit
+
+- **CSS only** — hover/focus/press states, one-shot entrances, marquees, simple
+  scroll reveals via `animation-timeline: view()`. Zero JS cost; always first choice.
+- **Motion (`motion/react`, formerly Framer Motion)** — React apps: presence
+  (`AnimatePresence`), layout animation (`layout` prop = free FLIP), springs,
+  `whileInView`, gesture props. The default for React product+brand pages.
+- **GSAP + ScrollTrigger** — timeline choreography: multiple elements coordinated
+  over one scroll range, scrubbed sequences, pinned sections, kinetic type.
+  Use when a Motion version would need 4+ manually-synced `useScroll` hooks.
+- **Lenis** — smooth scroll wrapper for scroll-driven brand pages. Only on brand
+  register with motion dial ≥7; never in product UI. Sync ScrollTrigger with
+  `lenis.on('scroll', ScrollTrigger.update)`.
+
+One animation system per page. Motion AND GSAP on the same page = two spring
+vocabularies fighting; pick one and commit.
+
+## 1. Springs beat durations for anything interactive
+
+Duration+easing is for one-shot choreography (entrances, exits). Anything that
+tracks input or can be interrupted (drag, hover follow, toggles, layout shifts)
+uses springs — they redirect mid-flight without a visible restart.
+
+- Motion defaults: `{ type: "spring", stiffness: 300, damping: 30 }` = snappy UI;
+  `stiffness: 120, damping: 20` = soft brand movement. Overshoot (`damping < 15`)
+  only on playful briefs, and only on small elements — never on layout.
+- `visualDuration` (Motion ≥11.13) sets spring feel by time: easier to reason about.
+- Never spring opacity or color; springs are for transform. Crossfade those.
+
+## 2. Orchestration: one timeline, one story
+
+The scattered-reveals look (every section fades up independently) is the #1 motion
+tell. Instead:
+
+- **Hero entrance** = ONE composed sequence: parent `staggerChildren: 0.08`,
+  `delayChildren` after nav settles; elements enter in reading order; total ≤ 900ms.
+  Nothing else on the page gets entrance choreography.
+- **Below the fold**: at most 2-3 sections get `whileInView` reveals (`once: true`,
+  `margin: "-20% 0px"`), and they should differ (a clip reveal here, a stagger
+  there) — not the same fade-and-rise stamped on everything.
+- Stagger direction carries meaning: top-down for lists, center-out for grids
+  (`delay: Math.abs(i - mid) * 0.05`), left-right only for horizontal sequences.
+- Exits are faster than entrances (~75%) and simpler (fade + small offset; never
+  reverse the full entrance).
+
+## 3. Scroll choreography (motion dial ≥ 7)
+
+- **Scrub vs trigger**: scrub (`scrub: 0.5–1` or Motion `useScroll`+`useTransform`)
+  for progress-bound narrative (a product rotating, a number counting, a diagram
+  assembling). Triggered one-shots for everything else. Scrubbed text reveals are
+  worn out; scrub things that MOVE, trigger things that APPEAR.
+- **Pinning**: max ONE pinned sequence per page (`ScrollTrigger pin: true`, or
+  `position: sticky` + a tall parent — prefer sticky, it's free and un-janks).
+  Pin length ≤ 2.5 viewport heights; past that users feel trapped.
+- **Parallax**: subtle = 8-15% differential (`useTransform(scrollYProgress, [0,1],
+  ["-8%","8%"])`); apply to media/decoration, never body text. 2-3 layers max.
+- **CSS scroll-driven animations** (`animation-timeline: view(); animation-range:
+  entry 0% cover 40%`) handle simple reveals/parallax with zero JS — use for
+  progressive enhancement, gate with `@supports (animation-timeline: view())`.
+- Progress-linked values snap to keyframes users can feel: use eased ranges
+  (`useTransform` with cubic arrays), not raw linear mapping.
+- Never scroll-jack (hijacking wheel delta into slide-snapping). `scroll-snap` on
+  a horizontal strip is fine; taking over vertical page scroll is not.
+
+## 4. Kinetic type and text reveal
+
+- Split text with `SplitText` (GSAP, now free) or manual word-`<span>` wrapping;
+  animate **words or lines, not characters** for readability (chars only for short
+  display words ≤ 12 chars). Wrap split parents in `overflow-hidden` line masks and
+  slide lines up `y: "110%" → 0` — the line-mask reveal reads as premium; per-char
+  fade reads as 2021 template.
+- `aria-label` the original string on the split container; split spans get
+  `aria-hidden`. Re-splitting on resize: debounce, or use `SplitText`'s autoSplit.
+- Counters: animate with `useSpring`/gsap `snap: 1`, `tabular-nums` mandatory,
+  duration ≤ 1.2s, trigger once in view.
+
+## 5. Layout & presence
+
+- Motion `layout` prop for reflow (filtering grids, expanding cards, reordering) —
+  it's FLIP under the hood, transform-only. `layoutId` for shared-element morphs
+  (card → modal). Wrap conditional trees in `AnimatePresence mode="popLayout"`.
+- Accordion/height: `grid-template-rows: 0fr → 1fr` (CSS, cheap) or Motion
+  `height: "auto"` (it measures for you). Never `max-height: 9999px`.
+- **View Transitions API** for page-level transitions (`document.startViewTransition`,
+  or the framework wrapper e.g. Next `<ViewTransition>`): name persistent elements
+  with `view-transition-name` so they morph across routes. Feature-gate; fall back
+  to instant navigation, not a JS fade.
+
+## 6. Performance and accessibility (non-negotiable)
+
+- Transform/opacity only in hot paths; promote animating layers sparingly
+  (`will-change` set just-in-time, removed after). > 6 simultaneously-animating
+  elements = re-choreograph.
+- All scroll work driven by IntersectionObserver / ScrollTrigger / `useScroll`
+  (rAF-batched) — a raw `scroll` listener is a hard ban (DESIGN.md).
+- Test the tab hidden→visible case: loops must not accumulate; `whileInView` must
+  not re-fire (`once: true`).
+- `prefers-reduced-motion`: scrubbed narratives get a static end-state, entrances
+  become plain fades ≤ 200ms, marquees stop. In Motion use `useReducedMotion()`
+  and branch the variants — don't just shorten durations.
+- Content exists without JS: initial styles are the VISIBLE state; animation
+  libraries then hide/offset from JS before first paint (`gsap.set`, Motion
+  `initial`). An SSR'd page must never flash-then-hide.
+
+## 7. Recipes (copy the shape, restyle the skin)
+
+- **Hero sequence**: nav fades in (150ms) → headline lines mask-slide up, 80ms
+  stagger → subtext + CTA fade-rise together → hero media scales 1.04→1 with 6px
+  blur→0. Total 900ms, expo-out.
+- **Sticky product walkthrough**: `sticky` media column + scrolling step copy;
+  step index from IntersectionObserver on copy blocks; media crossfades/transforms
+  per step (springy, 300ms).
+- **Marquee**: duplicated track, `animation: scroll Xs linear infinite`,
+  `width: max-content`, pause on hover, speed from content width (px/s constant,
+  ~60-90px/s), masked edges with `mask-image: linear-gradient`.
+- **Scrub showcase**: sticky canvas/image sequence, `useScroll` on the wrapper,
+  map progress to frame index / rotation; preload frames; ≤ 2.5 viewports tall.