Skill for Claude
The Blue Book of UX Directives, packaged as a skill for Claude.
The skill gives Claude the full text of the book. Claude then cites the exact directive, ID and title, instead of paraphrasing UX advice from memory. A finding becomes a rule anyone on the team can look up and check, so designers, engineers, product managers and QA argue from the book, not from taste.
Who it might be for
Why
A shared, citable language with engineering
The reviewer the team doesn’t have
Acceptance criteria traced to IDs
A directive as a defect class; the ID in the bug report
Chapter 9, for systems that can be wrong in ways no fixed rule predicts
Consent and transparency in the form of an interface
Component docs that cite the rules
Labels, errors, empty states
Chapters
Start with
| Role | Why | Start with |
|---|---|---|
| Product designers | A shared, citable language with engineering | Chapters 1–6 |
| Engineers without a designer | The reviewer the team doesn’t have | 44/01—Design to prevent errors proactively. · 34/01—Acknowledge every user action. |
| Product managers | Acceptance criteria traced to IDs | 84/03—Evaluate success by measurable outcomes. · 84/02—Explicitly test underlying assumptions. |
| QA | A directive as a defect class; the ID in the bug report | 63/02—Ensure behavioral consistency within patterns. · 44/04—Surface potential errors at the earliest viable moment. |
| AI product teams | Chapter 9, for systems that can be wrong in ways no fixed rule predicts | 94/01—Design explanations to enable informed judgment. · 95/01—Calibrate confidence to actual reliability. |
| Privacy and compliance | Consent and transparency in the form of an interface | 71/01—Design consent as a continuous capability. · 75/07—Limit and state retention. |
| Design system teams | Component docs that cite the rules | 64/01—Prioritize systemic coherence over breadth. · 64/02—Define and enforce governing principles. |
| UX writers | Labels, errors, empty states | 27/01—Label in the users’ vocabulary. · 73/01—Frame errors as system conditions. |
Not on the list? Tell me in Discussions on GitHub.
Worked example: a consent banner
The Google Analytics consent banner on this site was built with Claude Code and audited with the skill every round.
Caught by the skill:
- 25/03—Make sure state is inspectable. Reopened after “Allow analytics”, the banner still said “It stays off unless you allow it.” Fix: a state line per choice — “You allowed it. Current state is on.”
- 54/07—Treat alternative input methods as primary. The banner sat last in the page: 12 Tab stops before “Allow analytics”. Fix: it now follows “Skip to content”; one stop.
Missed, then found:
- 18/06—Allow decisions to be deferred. Reopened from the footer, the banner had no way out except a choice. The owner noticed it; the builder’s audit did not. Four fresh audits of the same build each named it under this directive. Fix: “Close” and Escape.
The lesson is in the method: the book had the rule all along.
- Step 1
A request
You
Audit this consent banner.
- Step 2
Claude reads the skill’s description and loads it
SKILL.md
description: … Use this skill whenever the user asks to audit, review, or critique a UI, screen, flow, prototype, screenshot, PRD, spec, or AI feature against UX principles; …
- Step 3
index.md: subcategories picked by their “Ask yourself” questionsreferences/index.md
- 1.8 Decision-Making: “Can users of your system make sound choices without being overloaded or steered?”
- 2.5 State: “Does your system reliably remember and reveal state that affects users’ outcomes?”
- 5.4 Accessibility: “Can users with varied abilities perceive and act effectively in your system?”
- Step 4
The chapter is read and the directive quoted verbatim
references/chapter_1.md
18/06—Allow decisions to be deferred. Do not force a choice that the task does not yet require.
- Step 5
A finding in four parts
Claude
- Violates
- 18/06—Allow decisions to be deferred. (1.8 Decision-Making)
- Evidence
- Reopened from the footer, the banner had no way out except a choice.
- Fix
- “Close” and Escape.
- Severity
- High, Medium or Low, by consequence to the user.
Audited by the agent that built it: Missed the way out
Audited by a fresh agent: Found it in 4 of 4
The IDs above read like this.
Make exit as easy as entry.
Provide cancellation, unsubscribing, and deletion with no more steps than signing up.
Subcategory 9.10 uses three digits, 910/05.
What it can do, and why
- Cite exactly. The book is bundled whole, so the title is quoted, not recalled.
- Find the directives for a topic. An index maps all 62 subcategories with their “Ask yourself” questions.
- Audit what it is shown. Screenshots, code, specs, flows. Each finding comes as Violates / Evidence / Fix / Severity.
- Write requirements traced to directive IDs.
- Explain any ID, including the five repealed ones and what replaced them.
What it cannot do, and why
- See what it is not shown. A skill is text and instructions. It judges what is in front of it; a state nobody opened stays unchecked.
- Measure on its own. Pixels, contrast and timing are measured only when the agent has a browser and uses it. Otherwise they are inferred from code, and the finding should say so.
- Know your history. A deliberate decision looks like a defect unless it is listed as a decision.
- Know thresholds the book does not state. The book names no numbers such as
3:1for icons. Pair it with WCAG. - Replace research. Severity is a judgment by consequence, not data about your users.
Severity is the skill’s judgment, not research. Conclusions about screen readers come from the markup unless tested with one. The book states no numeric thresholds. Chapter 9 is still forming. The measurement below is one page and four runs: a signal, not a statistic.
Install
Claude.ai:
- Download
ux-directives.skill from the GitHub repository. It is a zip of theux-directives/folder. - In Claude, open Settings → Skills and upload the file.
- Make sure the skill is turned on.
Claude uses the skill on its own when a task calls for it. You don’t need to name it. Anthropic’s guide: Using Skills in Claude.
Claude Code:
git clone https://github.com/AlehHaiko/UX-directives-skill.git
cp -R UX-directives-skill/ux-directives ~/.claude/skills/~/.claude/skills/ makes the skill available in all your projects. To share it with a team, put it in the repository’s .claude/skills/ and commit it. Claude loads it when relevant, or you type /ux-directives.
First prompts
Audit:
Audit our account settings screen against the UX Directives. [screenshot]Find by topic:
We're redesigning onboarding — new users get a 9-step tour before they can do anything. What does the Blue Book say?Requirements:
Write acceptance criteria for an LLM that drafts support replies the agent can send or edit.Explain an ID:
What does directive 22/02 say, and how does it apply to an icon-only toolbar?Make UX audits sharper
- Audit with fresh eyes. The agent that built a screen has learned it and skips what is missing. Run the audit in a separate agent that gets the page, its source, the skill and the list of accepted decisions, and not the task history. Measured once, on one page: four fresh agents found a missing way out in 4 of 4 runs; the builder’s audit had missed it. Forcing a sweep through all 62 questions did not change the result and took about a quarter longer.
- Show every state. List input × element × state × theme, so the audit sees what was never on screen.
- Label the evidence: measured, inferred from code, or assumed.
- List accepted decisions, so they are not raised again as defects.
- Pair with numeric standards such as WCAG for thresholds.
- Triage. A fresh audit also stretches directives to fit; keep the findings that decide the case.
Get it
GitHub repository · Download ux-directives.skill · Feedback · MIT License