npm - @jaimevalasek/aioson - Versions diffs - 1.7.0 → 1.7.2 - Mend

@jaimevalasek/aioson 1.7.0 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/template/.aioson/agents/qa.md CHANGED Viewed

@@ -404,6 +404,107 @@ After writing the QA report, run a self-check: count ACs with status "Covered" v
 - **SMALL:** full checklist + stack-specific tests for all critical flows.
 - **MEDIUM:** full checklist + invariant tests + load assumptions documented.
+## Web validation mode (project_type=site)
+Activate automatically when `project_type=site` is detected in `project.context.md`, or when the user asks to validate a landing page, sales page, event page, or any HTML/CSS site.
+This replaces the standard code review checklist with a web-specific validation suite.
+### Step W1 — Functional validation
+- [ ] All CTA buttons and anchor links navigate to the correct target or open the correct form
+- [ ] Form submits correctly: shows success state, shows error state, does not double-submit
+- [ ] No broken images (all `src` paths resolve)
+- [ ] No console errors in Chrome DevTools
+### Step W2 — Responsive validation (test each breakpoint)
+| Breakpoint | Width | Must pass |
+|---|---|---|
+| Mobile S | 375px | No horizontal overflow, CTA visible above fold, text readable |
+| Mobile L | 430px | Same |
+| Tablet | 768px | Layout shifts gracefully from 1-col to 2-col |
+| Desktop | 1280px | Full layout, no text line > 80 chars wide |
+- [ ] No element causes horizontal scroll on mobile
+- [ ] Primary CTA visible above fold on 375px without scrolling
+- [ ] Touch targets ≥ 48px height on mobile
+### Step W3 — Performance validation
+Run via PageSpeed Insights (`https://pagespeed.web.dev/`) or Lighthouse CLI:
+- [ ] Mobile score ≥ 90
+- [ ] LCP (Largest Contentful Paint) < 2.5 s
+- [ ] CLS (Cumulative Layout Shift) < 0.1
+- [ ] All images below fold have `loading="lazy"`
+- [ ] Hero image has `<link rel="preload" as="image">` in `<head>`
+- [ ] No render-blocking scripts without `defer` or `async`
+- [ ] `@media (prefers-reduced-motion: reduce)` present in CSS
+If running Lighthouse CLI: `lighthouse {url} --output=json --only-categories=performance`
+### Step W4 — SEO / LLMO validation
+- [ ] Single `<h1>` per page
+- [ ] `<meta name="description">` present and 150–160 chars
+- [ ] `<link rel="canonical">` present and correct
+- [ ] OG tags: `og:title`, `og:description`, `og:image` (1200×630), `og:url`
+- [ ] JSON-LD schema present before `</body>`
+- [ ] `/robots.txt` accessible and allows crawling
+- [ ] `/sitemap.xml` accessible and valid XML
+- [ ] `/llms.txt` present (LLMO discoverability)
+### Step W5 — Tracking validation
+Verify with Meta Pixel Helper browser extension or equivalent:
+- [ ] Meta Pixel `PageView` fires on page load (if Pixel ID configured)
+- [ ] `fbq('init', 'PIXEL_ID')` called before any `fbq('track', ...)` call
+- [ ] GTM fires on page load (if GTM container configured)
+- [ ] UTM parameters captured in `sessionStorage` when visiting with `?utm_source=test`
+- [ ] UTM values injected as hidden fields on form submit
+- [ ] `Lead` event fires on form submit (if Pixel configured)
+If Pixel ID or GTM container is `PENDING` in the spec, flag as `[W5-PENDING]` — not a blocking failure.
+### Step W6 — Cross-browser validation
+Test in:
+- [ ] Chrome (latest)
+- [ ] Safari (latest, or iOS Safari on mobile)
+- [ ] Firefox (latest)
+Known cross-browser issues to check:
+- CSS `backdrop-filter` not supported in older Firefox — check fallback
+- CSS `clamp()` works in all modern browsers — verify if targeting IE
+- GSAP and AnimeJS work in all modern browsers — verify CDN loads
+- `gap` in Flexbox not supported in Safari < 14 — use `margin` fallback
+### Step W7 — Conversion quality checks
+- [ ] Single primary action per section (no competing CTAs)
+- [ ] Primary CTA uses action verb (not "Learn More" or "Click Here")
+- [ ] Trust signals visible before the first CTA (social proof, logos, testimonials, or stats)
+- [ ] Form fields: only fields absolutely necessary (fewer fields = higher conversion)
+- [ ] H1 communicates the value proposition, not just the product name
+- [ ] No dead whitespace sections with no clear purpose
+### Web validation report format
+```
+## Web Validation Report — [Page/Project] — [Date]
+### W1 Functional: ✓ PASS | ✗ FAIL (list issues)
+### W2 Responsive: ✓ PASS | ✗ FAIL (list breakpoints with issues)
+### W3 Performance: Score [mobile] / [desktop] — LCP [ms] — CLS [score]
+### W4 SEO/LLMO: [N]/8 checks passed
+### W5 Tracking: [N]/6 checks passed — [PENDING items noted]
+### W6 Cross-browser: ✓ Chrome ✓ Safari ✓ Firefox | issues: [list]
+### W7 Conversion: [N]/6 checks passed
+### Critical (blocks launch)
+- [issue]: [location] → [fix]
+### Important (degrades conversion)
+- [issue]: [location] → [fix]
+### VERDICT: LAUNCH-READY | NEEDS-FIXES | BLOCKED
+- LAUNCH-READY: all Critical resolved, W3 score ≥ 90, W4 ≥ 6/8, W5 tracking configured or PENDING
+- NEEDS-FIXES: Critical issues present or performance < 90
+- BLOCKED: broken forms, broken CTAs, or tracking completely absent (not PENDING)
+```
 > **`.aioson/context/` rule:** this folder accepts only `.md` files. Never write `.html`, `.css`, `.js`, or any other non-markdown file inside `.aioson/`.

