Skill: corbin-breton/design-engineering (version 1.2.0)

--- name: design-engineering description: Orchestrate iterative design and frontend engineering work through research, planning, sub-agent execution, and validation loops. Use when a visual/UI task requires multiple iterations, when the first implementation needs refinement based on feedback, when choosing between competing technical approaches (Canvas vs SVG vs CSS), or when coordinating sub-agents on design-heavy work. Covers animation architecture decisions, progressive enhancement patterns, performance-aware rendering choices, and the research→plan→execute→validate workflow. Complements frontend-design (which handles aesthetics) by adding engineering discipline, iteration management, and technical decision-making. version: 1.2.0 --- # Design Engineering Orchestrate design-heavy frontend work that requires iteration, technical decisions, and validation. This skill is about the *process* — how to research, plan, build, validate, and refine — not the aesthetics (use `frontend-design` for that). ## When to Use - Visual work that will take multiple iterations to get right - Choosing between technical approaches (Canvas vs SVG vs CSS, etc.) - Coordinating sub-agents on parallel design/engineering tasks - Refining an implementation based on user feedback - Any frontend work where "build it and ship" isn't enough ## Scope & Safety - All file operations stay within the user's project directory — no absolute paths outside the project root - Sub-agents operate within the project scope defined by the orchestrator and must not access files outside it - Sub-agent outputs (file writes, research findings) are confined to the project working directory - No credentials or external services are required - Playwright (when used for screenshots) connects only to `localhost` dev servers — never to external URLs - No data is exfiltrated or transmitted to external endpoints; all work is local ## The Iteration Loop Every design-engineering task follows this cycle: ``` Research → Plan → Approve → Execute → Validate → Feedback → Refine ``` ### 1. Research Phase Before touching code, understand the problem space. Spawn 2-3 research sub-agents in parallel with different lenses: - **Inspiration/reference** — find examples of what we're trying to achieve - **Technical approaches** — what tools/techniques solve this class of problem - **Constraints** — performance, browser support, accessibility, progressive enhancement Research agents should write findings to files within the project's working directory so context is preserved across iterations. ### 2. Plan Phase Synthesize research into a concrete plan. Present to user for approval before executing. The plan should include: - Architecture decision with rationale (not just "use X" but "use X because Y fails at Z") - Layer/component breakdown - What gets removed, what gets added, what stays - Pre-mortem: "what would cause this to fail?" - Estimated sub-agent tasks - **Horizon estimate:** Count estimated steps across all sub-agents. If > 40 steps total, decompose into sub-phases of ≤ 20 steps. If 20–40 steps, insert a midpoint quality checkpoint (screenshot + integration check before proceeding). Under 20 steps, execute directly. This prevents quality collapse on complex design tasks. ### 3. Execute Phase Dispatch sub-agents with focused, context-minimal tasks. Key rules in `references/subagent-patterns.md`. ### 4. Validate Phase After sub-agents complete, the orchestrator MUST validate. Build check is necessary but not sufficient. Check integration points — see `references/validation-checklist.md`. ### 5. Feedback → Refine Ship to user for review. Expect 2-5 iterations on visual work. Each iteration: 1. Screenshot the live result (use Playwright if available) 2. Identify specific issues from feedback 3. Make targeted fixes (don't rebuild from scratch each time) 4. Validate and redeploy ## Technical Decision Framework When choosing between rendering approaches, read `references/rendering-decisions.md`. Quick heuristic: | Need | Use | |------|-----| | Static decorative pattern | CSS `background-image` with SVG data URI | | <100 authored animated elements | Inline SVG + CSS animations | | Procedural generation, >100 elements, full-page coverage | Canvas 2D | | 3D, heavy particle systems, post-processing | Three.js/WebGL (last resort — heavy) | ## Progressive Enhancement Stack Every visual enhancement must degrade gracefully: 1. CSS baseline (always works, no JS) 2. JS-enhanced layer fades in on top 3. `prefers-reduced-motion` → skip animations entirely 4. Low-end device detection → reduce complexity 5. Light/dark theme awareness ## Glass-Panel Pattern For content floating over animated backgrounds: ```css .card { background: color-mix(in srgb, var(--bg-card) 50-60%, transparent); backdrop-filter: blur(8-12px); -webkit-backdrop-filter: blur(8-12px); } ``` Lets animation show through while keeping text readable. Adjust blur and opacity based on background intensity. ## References - `references/subagent-patterns.md` — How to dispatch and validate sub-agent work - `references/validation-checklist.md` — Post-execution checks that catch integration bugs - `references/rendering-decisions.md` — Canvas vs SVG vs CSS decision guide with production lessons

