INSTRUCTIONS.md

Free

The rules your agent should never forget, in about forty lines: build with WunderUI components, no raw colours, motion and copy from the system. Short enough to live in CLAUDE.md or AGENTS.md, so every session starts with them — DESIGN.md and the MCP server answer the rest.

Open INSTRUCTIONS.md

What it is

DESIGN.md is the whole design system — too long to load into every conversation. is the part that must always be there: the rules for agents, the motion rules and the copy rules, each as one line. It is generated from the same source as DESIGN.md, so the two never disagree.

Add it to your project

Append it to the rules file your agent reads at the start of every session:

bash

# Claude Code
curl -s https://wunderui.com/INSTRUCTIONS.md >> CLAUDE.md

# Codex and other agents that read AGENTS.md
curl -s https://wunderui.com/INSTRUCTIONS.md >> AGENTS.md

# Cursor
curl -s https://wunderui.com/INSTRUCTIONS.md -o .cursor/rules/wunderui.md

With the MCP server connected, the agent can also fetch it itself with the tool . The free skill wunderui-setup adds it while it sets up a project.

The file

markdown

# WunderUI — instructions for your coding agent

Paste this into CLAUDE.md, AGENTS.md or .cursor/rules. It is the short, always-on version;
the full context is https://wunderui.com/DESIGN.md and the MCP server answers everything else
(`claude mcp add wunderui -- npx -y wunderui-mcp`).

## Always
- Never hardcode colours.
- Theme by overriding tokens, not by restyling components.
- Dark mode is a `.dark` class on `<html>`.
- The package is client code.
- Import from the package root, never from `dist/` or `src/` paths.
- `cn` is not re-exported — import it from the `cn` package directly.
- Prefer a composite over rebuilding one.
- Charts take a `loading` prop; do not build your own skeleton.
- A KPI chart ends on the trend line.
- Motion comes from tokens too.
- Agent UI has its own components.
- Before writing UI by hand, look up the component: the Task → component table in DESIGN.md, or the MCP tool `list_components`.

## Motion
- Duration and easing are class names, not numbers.
- Only `transform` and `opacity`.
- Entrances decelerate, exits accelerate.
- Never fade in the LCP element.
- Restrain the travel.
- One overshoot per screen.
- Reduced motion is opt-in, not a kill switch.
- Never `transition-all`.
- Loading keeps its height.
- A looping ambient animation is the one place `ease-in-out` belongs.
- Animate by frequency.
- Anchored surfaces grow from their trigger.
- Toggles stay interruptible.
- Hover only where hover exists.
- Reduced motion keeps the fade.

## Copy
- Buttons say what happens.
- Sentence case everywhere in the product.
- Errors say what happened and what to do.
- Empty states explain and offer one action.
- Labels are nouns, hints are sentences.
- Numbers carry their unit.
- No filler.
- Confirmations name the object.

## Before you finish
- Run the free skills `wunderui-token-check` (no raw colours) and, with Pro, `wunderui-motion-audit` and `wunderui-a11y` on the files you changed.
- Check light, dark and 390 px.

https://wunderui.com/DESIGN.md · https://wunderui.com/skills · https://wunderui.com/llms-full.txt

Which file when

Situation	Reach for
Every session, always on	INSTRUCTIONS.md in CLAUDE.md / AGENTS.md
Your editor speaks MCP	the MCP server
Plain chat, building a whole screen	DESIGN.md
A small context window, or one file with everything	llms-small.txt / llms-full.txt