Activation Contract
Use for designing, reviewing or refining a terminal interface (panels, rails, status bars, cards, prompts), especially Gentle Shell. The target feel is an IDE inside a terminal: dense, calm, developer-first, never a costume of retro TUI chrome. Not for web pages (use gentle-design).
Hard Rules
- Never judge a terminal UI from code or memory: capture it (
references/visual-loop.md) and look at the PNG before and after every change.
- Read
references/terminal-craft.md before any UI edit; it is the floor, not a suggestion.
- Operate mode: familiarity beats expression. Use IDE vocabulary (panes, tree, tabs, status bar, command palette); the brand lives in palette, density and one signature move.
- Every row costs. Hierarchy comes from color role, weight and alignment, never from blank rows or nested boxes.
- Say each fact once per screen. Data shown in the header never repeats in a panel.
- One command, one target. Refinement preserves the system; redesign replaces it. Never polish a look being thrown away.
- Rendering stays cheap: no I/O or recomputation in render paths, cache keyed on everything that changes output (style, width, theme).
- Mockups (via
gentle-design) must be terminal-expressible: monospace cell grid in ch units, only fg/bg colors, bold/dim/italic/underline/strikethrough, box-drawing and glyphs.
Decision Gates
| Ask |
Command |
Load |
| No product/design context yet |
document |
references/design-doc.md |
| New surface or redesign |
shape, then mockups, then implement |
references/commands.md |
| "How does it look / what is wrong" |
critique |
references/critique.md |
| Too busy, wasted space, redundant |
distill / layout / quieter |
references/commands.md |
| Flat, no hierarchy, unreadable |
typeset / colorize / bolder |
references/commands.md |
| Edge cases, narrow terminals, long text |
harden / adapt |
references/commands.md |
| Final pass before commit |
polish |
references/commands.md |
Execution Steps
- Load
DESIGN.md context if the project has one; otherwise propose document first.
- Capture the current state with the visual loop at the shipped sizes (wide 180x50, breakpoint 140, narrow 80x24).
- Run the chosen command against one named target; write findings before changing code.
- Change, re-capture, compare against the previous PNG and the brief; iterate at most 3 rounds, then report.
- End every refine command with
polish checks and the repository's focused tests (render counts, overflow).
Output Contract
Return: target, command run, before/after PNG paths, findings fixed with P0-P3 tags, findings left open, and checks run.
References
references/terminal-craft.md: floor rules and terminal anti-patterns.
references/commands.md: command playbooks adapted to terminals.
references/critique.md: scored critique and severity rubric.
references/design-doc.md: DESIGN.md shape for a terminal product.
references/visual-loop.md: screenshot harness and comparison loop.
NOTICE.md: attribution.
1---2name: gentle-ai-tui-design3description: "Trigger: terminal UI design, TUI redesign, Gentle Shell look, IDE in a terminal, sidebar/status bar polish, critique TUI. Refine terminal UIs with visual proof."4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/gentleman-programming/gentle-ai-tui-design7 author: gentleman-programming8 version: "1.0"9---1011## Activation Contract1213Use for designing, reviewing or refining a terminal interface (panels, rails, status bars, cards, prompts), especially Gentle Shell. The target feel is an IDE inside a terminal: dense, calm, developer-first, never a costume of retro TUI chrome. Not for web pages (use `gentle-design`).1415## Hard Rules1617- Never judge a terminal UI from code or memory: capture it (`references/visual-loop.md`) and look at the PNG before and after every change.18- Read `references/terminal-craft.md` before any UI edit; it is the floor, not a suggestion.19- Operate mode: familiarity beats expression. Use IDE vocabulary (panes, tree, tabs, status bar, command palette); the brand lives in palette, density and one signature move.20- Every row costs. Hierarchy comes from color role, weight and alignment, never from blank rows or nested boxes.21- Say each fact once per screen. Data shown in the header never repeats in a panel.22- One command, one target. Refinement preserves the system; redesign replaces it. Never polish a look being thrown away.23- Rendering stays cheap: no I/O or recomputation in render paths, cache keyed on everything that changes output (style, width, theme).24- Mockups (via `gentle-design`) must be terminal-expressible: monospace cell grid in `ch` units, only fg/bg colors, bold/dim/italic/underline/strikethrough, box-drawing and glyphs.2526## Decision Gates2728| Ask | Command | Load |29|-----|---------|------|30| No product/design context yet | `document` | `references/design-doc.md` |31| New surface or redesign | `shape`, then mockups, then implement | `references/commands.md` |32| "How does it look / what is wrong" | `critique` | `references/critique.md` |33| Too busy, wasted space, redundant | `distill` / `layout` / `quieter` | `references/commands.md` |34| Flat, no hierarchy, unreadable | `typeset` / `colorize` / `bolder` | `references/commands.md` |35| Edge cases, narrow terminals, long text | `harden` / `adapt` | `references/commands.md` |36| Final pass before commit | `polish` | `references/commands.md` |3738## Execution Steps39401. Load `DESIGN.md` context if the project has one; otherwise propose `document` first.412. Capture the current state with the visual loop at the shipped sizes (wide 180x50, breakpoint 140, narrow 80x24).423. Run the chosen command against one named target; write findings before changing code.434. Change, re-capture, compare against the previous PNG and the brief; iterate at most 3 rounds, then report.445. End every refine command with `polish` checks and the repository's focused tests (render counts, overflow).4546## Output Contract4748Return: target, command run, before/after PNG paths, findings fixed with P0-P3 tags, findings left open, and checks run.4950## References5152- `references/terminal-craft.md`: floor rules and terminal anti-patterns.53- `references/commands.md`: command playbooks adapted to terminals.54- `references/critique.md`: scored critique and severity rubric.55- `references/design-doc.md`: DESIGN.md shape for a terminal product.56- `references/visual-loop.md`: screenshot harness and comparison loop.57- `NOTICE.md`: attribution.