AgentCompany/builtin-skills/frontend-design/design-dna/references/generation-guide.md

Generation Guide

How to use a completed Design DNA JSON to generate designs in Phase 3. Covers all three dimensions.

Priority Order

When generating a design from DNA JSON + content:

1. Color & Typography — define 80% of visual identity
2. Spacing & Layout — structural rhythm
3. Shape & Elevation — surface treatment
4. Design Style qualitative fields — mood, personality, composition approach
5. Visual Effects — special rendering layer (Canvas, WebGL, shaders, etc.)
6. Motion & Interaction — enhance after static layout and effects are solid

Dimension 1: design_system → Code

Tailwind CSS / Utility-First

color.primary.hex        → --color-primary / bg-[hex]
typography.font_families → font-family config
spacing.scale            → spacing config values
shape.border_radius      → rounded-{sm|md|lg|full}
elevation.levels         → shadow-{sm|md|lg}

Plain CSS / CSS Variables

Generate a :root block with all design tokens:

:root {
  --color-primary: {color.primary.hex};
  --color-secondary: {color.secondary.hex};
  --color-accent: {color.accent.hex};
  --font-heading: {typography.font_families.heading};
  --font-body: {typography.font_families.body};
  --radius-sm: {shape.border_radius.small};
  --radius-md: {shape.border_radius.medium};
  --radius-lg: {shape.border_radius.large};
  --shadow-low: {elevation.levels.low};
  --shadow-med: {elevation.levels.medium};
  --shadow-high: {elevation.levels.high};
  --ease: {motion.easing};
  --duration-micro: {motion.duration_scale.micro};
  --duration-normal: {motion.duration_scale.normal};
  --duration-macro: {motion.duration_scale.macro};
  /* ... map all tokens */
}

Component Decisions

• components.button_style → button classes and variants
• components.card_style → card container treatment
• components.navigation_pattern → nav component choice
• interaction_feel.hover_behavior → :hover / :focus states
• motion.easing + motion.duration_scale → transition properties

Dimension 2: design_style → Subjective Decisions

DNA Field	Guides
aesthetic.mood	Overall emotional feeling — warm tones, cool precision, etc.
visual_language.whitespace_usage	padding/margin generosity
visual_language.contrast_level	How much elements pop vs. blend
composition.hierarchy_method	What tool to use for emphasis
composition.balance_type	Symmetric layout vs. dynamic asymmetry
imagery.graphic_elements	Decorative SVGs, gradients, patterns
brand_voice_in_ui.tone	Microcopy phrasing
interaction_feel.microinteraction_density	How many hover/click effects

Dimension 3: visual_effects → Special Rendering

Technology Selection by Performance Tier

Tier	Technologies	When to Use
lightweight	CSS animations, SVG SMIL, vanilla JS	overview.performance_tier = "lightweight"
medium	Canvas 2D, GSAP, Lottie, anime.js	overview.performance_tier = "medium"
heavy	Three.js, custom GLSL, Pixi.js, WebGL	overview.performance_tier = "heavy"

Implementation Patterns

Background Effects

"none"              → skip
"gradient-animation" → CSS @keyframes on linear-gradient or conic-gradient
"noise-field"       → Canvas 2D with Perlin/simplex noise
"mesh-gradient"     → SVG <mesh> or canvas interpolation
"video-bg"          → <video autoplay muted loop> with poster fallback
"generative-art"    → Canvas 2D or WebGL generative algorithms

Particle Systems

When particle_systems.enabled: true:

• For count < 100 and no complex physics → vanilla JS + Canvas 2D
• For count >= 100 or complex interaction → consider Pixi.js or Three.js Points
• Map interaction ("mouse-repel", "mouse-attract") to pointer event handlers
• Use requestAnimationFrame loop; include destroy/cleanup on unmount

3D Elements

When 3d_elements.enabled: true:

