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 (tools/snap.ps1) 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.

| 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 Windows' words for system actions: Settings, Exit, Close, Undo, Delete (it goes to the Recycle Bin or can come back), Permanently 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.

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.

Ctrl+N, command bar New task, File > New task -> title field has focus -> Enter saves, row appears -> focus stays for the next task

• List every entry point: keyboard shortcut, command bar, menu, context menu, drag and drop, the tray icon.
• Cut steps: fill in good defaults, ask only for what you cannot guess.
• Every step has a way back: Esc cancels, Ctrl+Z undoes.
• The end is visible: the new row, a check mark, 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.

• Show one dialog at a time. Never open a flyout from a flyout (a submenu is fine), or a dialog from a dialog. WinUI allows only one open ContentDialog at a time; a second ShowAsync throws.
• A dialog's title names its task: "Rename project", not "Edit".
• Enter confirms, Esc cancels, and the primary button names the action.
• Ask before closing only when people would lose what they typed.
• Information that needs no action goes inline or in an InfoBar, never in a dialog.

Details and WinUI code for each surface: 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 ProgressBar when the length is known, with words for what is happening ("Importing 12 photos"), and Cancel when it is safe. A ProgressRing when it is not.
• Error: inline, next to the problem, with the fix.
• Too much: long names trim with TextTrimming="CharacterEllipsis" and show the full text in a tooltip; a thousand rows still scroll smoothly (ListView and ItemsView virtualize; a StackPanel in a ScrollViewer does not).
• Done: visible feedback in the same frame, and Undo where it applies.

Check: each state has a snapshot page or seed data (SeedData.cs) 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.
• Sentence case everywhere: buttons, menu items, window titles, labels, and messages ("New task", not "New Task").
• Errors say what happened and how to fix it, without blame. Write "Can't load tasks", never "Oops, something went wrong".
• Confirmations repeat the action: "Delete 3 tasks?" with buttons "Delete" and "Cancel", never "Yes" and "No".

Patterns and before and after examples: writing.md.

A feature that uses AI (a summary, generated text, a model's suggestion) also follows 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 tooltips

• Every icon-only button gets a tooltip: ToolTipService.ToolTip="Add a task to this list (Ctrl+N)". What it does, starting with a verb, then its shortcut. Not its name again. Rules: writing.md.
• A Button or AppBarButton with a KeyboardAccelerator and no tooltip of its own shows "Label (Ctrl+N)" by itself. Setting your own tooltip replaces that, so write the shortcut into it.
• 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 built app (./build.ps1 -Open). Each one shows a tooltip.

7. Check accessibility

• The whole flow works with the keyboard alone, in a logical focus order, with a visible focus rectangle.
• Narrator reads every control with the same words as the screen (AutomationProperties.Name where there is no visible text).
• Meaning never rests on color alone: add an icon or a word.
• Text is 12 epx or larger, uses the type ramp styles, and stays readable in a contrast theme and at 200% text size.
• With Animation effects off (UISettings.AnimationsEnabled is false), slides and bounces become fades or nothing.
• Every custom control has a name, a value, keyboard actions, and feedback.

The audit steps and WinUI properties: accessibility.md.

Check: you ran the flow keyboard-only and with Narrator, and Accessibility Insights for Windows (FastPass) shows no failures for the new views.

8. Write the UX block

Add the result under the story's acceptance lines:

UX:
- Flow: Ctrl+N, command bar New task, File > New task -> title field -> Enter 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 (Ctrl+N)", "Undo add task"
- Access: Enter saves, Esc cancels; Narrator "New task title, edit"

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.