Prototyping from a Design Idea

Concepts

Mockup, prototype, product: three different things. A mockup is a picture of a screen. A prototype is one that responds, with real components and real interaction running on fake data. A product is a prototype hardened for strangers, with real data, accounts, and error handling. This course lives in the middle. You're building prototypes real enough to test and share, without the weight of a full product.

The stack this course uses. You'll build with React, Vite, and TypeScript. It's a deliberate choice, not the only one. React gives you components that map cleanly onto how designers already think. Vite runs your project and shows it in a browser quickly. TypeScript adds guardrails that catch mistakes before they reach the screen. Other stacks work fine too, and you should know they exist.

Concepts

Persistent context beats repeated instruction. Drift happens because you re-explain your intentions every time, slightly differently, and the tool fills the gaps with its own guesses. When the rules live in a file that's read automatically instead, every build inherits the same law. You stop repeating yourself, and the guessing stops with it.

Two files, two jobs. A CLAUDE.md is your project's operating manual: Claude Code reads it automatically at the start of every session, and it holds the stack, conventions, and pointers to other docs. A DESIGN.md is your design law: tokens, spacing scale, type scale, component rules, and a do-not list. You keep them separate because they answer different questions, and you point CLAUDE.md at DESIGN.md so the design law loads every session without you pasting it in again.

# Project: Onboarding Prototype

## Stack
- React + Vite + TypeScript
- All styling uses design tokens. Never hardcode colors or spacing.

## Design rules
Read DESIGN.md before building or changing any UI.
It is the source of truth for color, spacing, type, and components.

## Conventions
- One component per file.
- Components live in src/components.

A DESIGN.md is your design system, written so a machine can obey it. This is the document you always wished engineering would follow. Here, Claude follows it because you made it cheap to. Define your tokens as named values, your scales as fixed steps, and your rules as plain statements. The more specific you are, the less Claude guesses.

# Design Law

## Color tokens (use these names, never raw hex)
- color-ink:     #1a1a1a   # primary text
- color-muted:   #6b7280   # secondary text
- color-accent:  #c4633f   # actions, links
- color-surface: #f5f5f4   # cards, panels

## Spacing scale (only these steps, in px)
4, 8, 12, 16, 24, 32, 48, 64

## Type scale
- h1: 32px / 600   - body: 16px / 400
- h2: 24px / 600   - small: 13px / 400

## Rules
- Buttons use color-accent. Never invent a new button color.
- One accent color only. No gradients.
- Border radius is always 6px.

## Do not
- Do not hardcode hex values. Use a token.
- Do not introduce a spacing value outside the scale.

Concepts

Break a screen into four layers. Before you describe anything, look at your design and separate it into structure (what regions exist and how they stack), hierarchy (what's primary, what's secondary), states (what this screen looks like when empty, loading, or full), and behavior (what happens when someone interacts). Most weak briefs only cover structure and skip the other three. States matter especially: an empty list and a full list are different screens, and a prototype that ignores the empty case feels fake the moment someone tests it.

Specify what matters; delegate the rest. You don't need to dictate every pixel; that's what DESIGN.md is for. Name the things that carry your intent and let Claude handle the rest. If you find yourself describing a color or a spacing value in your brief, stop: that belongs in your design law, not repeated in every prompt.

Concepts

A component is a Figma component that runs. It's a reusable piece you define once and place many times. The configurable parts (the label, the color variant, whether it's disabled) are called props. Nesting one component inside another is composition, the same as nesting frames. If you already think in components in Figma, React components will feel familiar.

// One component, defined once. The props are its knobs.
type ButtonProps = {
  label: string;
  variant: 'primary' | 'secondary';
  disabled?: boolean;
};

function Button({ label, variant, disabled }: ButtonProps) {
  return (
    <button className={`btn btn-${variant}`} disabled={disabled}>
      {label}
    </button>
  );
}

Register components in your design law as you build them. Every time you create a real component, add a line to DESIGN.md naming it and its props. Your design law grows into a living component inventory, and the next time you need a card, Claude already knows about it. That single habit stops the ten-disagreeing-cards problem before it starts.

The second layer is a check that proves the rules were followed. A DESIGN.md tells Claude the rules; a linter checks whether they were actually obeyed. Think of a linter as a spell-checker for your code's style: it reads every file and flags anything that breaks a rule you've set. Tools like Stylelint and ESLint can be configured against your tokens so that a stray hardcoded color or an off-scale margin fails the check automatically. The tool flags; you decide.

# Run the linter against your project
npm run lint

# A violation gets caught before it spreads:
src/components/Card.tsx
  14:18  error  Unexpected hardcoded color "#3a3a3a".
                Use a token from DESIGN.md  design/no-raw-color

The three-layer defense, in order of trust. Each layer catches what the one above it can't. Your DESIGN.md sets the rules. The linter catches violations a machine can prove. Claude-assisted review catches the judgment-level drift a linter can't see, but it's the least certain layer, and you stay the final check.

Concepts

State is what the screen remembers right now: whether the menu is open, which tab is selected, what the user typed. An event is what the user did: a click, a keystroke, a hover. The loop is straightforward: an event changes the state, and the changed state re-draws the screen. Once you see it, interaction stops feeling complicated.

import { useState } from 'react';

function Menu() {
  // "open" is the state. "setOpen" changes it.
  const [open, setOpen] = useState(false);

  return (
    <div>
      // the click event flips the state
      <button onClick={() => setOpen(!open)}>Menu</button>
      {open && <nav>...</nav>}
    </div>
  );
}

The same handful of patterns covers most prototypes. Toggles, tabs, modals, and form inputs are the workhorses. Learn to recognize them and you'll see that most interaction is a variation on "something is open or closed" and "something is selected." You rarely need anything exotic to make a prototype convincing.

Concepts

Deploying means putting your project somewhere with a public URL. On your machine, your prototype runs on a local address only you can reach. Deploying copies it to a host that serves it to anyone with the link. For a Vite project, this is close to one command: services like Vercel and Netlify detect your setup, build it, and hand you a URL.

# Build the production version, then deploy
npm run build
npx vercel deploy

# You get back a shareable URL:
# https://your-prototype.vercel.app

Know the difference between a preview link and a product. A deployed prototype is fast to share and perfect for feedback, but it's still running on fake data with no accounts and no hardening. That's fine; it's exactly what a prototype should be. Just don't let a slick URL trick anyone, including you, into thinking it's ready for real users.

The brief

The process:

1. Choose your screen and write its brief across structure, hierarchy, states, and behavior.
2. Write a DESIGN.md for it and a CLAUDE.md that points to it.
3. Scaffold the screen from your brief plus your design law.
4. Componentize the repeated parts, registering each in DESIGN.md.
5. Set up a lint check that enforces your tokens, and prove it catches a planted violation.
6. Add the interactions that make the screen answer its real question.
7. Wire in realistic data from a local JSON file.
8. Deploy to a live URL and share it with one person.