DESIGN.md Guide

DESIGN.md is a markdown file in your project root that tells Pretty about your brand. Think of it as CLAUDE.md for Claude Code — it provides persistent context that the agent reads on every run.

It's helpful but never required. Pretty works without it, and will ask about what it needs in the flow of doing work.

Quick start

You can bootstrap the Brand section directly from an existing image using pretty palette --save:

pretty palette brand-logo.png --save

This extracts colors from the image and writes them to the ## Brand section of DESIGN.md, creating the file if it doesn't exist. You can then edit it to add fonts, style direction, and conventions.

Or create a DESIGN.md manually in your project root:

## Brand

- Primary: #2563eb
- Secondary: #f59e0b
- Background: #09090b
- Text: #fafafa
- Font: Inter (headings), System UI (body)

## Style Direction

Modern, minimal, dark-first. Clean lines, generous whitespace.
Prefer flat design over skeuomorphism.

## Avoid

- Gradients on text
- Stock photo aesthetic
- Clip art or cartoon illustrations
- Comic Sans

## Conventions

- Always include the logo in the top-left corner
- Social media posts use the brand color as the background
- Maintain 16px minimum padding on all edges

Recognized sections

Pretty parses these heading sections from your DESIGN.md. All are optional — use only what's relevant to your project.

Section	Purpose
`## Brand`	Colors, fonts, logo usage — hard constraints the agent must follow
`## Style Direction`	Qualitative guidance: modern, playful, corporate, minimalist, etc.
`## Avoid`	Anti-patterns and prohibitions — things the agent must not do
`## Audience`	Who the designs are for — helps the agent make taste decisions
`## References`	Links or descriptions of visual references to draw from
`## Conventions`	Recurring rules: logo placement, safe zones, naming patterns
`## Output`	Default output preferences: format, resolution, naming
`## Notes`	Anything else — project context, stakeholder preferences, history

Other context files

Pretty also reads these files if they exist, in priority order:

DESIGN.md — Brand constraints (highest priority)
PROJECT.md — Project brief: goals, audience, style guidance
BRIEF.md — Creative brief (alternative to PROJECT.md)
plan.md — Deliverables plan: what to produce, checklist
feedback.md — Iteration history: what was tried, what to change

Directory conventions

Pretty automatically scans your project for design context in these conventional directories (up to 2 levels deep, max 8 files per role):

Brand assets

Place logos, icons, and brand materials in a brand/ directory:

brand/
  logo.svg
  logo-dark.png
  icon.png

References (positive)

Visual references and inspiration go in references/, mood-board/, or inspiration/:

references/
  competitor-landing-page.png
  color-inspiration.jpg
  typography-reference.png

Anti-references (negative)

Examples of what you don't want go in anti-references/, not-like-this/, or rejected/:

anti-references/
  too-corporate.png
  wrong-tone.jpg

Example project structure

my-project/
  DESIGN.md              # Brand guidelines
  PROJECT.md             # Project brief
  brand/
    logo.svg
    logo-dark.png
  references/
    style-inspiration.png
  anti-references/
    rejected-draft.png
  output/                # Pretty writes here
    social-banner.png
    favicon.ico

When you run pretty in this directory, it automatically picks up all the context files and assets — no configuration needed.