e51686a3d4
Specifies the V1 animation system end-to-end. Authored after two Deep Research passes (preserved as ANIMATION_V1_RESEARCH.md and ANIMATION_V1_DESIGN_DECISIONS.md for provenance). ANIMATION_V1.md covers: - Hard constraints: Chrome Heavy Ad Intervention (4MB / 15s burst / 60s total CPU), composite-only animation, 150KB initial-load cap, GSAP via s0.2mdn.net CDN, free-tier only. - Custom JSON schema (not Lottie) — block-based timeline, absolute start times, preset references only, no inline keyframes. Designed for AI authoring and human-readable diffs. - 25-preset library across entrance / exit / emphasis / typography / mask / list categories. Each preset specifies start state, end state, default ease, default duration, and split/mask requirements. - 9-category easing matrix using GSAP stock eases; bounce, slow, rough, and circ excluded from the V1 surface. - Mask system: mask is a property on the masked layer (not a standalone layer). clip-path mandatory over interactive elements to prevent ghost-click failures. Konva ↔ HTML parity table. - Per-character animation: SplitType at render time, Dropflow at spec time, automated aria-label / aria-hidden contract, 150-node ceiling enforced by QA gate. - Animated bounding-box math: discrete sampling at 30 fps, unionBoundingBox() called from asset selection, render worker, and QA gate. Adds required_source_size to ResolvedLayer. - 12 QA gates (G1-G12) covering schema, performance, asset, accessibility, and parity. ARCHITECTURE.md updates: - Forward-notes section at the top pointing to ANIMATION_V1.md and RESOLVED_FEED.md, matching the existing Part 7 forward-note style. - Inline forward note in the Part 3 animation stack block. - Old content preserved as historical record. Decisions baked in (resolved during draft): - Loops are global (max 3), not per-block. Per-block loops invite nested-infinite-loop bugs in AI-generated specs. - Block triggers are time-anchored only. Event/interaction triggers wait for V2 rich media. - blur_in and shake_horizontal dropped from the 27-preset research list. Blur is a video pattern; shake reads as a rendering error. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
||
|---|---|---|
| apps/web | ||
| feeds | ||
| infra/fonts | ||
| packages | ||
| patches | ||
| scripts | ||
| .env.example | ||
| .gitignore | ||
| .nvmrc | ||
| ANIMATION_V1.md | ||
| ANIMATION_V1_DESIGN_DECISIONS.md | ||
| ANIMATION_V1_RESEARCH.md | ||
| ANTI_PATTERNS.md | ||
| ARCHITECTURE.md | ||
| Avoiding UX Failure FIRST.md | ||
| BUILD_SEQUENCE.md | ||
| CLAUDE.md | ||
| EXECUTIVE_SUMMARY.md | ||
| FRUSTRATION_LIST.md | ||
| INTERACTION_STANDARDS.md | ||
| package.json | ||
| PHASE_1_BRIEF.md | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| PROJECT_STRUCTURE.md | ||
| README.md | ||
| RESEARCH.md | ||
| RESOLVED_FEED.md | ||
| SLICE_DEVIATIONS.md | ||
| tsconfig.base.json | ||
| turbo.json | ||
| UX_ACCEPTANCE_CRITERIA.md | ||
| VERTICAL_SLICE.md | ||
Banner Studio — Claude Code Briefing Bundle
This bundle contains everything needed to begin building the agentic HTML5 banner production platform with Claude Code, plus an executive summary for non-engineering audiences.
What's in here
For Claude Code (drop these in the project root):
CLAUDE.md— Read on every session. Locked decisions, conventions, what not to do. The operational source of truth.PROJECT_STRUCTURE.md— Monorepo layout, package by package, file by file. Use as the scaffolding target.PHASE_1_BRIEF.md— Step-by-step prompts for the first week of work. Foundation phase, no UI yet.BUILD_SEQUENCE.md— All 14 phases with exit criteria. Expand each phase into Claude Code prompts as you reach it.ARCHITECTURE.md— The full architecture spec (the document you authored). Source of truth for data shapes, algorithms, and rationale.RESEARCH.md— Research backing the locked decisions. Reference for the "why" behind stack and pattern choices.
For leadership and stakeholder decks:
EXECUTIVE_SUMMARY.md— Plain-prose briefing. The PPT source document. Sections map naturally to slides.
How to start
-
Create the project repo. Copy
CLAUDE.md,PROJECT_STRUCTURE.md,PHASE_1_BRIEF.md,BUILD_SEQUENCE.md,ARCHITECTURE.md, andRESEARCH.mdinto the root. -
Open Claude Code in that directory.
-
First prompt:
Read
CLAUDE.md, thenPHASE_1_BRIEF.md. We are at Step 1.1. Begin. -
Work through Phase 1 step by step. Do not skip the unit tests on the layout engine. Do not skip Step 1.9 (the type-safety proof) — it confirms the contract chain works before you build anything substantial on top of it.
-
At Phase 1 exit, tag
v0.1.0-foundationand start Phase 2.
A note on the documents
CLAUDE.md is intentionally opinionated. It states what is locked, what is forbidden, and where to look for the why. This is the right shape for a Claude Code briefing — it tells the model what decisions have already been made so it doesn't waste context re-deriving them, and it tells it where to look when a deeper question comes up.
PHASE_1_BRIEF.md is the only phase with literal prompts pre-written. As you complete Phase 1 and start Phase 2, expand that phase's summary in BUILD_SEQUENCE.md into a similar step-by-step brief. The first phase needed prompts because zero-state is the hardest moment; later phases can lean on the patterns established in Phase 1.
EXECUTIVE_SUMMARY.md is written to be read by people who will never touch the code. It's the document that gets adapted into a 10-slide deck or a one-pager for a stakeholder conversation. Sections are sized to map to slides without further editing.