dreative 0.5.1 → 0.5.3

package/skill/dreative/recipes/motion-recipes.md

@@ -0,0 +1,68 @@
+# Motion implementation recipes
+
+Load only after three original choreography concepts are recorded. Record access
+in `recipeAccess`.
+
+## Component motion
+
+- Presence: animate enter/exit around semantic state; exits are shorter and
+  simpler; return focus deliberately.
+- Layout: use transform-based layout animation and stable keys; avoid animating
+  expensive dimensions in dense UI.
+- Gestures: pointer capture, velocity, bounds, and spring settle; provide
+  keyboard/touch equivalents.
+
+## Scroll choreography
+
+- IntersectionObserver for one-shot reveals; visible content is the default.
+- Motion `useScroll`/transforms for bounded component-linked progress.
+- GSAP context + ScrollTrigger for multi-element chapters; one Lenis instance
+  and one ticker when smooth scrolling is justified.
+- Sticky CSS for simple pinning; cap pin length and remove/shorten on mobile.
+- Velocity treatments use damped/clamped derivatives, never raw scroll deltas.
+
+## Optional transformation patterns
+
+Choose only patterns that express the concept:
+
+- **Image fragmentation:** split a source into aligned DOM/SVG/Canvas tiles or
+  sampled pixels; disperse, filter, and reconstruct the actual image.
+- **Composition handoff:** carry an object, mask, grid, or type structure from
+  one section into the next instead of resetting the page.
+- **Layered image dive:** separate depth planes or use a depth map and move the
+  camera through the composition.
+- **Mask migration:** evolve one mask window across images or sections.
+- **Object persistence:** keep a key subject staged while its environment,
+  scale, supporting content, and berth change.
+- **Generated-keyframe morph:** blend related still states through masking,
+  displacement, or a bounded frame sequence.
+- **Pixel-to-object reconstruction:** assemble sampled text/image particles into
+  a recognizable subject.
+- **Typography-to-image:** use readable type as mask, grid, path, or fragment
+  source that becomes imagery.
+- **Environmental system:** drive texture, light, particles, type, and objects
+  from the same scroll/interaction state.
+- **Editorial sequence:** treat a long section as one pinned timeline with
+  deliberate internal states rather than independent blocks.
+
+## Type
+
+- Split lines/words/characters only for selected display moments; keep accessible
+  source text and restore wrappers on cleanup.
+- Variable-font axes can become a coherent development mechanism when states
+  change meaningfully rather than merely pulsing.
+
+## Setup and cleanup
+
+- Scope GSAP with context and call `revert()`.
+- Cancel rAF, observers, media queries, and event listeners on unmount.
+- Pause continuous work on `document.hidden` and outside the viewport.
+- Test SSR/hydration so content never flashes then hides.
+
+## Performance/fallback
+
+- Animate transform/opacity or shader state; avoid layout reads after writes.
+- Precompute measurements on resize, reuse objects, and cap continuous work.
+- Reduced motion uses final readable states and retains necessary feedback.
+- Fallback preserves timing hierarchy: setup, peak, rest, and resolution remain
+  legible even when the mechanism becomes static.

package/skill/dreative/references/ARTIFACTS.md

