@jaimevalasek/aioson 1.6.0 → 1.7.0

package/template/.aioson/skills/design/pt.squarespace.com/references/websites.md

@@ -0,0 +1,165 @@
+# Websites — Squarespace Homepage
+
+## Page Topology
+
+```
+1.  Header              — Sticky navigation with transparency transition
+2.  Hero                — Full-viewport dark section with video background + CTA
+3.  Grow Your Business  — Feature grid with icons (6 product areas)
+4.  One Platform        — Platform card carousel (videos + images)
+5.  Get Started         — Teal CTA section with template thumbnails
+6.  Your Domain         — Domain search input
+7.  How To              — Step-by-step how-to guide section
+8.  Customers Served    — Statistics row (large numbers)
+9.  Made With SQSP      — Showcase of customer sites
+10. FAQ                 — Accordion FAQ section
+11. Support             — Support options grid
+12. Conversion          — Final dark CTA section with video
+13. Footer              — 4-column links + legal
+```
+
+## Section Details
+
+### Header
+- **Type:** Sticky navigation
+- **Background:** Transparent initially, solid white on scroll
+- **Content:** Logo (left), Nav links (center), CTAs (right)
+- **Mobile:** Hamburger with drawer
+
+### Hero (#homepage-hero)
+- **Background:** Black `rgb(0, 0, 0)` + `<video>` background + `rgba(0,0,0,0.52)` overlay
+- **Video:** `video-desktop.webm/mp4` (desktop), `video-mobile.webm/mp4` (< 768px)
+- **Height:** ~1007px viewport height
+- **Content:**
+  - H1: "Um site faz acontecer" (`var(--text-3xl)`, `var(--font-light)`, white)
+  - P: "Comece de graça. Não precisa de cartão de crédito." (`var(--text-xl)`, white)
+  - CTA: "Comece já" (`.cta--primary.cta--light` — white button, black text, mix-blend-mode hover)
+
+### Grow Your Business (#grow-your-business)
+- **Background:** White or off-white
+- **Layout:** Content grid
+- **Content:** Feature highlights with icons
+
+### One Platform (#one-platform)
+- **Background:** Off-white `rgb(245, 245, 244)`
+- **Layout:** Split layout (text + visual)
+
+### Get Started (#get-started)
+- **Background:** Off-white `rgb(245, 245, 244)` with rotating template thumbnail cards
+- **Content:** Centered CTA + 3 template preview images (rotate/reseda/altaloma)
+- **Video:** `templates.webm/mp4` — template showcase animation
+
+### Your Domain (#your-domain)
+- **Background:** Light gray `rgb(223, 221, 216)`
+- **Layout:** Inline input + button
+- **Input placeholder:** "Digite seu domínio"
+
+### How To (#homepage-how-to)
+- **Background:** White `rgb(255, 255, 255)`
+- **Layout:** Numbered steps with icons
+- **Content:** Step-by-step guide to getting started with Squarespace
+
+### Customers Served (#customers-served)
+- **Background:** Black `rgb(0, 0, 0)`
+- **Layout:** Horizontal stat row
+- **Content:** Large numbers + labels
+- **Animation:** `.stats__card` uses `fadeIn` 1.2s `var(--ease-sqsp-reveal)` on `.in-view`
+
+### Made With SQSP (#made-with-sqsp)
+- **Background:** Off-white `rgb(245, 245, 244)`
+- **Layout:** Grid of customer site screenshots
+- **Content:** Customer-built site showcases with hover zoom effect
+- **Interaction:** `transform: scale(1.04)` on hover, 400ms `var(--ease-sqsp-reveal)`
+
+### FAQ (#homepage-faq)
+- **Background:** White `rgb(255, 255, 255)`
+- **Layout:** Accordion list — question rows expand to reveal answers
+- **Animation:** CSS grid `grid-template-rows: 0fr → 1fr` (same accordion pattern as mobile nav)
+- **Interaction:** Click chevron → expand; click again → collapse
+
+### Support (#support)
+- **Background:** Off-white
+- **Layout:** Grid of support options
+- **Content:** Links to help resources
+
+### Conversion (#conversion)
+- **Background:** Dark `rgb(26, 26, 26)` (charcoal)
+- **Content:** Final headline + CTA
+- **Video:** `conversion-centered.mp4` plays in background
+
+### Footer (.footer)
+- **Background:** Black
+- **Layout:** 4-column grid
+- **Columns:** Products, Solutions, Resources, Company
+- **Bottom:** Copyright, Privacy, Terms
+- **Height:** ~1019px
+
+## Internal Links Discovered
+
+- `/preise` — Pricing page
+- `/templates` — Templates gallery
+- `/design-de-sites` — Design page
+- `/templates/comece-agora` — Start page
+- `/sites/construtor-de-sites-com-ai` — AI builder
+- `/design-inteligente` — Smart design
+- `/websites/criar-um-portfolio` — Portfolio builder
+- `/websites/crie-um-blog` — Blog builder
+- `/websites/analytics` — Analytics
+
+## Typography Details
+
+### Font Family: Clarkson
+- Clarkson is Squarespace's proprietary sans-serif
+- Clarkson Serif is the serif variant
+- Falls back to Helvetica Neue, Helvetica, Arial, sans-serif
+
+### Font Weights Observed
+- 300 (light) — Hero H1
+- 400 (normal) — Body, H2, buttons
+- 500 (medium) — CTAs, emphasis
+
+### Size Scale
+- Hero H1: `var(--text-3xl)` → 42px
+- H2: `var(--text-xl)` → 26px
+- H3: `var(--text-lg)` → 20px
+- Body: `var(--text-base)` → 16px
+- Small: `var(--text-sm)` → 14px
+- Caption: `var(--text-xs)` → 12px
+
+## Color Palette (Hex)
+
+| Token | Hex |
+|-------|-----|
+| `--bg-inverse` | #000000 |
+| `--bg-charcoal` | #1A1A1A |
+| `--bg-teal` | #1E4C41 |
+| `--bg-surface` | #F5F5F4 |
+| `--bg-elevated` | #DFDDD8 |
+| `--text-primary` | #000000 |
+| `--text-inverse` | #FFFFFF |
+| `--text-muted` | #898989 |
+| `--text-light-gray` | #DDDDDD |
+| `--border` | #DDDDDD |
+| `--error` | #200603 |
+
+## Interaction Summary
+
+1. **Nav scroll:** Transparent → solid at 50px scroll via JS class toggle
+2. **Mobile hamburger:** Click → `clip-path: polygon()` wipe animation (600ms) — NOT `translateX`
+3. **Mobile accordion:** `grid-template-rows: 0fr → 1fr` CSS transition (700ms)
+4. **CTA button hover:** `mix-blend-mode: difference` pseudo-element scales in (300ms) — NOT color transition
+5. **Text link hover (`.cta--tertiary`):** Dual linear-gradient `background-position` slide (500ms)
+6. **Section scroll-reveal:** `IntersectionObserver` adds `.in-view`, CSS handles `opacity + translateY` (800ms `--ease-sqsp-reveal`)
+7. **Stats cards:** Staggered `fadeIn` with 0.1s per card delay
+8. **Support arrow hover:** `supportHoverArrow` shimmy keyframe (1.1s infinite)
+9. **AI dots:** `rotateAnimation` + `scaleAnimation{Large/Medium/Small}` coordinated (14s infinite)
+10. **FAQ accordion:** Same `grid-template-rows` technique as mobile nav
+
+## Design Signatures
+
+1. **Zero border-radius** — Sharp corners everywhere
+2. **Clarkson typography** — Distinctive proprietary font
+3. **Dark heroes** — Black backgrounds with white text
+4. **Teal accents** — Dark teal for CTAs and emphasis
+5. **Minimal shadows** — Almost no shadows used
+6. **Generous whitespace** — Large section padding

