AI Draws Out of Your Style: How to Get It to Follow a Design System

AI explained that the buttons are called Button/Primary, accent #E94560, font Bricolage Grotesque. This session is all right. Closed the chat. Opened a new one - again Inter, again blue button, again shadcn by default.

AI does not store memory between sessions. Every time from scratch. Manually explaining each time is not a workflow, it is a waste of time.

## Two Mechanisms Why AI Gets Hit

Distributional convergence. Without context, the model sampled from a statistical training data center. The center looks like a shadcn with an Inter and a blue accent. It's math, not a bug -- you can only change behavior in explicit context.

Context is not persistent between sessions. Claude Code, Cursor, v0 – all work without memory between sessions. Explained in one session - in the next AI doesn't know again.

Solution: Not to explain every time. Create files that AI reads automatically every time you start a project.

## Level 1: DESIGN.md – Visual Rules

File at the root of the repository. Claude Code reads it the first time you refer to a project in a session. It contains the visual rules of the product.

#DESIGN. md

##Typography
Heading (H1–H2): Fraunces, weight 700
Body text: Bricolage Grotesque, weight 400
Code, numbers: JetBrains Mono

Prohibited: Inter, Roboto, Open Sans, Arial, System Fonts

Colors – CSS variables only
Primary background: var(-color-background-primary) → #1A1A2E
Accent (CTA, active): var(-color-brand-accent) → #E94560
Surface (cards): var(-color-background-surface) → #F5F5F0

PROHIBITED:
- Purple-blue gradients on a white background
Glassmorphism without a functional cause
- Hardcut hex values in the code

Spacing - ONLY through var(-spacing-*)
4px grid: 4, 8, 12, 16, 24, 32, 48, 64px
Prohibited: arbitrary values (13px, 22px, 37px)

## Components - Only existing
Button/Primary, Button/Secondary, Button/Ghost, Button/Danger
Cards: Card/Default, Card/Featured, Card/Compact
Fields: Input/Default, Input/Search, Input/Textarea

Prohibited: Create new versions without adding to the library

## Visual Anti-patterns - Prohibited
Three identical cards in a row without content variation
Constantly animated background in work interfaces
Hero with a purple-blue gradient on a white background

## Level 2: AGENTS.md – working conventions

Supplements DESIGN.md with working rules - not about the appearance, but about the process.

## File structure
src/components/ui/ System components (read only)
src/components/ - Product components (can be created)
src/lib/billing/ – Do not touch without an explicit request
src/lib/auth/ Do not touch without an explicit request

## Working with components
Before creating a new one: check if src/components/ui/
If there is, use it. If not, be clear.

# Required for each component
TypeScript interface for all props
Loading/error/empty states wherever data is available
- aria-label for icons without text, alt for images
All colors through CSS variable tokens

## Level 3: Golden Screen

One reference screen in Figma uses the maximum set of system elements. All typographic levels, all button types, card, form, navigation. It's fixed as Reference.

Where consistency is important:

The new screen should be consistent with Golden Screen.
(Reference/Dashboard page in Figma via MCP)
Use the same components, indentations, hierarchy.

Golden Screen anchor. AI doesn't drift if you're explicitly referring to it.

## Level 4: Automatic check in CI

// .eslintrc.js — запрет захардкоженных hex
'no-restricted-syntax': ['error', {
  selector: 'Literal[value=/^#[0-9a-fA-F]{3,6}$/]',
  message: 'Используй CSS-переменную. Например: var(--color-brand-accent)'
}]

The most common violation is hex in the code. The rest is through a rev.

## Why DESIGN.md is more effective than prompts

It seems that you can just add rules to each prompt. It works, but it doesn't scale well for three reasons.

Prompt with rules competes with the description of the problem for the attention of the model. A long prompt is worse than both the rules and the task. DESIGN.md is read once at the beginning of the session and remains in context without competition with the task.

Different people on the team write prompts differently. One added the rules, the other forgot. DESIGN.md is the only source for the entire team. No discrepancies.

In a long session, AI can “forget” the rules from the beginning of the conversation. DESIGN.md can be mentioned at the beginning of each prompt with one line: "Read DESIGN.md." It's cheaper than explaining it all over again.

## What to do when AI continues to break

