Alternatives to a hand-written design rules file

Many AI coding agents read a project instructions file, such as CLAUDE.md or AGENTS.md, at the start of a session. Writing your design rules there is a sensible step: list your colours and fonts, say "no gradients" and "8 px spacing grid", and the agent sees it every time.

It's free, it lives in your repo and it beats repeating yourself in every prompt. It also runs out of road sooner than people expect. This page covers where, and four alternatives that pick up where a rules file stops.

What a rules file does well#

• It lasts. Unlike a prompt, it's there in every session and for every teammate who uses the repo.
• It's versioned. Changes go through the same review as code.
• It covers more than design. Stack choices, naming, testing and how you like changes made all belong there too.
• It's free and quick. A short, useful one doesn't take long to write.

Where it runs out#

• Words, not components. "Buttons are pill-shaped with a soft shadow" still leaves the agent to write the button, and it writes it slightly differently each time.
• Motion is hard to describe. "Snappy but smooth" means a different spring to every reader. Without numbers and a component to copy, the agent reaches for a default fade.
• It's easy to let it go stale. When you change the accent colour, you have to remember to change the file, and every place the old value was copied.
• Long files lose force. The more you write, the more each rule competes with everything else the agent is holding in mind.
• No feedback. Nothing tells you when a screen broke a rule. You find out by looking.

1. Pair it with a tokens file#

Move the values out of prose and into code: CSS variables or a Tailwind theme for colours, type, radii, spacing and shadows. The rules file then says "use only the tokens", and the values are exact rather than described.

This is the cheapest upgrade and worth doing whatever else you choose. It doesn't help with components or with most motion.

2. Add a lint step#

Lint rules and checks in CI can catch hard-coded colours, arbitrary spacing values or banned patterns in pull requests. They turn some of your rules from requests into checks. They're good at catching values that break the rules, but they don't tell the agent what to use instead, and you write and maintain them yourself.

3. Give the agent a component library#

Install components, theme them with your tokens, and point the rules file at them: "use the Button component, never a plain button". The agent now has real code to reuse instead of a description to follow. You still have to keep the list of which component goes where up to date, and the motion is whatever the library ships. Component libraries vs a design sheet goes through the trade-offs.

4. Let the agent look up a design sheet#

A Wuizard sheet keeps the design rules, but next to them sits everything the rules were trying to describe: foundations (colour, type, radius, spacing, shadows and a motion spring), and slots holding one chosen component each, such as button.primary, transition.modal and feedback.toast. You fill the slots from a live library where every component reads your foundations.

Your agent connects over MCP and asks rather than remembers. get_sheet returns the foundations and the rules before it builds, get_slot returns the exact component with your values, and check_ui reviews what it wrote and lists anything outside the sheet, which is the feedback a rules file can't give. The rules themselves stay short and specific, like "never introduce colours outside the foundations", and you can switch one off without deleting it.

You still get a file, too. Exporting a sheet writes CLAUDE.md and AGENTS.md with the rules and foundations, plus the tokens and components, for agents that aren't connected. The trade-offs: the AI features are a paid service, live reads need a connection, and the components are React first, with translate_asset for Vue, Svelte, SwiftUI and vanilla JS.

Side by side#

Which one to pick#

• Your rules file is working? Keep it, and add a tokens file so the values are exact.
• Values drift in pull requests? Add a lint step.
• The agent keeps writing its own components? Give it components: a library you theme, or a sheet whose slots it fetches from.
• Motion is the part that never matches? That's the gap prose fills worst. A sheet's motion slots and shared spring are built for it, and the modal and overlay animations topic shows the kind of thing a rules file can't describe.

Whatever you choose, the aim is the same: fewer things the agent has to remember, and more it can look up. The MCP setup guide covers connecting an agent to a sheet.