Design-to-Code

Module 01

The DDS Terminal Aesthetic

The token set

This is not a theoretical design system. It is the actual CSS running on the page you are reading right now. Open your browser's inspector, find the section element, and you will see these exact custom properties. That is the point: the design system is the code. There is no handoff gap because the tokens are defined once, in the section's CSS, and every rule references them.

Module 02

Design Tokens as CSS Custom Properties

#{{ section_id }} {
  /* Color tokens */
  --d2c-gold: #FFE069;
  --d2c-bg: #04090c;
  --d2c-surface: #0c1117;
  --d2c-border: #1e293b;
  --d2c-text: #e2e8f0;
  --d2c-text-strong: #f8fafc;

  /* Font stacks */
  --serif: 'Playfair Display', Georgia, serif;
  --sans: 'DM Sans', -apple-system, sans-serif;
  --mono: 'JetBrains Mono', ui-monospace, monospace;

  /* Spacing scale (4px base) */
  --space-xs: 4px;
  --space-sm: 8px;
  --space-md: 16px;
  --space-lg: 32px;
  --space-xl: 64px;

  /* Elevation */
  --elev-1: 0 1px 4px rgba(0,0,0,.4);
  --elev-2: 0 4px 12px rgba(0,0,0,.5);

  /* Radii */
  --radius-sm: 8px;
  --radius-md: 12px;
}

Rules for token discipline

• No magic numbers. Every color, font, spacing, shadow, and radius value must reference a token. If you write padding: 13px, that is a magic number. Use padding: var(--space-md) or do not use it.
• Scoped to the section ID. Tokens are defined on #section_id, not on :root or body. This prevents leaking into other sections on the same page.
• One source of truth. Tokens are defined once, at the top of the section's CSS. Every rule below references them. To change the entire color scheme, you change eight values.

Module 03

Component Structure

The DDS Academy page structure

• Breadcrumb nav — <nav aria-label="Breadcrumb">
• Hero header — <header> with eyebrow, icon, h1, deck, meta row, credential card, CTAs
• 3-column shell — CSS Grid: sticky TOC (nav) + article + sidebar (aside)
• Modules — <section id="..."> inside the article, each with answer capsule + content
• FAQ accordion — <section> with button/div toggle pattern
• Footer — <footer> with attribution and cross-links

Every component gets a prefixed class: .d2c-hero, .d2c-shell, .d2c-toc, .d2c-article, .d2c-faq-item. The prefix prevents selector collisions when multiple sections load on the same page. Figma users who name layers with the same convention (e.g., d2c/hero, d2c/shell) get cleaner exports because the AI maps layer names to class names.

Module 04

Tool Landscape (2026)

Module 05

The Design-to-Code Workflow

Stage 1: Input

Give the agent everything it needs to avoid inventing. At minimum: your token file (CSS custom properties or JSON), the component structure (what elements in what order), and a visual reference (Figma link, screenshot, or detailed description). The more specific the input, the less you fix later.

Stage 2: Generation

Run the prompt. The AI produces HTML + CSS. For a DDS Academy section, this is typically 800-1100 lines of Liquid/HTML/CSS/JS in a single file. The output should use your tokens, not arbitrary values. If the agent invents colors or spacing, the token file was not in the prompt.

Stage 3: Refinement

This is where most people skip and should not. Review the output against your checklist: semantic HTML (not div soup), headings in order, ARIA labels on buttons, tokens used (no magic numbers), responsive at three viewports, CSS scoped to the section. Fix what is wrong. This step typically takes 15-30% of the total time but determines whether the output is maintainable or disposable.

Stage 4: Integration

Merge into your codebase. For Shopify: deploy to staging, render-verify at 1440px, 1440x680, and 390x844, then promote to MAIN with length-parity assertion. Run accessibility validation. Ship.

Module 06

Accessibility Gates

The checklist

1. Semantic HTML. Use section, article, nav, aside, header, footer, ul, ol, figure. Not div for everything.
2. Heading hierarchy. One h1 per page. h2 for sections. h3 for subsections. No skipped levels.
3. ARIA labels. Every button, toggle, and interactive element has an accessible name. Decorative elements have aria-hidden="true".
4. Focus indicators. :focus-visible with a 2px solid outline offset 3px. Do not remove focus outlines.
5. Touch targets. Minimum 44x44px for all interactive elements (WCAG 2.2 AA).
6. Contrast. Text on background must pass WCAG AA (4.5:1 for body text, 3:1 for large text). Gold #FFE069 on #04090c passes at 11.6:1.
7. Keyboard navigation. Tab through the entire page. Every interactive element must be reachable and operable.
8. Screen reader test. Navigate with VoiceOver, NVDA, or JAWS. Headings should announce correctly. Landmarks should be labeled.

