@polymorphism-tech/morph-spec 8.28.0 → 8.29.0

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -20,6 +20,25 @@
 
 **Decision rule:** If the image is unique to the project's brand/aesthetic and doesn't exist as stock, use AI generation. If it's generic and widely available, use stock. If it's geometric or icon-based, use SVG/CSS.
 
+## Brand Fidelity: Reference, Don't Invent
+
+The advantage of an image MCP over generating from scratch is staying consistent with the client's **real** assets. Pass them as reference (`edit_image` with `referenceImages`) rather than generating in a vacuum. A generated look-alike is a different product, and the client sees it immediately.
+
+Two cases where this is a hard rule:
+
+- **Property developers and architecture:** the building is the client's **real architectural render**. Never AI-recreate it. AI only animates it (see `frontend/design-system/ai-video-generation.md`) or composes a scene around the real render.
+- **Physical products:** pass the real product photo as reference and generate angle or setting variations of the **same** product.
+
+### Chain from an approved hero
+
+Generate the **hero first**. Once approved, use it as the reference for every derived image (detail shots, cards, scene variants), so the whole set shares light, palette and identity instead of looking like separate photo shoots.
+
+```
+hero -> [approved] -> derivatives with the approved hero as referenceImages -> [approved per image]
+```
+
+Skipping this chain is the most common cause of a page whose images do not feel like one set.
+
 ## Gemini Image MCP API
 
 ```javascript
@@ -233,6 +252,25 @@ The `assets.md` file is created during the UI/UX phase (Step 4.5) and consumed b
 - **Priority:** high
 ```
 
+## Downstream: Images That Become Video
+
+Static images with faces usually pass image moderation. **Video generation is stricter**: face-bearing img2vid trips moderation (error E005).
+
+So if an image is destined to become video footage, frame it without a face from the start (neck down, hands, the product). For tailoring, craft and manufacturing subjects this usually improves the shot anyway, because the product becomes the subject. See `frontend/design-system/ai-video-generation.md`.
+
+For a frame that will drive a scroll scrub, also generate at the exact ratio the video will output, and place the subject on the side **opposite** the copy. See `frontend/design-system/premium-finish.md`.
+
+## The Two Assets Everyone Forgets
+
+- **Favicon / monogram.** Derive a simple mark (one or two letters, or the existing symbol) that reads at 32x32. Use `edit_image` from the real logo so it stays on-brand. Export PNG at 512x512 and let the browser downscale. **Never invent a new logo**, simplify the existing one.
+- **OG / share image (1200x630).** The image that appears when the link is pasted into a chat or a feed. Use the strongest shot on the page, with breathing room for a possible brand overlay. Generate or crop at that exact ratio. See `frontend/seo/meta-schema-audit.md`.
+
+## Variations and Cost
+
+Generate **two or three variations per image**, varying angle, light or composition, **not just the seed**. Seed-only variation produces near-identical options and wastes the review.
+
+If none are good, regenerate at the same step with the prompt adjusted by the feedback. **Do not advance with a weak image**: every derivative, any footage built from it, and the final page all inherit its quality.
+
 ## Quality Checklist
 
 - [ ] Colors match design system tokens (no random colors in prompts)
@@ -244,5 +282,10 @@ The `assets.md` file is created during the UI/UX phase (Step 4.5) and consumed b
 - [ ] `priority` prop set for above-the-fold images
 - [ ] Build compiles after integration (`npm run build`)
 - [ ] Image visible in dev server at correct route
+- [ ] Client assets passed as `referenceImages`; nothing generated in a vacuum
+- [ ] Real renders and real product photos used as-is, never AI-recreated
+- [ ] Hero approved first, then used as reference for derivatives
+- [ ] Images headed for video framed without faces
+- [ ] Favicon and 1200x630 OG image produced
 
 *MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/design-system/ai-video-generation.md

