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.mdbefore 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 inchunits, 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.mdcontext if the project has one; otherwise proposedocumentfirst. - 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
polishchecks 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.