Module 07

Pitfalls

1. CSS bloat

AI models generate redundant selectors because they solve each element independently. They write color: #FFE069 on 15 different rules instead of referencing var(--d2c-gold) once and inheriting. The fix: give the agent your token file and explicitly state “use only these tokens, no hardcoded values.”

2. Div soup

AI defaults to <div> for everything because div is the safest generic element. The result: a page with no landmarks, no heading structure, and no semantic meaning. Screen readers navigate a flat wall of identical containers. The fix: specify the semantic elements in your prompt (section, article, nav, aside, figure, ul).

3. Over-broad selectors

An AI writes h2 { color: white; } thinking it is styling your section. But that rule applies to every h2 on the page, including the Shopify header and footer. On a dark-on-dark page, white headings disappear. The fix: scope every selector under #section_id and use prefixed classes (.d2c-article h2).

4. Pixel-chasing

When an AI tries to match a screenshot exactly, it uses absolute positioning, fixed widths, and magic-number margins. The output looks correct at the exact resolution of the screenshot and breaks at every other resolution. The fix: aim for structural fidelity (correct hierarchy, correct tokens, correct responsive behavior), not pixel-perfect fidelity.

Module 08

Paste-Ready Prompts & Checklist

Generate a [component name] from this design reference.

Design tokens (use ONLY these, no hardcoded values):
  --primary: [your primary color]
  --bg: [your background color]
  --surface: [your surface color]
  --text: [your text color]
  --font-display: [your display font]
  --font-body: [your body font]

Requirements:
- Semantic HTML (section, article, nav, aside, figure, ul)
- Heading hierarchy: h2 for sections, h3 for subsections
- ARIA labels on all interactive elements
- CSS scoped under #[container-id] with [prefix]- classes
- Responsive: 3-column at 1280px, 2-column at 1180px, 1-column at 768px
- No inline styles. No arbitrary color or spacing values.
- WCAG 2.2 AA: 4.5:1 contrast, 44px touch targets, focus-visible

[Attach screenshot]

Replicate this UI as a [React component / HTML section / Liquid section].

Constraints:
- Use these design tokens: [paste your token file]
- Map visual elements to semantic HTML: header, nav, main, section, article
- Responsive: desktop-first, collapse to single-column at 768px
- No absolute positioning. Use Flexbox or Grid for layout.
- Include accessible labels for all buttons and icons.
- Output a single file. CSS scoped to a container ID.

Review this generated component for production readiness:

1. Replace all hardcoded color/spacing values with design token references
2. Replace all divs that should be semantic elements (section, nav, aside, ul)
3. Add missing ARIA labels on buttons and interactive elements
4. Fix heading hierarchy (h2 for sections, h3 for subsections, no skipped levels)
5. Remove duplicate CSS selectors
6. Add focus-visible styles to all interactive elements
7. Verify responsive behavior at 1440px, 1024px, and 390px
8. Scope all CSS under #[container-id]

Report what you changed and why.

The review checklist

1. Every color value references a token (no hex, no rgb outside the token definition)
2. Every spacing value references a token or uses the 4px base scale
3. All CSS scoped under the section ID with prefixed classes
4. Semantic HTML: correct elements for each component
5. Heading hierarchy: h1 once, h2 for sections, h3 for subsections, no skips
6. ARIA labels on buttons, toggles, and navigation landmarks
7. Focus-visible on all interactive elements
8. Responsive at 1440px, 1024px, 768px, 390px
9. No absolute positioning for layout (Flexbox/Grid only)
10. No duplicate selectors

Module 09

The Review Gate

How design-to-code feeds the storefront work: the Hydrogen Masterclass teaches the framework. The Homepage Upgrade teaches layout iteration. The SEO Magnet teaches the schema and discoverability layer. The Reading & Directing Code class teaches understanding the output. Design-to-code connects all of them: it is how the design intent becomes the actual section file that carries the SEO schemas, the responsive layout, and the accessible structure.

Frequently Asked Questions

FAQ