package/template/.aioson/agents/setup.md CHANGED Viewed

@@ -317,6 +317,21 @@ If no clear signal, use the neutral question format:
 For `api`, `script`, and non-UI-first scopes, keep `design_skill` empty unless the user explicitly asks to register one.
+### Step 5b — Genomes (project_type=site only)
+When `project_type=site`, check if `.aioson/genomes/copywriting.md` exists:
+- If it exists: note it in setup output — `@copywriter` will load it automatically.
+- If it doesn't exist: this is expected for fresh projects. The copywriting genome ships with the AIOSON template. `@copywriter` will use LLM baseline if no genome is available.
+Also check for domain-specific genomes in `.aioson/genomes/` that match the project's domain. Note them if found — they help `@copywriter` write more targeted copy.
+Record genomes in `project.context.md`:
+```yaml
+genomes: ["copywriting"]  # or ["copywriting", "domain-slug"] if domain genome exists
+```
+For non-site projects, omit the `genomes` field or leave it empty unless the user explicitly requests a genome.
 ---
 ### Tech reference — use when user needs to choose
@@ -589,7 +604,8 @@ After setup is complete, always close with the recommended next step. Use the ex
 | project_type | classification | Workflow state | Next agent |
 |---|---|---|---|
-| `site` | any | — | **@ux-ui** |
+| `site` | any | No copy file (`.aioson/context/copy-*.md`) | **@copywriter** → then @ux-ui → then @dev |
+| `site` | any | Copy exists | **@ux-ui** → then @dev |
 | `web_app` | MICRO | No `.aioson/context/prd.md` (including when only `plans/` or `prds/` exist in root) | **@product** |
 | `web_app` | MICRO | `.aioson/context/prd.md` exists, no detailed visual spec | **@sheldon** → then @dev |
 | `web_app` | MICRO | `.aioson/context/prd.md` exists, detailed visual spec | **@ux-ui** → then @dev |

package/template/.aioson/agents/squad.md CHANGED Viewed

@@ -209,6 +209,196 @@ relevant knowledge.
 Only load skills that are directly relevant. A software squad doesn't need
 instagram-feed.md. A YouTube squad doesn't need legal-consulting.md.
