|
| 1 | +# Terminal.Gui — Constitution |
| 2 | + |
| 3 | +> The tenets in each section are listed in **precedence order**. When two tenets conflict, the one higher in this document wins. |
| 4 | +
|
| 5 | +This document is the single authoritative source for Terminal.Gui's product mission, non-goals, engineering philosophy, and design tenets. All other documents (`CONTRIBUTING.md`, `CLAUDE.md`, `.claude/rules/`, and the deep-dive docs in `docfx/docs/`) elaborate on these tenets; they do not supersede them. |
| 6 | + |
| 7 | +## Table of Contents |
| 8 | + |
| 9 | +- [I. Mission](#i-mission) |
| 10 | +- [II. Non-Goals](#ii-non-goals) |
| 11 | +- [III. Tenets](#iii-tenets) |
| 12 | +- [IV. Engineering Philosophy](#iv-engineering-philosophy) |
| 13 | +- [V. Code Style Tenets](#v-code-style-tenets) |
| 14 | +- [Relationship to Sub-Projects](#relationship-to-sub-projects) |
| 15 | + |
| 16 | +--- |
| 17 | + |
| 18 | +## I. Mission |
| 19 | + |
| 20 | +Terminal.Gui is a **cross-platform UI toolkit for building sophisticated terminal UI (TUI) applications** on .NET. It is the standard by which TUI applications on .NET are measured. |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## II. Non-Goals |
| 25 | + |
| 26 | +These were considered and rejected — do not accidentally pursue them: |
| 27 | + |
| 28 | +- **Terminal.Gui is not a web framework.** We do not pursue HTML/CSS layout models. |
| 29 | +- **Terminal.Gui is not a replacement for ncurses.** We target .NET developers, not C developers. |
| 30 | +- **Terminal.Gui is not a pixel renderer.** Width is measured in terminal cells, not pixels. |
| 31 | +- **Terminal.Gui is not opinionated about application architecture.** We provide building blocks; we do not mandate MVVM, MVC, or any other application pattern. |
| 32 | +- **Terminal.Gui does not own the terminal.** We share it with the host shell and must be good citizens (clean up on exit, respect terminal state). |
| 33 | + |
| 34 | +--- |
| 35 | + |
| 36 | +## III. Tenets |
| 37 | + |
| 38 | +### Users Have Final Control |
| 39 | + |
| 40 | +Users choose the platform, the terminal, and the key bindings. Our defaults are consistent and sensible, but everything configurable must be configurable. We never hardcode behavior that the user or developer cannot override. See the [Keyboard deep dive](../docfx/docs/keyboard.md) and [Mouse deep dive](../docfx/docs/mouse.md). |
| 41 | + |
| 42 | +### Keyboard First; Mouse Optional |
| 43 | + |
| 44 | +Terminal users expect full functionality without a mouse. Anything that can be done with the mouse must also be doable with the keyboard. We avoid mouse-only features. See the [Mouse deep dive](../docfx/docs/mouse.md). |
| 45 | + |
| 46 | +### More Editor Than Command Line |
| 47 | + |
| 48 | +Once a Terminal.Gui app starts, the user is no longer using the command line. Users expect keyboard idioms consistent with GUI apps (VS Code, Vim, Emacs, etc.), not shell idioms. See the [Keyboard deep dive](../docfx/docs/keyboard.md). |
| 49 | + |
| 50 | +### Be Consistent With the User's Platform |
| 51 | + |
| 52 | +Users choose their platform. Terminal.Gui apps must respond to keyboard and mouse input in a way consistent with platform conventions. The source of truth for default key bindings is [Wikipedia's keyboard shortcuts table](https://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts). See the [Keyboard deep dive](../docfx/docs/keyboard.md). |
| 53 | + |
| 54 | +### If It's Hot, It Works |
| 55 | + |
| 56 | +If a `View` with a `HotKey` is visible and the HotKey is shown, pressing that HotKey must invoke the defined behavior. We strive to ensure that modal contexts do not leave HotKeys appearing active when they are not. See the [Keyboard deep dive](../docfx/docs/keyboard.md). |
| 57 | + |
| 58 | +### Separation of Concerns |
| 59 | + |
| 60 | +Layout, focus, input, and drawing are cleanly decoupled. We resist the urge to merge them for short-term convenience. See the [v2 Architecture overview](../docfx/docs/newinv2.md) and [Layout deep dive](../docfx/docs/layout.md). |
| 61 | + |
| 62 | +### Testability First |
| 63 | + |
| 64 | +Views must be testable in isolation without global state. `Application.Init` is required only for integration tests. We maintain ≥80% test coverage and we never decrease it. See [Testing patterns](../.claude/rules/testing-patterns.md). |
| 65 | + |
| 66 | +### Performance Is a Feature |
| 67 | + |
| 68 | +We measure rendering and event-handling overhead. We never accept regressions in the hot path without a documented justification. See the [Drawing deep dive](../docfx/docs/drawing.md). |
| 69 | + |
| 70 | +### Documentation Is the Spec |
| 71 | + |
| 72 | +API documentation is the contract. When docs and code conflict, the code is wrong. See [api-documentation rules](../.claude/rules/api-documentation.md) and Code Style Tenet 5 in [CONTRIBUTING.md](../CONTRIBUTING.md). |
| 73 | + |
| 74 | +### Think in Graphemes, Not Runes |
| 75 | + |
| 76 | +Text measurement and rendering always operate on grapheme clusters, not `char` or `Rune` values. Always use `string.GetColumns()` for width; always iterate with `GraphemeHelper.GetGraphemes()` for rendering. See [Unicode/Grapheme rules](../.claude/rules/unicode-graphemes.md). |
| 77 | + |
| 78 | +--- |
| 79 | + |
| 80 | +## IV. Engineering Philosophy |
| 81 | + |
| 82 | +Developers — AI agents and humans — working on Terminal.Gui strive to raise the bar as Principal Engineers. Principal Engineers are measured by how they live the [Amazon PE Community Tenets](https://www.amazon.jobs/content/en/teams/principal-engineering/tenets): |
| 83 | + |
| 84 | +1. **Exemplary practitioner** — set the standard through your own work. |
| 85 | +2. **Technically fearless** — tackle the hardest, most ambiguous problems. |
| 86 | +3. **Lead with empathy** — foster inclusion; be mindful of your impact. |
| 87 | +4. **Balanced and pragmatic** — neither dogmatic nor reckless. |
| 88 | +5. **Illuminate and clarify** — bring clarity to complexity; drive crisp decisions. |
| 89 | +6. **Flexible in approach** — adapt style and methods to the problem at hand. |
| 90 | +7. **Respect what came before** — appreciate existing systems; learn from the past. |
| 91 | +8. **Learn, educate, and advocate** — pursue continuous learning and teach others. |
| 92 | +9. **Have resounding impact** — results are the minimum; lasting impact is the bar. |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## V. Code Style Tenets |
| 97 | + |
| 98 | +*(Source of truth: [CONTRIBUTING.md](../CONTRIBUTING.md))* |
| 99 | + |
| 100 | +1. **Six-Year-Old Reading Level** — Readability over terseness. |
| 101 | +2. **Consistency, Consistency, Consistency** — Follow existing patterns ruthlessly. |
| 102 | +3. **Don't Be Weird** — Follow Microsoft/.NET conventions. |
| 103 | +4. **Set and Forget** — Rely on automated tooling; don't fight the formatter. |
| 104 | +5. **Documentation Is the Spec** — API docs define the contract; implementation must match. |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## Relationship to Sub-Projects |
| 109 | + |
| 110 | +Sub-projects (e.g., `Terminal.Gui.Text`) may extend this constitution. When a sub-project tenet conflicts with a tenet in this document, this document wins unless the sub-project explicitly documents the exception and the reason. |
0 commit comments