• Default to Three.js unless DNA specifies otherwise
• Apply lighting, camera, materials from params
• Add post_processing effects via EffectComposer
• Handle resize with ResizeObserver
• Load via CDN: https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js

Shader Effects

When shader_effects.enabled: true:

• Create vertex/fragment shaders based on type
• Pass uniforms from params (time, resolution, mouse position)
• For "noise-distortion": use noise functions matching noise_type
• Animate via requestAnimationFrame updating u_time uniform

Scroll Effects

• Parallax: Use transform: translateY() with scroll offset × layer speed
• Scroll-triggered: Use IntersectionObserver with threshold array
• Scrub behavior: If "scrubbed", animation progress = scroll progress. If "triggered", play once on enter.

Text Effects

"split-letter-animate" → Split text into <span> per char/word, stagger CSS animation
"typewriter"           → CSS steps() or JS interval revealing chars
"glitch"               → Layered clip-path + color offset animation
"gradient-fill"        → background-clip: text with animated gradient
"3d-extrude"           → text-shadow stack or WebGL text geometry

Cursor Effects

When cursor_effects.enabled: true:

• Hide default cursor: cursor: none
• Create custom cursor element following pointermove
• "magnetic-buttons": Apply transform pull on hover proximity
• "spotlight": Radial gradient mask following cursor
• "trail": Spawn fading elements on move

Glassmorphism / Neumorphism

"glass"             → backdrop-filter: blur({blur_radius}); background: rgba(..., {transparency})
"neumorphic-light"  → Dual box-shadow (light + dark offset) on light bg
"neumorphic-dark"   → Dual box-shadow (inverted) on dark bg
"frosted-layers"    → Stacked blur layers with varying opacity

Canvas Drawings

When canvas_drawings.enabled: true:

• Initialize canvas with width/height matching container
• Use draw_method to select rendering approach
• Animate with requestAnimationFrame
• Handle responsiveness via ResizeObserver

SVG Animations

When svg_animations.enabled: true:

• "path-draw": Animate stroke-dashoffset from path length to 0
• "morph-shapes": Interpolate d attribute between two paths
• "stroke-animation": Animate stroke properties (dasharray, width, color)

Fallback Strategy

Always implement the fallback defined in overview.fallback_strategy:

// Example: reduce to CSS on low-end devices
const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
const isLowEnd = navigator.hardwareConcurrency <= 2;
if (prefersReduced || isLowEnd) {
  // Apply fallback: static CSS version, disable canvas/WebGL
}

Output Format

Generate output as a single self-contained HTML file with inline CSS and JS (unless user specifies a framework). Include:

1. CSS custom properties block from design_system tokens
2. Component styles from design_system.components + design_style
3. Layout structure per design_system.layout
4. Content populated from user-provided content
5. Visual effects implemented per visual_effects specification
6. Animations/transitions if design_system.motion.philosophy is not "none"
7. Fallback handling for effects

For heavy effects requiring external libraries, load via CDN <script> tags:

<!-- Three.js -->
<script type="importmap">{"imports":{"three":"https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js"}}</script>

<!-- GSAP -->
<script src="https://cdn.jsdelivr.net/npm/gsap@latest/dist/gsap.min.js"></script>

<!-- Lottie -->
<script src="https://cdn.jsdelivr.net/npm/lottie-web@latest/build/player/lottie.min.js"></script>

Quality Checks

Before delivering, verify:

• Every color in output traces back to DNA palette
• Font families match DNA specification
• Spacing rhythm matches DNA scale
• Border radius matches DNA shape tokens
• Overall mood matches design_style.aesthetic.mood
• Component patterns match DNA components descriptions
• Contrast ratios meet WCAG AA minimum (4.5:1 body text, 3:1 large text)
• Visual effects match visual_effects specification (type, technology, params)
• Fallback strategy is implemented for effects
• prefers-reduced-motion is respected
• No effects render when their enabled flag is false
• Canvas/WebGL contexts are properly sized and handle resize
• Animation loops use requestAnimationFrame (no setInterval)