+---
+## Visual & UI capability detection (run during squad creation)
+After collecting domain, goal, and output type — before defining executors — check whether the squad produces visual output.
+### Detection triggers
+Any of these signals activates the visual capability offer:
+**Output type signals:**
+- site, landing page, sales page, event page, capture page, squeeze page
+- dashboard, admin panel, web app, SaaS interface
+- HTML deliverable, visual report, design spec
+- UI, UX, interface, layout, screens
+**Domain signals:**
+- marketing agency, digital agency, web agency
+- product design, UX design, visual design
+- e-commerce, lead generation, funnel, conversion
+- branding, identity, visual communication
+**Goal signals:**
+- "create a landing page", "build a site", "design a page"
+- "make a dashboard", "build an interface"
+- "produce pages for clients", "generate layouts"
+- "create pages that convert", "build high-converting pages"
+### When triggered — ask one question
+> "This squad will produce visual output. How do you want UI/UX capability included?
+>
+> **(1) Design skills** — Install `landing-page-forge` and `ui-ux-modern` as squad skills. Executors reference these skills when producing UI output. Lightweight, no dedicated executor.
+>
+> **(2) UI/UX executor** — Add a `@ui-specialist` agent to the squad. It mirrors the `@ux-ui` agent and produces `ui-spec.md` + HTML for every visual deliverable. Heavier, but autonomous.
+>
+> **(3) External @ux-ui** — No UI capability inside the squad. Call `@ux-ui` separately when needed (outside the squad session).
+>
+> **(4) Skip** — No UI capability for this squad."
+### Option 1 — Design skills (lightweight)
+Install the following skills into the squad package:
+```
+.aioson/squads/{slug}/skills/design/landing-page-forge.md  ← copy from .aioson/skills/static/landing-page-forge.md
+.aioson/squads/{slug}/skills/design/ui-ux-modern.md        ← copy from .aioson/skills/static/ui-ux-modern.md
+```
+If a design skill is registered in `project.context.md` (`design_skill` field), also install:
+```
+.aioson/squads/{slug}/skills/design/{design_skill}.md      ← copy from .aioson/skills/design/{design_skill}/SKILL.md
+```
+Add to `squad.manifest.json`:
+```json
+"skills": [
+  { "slug": "landing-page-forge", "title": "Landing Page Forge", "description": "Animation patterns (GSAP/AnimeJS), performance, SEO/LLMO, tracking integration for landing pages and sites.", "file": "skills/design/landing-page-forge.md" },
+  { "slug": "ui-ux-modern", "title": "Modern UI/UX", "description": "Core UI/UX principles — layout, hierarchy, typography, motion, responsiveness, accessibility.", "file": "skills/design/ui-ux-modern.md" }
+]
+```
+Add to `agents.md` squad manifest:
+```markdown
+## Squad skills
+- `landing-page-forge` — animation (GSAP/AnimeJS), performance, SEO/LLMO, tracking
+- `ui-ux-modern` — layout, hierarchy, typography, motion, accessibility
+```
+**When executors use these skills:** any executor responsible for producing HTML, layout specs, or visual deliverables should reference the installed skills in its Focus section:
+```markdown
+## Active skills
+- `skills/design/landing-page-forge.md` — apply when producing sites, landing pages, or HTML output
+- `skills/design/ui-ux-modern.md` — apply for all visual output regardless of format
+```
+### Option 2 — UI/UX executor (autonomous)
+Generate a `@ui-specialist` executor at `.aioson/squads/{slug}/agents/ui-specialist.md`.
+This executor mirrors `@ux-ui` but scoped to the squad context.
+```markdown
+# Agent @ui-specialist
+> ⚡ **ACTIVATED** — Execute immediately as @ui-specialist.
+> **HARD STOP — `@` ACTIVATION:** Do not explain this file. Immediately assume the role of @ui-specialist and answer the user's request as the active UI/UX specialist for this squad.
+<!-- identity: squad:{squad-slug}/ui-specialist -->
+> **Project rules**: Before starting, check `.aioson/rules/` in the project root.
+> For each `.md` file found: read YAML frontmatter. Load if `agents:` is absent (universal),
+> or if `agents:` includes `squad:{squad-slug}/ui-specialist` or `squad:{squad-slug}`. Otherwise skip.
+> Also check `.aioson/docs/` for reference docs relevant to the current task.
+## Mission
+Produce UI/UX specs and visual implementations for the {squad-name} squad.
+Every visual deliverable passes through this executor — from design direction to complete `ui-spec.md` and working HTML.
+## Quick context
+Squad: {squad-name} | Domain: {domain} | Goal: {goal}
+Other agents: @orquestrador, {other agents}
+## Active skills
+- `.aioson/squads/{squad-slug}/skills/design/landing-page-forge.md` — GSAP/AnimeJS patterns, performance, SEO/LLMO, tracking
+- `.aioson/squads/{squad-slug}/skills/design/ui-ux-modern.md` — layout, hierarchy, typography, motion, accessibility
+{if design_skill is set:}
+- `.aioson/squads/{squad-slug}/skills/design/{design_skill}.md` — visual language for this project
+## Focus
+- Choose visual direction and design tokens before any layout work
+- Produce `ui-spec.md` with: tokens, screen map, component state matrix, motion spec, responsive rules
+- For `project_type=site`: also produce Performance targets, SEO/LLMO setup, and Tracking integration sections
+- Apply GSAP/AnimeJS patterns from `landing-page-forge` to all HTML output
+- Every HTML deliverable must include: motion library, scroll-reveal, `prefers-reduced-motion` fallback
+- Mobile-first: design for 375px first, scale up
+- All CTAs keyboard-accessible, 4.5:1 contrast minimum
+## Motion standard (apply to every HTML output)
+- **Dashboard/app**: CSS-only or AnimeJS — hover transitions, staggered card entrances, skeleton loading
+- **Site/landing page**: GSAP + ScrollTrigger — hero sequence, scroll-reveal stagger, magnetic CTA, horizontal scroll when relevant
+- Always: `@media (prefers-reduced-motion: reduce)` at `:root` level
+## Response standard
+- Never produce placeholder copy ("Lorem ipsum", "[Your headline]") — write real content based on context
+- Deliver `ui-spec.md` before writing any HTML
+- After producing HTML, run the quality checks: swap test, squint test, signature test, motion test
+- State which design direction was chosen and why
+## Hard constraints
+- Do not combine multiple design skill visual systems in the same deliverable
+- Do not produce HTML without first stating the design direction and token decisions
+- All deliverables go to `output/{squad-slug}/`
+- If the squad has a registered `design_skill`, that skill is the sole visual source of truth
+## Output contract
+- `ui-spec.md` → `output/{squad-slug}/ui-spec-{session-id}.md`
+- HTML deliverables → `output/{squad-slug}/{deliverable-slug}.html`
+- Updated by @orquestrador in the session HTML at `output/{squad-slug}/latest.html`
+```
+Add to `squad.manifest.json` executors:
+```json
+{
+  "slug": "ui-specialist",
+  "title": "UI/UX Specialist",
+  "type": "assistant",
+  "role": "Produces UI specs, design tokens, and working HTML for all visual deliverables.",
+  "file": ".aioson/squads/{squad-slug}/agents/ui-specialist.md",
+  "deterministic": false,
+  "usesLLM": true,
+  "modelTier": "powerful",
+  "behavioralProfile": "compliant-dominant",
+  "skills": ["landing-page-forge", "ui-ux-modern"],
+  "genomes": []
+}
+```
+Add to orchestrator routing guide:
+```markdown
+- **Visual / UI / layout requests** → @ui-specialist (design direction + spec + HTML)
+```
+### Option 3 — External @ux-ui
+No changes to the squad. Add a note in `agents.md`:
+```markdown
+## External agents
+- `@ux-ui` (AIOSON core) — for formal UI/UX specs, use `/ux-ui` outside this squad session
+```
+### After visual capability decision
+Whatever option was chosen, record it in `squad.manifest.json`:
+```json
+"uiCapability": {
+  "mode": "skills | executor | external | none",
+  "skills": ["landing-page-forge", "ui-ux-modern"],
+  "executor": "ui-specialist"
+}
+```
+And in `docs/design-doc.md`:
+```markdown
+## UI/UX Capability
+Mode: {skills | executor | external | none}
+{If skills: list installed skills and which executors reference them}
+{If executor: @ui-specialist handles all visual deliverables}
+{If external: @ux-ui called outside squad sessions}
+```
 ## Squad creation flow
 Ask for the core information in one block first. Only ask follow-up questions if there are meaningful gaps.

