Why Aider + DESIGN.md Works Well

Aider has a different philosophy from other tools:

Explicit context control - you decide exactly which files the model sees. No “magic workspace” that might or might not include your file. /add DESIGN.md = guaranteed reading.
Conventions files - files read automatically in every session, without needing to re-add. Perfect for design system rules.
Diff-based editing - Aider shows exactly what changed. You see whether it used the right color or invented a new one.
Git-aware - every edit can become a commit. Easy to revert if the agent drifted from the design system.

For developers who want precision and control, Aider with DESIGN.md delivers both.

Step by Step Setup

1. Install Aider

pip install aider-chat
# or
pipx install aider-chat

Configure the API key:

export ANTHROPIC_API_KEY="sk-..."
# or
export OPENAI_API_KEY="sk-..."

2. Place DESIGN.md at the root

my-project/
├── DESIGN.md
├── .aider.conf.yml
├── CONVENTIONS.md
├── src/
└── ...

3. Configure .aider.conf.yml

Aider reads configuration from .aider.conf.yml at the root. Use it to load DESIGN.md automatically:

# .aider.conf.yml

# Adds DESIGN.md as read-only in every session
read:
  - DESIGN.md
  - CONVENTIONS.md

# Preferred model (adjust to your API key)
model: claude-sonnet-4-20250514

# Auto-commit disabled for manual visual review
auto-commits: false

# Auto-lint enabled
auto-lint: true

The read field is the key. Files listed there are added to context as read-only in EVERY Aider session. You don’t need to remember to /add. The DESIGN.md is just there.

4. Create CONVENTIONS.md

Aider supports a conventions file that functions as persistent instructions. Create it at the root:

# CONVENTIONS.md

## Design System

This project uses DESIGN.md as the source of truth for visual decisions.

### Mandatory rules for UI generation

1. Before generating any visual component, read DESIGN.md
2. Use ONLY colors defined in the DESIGN.md front matter
3. Follow the exact typographic scale (no intermediate sizes)
4. Spacing must be multiples of the base value
5. Components must have states: default, hover, focus, disabled
6. Respect ALL constraints in the "Constraints" section

### Code conventions for components

- TypeScript strict for props interfaces
- Named exports (not default exports)
- One component per file
- File named after the component (PascalCase)
- Styles colocated in the same file (CSS Modules or Tailwind)

### When DESIGN.md doesn't have a definition

- Infer from existing patterns
- Choose the most conservative/consistent option
- Mention in the response that the decision was inferred

5. Start Aider with the correct context

cd my-project
aider

If you configured .aider.conf.yml, DESIGN.md is already in context. Verify:

/tokens

This command shows the session’s token usage. DESIGN.md should appear in the read-only files list.

If you prefer manual control (without .aider.conf.yml):

aider --read DESIGN.md --read CONVENTIONS.md

Concrete Usage Example

Terminal session:

$ aider

Aider v0.82.0
Model: claude-sonnet-4-20250514
Read-only files: DESIGN.md, CONVENTIONS.md
───────────────────────────────────

> Create a newsletter signup component: email input + submit button. Desktop
> version side by side, mobile stacked. Use tokens from DESIGN.md.

Aider responds and edits the file:

// src/components/NewsletterSignup.tsx
interface NewsletterSignupProps {
  onSubmit: (email: string) => void;
  loading?: boolean;
  placeholder?: string;
  buttonText?: string;
}

