Tutorial Overview

Series index: gstack Tutorial Series

The design pipeline transforms ideas into production HTML through three stages.

What you will learn

• ✅ /design-consultation — Build design systems from scratch
• ✅ /design-shotgun — Generate variants with taste memory
• ✅ /design-html — Production HTML with Pretext
• ✅ Framework auto-detection
• ✅ Smart API routing patterns

The Pipeline

flowchart LR
    A[Idea] --> B[/design-consultation]
    B --> C[Design System]
    C --> D[/design-shotgun]
    D --> E[4-6 Variants]
    E --> F[User Selection]
    F --> G[/design-html]
    G --> H[Production HTML]

    style B fill:#e1f5ff
    style D fill:#e8f5e9
    style G fill:#fff3e0

/design-consultation — Design System Builder

What it does

Builds a complete design system from scratch:

1. Researches the landscape — Competitors, patterns, trends
2. Proposes creative risks — Not safe, but intentional
3. Writes DESIGN.md — Colors, typography, components, voice
4. Creates component library — Buttons, forms, cards, layouts

Example output

# DESIGN.md

## Brand Identity

**Voice**: Professional yet approachable. Confident without arrogance.
**Tone**: Helpful, clear, concise.

## Color Palette

| Token | Hex | Usage |
|-------|-----|-------|
| primary | #0066CC | CTAs, links, focus states |
| secondary | #6B7280 | Secondary text, borders |
| accent | #10B981 | Success states, highlights |
| error | #EF4444 | Errors, destructive actions |
| background | #F9FAFB | Page background |
| surface | #FFFFFF | Cards, modals |

## Typography

- **Heading**: Inter 600, 32px/40px
- **Body**: Inter 400, 16px/24px
- **Small**: Inter 400, 14px/20px
- **Code**: JetBrains Mono 400, 14px

## Spacing Scale

| Token | Value | Usage |
|-------|-------|-------|
| xs | 4px | Icon padding |
| sm | 8px | Button padding |
| md | 16px | Card padding |
| lg | 24px | Section padding |
| xl | 32px | Page margins |

## Components

- **Button**: Primary, secondary, ghost variants
- **Input**: With label, error state, icon
- **Card**: With header, body, footer
- **Modal**: With backdrop, close, actions

When to use

• Starting a new project
• Rebranding
• Creating a design system
• Setting up component library

/design-shotgun — Visual Exploration

What it does

Generates 4-6 AI mockup variants for comparison:

1. Creates variants — Different layouts, colors, styles
2. Opens comparison board — All variants side-by-side in browser
3. Collects feedback — “more whitespace”, “bolder headline”
4. Learns taste — Remembers what you like across sessions
5. Iterates — Generate new round based on feedback

The workflow

sequenceDiagram
    participant U as User
    participant S as /design-shotgun
    participant B as Browser

    U->>S: Landing page for SaaS app
    S->>S: Generate 6 variants
    S->>B: Open comparison board
    B->>U: Show all variants
    U->>S: "More whitespace, bolder headline"
    S->>S: Apply feedback + taste memory
    S->>B: New variants
    U->>S: "Love variant #2"
    S->>U: Selected for /design-html

Taste memory

gstack learns your preferences across sessions:

taste_memory:
  preferences:
    - "Prefers generous whitespace"
    - "Likes bold sans-serif headings"
    - "Avoids gradients on backgrounds"
    - "Prefers rounded corners (8px)"
    - "Uses subtle shadows, not heavy"
  avoids:
    - "Cookie-cutter hero sections"
    - "Meaningless gradients"
    - "Stock photo backgrounds"

When to use

• Exploring design directions
• Getting unstuck creatively
• Comparing multiple approaches
• Building consensus with stakeholders

/design-html — Production HTML

What it does

Turns approved mockups into shippable HTML:

1. Pretext computed layout — Text reflows, heights adjust
2. Zero dependencies — 30KB overhead, no framework required
3. Framework detection — Outputs React/Svelte/Vue if detected
4. Smart API routing — Different patterns for different page types

Pretext Computed Layout

Traditional AI HTML breaks on resize. Pretext fixes this:

<!-- Traditional (broken on resize) -->
<div style="height: 400px">
  <h1>Fixed height breaks text reflow</h1>
</div>

<!-- Pretext (dynamic) -->
<div data-pretext="layout">
  <h1 data-pretext="heading">Text reflows naturally</h1>
</div>
<script src="pretext.js" data-auto></script>

Framework Detection

gstack detects your framework and outputs correctly:

Smart API Routing

Different page types use different patterns:

Example output

<!-- Landing page hero - generated by /design-html -->

<section class="hero" data-pretext="section">
  <div class="hero__container">
    <h1 class="hero__title" data-pretext="heading">
      Ship faster with AI that thinks before it codes
    </h1>
    <p class="hero__subtitle">
      23 specialists. 8 power tools. One virtual engineering team.
    </p>
    <div class="hero__cta-group">
      <a href="/get-started" class="btn btn--primary">
        Get started free
      </a>
      <a href="/demo" class="btn btn--ghost">
        Watch demo
      </a>
    </div>
  </div>
</section>

<style>
.hero {
  padding: var(--space-xl) var(--space-md);
  text-align: center;
}
.hero__title {
  font-size: clamp(2rem, 5vw, 3.5rem);
  line-height: 1.2;
  margin-bottom: var(--space-md);
}
/* ... responsive styles ... */
</style>

<script src="https://cdn.gstack.dev/pretext/1.0.0.min.js" data-auto></script>

Full Example: SaaS Landing Page

Step 1: Design consultation

/design-consultation

I need a landing page for a developer tools SaaS.
Target audience: Senior engineers at startups.
Competitors: Vercel, Linear, Railway.

Output: DESIGN.md with colors, typography, components

Step 2: Visual exploration

/design-shotgun

Generate variants for the hero section.
Preferences: Minimal, developer-focused, dark mode support.

Output: 6 hero variants in comparison board

Step 3: Selection

User: "I like variant #3 but with more whitespace and
       a code example instead of the illustration."

Output: New variants incorporating feedback

Step 4: Production HTML

/design-html

Convert variant #3 to production HTML.
Framework: React (detected).
Include: Hero, features section, pricing, footer.

Output: Shippable React components with Pretext layout

Skill Quick Reference

Summary

The design pipeline transforms ideas into production code:

1. Consult — Build design system from scratch
2. Explore — Generate variants with taste memory
3. Produce — Shippable HTML with Pretext layout

Key takeaways

• ✅ Start with /design-consultation for new projects
• ✅ Use /design-shotgun to explore visually
• ✅ Taste memory learns your preferences
• ✅ /design-html outputs framework-appropriate code

Series navigation:

• ← Previous: Tutorial 4: Plan Reviews
• → Next: Tutorial 6A: Browser Basics
• Back: Series Index