Kero system

The design system of a project is a skill, not a document. It sits in the project, the agent finds it on its own, and it overrules the code: when a screen disagrees with it, the screen is fixed.

Where it lives

• In the project skills folder of the agent in use: .claude/skills/<project>-design/SKILL.md for Claude Code, where <project> is the short name of the project in lowercase, .agents/skills/ for Codex, .cursor/skills/ for Cursor. When several agents share the project, keep one real copy; tools that turn links into silent copies leave two files that drift apart.
• The description names every trigger: touching any screen, component or token, choosing color, type, spacing, icons, motion, focus or states, and before a screen is called finished.
• An old DESIGN.md stays only as history, with a first line that says it is no longer the source.

Where the values come from

• From the code that is running: the global stylesheet, the theme, the layout and the base components. Describe what exists, not what was intended.
• From the design.md and tokens of the reference when the code does not exist yet. Write down which values are still unconfirmed.
• Screens ask for roles, never for colors. When the palette lives in variables, trying a new one costs one file.

Sections

Use the ones the project needs, in this order. Each rule carries its reason in one line.