Design Spec

What this is

The design spec is a short file that describes how your website should look and feel.

You create it by having a quick conversation with ChatGPT, then saving the output as design-spec.md in your project folder — right next to project-brief.md.

Why it matters

When you start building in the IDE, your AI agent reads both files.

Without a design spec, the AI agent picks colors, fonts, and layout styles on its own. The result is usually generic. With a design spec, the AI agent has a clear visual direction to follow from the first prompt.

This step takes 5 minutes. It saves a lot of back-and-forth later.

What to do

Step 1 — Use the design spec coach prompt

Open ChatGPT. Paste this prompt and fill in your project details:

I am building a website. Here is my project brief:

[paste your project-brief.md content here]

Help me turn this into a better visual direction before you write the final design spec.

First, ask me 3-5 short questions about:
- the audience
- the feeling the site should create
- any color or style I already like
- anything the site should avoid looking like

After I answer, suggest 2-3 simple improvements that would make the site feel less generic.

Then create the final design spec in this format:

# Design Spec

Include only these sections:
1. Mood — 3-5 words describing the feeling
2. Audience feel — what the visitor should feel in one sentence
3. Colors — primary color, background color, and one accent color with hex codes
4. Typography feel — 1-2 short phrases
5. Layout direction — how the pages should be arranged
6. Component style — how buttons, cards, and sections should feel
7. Images or icons — what kind of visuals to use or avoid

Keep the final spec short enough for a beginner to use. Do not create a full brand book.

Step 2 — Answer and refine

Answer the questions simply. Then read ChatGPT's suggestions.

Ask yourself:

• Does the color mood match the feel of the site I imagined?
• Does the primary color feel right for the audience?
• Does the layout style make sense for the pages I planned?
• Did ChatGPT suggest anything that makes the site clearer or more memorable?

If something feels off, tell ChatGPT to adjust:

Adjust the design direction toward [your preference].
Keep it beginner-friendly and do not add complex animations or advanced UI patterns.

If the final spec becomes too long, use this:

Shorten this design spec. Keep the same sections, but make each section 1-2 lines.

Step 3 — Save the design spec

Copy the final output. Create a new file in your project folder called:

design-spec.md

Paste the design spec into that file and save it.

Your project folder should now have two reference files:

project-brief.md
design-spec.md

Example of a good design spec

# Design Spec

## Mood
Warm, local, relaxed, easy to read

## Audience feel
Visitors should feel like the cafe is friendly, nearby, and easy to visit.

## Colors
- Primary: #D97706 (warm amber)
- Background: #FFFBF5 (warm off-white)
- Accent: #166534 (deep green for small highlights)

## Typography feel
Rounded, readable, not too formal

## Layout direction
Mobile-first pages with clear sections, generous spacing, and the menu easy to scan.

## Component style
Soft cards for menu items, clear amber buttons, simple section headings.

## Images or icons
Use real cafe photos if available. Avoid dark stock photos or overly fancy icons.

Step 4 — Use both files when you start building

When you open the IDE and send your first prompt to the AI agent, reference both files:

Read project-brief.md and design-spec.md before writing any code.
Use them as your reference for what to build and how it should look.

The AI agent will use both files to stay aligned with your plan and visual direction throughout the build.

Common mistakes

• Skipping this step — the AI agent will invent a visual style that may not match your idea.
• Making the design spec too detailed — keep it to the short sections above.
• Not saving it as a file — the AI agent cannot read a ChatGPT window.
• Saving it in the wrong folder — it must be in the project root next to project-brief.md.