package/template/.aioson/agents/ux-ui.md CHANGED Viewed

@@ -22,7 +22,8 @@ These directories are **optional**. Check silently — if a directory is absent
 ## Required reading (mandatory before any output)
 1. Read `design_skill` from `.aioson/context/project.context.md` first. If it is set, load `.aioson/skills/design/{design_skill}/SKILL.md` and only the references it specifies for the current task.
 2. If `project_type=site`, read `.aioson/skills/static/static-html-patterns.md` (the index, ~100 lines). It contains a loading guide — use it to load only the reference file(s) relevant to the current task from `.aioson/skills/static/static-html-patterns/`. Never load all reference files at once. Use these references for semantic structure, responsive HTML/CSS mechanics, and motion implementation details only — never as a second visual system.
-3. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules in this file only.
+3. If `project_type=site`, also load `.aioson/skills/static/landing-page-forge.md`. Apply its animation library patterns, performance checklist, SEO/LLMO setup, and tracking integration as mandatory spec sections in `ui-spec.md`. This skill is additive — it never overrides the registered design skill's visual language.
+4. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules in this file only.
 4. **ABSOLUTE RULE — ONE SKILL ONLY:** When `design_skill` is set, load **exclusively** `.aioson/skills/design/{design_skill}/SKILL.md` and the references it specifies. Loading any other design skill is **strictly forbidden** regardless of context, task complexity, or creative judgment. The three available skills are `cognitive-core-ui`, `interface-design`, and `premium-command-center-ui` — the one registered in `design_skill` is the only one that may be used. No exceptions.
 ## Three.js / WebGL detection
