Visual Direction
Decide what the interface should feel like, and why, in one paragraph and a handful of tokens — then build from that instead of from a kit.
Generic UI usually comes from skipping this step: the first available palette, font, and layout fill the vacuum. A direction does not need to be bold. A calm, conventional direction chosen on purpose is still a direction.
When to Use
- Before building any user-facing page or app shell
- When
ui-template-auditscores a page high and patching won't fix it - When a brand exists only as a logo and needs to become a UI
- When multiple agents or contributors need to produce consistent screens
When NOT to Use
- An established design system already exists and the task is to follow it — follow it
- Pure backend or CLI work
Relationship to Other Skills
Anthropic's frontend-design skill covers grounding design in subject matter and planning a design system before building. This skill turns that into a concrete artifact (direction statement + tokens + constraints) that can be handed to other agents, checked into the repo, and reviewed. If frontend-design is installed, use both: this skill's output is a good input to it.
Workflow
Step 1: Collect Inputs from the Subject, Not from Other Startups
Answer in writing:
| Question | Example answer (hypothetical climbing-gym app) |
|---|---|
| What is the subject's physical or cultural world? | Chalk, plywood walls, colored holds, route tape with grades written in marker |
| Who uses it, where, on what device? | Members on phones, between climbs, often with chalky hands |
| What is the one job of the main screen? | See today's new routes and log a send |
| What existing materials are real? | Route-setter photos, the gym's hold colors, grade system (V-scale) |
| What must it never feel like? | A fintech dashboard; a fitness-tracker gamification app |
The subject's own vocabulary (materials, artifacts, signage, documents) is the most reliable source of distinctiveness. Competitor sites are the least reliable: copying them produces the same look.
Step 2: Gather Two or Three Concrete References
References should be things, not adjectives. "Clean and modern" is not a reference.
- Physical artifacts from the subject (a route card, a ticket stub, a field guide page)
- One typographic reference (a specimen, a printed publication)
- One interaction reference if motion matters
For each, write one line on what you are taking from it: "route tape: hand-marked labels, strong color coding by grade".
Step 3: Write the Direction Statement
One paragraph, four parts: subject, feeling, the signature element, and what is deliberately avoided.
## Direction
A route board you can carry. The interface borrows the gym's own system:
hold colors identify routes, grades are set large like marker on tape, and
the background is the warm off-white of fresh plywood rather than app gray.
The signature element is the route chip — a rounded tape shape in the hold
color with the grade in heavy condensed type. We avoid gradients, glass
effects, and leaderboard gamification; progress is shown as a plain log.
Test it: could this paragraph describe a competitor's product? If yes, it is not specific enough.
Step 4: Set Constraints
Constraints make a direction enforceable. Pick a few that follow from the statement:
## Constraints
- Color: hold colors are the only saturated colors; UI chrome is neutral
- Type: one display face (condensed, heavy) for grades and headings; one text face
- Shape: one radius family (tape: 6px); no shadows except on the bottom sheet
- Motion: only on logging a send (one short confirmation); none on scroll
- Imagery: real photos of the walls; no illustrations
Step 5: Translate into Starter Tokens
:root {
color-scheme: light dark;
/* Surfaces: neutral, warm */
--surface: light-dark(oklch(97% 0.012 80), oklch(20% 0.01 80));
--surface-raised: light-dark(oklch(100% 0 0), oklch(25% 0.01 80));
--text: light-dark(oklch(22% 0.02 60), oklch(94% 0.01 80));
--text-muted: light-dark(oklch(45% 0.02 60), oklch(75% 0.01 80));
/* Content colors come from the subject (hold colors), not the brand kit */
--hold-red: oklch(58% 0.19 27);
--hold-blue: oklch(55% 0.15 255);
--hold-yellow: oklch(86% 0.16 95);
/* Type */
--font-display: "Your Condensed Face", system-ui, sans-serif;
--font-text: system-ui, sans-serif;
/* Shape */
--radius-tape: 6px;
}
Every value above is a placeholder to be contrast-checked; see typography-and-color-systems and accessible-by-default. light-dark() requires color-scheme to be set, and is Baseline 2024, so provide a fallback if you support older browsers.
Step 6: Prove It on One Screen
Build the single most characteristic screen first (here: today's routes). Review it against the statement before building anything else. If the screen could be swapped into a different product without anyone noticing, revise the direction, not just the CSS.
Step 7: Record It
Commit the statement, constraints, and tokens (for example docs/design-direction.md plus a tokens file) so later contributors and agents inherit the decision instead of re-defaulting.
Common Failure Modes
| Symptom | Cause | Fix |
|---|---|---|
| Direction reads like a mood ("bold, playful, premium") | Adjectives instead of references | Replace each adjective with a thing from the subject |
| Signature element appears everywhere | Overuse | Use it where it carries meaning; let the rest be quiet |
| Direction ignored after screen two | Not written down | Commit it; reference it in the project's agent instructions |
| Distinctive but hard to read | Style overrode function | Function wins; adjust within the direction |
Best Practices
- Derive the look from the product's subject matter, not from what similar products use
- Keep the statement to one paragraph; a long brief gets skimmed
- Name one signature element and protect it from overuse
- State what is avoided as clearly as what is chosen
- Turn the direction into tokens early so it survives handoff
- Build the most characteristic screen first and review it before scaling out
- Treat taste as a reasoned argument: explain choices so others can disagree productively
- Accessibility constraints are inputs to the direction, not a later pass
References
- Anthropic
frontend-designskill: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md - MDN,
light-dark(): https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark - MDN,
oklch(): https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch - MDN,
prefers-color-scheme: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme