DESIGN.md + Devin

Why Devin + DESIGN.md Solves a Real Problem

Devin operates in a loop that other agents don’t have:

1. Clones the repo - reads the entire structure
2. Plans - decides which files to create/edit
3. Implements - writes code
4. Tests - runs tests and checks for errors
5. Iterates - fixes what failed
6. Delivers - opens a PR or commits

DESIGN.md enters at step 1. When Devin clones and explores the repo, it finds DESIGN.md at the root (just like it finds README.md). If the Knowledge instructions say “read DESIGN.md before doing UI work,” it reads and applies.

Without this, step 3 becomes a slot machine. With it, the entire loop produces visually consistent code from start to finish. And because Devin can self-iterate (step 5), it self-corrects when it notices it drifted from the palette.

Step by Step Setup

1. Place DESIGN.md in the repository

Devin clones your repo. It needs to find DESIGN.md there:

my-project/
├── DESIGN.md          ← First visual file it reads
├── README.md          ← Project context
├── AGENTS.md          ← Generic agent instructions (optional)
├── src/
│   └── components/
├── package.json
└── ...

The DESIGN.md should use the standard format with YAML front matter + markdown prose. Devin parses both.

2. Configure Knowledge in Devin

In the Devin dashboard, go to Knowledge and add a documentation entry:

Title: Design System Guidelines

Content:

## Design System Rules

All repositories in this workspace use the DESIGN.md format for design tokens.

### Mandatory workflow for UI tasks

1. When cloning any repo, check if DESIGN.md exists at the root
2. If it exists, read it COMPLETELY before generating any component
3. Extract tokens for: colors, typography, spacing, border-radius
4. Apply the tokens in all generated UI code
5. Check the "Constraints" section and do not violate any

### How to interpret DESIGN.md

The file has two parts:
- **YAML front matter** - design tokens in structured format (hex colors, sizes in px/rem, scales)
- **Markdown body** - design rationale, component patterns, examples, constraints

Prioritize the YAML for exact values. Use the markdown to understand intent and context.

### Component patterns

When creating UI components:
- Every color must come from DESIGN.md (never invent)
- Spacing: multiples of the base value
- Typography: use only sizes from the defined scale
- Interactive elements: hover, focus, disabled states mandatory
- Accessibility: aria-labels, keyboard nav, color contrast

### Expected output

- Code that uses exact tokens from DESIGN.md
- Visually consistent components across the project
- Zero invented colors or arbitrary spacing

3. Connect the repository

In Devin, go to Repos and connect the repository:

1. Authorize access via GitHub/GitLab
2. Select the project repo
3. Devin can now clone and access DESIGN.md directly

4. README.md reinforcement

Devin reads README.md to understand the project. Add a section:

## 🎨 Design System

This project uses [DESIGN.md](./DESIGN.md) as the source of truth for visual decisions.

**For AI agents:** read DESIGN.md before generating or modifying any UI component.
Color, typography and spacing tokens are mandatory.

This works as reinforcement. Beyond the Knowledge base, the README itself provides instruction.

5. Optimized session prompt

When creating a session in Devin, use prompts that explicitly reference the design system:

Task: Create a pricing page with 3 tiers (Free, Pro, Enterprise).

Requirements:
- Read DESIGN.md for visual tokens
- Responsive layout (3-column grid desktop, stack mobile)
- "Pro" tier highlighted as popular
- Each tier: name, price, features list, CTA button
- Use the Button and Card patterns defined in DESIGN.md
- Do not use colors outside the defined palette
- Accessibility: WCAG AA

Concrete Usage Example

You create a session in Devin:

Implement the complete design system as React components:
1. Read DESIGN.md at the root
2. Create components in src/components/ui/
3. Required components: Button, Input, Select, Textarea, Card, Badge, Avatar, Modal, Dropdown, Tabs
4. Each component must:
   - Use DESIGN.md tokens (colors, spacing, radius, typography)
   - Have TypeScript interfaces for props
   - Support variants via prop (e.g., Button variant="primary"|"secondary"|"ghost")
   - Have states: default, hover, focus, disabled
   - Be accessible (aria, keyboard)
5. Create src/components/ui/index.ts exporting everything
6. Create Storybook stories for each component (optional)
7. Run build to verify TypeScript errors

Devin executes the entire task:

1. Clones the repo
2. Reads DESIGN.md and extracts tokens
3. Creates the src/components/ui/ structure
4. Generates each component following tokens
5. Creates TypeScript interfaces
6. Tests the build (npm run build)
7. Fixes errors if any
8. Opens PR with all components

The result looks something like this for Button:

// src/components/ui/Button.tsx
import { forwardRef, type ButtonHTMLAttributes } from 'react';
import { clsx } from 'clsx';

type ButtonVariant = 'primary' | 'secondary' | 'ghost';
type ButtonSize = 'sm' | 'md' | 'lg';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant;
  size?: ButtonSize;
  loading?: boolean;
}

const variantStyles: Record<ButtonVariant, string> = {
  primary: 'bg-[#1A73E8] text-white hover:bg-[#1557B0] focus:ring-[#1A73E8]',
  secondary: 'bg-transparent border border-[#1A73E8] text-[#1A73E8] hover:bg-[#1A73E8]/5 focus:ring-[#1A73E8]',
  ghost: 'bg-transparent text-[#1A73E8] hover:bg-[#F8F9FA] focus:ring-[#1A73E8]',
};

