Principles

Surface what the backend already knows

First-class UI for real user jobs; power-user syntax is not a substitute

Parity of affordances

If Mentions is a dropdown, Commenter must be too

GUI / source-of-truth sync

Settings GUI must reflect reality; jump-to-JSON when needed

Clear severity and exit codes

Warnings look like warnings; help is not failure

No silent failure / lying toasts

Explain why, offer a fix

Theme as contract

Previews and diagrams inherit host theme tokens

Preview fidelity

Interactive constructs stay interactive; sync tracks source

Progressive disclosure

Budget the first screen; deepen on demand

Visitor-first repo homepage

Hide empty owner CTAs; put README before the file tree; disclose addable sidebar sections on demand

Context-bound settings

Settings follow activity state as a dependent surface — show only applicable controls beside the here-and-now; keep the global catalog as escape hatch

Instruction flows for decision-tree docs

Menu-style paths: one choice at a time, continuations under decisions, shareable URL state

Pass-through extensions for meta-suffixes

.example / .template / .dist badges peel to the inner type for open, edit, and icon — not a dead last-suffix ProgID

Open-with interrupt for alternate handlers

Ctrl+double-click or middle-click on a file asks which app opens this launch — default open is not an unstoppable handoff

ClearType subpixel fidelity

Tuner UI must not imply per-panel RGB/BGR when GDI orientation is session-global and DirectWrite monitor params are app-opt-in

Scoped UX architecture

Many small tools, each with a clear job, under one roof — hard boundaries plus a shared shell

Processing maps for ordered systems

If the runtime is a sequence, compose it as one typed pipeline — nest parallelism inside steps

Share IR, not pixels

Prototypes split core, headless controller, renderers, and thin host wrappers — do not auto-export full UI

Unified selection modes

File and folder in one dialog when the job is "open something"

Non-frustrating responsiveness

Hangs are architectural bugs, not user patience tests

Attention ethics

Do not spend the user’s brain for engagement metrics

Labels versus wires

Pretty names are human labels; systems wire on content identity or explicit pointers — not on the label alone. Public entry is the felt rename/URL breakage; this principle is the diagnosis.