Why connect DESIGN.md to Cline?
A task prompt explains what to build now. A repository design specification explains how the product should look across tasks, sessions, contributors, and models. The strongest setup separates concerns: production components are executable truth, DESIGN.md describes the visual system and its constraints, and .clinerules/design.md makes reading that context an explicit habit.
Persistent context
Cline describes rules as persistent Markdown instructions across conversations.
Focused instructions
Workspace rules live in .clinerules/ at the project root.
System before invention
Cline combines rule files and gives workspace rules priority over conflicting global rules.
Human review remains essential
Agent instructions reduce arbitrary choices; they do not replace design judgment, accessibility testing, or visual QA.
Four-step setup
Place DESIGN.md at the repository root
Keep exact semantic roles, component recipes, layout patterns, states, motion, responsive rules, accessibility expectations, and “do not” guidance in one reviewable file.
Create .clinerules/design.md
Use the concise rule below. It tells the agent when to consult the detailed specification without copying the whole document into another file.
Give the task measurable acceptance criteria
Name the existing component to reuse, the approved page to compare against, required states, responsive widths, and the visual decisions that must not change.
Review code and pixels
Search the diff for new hard-coded colors, fonts, shadows, radii, duplicate components, and one-off breakpoints. Then inspect the rendered result.
Copy-ready Cline rule
# .clinerules/design.md
Before changing any user interface:
1. Read /DESIGN.md completely.
2. Reuse existing tokens and components before creating new ones.
3. Do not introduce unapproved colors, fonts, radii, shadows, or motion.
4. Check desktop, mobile, focus, loading, empty, and error states.
5. Explain any intentional design-system exception.A better task prompt
Read DESIGN.md and the existing UI components before coding.
Build the account settings page using the approved page shell, form controls,
buttons, spacing rhythm, typography, and responsive breakpoints.
Acceptance criteria:
- no new colors, fonts, radii, shadows, or animation styles
- reuse existing components before adding variants
- include loading, validation, success, keyboard-focus, and mobile states
- compare at 1440px and 390px with the approved dashboard page
- list any intentional exception before implementing itCommon failure modes
- Only saying “follow the design.” Point to DESIGN.md and concrete implementation sources.
- Duplicating all tokens in the rule file. This creates two sources of truth.
- Ignoring non-default states. Empty, error, loading, focus, and narrow-screen states expose drift first.
- Allowing “improvements” during feature work. Treat visual changes as explicit design-system decisions.
Original implementation example
Suppose an approved card uses the semantic surface token, a 16px radius, one border token, and no shadow. A weak prompt may yield a visually plausible card with a 24px radius and a purple glow. The integrated workflow prevents that by requiring the agent to identify and reuse the card recipe before writing markup. If a new variant is genuinely needed, it must be named, implemented centrally, documented, and reviewed.
Frequently asked questions
Where should DESIGN.md go for Cline?
Put DESIGN.md at the repository root so it is easy to discover, version, review, and reference from the agent instruction file.
Does Cline read DESIGN.md automatically?
Do not assume it will. Add an explicit persistent instruction that requires the agent to read DESIGN.md before front-end work.
Should DESIGN.md duplicate the component library?
No. Point to real components and tokens, then document usage, composition, responsive behavior, states, and guardrails that code alone does not explain.
How do I know the integration is working?
Ask the agent to identify the relevant tokens and components before coding, then inspect the diff and compare the rendered result at desktop and mobile widths.