Sik.limited Logo

Build a design system for Claude Code and Codex

Give both coding agents shared design guidance while keeping their instructions clear.

·

When a team switches between Claude Code and Codex in the same repository, one agent may follow the design rules while the other falls back to defaults. A good way to reduce that gap is to separate tool instructions from visual design rules, then have both agents refer to the same source of design context.

The goal is not to force every tool to use one filename. It is to give each file a clear job.

Design Principles and Agent Instructions

Use DESIGN.md for the product’s visual identity and UI rules. Record color tokens, typography, spacing, corner radii, and the usage and states of important components. Use CLAUDE.md and AGENTS.md for how an agent should work. Examples include checking for existing components first, identifying project conventions, and explaining a conflict between a request and the design rules.

This separation means you can update the brand guidance in one place while adjusting tool-specific commands or review steps in each tool’s instruction file. The design document is the source of visual decisions; the tool instruction file is the signpost that tells the agent where to find and apply them.

Configuring CLAUDE.md and AGENTS.md

Claude Code supports CLAUDE.md project instructions and can also read AGENTS.md, but its default loading behavior matters. By default, if a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or any parent directory, Claude reads the CLAUDE.md files only and skips AGENTS.md. If none of those files exists, Claude Code v2.1.277 or later reads the AGENTS.md and .claude/AGENTS.md files in the working directory and its parents. You can choose claude-md-and-agents-md in /config to load both kinds of files, or put an @AGENTS.md import in CLAUDE.md to share the rules. Check /memory or /context all to confirm what actually loaded.

Codex recognizes AGENTS.md as repository instructions. A practical repository layout might look like this:

project/
├── DESIGN.md
├── AGENTS.md
├── CLAUDE.md
├── src/
└── docs/

Rather than copying a long set of rules into both AGENTS.md and CLAUDE.md, keep a brief shared pointer in each and add only instructions specific to that tool. This helps prevent the design guidance from drifting between duplicate copies.

For example, AGENTS.md could say:

## Project instructions

- Before changing UI, read the root DESIGN.md and relevant component docs.
- Reuse existing tokens and components before adding new values.
- If a request conflicts with the design rules, explain the conflict and use the narrowest change.
- For visual changes, report the pages and states that need review.

If you want one shared file, Claude Code can import AGENTS.md from CLAUDE.md with @AGENTS.md, or you can select claude-md-and-agents-md in /config. Direct AGENTS.md loading requires v2.1.277 or later and may be unavailable in some sessions or configurations, so verify the loaded files with /memory or /context all.

Writing Project Instructions

Put recurring guidance in the root instructions. For example, “Check for an existing Button component variant before creating a new button” applies to most UI work. A special accessibility check for one directory or a separate test procedure may belong only where it is needed. Claude Code supports path-specific rules in .claude/rules/; Codex can use nested AGENTS.md files for directory-specific instructions.

Broad rules can make small changes unnecessarily heavy. Instead of “read every document before every task,” write “check DESIGN.md when changing layout, and check the API docs when changing an API.” OpenAI’s Codex guidance also recommends keeping instructions relevant and pointing to the context needed for a particular task.

Design Rules in DESIGN.md

Even if tool instructions tell the agent to read the design document, abstract adjectives alone will still produce different results. Write rules that guide concrete choices. Replace “friendly and minimal” with observable expectations.

---
name: Northstar Console
colors:
  primary: "#2457D6"
  canvas: "#F4F6FA"
  ink: "#172033"
  border: "#D8DEE9"
rounded:
  control: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.control}"
    padding: 10px
---

## Overview

An operations console where staff scan order status quickly.
Use strong colors only for primary actions and selected states.
Do not use shadows on default cards; distinguish selected items with a border.

For example, when Codex is asked to implement an empty state in an order list, DESIGN.md can describe how empty, error, and selected states use color and copy. Claude Code can refer to the same color roles and spacing rules for the same task.

Validating AI-Generated Results

Claude Code’s official docs describe CLAUDE.md and AGENTS.md as context, not enforced configuration. Even when the files are loaded, the agent may not follow every rule. Specific, concise instructions tend to work more consistently. If an action must be blocked, a sentence in an instruction file cannot guarantee that; use permission settings or hooks that enforce the restriction.

DESIGN.md is not automatically loaded by every coding agent either. Check whether each tool supports the format and whether the file actually appears in its context. If necessary, reference it explicitly in CLAUDE.md and AGENTS.md, and name it in the task prompt.

Testing Screens and Component States

Do not redesign the entire app at once. Start with one small screen and compare the two tools. For example: “Implement the default, error, and disabled buttons in the order detail screen. Check for existing components first.” Review more than colors and spacing. Check keyboard focus, disabled states, long copy, and narrow viewport layout too.

When both results miss the same rule, improve DESIGN.md. If only one tool failed to find the instructions, fix that tool’s file loading or project guidance. Keeping those causes distinct makes the system easier to maintain.

Managing Design System Changes

The most common problem with separate design documentation is drift. When CSS tokens or components change, update DESIGN.md as part of the same work and review the change alongside the implementation. As the rules grow, separate what is used across the whole product from what applies only to a particular area.

Having two agents use the same design system does not mean their outputs will be identical. It means they start from a shared source of design decisions, and each tool has a clear way to load and apply it. Include which files were read and which screen states were checked in the work summary to make it easier to see whether the documented rules reached the product.

References

Latest posts