DESIGN.md + Cline

Why Cline + DESIGN.md Is a Strong Combination

Cline has three properties that make it ideal for working with design systems:

1. Autonomy - it doesn’t wait for approval on every line. If the rules are clear, it follows them and produces output. DESIGN.md provides the visual rules it needs.

2. Persistence - .clinerules are read on every task, not only when you remember to mention them. The design system stays “always on.”

3. Memory Bank - design decisions made in one session carry into the next. “We decided to use cards with soft shadows and no border” doesn’t need repeating.

Without DESIGN.md, Cline is a talented developer who never saw the design brief. With DESIGN.md, it becomes a dev who has internalized the entire design system before touching code.

Step by Step Setup

1. Install Cline in VS Code

If you don’t have it: Extensions > search “Cline” > Install. Configure the API key for whichever model you prefer (Claude, GPT, etc.).

2. Place DESIGN.md at the root

my-project/
├── DESIGN.md
├── .clinerules
├── .cline/
│   └── memory-bank/
├── src/
└── ...

3. Create the .clinerules file

The .clinerules file is the most powerful piece in the Cline ecosystem. It gets read automatically at the start of EVERY task, no exceptions. Create it at the project root:

# .clinerules

## Design System

This project follows a design system documented in DESIGN.md at the root.

### Absolute rule

Before generating, modifying or suggesting any UI component:
1. Read the complete DESIGN.md file
2. Extract the relevant tokens (colors, typography, spacing)
3. Apply them in the generated code
4. Verify the constraints listed in DESIGN.md before finalizing

### Mandatory patterns

- Colors: use ONLY the defined tokens. Never invent colors.
- Typography: respect the exact scale. No intermediate sizes.
- Spacing: multiples of the base value defined in DESIGN.md.
- Components: follow documented patterns (buttons, cards, inputs, etc.)
- States: every interactive element must have hover, focus and disabled.
- Constraints: the "Constraints" section of DESIGN.md is law. Do not violate.

### When DESIGN.md doesn't cover a case

If you need a token or pattern that isn't documented:
1. Infer from existing patterns (consistency > creativity)
2. Document the decision in the memory bank for future reference
3. Notify the user about the decision made

### CSS Framework

[Adapt this section to your project]
- If using Tailwind: map tokens to custom classes
- If using CSS Modules: create CSS variables from tokens
- If using styled-components: create theme object from tokens

4. Set up the Memory Bank

The Cline Memory Bank persists information between sessions. Create the directory:

mkdir -p .cline/memory-bank

Create an initial design context file:

# .cline/memory-bank/design-decisions.md

## Design decisions for this project

### Date: [auto-filled by Cline]

- Design system source of truth: DESIGN.md at root
- CSS framework: [Tailwind/CSS Modules/styled-components]
- Naming convention: [BEM/utility-first/component-scoped]
- Icons: [Lucide/Heroicons/custom SVG]

## Emergent patterns

[Cline updates this as it makes decisions]

5. Create per-directory rules (optional but recommended)

Cline supports .clinerules files in subdirectories. When it works on files inside that folder, it reads the local rules in addition to the global ones:

# src/components/.clinerules

## Rules for components

- Every component must be a named export
- Props must have an explicit TypeScript interface
- Visual components must follow root DESIGN.md
- Components must accept className for override
- Document variants with JSDoc above the component

Concrete Usage Example

Open Cline and type:

Create a dashboard page with:
- Header with logo and navigation
- Sidebar with menu links
- Main area with a grid of stats cards
- Each stat card shows: icon, label, numeric value, percentage change
- Responsive design: sidebar collapses on mobile

Cline reads .clinerules, then opens DESIGN.md, extracts tokens and generates:

// src/pages/Dashboard.tsx
import { StatsCard } from '@/components/StatsCard';
import { Sidebar } from '@/components/Sidebar';
import { Header } from '@/components/Header';

export function Dashboard() {
  return (
    <div className="min-h-screen bg-[#F8F9FA]">
      <Header />
      <div className="flex">
        <Sidebar />
        <main className="flex-1 p-8">
          <h1 className="text-[32px] font-bold text-[#202124] leading-[1.2]">
            Dashboard
          </h1>
          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mt-8">
            <StatsCard
              icon="users"
              label="Active users"
              value="12,847"
              change={+12.5}
            />
            <StatsCard
              icon="revenue"
              label="Monthly revenue"
              value="$84,320"
              change={+8.2}
            />
            <StatsCard
              icon="conversion"
              label="Conversion rate"
              value="3.24%"
              change={-0.8}
            />
            <StatsCard
              icon="sessions"
              label="Sessions"
              value="48,291"
              change={+15.3}
            />
          </div>
        </main>
      </div>
    </div>
  );
}

// src/components/StatsCard.tsx
interface StatsCardProps {
  icon: string;
  label: string;
  value: string;
  change: number;
}