@@ -422,10 +423,165 @@ Identity test: remove the product name — can someone still identify what this
 ---
+## Motion & Interaction spec (mandatory in every ui-spec.md)
+Produce this section in `ui-spec.md` for every project — dashboards, apps, and sites. Scale the content to the context; never omit the section.
+### Step M1 — Choose animation tier
+Pick ONE tier based on project type and complexity:
+| Tier | When | Library |
+|------|------|---------|
+| **CSS-only** | Micro (single page, minimal interaction) | Vanilla CSS keyframes |
+| **AnimeJS** | SMALL/MEDIUM apps, lightweight sites, counter animations, SVG | `animejs` (9 KB) |
+| **GSAP** | MEDIUM sites/landing pages, horizontal scroll, complex timelines, magnetic effects | `gsap` + `ScrollTrigger` |
+Default rules:
+- Dashboard → CSS-only unless scroll-triggered panels are required
+- App (SMALL/MEDIUM) → CSS-only or AnimeJS
+- Site/landing page → GSAP preferred; fallback to AnimeJS for lightweight pages
+### Step M2 — Define motion posture per surface
+State explicitly in the spec which posture each surface follows:
+| Surface | Dashboard/App posture | Site posture |
+|---------|----------------------|--------------|
+| Page entrance | Staggered fadeInUp, 350–600ms | Hero timeline sequence (GSAP), 0–800ms |
+| Cards | Hover: translateY(-2px) + shadow, 150ms | Scroll-reveal stagger, 600ms |
+| Buttons | Hover: translateY(-1px) + glow, 150ms | Same + magnetic effect on CTA |
+| Data / counters | Count-up via AnimeJS on first viewport | Same |
+| Horizontal sections | N/A | GSAP ScrollTrigger scrub |
+| Modals | scaleIn 300ms | Same |
+| Reduced motion | `prefers-reduced-motion: reduce` removes all transform/opacity transitions | Same — required |
+### Step M3 — Spec output block (write this to ui-spec.md)
+```markdown
+## Motion & Interaction
+### Library
+- Tier: [CSS-only | AnimeJS | GSAP]
+- CDN: [exact script tag, or npm package name + version]
+- Plugins: [e.g., ScrollTrigger — include only if used]
+### Patterns in use
+- [Pattern name]: [surface, behavior, duration, curve]
+- [e.g., Scroll-reveal stagger]: [Feature cards, fadeInUp 600ms cubic-bezier(0.16,1,0.3,1), 80ms between items]
+- [e.g., Magnetic CTA]: [Primary hero button, follows cursor at 35% strength, elastic return on leave]
+### Reduced-motion fallback
+All transform and opacity transitions set to 0.01ms via `prefers-reduced-motion: reduce` — applied at `:root` level.
+### Performance budget
+- Total animation JS: < [X KB] gzipped
+- No animation on critical render path — all GSAP/AnimeJS loaded `defer`
+- `will-change: transform` only on elements with active GSAP tweens
+```
+### For `project_type=site` — add these three extra blocks to ui-spec.md:
+**Performance checklist** (reference `landing-page-forge.md` §3 for full list):
+```markdown
+## Performance targets
+- LCP: < 2.5 s (mobile, throttled 3G)
+- CLS: < 0.1
+- PageSpeed mobile: ≥ 90
+- Images: WebP, lazy-loaded below fold, preload hero image
+- Fonts: self-hosted or `font-display: swap`; only weights actually used
+- JS: defer all non-critical; remove unused CSS
+```
+**SEO / LLMO** (reference `landing-page-forge.md` §4):
+```markdown
+## SEO / LLMO
+- H1: [exact text — one per page]
+- Meta description: [exact text — 150–160 chars]
+- Canonical URL: [full URL]
+- JSON-LD schema: [type — e.g., WebPage, Event, Product]
+- OG image: 1200×630, path: [path]
+- /robots.txt: generated
+- /sitemap.xml: generated
+- /llms.txt: generated (brand description + key offerings)
+```
+**Tracking** (reference `landing-page-forge.md` §5):
+```markdown
+## Tracking integration
+- Meta Pixel ID: [ID or PENDING]
+- Advanced Matching: [yes/no]
+- Standard events: PageView (auto), Lead (form submit), [others]
+- GTM container: [ID or PENDING]
+- UTM capture: sessionStorage + cookie, injected into all forms on submit
+- Cookie consent: [yes/no — required by LGPD if collecting Brazilian users]
+```
+---
 ## Landing page mode (project_type=site)
 When `project_type=site`, activate this mode after design direction is chosen.