export function NewsletterSignup({
  onSubmit,
  loading = false,
  placeholder = "Your best email",
  buttonText = "Subscribe",
}: NewsletterSignupProps) {
  const [email, setEmail] = useState("");

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    if (email.trim()) onSubmit(email);
  };

  return (
    <form
      onSubmit={handleSubmit}
      className="flex flex-col sm:flex-row gap-3"
    >
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder={placeholder}
        required
        className="
          flex-1 px-4 py-3
          border border-[#5F6368]/30 rounded-lg
          text-sm text-[#202124]
          placeholder:text-[#5F6368]
          focus:border-[#1A73E8] focus:ring-1 focus:ring-[#1A73E8]
          outline-none transition-colors
        "
      />
      <button
        type="submit"
        disabled={loading}
        className="
          px-6 py-3
          bg-[#1A73E8] text-white text-sm font-medium
          rounded-lg
          hover:bg-[#1557B0]
          focus:ring-2 focus:ring-offset-2 focus:ring-[#1A73E8]
          disabled:opacity-50
          transition-colors whitespace-nowrap
        "
      >
        {loading ? "Sending..." : buttonText}
      </button>
    </form>
  );
}

The diff clearly shows what was created. Colors from DESIGN.md: #1A73E8 (primary), #202124 (text-primary), #5F6368 (text-secondary). Spacing in multiples of 4/8. Border-radius rounded-lg (medium: 8). Hover, focus, and disabled states present.

To commit:

> /commit Add NewsletterSignup component following DESIGN.md

Aider-Specific Tips

When asking to create a component that needs to integrate with others, add the existing ones to context:

/add src/components/Button.tsx src/components/Card.tsx

Now Aider sees how other components use the tokens and maintains consistency. This is more effective than DESIGN.md alone because it copies the actual implementation pattern.

/architect for visual planning

Use architect mode before generating complex code:

/architect

> I need a landing page with hero, features grid, testimonials and CTA.
> Plan the component structure following DESIGN.md before implementing.

Architect mode plans without editing files. You confirm, then it implements.

/read-only vs /add

/read-only DESIGN.md - the model reads but cannot edit. Perfect for design system reference.
/add DESIGN.md - the model can read AND edit. Useful if you want it to update DESIGN.md with new tokens.

For design system as reference, always use read-only.

Lint conventions

In .aider.conf.yml, enable automatic linting:

lint-cmd: "npx eslint --fix"
auto-lint: true

This ensures generated code passes the linter before commit. If your linter has style rules (Tailwind sort, etc.), the code already comes out formatted.

Multiple conventions files

Aider accepts multiple read-only files. Separate by responsibility:

read:
  - DESIGN.md           # Visual tokens
  - CONVENTIONS.md      # Code rules
  - ARCHITECTURE.md     # Project structure

Each file focuses on one aspect. DESIGN.md stays concise without being polluted by code rules.

Use /diff to audit

After generating a component, use:

/diff

Review whether the hardcoded colors match DESIGN.md. If you see #3B82F6 (Tailwind default blue) instead of #1A73E8 (your primary), correct it immediately:

> The button color is wrong. Should be #1A73E8 (primary from DESIGN.md), not #3B82F6.

.env for permanent API keys

Create a .env at the root:

ANTHROPIC_API_KEY=sk-ant-...

And in .aider.conf.yml:

env-file: .env

Never commit the .env. Add it to .gitignore.

Troubleshooting and Gotchas

Aider doesn’t read .aider.conf.yml

Check:

The file is at the project root (where you run aider)
The name is exactly .aider.conf.yml (not .yaml, not .aider.yml)
The YAML indentation is correct (use spaces, not tabs)
Test with aider --verbose to see which configs were loaded

DESIGN.md too large, context blown

Aider shows token usage with /tokens. If DESIGN.md is consuming too much:

Shorten the prose. YAML tokens are more concise than text.
Remove code examples from DESIGN.md (keep only tokens + rationale)
Use a “light” DESIGN.md for Aider and the full version for humans:

read:
  - DESIGN-TOKENS.md   # Compact version with just tokens

Aider generates vanilla CSS instead of Tailwind

If your project uses Tailwind but Aider insists on plain CSS, add to CONVENTIONS.md:

## CSS Framework: Tailwind CSS

- Use ONLY Tailwind classes (utility-first)
- Custom colors are in tailwind.config.js
- When the DESIGN.md token is `primary: #1A73E8`, use class `text-primary` or `bg-primary`
- Never use inline styles
- Never use separate CSS files for components

Model doesn’t respect constraints

If the model ignores the “Constraints” section of DESIGN.md (uses forbidden gradients, for example):

Move constraints to the TOP of CONVENTIONS.md (read first)
Be more emphatic:

## ABSOLUTE PROHIBITIONS (violation = code rejection)

- ❌ NEVER use gradients on backgrounds
- ❌ NEVER use shadows larger than shadow-md
- ❌ NEVER use more than 2 font-weights per component
- ❌ NEVER use colors outside the DESIGN.md palette

Reinforce in the prompt: “Remember the design system constraints before responding”

Conflict between DESIGN.md and existing code

If the project already has components with wrong colors, Aider might copy the wrong pattern. Fix it:

> The existing components are outdated. For new components, ignore patterns from
> existing files and follow ONLY DESIGN.md. Use the colors and spacing defined
> there, even if they differ from current code.

Long session loses context

In very long sessions, Aider can “forget” DESIGN.md. Solution:

/clear

Clears history and reloads read-only files. DESIGN.md returns to the top of context.

Development Workflow with Aider + DESIGN.md

# 1. Start session
cd my-project
aider

# 2. Verify context
/tokens
# → DESIGN.md (read-only), CONVENTIONS.md (read-only)

# 3. Add relevant files for editing
/add src/components/Button.tsx src/pages/Home.tsx

# 4. Request generation following the design system
> Create a Hero component with headline, subtext and CTA button.
> Follow DESIGN.md for colors and spacing.

# 5. Review the diff
/diff

# 6. If approved, commit
/commit feat: add Hero component following design system

# 7. Next component...

Conclusion and Next Step

Aider with DESIGN.md is the minimalist approach that works. No plugins, no extensions, no complex configuration. One YAML config file, one conventions file, and a DESIGN.md at the root. Terminal, AI, and design system integrated.

The strength is control: you know exactly what the model is reading. There’s no “workspace indexing” magic that might silently fail. If DESIGN.md is in the read list, it’s in context. Period.

For anyone already using Aider who wants to improve the visual quality of generated code, setup takes 5 minutes. For those coming from IDEs looking to experiment, Aider with DESIGN.md is an honest entry point: fast results with total control.

Next steps:

What is DESIGN.md - complete format specification
DESIGN.md Library - 450+ ready-made design systems
Guides for other agents: GitHub Copilot · Cursor · Cline · Codex CLI

DESIGN.md + Aider

Why Aider + DESIGN.md Works Well

Step by Step Setup

1. Install Aider

2. Place DESIGN.md at the root

3. Configure .aider.conf.yml

4. Create CONVENTIONS.md

5. Start Aider with the correct context

Concrete Usage Example

Aider-Specific Tips

/architect for visual planning

/read-only vs /add

Lint conventions

Multiple conventions files

Use /diff to audit

.env for permanent API keys

Troubleshooting and Gotchas

Aider doesn’t read .aider.conf.yml

DESIGN.md too large, context blown

Aider generates vanilla CSS instead of Tailwind

Model doesn’t respect constraints

Conflict between DESIGN.md and existing code

Long session loses context

Development Workflow with Aider + DESIGN.md

Conclusion and Next Step

Useful links

DESIGN.md + Aider

Why Aider + DESIGN.md Works Well

Step by Step Setup

1. Install Aider

2. Place DESIGN.md at the root

3. Configure .aider.conf.yml

4. Create CONVENTIONS.md

5. Start Aider with the correct context

Concrete Usage Example

Aider-Specific Tips

/add for related components

/architect for visual planning

/read-only vs /add

Lint conventions

Multiple conventions files

Use /diff to audit

.env for permanent API keys

Troubleshooting and Gotchas

Aider doesn’t read .aider.conf.yml

DESIGN.md too large, context blown

Aider generates vanilla CSS instead of Tailwind

Model doesn’t respect constraints

Conflict between DESIGN.md and existing code

Long session loses context

Development Workflow with Aider + DESIGN.md

Conclusion and Next Step

Useful links