export function StatsCard({ icon, label, value, change }: StatsCardProps) {
  const isPositive = change > 0;

  return (
    <div className="bg-white rounded-2xl p-6 shadow-sm hover:shadow-md transition-shadow">
      <div className="flex items-center gap-3">
        <div className="w-10 h-10 rounded-lg bg-[#F8F9FA] flex items-center justify-center">
          <Icon name={icon} className="w-5 h-5 text-[#1A73E8]" strokeWidth={1.5} />
        </div>
        <span className="text-sm text-[#5F6368]">{label}</span>
      </div>
      <p className="text-[32px] font-bold text-[#202124] mt-4 leading-[1.2]">
        {value}
      </p>
      <span className={`text-sm font-medium ${
        isPositive ? 'text-[#34A853]' : 'text-[#D93025]'
      }`}>
        {isPositive ? '↑' : '↓'} {Math.abs(change)}%
      </span>
    </div>
  );
}

Cline generated the card using: bg-white (surface), rounded-2xl (large: 16), padding 24px (multiple of 8), colors #1A73E8 (primary), #34A853 (secondary/success), #D93025 (error), typography 32px for values (from the scale). Everything extracted from DESIGN.md.

Cline-Specific Tips

Use Custom Instructions alongside .clinerules

In Cline’s Settings panel, there’s a “Custom Instructions” field. Use it for rules that apply across ALL projects:

When working on projects with a DESIGN.md at the root, always read that file before generating UI.
Prioritize visual consistency. Ask when there's ambiguity in the design.

.clinerules is per-project. Custom Instructions is global. Use both.

Take advantage of approval mode

Cline asks for approval before creating or editing files. Use that moment to verify it followed DESIGN.md. If it generated wrong colors, reject and instruct:

Rejected. The button color should be #1A73E8 (primary from DESIGN.md), not #3B82F6.

It learns within the session context and won’t repeat the mistake.

Memory Bank as design history

Configure Cline to log design decisions in the Memory Bank. In .clinerules:

### Decision logging

After creating a new component or making a visual decision not covered by DESIGN.md:
1. Add the decision to .cline/memory-bank/design-decisions.md
2. Format: date, component, decision, justification

This creates a living record of how the design system evolves.

Force explicit reading

If Cline seems to ignore the design system on a particular prompt, be direct:

Read DESIGN.md before continuing. Fix the components to use the correct tokens.

Cline can reread files at any time. Don’t hesitate to ask.

.clinerules as living documentation

The .clinerules file is plain markdown. Teams can review it in PRs, version it, discuss changes. It’s executable documentation: written for humans to read, but executed by the agent.

Troubleshooting and Gotchas

Cline doesn’t read .clinerules

Check:

• The file is at the project root (same level as package.json)
• The name is exactly .clinerules (with dot, no extension)
• VS Code has the project open as a workspace (File > Open Folder)

Memory Bank doesn’t persist between sessions

The Memory Bank depends on Cline’s version. Verify:

• Extension is updated to the latest version
• Directory .cline/memory-bank/ exists and has write permissions
• The file isn’t in .gitignore (if you want to share it with the team)

Cline generates inconsistent UI between components

Likely cause: the DESIGN.md is too long and context gets truncated. Solutions:

1. Keep DESIGN.md below 3000 tokens (ideal: 1500-2500)
2. Use sections with clear headers so Cline navigates better
3. Put the most critical rules at the TOP of the file
4. Tokens in the YAML front matter are more concise than prose

Conflict between global .clinerules and per-directory rules

Subdirectory rules do NOT override root rules. They stack. If there’s a contradiction, the root rule wins. Keep a clear hierarchy:

• Root: universal rules (design system, conventions)
• Subdirectory: scope-specific rules (component patterns, page patterns)

Cline tries to edit DESIGN.md

Sometimes Cline interprets “follow the design system” as “edit the design system.” Add to .clinerules:

## Read-only files

The following files are read-only. Never modify:
- DESIGN.md
- .clinerules (root)

Recommended Workflow

1. Project start: create DESIGN.md + .clinerules before writing any code
2. During development: use Cline to generate components referencing the design system
3. Review: check if the Memory Bank captured emergent decisions
4. Iteration: update DESIGN.md as the design evolves
5. Team: commit .clinerules and DESIGN.md so everyone benefits

Conclusion and Next Step

Cline with DESIGN.md is for developers who want an agent that acts, not one that suggests. The combination of .clinerules (persistent rules) + Memory Bank (cross-session memory) + DESIGN.md (design tokens) creates a workflow where the agent maintains visual consistency without constant oversight.

Setup takes 10 minutes. The payoff is immediate: the first generated component already matches the design system. As the project grows, the Memory Bank accumulates context that makes Cline increasingly precise.

Next steps:

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