@@ -0,0 +1,196 @@
+# Direct Design artifacts
+
+Use JSON as the machine source of truth and Markdown only as its readable view.
+All paths are relative to the target project.
+
+## `.dreative/plan.json`
+
+Required top-level fields:
+
+- `version: 2`
+- `doctrineVersion: 2` for the bounded-creative-controls format. Legacy v2
+  plans without this field remain readable and receive a migration warning.
+- `request`, `createdAt`
+- `tier`: `solid | premium | expressive | award`
+- `depth`: `restyle | relayout | restructure | reimagine`
+- `skills`: user-approved, dependency-resolved pool including `ux` and `mobile`
+- `skillPolicy`: hybrid routing policy, global foundations, explicit user page
+  assignments, and `routingApproved: true`
+- `designRead`: `{ register, concept, signature }`
+- `preservationManifest`: normally `.dreative/preservation.json`
+- `decisionLedger`: normally `.dreative/ledger.json`
+- `pages`: ordered pages, each with its assigned skills and delivery sections
+- `implementationStartedAt`: timestamp used to prove rule substitutions were
+  declared during planning
+- `ruleExceptions`: bounded substitutions of evidence-backed defaults
+- `creativeStrategy`: `diversity` or `development` at expressive/award tiers
+- `motionComplexityBudget`: hero moments, calm sections, shared language,
+  device limits, progressive enhancement, and anti-default review
+- `fontDecision`: candidates, reflex markers, ledger history, and justification
+- `experimentalPlan`: per-section candidates and the selected two or three peaks
+- `conceptExploration` and `recipeAccess`: proof recipes were loaded only after
+  original concepts were recorded
+
+Every selected skill must appear on at least one page. Every page includes `ux`
+and `mobile`, but optional treatments are assigned only where they serve that
+page. A section may use only skills assigned to its parent page.
+
+Each section requires `id`, `name`, `layoutFamily`, `skills`, `interactions`,
+`mobile`, `fallback`, `verification`, `assets`, and `status`. At expressive/
+award it also requires `motionTreatment`: class, static composition, start/end
+states, changes, pins, handoff, purpose, mechanism, mobile, and reduced motion. Status is
+`planned | shipped | fallback | cut`; fallback/cut requires `reason`.
+
+Each asset requires `id`, `path`, `purpose`, `importance`, `preparation`, and
+`status`. Preparation records flat/decompose/variants/sequence, named
+derivatives, and rationale. A shipped asset must exist when `dreative audit` runs.
+
+### Routing authority
+
+The user's selection is authoritative. Routing may place selected-but-unassigned
+skills and suggest additional treatments, but it never activates an unselected
+optional skill. Explicit page assignments always win. If the user selects all,
+all ten skills appear in the overall plan; this does not mean all ten belong on
+every page. Show the proposed page matrix and obtain approval before setting
+`routingApproved: true`.
+
+## Rule substitutions
+
+Rules live in `references/RULES.json`. Hard gates cannot appear in
+`ruleExceptions`. A valid substitution includes the registered `ruleId`,
+`decision: "substituted"`, planning timestamp, specific reason, concrete
+alternative, at least two observable success criteria, and passing verification
+evidence IDs. The exception must predate `implementationStartedAt`.
+
+```json
+{
+  "ruleId": "media.keyAssetTreatment",
+  "decision": "substituted",
+  "declaredAt": "2026-01-01T00:30:00.000Z",
+  "reason": "The archive contains no raster key imagery, so inventing photography would misrepresent the supplied material.",
+  "alternative": "A persistent variable-type specimen becomes index, spatial architecture, and interactive control.",
+  "successCriteria": [
+    "The specimen appears in materially different structural roles",
+    "Pointer and scroll input visibly reshape the specimen"
+  ],
+  "evidenceIds": ["type-system-desktop", "type-system-mobile"]
+}
+```
+
+## Creative strategy and experimental hierarchy
+
+At `expressive` and `award`, `creativeStrategy.path` is either:
+
+- `diversity`: the concept-related mechanisms and drivers the experience needs;
+  or
+- `development`: one named mechanism with materially different states and
+  quieter support.
+
+`motionComplexityBudget` concentrates complexity into one to three hero moments
+(normally two or three; one for a short page), names calm sections and the
+shared language, and records the anti-default review. It is contextual, not a
+mechanism quota.
+
+When `experimental` is selected, `experimentalPlan` records one candidate for
+every major section and marks only two or three as selected. Other sections
+support, rest, contrast, prepare, or transform those peaks.
+
+## Font decision
+
+`fontDecision` records at least three candidates, identifies reflex fonts using
+`references/REFLEX_FONTS.json`, and includes the last three display fonts from
+the ledger. A reflex winner needs a specific brand/metrics/product/reference/
+language/variable-font/performance reason, recorded in `reasonKinds` using a
+category from the registry. Repeating a recent display font needs an additional
+`repeatJustification`.
+
+## `.dreative/preservation.json`
+
+```json
+{
+  "version": 1,
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "items": [
+    {
+      "id": "nav-pricing",
+      "kind": "link",
+      "file": "src/components/Nav.tsx",
+      "needle": "href=\"/pricing\"",
+      "purpose": "Primary pricing navigation"
+    }
+  ]
+}
+```
+
+Allowed kinds: `link`, `handler`, `form-field`, `visible-copy`, `state`,
+`analytics-hook`, `accessibility`, `route`. Intentional changes add
+`intentionallyChanged: true` and a non-empty `changeReason`.
+
+## `.dreative/verify.json`
+
+Schema: `schemas/verify.schema.json`.
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-01-01T00:00:00.000Z",
+  "evidence": [
+    {
+      "id": "mobile-nav",
+      "criterion": "Mobile navigation opens and closes",
+      "status": "pass",
+      "evidence": "Escape closes and focus returns to trigger",
+      "proof": {
+        "timestamp": "2026-01-01T00:00:00.000Z",
+        "artifactPath": ".dreative/screenshots/mobile-nav.png",
+        "viewport": { "width": 390, "height": 844, "dpr": 2 },
+        "testedUrl": "http://localhost:3000",
+        "consoleErrorCount": 0,
+        "playwrightTestId": "navigation closes with Escape"
+      }
+    }
+  ]
+}
+```
+
+Every evidence row requires a timestamp and concrete proof: an existing artifact
+path, command + exit code, tested URL/console count, FPS/frame-time measurement,
+or Playwright test identifier. `dreative audit` checks referenced artifact paths
+and rejects passing commands with nonzero exits or passing runs with console
+errors. `fail` blocks completion. Use `not-applicable` only with a concrete
+explanation and proof of why the criterion does not apply.
+
+For expressive/award motion, tag evidence with `timelineState`: initial, early,
+mid-transition, final, handoff, mobile, and reduced-motion; add pinned midpoint
+and exit states when relevant. Record the post-inspection refinement in
+`refinement` with findings, changes, and passing evidence IDs.
+
+## `.dreative/ledger.json`
+
+The ledger is append-only design memory:
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {
+      "at": "2026-01-01T00:00:00.000Z",
+      "request": "Redesign landing page",
+      "tier": "premium",
+      "chosen": ["Editorial split with product photography"],
+      "rejected": ["Bento dashboard", "Dark cinematic world"],
+      "failures": [],
+      "userPreferences": ["Calm motion", "No custom cursor"]
+    }
+  ]
+}
+```
+
+Record only project-relevant design preferences and technical failures. Never
+store secrets, personal notes, or unrelated conversation.
+
+## Audit
+
+Run `dreative audit`. It validates schemas, skill dependency closure, section
+completion, shipped assets, preservation needles, verification evidence, and the
+decision ledger. `--json` emits a machine-readable report.

