Briefatto LabBriefatto Lab

Questions

Why is Cursor bad at UI design, even with detailed visual instructions?

Detailed visual instructions are still words, and Cursor has to guess the exact values behind every one of them. Give it a DESIGN.md whose styles were recorded from your rendered pages, pointed to from AGENTS.md, and let board check measure what it drew.

Updated Markdown version

Briefatto BoardFree and open source, Apache-2.0

Blind-tested against Impeccable, Taste Skill and Hallmark

Automated tests, green CI

Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf and any agent that reads AGENTS.md

Words lose the values

"Warm, generous spacing, soft corners, a confident headline" reads clearly to you because you have seen the site. Cursor has not. On every request it turns your adjectives back into colours, sizes and radii, and each guess lands somewhere new.

Cursor's own rules documentation pushes the same way: keep rules under 500 lines, make them focused, actionable and scoped, start simple, and add a rule only when the Agent repeats a mistake. A paragraph of adjectives is long, vague and unscoped, the opposite of each.

What works is a record. board freeze writes the exact styles of a fresh render into DESIGN.md beside the prose, and for a new brand the intent travels as pictures: a reference sheet and three drawn directions you pick from.

Set it up in Cursor

  1. Run npx briefatto-board install. It writes a marked block into AGENTS.md, which Cursor's documentation lists as agent instructions, and puts the skill in .claude/skills/, which Cursor also loads.
  2. Existing site: run npx briefatto-board adopt ., let Cursor's agent write DESIGN.md from the captures, then npx briefatto-board freeze ..
  3. New brand: put the brief in brief.md and ask the agent to follow the skill through references, directions, pick and freeze.
  4. Ask for the screen. Save it as its own file and run npx briefatto-board check . <file.html> before you accept it.

The measurement under it

In our drift test, agents with no design file matched the brand's fonts in 0 of 18 pieces. With a DESIGN.md they matched in 53 of 54.

board check then covers what a file cannot: it renders the piece and fails clipped, overlapping or too-small text, fonts that never loaded, contrast below WCAG and the Impeccable detector's anti-patterns, with exit status 1.

Questions and answers

Should I delete my .cursor/rules?

Keep them for code. Move the design out of them into DESIGN.md, and let the block in AGENTS.md point Cursor there: Cursor's documentation lists AGENTS.md as a plain-markdown alternative to .cursor/rules.

Does Cursor read DESIGN.md by itself?

Cursor reads AGENTS.md, and the Briefatto Board block in it tells the agent to read DESIGN.md before any visual work and to run board check before handing a piece over.

How do I stop Cursor using colours outside my palette?

Run npx briefatto-board check . <file.html> on each screen. On a frozen board it notes every painted colour and font not in the guide, and names the older version a stray value came from. Fix those before you accept the screen.

One guide. Every agent.

Briefatto Board is free and open source under Apache-2.0. One command adds the skill and the pointer your agent reads.

npx briefatto-board install

Sources

  1. cursor.com/docs/context/rules checked 2026-11-21
  2. cursor.com/docs/skills checked 2026-11-21
  3. github.com/Briefatto/briefatto-board/blob/main/README.md
  4. github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
  5. github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
  6. github.com/Briefatto/briefatto-board/blob/main/src/board/cli.ts
  7. github.com/Briefatto/briefatto-board/blob/main/src/board/check.ts