const sizeStyles: Record<ButtonSize, string> = {
  sm: 'px-3 py-1.5 text-xs rounded-md',
  md: 'px-4 py-2.5 text-sm rounded-lg',
  lg: 'px-6 py-3 text-base rounded-lg',
};

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', loading, disabled, className, children, ...props }, ref) => {
    return (
      <button
        ref={ref}
        disabled={disabled || loading}
        className={clsx(
          'inline-flex items-center justify-center font-medium transition-colors',
          'focus:outline-none focus:ring-2 focus:ring-offset-2',
          'disabled:opacity-50 disabled:pointer-events-none',
          variantStyles[variant],
          sizeStyles[size],
          className,
        )}
        {...props}
      >
        {loading && (
          <svg className="animate-spin -ml-1 mr-2 h-4 w-4" viewBox="0 0 24 24">
            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
          </svg>
        )}
        {children}
      </button>
    );
  }
);

Button.displayName = 'Button';

Colors #1A73E8, #1557B0 (hover), #F8F9FA (ghost hover) all from DESIGN.md. Radius rounded-md (sm: 4) and rounded-lg (md: 8) matching tokens. Spacing in multiples of 4. States fully implemented.

Devin-Specific Tips

Hierarchical Knowledge

If you work with multiple projects that have different design systems, organize Knowledge entries:

Knowledge Entry: "Design System — Project A"
→ Links to: repo-project-a DESIGN.md

Knowledge Entry: "Design System — Project B"  
→ Links to: repo-project-b DESIGN.md

Knowledge Entry: "Design System — Global Rules"
→ Common rules for all projects (mandatory DESIGN.md reading)

Devin cross-references Knowledge with whatever repo it’s currently working on.

Use Playbooks for recurring tasks

If you frequently ask “generate components following DESIGN.md,” create a Playbook:

Playbook: Create UI component

1. Read DESIGN.md at project root
2. Check existing components in src/components/ for consistency
3. Create the component with TypeScript strict
4. Apply DESIGN.md tokens for colors, spacing, radius
5. Implement variants and states
6. Ensure accessibility (aria, keyboard)
7. Run npm run build to verify types
8. Commit with descriptive message

Session feedback trains Devin

If Devin generates UI with wrong colors, give feedback in the session:

The Button is using #3B82F6 instead of #1A73E8. Fix it to use the primary 
color defined in DESIGN.md. Check ALL generated components and fix if necessary.

Devin corrects and learns within that session’s context. For persistent learning, update the Knowledge.

Devin + PRs as design review

Configure Devin to open PRs instead of committing directly. This enables:

1. Devin generates the components
2. Opens PR with full diff
3. You (or the team) review whether it followed DESIGN.md
4. Merge if approved, feedback if not

This workflow is the safest for design systems. No code reaches main without visual review.

Cross-references with existing code

If the repo already has components that correctly follow DESIGN.md, instruct Devin to use them as reference:

Before creating new components, read existing ones in src/components/ui/ 
to understand how DESIGN.md tokens are applied in this project. 
Maintain consistency with the existing implementation.

Troubleshooting and Gotchas

Devin ignores DESIGN.md

Common causes:

• Knowledge isn’t configured with the instruction to read DESIGN.md
• The session prompt doesn’t mention the design system
• DESIGN.md is in a subfolder (it should be at the root)

Solution: be explicit in the prompt AND in Knowledge. Redundancy helps with autonomous agents.

Inconsistent colors between components

If Devin generates 10 components and the last few use different colors than the first:

1. Context might have been truncated. DESIGN.md is too large.
2. Solution: keep DESIGN.md below 2000 tokens
3. Place a summary of the most-used tokens at the top of the file
4. Split the task into smaller batches (5 components per session)

Devin installs unexpected UI libraries

Without clear instructions, Devin might decide to use shadcn, Radix, or MUI. Control via Knowledge:

### UI Dependencies

This project does NOT use third-party component libraries.
All components are custom-built on Tailwind CSS.
Do not install: @radix-ui/*, @headlessui/*, @mui/*, shadcn.
Allowed: clsx, tailwind-merge, lucide-react.

Session takes too long

Devin can spend time browsing documentation about design patterns online. Reduce that by instructing:

Do not research design patterns on the web. Use EXCLUSIVELY the project's DESIGN.md 
as visual reference. For decisions not covered, infer from existing tokens.

Devin edits DESIGN.md

Sometimes it interprets “follow the design system” as “improve the design system.” Protect it:

In Knowledge:

### Protected files

NEVER edit these files:
- DESIGN.md — source of truth, read-only
- README.md — modify only if explicitly asked

DESIGN.md version becomes stale

If the design system evolves but Devin’s Knowledge has a cached version:

1. Update the Knowledge entry when DESIGN.md changes
2. Better: rely on the repo file (Devin always reads the latest when cloning)
3. Knowledge serves as “general rules,” the repo’s DESIGN.md is “current source of truth”

Complete Workflow with Devin

1. Initial setup:

   • DESIGN.md at the repo root
   • Knowledge configured in Devin
   • Repo connected

2. Component task:

   • Session with clear prompt referencing DESIGN.md
   • Devin executes autonomously
   • PR opened for review

3. Review:

   • Verify colors, spacing, typography against DESIGN.md
   • Approve or provide feedback

4. Iteration:

   • Devin corrects based on feedback
   • New PR or push to same branch

5. Evolution:

   • When DESIGN.md changes, update Knowledge
   • Next sessions already use updated tokens

Conclusion and Next Step

Devin with DESIGN.md is for teams that want to delegate heavy lifting. “Generate all the design system components” isn’t a fantasy. It’s a single Devin session with the right context. The Knowledge base keeps rules persistent, DESIGN.md in the repo ensures tokens are current, and the PR system provides a safety net.

The initial setup is the longest among all agents (Knowledge + Repos + Playbooks), but the payoff is proportional: you delegate entire UI tasks without opening an IDE. For teams that want maximum productivity with visual consistency, this is the configuration that delivers.

Next steps:

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