MentalDesk.Tui
0.6.11
dotnet add package MentalDesk.Tui --version 0.6.11
NuGet\Install-Package MentalDesk.Tui -Version 0.6.11
<PackageReference Include="MentalDesk.Tui" Version="0.6.11" />
<PackageVersion Include="MentalDesk.Tui" Version="0.6.11" />
<PackageReference Include="MentalDesk.Tui" />
paket add MentalDesk.Tui --version 0.6.11
#r "nuget: MentalDesk.Tui, 0.6.11"
#:package MentalDesk.Tui@0.6.11
#addin nuget:?package=MentalDesk.Tui&version=0.6.11
#tool nuget:?package=MentalDesk.Tui&version=0.6.11
MentalDesk TUI style guide
How terminal UIs in this org should look and behave, so that requirements, implementations and reviews all start from the same assumptions.
Read this before writing a requirement that describes UI, and before building one. It is deliberately small: it covers the things that keep coming back in review, not everything a UI can do. It grows by pull request as new ones come back (see Extending this guide).
The framework is Terminal.Gui v2. Rules that are really framework mechanics say so; the rest are design rules that would hold in any TUI.
Using this guide. The rules are here. Each one is also built, once, in
MentalDesk.Tui, the shared library, and shown working in
Swatch, a theme editor that exists to exercise them
(dotnet run --project src/Swatch). To try a theme for real, select it and use Theme › Try it
(Ctrl+T T, or Enter on the preview): a small sample app opens in that theme, with live menus,
dialogs and buttons, and Esc brings you back. When you build something a rule covers, start from the
library type its section names, not from TuiCode's or a-team's own version: those are the older
copies the library was taken from. Where a section still names TuiCode or a-team code, the library
doesn't have that piece yet. Apps reference the library as the
MentalDesk.Tui package rather than copying from it.
Contents
- Build from the framework's widgets
- One affordance per action
- Errors and status
- Icons and glyphs
- Keys and focus
- Scrolling
- Writing requirements
1. Build from the framework's widgets
Reach for a built-in view before writing your own. A built-in already has the focus handling, mouse handling, theming and keyboard conventions that a bespoke control has to reinvent and usually gets half right.
Pick the control that matches the shape of the input, not the one that is easiest to draw:
| The input is | Use |
|---|---|
| On or off | CheckBox |
| One of a few choices, all worth showing | OptionSelector<T> |
| Several independent on/off flags | FlagSelector<T> |
| A number in a range | NumericUpDown<T>, with a minimum and maximum |
| One of many choices | DropDownList<T> or ListView |
| One of many, with hierarchy | TreeView |
| A short free-text value | TextField |
| Multi-line free text | The library's MultiLineField |
| Progress of a known-length job | ProgressBar |
MultiLineField is Terminal.Gui.Editor, which replaces the obsolete TextView, set to this guide's
rules: it wraps, shows a dimmed Placeholder while empty, wrapped as text is, undoes and selects like an editor, and
copies through the library's clipboard. Ctrl+K deletes to the end of the line, even when the clipboard
refuses the text. The terminal's own paste puts in what the terminal sent, as one undo step, which over
SSH is the laptop's clipboard rather than the remote one Ctrl+V reads. In Swatch, Help › Writing a
comment… has one.
It moves the caret with the keys a Mac user already knows:
| To move to | Keys | On a Mac laptop | With Mac keys on |
|---|---|---|---|
| Previous / next word | Option+←/→ or Ctrl+←/→ |
— | Option+←/→ |
| Start / end of the row you see | Home / End |
fn+←/→ |
Cmd+←/→ |
| Start / end of the text | Ctrl+Home / Ctrl+End |
fn+Ctrl+←/→ |
Cmd+↑/↓ |
Each selects as it moves with Shift held, and Ctrl+A selects all. Option+←/→ works whether the
terminal sends it as Alt+←/→ (iTerm2, Ghostty) or Esc b/Esc f (Terminal.app). With Mac keys on,
Cmd+⌫ and Option+⌫ delete to the start of the line and the previous word, and Cmd+A, Cmd+C,
Cmd+X and Cmd+Z select all, copy, cut and undo, in MultiLineField and TextField alike.
Home and End go by the row you see rather than the paragraph, as in TextEdit: in a box that wraps,
a comment is often one long paragraph, and End would otherwise jump to the end of all of it.
Style a built-in before you replace it. Most of what looks like "we need a custom control" is a
property: NoDecorations, NoPadding, ShadowStyle, SchemeName, Orientation, TabBehavior.
A custom view needs a reason, stated in the PR — name the built-in you rejected and what it
could not do. TuiCode's LogView is custom only because TextView cannot scroll without moving its
cursor; that sentence is the whole bar to clear.
An app's own colours
An app's own colours are worked out from the shared schemes, never copied from themes.json.
A diff line, a log level or a Markdown heading needs a colour the shared themes don't have. Register a
function with Themes.AddAppSchemes before Themes.Load: given a theme's name and its shared schemes,
it returns the app's own, and the library runs it every time a theme is applied, Try it included.
A theme the library adds or fixes later then reaches the app without a change to it.
Themes.AddAppSchemes((theme, shared) => new Dictionary<string, Scheme>
{
["Diff.Removed"] = shared[SchemeNames.Base] with { Normal = shared[SchemeNames.Error].Normal },
});
Themes.Load(settings.Theme);
- Key a colour on the theme's name only when no derivation gives a good one in every theme. A colour picked by hand for each theme is a copy again, and a new theme has none.
- The shared names are the library's. An app scheme named
WarningorBaseis refused at start-up, and an app can't change a shared scheme's colours: that's what a theme is for. - A colour a second app needs is a candidate for the shared set, through a pull request here.
Swatch's sample app
is the reference implementation: its editor marks a removed and an added line in two schemes of its
own, tinted from Error's background and kept readable against the editor's. Theme › Try it, then
switch themes from its Theme menu, and they change with it; Swatch's Themes pane lists them under
each theme, in Sample app's own.
Rows with columns
Pick the control by what the rows are for.
- Data you read or compare (spending, trends, decisions, language servers): a
TableView, made with the library'sColumnTable<T>. - A list you pick one row from (pickers, the palette, recent folders, keybindings): a
ListViewwhose rows are laid out byRowLayout<T>, so it keepsListFilterandPickerDialog(see Filtering a list).
Both take the same description of the columns: each is a Column<T> that names the row, holds a path,
text or a number. They look the same:
- A header row, dimmed, with no underline and no grid lines. It sits in the rows' own columns, so it can't drift from them. A list of one column has no header.
- Two spaces between columns. Content starts one column in from the border, as every dialog's does.
- Text aligns left, numbers right, header included, so the digits line up.
- The last column doesn't stretch to fill the width.
- A table you can't focus shows no selected row. It's there to read, and a highlighted row would look like one you could act on.
When the terminal is too narrow for them:
- Cut text says so with
…, never silently. Text is cut at its end; a path is cut at its start (…/code/TuiCode/side-pane-resize), so the last folder stays. - The column that names the row gives way first (Title, Command, Name). It shrinks to its minimum, then a path does, then the columns to its right drop, last first, then those to its left, furthest first. The column just left of the name never drops: the name is cut further instead, so a key stays beside what it does.
- A number, key or id is never cut. If it doesn't fit, its column drops instead: a cut number reads as a different number.
- Widening the terminal brings them back in the reverse order.
var columns = new RowLayout<Spend>(
Column<Spend>.Name("What", spend => spend.What, minWidth: 14),
Column<Spend>.Number("Runs", spend => spend.Runs.ToString()),
Column<Spend>.Number("Cost", spend => $"${spend.Cost:0.00}"));
var table = new ColumnTable<Spend>(columns, spending) { Width = Dim.Fill(), Height = Dim.Fill() };
ColumnTable needs no AppShell. A picker passes its RowLayout to PickerDialog, which fits the
rows and the header to its width as the terminal changes. In Swatch, Help › Rows with columns… has a
table of made-up figures beside a picker-style list: narrow the terminal and the name shrinks with …,
then the right-hand columns drop. The Keys page, the keys dialog, the command palette and Help ›
Picking an issue… are laid out the same way.
2. One affordance per action
Never give the same action two affordances in the same view. A dialog with a Submit button
and a hint reading Ctrl+Enter submit is telling the user the same thing twice and asking them to
work out whether it is one thing or two.
Each view shows its keys in one place: on its buttons. Never on a button and in a hint too, and
never a mix: if one action shows its key, every action does, Cancel included. Wherever the key is
shown, it comes first: ▓ Ctrl+Enter Delete ▓. The status bar's Press F1 for help is the one
exception (see Status bars and hints).
- A dialog shows every action as a button, keys on the labels, with no hint row:
▓ Ctrl+Enter Post ▓ ▓ Esc Cancel ▓. That holds when the dialog is mostly a field, when it's a picker (▓ Enter Run ▓ ▓ Esc Cancel ▓), and when it has many actions. Its other keys are found withF1(see Status bars and hints).
Buttons
A button is a filled block, not bracketed text. No
[ ], one space of padding either side.One Primary per view, at most.
Danger is for destructive actions only: delete, discard, overwrite. If the destructive action is the only one besides Cancel, it's still Danger, not Primary, and focus never starts on it.
Everything else is Secondary, including Cancel.
Focus is shown by colour and in bold, separately from emphasis, so a focused Secondary button is still obviously focused. Hover lightens the button without moving focus.
Framework mechanic: with
NoDecorationsthe stockButtondrops its padding too, and padding the view instead leaves the padding in the unfocused colour. Pad the text.
The library's AppButton
(AppButton.Primary("Save"), .Danger("Delete"), .Secondary("Cancel")) and the ButtonPrimary,
ButtonDanger and ButtonSecondary schemes in each of its
themes are the reference implementation.
Swatch's Theme › Delete…, Remove… and Close… are live dialogs to tab through and hover over.
Status bars and hints
The main screen's last row is the status bar, and it shows status, not keys: the focus word (section 5), errors outside a dialog (section 3), and whatever describes where the user is, such as the selected item or the caret's row and column.
Its one hint is Press F1 for help, always last at its right end (section 5). Without it, no
other key can be found. It's the one hint that doesn't put the key first: it's a sentence for someone
who hasn't learned the keys yet. Anything else the status bar shows on the right, such as the theme
name, sits just before it: Daylight • Press F1 for help. The unread-error count ⚠ n comes
before those, in the Error scheme: ⚠ 1 • Daylight • Press F1 for help (see
Status messages).
A dialog never has a hint row. Every action it has is a button at its foot, right-aligned, with its key on the label (section 2).
Every other key, in a dialog or on the main screen, is found with F1 (under the area's name) or the command
palette, never on screen: a picker's Up/Down/PgUp/PgDn, a control's editing keys such as undo,
select all and Home/End.
Write the status bar's hint and status text the same way:
- Key first, then a lower-case verb phrase:
Ctrl+E commands. The key is what the user is scanning for.Press F1 for helpis the one exception. - Separate items with
•(two spaces, U+2022, two spaces):Daylight • Press F1 for help.HintRowlays them out. - Name keys as the terminal reports them:
Ctrl+Enter,Esc,PgUp. - Make the hint clickable. A Terminal.Gui
Buttonwith its decorations turned off is a clickable hint:
private static Button Hint(string text, Pos x) => new()
{
Text = text,
X = x,
NoDecorations = true,
NoPadding = true,
ShadowStyle = ShadowStyles.None,
HotKeySpecifier = (Rune)0xffff, // the hint names its own key; don't also claim a hotkey
};
The status bar itself:
- It spans the full width of the screen's last row, never the window title or the foot of one pane.
- Give it its own colour, a
StatusBarscheme whose background differs from every region above it, in every theme. In the content's colours it reads as one more line of content. - Framework mechanic: TG's built-in
StatusBarpaints in theMenuscheme and draws a border between its items, so the status bar is a plain one-rowViewin theStatusBarscheme instead.
The library's AppStatusBar,
which AppShell gives Press F1 for help and nothing else, and the StatusBar scheme in each of its
themes are the reference implementation.
AppDialog
has no hint row, and lays out a dialog's buttons from its commands and keys. Every dialog in Swatch,
the command palette and Help › Loading states… included, has buttons and no hint row.
3. Errors and status
An error must never be interleaved with the controls. Growing a Label in place pushes it over
whatever sits below, and an error that lands between the buttons reads as part of them.
Give the dialog a dedicated message block at its foot, below its buttons, spanning the full width, occupying zero rows while there is nothing to say. When a message arrives, the dialog grows and the content above it shrinks — the message never steals the buttons' row.
The library's AlertView is the reference implementation: it
word-wraps to as many rows as the message needs, reports that count as Lines so the dialog can
re-lay itself out (AppDialog grows by it), and picks its colours from
the theme by severity rather than hard-coding them.
| Severity | Scheme | For |
|---|---|---|
Error |
Error |
The action was refused or failed |
Info |
Accent |
Progress, or a fact the user needs before acting |
Rules that matter more than the widget:
- Keep what the user typed. A refused action leaves the dialog open with its input intact. Never clear a form because the server said no.
- Say what happened, in the app's terms. One line. The first line of the tool's stderr beats an exception type; a stack trace belongs in the log, never on screen.
- Put focus where the fix is. A missing summary focuses the summary field.
- Show busy, and refuse a second go.
Submitting…in the message block, with the confirm disabled until it resolves. - Outside a dialog, errors go to the status bar — same wording rules, one line. Don't open a modal to report something the user did not just ask for. A pane that failed to load is the exception: see Loading and empty.
Checking what's typed
Check on confirm, not before. A field the user hasn't reached yet isn't wrong, so nothing is marked
until Ctrl+Enter. Not as you type, and not on leaving a field.
- The confirm stays enabled. Pressing it is how the user finds out what's missing. It's disabled only while busy, as above.
- A refused confirm marks every field that's wrong, at once. Its label turns to the
Errorscheme, and focus goes to the first. No error row under the field, no icon, no glyph. - The message block speaks for the focused field, and names it:
Title is needed • 1 more to fix.Tabto another marked field and the message follows. - Marks clear as the user fixes them. After a refusal, a marked field re-checks as it changes, or as a choice its check depends on changes, and its mark goes when it passes. The message clears with the last mark, and the dialog shrinks back.
- Empty never cancels. Confirming an empty field says what's needed. Only
Esccancels. - Mark the optional field, not the required one:
Folder (optional). No asterisks. - A refusal from disk or a server about one field works the same way.
There's already a theme named Midnightmarks that field, focuses it, and keeps what was typed.
┌─ Writing a comment ──────────────────────────────────────┐
│ Title │ Label, Error scheme
│ [▏ ] │ TextField, focused (first marked)
│ Comment │ Label, Error scheme
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Leave a comment… │ │ MultiLineField
│ └──────────────────────────────────────────────────────┘ │
│ ▓ Ctrl+Enter Post ▓ ▓ Esc Cancel ▓ │ Primary, Secondary
│ Title is needed • 1 more to fix │ AlertView (Error), for the focused field
└──────────────────────────────────────────────────────────┘
AppDialog
is the reference implementation. Check(field, label, refusal) registers a field with its label and a
function that returns why it's refused, or null. A dialog's confirm starts with Checked(), which marks,
focuses and says, and returns false on any refusal. Refuse(field, message) does the same for a no that
comes back later. ConfirmDialog takes a check for its field, run before its Ctrl+Enter action, and
marks its prompt line.
In Swatch, Help › Writing a comment… and Ctrl+Enter with both fields empty marks both; fix them one at
a time and watch the marks go. In the sample Try it opens, File › Save as… refuses an empty name and
Midnight.
Status messages
A message is either a reply or news. A reply answers what the user just did: Copied 3 lines,
Saved, Opened https://…. News happened by itself: Couldn't list files…, notes.md changed on disk.
A message stays for 5 seconds, except:
- A newer message replaces it. There's no ladder: the latest wins.
- A reply goes at your next key, if that comes first, since you've seen it.
- An
Errordoesn't time out. It stays until your next key; error news, until your next key after its 5 seconds, so typing through it doesn't lose it. - News that stops being true comes off. A load that works after a failed one takes the failure's message off the bar.
The keys of a chord don't count: Ctrl+G… shows over the message, which comes back after it.
With nothing to say, the bar can rest on something useful, like the active file's path, in its normal colours. A message or a chord shows over it.
No error is lost. Every Error news counts in ⚠ n, a button in the Error scheme just before
the theme name at the status bar's right end, until Messages is opened. A reply doesn't count,
because the user is looking at it. What the app logs rather than shows, like a folder it couldn't
watch, goes in Messages too, and counts in ⚠ n if it's an Error.
Messages lists this session's messages, newest first, each with its time, and focus starts on the
newest. It's in the Help menu and the command palette, and clicking ⚠ n opens it. Errors show in
the Error scheme, Ctrl+C copies the selected line, and Esc closes it. With nothing to show, it
says No messages yet, dimmed.
Editor • Couldn't list files, so these are the files from the last load ⚠ 1 • Daylight • Press F1 for help
The library's AppStatusBar
is the reference implementation. ShowMessage(…) puts up a reply and ShowNews(…) news; both return
the message, which Withdraw(…) takes off again if it's still showing. Record(…) adds a message to
Messages without showing it, and RestingText is what the bar shows between messages. AppShell has
those three methods too, counts each key that isn't part of a chord, and opens
MessagesDialog
from Messages. The copy and link outcomes it reports are replies. An app without AppShell calls
KeyPressed() on its AppStatusBar before handling each key, and opens MessagesDialog from the
bar's MessagesRequested.
In Swatch's sample, type in the Editor while View › Load files, failing runs: the failure stays, and
⚠ 1 appears. View › Log a warning adds to ⚠ n without a message, the selected file rests on the
bar, File › Save shows a reply, and Help › Messages… lists them all.
Times and durations
When something happened: relative while it's recent, then the date.
| Age | Shown | |
|---|---|---|
| Under a minute | now |
A time a little in the future is now too. |
| Under 90 minutes | 5m ago |
|
| Under 36 hours | 3h ago |
|
| Under 7 days | 2d ago |
|
| 7 days or more | 9 Nov |
9 Nov 2025 outside this year. |
Each rounds to the nearest unit, as git log --date=relative does, and the unit only changes at 90
minutes and 36 hours. In a column of ages, ago is dropped (5m, 3h, 2d): the column's header
(Waited, Last run) says what it measures. An age is right-aligned and never cut, as a number is
(see Rows with columns).
The exact time is always local, and always one look away. Wherever an exact time is shown, like a comment heading, a detail line or Messages, it's in the user's local time zone:
09:30for today14 Nov 09:30for this year14 Nov 2025 09:30for another year
The day has no leading zero, and month names are English, whatever the locale. A screen that shows
only a relative time, like a card, shows the exact time in its detail line or a dialog. A live log that
ticks every second keeps HH:mm:ss. Files and logs written for machines keep ISO 8601 in UTC: that
format isn't for the screen.
How long: the two largest units, or a clock while it's still going.
- A finished or waiting length is
45s,5m,4h 5mor2d 4h: the two largest units, with a space between. The second unit is always the next one down, and is left out when it's zero:2h, not2h 0m, and1d, not1d 30m. - A length still counting up or down, like a run in progress or the next pass, is a clock:
1:02, or1:02:03from an hour.
The library's Times
writes all of them: Ago(at), Age(at) for a column, At(at), and Took(span) and Running(span)
for lengths. It reads now from the TimeProvider it's given, so a test can fix it, needs no
AppShell, and only returns strings.
In Swatch, Help › Messages… gives each message's time with At, and Help › Rows with columns… has
a Last run column of ages, which drops before Cost as the terminal narrows. In the sample, move off a
file and the status bar rests on Synced now, counting up; View › When files last loaded… shows the
exact time.
Loading and empty
A region that waits for data says so in itself, where its content goes: not on the status bar, or in a header. A message away from the pane outlives the load.
It's always one of four states: loading, empty, failed, or its content. Never blank.
- Loading: a spinner and
Loading pull requests…, naming what. Shown only once the load has taken longer than a moment, so a fast load doesn't flicker. - Empty: say what isn't there, in the app's terms (
No open pull requests), dimmed. If there's an obvious next step, add it as a hint under it (N new branch). - Failed: one line in the
Errorscheme, same wording rules as above, withR retryunder it. A failed load is a state of the pane, so it stays in the pane rather than going to the status bar. - Reloading keeps what's there. The rows stay, and a spinner sits at the right of the region's top border until the new rows arrive. A reload that fails keeps the old rows and says so on the status bar.
- The content keeps focus in every state, so
Taborder doesn't change as a pane loads.
┌┤Pull requests├────────────────────────────┐ ┌┤Pull requests├─────────────────────────⠙──┐
│ │ │ #27 Typing to narrow the command palette │
│ ⠋ Loading pull requests… │ │ #26 Esc, Space and each action's own key │
│ │ └───────────────────────────────────────────┘
└───────────────────────────────────────────┘
The library's LoadStateView
is the reference implementation: it wraps any content view, and the app tells it ShowLoading(),
ShowEmpty(…), ShowFailed(…) or ShowContent(). It centres each state over the content with
SpinnerView and the theme's ReadOnly role and Error scheme, and switches the terminal's own
progress indicator on while loading. In Swatch, Try it opens a sample whose Files pane loads, and
its View menu reloads it, empty or failing; Help › Loading states… shows the same states in a dialog.
Copying
Anything the user reads can be copied. A view with a selection copies it with Ctrl+C. One
without offers a Copy command for what's under the cursor, on a key and in the menu.
Copy through the library, so it reaches the laptop over SSH. AppShell installs a clipboard that
sends every copy through the terminal (OSC 52) as well as to the machine's own clipboard, so built-in
controls like TextField take that path with no app code. An app's own copy command calls
shell.Copy(text).
An app without AppShell calls TerminalClipboard.Install(app) once after Init. Built-in controls then
copy through the terminal too, and its own copy command calls Copy(text) on the clipboard that returns.
It shows each Copied outcome on its status bar, with the message and severity the table below gives.
Say what was copied, on the status bar:
| Outcome | Says | Severity |
|---|---|---|
| The clipboard took it | Copied 3 lines • 142 characters |
Info |
| Only the terminal took it | Copied 3 lines • 142 characters through the terminal |
Info |
| Nothing took it | Copy failed: too large to send through the terminal (the limit is 750 KB) |
Error |
In a dialog, MultiLineField puts a failed copy in the dialog's message block instead (see
Errors and status), keeps the selection, and a failed cut leaves the text.
Deleting to the end or start of a line (Ctrl+K and friends) puts the text on the clipboard too,
but says what it did: 6 characters deleted.
Through the terminal is the normal outcome over SSH, not a warning. For it to land, tmux needs
set -g set-clipboard on, and iTerm2 needs Applications in terminal may access clipboard.
In Swatch, Ctrl+C in Roles, or Edit › Copy colours, copies the selected role's colours.
Opening a link
A link opens locally and is copied over SSH. Over SSH (SSH_CONNECTION, SSH_CLIENT or
SSH_TTY is set) there's no browser to open it in, so it's copied the same way as any other copy.
Only http, https and mailto links open; nothing the opener prints reaches the screen.
Say which, on the status bar:
| Outcome | Says | Severity |
|---|---|---|
| Opened | Opened https://github.com/mentaldesk/tui-style-guide |
Info |
| Copied over SSH | Copied https://github.com/mentaldesk/tui-style-guide (no browser over SSH) |
Info |
| The copy failed | Copy failed: …, as for any copy |
Error |
| No opener | Couldn't open the link: xdg-open not found |
Error |
| Not a web or mail link | Couldn't open the link: only web and mail links open |
Error |
Never call Link.OpenUrl directly. An app with AppShell calls shell.OpenLink(url), which puts the
outcome on the status bar. One without builds a LinkOpener with its clipboard, calls
opener.Open(url) and shows the LinkOutcome it returns. A Markdown view's LinkClicked is one of
the places to call it: open the link there and set e.Handled = true.
In Swatch, Help › Open the guide on GitHub opens this page.
4. Icons and glyphs
Use Nerd Font glyphs where an icon does real work. An icon earns its place when it classifies (this row is a folder, this one a C# file) or disambiguates at a glance. Decoration does not earn its place — a glyph on every label makes the ones that mean something invisible.
- One vocabulary per app. Reuse a glyph already in use before picking a new one, and pick from
one Nerd Font set (
nf-md-*, say) rather than mixing. - Always have a fallback: plain Unicode, not emoji. No terminal reports its font, so assume some
users have no Nerd Font. Give every icon a plain Unicode glyph too (
▸,✓,⚠). Emoji ignore the theme's colours, and their width depends on the terminal and the font. - One icon style for every MentalDesk app: Auto, Nerd Font or Plain. It's a shared
setting, never a per-app one, kept in
~/.config/mentaldesk/settings.json($XDG_CONFIG_HOMEif set;%APPDATA%\MentalDesk\settings.jsonon Windows). Change it in any app and the others use it the next time they start. - Auto says why it chose what it did, so a user who gets Plain can see why and fix it: "iTerm2 uses JetBrainsMono Nerd Font", "couldn't tell which font the terminal uses". Show it next to the setting and in Diagnostics.
- Draw the icon; don't put it in the text. Prepend the glyph's cells at draw time so the item's text stays the bare name, or filtering, sorting and type-to-jump all match against the glyph.
- Budget the cells. Every icon gets the same 2-cell field in either style, so the text beside it never moves when the style changes.
- Colour comes from the theme, and the icon keeps its row's background so selection still reads.
The library's IconSettings
is the shared style, read once at start (AppShell.Icons), with
TerminalFontDetection
behind Auto. Each app keeps its own icons, each an Icon with a Nerd Font and a Plain glyph.
IconField
draws one in its 2-cell field, in the row's hot colour over the row's background, in front of a tree
row or anywhere else. In Swatch, File › Settings… picks the style on its Appearance page, with
Auto's reason beside it, and F12 shows what Auto chose.
5. Keys and focus
Esccancels. Always. It never does anything else.Ctrl+Enterconfirms. Always. In every dialog, whether it has a field, a multi-line one or none, so a user never has to stop and check which key this one takes.Enternever confirms a dialog: in a multi-line field it starts a new line, and anywhere else it does nothing, so a strayEntercan't delete or save anything. A picker is a list, not a dialog:Enterpicks (see Filtering a list).- Framework mechanic: the Windows console reports
Ctrl+EnterasCtrl+LineFeed;AppShellturns it back. Terminal.app and other terminals without the kitty keyboard protocol send it as plainEnter, so there the userTabs to the button and pressesSpace.F12says which this terminal does. - Every action is reachable from the keyboard. The mouse is a convenience, never the only way.
- Tab moves focus, everywhere. Terminal.Gui.Editor binds Tab to indent, so a multi-line field in
a dialog is the library's
MultiLineField, which leaves Tab, Esc andCtrl+Enterto the dialog.Tabgoes on from a pane's last control to the next pane. Where an app has a stated reason forTabto do something else, such as an editor that indents,F6is still the way out (see Panes and screens). - Tabs and pages switch with
Ctrl+PgUp/Ctrl+PgDn. Wherever a view has tabs or pages, these go to the previous and next one, wrapping at either end, andTabstays inside the current one. - Focus lands where work starts when a view opens — the filter field, the summary, the first row.
- In a set of options, the arrows choose.
Left/Right(orUp/Down) pick the next option, not just focus it, and focus enters on the chosen option.Tableaves the set in one press and never changes the choice.Spacehas nothing left to do. Terminal.Gui'sOptionSelectoronly moves focus, andTabsteps through its options, so call the library'sSelectOnArrows()on every one. Swatch's Settings uses it for the icon style. - A container
Viewthat hosts focusable children needsCanFocus = true;SetFocus()silently returns false when any ancestor has it off.
Panes and screens
A pane is a part of the current screen that takes its own keys: a sidebar view, an editor group, a list beside a detail. Moving to one only moves focus. A screen replaces everything below the menu bar, so moving to one redraws the window.
F6/Shift+F6move to the next / previous pane, in reading order, wrapping. Focus lands where work starts in it. Every pane is reachable this way, whatever else the app binds.- The arrows never leave a pane. At the top of a list or the end of a file,
UporDowndoes nothing. Terminal.Gui would move focus on an arrow the view doesn't use;AppShellstops it. - A pane the user moves to many times an hour may also have a chord of its own, as TuiCode's
Explorer has
Ctrl+Shift+E. It's a second way in, never the only one. NotCtrl+Esc, which Windows takes, and remember some terminals foldCtrl+Shift+letterintoCtrl+letter. Ctrl+Gthen a letter switches screen. Every screen has one, listed in the Go menu, with the current screen checked, and inF1. Going back to a screen puts focus where you left it there (see Coming back); only the first visit lands where work starts.Ctrl+Gis Go: to a screen, or to a place (a line, a definition, a scheme). It never just moves focus to a pane.
Go
┌────────────────────────────────┐
│ Next pane F6 │
│ Previous pane Shift+F6 │ Menu with MenuItems
│ ────────────────────────────── │
│ ● Files Ctrl+G F │
│ Log Ctrl+G L │
└────────────────────────────────┘
AppShell is the reference implementation. The regions an app registers with FocusTracker are its
panes, in the order it registers them; F6 and Shift+F6 follow the framework's next- and
previous-pane keys if the user rebinds them. AddScreen gives a screen its Ctrl+G letter and a
Go to command, and throws if the letter clashes with a key already bound. GoMenu and GoTo build
the Go menu above, and F1 lists it under Moving around. In Swatch, F6 cycles Themes, Roles and
Preview, and Go › Scheme… is a place. In the sample app Try this theme opens, Ctrl+G L shows the
Log screen and Ctrl+G F goes back to Files.
Coming back
Leaving part of an app and coming back, or quitting and reopening it, puts you where you were.
- Going back to a screen puts you where you left it: the same pane, the same control, the same selected row, scrolled the same way. Focus lands where work starts only the first time you visit a screen in a session.
- Reopening the app opens the screen you left, on the pane you were in. If that pane opens only on request, like an assistant pane, it starts closed and focus lands where work starts.
- Whatever an app brings back inside a pane, it finds again by what it is, not where it was: a card's issue number, a file's path, a row's key. If it's gone, select the item that's now in its place, or the last one, and never the first by default.
- Never bring back a dialog, a filter you typed, or a half-finished edit. Coming back gives you your place, not your last action.
AppShell does the screen and pane part. ShowScreen, and so each screen's Ctrl+G key and its Go
menu entry, goes back to the control that last had focus on that screen, or to the screen's start if
it hasn't had focus yet or that control is gone. Reopen opens on the screen and pane saved in the
app's section of the settings file, and saves them there again when the app quits; a screen or pane
that no longer exists opens the app as if nothing was saved. What an app brings back inside a pane is
its own. In the sample app, select todo.md in Files, then Ctrl+G L and Ctrl+G F: focus is back
on todo.md. In Swatch, quit with focus in Roles and reopen: focus is in Roles.
Resizing panes
A side pane can be resized; the main pane can't. A side pane sits beside what the user reads or edits: a tree, a list, a history, the Assistant. The main pane takes what's left. The app says which panes are side panes; no other pane is resizable.
- Drag its inner border, the one facing the main pane, with the mouse. Focus stays where it was, and nothing else appears: a drag only changes the width.
- Widen pane and Narrow pane resize the focused side pane by 5 columns. They're in the command
palette, and only while focus is in a side pane (see Only what works here). They have no keys:
anyone who wants one gives it one on Settings › Keys (see Changing keys), and
F1lists it. - A side pane is never narrower than 15 columns, and never leaves the main pane fewer than 40. A drag stops at the limit, and Widen pane or Narrow pane there says so in the status bar.
- In a terminal too narrow for both, the side panes give way first, the widest a column at a time, so the main pane keeps 40 columns where it can.
- The width is remembered per pane as the width the user chose. A narrow terminal shrinks what's drawn, not what's remembered, so widening the terminal brings it back, and so does the next start.
- Reset pane width puts the focused pane back to the app's default. The default can follow the window, like two fifths of it, until the user chooses a width.
The library's SidePanes
is the reference implementation. An app adds its panes in reading order, each side pane with its
region and default width, or a function of the row's width for one that follows the window, and the main pane; it registers the three commands, makes each side pane's
inner border LeftResizable or RightResizable for Terminal.Gui's own drag, and keeps the widths in
the app's MentalDeskSettings section. An app without AppShell hands it the focused region, a way to
show a message and a place to keep the widths, and registers Widen, Narrow and Reset itself, offered
while CanResize. In Swatch, Themes, Roles and the Assistant are side panes and
Preview is the main pane; while the Assistant is open in Preview's place, Roles takes what's left.
An assistant pane
An app that lets the user ask an AI agent about it does so in one pane, Assistant. One command of that name, in the menu and the command palette, opens it down the right of the screen with focus in its question box, and closes it again. It stays open while the user moves between screens.
- A question carries what it's about, so the user never has to name it. The line above the box says
what the next question is about, the selection, and the question's heading repeats it:
You · Midnight › Base. - Answers stream in, with one
▸row for each run of things the agent looks at or does, so a long answer shows its progress and still starts near the top. The row is the newest call, clipped with…to fit, then(+N)for the earlier ones, and it updates in place as calls arrive. Text between calls starts a new run, so the answer reads in order. A failed call keeps its own▸ … (failed)row and isn't counted. Entersends,Escstops the answer and keeps what arrived,Ctrl+Lstarts a new conversation,Ctrl+T T(Show tool calls in full) gives every call its own row and folds them again, keeping what you were reading in view. They're the pane's keys, listed under Assistant byF1. An app with a setting for this says where a conversation starts; the key doesn't change it.- In an app where
Esctakes you back to the main work from anywhere, it does that from the pane too, andCtrl+H(halt) stops the answer. The answer keeps arriving while you're away, and the status bar says so. While no answer is coming,Ctrl+Hin the pane does nothing, whatever it means elsewhere. The pane's hint names the stop key:Ctrl+H stop · Ctrl+L clear. - The agent asks before it acts. It reads without asking. A command, an edit or any other tool opens
a dialog, Claude Code wants to run a command, showing the command, with
Ctrl+Enter Allow onceandEsc Deny. Deny has focus, andEnterdoes nothing there (see Dialog buttons). There's no Always allow. - When the agent can't answer, the pane says why in a line: it isn't installed, it isn't signed in (with the command that signs in), or it exited.
- The last conversation is there after a restart, where the agent can reopen one.
The library's AssistantPane
is the reference implementation, for an app where Esc doesn't mean "back to the work": there Esc
stops the answer. It talks to the agent, Claude Code by default, over the
Agent Client Protocol, takes its own keys so it works in an app
without AppShell, and asks with
AssistantPermission.
In Swatch, Help › Assistant opens it beside the Roles pane, with a demo agent that makes a few tool
calls, one of which fails, streams a canned answer about the selected scheme and asks to run a command.
Finding keys
F1 always opens Help, and never means anything else. Everywhere is on the left: the
global keys, grouped under the menu's headings. The focused area's keys are on the right, headed with
the area's name alone (Themes). When the two columns don't fit side by side, the area's keys go on
top and Everywhere below. Both are read from the keymap when it opens, so they can't drift from the
real bindings.
F1 works in dialogs too, with one column. It's headed with the dialog's title (Commands) and
lists every key the dialog binds, its buttons' keys included. There's no Everywhere: the app's keys
don't work behind a dialog (see Only what works here). Closing it puts you back in the dialog, with
focus where it was.
- The main screen's status bar always ends with
Press F1 for help, and shows no other hint (see Status bars and hints), so it's in the same place in every app. A dialog shows noF1hint: it works the same everywhere. - A command that only works in one region belongs to that region, and so do its keys, so they show under its name (see Only what works here).
- It's a reference, not a runner: nothing in it takes focus, its one button is
▓ Esc Close ▓,F1in it does nothing, and it leaves out commands that can't run here and commands with no key. The command palette has the second kind.
The library's KeysDialog,
which AppShell binds to F1 and AppDialog binds in every dialog, is the reference implementation. Swatch's Ctrl+T theme commands,
all but Try it, belong to the Themes pane.
Filtering a list
Every list that narrows as you type matches the same way, so a user learns it once.
- CamelHumps, then contains. Case never matters. Each letter continues the last match or starts
a new word or hump, as in JetBrains:
gtd,GTDandgotodefall findGoToDefinition. A space makes the next letter start a hump. A row the letters don't match that way still matches if it contains them as one run:iewfindsGrammarPickerView.cs. A query with/matches path segments in order, by CamelHumps only. - Best match first: a prefix, then fewest jumps between humps, then rows that only contain the letters. Ties, and an empty filter, keep the list's own order.
- Match only what's on screen. A hidden id never matches, so every row shows why it's there.
- Say when nothing matches, in the list: a dimmed
(no matches).Enterthen does nothing, and its button is dimmed. - An empty filter says
Type to filter, dimmed, in the field. It goes as soon as you type. - Typing never leaves the filter.
Up/Down/PgUp/PgDnmove the selection while the cursor stays in the field, and the first row is selected after every keystroke, soEntertakes the best match. - A picker whose rows are fetched opens at once and loads in its list, as any region does (see
Loading and empty):
Loading pull requests…, then the rows, or the failure withR retryunder it. Until the rows are in, the pick button is dimmed andEnterdoes nothing. - Rows with columns get a dimmed header above the list, in the rows' columns: see Rows with columns.
- A pick that can't be done says why and stays open, in the dialog's message block, so another row can be picked. Typing clears it.
The library's PickerDialog,
matching with ListFilter
and TuiCode's CamelHumps,
is the reference implementation. The command palette is built on it, and so are Swatch's
Go › Scheme… and Help › Picking an issue…, whose first load fails on purpose, and where a closed
issue can't be opened.
Filter a list to pick one thing by a name you half-remember; find in what you read (below) to look for words you've seen in text that stays as it is.
Filtering a board in place
A board of cards narrows where it stands, under a filter bar, rather than in a picker over it, since you go on working with the cards you find. It matches as a list does, with these differences:
Ctrl+Fopens the bar docked above the board, laid out as the find bar is: aFilterlabel, then the field with focus, sayingType to filterwhile it's empty. Empty, the whole board shows.- Every lane and column keeps its place and its own order; only the cards that don't match go.
A lane with none left stays, as one dimmed
(no matches)row, so the board's shape doesn't move. - Nothing that matches is hidden: while the bar has text, no lane folds its cards behind a
+N. - A card matches on its number and its whole title, with a leading
#ignored, even where the card cuts its title short: the title is the card's own, shown in full when it's selected. - The bar's right end counts the matches across the board, dimmed:
7 cards, orNo results. ↓orTabgoes from the bar to the first match, where the board's own keys work on what's left.Ctrl+Fgoes back to the bar with its text selected.Esccloses the bar and brings the whole board back, on the card picked from the narrowed one, or else the one selected before, scrolled into view.- A board read again keeps the filter on, and narrows the new cards.
a-team's Overseer is the reference implementation; Swatch has no board of cards to filter.
Picking a path
A file, a folder or a new file's name is picked in one browser, which works as a picker does (see Filtering a list) and stays open as you move between folders.
- One folder at a time, until you type. The line above the filter says where you are, dimmed, with
~for home (~/code). With the filter empty, the list is../(except at the root), then folders ending in/, then files, each sorted by name. Hidden files and folders are left out. - Typing searches this folder and everything below it. Matches show their path from here
(
tui-style-guide/src/Swatch/) and rank as any filter does, the shallower first on a tie. A/in the filter matches folder by folder (src/sw). - The search runs in the background, breadth first, skips
.git,.hg,.svn,node_modules,binandobj, and stops at 10,000 entries. The line under the filter saysSearching…until it's done, andFirst 10,000 entriesif it stopped. - A filter starting with
.shows hidden files and folders, so.github/is a.giaway. Enteracts on the selected row: a folder, wherever it is, goes in, and../goes up.Backspacein an empty filter goes up too. Going in or up empties the filter. Going in selects the first row; going up selects the folder you came from.- Typing a path that starts with
~or/and pressingEntergoes there: into it if it's a folder, picking it if it's a file. - Picking a file:
Enteron a file picks it, wherever it is in the list. - Picking a folder:
▓ Ctrl+Enter Use this folder ▓uses the one you're in, andEnterstill only goes in. Only folders are listed. - Picking a file or the folder you're in, where either will do (an editor's Open):
Enteron a file picks it, and aCtrl+Enterbutton named for what happens (▓ Ctrl+Enter Open this folder ▓) uses the folder.▓ Enter Open ▓stays the primary button. - Naming a new file: the filter is the name. While no file of that name is in this folder, the
first row is a dimmed
New file: notes.md, above any matches below, and▓ Ctrl+Enter Save here ▓uses it. Picking a file that's already there asks, withConfirmDialog, whether to replace it. - A folder that can't be read says why in the list, in place of
(no matches), and../still works. - Where the app marks files and folders with icons elsewhere, the rows do too, in the same 2-cell field (see Icons and glyphs), and none at all when the app shows none.
- The path comes back as it was shown, with
~for home, so a setting reads the way the user saw it.
┌─ Open folder ────────────────────────────────────────────────┐
│ ~/code │ Label, dim
│ sw▏ │ PlaceholderField (focused)
│ Searching… │ Label, dim
│▓swatch/ ▓│ ListView, first row selected
│ sentry-swift/ │
│ tui-style-guide/src/Swatch/ │
│ │
│ ▓ Enter Open ▓ ▓ Ctrl+Enter Use this folder ▓ ▓ Esc Cancel ▓ │ Button (Secondary), Button (Primary), Button (Secondary)
└──────────────────────────────────────────────────────────────┘
┌─ Save copy as ───────────────────────────────────────────────┐
│ ~/code/swatch/themes │ Label, dim
│ solar.json▏ │ PlaceholderField (focused)
│ │
│▓New file: solar.json ▓│ ListView, first row, dim
│ old/solar.json │ a match below
│ │
│ ▓ Ctrl+Enter Save here ▓ ▓ Esc Cancel ▓ │ Button (Primary), Button (Secondary)
└──────────────────────────────────────────────────────────────┘
The library's PathPicker
is the reference implementation, for a file, a folder or a new file; its useFolder names the folder
button, and a file picker has one only when given it. It's a PickerDialog, which can replace its rows
while it's open and draws each row's Icon with IconField. The sample app's File › Open… (which
also opens the folder you're in), Open folder… and Save copy as… try all three.
Finding in what you read
Ctrl+F opens a find bar on what you're reading, docked at the top of that pane, never a dialog,
so the text stays where it was. A single-line selection starts the query.
- Matching is plain text, and case never matters. Not CamelHumps: you're looking for words you've seen, not a name you half-remember (Filtering a list is for that).
- Every match is highlighted, and the current one is selected.
Entergoes to the next andShift+Enterto the previous, wrapping at either end. The bar's right edge says3 of 12, orNo results. Terminals without the kitty keyboard protocol sendShift+EnterasEnter, so there you step forward only. - A growing log keeps its place. New lines are searched as they arrive and the count updates, but the view stops following the tail while the bar has a current match, so the line you found doesn't scroll away.
Esccloses the bar, from the bar or the text, and leaves the view scrolled to the current match, with focus back in it.F1in the bar lists its keys in Help, in the area column, headed Find bar.- Find sits in the Edit menu with
Ctrl+F, and is dimmed wherever there's nothing to search (see Only what works here).
┌─Reading a log────────────────────────────────────────────────────┐
│ Find retry▏ 2 of 5 │ Label, TextField, Label
│──────────────────────────────────────────────────────────────────│
│ 11:02:31 restore failed: 503, ░retry░ in 5s │ every match highlighted
│ 11:02:36 ▓retry▓ 1 of 3 │ the current one selected
│ 11:02:37 restore ok │
└──────────────────────────────────────────────────────────────────┘
The library's FindBar
is the reference implementation, moved from TuiCode with its replace row, which readers never show. It
searches an IFindTarget:
EditorFindTarget covers a Terminal.Gui.Editor, read-only or not, and an app writes a small one for a
view of its own. AppShell.FindIn gives a region its target, and AppShell binds Ctrl+F to Find
there. An app without AppShell binds Ctrl+F itself, pushes ScopeOver its own keys when it opens the
bar, pops it on Closed, and shows the KeysRequested column on F1. Swatch's Help › Reading a log…
is a log that gains a line a second, to try it on.
Menu letters
Every item in an open menu has its own underlined letter, and pressing it runs the item, without
Alt, as the menu bar's titles do with it.
- No two items in a menu share a letter. Each takes its first letter if that's free, else the first
letter of a later word (Save [a]s…), else any letter in its label (Se[t]tings…, with Export holding
E). First letters are handed out before later words, so Open recent doesn't take Run'sR. An item that marks its own letter keeps it. - A dimmed item keeps its letter, underlined in the dim colour, so the menu doesn't change shape. Pressing it does nothing, and the menu stays open.
AppMenu picks the letters, keeping any a MenuEntry title marks with _. An app with menus of its own
picks them with MenuLetters.Pick, passing every title the menu can show, dimmed and swapped-out ones too. The sample app's File
menu has Save, Save as… and Settings…; Swatch's Theme › Use for Swatch dims with its U.
Dialog buttons
A dialog of buttons, such as an "are you sure?", works the same way in every app:
Esccancels.Left/Right(andTab) move between the buttons, andSpacepresses the focused one.- The main action's key is
Ctrl+Enter, Danger or not (▓ Ctrl+Enter Delete ▓). - Every action has one key, shown on its button, Cancel's
Esctoo: the key written before the label (▓ Ctrl+Enter Save ▓), or for any other action the underlined letter (Ddiscard). The letter works withoutAlt, as in a menu. The dialog has no hint row (see Status bars and hints). Enterdoes nothing, whichever button has focus.
┌─ Delete theme ───────────────────────────────────┐
│ Delete "Solar"? │
│ This can't be undone. │
│ │
│ ▓ Ctrl+Enter Delete ▓ ▓ Esc Cancel ▓ │ Button (Danger, key Ctrl+Enter), Button (Secondary, key Esc)
└──────────────────────────────────────────────────┘
Which button starts focused, as long as it isn't a Danger one, the wording and the layout are up to
the app. Two pieces of advice:
name the action on the button (Delete, not OK), and say in the text whether it can be
undone.
- Framework mechanic: a focused
Buttonpresses onEnter. The dialog takesEnterbefore the button sees it, soEntercan't press Delete just because Delete has focus.
The library's ConfirmDialog
is the reference implementation: give it the message and the actions with their keys. It refuses
an action on Enter, a dialog without exactly one action on Ctrl+Enter, and focus starting on a
Danger button. Swatch's Theme › Delete… (can't be undone), Remove… and Close… (Save, Discard,
Cancel) try every key. An app without AppShell uses it too: add it, push its Scope (keys fed
through CtrlEnter.FromWindows), and on Closed pop it, remove it, then run the chosen action.
Leaving unsaved work
Leaving something the user wrote or asked for asks first, and only then.
- Ask before throwing away anything the user wrote or asked for: closing a tab, a dialog or a screen, switching folder, quitting. If nothing would be lost, don't ask.
- Name what would be lost: the file, your comment, 2 writes still queued. Up to four names, then and n more.
- Offer to keep it when you can. If it can be saved or sent from here, the main action does that
(
Ctrl+Enter Save,Ctrl+Enter Post) and throwing it away isD Discard(Danger). If it can't,Ctrl+Enter Discard(Danger) is the only action.Escalways goes back to the work. - Quit asks once, listing everything the app would lose, never one prompt per item, and never quits silently over unsaved work.
┌─ Unsaved changes ──────────────────────────────────────────┐
│ 2 files have unsaved changes: │
│ notes.md, plan.md │
│ Save them before quitting? │
│ │
│ ▓ Ctrl+Enter Save all ▓ ▓ Discard ▓ ▓ Esc Cancel ▓ │ Button (Primary), Button (Danger, key D), Button (Secondary)
└────────────────────────────────────────────────────────────┘
Save all is offered only when every item can be saved; with any that can't, the prompt says which
and offers Discard alone. Which label Esc gets (Cancel, Keep writing, Stay) is up to the app.
The app, and each of its screens, tells AppShell what it would lose with ReportUnsaved, as
UnsavedItems
with a way to save each where there is one. AppShell asks before its window stops, however it
stops, Ctrl+Q and Terminal.Gui's own Quit binding included, and quits at once when nothing's
reported. A save that throws keeps the app open and says which item failed and why. UnsavedPrompt
builds the same prompt for closing one thing. In the sample app, View › Leave two files unsaved
then Ctrl+Q; Leave a file that won't save and Leave an untitled file try a failed save and the
Discard-only prompt. In Swatch, type in Help › Writing a comment… and press Esc.
Settings screens
Nothing in Settings is kept until Ctrl+Enter, and Esc undoes all of it. A user never has to ask
which changes Esc will undo, because the answer is always "every one".
- Settings holds only what the app owns. Anything that acts on something else (GitHub, another app's config, another file) is a screen or a command of its own, reached from the menu and the palette, with its own Cancel. That's the test for whether something belongs in Settings.
- Changes preview while Settings is open. Pick a theme and the screen is in it. Leaving any way
but
Ctrl+Enter(Esc, Cancel, the close box) puts back every setting as it was saved, with no "are you sure?". - A dialog opened from a page stages its result. Confirming it (
Ctrl+Enter) changes the page; itsEsccloses only that dialog. Nothing it did is kept untilCtrl+Enteron Settings, andEscthere undoes it with everything else. - Pages on the left, the page on the right. The page list never takes focus:
Ctrl+PgUp/Ctrl+PgDnchange page, or click one, andTab,Shift+Taband the arrows move only among the page's controls. Focus starts on the page's first control. ▓ Ctrl+Enter Keep ▓and▓ Esc Cancel ▓, at the foot, and no hint row.Keep, notSave: the change is already on screen, and you're keeping it. A page's own action is a button on that page, its key on the label, andF1lists every key under Settings.- A page with changes not yet kept shows
•after its name in the list, and loses it when they're put back. - A setting that differs from its default says so on its row:
[ ] Show hex values (default: on),Daylight (default: Midnight). - Keys are a page in Settings, called Keys, and follow these rules too (see Changing keys).
┌─ Settings ──────────────────────────────────────────────────────────────────┐
│ Appearance • │ Theme │ ListView (pages, no focus) │ Line
│ Swatches │ Midnight │
│ │ Daylight (default: Midnight) │ ListView, focused, previews live
│ │ Turbo Pascal │
│ │ Modern Borland │
│ │ │
│ │ Icons (•) Auto ( ) Nerd Font ( ) Plain │ OptionSelector, previews live
│ │ Auto chose Nerd Font: kitty bundles the Nerd Font symbols │ Label, dim
│ │ │
│ │ ▓ Ctrl+Enter Keep ▓ ▓ Esc Cancel ▓ │ Button (Primary), Button (Secondary)
└─────────────────────────────────────────────────────────────────────────────┘
The library's SettingsDialog
is the reference implementation. An app adds its own pages, each a
SettingsPage
that says whether it has changes and how to keep or put them back. Swatch's File › Settings… has
an Appearance page (theme and icon style), a Swatches page, whose Reset to defaults… asks
through ConfirmDialog and stages the reset, a Keys page, and a Mac keys page.
Changing keys
Every app's keys are changed on a Keys page in its Settings, and saved the same way, so a user
who has rebound a key in one app already knows how in the next. Nothing on it is kept until
Ctrl+Enter, and Esc undoes all of it, a reset included (see Settings screens).
- One row per key, and one for a command with none. Columns Command, Keys and Where: Everywhere,
or the region's name as
F1heads it. The filter above matches all three, as Filtering a list does. Enterrecords keys for the selected row. The row readsPress keys…, each key joins the chord as you press it (Ctrl+T X),Entertakes it andEscstops recording without changing anything. It adds a key, in the row's place; the command's other keys stay. A dim line under the list says which keys do what.Delremoves the selected key.- Keys the guide fixes can't be taken:
Esc,Enter,Ctrl+Enter,Tab,Shift+Tab,F1, andF6/Shift+F6for panes. The row says why, and recording carries on. A command's fixed key can't be removed either. - A clash says what it clashes with. The same chord in the same place asks through
ConfirmDialog(Ctrl+T Dalready runs Delete this theme in Themes. Give it to Close this theme instead?), and Replace moves it. A chord that starts or goes on from another one there is refused on the row, naming it; recording carries on. A region's key that hides one that works everywhere asks first, saying which wins where. - A changed command says its defaults at the end of each key the user added, or of its first row
when it only lost keys, where a narrow screen cuts it rather than the columns:
Ctrl+T X Everywhere (default: none). A key it has by default says nothing. Reset to defaults… (Ctrl+R) asks throughConfirmDialogand stages the reset.
│ Appearance │ comment▏ │ TextField (filter)
│ Swatches │ Command Keys Where │ Label, dim
│ Keys • │▓Write a comment Press keys… Ctrl+T Everywhere ▓│ ListView, recording
│ Mac keys │ │
│ │ Enter takes the keys · Esc stops recording │ Label, dim
│ │ ▓ Ctrl+R Reset to defaults… ▓ │ Button (Secondary), page action
│ │ ▓ Ctrl+Enter Keep ▓ ▓ Esc Cancel ▓ │ Button (Primary), Button (Secondary)
Only what differs from the defaults is saved, by command, as key names a person can read and edit.
A command with one key in its usual place is a string, "" is no key, and anything more is a list,
where a key in another place says where:
"keys": {
"swatch.writeComment": "Ctrl+T x",
"app.quit": "",
"swatch.tryTheme": ["F5", { "key": "Enter", "where": "Preview" }]
}
An entry that doesn't parse is skipped and that command keeps its defaults; the rest still load. A key
whose name doesn't read back as itself is written as # and its keycode. Terminal.Gui's own key-binding
config only holds its built-in commands, one key each, so the app's commands, chords and regions live here.
The library's KeysPage
and KeyOverrides
are the reference implementation. Once every default key is bound, an app creates KeyOverrides, keeping
it in its MentalDeskSettings section with KeyOverrides.InSection or handing it a section of its own
file, and calls Load(); then it adds new KeysPage(shell, overrides) to its Settings. A kept key works at
once and shows in the menu, the palette and F1. Swatch's File › Settings… › Keys is it.
Mac keys
Cmd and Option keys are each app's own, turned on from a Mac keys page in its Settings. A Mac
terminal never passes Cmd to the app. So the library installs a small file in iTerm2, kitty or WezTerm,
under the app's name, that turns them into keys every TextField and MultiLineField already
handles, only while that app runs. The shell and every other app keep the terminal's own keys, and
installing or removing one app's file never touches another's.
| Keys | Does |
|---|---|
Cmd+← / Cmd+→ |
Start / end of the line |
Cmd+↑ / Cmd+↓ |
Start / end of the text |
Option+← / Option+→ |
Previous / next word |
any of those with Shift |
Select as it moves |
Cmd+⌫ / Option+⌫ |
Delete to the start of the line / the previous word |
Cmd+A Cmd+C Cmd+X Cmd+Z |
Select all, copy, cut, undo |
Cmd+V stays the terminal's paste, which already works.
The page follows the Settings rules: ticking the box changes nothing until Ctrl+Enter, which installs
(or updates an out-of-date copy), and clearing it then removes it. Esc leaves the terminal as it was.
│ Appearance │ Terminal kitty │ Label
│ Swatches │ State Installed │ Label
│ Mac keys │ │
│ │ [x] Cmd and Option keys in Swatch │ CheckBox
│ │ │
│ │ Add this line to ~/.config/kitty/kitty.conf, then reopen │ kitty and WezTerm only,
│ │ Swatch: │ once installed
│ │ include swatch.conf ▓ C Copy ▓ │ Button (Secondary)
│ │ │
│ │ Cmd+← / Cmd+→ Start / end of the line │ the table above
- State reads Not installed, Installed, Out of date · saving updates it, or, anywhere but iTerm2, kitty and WezTerm on a Mac, Can't be installed here. There the box is disabled and the page says which keys work without it.
- Until it's installed, the page says Only Swatch is affected; your shell and other apps are unchanged.
- kitty and WezTerm need one line in the user's own config, which the library never edits, so the page shows it with a Copy button.
The library's MacKeys
has everything the page shows: Here (this terminal's integration, or null), Terminal, the
integration's State, ConfigLine and ConfigFile, Install() and Remove(), and MacKeys.Rows.
An app with AppShell calls shell.UseMacKeys(new MacKeys("Swatch")) before it creates any view, and
the shell marks it running while Run runs. One without calls keys.Activate() and disposes what it
returns on exit, and suspends inside keys.WhileSuspended(...). Copy Swatch's
MacKeysPage for
your own Settings: File › Settings… › Mac keys.
Showing focus
Focus has one owner, and that owner is not the framework's HasFocus. Keep the focused
region in one place and re-read it from the view the framework reports as focused, on every
iteration and before every key — a mouse click moves focus between iterations. TG leaves HasFocus
set on a view that focus has moved on from, so reading it view by view gives you two views that
both claim the keyboard. Navigation.GetFocused() can also return an ancestor of the view
actually holding keys, so walk down to the innermost with View.MostFocused.
Put it on screen twice: in colour and in a word. The focused pane draws its border in the theme's focus colour, and a word naming the region sits at the far left of the status bar, always present. The colour is what you notice; the word is what still works when the theme is pale, the terminal profile overrides, or the user can't tell the two colours apart. Without either, a focus move that went somewhere unintended is invisible until the user types.
- Framework mechanic: TG draws border lines in
VisualRole.Normalwhatever has focus. Swap the role as the attribute is resolved — aGettingAttributeForRolehook mappingNormal→FocusandHotNormal→HotFocus— rather than overriding the pane's scheme, which has to be reapplied on every theme change. - Don't read the framework's button painting as the answer either: TG draws the first
Buttonin theFocusattribute whether or not it has focus, so the thing that looks focused is often the wrong one.
The library's FocusTracker and
FocusBorder, wired up in AppShell, are the
reference implementation. FocusTracker is framework-free and unit-tested directly: the host
registers each region with a move and an ownership test and supplies the focused view.
What a command acts on
A command acts on the selection, and the selection stays put while the menu or the palette has focus. Opening either one takes focus from the content. A command that finds its target by asking what has focus finds nothing there, so its menu item dims a moment after the menu opens, just as the user reaches for it.
- Read the target, and
isEnabled, from state the content keeps: the list's selected row, the pane last selected. Never fromHasFocusorNavigation.GetFocused(). - Where selecting a thing is focusing it, as in a grid of panes, remember the last one focus was in, and keep answering with it while focus is outside them.
- Test it with the menu open. Select something, open the menu, refresh it, and check the item isn't dimmed. Refreshing matters: an app that refreshes its menu on a timer dims the item on the first tick, not when the menu opens.
FocusTracker already does this for regions: while focus is in a view no region owns, such as the
open menu, it keeps the region it had. Swatch's Theme › Use for Swatch is the reference for a
selection. It acts on the theme selected in the tree, and is enabled only while that isn't the theme
already in use.
Only what works here
A command that can't run where you are seems not to exist. Where you are is the region that had
focus when the menu or the palette opened. A command can run there if it's global or that region's,
and enabled. Its key, its menu item, the palette and F1 all go by that one test, so they never
disagree, and none of them says why a command didn't run.
- The palette and
F1leave it out. - The menu dims it in place, so a menu reads the same wherever it opens. The arrows still stop on
a dimmed item;
Enteror a click on it does nothing. - A menu with nothing that can run leaves the bar, and the titles close up behind it. Its
Alt+letterdoes nothing until it's back. - Of two actions that undo each other, the menu offers only the one you can take, in a place
they share: Collapse folders while the folders are open, Expand folders while they're shut. No
•beside the current state: the screen already shows it. A choice among more than two, like the sample's theme list, keeps its●. - A command that only works in one region belongs to that region, and so do its keys, so a menu
item can always show its key: the key works wherever the item does. A global command can have an
extra key in one region, as Swatch's preview has
Enter. - Framework mechanic: Terminal.Gui's arrows skip a disabled
MenuItem, and itsMenuBarkeeps a hidden title's place. So dim an item by drawing it in theDisabledcolour and ignoring its activation, and take an empty menu off the bar.
The library's AppMenu
and CommandPalette
share the test, CommandRegistry.IsAvailable, and Keymap.Bind won't give a region's command a key
anywhere else. A MenuEntry's Opposite shares its place in the menu. In Swatch, open Theme from
the Roles pane: Delete…, Remove… and Close… are dimmed, with their Ctrl+T keys. In the sample
app that Try it opens, Edit leaves the bar while the Files pane has focus, and View offers
Collapse folders or Expand folders.
The caret
Every text box paints its own caret. A terminal can lose the cursor colour the app asks for
(iTerm2 puts a profile's colours back over OSC 12 whenever it switches the session to that profile)
or ignore it, and then the caret can vanish against the theme's background. A painted caret can't.
- A caret is a solid block over the character at the insertion point, in the theme's
Cursorscheme: the block in itsNormalforeground, the character under it in itsNormalbackground, so it stays readable. At the end of a line it covers the empty cell after the last character, which at the end of a full row is the first cell of the row below, where the next character will go. A bar can't share a cell with the character it's before, so a painted bar would hide it. - It doesn't read as a selection. A selection is a run of cells in the selection colour; the caret is one cell in its own.
- Only the focused box has a caret, and the terminal cursor is hidden while it does. One painted caret beside one real one is two different-looking things on screen claiming to be the same thing.
- It doesn't blink. A blink is a redraw on a timer for every box, and more bytes over SSH.
- Redraw whenever the caret moves. A painted caret only moves when the view redraws. A caret that
snaps into place only once the user types is a missing
SetNeedsDraw(), not a drawing bug — the terminal cursor hid this, because the framework moves that one without a repaint.
PlaceholderField and MultiLineField do all of this, so use them for every text box rather than a
plain TextField or TextView. Keep colouring the terminal cursor with OSC 12 when the theme is
applied, and restoring it with OSC 112 on exit, for anything still on the terminal's cursor; the
library's TerminalCursor
does it, and the Diagnostics dialog shows what was asked for beside what the terminal reports.
6. Scrolling
Anything that scrolls shows a scroll bar while its content doesn't fit. It is the one cue that
says, at a glance, where you are and how much is left. Without it, a pane that scrolls on
PgUp/PgDn looks like it ends at its last visible row.
- Auto: never always, never off. The bar appears when the content outgrows the view and goes when it fits again, so content that fits keeps every column. No setting to hide it.
- Horizontal too, where lines don't wrap. A line running past the right edge gets a bar along the bottom on the same terms. A view that wraps never needs one.
- Focus doesn't matter. A pane that never takes focus, scrolled by its parent's keys, still shows its bar.
- One bar for panes that scroll together, such as the two sides of a diff.
Framework mechanics:
- Every
Viewhas aVerticalScrollBarand aHorizontalScrollBar, hidden until you setViewportSettingsFlags.HasVerticalScrollBar/HasHorizontalScrollBar(orVisibilityMode = ScrollBarVisibilityMode.Auto).TreeView<T>,Markdownand the library'sMultiLineFieldturn theirs on. - These bars track the view's content size and
Viewport, and the mouse can drag them. A custom view that keeps its own scroll offset gets a bar that never moves: scroll it withSetContentSizeandViewportinstead.
a-team's WorkView is the
reference implementation of a custom view scrolled that way.
7. Writing requirements
A requirement that describes UI is not done until a reader can build it without guessing.
Name the control for every element, using the names in section 1, and sketch it. The sketch carries the layout; the control names carry the behaviour.
┌─ Submit review on #187 ────────────────────────────────┐
│ (•) Comment ( ) Approve ( ) Request changes │ OptionSelector<T>, horizontal
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Summary… │ │ MultiLineField; focus starts here
│ └────────────────────────────────────────────────────┘ │
│ ▓ Ctrl+Enter Submit ▓ ▓ Esc Cancel ▓ │ Primary, Secondary
└────────────────────────────────────────────────────────┘
Sketch conventions: [x] / [ ] checkbox, (•) / ( ) option, [ 2 ▲▼] numeric up/down,
▓ Button ▓ button (say which: Primary, Danger or Secondary), [text▏ ] text field with its caret, ▸ collapsed tree node, … placeholder text, ▲ █ ▼ down the right edge
a vertical scroll bar.
Then say, in prose:
- Every key the view shows, verbatim, on its buttons or in the status bar — it is part of the design, not a detail for the implementer.
- Where focus starts, and what
EnterandEscdo. - What happens when it fails. Which message, shown where, and what survives. A requirement that only describes the happy path gets an error path invented in review.
- What each field refuses, and the words that say so, naming the field:
Title is needed. See Checking what's typed. - Anything it brings back beyond what Coming back covers.
Extending this guide
Add a rule when a review comment has had to make the same point twice. A rule here should be short, imperative, and about a decision someone will actually face — if it cannot be violated, it does not need writing down.
Open a pull request. Include the review comment that prompted it in the PR description, not in the guide: the guide says what to do, the PR says why. Change the library and Swatch in the same pull request, so a rule and its reference implementation never disagree.
Repos that follow this guide link to it from their AGENTS.md:
mentaldesk/TuiCode,
mentaldesk/a-team.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Terminal.Gui (>= 2.5.0)
- Terminal.Gui.Editor (>= 2.5.7)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.6.11 | 0 | 11/19/2026 |
| 0.6.10 | 331 | 11/17/2026 |
| 0.6.9 | 288 | 11/16/2026 |
| 0.6.8 | 72 | 11/15/2026 |
| 0.6.7 | 73 | 11/14/2026 |
| 0.6.6 | 318 | 11/13/2026 |
| 0.6.5 | 422 | 11/9/2026 |
| 0.6.4 | 271 | 11/7/2026 |
| 0.6.3 | 139 | 11/7/2026 |
| 0.6.2 | 163 | 11/7/2026 |
| 0.6.1 | 568 | 11/5/2026 |
| 0.6.0 | 348 | 11/3/2026 |
| 0.5.2 | 244 | 11/1/2026 |
| 0.5.1 | 138 | 11/1/2026 |
| 0.5.0 | 327 | 11/1/2026 |
| 0.4.5 | 128 | 10/31/2026 |
| 0.4.4 | 243 | 10/30/2026 |
| 0.4.3 | 203 | 10/29/2026 |
| 0.4.2 | 221 | 10/28/2026 |
| 0.4.1 | 448 | 10/26/2026 |