[robfeldmann]

The owner found the first component demos ugly and unclear: it is hard to tell what you are looking at or what is being demonstrated. This PR studies how good TUIs avoid that problem and turns the findings into a repo skill for designing useful terminal applications: sketching a screen before it is built and reviewing it after. Tessera's demos are one use of it, each built as a small worked application. It changes documentation and one lint task only. No Swift changes.

What's in it

• Research record docs/research/intuitive-tui-design.md (048). I ran ratatui's flex, constraint-explorer, constraints, and demo2, plus lazygit 0.66.2, headless in a pty and kept their screens. I read the source of btop, htop, k9s, Bubbles/Bubble Tea, gum, Lip Gloss, Textual's demo, and Tessera's omp2-derived catalog, with citations pinned to commits. The record also critiques each of Tessera's eight demos, using dev:shot output at both viewports. It also records a blind trial of the skill: three agents each built a flex demo with it, what the owner preferred and why, and the gaps all three hit.
• Skill .agents/skills/tui-design/SKILL.md is about building useful TUIs that look good and work well. It has eleven principles, four of them with before/after pairs in the catalog's wireframe dialect drawn from small applications (a focus timer, a backup disk, a mail client, a file browser). It also has a sketch mode that draws every interaction's extremes, a review mode, a checklist, anti-patterns, and a separate Tessera-specifics section: the dialect and roles and how they map to today's attributes, what the view layer can draw today, a rule for small named stand-ins where the toolkit lacks a piece (a measuring LeafView; and, per owner decision Q29, one shared KeyLegend-style key row in DemoSupport that every demo calls, never per-demo copies), demos as worked applications with a Flex editor-window example, and the tessera review recipe. AGENTS.md and tessera-contributing ("Add a demo") now point to it. mise run quality:wireframes now checks the skill's wireframes along with the catalog's.
• Designer step in plan 036 (owner decision Q25, 2026-10-27). "Patterns to follow" and "Unattended execution" now say: every slice that adds or changes a demo has a designer agent with the tui-design skill sketch the demo before it is built and review it after; the sketch goes in the slice's PR description under ## Demo sketch and is cited on its Progress line; the owner glances at it when available and it never blocks an unattended run; the designer review runs before the critic hands the PR off. Plan 036 records the decision, and its Patterns now also carry Q29 (the one shared key-row stand-in).
• Separate commit docs: correct libghostty-vt distribution facts:
  • Saves the Ghostty 1.4 review as research record 047.
  • Adds dated corrections to libghostty-vt-distribution.md: tip assets can be pinned per commit at tip.files.ghostty.org/<commit>/…, and caelyreth/libghostty-vt-spm does ship the VT-only library, for Apple only.
  • Rewrites updating-ghostty-vt.md:14 around libghostty-vt's own 1.0 tag and the owner's 2026-10-27 decision to hold the pin until then.
  • Corrects plan 036's Decision 9 entry to name the ghostty-vt-f54340ad7781-r2 release.

Checks

mise run quality:format, mise run quality:lint, mise run quality:wireframes, and iwe schema validate (from docs/) all pass.