Quality Heuristics

Overview

A craft-quality review layer. This page names a small set of heuristics for judging whether a design feels deliberate, coherent, and restrained — or generic, over-built, and assembled from defaults. It is used at review time, on work that is already functionally correct, to catch the gap between "it works" and "it was made with intention."

It is a companion to UX Principles, and it answers, like everything else in the system, to the Design Approach. Three layers review a design, each asking a different question:

Layer	The question it asks
UX Principles	Will this work for the people using it?
Quality Heuristics	Is this made with intention, or assembled from defaults?
Design system rules — the component and foundation contracts	Does this use the system's conventions correctly?

All three answer to the Design Approach; none of them override it. A screen can satisfy every component contract and still feel generic — that gap is what this page is for.

What This Page Is Not

Not taste as law. A heuristic is a reason to look closer at a choice, never an automatic defect. Content, data, accessibility needs, and the component contract can all justify a "no."
Not a redefinition of anything. Applying a heuristic never changes tokens, semantics, component names, variants, states, or conventions. Those are fixed by the component contracts and the Design Approach.
Not a rewrite of UX Principles. That framework covers usability and human behavior. This one covers craft. They overlap on some screens and stay separate documents.
Not a site-wide checklist. Do not walk all seven heuristics through every component page. Reach for them on a specific review and move on.

How to Use It

Use it at review. Before a handoff, on someone else's work, or on an AI-assisted diff — after the work is functionally correct, not as a design-time form to fill in.
Run the review question for each heuristic against the screen or component in front of you. Each is a lens; more than one usually applies.
Treat a "no" as a prompt, not a verdict. Look closer. If the constraint that produced it is real, record the call next to the decision, per Every choice carries its rationale.
Keep it local. Apply it to the work under review and stop there.

A heuristic is a question, not a rule. If you cannot name the concrete change it would prompt, it is not helping here.

The Heuristics

Restraint

Every element on screen earns its place; nothing can be removed without losing meaning or function.

What good looks like: borders and surfaces appear only where spacing and alignment cannot carry the grouping on their own; decoration is absent unless it does work; one weight and one size per level of the hierarchy.
Common failure mode: a box around every group, an icon beside every label, decorative shadows or gradients, "just in case" controls, dividers used as spacing.
Review question: if I removed this element, border, or flourish, what would the user actually lose?
Supporting principle: Restraint.

Specificity

The design responds to this content, this data, and this flow — not a template dropped over them.

What good looks like: labels, empty states, and error messages name the real situation; layout reflects the actual priority of this screen; structure follows the content rather than the content being cut to fit the structure.
Common failure mode: a three-across card row because the width divided by three; "Welcome to your dashboard"; "Something went wrong"; a hero-plus-feature-grid-plus-CTA layout regardless of what the page is for.
Review question: could this exact screen be lifted into a different product unchanged? If yes, it is not specific enough.
Supporting principle: Jakob's Law sets the floor — start from the familiar pattern — but specificity is what you owe the content on top of it.

Hierarchy

Priority and emphasis are deliberate: the most important thing is the most prominent thing.

What good looks like: one clear primary action per view; type size and weight track real importance; secondary and tertiary elements are visibly subordinate; the eye has an obvious place to land first.
Common failure mode: three buttons all styled primary; every heading the same size; emphasis by making everything bold; two or three focal points competing for the same attention.
Review question: what is the one thing this view is for, and is it the most prominent element on it?
Supporting principle: pairs with Cognitive Load — a visible hierarchy is structure the user does not have to hold in their head.

Purposeful Styling

Color, weight, elevation, and motion each signal something — state, affordance, grouping, or layering. Style tracks meaning.

What good looks like: --primary marks the primary action; --destructive marks danger and nothing else; a shadow means "above the surface"; motion marks a state change the user should notice.
Common failure mode: color chosen because it looks good, --destructive as a decorative accent, elevation on things that are not layered, hover effects on non-interactive elements, animation that communicates nothing.
Review question: for each color, shadow, and transition here — what does it tell the user? If the answer is "it looks better," reconsider it.
Supporting principle: Semantic over literal.

Meaningful Content

The design is judged against real content — the longest name, the empty list, the three-digit number — not filler shaped to make the layout look finished.

What good looks like: realistic copy and data while designing; empty, loading, and error states written with real messages; the layout holds at the extremes of the real content range.
Common failure mode: "Card Title" over lorem ipsum; a table with exactly three tidy rows; every avatar the same initials; every label the same comfortable length.
Review question: would this layout still hold with the real content — the 40-character title, the empty state, the 3-digit count?
Supporting principle: none direct; it is the craft-side counterpart to the "a law is a hypothesis, a usability test is the check" note in UX Principles.

Consistency

An existing component, variant, or token is used before a new one is invented; new patterns appear only when nothing existing fits and the gap is named.

What good looks like: the need is met by something already in the system; spacing comes from the scale, color from semantic tokens, page structure from the documented template; a genuinely new pattern is introduced deliberately, with its rationale.
Common failure mode: a one-off card that is not Card; a hand-rolled menu where Popover fits; a 13px font size; a bespoke shadow; a new spacing value a few pixels off an existing one.
Review question: does the system already have something for this — and if I am adding something new, can I say why nothing existing works?
Supporting principle: Consistency through templates.

Simplicity

Accidental complexity is removed from what remains: the simplest structure that still does the job.

What good looks like: flat over nested; one screen over a wizard when the task fits on one; fewer states and fewer branches; the complexity that is left is essential, not speculative.
Common failure mode: a modal that opens another modal; cards nested three deep; a settings screen with twenty controls where three matter; configurability added for a case no one has yet.
Review question: what is the simplest version of this that still works, and what specifically breaks if I simplify to it?
Supporting principle: Restraint; it is the craft-side counterpart to Tesler's Law, aimed at the complexity that is reducible.

Examples

Short walk-throughs of the heuristics in use. Each names a situation, the heuristics in play, and the call — and none of them redefine a Monogem contract.

A Dashboard Empty State

Situation: a list view with no items yet shows a centered stock illustration, the text "No data yet," and a greyed-out button. Heuristics: Specificity (the message names nothing about this list or how it fills), Meaningful Content (placeholder art standing in for a designed state), Purposeful Styling (a button that looks disabled but is not). Call: one line naming what will appear here and the action that creates the first item, a real enabled primary Button, no illustration. Button variants and states are unchanged; this is a content and composition fix.

A Settings Section

Situation: eight rows, each a Switch with its own leading icon, each wrapped in its own bordered Card. Heuristics: Restraint (a border and an icon per row, neither doing work), Hierarchy (eight equally weighted toggles with no grouping or order), Simplicity (a surface nested per row inside the section). Call: one Card for the section, rows separated by spacing — or a Separator only where a real group boundary exists — icons dropped unless they speed scanning, and the two most-changed settings lifted to the top. Hick's Law already says eight comparable choices slow every use; these heuristics say the presentation is also over-built. Same screen, two lenses; no component contract changes.

A One-Off Stat Tile

Situation: a metric is shown in a plain <div> with a hand-picked 18px value, a custom label color, and a bespoke drop shadow. Heuristics: Consistency (a container, a type ramp, --muted-foreground, and a shadow scale all already exist), Purposeful Styling (the shadow signals elevation the tile does not have). Call: build it from Card at compact density, the number at an existing type-ramp size, the label in --muted-foreground, no shadow. If the same tile is needed repeatedly, that is a Patterns entry with its rationale — not a one-off. The component contract then governs how Card is used; this heuristic is about reaching for it in the first place.

Boundaries

A lens, not a gate. The Design Approach and each component's documented contract outrank anything on this page. A heuristic informs a review; it does not decide it.
No redefinition. Applying a heuristic never changes semantics, token naming, component naming, variants, states, or shadcn-style conventions.
No blanket rollout. Apply it to the work under review and record any close call there. Do not thread it through every component doc.
Not a substitute for the contracts or for testing. The component docs say what is correct; a usability test says what works; this page asks whether the result feels deliberate. Three separate checks.
Boundary with UX Principles. Usability and human behavior are that page's; craft and intentionality are this one's. When both apply to a screen, cite each where it does its work.