package/skill/dreative/references/REFLEX_FONTS.json

@@ -0,0 +1,44 @@
+{
+  "version": 1,
+  "purpose": "Flag frequently reflexive choices for explicit reasoning; these fonts are not inherently bad or prohibited.",
+  "fonts": [
+    "Inter",
+    "Arial",
+    "Helvetica",
+    "Roboto",
+    "Open Sans",
+    "DM Sans",
+    "DM Serif",
+    "Space Grotesk",
+    "Space Mono",
+    "Outfit",
+    "Plus Jakarta Sans",
+    "Instrument Sans",
+    "Instrument Serif",
+    "Fraunces",
+    "Playfair Display",
+    "Poppins",
+    "Montserrat",
+    "Lato",
+    "Oswald",
+    "Raleway",
+    "Merriweather"
+  ],
+  "validReasonKinds": [
+    "existing-brand",
+    "design-system-metrics",
+    "product-register",
+    "supplied-reference",
+    "language-coverage",
+    "variable-font-capability",
+    "performance",
+    "physical-editorial-historical-reference"
+  ],
+  "invalidGenericReasons": [
+    "looks clean and modern",
+    "clean and modern",
+    "looks professional",
+    "felt better",
+    "fits the design"
+  ]
+}

package/skill/dreative/references/RULES.json