path: references/rendering-decisions.md
content: # Rendering Technology Decisions

Production-tested guidance for choosing between CSS, SVG, and Canvas for visual effects.

## Decision Matrix

| Criteria | CSS background-image | Inline SVG | Canvas 2D | WebGL/Three.js |
|----------|---------------------|------------|-----------|----------------|
| Static patterns | ✅ Best | ✅ Good | Overkill | Overkill |
| <50 animated elements | ❌ Jittery | ✅ Best | Good | Overkill |
| 50-200 animated elements | ❌ | ⚠️ DOM overhead | ✅ Best | Good |
| >200 animated elements | ❌ | ❌ Jank | ✅ Best | ✅ Best |
| Procedural generation | ❌ | ❌ Impractical | ✅ Best | ✅ Good |
| Parallax scroll | ❌ Broken on iOS | ⚠️ Complex | ✅ Native | ✅ Native |
| Glow/blur effects | Limited | ✅ SVG filters | ✅ shadowBlur | ✅ Post-processing |
| No-JS fallback | ✅ Built in | ✅ Built in | ❌ Needs JS | ❌ Needs JS |
| HiDPI | ✅ Auto | ✅ Auto | Manual (dpr) | Manual |
| Bundle size | 0KB | 0KB | 0KB (native) | 500KB+ (Three.js) |

## Critical Lesson: SVG in background-image Cannot Animate

**This is the #1 trap.** SVG embedded as `background-image: url("data:image/svg+xml,...")` is sandboxed:
- Browser treats it as a static image (security restriction)
- SMIL animations may run but execute on main thread, outside compositor → jitter
- CSS animations on SVG elements inside background-image are NOT GPU-composited
- `animateMotion`, `animate`, CSS `@keyframes` — all unreliable in this context

**Rule**: Animated SVG must be inline `<svg>`. Static-only SVG can be background-image.

## SVG `preserveAspectRatio` Pitfall

When an SVG viewBox doesn't match its container:
- `preserveAspectRatio="none"` → stretches content. Circles become ovals. Paths warp.
- Default (`xMidYMid meet`) → maintains ratio, letterboxes
- `xMinYMin slice` → maintains ratio, crops excess

Always verify when SVG dimensions differ from container dimensions.

## Canvas Parallax Architecture

The proven pattern for full-page animated backgrounds:

```
position: fixed canvas → reads window.scrollY → draws layers at different offsets
```

- Canvas stays fixed, covers viewport
- Each depth layer offsets by `scrollY × layerSpeed`
- Deep: 10% scroll speed, Mid: 25%, Near: 5%
- Wrap with modulo for seamless tiling: `offset = -(scrollY * speed % virtualHeight)`
- Draw everything twice (at offset and offset + virtualHeight) for seamless wrap

## Canvas Resize Trap

`buildScene()` on resize randomizes all procedurally-generated elements → visual jump.

Fix:
```js
function setupCanvas(regenerateScene) {
  // Always resize the canvas dimensions
  // Only regenerate scene geometry if regenerateScene is true
}
// On resize: only regenerate on width change, not height change
// Mobile address bars cause height changes constantly
```

## CSS Scroll Parallax (`animation-timeline: scroll()`)

Modern alternative to JS parallax. Runs on compositor thread — zero jank.

Browser support (March 2026): Chrome ✅, Edge ✅, Samsung ✅, Safari 26+ ✅, Firefox ❌ (flag only).

Pattern:
```css
@supports (animation-timeline: scroll()) {
  .bg-layer { animation: drift linear both; animation-timeline: scroll(root block); }
}
```
Always provide JS fallback for Firefox (~25% of users).

## Performance Rules of Thumb

- Canvas: 50-100 paths + 25-40 pulses = imperceptible on modern devices
- SVG: performance degrades noticeably above 100-200 animated elements
- `shadowBlur`: batch all glow draws, set once, reset once. Per-element toggle is expensive.
- `navigator.hardwareConcurrency < 4` → halve element counts
- `contain: layout paint style` on canvas wrapper for browser optimization hints


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)