package/template/.aioson/skills/process/aioson-spec-driven/SKILL.md

@@ -43,3 +43,4 @@ Load the file that matches your current context — do not load all at once:
 | `references/hardening-lane.md` | The input is vague, exploratory, or "vibe-style" and needs to be converted |
 | `references/maintenance-and-state.md` | You are writing or reading `spec*.md`, checkpoints, or retaking work |
 | `references/ui-language.md` | You need to present options, status symbols, or checkpoints to the user with consistent visual standards |
+| `references/qa.md` | You are running QA review and need Gate D verification criteria or artifact validation |

package/template/.aioson/skills/process/aioson-spec-driven/references/analyst.md

@@ -0,0 +1,30 @@
+# Spec-Driven Reference — @analyst
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for discovery and feature requirements
+
+### Always load when this skill is active
+
+- `classification-map.md` — use during discovery to score complexity and declare MICRO/SMALL/MEDIUM before any other decision
+- `artifact-map.md` — use to know exactly what artifacts @analyst owns vs what belongs to @architect or @dev
+- `approval-gates.md` — use Gate A criteria to know when requirements are ready to hand off
+
+### Load when input is vague or exploratory
+
+- `hardening-lane.md` — use to detect whether input is still in vibe mode and route accordingly before producing requirements
+
+### Do not load for @analyst
+
+- `maintenance-and-state.md` — this is for execution/continuation sessions, not discovery
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation
+
+## Behavioral notes
+
+- Declare classification (MICRO/SMALL/MEDIUM) early — it controls depth of requirements, AC verbosity, and whether Gate A is blocking
+- Gate A must be explicitly evaluated before handing off to @architect or @dev
+- `requirements-{slug}.md` is @analyst's primary output — see `artifact-map.md` for ownership chain
+
+### Conformance contract (MEDIUM only)
+
+For MEDIUM features, generate `.aioson/context/conformance-{slug}.yaml` alongside `requirements-{slug}.md`. This YAML file structures each AC into machine-readable preconditions, actions, expected outcomes, and negative cases. @qa and @dev consume this for precise verification and test writing.

package/template/.aioson/skills/process/aioson-spec-driven/references/architect.md

@@ -0,0 +1,23 @@
+# Spec-Driven Reference — @architect
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for architecture work
+
+### Always load when this skill is active
+
+- `classification-map.md` — use to determine architecture depth: MICRO skips most of this, MEDIUM requires full `architecture.md`
+- `approval-gates.md` — Gate B criteria define what @architect must produce before @dev can start; Gate A must already be passed before @architect begins
+- `artifact-map.md` — use to confirm which artifacts @architect owns (`architecture.md`, `design-doc*.md`) and which feed into it
+
+### Do not load for @architect
+
+- `hardening-lane.md` — input is expected to be already past vibe mode when @architect is activated
+- `maintenance-and-state.md` — this is for execution/continuation sessions
+
+## Behavioral notes
+
+- Classification depth from `classification-map.md` controls whether `architecture.md` is required, selective, or skippable
+- Gate B is the handoff signal — @dev must not start implementation without Gate B passing (MEDIUM) or being explicitly waived (SMALL)
+- Decision rationale is mandatory for non-obvious choices — `approval-gates.md` Gate B checklist item applies
+- `design-doc*.md` is @architect's scope-specific decision document — see `artifact-map.md`

package/template/.aioson/skills/process/aioson-spec-driven/references/dev.md