@@ -0,0 +1,186 @@
+{
+  "version": 1,
+  "wordingPrinciple": "Follow the proven default, or outperform it with a named alternative, measurable success criteria, and runtime evidence.",
+  "rules": [
+    {
+      "id": "preservation.noLoss",
+      "category": "hard-gate",
+      "observedFailure": "Redesigns silently removed links, handlers, copy, routes, states, or analytics hooks.",
+      "defaultRemedy": "Complete and pass the preservation manifest before delivery.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "ux.functional",
+      "category": "hard-gate",
+      "observedFailure": "Visually ambitious pages shipped broken navigation, forms, states, focus, or pointer behavior.",
+      "defaultRemedy": "Pass the functional UX audit with keyboard and pointer evidence.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "mobile.required",
+      "category": "hard-gate",
+      "observedFailure": "Desktop effects were cropped, unusable, or absent on touch devices.",
+      "defaultRemedy": "Ship a deliberate mobile treatment for every page and effect.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "motion.reducedMotion",
+      "category": "hard-gate",
+      "observedFailure": "Motion-heavy pages ignored user preferences or hid content when animation failed.",
+      "defaultRemedy": "Ship visible defaults and a tested reduced-motion path.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "spatial.noOcclusion",
+      "category": "hard-gate",
+      "observedFailure": "Traveling decoration and canvases covered text, controls, or pointer targets.",
+      "defaultRemedy": "Pass the occlusion and pointer-events sweep at desktop and mobile sizes.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "3d.noCodedOrganic",
+      "category": "hard-gate",
+      "observedFailure": "Organic real-world subjects built from primitives looked like crude blobs and damaged credibility.",
+      "defaultRemedy": "Use a real GLB, a photoreal cutout, sourced photography, or remove the claimed object.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "effects.runtimeFallback",
+      "category": "hard-gate",
+      "observedFailure": "WebGL, video, and scroll effects left blank or broken content when runtime assumptions failed.",
+      "defaultRemedy": "Ship and exercise loading, context-loss, low-power, and static fallbacks.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "verification.realEvidence",
+      "category": "hard-gate",
+      "observedFailure": "Agents claimed checks passed without commands, screenshots, traces, or measurements.",
+      "defaultRemedy": "Attach structured, auditable proof to every passing verification claim.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "assets.plannedExist",
+      "category": "hard-gate",
+      "observedFailure": "Plans promised distinct assets that were missing, duplicated, or never rendered.",
+      "defaultRemedy": "Reconcile every shipped asset path against the plan and rendered page.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "content.visible",
+      "category": "hard-gate",
+      "observedFailure": "JS animation and effect layers made content invisible or inaccessible.",
+      "defaultRemedy": "Content remains visible and usable before enhancement and when effects fail.",
+      "exceptionAllowed": false,
+      "exceptionTest": "none",
+      "reviewAfterRuns": 0
+    },
+    {
+      "id": "typography.reflexChoice",
+      "category": "evidence-backed-default",
+      "observedFailure": "Agents repeatedly chose the same training-data fonts using generic clean-and-modern reasoning.",
+      "defaultRemedy": "Explore at least three candidates, mark reflex fonts, read the recent ledger, and choose a brand-specific voice.",
+      "exceptionAllowed": true,
+      "exceptionTest": "A reflex font has a specific brand, metric, product, language, variable-font, performance, or supplied-reference reason.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "award.spatialSignature",
+      "category": "evidence-backed-default",
+      "observedFailure": "Award builds used a generic orb or had no recurring dimensional system beyond the hero.",
+      "defaultRemedy": "Plan one concept-specific spatial, media, typographic, or material signature that recurs and changes state.",
+      "exceptionAllowed": true,
+      "exceptionTest": "A named alternative creates equivalent recurrence, interaction, visual dominance, and journey continuity on desktop and mobile.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "3d.signatureRecognizable",
+      "category": "evidence-backed-default",
+      "observedFailure": "Abstract coded spheres, blobs, and toruses were promoted as signature objects and read as generic demos.",
+      "defaultRemedy": "Promote a recognizable subject; keep abstract geometry supporting-only.",
+      "exceptionAllowed": true,
+      "exceptionTest": "A brand-native abstract instrument has a nameable function, material identity, recurrence, and input response rather than being ambient decoration.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "media.award.participatoryMoment",
+      "category": "evidence-backed-default",
+      "observedFailure": "Award media remained something visitors only watched while the page claimed immersion.",
+      "defaultRemedy": "Create one concept-specific point where the visitor affects, enters, transforms, or controls the media's visual logic.",
+      "exceptionAllowed": true,
+      "exceptionTest": "The visitor affects, enters, transforms, scrubs, drags, refracts, or controls the media's visual logic with equal perceptual impact.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "media.keyAssetTreatment",
+      "category": "evidence-backed-default",
+      "observedFailure": "Award builds shipped one set-piece while all other key images remained static or used basic fade-and-zoom.",
+      "defaultRemedy": "Give every key image an explicit flat-or-decompose decision and concentrate meaningful transformation where the narrative changes state.",
+      "exceptionAllowed": true,
+      "exceptionTest": "A coherent alternative media system makes key imagery intentional while preserving calm sections and asset feasibility.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "motion.expressive.architecture",
+      "category": "evidence-backed-default",
+      "observedFailure": "Multiple sections repeated the same simple reveal or used unrelated effects only to satisfy a catalog.",
+      "defaultRemedy": "Plan the page as connected visual states with a small number of hero moments, calm sections, and a concept-specific handoff language.",
+      "exceptionAllowed": true,
+      "exceptionTest": "A coherent signature mechanism develops through materially different states without requiring unrelated mechanisms or gimmick quotas.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "exploration.provocationRoll",
+      "category": "creative-provocation",
+      "observedFailure": "Agents converged on the first familiar concept and repeated prior signatures.",
+      "defaultRemedy": "Use a random provocation to force at least one divergent exploration concept.",
+      "exceptionAllowed": true,
+      "exceptionTest": "The exploration still records three genuinely divergent, brand-native concepts.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "experimental.sectionCandidates",
+      "category": "creative-provocation",
+      "observedFailure": "Experimental mode added effects to a conventional page or made every section compete as a technical demo.",
+      "defaultRemedy": "Explore one non-obvious candidate per major section, then ship only the strongest two or three.",
+      "exceptionAllowed": true,
+      "exceptionTest": "The plan records hierarchy: selected peaks plus supporting, resting, contrasting, or transforming sections.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "recipes.afterExploration",
+      "category": "creative-provocation",
+      "observedFailure": "Large effect catalogs anchored concepts before the agent understood the brand or assets.",
+      "defaultRemedy": "Record three original concepts before loading recipe references.",
+      "exceptionAllowed": true,
+      "exceptionTest": "Early recipe access is limited to feasibility for a user-mandated technique and is recorded explicitly.",
+      "reviewAfterRuns": 5
+    },
+    {
+      "id": "layout.familiesArePrompts",
+      "category": "creative-provocation",
+      "observedFailure": "Suggested layout families became repeated templates instead of content-shaped compositions.",
+      "defaultRemedy": "Use layout-family labels to provoke exploration, not as mandatory templates.",
+      "exceptionAllowed": true,
+      "exceptionTest": "The shipped composition is brand-native, structurally honest, and passes hierarchy and repetition checks.",
+      "reviewAfterRuns": 5
+    }
+  ]
+}

