COLORS.md: the file every AI project needs

Every project has a README.md. Most have a .gitignore. Many have a CLAUDE.md or .cursorrules. But almost none have a COLORS.md. And that's why every AI-generated component in your project uses the wrong colors.

COLORS.md is a plain markdown file in your project root that describes your color palette in a format AI coding tools understand. Roles, values, contrast ratios, tokens, and rules. Everything an AI needs to use your colors correctly, in a format every tool already knows how to read.

This is the deep dive. What goes in it, how each tool reads it, how to maintain it, and why markdown is the right format.

What goes in a COLORS.md

Roles

Every color in your palette has a job. COLORS.md assigns five semantic roles:

• Background — the default surface. Page backgrounds, card fills, modal backdrops. This is the canvas everything sits on.
• Ink — primary text and content. Headings, body copy, icons. The color people read.
• Accent — calls to action and highlights. Buttons, links, active states, badges. Used sparingly for maximum impact.
• Support — secondary content. Captions, metadata, timestamps, helper text. Present but not dominant.
• Neutral — structural elements. Borders, dividers, disabled states, subtle backgrounds. The skeleton of the UI.

Roles turn a hex list into a design system. The AI doesn't just know what your colors are — it knows what they do.

Contrast ratios

COLORS.md includes pre-computed WCAG contrast ratios for every meaningful color pair. Ink on background. Accent on background. Ink on accent. Support on background. Each pair gets a numeric ratio and an explicit AA/AAA pass/fail status.

This matters because AI tools don't calculate contrast ratios on the fly. If you don't tell them which combinations are accessible, they'll use whatever looks right to the model — which may or may not pass WCAG guidelines.

With contrast data in the file, the AI can make accessibility-correct decisions without doing math. It knows that ink-on-background passes AAA but accent-on-background only passes AA for large text. It acts accordingly.

CSS variables and Tailwind tokens

COLORS.md includes ready-to-use code blocks. Semantic CSS custom properties:

• --color-bg: #F5DBC1;
• --color-text: #2D1B0E;
• --color-primary: #FC6911;
• --color-secondary: #8B6F47;
• --color-muted: #A39484;

And a Tailwind v4 @theme block that maps to the same values. The AI copies these directly into your code. No translation, no interpretation, no getting creative with naming.

Rules

This is the section most people would skip if they wrote the file by hand. And it's the most important one.

Rules tell the AI what not to do. Every palette has constraints that aren't obvious from the values alone:

• Never use the accent color for body text — the contrast ratio against the background is insufficient for small text
• Always use ink-colored text on accent buttons, not white
• Don't place support-colored text on the neutral background — the contrast is too low
• Do not invent new colors outside this palette
• Maintain minimum 4.5:1 contrast ratio for normal text, 3:1 for large text

Without rules, the AI makes "reasonable" decisions that break your system. With rules, it stays on brand and stays accessible.

How each AI tool reads it

Claude Code

Claude Code reads project files automatically at the start of every conversation. A COLORS.md in your project root is picked up as context. You can also reference it explicitly in your CLAUDE.md instructions file — "Always use the palette defined in COLORS.md" — which makes it a hard constraint rather than optional context.

Claude Code is particularly good with COLORS.md because it understands the role structure and applies rules proactively. It will refuse to use your accent as body text before you even ask. Full Claude Code integration guide.

Cursor

Cursor indexes your workspace files and uses them as context when generating code. COLORS.md in your project root becomes part of the codebase context. For even stronger enforcement, copy the file into .cursor/rules/ — Cursor treats files in that directory as persistent instructions.

Cursor's composer and inline edit features both pick up the palette. Components generated in Cursor will use your tokens instead of defaults. Full Cursor integration guide.

Windsurf

Windsurf reads project files for context, same principle as Claude Code and Cursor. Drop COLORS.md in the root and it's available in every Cascade conversation. Windsurf's flow-based editing picks up the palette when generating multi-file changes.

GitHub Copilot

Copilot uses open files and workspace context for suggestions. Keep COLORS.md open in a tab, or reference it in your prompt with @workspace mentions. Copilot Chat picks up the file content and uses it for inline completions and chat-based generation.

v0, Bolt, and other generative tools

Tools that don't read your filesystem need a different approach. Copy the palette section from COLORS.md and paste it into the system instructions or initial prompt. The structured format works the same way — the AI gets roles, values, and rules regardless of how it receives the data.

How to maintain it

COLORS.md is a living file. When your palette changes, the file should change too.

Regenerate, don't edit by hand. If you update a color, you need to recalculate contrast ratios, update CSS variables, update Tailwind tokens, and review rules. Doing this manually is error-prone. Paletter regenerates the entire file from your updated palette in one click.

Commit it to version control. COLORS.md belongs in your repo alongside your code. Every developer on your team gets the same palette context. Every branch has the right colors. Pull requests that change the palette include the updated COLORS.md.

One file per project. If you have a monorepo with multiple apps that use different palettes, put a COLORS.md in each app's root directory. AI tools scope their context to the working directory, so each app gets its own palette.

Review it in PRs. When someone changes COLORS.md, review it like any other design system change. Check that contrast ratios still pass. Verify the rules make sense. This is your single source of truth for color.

Why markdown

You might wonder why not JSON. Or YAML. Or a design token format like Style Dictionary.

Universal readability. Every AI tool reads markdown natively. It's the lingua franca of project documentation. No parsing needed, no schema required, no tooling to install.

Human readable. Your team can read COLORS.md without a token viewer or design tool. Open it in any text editor. Read it on GitHub. Review it in a PR diff. No special tooling.

AI optimized. Large language models understand markdown structure — headings, lists, code blocks, emphasis. They parse it naturally. A markdown table of color roles with hex values and descriptions is more useful to an AI than a JSON blob with the same data.

Convention, not configuration. README.md didn't need a spec. CLAUDE.md didn't need a plugin. COLORS.md doesn't need a build step. Drop it in the root and it works. The simplicity is the point.

Learn more about how Paletter generates AI-ready palettes.