| name | ui-ux-design-principles |
| description | Experience-level engineering canon, the UI/UX counterpart to software-design-principles (code-level) and architectural-design-principles (system-level). Usability heuristics, visual hierarchy, accessibility, interaction and feedback, information architecture, design systems and tokens, and testable UI. Imported by the consort UX Designer (authoring design-guide.{md,json} + ia.md and the adherence gate) and by the Driver building UI. Use when: shaping a design guide or information architecture, reviewing a user-facing surface, choosing a UI framework, or making the UI testable. |
ui-ux-design-principles
Canon for decisions about the USER's experience. The third of the design-principles trio:
software-design-principles – how a unit of code is written (SOLID, DRY, clean code).architectural-design-principles – how the system is shaped (layers, twelve-factor, fitness functions).ui-ux-design-principles – how the product looks, behaves, and is navigated, kept testable.
The project's design-guide.{md,json} and ia.md are the per-project instantiation of this canon, the way architecture.json instantiates the layering rules. Markdown only, no scripts: consulted, not invoked. Like the architecture canon, it points each rule at how it's enforced (the E2E/Playwright layer, the design-adherence check against design-guide.json, a11y checks). A rule no test defends is advisory; one a check defends is part of the build.
When to use
- The
consort UX Designer imports it to author design-guide.{md,json} + ia.md and define the adherence gate.
- The Driver imports it when building UI that must adhere to the design guide.
- You're reviewing a user-facing change and need a shared vocabulary (heuristics, hierarchy, accessibility) rather than taste.
- You're choosing how the UI is built and need the testability rules (framework choice, stable seams).
UX review checklist (mandatory before promote/merge)
Confirm each row before declaring the design done. A blank row is fine when scope justifies it; an unconsidered row is a smell.
| Property | The rule | Enforced by |
|---|
| Feedback | Every data-changing action shows success AND failure feedback; no silent failures | E2E asserts the visible confirmation |
| Accessibility | Keyboard-navigable, semantic HTML, sufficient contrast, labelled controls | a11y check (axe / equivalent) at the E2E layer |
| Visual hierarchy | The primary action is most prominent; the eye is guided | design-adherence (tokens) + review |
| Consistency | Reuses design-guide tokens + standard components; one pattern per job | design-adherence against design-guide.json |
| Information architecture | Screens, navigation, primary flows defined before styling | ia.md present + E2E flows trace it |
| Testable seams | Interactive elements expose stable selectors (data-testid / role) | E2E addresses elements by seam, not brittle CSS |
| Loading / latency | Any action over ~200ms shows a loading state; feedback causes no layout shift | E2E + design-adherence |
A property with no owner or no check: resolve it before merging.
References
- Usability heuristics – Nielsen's ten, condensed, each with its violation smell.
- Visual hierarchy – type scale, spacing, color, contrast, alignment: guiding the eye.
- Accessibility – WCAG essentials, semantic HTML, ARIA, keyboard, focus, contrast. Not optional.
- Interaction and feedback – affordances, feedback rules, loading states, error prevention/recovery, progressive disclosure.
- Information architecture – screens, navigation, flows, mental models. The source of
ia.md.
- Design systems and tokens – tokens as source of truth, consistency, component reuse, the
design-guide.md / .json relationship.
- Testable UI – testable frameworks, stable seams, deterministic rendering, boundary-layer rendering, design-adherence at the E2E layer.
Hard rules
- No silent failures, no unacknowledged success. Every data-changing action shows visible success and failure feedback; feedback never shifts layout.
- Accessibility is not optional. Keyboard-navigable, screen-reader-friendly, sufficient contrast, labelled controls, defended by an a11y check.
- Consistency over novelty. Reuse the design-guide tokens and standard components; one pattern per job.
design-guide.json is the source of truth.
- Visual hierarchy guides the eye. The most important action is the most prominent; importance maps to weight, size, position.
- Information architecture before pixels. Screens, navigation, and flows are defined (
ia.md) before styling.
- The UI is testable by construction. Modern framework, deterministic render, stable seams; rendering lives in the boundary layer. See testable-ui.
- Progressive disclosure. Show what the user needs now; defer complexity behind intent.
Composition
consort – UX Designer authors design-guide.{md,json} + ia.md and sets the adherence contract; Test Strategist writes E2E scenarios + a11y checks against it (see test-strategy); Driver builds UI that adheres.architectural-design-principles – testable-ui shares the boundary-layer rule (templating is a boundary adapter) and the fitness-function model.software-design-principles – clean-code naming applies to components and template partials too.