package/skill/dreative/references/SKILL_CONTRACT.md

@@ -0,0 +1,30 @@
+# Specialist skill contract
+
+Every specialist skill follows this contract, in addition to its own doctrine:
+
+Universal foundation: ux and baseline mobile apply to every web page.
+
+1. **Load when:** selected in `plan.skills` or clearly triggered by the brief.
+2. **Do not load when:** the treatment adds cost without serving the request.
+3. **Dependencies:** resolve the skill graph in `SKILL.md`; `ux` and `mobile`
+   are universal.
+4. **Deliverables:** name concrete components, effects, assets, and states in the
+   plan—never select a skill as a mood label.
+5. **Budget:** define asset/runtime limits appropriate to the ambition tier.
+6. **Accessibility:** provide keyboard, reduced-motion, semantic, and readable
+   fallbacks for every treatment.
+7. **Fallback:** name the cheaper robust version before implementation.
+8. **Definition of done:** record observable evidence in `verify.json` and pass
+   `dreative audit`.
+
+A specialist file may strengthen these floors but may not weaken them.
+
+Rules use three categories from `RULES.json`:
+
+- hard gates are objective delivery failures and cannot be waived;
+- evidence-backed defaults are proven remedies with bounded substitutions;
+- creative provocations generate exploration candidates, not mandatory clutter.
+
+Follow the proven default, or outperform it with a named alternative,
+measurable success criteria, and runtime evidence. Generate and record three
+brand-native concepts before loading any `recipes/` reference.

package/skill/dreative/references/TIERS.md

@@ -0,0 +1,44 @@
+# Ambition tiers
+
+Choose the lowest tier that honestly satisfies the request. Higher tiers inherit
+all lower-tier requirements.
+
+## Solid (`solid`)
+
+- Complete, accessible, responsive interface.
+- Existing behavior and preservation manifest pass.
+- Clear hierarchy, coherent type/color/spacing, designed states.
+- Desktop, keyboard, reduced-motion, and approximately 390px mobile verified.
+- Heavy media or bespoke motion is not required.
+
+## Premium (`premium`)
+
+- Everything in Solid.
+- A named register, design concept, and visible signature detail.
+- Intentional photography/media treatment and a dedicated craft pass.
+- Layout composition varies by content; no repeated default-card solution.
+- Motion is restrained and purposeful unless the brief asks for more.
+
+## Expressive (`expressive`)
+
+- Everything in Premium.
+- A recorded diversity-or-development path: concept-related mechanisms/drivers,
+  or one signature mechanism developing through materially different states.
+- A section-by-section motion treatment and contextual complexity budget
+  concentrate structural/transformational motion into a few hero moments.
+- At least one input-driven treatment; entrances alone do not satisfy the tier.
+- Mobile translations and reduced-motion fallbacks are implemented, not noted.
+- Frame behavior and heavy asset cost are measured.
+
+## Award (`award`)
+
+- Everything in Expressive.
+- A distinctive persistent spatial, media, or material system shapes the journey.
+- One unmistakable spatial, media, typographic, or material signature is
+  subject-honest, staged, and resilient. WebGL/3D is used only when justified.
+- Runtime evidence covers effects, transferred weight, frame time, occlusion,
+  context loss/loading, and fallbacks.
+- The page has a small number of memorable moments without sacrificing function.
+
+Do not force Award requirements on product dashboards, checkout, forms, or users
+who asked for calm professional work. Ambition is a product decision, not a score.