Each violation is a signal that the documentation is incomplete. Not "AI bad.".

The rule is too vague. Use the right typography → Use Bricolage Grotesque for body, Fraunces for H1–H2. Never Inter. Specificity works.

The rule is buried in a long file. AGENTS.md is up to 200 lines long and important rules are lost. Critical rules are closer to the beginning.

AI observes at the beginning but violates by the end of a long session. Add a reminder to each prompt: "Read DESIGN.md." Components in the list only.” Two lines, no duplicate content.

## Quality Test: How to Know if the System Works

Consistency test (once every 2 weeks).

Terms: give only DESIGN.md and AGENTS.md, without other instructions.
Task: Create a user list screen with a search and filter.

Checking:
Bricolage Grotesque Font (not Inter)
Buttons from DESIGN.md (Button/Primary) are not new
Colors in var(--color-*), not hex
Card/Default or Card/Compact (not a new component)
● No three cards are the same without variation.

Add an explicit ban to DESIGN.md.

## Prompt with full protection

Read DESIGN.md and AGENTS.md before you start.

Task: [Description]

Limitations specific to this task:
- Only components from DESIGN.md, do not create new ones
All colors through var(--color-*), no hex
Font: Bricolage Grotesque for text, Fraunces for headlines
Check with Golden Screen (Reference to Figma via MCP)

Upon completion:
List all the components you use (exact names)
List the CSS color variables you have used
If you have created something new (not from the library)

## How DESIGN.md evolves with the product

DESIGN.md, written once and not updated, is an outdated document that misleads AI. After six months without updates, it describes the product as it was, not as it is.

Practice that works: Update DESIGN.md in the same PR that changes the visual system. The accent color has changed – it has updated the token in CSS and the value in DESIGN.md in one commit. A new version of the component was added to the list of allowed components.

Another practice: once a month to view DESIGN.md and remove the outdated. The component that has been removed from the system is removed from the list. A rule that was added but never violated may have become superfluous.

DESIGN.md, which is actively supported, is a living tool. DESIGN.md, which has not been touched for three months, is probably outdated.

## Team and DESIGN.md: How to Involve Everyone

DESIGN.md is most effective when the entire team understands it. Several practices that help:

New person onboarding: The first day includes reading DESIGN.md and AGENTS.md. Don't "see when the time is" is a clear part of onboarding.

Review through the system: When checking PR, ask “does this violate something in DESIGN.md?” instead of subjective judgments about beauty. The objective criterion eliminates disputes.

An update via PR with a description: A change to DESIGN.md is a PR describing why the rule is added or changed. Creates a decision history and allows the team to discuss before application.

## Anti-pattern: Too many rules

DESIGN.md with 500 lines of rules is worse than DESIGN.md with 50 lines.

When the documentation is too extensive, AI starts to apply the rules incorrectly: adds aria-label to each element, including those that do not need it, or tries to apply typography tokens to icons. Overloading with rules creates new problems.

Principle: Only rules that AI violates without them. If AI never puts transition: all, don’t ban it from DESIGN.md. If AI sometimes uses Inter, bans are explicit.

The best way to determine what to add: a test from the previous section. What AI has broken is prohibition. What is not violated, do not add preventively. Documentation grows from real problems, not from perceived ones.

## A real estimate: how much time the system saves

A team of 3 people (1 designer, 2 developers) without a system spends on average:

• 3 hours a week to ask “how to do it”
• 2 hours a week to correct design/code discrepancies
• 4 hours a week to edit the AI generation that is “a little wrong”

Total: 9 hours a week. At the cost of an hour, $50 - $450 per week, $1,800 per month.

With the system (DESIGN.md + AGENTS.md + MCP), these numbers drop to about 2-3 hours per week. Savings: $300 a week. The time to create the system is about 40 hours. It pays off in 2 months.

It's not marketing numbers, it's a real calculation that you can show stakeholders.

DESIGN.md: typography + colors + components + anti-patterns
AGENTS.md: file structure + prohibited directories
● Both files at the root of the repository
Golden Screen in Figma, reference in prompts
ESLint rule against hex in code
● Test every 2 weeks: DESIGN.md + AGENTS.md → standard screen
● Violations in the test → Update documentation (do not grumble on AI)