ux-documentation-and-handoff
Skill0 starsChanged 22 days agoMITView on GitHub
Use when writing UX documentation for an app: personas, user flows, site maps, wireframe and prototype notes, a style guide, component state specs, design principles, or a developer hand-off pack. Do not use for choosing the design itself (the design skills), for running usability tests (ux-review-and-testing) or for software documentation such as a README.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- accessible-designSkill
- adaptive-layout-and-spacingSkill
- ai-interface-designSkill
- interaction-feedback-and-formsSkill
- mobile-ux-foundationsSkill
- navigation-and-flowsSkill
- ui-ux-designerSkill
- ux-review-and-testingSkill
- visual-design-systemSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Use real copy, not placeholders, with notes on when each message appears.
- Distinctive: line 19
Keep one living set of documents with version history.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
UX Documentation and Hand-off
Stance: frozen are a single source of truth, versioned records, and specs that describe behaviour, not just looks. Flexible are the format and tool, and how many of the document types a project needs.
Hard rules
- Describe behaviour and states, not only pictures. Mechanism: a static mockup hides what happens on error, loading, empty, long text and large text; developers then guess.
- Use real copy, not placeholders, with notes on when each message appears. Mechanism: lorem ipsum hides length and tone problems, and developers end up writing copy.
- Keep one living set of documents with version history. Mechanism: stale copies in chat and email lead to building the wrong version.
- Record the reason for each decision. Mechanism: later changes can be checked against the original intent.
- Label an AI-drafted persona, insight or research summary as a hypothesis to validate, not a finding, until a real user has confirmed it. Mechanism: a generative tool can draft a plausible-sounding persona or synthesise a convincing theme from notes, but it has not observed anyone; documenting it as settled fact lets an unvalidated guess quietly become the brief everyone designs against.
- Specify behaviour for each size class and for large text. Mechanism: a phone-only spec leaves tablet and desktop to improvisation.
- Include accessibility annotations: names, reading order, target sizes, contrast pairs. Mechanism: added late they are rarely added at all.
- Mark timing advice as guidance, not rule. Mechanism: projects vary; the sources give typical order only.
- Act only on what the user asked. Before answering or changing anything, open the relevant files and check what is already done; report only what you checked, never guess, and do not redo finished work. Reason: guesses and repeated work waste the user's credit.
Gate
| Situation | Action |
| Small change to one screen | Update the affected spec and changelog only |
| New product or major flow | Produce the full set in the order below |
| No time for everything | Keep flows, states, style guide and hand-off notes; drop the rest |
| Developers already have a spec tool | Use it; do not create a second source |
Steps
- Research documents. Methods used, personas (goals, pain points, behaviour, scenarios), user flows with entry points, decisions, success and error paths.
- Information architecture. Site map of screens and sections, content groups, navigation paths.
- Design deliverables. Wireframes for structure, mockups for visuals, prototypes for interaction; annotate each.
- Principles and style guide. Shared priorities; colour, type, icons, components with states, layout and responsive rules, motion, accessibility.
- Interaction patterns. Navigation, input, feedback, microinteractions, transitions, in the project's own words.
- Prototype notes. Purpose, audience, scope, navigation, behaviour, feedback received and changes made.
- Hand-off pack. Final named screens, functional spec, copy, state matrix, specs tool link, open questions, a call with developers. A validated, user-tested prototype can stand in for part of the written spec if developers can open and interact with it directly; say so and still document the states and copy it does not show (error text, edge cases, accessibility names). Templates: document-templates.md.
- Version. Date, author and change summary on every release of the documents.
Checklist (copy into the reply and tick as you go)
- [ ] Personas and flows reflect research, not guesses; any AI-drafted ones marked as unvalidated
- [ ] Site map matches the built navigation
- [ ] Every component has all states specified
- [ ] Behaviour given per size class and at large text
- [ ] Real copy included with display conditions
- [ ] Accessibility annotations added
- [ ] Version history and open questions recordedExamples
Example 1: hand-off pack User says: "Write the hand-off notes for the new transfer screen." Actions: list screens and flows; state matrix for amount field, buttons and result; copy with conditions; size class behaviour; accessibility names; call out open questions. Result: a pack that lets developers build without asking about every case.
Example 2: placeholder copy User says: "Just leave lorem ipsum in the error messages, we will fill them later." Actions: explain the cost; draft real messages from the error cases and ask the owner to approve. Result: copy that fits the layout and is ready to build.
Common issues
- Developers ask the same questions repeatedly. Cause: missing states and edge cases. Fix: add the state matrix and error paths.
- Docs and product drift apart. Cause: no owner or version. Fix: name an owner and update with each release.
- The site map and real navigation differ. Cause: changes made in the app only. Fix: update the map in the same change.
References
- document-templates.md: outlines for each document type.
Next
ux-review-and-testing to test the documented design.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