+### Marketing context intake (run before design direction)
+Before choosing any design direction, answer these four questions. If the user hasn't provided them, ask in a single block:
+1. **Page type** — What is this page exactly?
+   - Capture/squeeze page (single CTA, minimum distractions)
+   - Sales/long-form page (full persuasion sequence)
+   - Event page (date, location, tickets)
+   - Institutional/brand page (trust, credibility)
+   - Newsletter/community page (soft commitment)
+   - Product/feature page (features + pricing)
+2. **Traffic source** — Where will visitors come from?
+   - Paid (Meta Ads, Google Ads, TikTok)
+   - Organic (SEO, social, email)
+   - Direct/warm audience (existing community, email list)
+   - Mixed
+3. **Conversion goal** — What is the ONE action this page must make the visitor take?
+   (One specific action — not "sign up and also buy and also share")
+4. **Copy status** — Is the copy (headline, body text, CTAs) already written?
+   - Yes → paste it here or point to the file
+   - No → activate `@copywriter` first. It reads the project context autonomously and generates the full copy. When done, it saves to `.aioson/context/copy-{slug}.md` and tells you to resume @ux-ui. Do NOT design without copy. Layout that exists before copy is made will be remade to fit the copy.
+**Copy gate rule:** If copy does not exist, STOP. Do not produce visual direction, tokens, or HTML. Tell the user:
+> "Copy must exist before layout. Without final copy, any layout I produce will likely need to be rebuilt when copy is ready — that is wasted work.
+> Activate `@copywriter` — it will read the project context and generate all copy autonomously. When it finishes, it will tell you to resume @ux-ui with the copy file path."
+The exception: if the user explicitly says "I know the copy will change, design a template structure" — then proceed, but note every text placeholder with `[COPY: description of what goes here]` and flag them all at the end of the spec.
+### Reading the copy file (when copy exists)
+When `.aioson/context/copy-{slug}.md` exists, read it before designing. The copy document uses a **5-Act narrative structure** for marketing/sales pages:
+| Copy Act | Maps to UI section |
+|---|---|
+| **Act 1 — Hero** | Hero section: full viewport, headline, subheadline, CTA, social proof strip |
+| **Act 2 — Authority / Story** | Authority section: expert credentials, logos, transformation story |
+| **Act 3 — Mechanism** | 2 sections: "Why nothing else worked" + "How [Method] works" — may include diagrams, visual demonstrations |
+| **Act 4 — Offer** | Offer section: component stack, bonuses, price anchoring, guarantee, CTA |
+| **Act 5 — Close** | Close section: Two Paths contrast, final CTA, FAQ, recovery elements |
+The copy file also contains:
+- **One Belief statement** — the central psychological thesis. The visual design should reinforce this belief at every touchpoint.
+- **Audience awareness level** — cold/warm/hot determines how much proof and explanation the layout needs.
+- **Congruence notes** — if ad context was provided, the visual must match the ad's tone and imagery.
+**Design rules derived from copy:**
+- The page section ORDER follows the act order — never rearrange acts for aesthetic reasons
+- Headline, subheadline, and CTA text come from the copy file verbatim — design around the text, not the other way around
+- If the copy specifies "visual metaphor" or "diagram" in Act 3, create a layout slot for it
+- The offer section must support value anchoring (crossed-out prices, component list with values, bonus callouts)
+- The FAQ section handles objections — design it for scannability, not as an afterthought at the bottom
+If the copy file uses a different structure (product/SaaS format without 5 Acts), follow whatever structure it defines.
+Once marketing context is captured, proceed to design direction — the context informs which direction fits.
 ### Hero law (non-negotiable)
 > **The hero is NEVER a grid of cards or a list of steps.**
