DESIGN.md for Claude Code: import it through CLAUDE.md

Claude Code supports @path imports in CLAUDE.md. Save the two files below in the same project directory, with @DESIGN.md on its own line. The import must be ordinary Markdown text in CLAUDE.md, outside backticks or a fenced code block. Claude Code’s documentation says imports inside those literal code examples are skipped.

The import connects your chosen design file to a documented loading mechanism. The design file itself is an informal project note. It can hold review instructions as well as colours and component choices; no special DESIGN.md schema is required for this example.

This fixture is for a fictional product called Wrenboard. Its main action should say Request access. The design note asks a reviewer to start with a particular phrase and report the label actually present. That gives you two separate observations: did the review follow the output rule, and did it compare the page with the intended label?

Copy this whole file beside CLAUDE.md. Replace the fictional product, file paths and action before using it in a real repository. The output phrase is a diagnostic aid; remove it after the loading check if you do not want it in ordinary reviews.

Claude Code resolves a relative import from the file that contains it. If CLAUDE.md is at the root beside DESIGN.md, @DESIGN.md points to that neighbouring file. If you move the importing file into a subdirectory, check the relative path again. The vendor documents that path rule; do not infer it from the shell’s current directory.

Use the exact filename and case in both places. A link that works on one filesystem can hide a spelling mistake until someone checks out the repository elsewhere. Keep this first example within one project so you can inspect both files together.

Create a local page whose main link says Join waitlist, while keeping Request access in DESIGN.md. Start a fresh Claude Code session in that project and ask for a read-only design review. Do not include the expected output phrase or label in your request: the reviewer should obtain those from the project files.

A useful result starts with Design check: and reports the label mismatch. That supports a narrow conclusion about this session using the instructions. It does not show that the layout is good, that a signup works, or that future sessions will obey every rule. For a rendered review, provide a screenshot or a browser tool and check the same page at phone width.

On 3 November 2026, Claude Code 2.1.309 reviewed a copy of this fixture with claude -p and only the Read tool enabled. It used the CLAUDE.md import and reported the deliberate mismatch at index.html line 8: the page said Join waitlist. It quoted the DESIGN.md instruction: “The main action is Request access. Use that exact label.” The command exited 0.

Its reply began: “Design check: one failure.” That failure describes the page’s label, not the review command. Claude also noted that the link reaches a local access note rather than a signup service. It made no edits and did not render or click the page. To repeat the read-only check, use the prompt above in a fresh project session. This one run demonstrates use of the imported rule on this fixture; it does not establish how every session will behave.

Add the paths to your real tokens, shared controls and approved product media. Put a specific decision beside each path: which button to reuse, what the primary action says, or which screenshot is current. That gives the reviewer something it can compare with the page.

The existing iter0 DESIGN.md guide covers those broader website decisions and includes a starter file. Keep one design note for the project and point the tools you use to it, rather than maintaining a separate palette in every tool’s instructions.