AI for UX · Step 2 · 6 min read
Design specs for AI
Why the written spec becomes the most important design artefact when AI can draw screens in seconds: the three layers of context, an AI-ready spec template with a worked example, the new context files (AGENTS.md, DESIGN.md), and how design fits into spec-driven development.
When AI can generate a screen in seconds, the screen stops being the hard part. The hard part is knowing what the screen should do: for whom, in which situations, under which rules. That knowledge lives in the spec. A good spec is what makes AI output yours instead of generic, and it's the thing both people and AI agents work from.
What you'll be able to do after reading:
- Explain why specs matter more, not less, when AI generates designs
- Tell apart the three layers of context: product, feature and task
- Write an AI-ready feature spec with states, rules and acceptance criteria
- Recognise the new context files (
AGENTS.md,DESIGN.md) and spec-driven tools engineers use
1. Why specs matter more now
- Vague in, generic out. "Make a booking dashboard" produces the internet's average dashboard. A spec that names the users, tasks, states, data and components produces your dashboard.
- One spec, many uses. The same document feeds a Figma prototype, a coded prototype, the engineering ticket and the test checklist.
- You can only review against something written down. Without a spec, "is this right?" becomes a matter of taste.
- Agents follow documents. AI agents that build software increasingly start from written specs. If design doesn't write the experience part, the agent will make it up.
2. Three layers of context
Stable rules every session reads: users, principles, tokens, components, "never" rules.
Typically: CLAUDE.md, AGENTS.md, DESIGN.mdWhat this feature must do: problem, users, flows, states, rules, acceptance criteria.
Typically: a spec in the wiki or repoThe request for this one iteration, inside the conversation with the tool.
Typically: "Show three options"Changes rarely → changes per feature → changes per iteration
Most poor AI output comes from a missing layer 1 or 2, not from a badly worded prompt. See Context files and Prompt patterns for designers.
The new context files
| File | What it is | Status (Nov 2026) |
|---|---|---|
AGENTS.md |
A plain Markdown file in a code repository that tells any coding agent how the project works | Open format, stewarded by the Agentic AI Foundation under the Linux Foundation (agents.md) |
DESIGN.md |
A file that describes a visual identity to coding agents: tokens in YAML plus the reasoning in Markdown | From Google Labs; still an alpha format, "expect changes" (repo) |
CLAUDE.md |
Claude Code's project instructions, read at the start of every session | Product feature (docs) |
| Design tokens (DTCG) | A shared JSON format for colours, spacing, type | First stable version Oct 2025; a W3C Community Group report, not a W3C standard (spec) |
You don't need all of them. One well-kept file with your principles, components and "never do" rules already changes the output.
3. An AI-ready feature spec template
# Feature: <name>
## Problem
What's wrong today, for whom, with evidence (research, support tickets, analytics).
## Users and context
Roles, expertise, environment (desk, on the move, noisy place), how often they use it.
## Jobs to be done
When <situation>, I want to <action>, so I can <outcome>.
## Success metrics
Task success, time on task, error rate, satisfaction.
## Scope
In: … Out: …
## Flow
The main path step by step, plus the key alternatives.
## States
Empty · loading · partial · error · no permission · offline · very large data
## Rules and logic
Validation, permissions, defaults, sorting, business rules.
## Data
Fields, formats, realistic anonymised examples, maximum lengths, languages.
## Design system
Components to use (names as in the library), patterns, tokens. New components needed?
## Accessibility
Keyboard flow, focus order, labels, contrast, motion (WCAG 2.2 AA).
## Acceptance criteria
Given / When / Then, testable.
## Open questions
…
The sections AI most often gets wrong when they're missing: states, rules and data. Write those first if you're short on time.
4. Worked example (fictional)
A booking app for community sports centres. Members keep missing that their booking was cancelled because of maintenance.
Problem: Members turn up to courts that were closed for maintenance. Support receives about 40 complaints a month mentioning "nobody told me". Users: Members on their phones, often on the way to the centre; staff who close courts from the admin tool. Job: When a court I booked is closed, I want to know straight away and get an alternative, so I don't waste the trip. States: No affected bookings · one affected booking · several affected bookings · closure announced less than one hour before (urgent) · member offline (notification queued). Rules: Offer the nearest free slot at the same centre first; never rebook automatically without the member's confirmation. Design system:
Banner(urgent variant),BookingCard,Button. No new components. Acceptance: Given a booking on a closed court, when the member opens the app, then a banner shows the closure and the alternative slot at the top, with "Accept" and "Choose another time".
A spec like this produces useful output from Figma Make, Claude or a coding agent. "Make cancellations clearer" doesn't.
5. Spec-driven development
Engineering is moving the same way. Spec-driven tools structure work as documents that agents follow:
- GitHub Spec Kit: constitution → specify → plan → tasks → implement, now followed by a "converge" step that brings code and spec back in line.
- Kiro:
requirements.md→design.md→ tasks (and abugfix.mdfor fixes).
- 1Design spec
Users, flows, states, rules, accessibility.
Owned by design - 2Engineering spec
Architecture, data, tasks.
Owned by engineering - 3Agent builds
Code that follows both documents.
Reviewed by people
The opportunity for design: when engineering works from specs, the design spec becomes an input to the engineering spec. Make sure design owns the experience sections (flows, states, rules, accessibility), instead of leaving an agent to invent them.
6. Common mistakes
| Mistake | Better |
|---|---|
| A spec that's only screenshots | Screens plus the rules and states behind them |
| "Handle errors gracefully" | List each error and what the user sees and can do |
| Fake data like "Lorem ipsum" or "User 1" | Realistic, anonymised examples, including long names and edge cases |
| Inventing components in the spec | Name the library's components; flag a missing one as an open question |
| Writing the spec after the design | Write the problem, users, states and rules first; they guide the design |
7. Try it (no code needed)
- Pick a feature you worked on recently.
- Fill in only four sections of the template: Users, States, Rules, Acceptance criteria.
- Give the spec to any approved AI tool and ask: "Design the main screen for this spec. Then list anything in the spec that's unclear or contradictory."
- Read the list of unclear points. Would an engineer have asked the same questions?
Reflection questions: Which section of your specs is usually missing? Who in your team would notice if an agent invented a business rule?
8. If you lead a team
- Agree on a team spec template and a short "ready for AI" checklist (users, states, rules, data, components).
- Create one design context file for your design system: principles, tokens, components, do and don't.
- Run spec critiques: review the spec, not only the screens. See Design critique.
- Pair each spec with a success measure, so AI-assisted work is judged by outcomes.
Checklist
Learn more
- NN/g: Prompt to Design Interfaces: Why Vague Prompts Fail and How to Fix Them · UX-Context Design · Context Libraries
- Formats: AGENTS.md · DESIGN.md · Design Tokens Format 2025.10
Books, courses and videos to go deeper
Related
Prompt patterns for designers · Prototyping with AI · Generating design with Claude Code · Figma AI · Context files · Spec-driven development · AI design review process