@@ -0,0 +1,47 @@
+# Spec-Driven Reference — @dev
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for implementation
+
+### Always load when this skill is active
+
+- `maintenance-and-state.md` — use to write and update `spec-{slug}.md` correctly: `phase_gates`, `last_checkpoint`, `pending_review`, and `Key decisions` format
+- `approval-gates.md` — Gate C (plan approval) must be checked before executing a significant batch; Gate D (execution verification) defines done criteria for each phase
+
+### Load when starting a new feature with classification context
+
+- `classification-map.md` — use to confirm whether an implementation plan is optional (MICRO), recommended (SMALL), or required (MEDIUM) before starting
+
+### Load when resuming or checking artifact chain
+
+- `artifact-map.md` — use to verify which upstream artifacts exist and which @dev should read before implementing
+
+### Do not load for @dev
+
+- `hardening-lane.md` — @dev activates after hardening; if the spec is still in vibe mode, stop and route back
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation for the user
+
+## Spec drift detection
+
+At session start, after reading `spec-{slug}.md`:
+
+1. Compare `spec_version` in `spec-{slug}.md` with the version recorded in `dev-state.md` (`last_spec_version` field)
+2. If versions differ:
+   > "⚠ Spec changed since last session (version {old} → {new}). Reading the changes before continuing."
+   - Read the diff (Key decisions, Entities added, Edge cases sections)
+   - Update `dev-state.md` with new `last_spec_version`
+3. If versions match: proceed normally
+
+Additionally, at session start for SMALL/MEDIUM:
+4. Check if any `AC-{slug}-{N}` from `requirements-{slug}.md` has a corresponding test file
+5. If coverage is < 50%:
+   > "⚠ AC coverage is low ({N}/{M} ACs have tests). Consider writing missing tests before adding new behavior."
+   This is informational, not blocking.
+
+## Behavioral notes
+
+- `spec-{slug}.md` must be updated at the end of every implementation session — see `maintenance-and-state.md` for format
+- Gate C from `approval-gates.md` means the implementation plan is locked — do not re-discuss pre-taken decisions
+- Gate D verification must happen before marking a phase complete — not just "I think it works"
+- If `phase_gates.plan` is `pending` and classification is SMALL/MEDIUM, suggest generating an implementation plan before proceeding

package/template/.aioson/skills/process/aioson-spec-driven/references/deyvin.md

@@ -0,0 +1,27 @@
+# Spec-Driven Reference — @deyvin
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for continuation and resume flows
+
+### Always load when this skill is active
+
+- `maintenance-and-state.md` — @deyvin's primary job is resumption; use this to read `phase_gates`, `last_checkpoint`, and `pending_review` correctly before any action
+- `approval-gates.md` — use to check which gates are already approved before proceeding; never advance past a gate that is not yet passed
+
+### Load when the continuation context is unclear
+
+- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing when resuming a session with incomplete context
+
+### Do not load for @deyvin
+
+- `hardening-lane.md` — by the time @deyvin is active, the spec pack should already be hardened
+- `classification-map.md` — classification was set in the spec and should not be re-evaluated during continuation
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation for the user
+
+## Behavioral notes
+
+- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads — see `maintenance-and-state.md` for format
+- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
+- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
+- `pending_review` items must be surfaced to the user before proceeding past them

package/template/.aioson/skills/process/aioson-spec-driven/references/maintenance-and-state.md

@@ -57,6 +57,41 @@ Good example:
 
 The reason is what makes the decision useful in 6 months.
 
+## spec_version field
+
+- Seeded at `1` by @analyst when creating the skeleton
+- Incremented by any agent that modifies the spec body (entities, decisions, edge cases — NOT just `last_checkpoint` or `pending_review`)
+- @dev checks at session start: if version changed since last `dev-state.md` update, read the spec diff before continuing
+- @qa checks at review: if version doesn't match what @dev reported, flag as potential drift
+
+## Unified resumption fields
+
+Every agent that produces or updates a persistent artifact should include these fields in the artifact's frontmatter or closing section:
+
+### In frontmatter (machine-readable):
+- `last_agent: {agent-name}` — who was here last
+- `last_session: {ISO-date}` — when
+- `session_result: completed | interrupted | blocked` — what happened
+
+### In closing section (human-readable):
+```
+## Session close — {ISO-date}
+Agent: @{name}
+Result: {completed | interrupted | blocked}
+Next: {clear instruction for next agent or next session}
+```
+
+### Which artifact each agent updates:
+| Agent | Primary artifact |
+|-------|-----------------|
+| @product | `prd.md` or `prd-{slug}.md` |
+| @sheldon | `sheldon-enrichment-{slug}.md` |
+| @analyst | `discovery.md` or `requirements-{slug}.md` |
+| @architect | `architecture.md` |
+| @dev | `dev-state.md` (already does this) |
+| @deyvin | `dev-state.md` or `spec-{slug}.md` |
+| @qa | QA report file |
+
 ## How @deyvin should use this file
 
 1. Read `phase_gates` first — know which phases are locked