@@ -0,0 +1,113 @@
+# AI Video Generation — Directional Footage for Scroll Scrub
+
+> **Scope:** frontend-design-system
+> **Layer:** 3
+> **Keywords:** video generation, seedance, img2vid, endImage, directional footage, loop video, E005 moderation, cost ladder
+> **Load When:** producing footage for a scroll-driven page or animating a client render
+
+**Verified against:** seedance MCP (generate_video, generate_loop_video, get_video, list_videos) over Replicate. Last-verified: 2026-08-21.
+
+---
+
+How to generate footage that actually works under scroll control. The single most expensive mistake here is generating a perfect loop for a scrub section, which produces a page that feels frozen while the user scrolls. Covers the loop-versus-directional distinction, how to build directional footage, the face moderation workaround, and the cost ladder.
+
+This is the knowledge layer. The approval gates that stop generation from burning credit belong to the calling workflow, not to this standard.
+
+---
+
+## Section 1: The Distinction That Decides Everything
+
+A **perfect loop** has a last frame identical to its first: the camera and everything in it return to the start. That is exactly right for a video that plays itself on repeat, and exactly wrong for scrubbing. With start and end nearly identical, dragging the scroll appears to change nothing, and the page reads as static while the user scrolls.
+
+Scrubbing needs the opposite: **directional movement**, with the end clearly different from the start. The scroll becomes the control for a camera traveling from one point to another.
+
+| Use | Tool | Start vs end | Why |
+|---|---|---|---|
+| Hero or section driven by scroll | `generate_video` + `endImage` | **different** (push-in, dolly, reveal) | scroll must feel progression |
+| Ambient background that plays itself | `generate_loop_video` | **identical** (loop seal) | seamless repeat |
+| Animating a real client render | `generate_video` (img2vid) | per the desired movement | the building comes from the client, AI only animates |
+
+**Directional is the default.** A seamless loop is the special case, reserved for a secondary ambient plane.
+
+---
+
+## Section 2: Building Directional Footage
+
+Give a start image and an end image, and let the model interpolate a camera traveling between them.
+
+1. Pick or generate the **start frame**: the wide shot, the resting state.
+2. Pick or generate the **end frame** (`endImage`): the destination of the movement (a detail in close-up, a revealed facade).
+3. Call `generate_video { prompt, image: start, endImage: end }`. The prompt describes the camera movement between the two.
+
+**Movements that scrub well:**
+
+- **Push-in / dolly-in**: wide to detail. The most reliable by a wide margin.
+- **Reveal**: camera rises or translates, uncovering more of the subject.
+- **Pull-back**: detail to context, the inverse of push-in.
+- **Slow tilt or pan** anchored on a subject.
+
+**Avoid for scrub:** full orbits and any movement that returns to its origin. They become loops and kill the sense of progress.
+
+---
+
+## Section 3: Faces Trip Moderation
+
+Img2vid with a **human face** repeatedly fails moderation (error E005). The workaround that works is to **crop the face out of frame** before generating.
+
+- Frame from the neck down (garment, hands, fabric) rather than the whole person. For tailoring, craft and manufacturing this usually improves the shot, because the product becomes the subject.
+- Hands working (at a cuff, a button, the material) pass reliably and carry the craft story.
+- If the client insists on a face, generate the **static image** with it (image generation is more permissive) and reserve video for the face-free shots.
+
+---
+
+## Section 4: The Cost Ladder
+
+Every generation costs money and you rarely nail the movement on the first attempt.
+
+1. **Draft:** fast model, 480p, 4s. Enough to judge framing and movement.
+2. **Final:** only after the draft is approved, regenerate at 1080p. Then re-extract frames and swap them into the build **with a cache-bust** (`?v=N`), or the browser serves the old ones. See `frontend/scroll-driven/frame-scrub.md`.
+
+Never open at 1080p.
+
+---
+
+## Section 5: Prompt Skeleton
+
+A directional prompt does not need a loop seal. It needs to be specific about camera, start, end and legibility:
+
+```
+SCENE: [subject without a face: material, color, detail]. [environment]. Mood reference: [1-2 real refs]. Palette: [tones].
+CAMERA: [directional movement] from the start frame to the end frame. Speed [slow, cinematic].
+        Start = [start image], end = [endImage]. Does NOT return to the start.
+ACTION ARC: opens on [initial state], camera [pushes / reveals] until [final state or detail].
+        No elements that return to their starting position.
+LIGHTING: [source, temperature]. Stable from start to finish, no flicker or color shift.
+LEGIBILITY: leave a calm, dark region on one side of the frame for the page copy to sit over.
+        The subject stays on the side OPPOSITE the copy; if it comes out on the wrong side,
+        mirror it at extraction time (hflip).
+TECHNICAL: img2vid with image (start) + endImage (end). No audio. No watermark.
+        Draft 480p/4s; 1080p only after approval.
+```
+
+**Tone:** direct and technical, like director's notes. No hype words ("stunning", "breathtaking"). Describe what happens on screen, not editing software.
+
+---
+
+## Section 6: Async Contract
+
+`generate_video` and `generate_loop_video` return a `request_id` rather than a file. Poll with `get_video { requestId, outputPath? }`, which downloads the `.mp4` once the job reports COMPLETED. `list_videos { limit? }` reads local job history and spends no credits, which also makes it the safe health check for the MCP.
+
+---
+
+## Checklist
+
+- [ ] Directional footage (start differs from end) for anything scroll-driven
+- [ ] Seamless loop used only for a self-playing ambient plane
+- [ ] Client renders animated, never AI-recreated
+- [ ] Faces cropped out of frame before img2vid
+- [ ] Movement chosen from the scrub-friendly list, no orbits or returns
+- [ ] Prompt reserves a calm region for copy, subject opposite the text
+- [ ] Draft at 480p/4s approved before any 1080p render
+- [ ] Frames re-extracted with a bumped cache-bust after the final render
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/design-system/premium-finish.md

@@ -0,0 +1,160 @@
+# Premium Finish — The Layer That Separates Good From Expensive
+
+> **Scope:** frontend-design-system
+> **Layer:** 3
+> **Keywords:** premium, polish, typography, film grain, atmosphere, load-in, scrim, legibility over video, accent
+> **Load When:** ui-designer active, or the brief asks for a premium or high-end feel
+
+**Verified against:** Production landing pages, CSS-only techniques, no runtime dependency. Last-verified: 2026-08-21.
+
+---
+
+A build that runs, is responsive and has scroll animation can still look like a template. The gap between that and something a client reads as expensive is a finish layer applied on purpose. This is that checklist and the reasoning behind each item.
+
+**Read these as principles, not as a recipe.** The goal is to hit the quality *level* for any brand, not to reproduce one project's aesthetic choices. Each item states the principle, which always holds, and then an illustrative answer in italics, which is one option among many.
+
+**Never converge on the same choices across projects.** Same font, same palette, same gradient across clients is the failure mode. Each page should look designed for that business.
+
+---
+
+## Section 1: Typography With Character
+
+Stack default fonts (Inter, Roboto, Arial, system) and the fonts that have become AI-generation tells (Space Grotesk, Playfair) announce "made by a machine". Commit to a display face with real personality, chosen from the brand: what it sells, to whom, at what temperature. Pair a distinctive display with a sober, legible body.
+
+- Enable `font-optical-sizing: auto`.
+- Tighten `letter-spacing` slightly on large headings (`-0.012em` to `-0.015em`) for an editorial set.
+
+*One project (menswear tailoring) used Cormorant for headings and Jost for body. For a property developer or a SaaS the answer is different. Cormorant is not the rule, it was one answer.*
+
+---
+
+## Section 2: Atmosphere, Never Flat Color
+
+Solid backgrounds flatten. Depth and texture make the eye read material. All of these generalize: film grain, subtle radial gradients (a brand glow), vignette, gradient meshes, dramatic shadows, layered transparency.
+
+Film grain is cheap and universal, via an inline SVG `feTurbulence`:
+
+```css
+body::after {
+  content: ''; position: fixed; inset: 0; z-index: 200; pointer-events: none;
+  opacity: 0.055; mix-blend-mode: overlay;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.82' numOctaves='2' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='160' height='160' filter='url(%23n)'/%3E%3C/svg%3E");
+}
+```
+
+The correct opacity is low: texture you feel, not texture you see. Calibrate per brand and per how dark the theme is.
+
+---
+
+## Section 3: One Orchestrated Load-In Beats Ten Micro-Interactions
+
+A single well-choreographed page load (hero elements rising in stagger) delivers more impact than effects scattered across the page. Concentrate the effort on first contact.
+
+Animate the children of the first hero block with one keyframe and increasing `animation-delay`: kicker, then H1, then subtitle, then CTA.
+
+```css
+@keyframes heroRise {
+  from { opacity: 0; transform: translateY(28px); }
+  to   { opacity: 1; transform: none; }
+}
+.hero-beat--1 .kicker,
+.hero-beat--1 h1,
+.hero-beat--1 .sub,
+.hero-beat--1 .actions {
+  opacity: 0; animation: heroRise 1.1s cubic-bezier(.2,.7,.2,1) forwards;
+}
+.hero-beat--1 .kicker  { animation-delay: .30s }
+.hero-beat--1 h1       { animation-delay: .46s }
+.hero-beat--1 .sub     { animation-delay: .68s }
+.hero-beat--1 .actions { animation-delay: .84s }
+```
+
+The exact delays are an example rhythm. The principle is stagger on first impact.
+
+---
+
+## Section 4: Legibility Over Video (Close To a Hard Rule)
+
+Text over video or photography is where a premium hero most often breaks. Solve it with a **directional scrim plus text-shadow**, every time.
+
+The scrim darkens exactly the side where the copy lives and stays clear over the subject. A uniform veil is the wrong tool: it dims the whole image and kills the footage.
+
+```css
+.scrub__scrim {
+  position: absolute; inset: 0;
+  background: linear-gradient(90deg,
+    rgba(14,11,12,.86) 0%, rgba(14,11,12,.5) 38%, rgba(14,11,12,0) 70%);
+}
+.scrub__copy {
+  text-shadow: 0 1px 3px rgba(0,0,0,.5), 0 4px 34px rgba(0,0,0,.5);
+}
+```
+
+The text-shadow is the insurance policy: it keeps the copy readable if a bright frame passes behind it.
+
+If the subject collides with the copy, mirror the footage at extraction time (`hflip`) to throw the subject to the opposite side. See `frontend/scroll-driven/frame-scrub.md`.
+
+---
+
+## Section 5: One Precious Accent, Used Sparingly
+
+A jewel-like detail in very few places (primary CTA, a proof number, one heading highlight) raises perceived value. Sparing and precise: if everything shines, nothing does.
+
+```css
+/* light sweep on the CTA */
+.btn-accent { position: relative; overflow: hidden; }
+.btn-accent::before {
+  content: ''; position: absolute; top: 0; left: -130%; width: 55%; height: 100%;
+  transform: skewX(-22deg); pointer-events: none;
+  background: linear-gradient(90deg, transparent, rgba(255,255,255,.6), transparent);
+  transition: left .6s cubic-bezier(.2,.7,.2,1);
+}
+.btn-accent:hover::before { left: 150%; }
+
+/* metallic gradient text */
+.metallic {
+  background: linear-gradient(180deg, #fff3cf 0%, #ffecb4 28%, #c9a24b 62%, #9a7b35 100%);
+  -webkit-background-clip: text; background-clip: text;
+  -webkit-text-fill-color: transparent;
+  filter: drop-shadow(0 2px 16px rgba(201,162,75,.25));
+}
+```
+
+*The gold above is one answer. For another brand the accent could be chrome, copper, a brand neon, or a single stroke of color. The principle is "one precious accent, used sparingly", not "use gold".*
+
+---
+
+## Section 6: The Details That Add Up
+
+- Scrollbar styled in brand color, not browser gray.
+- `::selection` in the accent color.
+- Hairlines (1px) as gradients that fade at the ends, instead of solid borders.
+- Hover states with a micro-transition (a gap that grows, an arrow that advances), never binary on/off.
+- Consistent radii and a spacing system, not loose numbers.
+
+---
+
+## Section 7: Order of Application
+
+Apply this from the start of the build, not as a final polish pass. The client judges in two seconds.
+
+1. Define brand tokens first (colors, fonts, radii, shadows) as CSS variables. Everything inherits from there.
+2. Apply atmosphere globally (grain plus glow).
+3. Work the hero until the load-in and legibility are flawless.
+4. Place the accent in two or three spots, maximum.
+5. Sweep the details (scrollbar, selection, hovers, hairlines).
+
+Finish with fresh eyes: open the page as if you were the client. Whatever looks like a template is the next thing to raise.
+
+---
+
+## Checklist
+
+- [ ] Display font chosen from the brand, not from stack defaults or the AI-tell list
+- [ ] Brand tokens defined as CSS variables before any component styling
+- [ ] Atmosphere layer applied (grain, glow, or equivalent) at low opacity
+- [ ] Hero load-in staggered with a single keyframe and increasing delays
+- [ ] Directional scrim plus text-shadow on every text-over-media block
+- [ ] Accent used in three places or fewer
+- [ ] Details swept: scrollbar, selection, hairlines, hover micro-transitions
+- [ ] Fresh-eyes pass done, and it does not read as a template

package/framework/standards/frontend/gsap/gsap-core.md

@@ -3,7 +3,7 @@
 > **Scope:** frontend-nextjs-ui
 > **Layer:** 3
 > **Keywords:** gsap, animation, timeline, tween, useGSAP, greensock, transform
-> **Load When:** gsap-animator active
+> **Load When:** ui-designer active, or the project animates with GSAP
 
 **Verified against:** GSAP 3.13 + @gsap/react. Last-verified: 2026-05-20.
 

package/framework/standards/frontend/gsap/gsap-plugins.md

@@ -3,7 +3,7 @@
 > **Scope:** frontend-nextjs-gsap
 > **Layer:** 3
 > **Keywords:** flip, splittext, morphsvg, drawsvg, motionpath, draggable, observer, scrollto, gsap-plugins
-> **Load When:** gsap-animator active
+> **Load When:** ui-designer active, or the project animates with GSAP
 
 **Verified against:** GSAP 3.13 + @gsap/react. Last-verified: 2026-05-20.
 

package/framework/standards/frontend/gsap/gsap-scrolltrigger.md

@@ -3,7 +3,7 @@
 > **Scope:** frontend-nextjs-gsap
 > **Layer:** 3
 > **Keywords:** scrolltrigger, scroll-animation, pinning, scrubbing, parallax, scroll-driven, gsap
