Desktop UI conventions

Apply these to every screen in every desktop app, not just one project. Sections 7, 8, 9 and 12 (input controls, explanatory text, captions, required marks) apply to web forms too; the others are desktop only. They come from concrete requests made across a real project (CodeGenNew) after the first pass shipped without them.

1. Keyboard access keys (hotkeys) on buttons

• Give every dialog's footer buttons a mnemonic letter: C for Cancel or Copy, O for OK/Open/Done, S for Save. Pick a different, non-conflicting letter for anything else on the same screen (e.g. a "Test" button can take T).
• Always check for conflicts within the same screen/scope before assigning a letter. Two controls that are both visible and focusable at the same time must never share a mnemonic. A modal dialog is its own scope — its access keys don't need to avoid the letters used by the window underneath it, since the OS/framework's access-key manager scopes to whatever's currently active (the dialog shadows the parent window's own access keys while it's open).
• The convention is a leading & (or the framework's equivalent, e.g. WinUI3's AccessKey property) on the mnemonic letter in the caption, e.g. &Cancel, &OK, &Save.
• The platform's own default is to underline the mnemonic only while Alt is held down (true of Win32, WPF, and WinUI3 alike) — that's expected, not a bug, and matches how every native Windows app already behaves. If a permanently-visible bold/underlined letter (not just on Alt-hold) is specifically wanted, that requires replacing the framework's built-in string-based button captions with custom button content built from separate text runs (one bold, one normal) — a bigger, separate change from just wiring up the access key itself. Don't conflate the two asks; implement the access key first, then ask before doing the heavier custom-content rework.

2. Escape = Cancel, Enter = Save/OK

Most native dialog frameworks (WPF Window/WinUI3 ContentDialog) already give you this for free:

• Escape always triggers the Cancel/Close action.
• Enter triggers whichever button is marked as the dialog's default button — including when focus is inside a TextBox, which is exactly the scenario a form-style dialog needs (type values, press Enter to submit).

Check whether the framework already does this before writing custom KeyDown handling. Reimplementing it by hand risks subtly diverging from the platform convention users already expect (e.g. handling Enter only when a Button has focus, missing the TextBox case).

3. Default-button focus

When a dialog opens, keyboard focus should already be on whichever button is marked as the default one (the one Enter would trigger) — not on the first input field, and not nothing. For a dialog with only one button (a plain info/confirmation dialog), that single button gets the initial focus.

This has to be done explicitly in most frameworks — a dialog's default-button styling (bold border, etc.) does not automatically mean it holds keyboard focus. Set focus programmatically when the dialog opens/loads.

4. First-control focus on a toolbar/menu bar

The top-level command bar/toolbar/menu bar of the main window should give keyboard focus to its first button as soon as it's shown, so a keyboard-only user can immediately Tab or Enter without first having to click into the toolbar. Do this once, when the toolbar first loads.

5. Tooltips on every toolbar button

Every button on a top-level toolbar/command bar should have a tooltip explaining what it does — standard practice, not optional polish. Include the access key in the tooltip text (e.g. "Connect to a SQL Server database (Alt+C)") so the keyboard shortcut is discoverable without needing to hold Alt first.

6. Status icons: shape-coded, not just color-coded

Any success/warning/error message — a result popup, an inline validation message, a status bar entry — gets an icon whose shape carries the meaning, not just its color. Color alone (a green dot vs. an amber dot vs. a red dot) is unreliable for colorblind users (protanopia/deuteranopia make red/green/amber hard to tell apart at a glance) and is the reason this convention exists at all — it's the same fix microsoft/skills#398 made to a review-output legend, applied here to actual app UI instead of markdown text.

These three SVGs are simple, flat, single-color icons deliberately kept easy to re-theme (swap the fill/ stroke colors) or redraw at a different size — they're a starting point, not a locked design. See the winui3 skill for how to wire this into an actual WinUI3 dialog (prefer the built-in InfoBar control's Severity property over loading these as custom images when the framework already gives you this for free).

7. Pick the input control that cannot take a bad value

Apply to every screen, dialog and settings page in every project. A free-text box is the last choice, for values that are free text. If the valid values are known, the control offers them, so the user cannot mistype one.

• A value already stored that is not on the list (a hand-edited file) must survive: show no selection and keep the stored text until the user picks something else.
• Keep the list of valid values in one place in the non-UI layer (a table of key, kind, choices) so tests can check it against the code that parses the value, and so every screen offers the same list.
• Match case when loading a stored value ("sqlserver" selects "SQL Server"); write the canonical spelling.

8. Explanatory text is a label, never a text box

A text box looks like something to type in and takes a tab stop. Read-only explanatory text (what a tab holds, what a field means, a hint under a field) is a label / text block (in WinUI3 a TextBlock, inside a Border panel when it needs a background), which is not focusable and cannot be edited. Do not use a read-only, disabled or placeholder-filled text box for it. Do not put the explanation inside the value: a placeholder like "true: the plan also writes ..." makes the user wonder what to type. Caption, then the explanation as its own small line, then the control.

• A tab description starts "This tab has ..." and is plain weight, not bold.
• Black text needs a light panel behind it; the screen's theme may be dark, so check contrast.

9. Captions have spaces between the words

A caption made from an identifier ("DashboardStrip", "NoApiTables") is shown with the words apart ("Dashboard Strip", "No Api Tables"), the way generated screens already caption column names. Use the same word-splitting function for every screen so they agree.

10. At most 20 fields on a tab; group by what the user is deciding

A settings screen with one long tab is hard to scan. Split by topic (General, Namespaces, Tables, Database, API, Output, Build ...), at most 20 fields per tab, each tab opening with its "This tab has ..." description. A field no tab lists falls into the first tab so a new setting is never hidden, and a test asserts that every setting is on exactly one tab and no tab is over the limit.

11. A setting the user turns on must say what else they have to do

A feature switch that only takes effect on the next generate, restart or rebuild says so in its own explanation line. Saving a setting does nothing by itself, and a user who ticks a box and sees no change assumes the feature is broken. Where a control depends on another (a "Stacks" list that decides what is generated), say so beside it, and state what a blank value does.

12. Required fields get a red asterisk, and Save stays enabled

• Put a literal * after the caption of every field the person must fill in: shown on the form, editable, NOT NULL, and not a yes/no box (it always holds a value) or a value the system writes. Colour it red (about #b00020 on white, 7:1; the asterisk shape means colour is not the only cue).
• Mark it twice: the visible * is hidden from assistive technology (aria-hidden="true"; WinUI3 skips it because the header is not the control), and the control itself says it is required (the native required attribute, aria-required only as a fallback; WinUI3 AutomationProperties.IsRequiredForForm="True"). Do not also print the word "required" beside each field: it is announced twice.
• A legend line ("* required") is optional; the project owner chose none for the generated screens.
• Do not disable Save until the required fields are filled. A disabled button leaves the tab order, gives no reason, and a screen-reader user cannot find the button they are told to use. Keep Save enabled and refuse on press, with a message, and move focus to the first missing field. If a disabled Save is ever wanted: aria-disabled="true" so it stays focusable, plus a visible hint naming the empty fields.
• One rule decides which fields are required, for every screen and every technology, and the mark and the check read it, so the star never disagrees with the check. A setting can switch the marks off; the fields stay required.
• Check it on the screen where the mark lives: the detail form reached with Edit (or Add New), not the list page. Compare the marked captions with the NOT NULL columns of the table.