dreative 0.5.2 → 0.5.3

package/dist/cli/docsCheck.js

@@ -82,7 +82,7 @@ export function runDocsCheck(skillDir) {
             add(findings, "recipes", specialist, "inline recipe catalog remains in the primary specialist file");
     }
     const planSchema = contents.get("schemas/plan.schema.json") ?? "";
-    for (const field of ["doctrineVersion", "ruleExceptions", "creativeStrategy", "fontDecision", "experimentalPlan", "conceptExploration", "recipeAccess"]) {
+    for (const field of ["doctrineVersion", "ruleExceptions", "creativeStrategy", "motionComplexityBudget", "motionTreatment", "preparation", "fontDecision", "experimentalPlan", "conceptExploration", "recipeAccess"]) {
         if (!planSchema.includes(`\"${field}\"`))
             add(findings, "schema", "schemas/plan.schema.json", `missing creative-control field ${field}`);
     }

package/dist/shared/artifacts.js

@@ -59,6 +59,26 @@ export function validatePlan(value) {
                 errors.push(`${prefix} is still planned`);
             if ((section.status === "fallback" || section.status === "cut") && !nonEmpty(section.reason))
                 errors.push(`${prefix}.reason is required for ${section.status}`);
+            if (section.motionTreatment) {
+                const treatment = section.motionTreatment;
+                if (!["none", "decorative", "structural", "transformational"].includes(treatment.class))
+                    errors.push(`${prefix}.motionTreatment.class is invalid`);
+                for (const [name, value] of Object.entries({
+                    staticComposition: treatment.staticComposition,
+                    startState: treatment.startState,
+                    endState: treatment.endState,
+                    handoff: treatment.handoff,
+                    purpose: treatment.purpose,
+                    mechanism: treatment.mechanism,
+                    mobile: treatment.mobile,
+                    reducedMotion: treatment.reducedMotion,
+                })) {
+                    if (!nonEmpty(value))
+                        errors.push(`${prefix}.motionTreatment.${name} is required`);
+                }
+                if (!Array.isArray(treatment.changes) || !Array.isArray(treatment.pinnedElements))
+                    errors.push(`${prefix}.motionTreatment changes and pinnedElements must be arrays`);
+            }
             for (const skill of section.skills ?? []) {
                 if (!page.skills?.includes(skill))
                     errors.push(`${prefix} uses skill ${skill} not assigned to its page`);
@@ -66,6 +86,20 @@ export function validatePlan(value) {
             for (const asset of section.assets ?? []) {
                 if (!nonEmpty(asset.id) || !nonEmpty(asset.path) || !nonEmpty(asset.purpose))
                     errors.push(`${prefix} contains an incomplete asset`);
+                if (plan.doctrineVersion === 2 && (!asset.importance || !asset.preparation))
+                    errors.push(`${prefix} asset ${asset.id || "unknown"} needs importance and a preparation decision`);
+                else if (asset.preparation) {
+                    if (!asset.importance || !["supporting", "key"].includes(asset.importance))
+                        errors.push(`${prefix} asset ${asset.id} has invalid importance`);
+                    if (!["flat", "decompose", "variants", "sequence"].includes(asset.preparation.decision))
+                        errors.push(`${prefix} asset ${asset.id} has an invalid preparation decision`);
+                    if (!nonEmpty(asset.preparation.rationale))
+                        errors.push(`${prefix} asset ${asset.id} needs a preparation rationale`);
+                    if (!Array.isArray(asset.preparation.derivatives))
+                        errors.push(`${prefix} asset ${asset.id} preparation.derivatives must be an array`);
+                    if (asset.importance === "key" && asset.preparation.decision !== "flat" && asset.preparation.derivatives.length === 0)
+                        errors.push(`${prefix} key asset ${asset.id} promises preparation but names no derivatives`);
+                }
                 if ((asset.status === "fallback" || asset.status === "cut") && !nonEmpty(asset.reason))
                     errors.push(`${prefix} asset ${asset.id} needs a reason`);
             }
@@ -132,11 +166,35 @@ export function validateVerificationReport(value) {
         errors.push("verification report version must be 1");
     if (!Array.isArray(report.evidence))
         errors.push("verification evidence must be an array");
+    if (report.refinement) {
+        if (!nonEmpty(report.refinement.inspectedAt) || Number.isNaN(Date.parse(report.refinement.inspectedAt)))
+            errors.push("verification refinement needs a valid inspectedAt timestamp");
+        if (!Array.isArray(report.refinement.findings) ||
+            report.refinement.findings.length === 0 ||
+            !Array.isArray(report.refinement.changes) ||
+            report.refinement.changes.length === 0 ||
+            !Array.isArray(report.refinement.evidenceIds) ||
+            report.refinement.evidenceIds.length === 0)
+            errors.push("verification refinement needs findings, changes, and evidenceIds arrays");
+    }
     if ((report.evidence ?? []).some((item) => item.status === "fail"))
         errors.push("verification report contains failing evidence");
+    const timelineStates = new Set([
+        "initial",
+        "early",
+        "mid-transition",
+        "final",
+        "handoff",
+        "pinned-midpoint",
+        "pinned-exit",
+        "mobile",
+        "reduced-motion",
+    ]);
     for (const [index, item] of (report.evidence ?? []).entries()) {
         if (!nonEmpty(item.id) || !nonEmpty(item.criterion) || !nonEmpty(item.evidence))
             errors.push(`verification.evidence[${index}] is incomplete`);
+        if (item.timelineState && !timelineStates.has(item.timelineState))
+            errors.push(`verification.evidence[${index}].timelineState is invalid`);
         const proof = item.proof;
         if (!proof || !nonEmpty(proof.timestamp) || Number.isNaN(Date.parse(proof.timestamp))) {
             errors.push(`verification.evidence[${index}].proof requires a valid timestamp`);

package/dist/shared/design.js

@@ -142,12 +142,13 @@ export function buildDesignPlan(page, brief, assignedSkills) {
     const motionBudget = dials.motion <= 3
         ? "hover/active states only, no scroll animation"
         : dials.motion <= 6
-            ? "entry fade+rise on hero, whileInView reveals on 2-3 key sections, nothing infinite"
-            : "scroll choreography allowed on ≤2 sections + hero entry; everything reduced-motion safe";
+            ? "purposeful local motion; use structural transitions only where content changes state, with visible defaults"
+            : "write section motion treatments; concentrate structural/transformational choreography into a few hero moments with calm sections, mobile translations, and reduced-motion states";
     const directives = [
         `aesthetic: ${aesthetic}; dials variance=${dials.variance} motion=${dials.motion} density=${dials.density}`,
         `spacing scale: ${spacing}`,
         `motion budget: ${motionBudget}`,
+        "choose the simplest mechanism that makes each intended transformation convincing; do not default blindly to fade/slide/scale or to WebGL/3D",
         "one accent color, one neutral family, one radius system, locked across ALL pages of this project",
         "section layout families are assigned below — follow them, do not default to repeated card rows",
         ...(dials.variance > 4 ? ["avoid centered-hero-over-gradient; use split or asymmetric composition"] : []),

package/dist/shared/ruleSystem.js

@@ -9,6 +9,12 @@ function specific(value, minLength) {
         return false;
     return !/^(it |this )?(did not fit|didn't fit|felt better|was unnecessary|was not needed|looked better|fits? the design|restraint)$/i.test(value.trim());
 }
+function genericMotionOnly(value) {
+    const text = normalized(value);
+    const basic = /\b(fade|opacity|translate|slide|scale|zoom|parallax|reveal|stagger)\b/;
+    const structural = /\b(mask|fragment|tile|pixel|layer|depth|pin|persist|handoff|morph|reconstruct|sequence|canvas|svg|webgl|shader|state|composition|camera|clip-path|typography)\b/;
+    return basic.test(text) && !structural.test(text);
+}
 export function validateRuleControls(plan, registry, reflexFonts, verification) {
     if (plan.doctrineVersion !== 2)
         return [];
@@ -81,20 +87,104 @@ export function validateRuleControls(plan, registry, reflexFonts, verification)
         if (!strategy)
             errors.push(`${plan.tier} plans require a diversity-or-development creativeStrategy`);
         else if (strategy.path === "diversity") {
-            if (distinct(strategy.mechanisms ?? []).length < 4)
-                errors.push("diversity path requires four distinct mechanisms");
-            if (distinct(strategy.drivers ?? []).length < 3)
-                errors.push("diversity path requires three distinct drivers");
+            if (distinct(strategy.mechanisms ?? []).length === 0)
+                errors.push("diversity path requires at least one concept-specific mechanism");
+            if (distinct(strategy.drivers ?? []).length === 0)
+                errors.push("diversity path requires at least one meaningful driver");
         }
         else {
             if (!specific(strategy.signatureMechanism, 12))
                 errors.push("development path requires a named signature mechanism");
-            if (distinct(strategy.states ?? []).length < 3 || (strategy.states ?? []).some((state) => state.trim().length < 12))
-                errors.push("development path requires three materially different described states");
-            if (distinct(strategy.secondaryMechanisms ?? []).length < 2)
-                errors.push("development path requires two quieter secondary mechanisms");
-            if (distinct(strategy.drivers ?? []).length < 2)
-                errors.push("development path requires two distinct drivers");
+            if (distinct(strategy.states ?? []).length < 2 || (strategy.states ?? []).some((state) => state.trim().length < 12))
+                errors.push("development path requires materially different described states");
+            if (!Array.isArray(strategy.secondaryMechanisms))
+                errors.push("development path must record its quieter supporting mechanisms");
+            if (distinct(strategy.drivers ?? []).length === 0)
+                errors.push("development path requires a meaningful driver");
+        }
+        const sections = plan.pages.flatMap((page) => page.sections);
+        const sectionIds = new Set(sections.map((section) => section.id));
+        const budget = plan.motionComplexityBudget;
+        if (!budget)
+            errors.push(`${plan.tier} plans require a contextual motionComplexityBudget`);
+        else {
+            if (budget.heroMoments.length === 0 || budget.heroMoments.length > 3)
+                errors.push("motion complexity must be concentrated into one to three hero moments");
+            for (const moment of budget.heroMoments) {
+                if (!sectionIds.has(moment.sectionId))
+                    errors.push(`motion hero moment references unknown section ${moment.sectionId}`);
+                if (!specific(moment.reason, 20))
+                    errors.push(`motion hero moment ${moment.sectionId} needs a concept-specific reason`);
+            }
+            for (const sectionId of budget.calmSectionIds) {
+                if (!sectionIds.has(sectionId))
+                    errors.push(`motion calm section references unknown section ${sectionId}`);
+            }
+            if (!specific(budget.sharedLanguage, 20) || !specific(budget.deviceLimits, 20) || !specific(budget.progressiveEnhancement, 20))
+                errors.push("motion complexity budget needs shared language, device limits, and progressive-enhancement decisions");
+            const antiDefault = budget.antiDefaultReview;
+            if (!antiDefault)
+                errors.push("motion complexity budget requires the anti-default review");
+            else
+                for (const [name, answer] of Object.entries(antiDefault)) {
+                    if (!specific(answer, 20))
+                        errors.push(`anti-default review ${name} needs a concrete answer`);
+                }
+        }
+        const treatments = sections.map((section) => section.motionTreatment);
+        if (treatments.some((treatment) => !treatment))
+            errors.push(`${plan.tier} plans require a motion treatment for every major section, including calm sections`);
+        const significant = treatments.filter((treatment) => Boolean(treatment && (treatment.class === "structural" || treatment.class === "transformational")));
+        if (significant.length === 0)
+            errors.push(`${plan.tier} motion cannot be decorative-only`);
+        if (significant.length > 0 &&
+            significant.every((treatment) => genericMotionOnly(`${treatment.mechanism} ${(treatment.changes ?? []).join(" ")} ${treatment.handoff}`)))
+            errors.push(`${plan.tier} motion still describes only generic fade/slide/scale behavior; revise the scene architecture`);
+        for (const [index, treatment] of treatments.entries()) {
+            if (!treatment)
+                continue;
+            const prefix = `motion treatment ${sections[index].id}`;
+            for (const [name, value] of Object.entries({
+                staticComposition: treatment.staticComposition,
+                startState: treatment.startState,
+                endState: treatment.endState,
+                handoff: treatment.handoff,
+                purpose: treatment.purpose,
+                mechanism: treatment.mechanism,
+                mobile: treatment.mobile,
+                reducedMotion: treatment.reducedMotion,
+            })) {
+                if (!specific(value, 12))
+                    errors.push(`${prefix}.${name} needs a concrete decision`);
+            }
+        }
+        if (verification) {
+            const timelineStates = new Set(verification.evidence.map((item) => item.timelineState).filter(Boolean));
+            const requiredStates = [
+                "initial",
+                "early",
+                "mid-transition",
+                "final",
+                "handoff",
+                "mobile",
+                "reduced-motion",
+            ];
+            if (treatments.some((treatment) => (treatment?.pinnedElements?.length ?? 0) > 0))
+                requiredStates.push("pinned-midpoint", "pinned-exit");
+            for (const state of requiredStates) {
+                if (!timelineStates.has(state))
+                    errors.push(`visual verification is missing timeline state ${state}`);
+            }
+            const refinement = verification.refinement;
+            if (!refinement || refinement.changes.length === 0 || refinement.evidenceIds.length === 0)
+                errors.push(`${plan.tier} verification requires a recorded refinement pass after visual inspection`);
+            else {
+                for (const id of refinement.evidenceIds) {
+                    const item = evidence.get(id);
+                    if (!item || item.status !== "pass")
+                        errors.push(`refinement references missing or failing evidence ${id}`);
+                }
+            }
         }
     }
     if (plan.skills.includes("experimental")) {

package/dist/shared/ruleSystem.test.js

@@ -33,6 +33,20 @@ function basePlan(tier = "award") {
             mechanisms: ["variable-type morph", "depth-stack", "drag-inertia", "mask-dissolve"],
             drivers: ["scroll", "pointer", "time"],
         },
+        motionComplexityBudget: {
+            heroMoments: [{ sectionId: "hero", reason: "The archival specimen becomes the navigation system and establishes the living-catalog concept." }],
+            calmSectionIds: [],
+            sharedLanguage: "Archival sheets fold, align, and become structural boundaries across the journey.",
+            deviceLimits: "Desktop uses the full pinned chapter while mobile shortens travel and removes continuous rendering.",
+            progressiveEnhancement: "Semantic catalog content renders first; masks and synchronized motion enhance it when supported.",
+            antiDefaultReview: {
+                basicMotionAssessment: "The key specimen changes role and geometry rather than only fading, sliding, or scaling.",
+                compositionHandoff: "The specimen edge becomes the next chapter's indexing rail instead of disappearing.",
+                visualStateChange: "Loose sheets become navigation, a research surface, and then the closing mark.",
+                conceptSpecificity: "The sheet behavior is derived from archival handling and would not fit an unrelated product.",
+                memorableMoment: "Dragging the specimen reorganizes the complete catalog into the next chapter.",
+            },
+        },
         pages: [
             {
                 id: "home",
@@ -45,6 +59,19 @@ function basePlan(tier = "award") {
                         layoutFamily: "archival-index",
                         skills: ["ux", "mobile", "motion", "media"],
                         interactions: ["drag specimen"],
+                        motionTreatment: {
+                            class: "transformational",
+                            staticComposition: "A loose archival specimen sits beside the catalog index.",
+                            startState: "The specimen is centered and isolated as the page's primary subject.",
+                            endState: "The specimen unfolds into the structural rail for the next catalog chapter.",
+                            changes: ["The specimen mask expands and its edge becomes the next chapter rail."],
+                            pinnedElements: [],
+                            handoff: "The specimen edge persists as the indexing rail in the following composition.",
+                            purpose: "Turn passive archival viewing into active handling and establish continuity.",
+                            mechanism: "SVG mask migration synchronized with a GSAP scroll timeline.",
+                            mobile: "A shorter clip-path handoff preserves the specimen-to-rail transformation.",
+                            reducedMotion: "Render the specimen already aligned with the rail and use a direct section cut.",
+                        },
                         mobile: "stacked specimen",
                         fallback: "static catalog",
                         verification: ["Signature responds to input"],
@@ -59,41 +86,59 @@ function basePlan(tier = "award") {
     };
 }
 function verification(...ids) {
+    const timelineStates = ["initial", "early", "mid-transition", "final", "handoff", "mobile", "reduced-motion"];
+    const timeline = timelineStates.map((timelineState) => ({
+        id: `timeline-${timelineState}`,
+        criterion: `Captured ${timelineState} visual state`,
+        status: "pass",
+        evidence: "Captured the production build at the planned visual state.",
+        timelineState,
+        proof: { timestamp: started, testedUrl: "http://localhost:3000", consoleErrorCount: 0 },
+    }));
     return {
         version: 1,
         generatedAt: started,
-        evidence: ids.map((id) => ({
-            id,
-            criterion: id,
-            status: "pass",
-            evidence: "Captured runtime behavior in the production build.",
-            proof: { timestamp: started, testedUrl: "http://localhost:3000", consoleErrorCount: 0 },
-        })),
+        evidence: [
+            ...timeline,
+            ...ids.map((id) => ({
+                id,
+                criterion: id,
+                status: "pass",
+                evidence: "Captured runtime behavior in the production build.",
+                proof: { timestamp: started, testedUrl: "http://localhost:3000", consoleErrorCount: 0 },
+            })),
+        ],
+        refinement: {
+            inspectedAt: started,
+            findings: ["The mid-transition index was too compressed to read."],
+            changes: ["Extended the mask handoff and delayed the rail compression."],
+            evidenceIds: ["timeline-mid-transition"],
+        },
     };
 }
 test("valid default award plan", () => {
     assert.deepEqual(validateRuleControls(basePlan(), registry, reflex, verification()), []);
 });
-test("valid 3D substitution using spatial typography", () => {
+test("valid key-asset substitution for a typography-only experience", () => {
     const plan = basePlan();
     plan.ruleExceptions = [
         {
-            ruleId: "award.spatialSignature",
+            ruleId: "media.keyAssetTreatment",
             decision: "substituted",
             declaredAt: planned,
-            reason: "The archival concept has no physical subject, so a product-like prop would misrepresent the material.",
-            alternative: "A persistent variable-type specimen becomes index, spatial architecture, and interactive control across four chapters.",
-            successCriteria: ["The specimen appears in three materially different roles", "Pointer and scroll input visibly reshape its depth"],
-            evidenceIds: ["spatial-type-desktop", "spatial-type-mobile"],
+            reason: "The archive contains no raster key imagery; inventing photography would misrepresent the supplied typographic material.",
+            alternative: "A persistent variable-type specimen becomes index, spatial architecture, and interactive control across the complete journey.",
+            successCriteria: ["The specimen appears in materially different structural roles", "Pointer and scroll input visibly reshape the specimen"],
+            evidenceIds: ["type-system-desktop", "type-system-mobile"],
         },
     ];
-    assert.deepEqual(validateRuleControls(plan, registry, reflex, verification("spatial-type-desktop", "spatial-type-mobile")), []);
+    assert.deepEqual(validateRuleControls(plan, registry, reflex, verification("type-system-desktop", "type-system-mobile")), []);
 });
-test("invalid vague 3D exception", () => {
+test("invalid vague creative-rule exception", () => {
     const plan = basePlan();
     plan.ruleExceptions = [
         {
-            ruleId: "award.spatialSignature",
+            ruleId: "media.keyAssetTreatment",
             decision: "substituted",
             declaredAt: planned,
             reason: "It did not fit",
@@ -135,11 +180,41 @@ test("valid development plan", () => {
     };
     assert.deepEqual(validateRuleControls(plan, registry, reflex, verification()), []);
 });
-test("invalid repeated-mechanism plan", () => {
+test("invalid decorative-only expressive plan", () => {
     const plan = basePlan();
-    plan.creativeStrategy = { path: "diversity", mechanisms: ["fade", "fade", "fade", "fade"], drivers: ["scroll", "scroll", "scroll"] };
+    plan.pages[0].sections[0].motionTreatment = {
+        ...plan.pages[0].sections[0].motionTreatment,
+        class: "decorative",
+        changes: ["The image fades upward and scales into view."],
+        mechanism: "CSS opacity, translateY, and scale transitions on scroll reveal.",
+    };
     const errors = validateRuleControls(plan, registry, reflex, verification());
-    assert.ok(errors.some((error) => error.includes("distinct mechanisms")));
+    assert.ok(errors.some((error) => error.includes("decorative-only")));
+});
+test("expressive plan requires contextual motion budget", () => {
+    const plan = basePlan("expressive");
+    delete plan.motionComplexityBudget;
+    assert.ok(validateRuleControls(plan, registry, reflex, verification()).some((error) => error.includes("motionComplexityBudget")));
+});
+test("award verification requires timeline states and a refinement pass", () => {
+    const plan = basePlan();
+    const report = {
+        version: 1,
+        generatedAt: started,
+        evidence: [
+            {
+                id: "initial-only",
+                criterion: "Initial state",
+                status: "pass",
+                evidence: "Captured only the initial frame.",
+                timelineState: "initial",
+                proof: { timestamp: started, testedUrl: "http://localhost:3000", consoleErrorCount: 0 },
+            },
+        ],
+    };
+    const errors = validateRuleControls(plan, registry, reflex, report);
+    assert.ok(errors.some((error) => error.includes("mid-transition")));
+    assert.ok(errors.some((error) => error.includes("refinement pass")));
 });
 test("valid reflex-font justification", () => {
     const plan = basePlan("premium");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreative",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Frontend design skill for coding CLIs with typed planning, specialist treatments, verification, and an optional visual editor.",
   "type": "module",
   "bin": {

package/skill/dreative/DESIGN.md

@@ -156,7 +156,7 @@ its own plan didn't describe. Hard rules for any expressive+ no-media build:
    the blueprint's layout-family words couldn't match them, the build
    restyled a card list and called it the spine — that is a depth-honesty
    failure (§11), not a detail.
-2. **≥ 2 bespoke drawn/procedural artifacts.** With no photography, the page
+2. **Bespoke drawn/procedural artifacts carry the missing media role.** With no photography, the page
    earns visual richness from things MADE for it: a live canvas (meter,
    field, trace), custom SVG structure (rules, notches, connectors, dials —
    drawn, not icon-font), procedural texture/grain, a data-driven ornament.
@@ -165,16 +165,14 @@ its own plan didn't describe. Hard rules for any expressive+ no-media build:
 3. **Type does structural work.** Multi-scale composition (oversized
    numerals/designators against small mono metadata), real hierarchy per §6
    — not one font-size row layout repeated N times.
-4. **Motion budget spends on the structure**, not on entrance fades: the
-   spine's own physicality (things racked, tossed, slid, stamped) is the
-   choreography. Motion.md's inventory applies at full dial.
-5. **A live rendered layer is required at award tier.** No imagery does not
-   mean no rendering: the page ships at least one WebGL/canvas system doing
-   real graphic work — a particle field, procedural texture/flowfield,
-   shader-lit surface, a data-driven instrument that never stops — plus
-   dimensional motion somewhere real (CSS 3D card physicality, depth-layered
-   parallax, a lit WebGL surface). A no-media award page with zero rendered
-   pixels is a text document with transitions. Vocabulary to draw from
+4. **Motion budget spends on the structure**, not on entrance fades: the
+   spine's own physicality (things racked, tossed, slid, stamped) is the
+   choreography. Motion.md's treatment and verification rules apply.
+5. **Choose a rendering layer only when it earns its cost.** No imagery can
+   justify Canvas/WebGL when a live procedural or data-driven surface is the
+   concept, but award ambition does not require one. Spatial typography,
+   layered DOM/SVG composition, masks, or other subject-grounded systems may be
+   stronger. Vocabulary to draw from when rendering is warranted
    (subject-grounded, not decorative): oscilloscope/waveform traces driven by
    real events · topographic contour lines drifting · dot-matrix/LED field
    that spells live state · plexus line-network connecting related items ·
@@ -361,10 +359,17 @@ sites win on composition, not decoration; this is where that happens.
 - Product register: responsive behavior is structural (collapse sidebar, responsive
   table), not fluid type.
 
-## 6. Motion
-
-Every animation answers "what does this communicate?" — hierarchy, storytelling,
-feedback, or state change. "It looked cool" = delete it.
+## 6. Motion
+
+Every animation answers "what does this communicate?" — hierarchy, storytelling,
+feedback, or state change. "It looked cool" = delete it.
+
+Motion has three roles. **Decorative motion** reveals, responds, or adds ambient
+life. **Structural motion** controls hierarchy, pacing, pinning, and composition
+handoffs. **Transformational motion** changes imagery/type/objects into a new
+form or the next scene. Expressive/award pages evaluate key moments for the last
+two roles; opacity, translate, scale, and slight parallax are not automatically
+enough merely because they animate.
 
 **The 100/300/500 rule:** 100-150ms instant feedback (press, toggle) · 200-300ms
 state changes (menu, tooltip, hover) · 300-500ms layout changes (accordion, modal)
@@ -381,9 +386,12 @@ micro-interactions; the uniform fade-and-rise on every scrolled section is the
 saturated AI tell. Some brands skip entrance motion entirely — restraint as voice.
 Product = 150-250ms, state-conveying only, zero page-load choreography.
 
-**Mechanics:** animate transform/opacity by default; blur/backdrop-filter/clip-path/
-masks/shadow allowed when they materially improve the effect, bounded to small areas,
-verified smooth. Never casually animate width/height/top/left/margins (use FLIP or
+**Mechanics:** use transform/opacity for ordinary local state when they fit, but
+do not make them the unexamined expressive default. Select CSS, GSAP timelines,
+ScrollTrigger, SVG, masks, `clip-path`, DOM fragments, Canvas, WebGL/shaders,
+sequences, video, Lottie, or 3D by visual result, cost, responsiveness, and
+available assets. Use the simplest mechanism capable of making the intended
+transformation convincing. Never casually animate width/height/top/left/margins (use FLIP or
 grid-template-rows). Sibling stagger `calc(var(--i) * 50ms)` capped at ~500ms total.
 IntersectionObserver (unobserve after firing), CSS scroll-driven animations, or
 Motion/GSAP scroll tools — `window.addEventListener("scroll")` is a hard ban. Reveals
@@ -734,11 +742,11 @@ On touch, whatever hover revealed must be visible by default or reachable by
 tap — never lost. Custom cursors simply don't exist on touch; don't ship their
 DOM/listeners there.
 
-**Pinned/scrubbed sections**: pinning is fragile on mobile (URL-bar resize
+**Pinned/scrubbed sections**: pinning is fragile on mobile (URL-bar resize
 fires viewport changes mid-pin; iOS momentum scroll skips scrub frames).
-Strategies in preference order: (1) keep the pin but shorten it (≤ 1.5
-viewports) and drive it with `position: sticky`, never JS pinning; (2) unpin —
-the same content as stacked sections with simple in-view reveals;
+Strategies in preference order: (1) keep the pin but shorten it and drive it
+with `position: sticky` when reliable; (2) redesign the same idea as a shorter
+mask, layered-parallax, or state handoff sequence rather than merely disabling it;
 (3) `ScrollTrigger.matchMedia()` / a `matchMedia` branch that swaps the whole
 choreography. Never let a desktop pin length ride on a phone.
 
@@ -765,10 +773,10 @@ clamps DOWN gracefully (hero ≥ 2rem, body stays ≥ 16px — iOS zooms inputs
 under 16px); sticky navs shrink rather than stack; test the three widths 320 /
 768 / 1280 mentally before responding.
 
-**Motion budget on mobile**: entrance choreography total ≤ 600ms (vs 900ms
-desktop), at most 1 scroll-driven sequence per page, marquees pause when
-off-screen. Battery is a design constraint: continuous rAF loops must idle
-when nothing animates.
+**Motion budget on mobile**: shorten travel and timelines according to content,
+viewport, and measured device cost. Preserve one defining idea when feasible;
+marquees pause off-screen and continuous rAF loops idle when nothing animates.
+Battery is a design constraint, not a reason to erase the concept.
 
 ## 14. Typography sourcing (escape the first reflex)