-> **Load When:** gsap-animator active
+> **Load When:** ui-designer active, or the project animates with GSAP
 
 **Verified against:** GSAP 3.13 ScrollTrigger + @gsap/react. Last-verified: 2026-05-20.
 
@@ -11,6 +11,8 @@
 
 Reference guide for implementing scroll-driven animations in Next.js projects using GSAP ScrollTrigger. Covers plugin setup, scrubbing, pinning, batch processing, responsive breakpoints, SSR considerations, and mandatory cleanup patterns.
 
+**Pair this with a smooth scroller before shipping a cinematic page.** ScrollTrigger reads native scroll on its own, which is correct for app UI. A landing page whose scroll drives a scene wants Lenis handing scroll to ScrollTrigger through the GSAP ticker, plus the instance exposed on `window` so overlays and automated verification can drive it. That wiring, and the traps that come with it, live in `frontend/scroll-driven/smooth-scroll.md`.
+
 ---
 
 ## Section 1: Plugin Registration

package/framework/standards/frontend/nextjs/motion-patterns.md

@@ -9,7 +9,9 @@
 
 ---
 
-Reference guide for implementing animations and transitions in Next.js projects using **Motion for React** — the library formerly published as `framer-motion`. The package is now `motion` and components import from `motion/react`; the `framer-motion` name only survives inside the Framer design tool. Covers the canonical variants library, design token bridge, scroll and gesture patterns, loading states, and mandatory WCAG accessibility compliance.
+Reference guide for implementing animations and transitions in Next.js projects using **Motion for React**, the library formerly published as `framer-motion`. The package is now `motion` and components import from `motion/react`; the `framer-motion` name only survives inside the Framer design tool. Covers the canonical variants library, design token bridge, scroll and gesture patterns, loading states, and mandatory WCAG accessibility compliance.
+
+**Scope, and where the other motion stack starts.** This standard governs component-level motion: enter and exit, gestures, mount and unmount transitions, short scroll reveals in an app or product UI. When the scroll position itself drives the scene (frame scrubs, pinned sequences, parallax, a cinematic landing page), that is GSAP plus ScrollTrigger plus Lenis: see `frontend/scroll-driven/smooth-scroll.md` and `frontend/gsap/gsap-core.md`. The two stacks may share a page but never the same element, because both write inline styles and will fight for control. On a page that runs Lenis, use the `useReveal` recipe in `frontend/scroll-driven/scroll-components.md` rather than `whileInView`, so a single library owns the answer to when an element is visible.
 
 ---