package/template/.aioson/skills/process/aioson-spec-driven/references/product.md

@@ -0,0 +1,25 @@
+# Spec-Driven Reference — @product
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for PRD and feature scoping
+
+### Always load when this skill is active
+
+- `classification-map.md` — use to declare MICRO/SMALL/MEDIUM at the start of scoping; classification controls PRD depth, whether a `## Specify depth` section is required, and which downstream phases are mandatory
+- `artifact-map.md` — use to understand what @product's PRD feeds into downstream; helps scope the PRD correctly without over-specifying what belongs to @analyst or @architect
+
+### Load when input is still ambiguous or exploratory
+
+- `hardening-lane.md` — use to detect if the request is still in vibe mode and needs more discovery before a PRD can be written
+
+### Do not load for @product
+
+- `approval-gates.md` — @product produces the PRD; Gate A is evaluated by @analyst after @product hands off
+- `maintenance-and-state.md` — this is for execution/continuation sessions
+
+## Behavioral notes
+
+- Classification (MICRO/SMALL/MEDIUM) from `classification-map.md` must be declared in the PRD — it is the signal that controls all downstream process depth
+- @product does not write requirements (`requirements-{slug}.md`) — those belong to @analyst; see `artifact-map.md` for the boundary
+- If classification is MEDIUM, the PRD must include a `## Specify depth` section per `classification-map.md`

package/template/.aioson/skills/process/aioson-spec-driven/references/qa.md

@@ -0,0 +1,30 @@
+# Spec-Driven Reference — @qa
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for quality verification
+
+### Always load when this skill is active
+
+- `approval-gates.md` — Gate D (execution verification) defines done criteria; @qa is the external verifier of Gate D claims
+- `artifact-map.md` — use to verify that all artifacts claimed by upstream agents actually exist and are substantive
+
+### Load when evaluating AC coverage
+
+- `classification-map.md` — use to calibrate verification depth: MICRO gets happy path + auth only; MEDIUM gets full checklist + invariant tests
+
+### Load when investigating failures or forensics
+
+- `maintenance-and-state.md` — use to read `phase_gates`, `last_checkpoint`, and `pending_review` from `spec-{slug}.md` during forensics mode
+
+### Do not load for @qa
+
+- `hardening-lane.md` — @qa activates after implementation; hardening is not relevant
+- `ui-language.md` — @qa produces structured reports, not interactive checkpoints
+
+## Behavioral notes
+
+- @qa is the external verifier of @dev's Gate D self-certification — "I think it works" from @dev is not evidence until @qa confirms
+- Gate D verification from `approval-gates.md` maps directly to @qa's adversarial probe protocol: truths = behavior tests, artifacts = file existence checks, key_links = wiring verification
+- For MEDIUM projects, @qa should verify that `spec_version` in `spec-{slug}.md` matches the version that @dev was working from — if not, flag as potential drift
+- AC coverage mapping in the QA report should use the same `AC-{slug}-{N}` format from `requirements-{slug}.md`

package/template/.aioson/skills/process/aioson-spec-driven/references/sheldon.md

@@ -0,0 +1,25 @@
+# Spec-Driven Reference — @sheldon
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for enrichment and validation
+
+### Always load when this skill is active
+
+- `hardening-lane.md` — @sheldon's primary job is to move input from Lane 1 (exploration) to Lane 2 (spec hardening); use this to identify vibe signals and what is missing
+- `classification-map.md` — use to determine enrichment depth: MEDIUM requires Modo C (full validation), MICRO/SMALL have lighter enrichment expectations
+
+### Load when evaluating PRD readiness for handoff
+
+- `approval-gates.md` — use Gate A criteria as the readiness checklist @sheldon applies before recommending @analyst activation
+
+### Do not load for @sheldon
+
+- `maintenance-and-state.md` — enrichment is a pre-execution phase; spec state is not relevant yet
+- `artifact-map.md` — load only if @sheldon needs to verify that the right PRD artifact exists before enriching
+
+## Behavioral notes
+
+- @sheldon activates before @analyst — its output (`sheldon-enrichment-{slug}.md`) feeds @analyst
+- Vibe detection from `hardening-lane.md` determines whether to proceed with enrichment or route back to @product
+- MEDIUM classification triggers Modo C: @sheldon must validate completeness more strictly than MICRO/SMALL