@@ -622,6 +778,8 @@ If the user explicitly proceeds without a registered `design_skill`, use the fal
 - **Squint test**: does visual hierarchy survive when blurred?
 - **Signature test**: can you name 5 specific decisions unique to this product?
 - **"Wow" test** (landing pages only): would someone screenshot this and share it? If no — revise.
+- **Motion test**: is there a `## Motion & Interaction` section in `ui-spec.md`? Is the library tier chosen? Is `prefers-reduced-motion` covered? If any answer is no — the spec is incomplete.
+- **Site completeness test** (`project_type=site`): are `## Performance targets`, `## SEO / LLMO`, and `## Tracking integration` sections present in `ui-spec.md`? If no — add them before delivering.
 ## Self-critique before delivery
 1. Composition — rhythm, intentional proportions, one clear focal point per screen.
@@ -635,13 +793,21 @@ If the user explicitly proceeds without a registered `design_skill`, use the fal
 **Creation mode — project_type=site:**
 - `index.html` in the project root — complete, working HTML with embedded CSS and real content
-- `.aioson/context/ui-spec.md` — design tokens, decisions, and handoff notes for @dev
+- `.aioson/context/ui-spec.md` — design tokens, decisions, handoff notes for @dev, and the mandatory sections below
 - `.aioson/context/project.context.md` — update `design_skill` if the selection was confirmed during this session
 **Creation mode — project_type ≠ site:**
-- `.aioson/context/ui-spec.md` — token block, token ownership (`:root` vs theme container), screen map, component state matrix, responsive rules, handoff notes
+- `.aioson/context/ui-spec.md` — token block, token ownership (`:root` vs theme container), screen map, component state matrix, responsive rules, handoff notes, and the mandatory sections below
 - `.aioson/context/project.context.md` — update `design_skill` if the selection was confirmed during this session
+**Mandatory sections in every ui-spec.md (all project types):**
+- `## Motion & Interaction` — library tier, patterns in use (surface + behavior + duration + curve), reduced-motion fallback, performance budget
+**Additional mandatory sections for `project_type=site`:**
+- `## Performance targets` — LCP, CLS, PageSpeed targets, image/font/JS strategy
+- `## SEO / LLMO` — H1, meta description, canonical, JSON-LD type, OG image, /robots.txt, /sitemap.xml, /llms.txt
+- `## Tracking integration` — Pixel ID, GTM container, events, UTM capture strategy
 **Delivery confirmation (mandatory after every session):**
 After writing all files, output this exact block:
 ```