# When AI ignores DESIGN.md

> Check whether your agent reads DESIGN.md, resolve conflicting instructions and connect design rules to real components and visual checks.

Canonical page: https://sitepeel.dev/guides/ai-ignoring-design-md/

Check that the file is loaded, relevant and unambiguous. Then verify the rendered result against its rules. Having the file in a repository is only the starting point.

## Confirm the agent is reading the right file

First separate a loading problem from a design problem. Ask the agent to open the exact project file and identify the rules it will use for the requested component. Check the actual file-read activity when your tool exposes it. A confident summary from memory is less useful than evidence that the current file was read.

Project instruction conventions differ between tools. AGENTS.md documents agent-facing project instructions for tools that support it. Claude Code documents CLAUDE.md and its file-import syntax. Do not assume every tool automatically loads a file named DESIGN.md. Connect the design reference through your tool’s supported project instructions, or explicitly attach it to the task.

Example: CLAUDE.md

```
# UI work

@DESIGN.md

Before changing the interface, inspect the existing shared components.
Use the named design tokens and component variants.
If this reference conflicts with the current implementation,
identify the conflict before making a new design choice.
```

## Remove contradictory rules and stale references

Search the project for other design instructions. A root reference might specify one typeface while a nested package document specifies another. An old prompt might ask for a new visual direction even though the task is a small bug fix. Resolve the contradiction where it lives rather than adding another warning to the end of DESIGN.md.

Check file paths too. If the document points to a component that moved or a token file that no longer exists, the agent has to guess. Keep the reference close to the implementation it describes. A short list of current component paths and approved variants can be more useful than several pages of aspirational style language.

## Turn visual intentions into concrete choices

A rule such as “keep spacing consistent” does not say which value belongs between a field and its label. Give recurring values names, describe their roles and show one component that already uses them well. Identify which values are fixed and which can adapt to the available space.

If you create the reference from a website with Sitepeel, review it before asking an agent to follow it. An extracted page can contain one-off campaign styling, multiple font families or accidental spacing. Choose the decisions that belong in your project. A record of everything observed is not automatically a coherent specification.

- Specify the existing token or component to reuse.
- Include a concrete example of the intended result.
- Describe narrow-screen behavior and longer-content behavior.
- Remove rules that no longer apply to the project.

## Give the task a small, reviewable scope

Ask for one representative component or screen first. A task that simultaneously changes navigation, authentication, pricing and visual style has many competing requirements. If the design direction is uncertain, making the whole application at once multiplies the amount of work that needs correction.

Before implementation, request the component paths, token choices and relevant design rules. After implementation, compare the rendered screen with the reference using the same content and viewport. If a rule was missed, record the specific mismatch and correct it. Repeating “follow DESIGN.md exactly” gives less useful feedback than identifying the incorrect heading scale.

## Verify the result instead of relying on a promise

Use checks where they provide evidence: confirm that shared tokens are imported, compare representative screenshots, and test the component’s keyboard and error states. A screenshot can reveal layout drift, while a code review can reveal a hard-coded value that happens to look correct today.

Instructions influence an agent; they do not make every outcome deterministic. Treat DESIGN.md as a maintained reference within a review process. Once a correction is approved, update the underlying component or token and keep the document accurate. This prevents the same disagreement from returning in the next task.

## Further reading

- [Reddit: an agent repeatedly missing project instructions](https://www.reddit.com/r/codex/comments/1wdx5jx/have_agent_respect_the_agentsmd/)
- [AGENTS.md: project instructions and supported tools](https://agents.md/)
- [Claude Code: file imports and instruction troubleshooting](https://code.claude.com/docs/en/memory)

## Related pages

- [Design MD generator](https://sitepeel.dev/design-md-generator/index.md): Generate a Design MD reference from a website. Extract typography, colors and spacing into a visual guide and Markdown for your next project.
- [Create a Design MD file](https://sitepeel.dev/guides/create-design-md-from-website/index.md): Extract a website’s design details, review the tokens and export a useful Design MD reference. Includes a Markdown example you can copy.
- [Keep designs consistent across projects](https://sitepeel.dev/guides/keep-ai-ui-consistent-across-projects/index.md): Keep separate websites and dashboards visually consistent with shared design tokens, reusable components and a small, versioned design reference.