package/template/.aioson/skills/process/design-hybrid-forge/SKILL.md

@@ -90,7 +90,9 @@ Each phase must complete before the next begins. Do not skip phase 2 and 3 — t
 ```
 primary_a: {skill-name}            # e.g. "cognitive-core-ui"
 primary_b: {skill-name}            # e.g. "glassmorphism-ui"
-modifiers: {optional 0..2}         # e.g. ["bold-editorial-ui"]
+modifiers: {optional 0..2}         # e.g. ["bold-editorial-ui"] or ["threejs-spatial"]
+                                  # threejs-spatial is a special modifier: it layers WebGL/Three.js
+                                  # on any primary pair, adding particle/3D scene as visual substrate
 variation_overlay: {optional}      # selected via conversation or `aioson design-hybrid:options`
 modifier_policy: {optional}        # "up_to_2_modifiers" by default, "up_to_3_modifiers" in advanced mode
 name_suggestion: {optional}        # e.g. "aurora-command-ui" or leave blank
@@ -142,3 +144,4 @@ The hybrid must satisfy ALL of the following:
 9. Every hybrid ships with both previews and a `.skill-meta.json`. No preview = not done.
 10. Project-local generation goes to `.aioson/installed-skills/` by default. Promotion to core is a separate, explicit step.
 11. `design-hybrid:options` creates a temporary preset in `.aioson/context/design-variation-preset.md`; after successful generation, archive or remove the active preset and preserve the history snapshot.
+12. **`threejs-spatial` modifier rules:** It is NOT a primary parent. It layers WebGL/Three.js as a visual enhancement on the chosen primary pair. It does not own substrate (CSS gradient is still the base), does not own structure (HTML layout is CSS), and does not own tokens. Accent colors from primary parents MUST flow through Three.js parameters. Three.js CDN (no npm install) is the only supported delivery mode.

package/template/.aioson/skills/process/design-hybrid-forge/references/output-contract.md

@@ -234,6 +234,21 @@ Must show:
 - Hybrid accent gradient on hero heading or CTA
 - AIOSON badge
 
+### Three.js modifier preview requirements
+
+When `threejs-spatial` is a modifier, both preview HTMLs must include a Three.js scene as the background layer. The preview must demonstrate:
+
+- Three.js canvas is `position: fixed; inset: 0; z-index: 0` — behind all HTML content
+- Canvas is `alpha: true` — CSS aurora gradient shows through
+- Particle count: ≤ 6,000 on desktop, ≤ 1,500 on mobile (use `navigator.userAgent` check)
+- WebGL support check with CSS fallback: `if (!canvas.getContext('webgl')) { canvas.style.display = "none"; document.body.style.background = "linear-gradient(...)"; }`
+- `prefers-reduced-motion` check: disables canvas, shows static aurora CSS background
+- Accent colors from the hybrid's accent gradient flow into Three.js point light colors and particle palette
+- `requestAnimationFrame` render loop with `IntersectionObserver` to pause when off-screen
+- Three.js CDN loaded via importmap: `<script type="importmap">{"imports":{"three":"https://unpkg.com/three@0.160.0/build/three.module.js"}}</script>`
+
+---
+
 ### Technical requirements (both previews)
 
 - Single `.html` file (no external CSS or JS files)

package/template/.aioson/skills/process/design-hybrid-forge/references/pair-compatibility.md

@@ -78,6 +78,38 @@ Each base skill has a primary role:
 |---|---|
 | `bold-editorial-ui` × `cognitive-core-ui` | Dark editorial command — large display type + mono rails, red-orange × teal tension |
 | `neo-brutalist-ui` × `warm-craft-ui` | Crafted brutalism — raw structure + handmade warmth, artisan dev aesthetic |
+
+---
+
+## Three.js Spatial — Modifier (not a primary parent)
+
+`threejs-spatial` is a **special modifier category** — it is not a standalone design skill
+and can never be a primary parent. It layers WebGL/Three.js spatial effects on top of any
+design skill, adding a 3D scene or particle system as the visual substrate.
+
+**How it works as a modifier:**
+- Applied as a modifier (up to 3 modifiers allowed in advanced mode)
+- Governs: background scene layer, particle systems, 3D object showcase, holographic effects
+- Does NOT govern: tokens, typography, component structure, layout rhythm
+- Accent colors from the primary parents MUST flow through the Three.js parameters
+- The Three.js scene is always alpha: true — CSS gradient background shows through
+
+**Three.js × Design Skill combinations:**
+
+| Primary parent | Three.js layer | Result | Best for |
+|---|---|---|---|
+| `glassmorphism-ui` | Particle aurora backdrop | Frosted 3D glass — glass panels float over real particle scenes | AI tools, crypto, modern SaaS landing |
+| `aurora-command-ui` | Holographic glass object | Holographic command center — glass panels reveal 3D object inside | SOC dashboards, security platforms |
+| `neo-brutalist-ui` | Raw geometry + particles | Particle brutalism — hard geometric forms with particle swarms | Dev tools, indie platforms |
+| `bold-editorial-ui` | Scroll-driven 3D parallax | Editorial 3D depth — typography and images move through a 3D scene | Premium marketing, product launches |
+| `cognitive-core-ui` | Floating data cards (3D boxes) | Command 3D — dense data cards as 3D objects floating in space | Monitoring dashboards, metrics platforms |
+| `warm-craft-ui` | Organic particle drift | Warm particle field — particles drift like embers or dust motes | Wellness, creative tools, B2C |
+
+**Anti-blend rules for Three.js modifier:**
+- Three.js never replaces the CSS/HTML layout — it enhances the background/scene layer only
+- No particle count above 8,000 on desktop, 2,000 on mobile
+- WebGL support check + CSS fallback is mandatory
+- Three.js is never the primary story — the product message comes first
 | `clean-saas-ui` × `bold-editorial-ui` | Enterprise editorial — clean precision + cinematic moments, professional drama |
 
 ---

package/template/.aioson/skills/process/design-hybrid-forge/references/quality-gates.md

@@ -159,6 +159,26 @@ Fail: Return to Phase 4 and fix the metadata before distribution.
 
 ---
 
+## Gate J — Three.js modifier validation (only when `threejs-spatial` is a modifier)
+
+**Question:** Does the Three.js layer enhance without dominating?
+
+Checklist:
+- [ ] WebGL support check present — graceful CSS fallback when WebGL unavailable
+- [ ] `prefers-reduced-motion: reduce` disables the canvas entirely
+- [ ] Mobile particle count ≤ 30% of desktop count
+- [ ] Canvas is `alpha: true` — CSS gradient background visible through it
+- [ ] Accent colors from primary parents flow through Three.js scene parameters (point lights, particle colors, glow)
+- [ ] Three.js scene is background/scene layer only — HTML layout and CSS components are unaffected
+- [ ] No external texture/model URLs — all assets are procedural (geometry, gradients, shaders)
+- [ ] `IntersectionObserver` or equivalent stops render loop when canvas is off-screen — uses `cancelAnimationFrame` + null guard, not `renderer.setAnimationLoop(null)` (which only controls the renderer's internal loop, not `requestAnimationFrame`)
+- [ ] `beforeunload` disposes renderer, geometries, and materials — no memory leaks on page unload
+
+Pass: Three.js enhances without violating the design skill's visual language.
+Fail: Fix the specific violation. Three.js is a modifier — it serves the hybrid, not the other way around.
+
+---
+
 ## Final ship checklist — project-local mode
 
 Before marking the project-local hybrid as done: