ux-design · daveebbelaar — Claude Code skill: what it does, how to install
The ux-design skill for Claude Code runs a UX pass for a macOS app feature before coding, covering terminology, flows, surface selection, and accessibility. Runs before coding a story that adds a screen, an action, or text.
MIT 1,000 installs ★ 1,933 updated 2026-11-05
npx skills add daveebbelaar/bama --skill ux-design -a claude-codeWhat ux-design does
The skill structures the UX review process for macOS application features prior to writing implementation code. The agent establishes a glossary of terms, writes single-line user flows, and determines the appropriate presentation surface from inline controls to dedicated windows.
The workflow covers interface states for loading, empty data, errors, and completion, alongside copy guidelines and VoiceOver accessibility checks. The results are recorded directly into project documentation files as a structured verification block.
Project documentation and story files must exist in the workspace for the review process to execute properly. The tool ensures consistent interface naming and interaction patterns across the application.
What it helps with
- map out user interaction flows for a new feature
- build a strict terminology glossary for application terms
- select the proper UI presentation surface for a screen
- define interface states for loading, errors, and empty views
- audit accessibility and keyboard navigation support
Example prompts for the agent
- Run a UX pass for story [story ID]
- Review the flow and terminology for this screen
- Update the interface glossary with new terms
How to install ux-design
1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill ux-design -a claude-code2Manually: put the files in place
~/.claude/skills/ux-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ux-design/
1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill ux-design -a codex2Manually: put the files in place
.agents/skills/ux-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill ux-design -a cursor2Manually: put the files in place
.cursor/skills/ux-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install daveebbelaar/bama skills/design/ux-design2Manually: put the files in place
.github/skills/ux-design/SKILL.md1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill ux-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/daveebbelaar/bama --path skills/design/ux-designManually: put the files in place
.devin/skills/ux-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill ux-design -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ux-design
How to install ux-design in Claude Code?
Run npx skills add daveebbelaar/bama --skill ux-design -a claude-code and reference ~/.claude/skills/ux-design/SKILL.md.
What does ux-design do?
It performs a UX review for a macOS app feature before coding, defining names, interaction flows, presentation surfaces, UI states, and accessibility requirements.
Where are the review results stored?
The review output is saved as a UX: block in the story documentation file, and new terms are added to the project glossary.
Source text
SKILL.md · MIT
---
name: ux-design
description: UX pass for one feature of a macOS app, covering names, flow, where it opens (inline, popover, sheet, window, alert), states, words, hover help, accessibility, and AI features. Use before coding a story that adds a screen, an action, or text, when user-stories or improve-loop call it, or when the user asks for a UX review, clearer wording, better names, or whether something should be a modal.
argument-hint: "[story ID or screen]"
---
# UX design
A feature that works can still confuse people. This pass decides what
things are called, how a person moves through the feature, where it opens,
and what it says, before any code exists.
Run it once per story that adds a screen, an action, or words. The output
is a `UX:` block in the story in `docs/STORIES.md`, plus new terms in
`docs/GLOSSARY.md`. To review a built screen, run the same steps against
its snapshot and list what fails, most serious first.
## 0. Read
Read `docs/BRIEF.md`, `docs/GLOSSARY.md` (create it if missing), the story,
and its reference screenshots.
## 1. Name it
Every thing in the app has exactly one name, and every name lives in the
glossary.
```markdown
| Term | Means | Not |
| --- | --- | --- |
| Task | One thing to do, with an optional due date | to-do, item, entry |
| Complete | Mark a task done; it leaves the list | check, finish, close |
```
- Name the things first (the nouns in the brief), then the actions on them.
- Use the user's words, not the code's: "Task", not "TaskEntity" or "record".
- Use Apple's words for system actions: Settings, Quit, Close, Undo, Move
to Trash (when it can come back), Delete (when it cannot).
- One word per idea across buttons, menus, titles, tooltips, and errors.
- Name a feature for what it does for the person, not the technology. A
toggle gets a verb phrase that says what and for whom ("Enhance
Dialogue", not "Isolate Vocals"). Say the name in a sentence out loud.
Method: [writing.md](writing.md#names).
Check: every noun and verb the story puts on screen is in the glossary,
and no glossary term has a second name anywhere.
## 2. Map the flow
Write the flow as one line, from every way in to a clear end.
```text
Command-N, toolbar +, File > New Task -> title field has focus -> Return saves, row appears -> focus stays for the next task
```
- List every entry point: menu command, shortcut, toolbar, context menu,
drag and drop.
- Cut steps: fill in good defaults, ask only for what you cannot guess.
- Every step has a way back: Escape cancels, Command-Z undoes.
- The end is visible: the new row, a checkmark, the window closing.
Check: the flow fits on one line, and each step names its way back.
## 3. Pick the surface
Go down this list and use the first one that fits. Lighter is better.
| The feature | Use |
| --- | --- |
| Changes one value on something already on screen | Inline (field, toggle, menu in the row) |
| Shows details of the selection while people keep working | Inspector |
| A few related choices tied to one control | Popover |
| Input people repeat while they watch the result, or a tool kept open beside the work | Panel |
| One short task that must finish or cancel before going on | Sheet |
| A long or self-contained task, or one people keep open beside the main window | New window |
| A place people come back to, like a list or a collection | Sidebar page |
| A rare action that destroys data and cannot be undone | Confirmation dialog |
| A problem people must act on right now | Alert |
- Show one modal at a time. Never open a popover from a popover, or a
sheet from a sheet.
- A modal's title names its task: "Rename Project", not "Edit".
- Return confirms, Escape cancels, and the confirm button names the action.
- Ask before closing only when people would lose what they typed.
- Information that needs no action goes inline, never in an alert.
Details and SwiftUI code for each surface: [presentation.md](presentation.md).
Check: the `UX:` block names the surface and the table row that picked it.
## 4. Cover the states
Every view the story touches has words and a look for each state:
- **Empty**: what it is for, plus the first action as a button.
- **Loading**: only when it can take longer than half a second. Show
cached content first. A bar when the length is known, with words for
what is happening ("Importing 12 photos"), and Cancel when it is safe.
- **Error**: inline, next to the problem, with the fix.
- **Too much**: long names truncate with the full text in a tooltip; a
thousand rows still scroll smoothly.
- **Done**: visible feedback in the same frame, and Undo where it applies.
Check: each state has a snapshot page or seed data that shows it.
## 5. Write the words
- Buttons and menu items start with a verb: "Add Task", "Export…".
- Add an ellipsis when the command asks for more input before it acts.
- Title case for buttons, menu items, and window titles. Sentence case for
labels, descriptions, and messages.
- Errors say what happened and how to fix it, without blame. Write
"Unable to load tasks", never "We're having trouble".
- Confirmations repeat the action: "Delete 3 Tasks?" with buttons "Delete"
and "Cancel", never "Yes" and "No".
Patterns and before and after examples: [writing.md](writing.md).
A feature that uses AI (a summary, generated text, a model's suggestion)
also follows [ai-features.md](ai-features.md).
Check: read every string aloud. Each one is short, uses glossary terms
only, and a new user could say what each button does.
## 6. Add hover help
- Every icon-only button gets `.help("Add a task to this list (⌘N)")`:
what it does, starting with a verb, then its shortcut. Not its name
again. Rules: [writing.md](writing.md#tooltips).
- Hover can reveal secondary actions on a row. The same actions are also in
the context menu and on the keyboard.
- Hover feedback shows at once and never shifts the layout.
- Information people need is always visible. Hover only adds detail.
Check: hover every icon-only control on the snapshot build. Each one shows
a tooltip.
## 7. Check accessibility
- The whole flow works with the keyboard alone, in a logical focus order.
- VoiceOver reads every control with the same words as the screen.
- Meaning never rests on color alone: add an icon or a word.
- Text is 10 pt or larger and readable in Increase Contrast.
- Reduce Motion replaces slides and bounces with fades.
- Every custom control has a label, a value, actions, and feedback.
The audit steps and SwiftUI modifiers: [accessibility.md](accessibility.md).
Check: you ran the flow keyboard-only and with VoiceOver, and the
Accessibility Inspector audit shows no issues for the new views.
## 8. Write the UX block
Add the result under the story's acceptance lines:
```markdown
UX:
- Flow: Command-N, toolbar +, File > New Task -> title field -> Return saves -> focus stays
- Surface: inline row at the top of the list (changes one value on screen)
- States: empty "No Tasks" with "Add Task"; error "Give the task a title." under the field
- Words: "Add Task", tooltip "Add a task to this list (⌘N)", "Undo Add Task"
- Access: Return saves, Escape cancels; VoiceOver "New task title"
```
Done when the story has a `UX:` block, every term it uses is in
`docs/GLOSSARY.md`, and steps 1 to 7 pass on its snapshots.
© daveebbelaar · MIT · daveebbelaar/bama
Similar skills
All skills for Design →ux-design by other authors comes first.