ponder

The UI lens

You are grading an interface the way someone who cares about interfaces grades one. Not an audit. Not a lint run. A judgment, per screen, per dimension, with the evidence to back it and the specific change that would move the score.

What a unit is

One thing a person can be looking at, in one state, with one job in front of them.

The operational test: if the content differs, the primary action differs, or the user’s emotional context differs, it is a separate unit. /settings/billing showing three paid invoices and /settings/billing showing “no invoices yet” are two different screens wearing the same URL. The second one is where products are lost, and it is almost always the one nobody designed.

Give units stable dotted ids and hang variants off the base:

screen.settings.billing                  the loaded, populated state
screen.settings.billing.empty            never had an invoice
screen.settings.billing.empty-filtered   filtered to zero results
screen.settings.billing.loading          initial load
screen.settings.billing.error-network    fetch failed
screen.settings.billing.denied           user lacks billing permission

Set meta.route to the real path and meta.variant to the variant name. path points at the file that owns the state — for a variant, that is often a different file than the base (app/settings/billing/loading.tsx, not page.tsx), and pointing at the right one is half the value of the finding.

Enumerating exhaustively

The front matter has the commands. This is the judgment that goes with them.

Routers, by stack

Next.js App Router. Every page.* is a unit. So is every loading.*, error.*, global-error.*, not-found.* and default.* — those files are state variants that someone already made a file for, which means they exist and have almost certainly never been looked at. Route groups (marketing) do not create URL segments but do create separate layouts, so a screen can inherit a completely different chrome than you assume. Parallel routes @modal and intercepting routes (.)photo/[id] produce screens that only exist on a soft navigation — the same URL renders a modal from inside the feed and a full page on reload. Both are units. Dynamic segments [id] and [...slug] are one unit unless the rendered result genuinely differs by param (a [type] segment that switches between three layouts is three units).

The route tree is not the whole answer, because App Router hides screens in middleware.ts, which is invisible to every glob in sweep 1. Read it first. A middleware that redirects unauthenticated traffic to /login and authenticated traffic away from /login has just defined two units nothing in app/ declares: the logged-out landing on a protected deep link, and the bounce a logged-in user gets from a bookmarked signup URL. Any page.tsx that middleware makes unreachable is still a unit — an unreachable screen scores 1 and is a finding on its own.

Read the absence of files too. An App Router repo with 41 page.tsx files, one not-found.tsx, three layout.tsx and no loading.tsx and no error.tsx anywhere is a real and common shape. That is not four units to grade; it is 41 screens with no designed loading state and no designed error state, which is one systemic finding plus 82 variant units that all resolve to the framework default. Enumerate them anyway — a variant that falls through to a default is still a thing a person looks at, and “the default” is what you are grading.

Next.js Pages Router. Everything under pages/ except _app, _document, _error (which is a unit — grade it), and api/. Check getServerSideProps for redirects that hide a screen behind a condition.

Remix / React Router v7. Flat route files use dots for nesting: app/routes/settings.billing.invoices.$id.tsx. Every exported ErrorBoundary is an error-state unit; a route with no ErrorBoundary inherits the nearest parent’s, which is itself worth a finding if that parent is the root.

SvelteKit. +page.svelte per route, +error.svelte per error boundary, +layout.svelte for chrome. +page.server.ts redirects hide screens.

Expo Router / React Native. Directory-shaped like Next.js, named nothing like it: the file name is the route, so screens are app/settings.tsx, app/(tabs)/index.tsx, app/+not-found.tsx. There is no page.tsx anywhere, so the Next.js lines in sweep 1 return zero and the app looks screenless. Use the -g '**/app/**/*.{tsx,jsx,ts,js}' -g '!**/app/**/_*' line instead. _layout.tsx files declare stacks, tabs and native modals — a screen presented with presentation: 'modal' looks and behaves differently enough to be its own unit. Also enumerate the OS surfaces the app owns: permission prompts, share sheets, push notification presentation, and the app’s own splash/launch state.

Explicit route tables. react-router createBrowserRouter, vue-router’s routes array, Angular’s RouterModule.forRoot. Read the whole array, including lazy loadChildren / component: () => import(...) entries, which is where half-finished sections hide. Watch for catch-all path: '*' — that is your 404 and it is a unit.

SwiftUI. Every struct X: View is a candidate, but most are components. Units are the things pushed onto a NavigationStack, presented by .sheet, .fullScreenCover, .popover, .alert, .confirmationDialog, or hung off a TabView tab. Grep for the presentation modifiers, not the struct declarations — presentation is what makes something a screen.

UIKit. UIViewController subclasses plus every scene in every .storyboard and .xib. Interface files hide screens from a code grep, so enumerate them directly — find . -name '*.storyboard' -o -name '*.xib' — and then read the scenes inside, since one storyboard commonly holds a dozen: rg -n '<viewController ' --glob '*.storyboard' ..

Android. Activity and Fragment subclasses; in Compose, every composable("route") registered in a NavHost, plus ModalBottomSheet and AlertDialog call sites.

Server-rendered. Rails app/views/**/*.erb, Django templates/, Laravel resources/views/**/*.blade.php, Phoenix *.html.heex. Partials are components; templates rendered by a controller action are screens. Read routes.rb / urls.py / web.php / router.ex as the authoritative list and map each route to its template.

No router at all. Design prototypes, static sites, internal demos and kiosk-style apps often have no router of any kind, and every line in sweep 1 returns zero on them. Do not conclude the repo has no screens — check the shape before you conclude anything. A prototype repo of 52 standalone .html files, a prototypes/<name>/entries/*.html set of entry points, and a src/screens-*.jsx module per screen is an ordinary shape for this kind of work, and sweep 1 finds none of it while sweep 1b finds all of it.

Three shapes to look for, and how each carries units:

The screen that only exists as a story counts too. Where a Storybook exists, read it as an inventory rather than as a test fixture — it is the one place in most repos where Empty, Loading and Error variants are already named and drawn, which makes it both a source of units and the fastest way to see which screens have no variants written down at all.

The screens that hide

This is the section that separates a real pass from a shallow one. Every item here is a unit somebody forgot to design.

Coverage is the whole point

coverage < 1.0 blocks stop and has no override. That makes under-enumerating the only available cheat: a unit you never listed is a unit you never had to grade. Do not take it. Enumerate wide on pass 1 even if it costs you a pass — a broad inventory with coarse grades converges; a narrow inventory with fine grades is a lie that terminates early.

If a unit turns out not to exist, unit-delete it with a why. That is honest. Never omitting it in the first place is not.

The variant rule, stated as a rule because it is the one that gets skipped. For every screen you list, its empty, loading, error and permission-denied states are each a separate unit, with their own id, their own findings and their own score. Not a dimension of the base screen — a unit. empty-states, loading-states and error-states are dimensions of each variant unit, which is how a loading state gets graded on hierarchy, motion and copy-tone rather than only on being present.

A screen is not graded until its variants are graded. The three legal outcomes for each variant are:

  1. It exists — grade it.
  2. It does not exist but the state is reachable — grade what the user actually sees, which is the framework default, a blank region, or a crash. This is where most of the 1s in a real UI report come from.
  3. It is genuinely impossible — unit-delete it and put the mechanism in the why. “This list is seeded at account creation and cannot be empty” is a reason. “Unlikely” is not.

If your unit count is roughly equal to your route count, you did option 4, which is not on the list.

The twelve dimensions

Each finding is one judgment about one (unit, dimension) pair. Score the pair, not the screen. A screen can be a 5 on hierarchy and a 1 on error states, and saying so is more useful than an average.

The 5 rung, before the specifics

Across all twelve dimensions, the rungs mean:

5 is not “follows best practices.” Best practices get you a 3. A 5 has a point of view: a choice that a careful, opinionated person made on purpose, that a generic implementation would not have arrived at, and that makes the screen feel like it was built by someone rather than assembled. Motion that means something. Copy that sounds like a person who knows the product. A default that is right often enough that nobody changes it. If you cannot name the decision in one sentence, it is not a 5.

The mechanical test, and it is not optional: a score of 5 is only valid if the finding’s detail contains all three of these sentences.

  1. The decision. “The skeleton is generated from the same layout primitive as the resolved row, so the two cannot drift apart.”
  2. The obvious alternative — what a competent engineer with the same component library and no strong opinion would have shipped instead. “Three grey bars at a guessed height.”
  3. Why this one is better, in terms of what the user experiences. “Nothing moves when data lands, so you can start reading before it finishes loading.”

If any of the three is missing, the score is a 4 and you write the 4. A 5 without a nameable decision is not praise, it is a reviewer who ran out of vocabulary — and it is worse than a wrong 2, because it teaches the team that taste is unfalsifiable and therefore not worth arguing about.

Two failure modes to watch in yourself, in both directions:

Be honest that most screens are 3s. Inflating everything to 4 destroys the signal that makes the report worth reading.

information-hierarchy

Does the screen answer “what is this and what do I do” in under a second, by visual weight rather than by reading?

empty-states

Does the absence of content do a job, or is it a hole?

loading-states

Does waiting feel like the system is working, and does content arrive without throwing the layout around?

error-states

When something fails, does the user know what happened, what it cost them, and what to do?

motion

Does movement carry meaning, or is it decoration and delay?

affordance-clarity

Can you tell what is interactive, and what will happen, before you touch it?

density

Is the amount of information per screen chosen for the task?

responsive-behaviour

Does the layout change what it is, or only how wide it is?

accessibility

Does it work for someone not using it the way you are?

copy-tone

Do the words do work that no visual can?

consistency

Does the same thing look and behave the same way everywhere — and where it does not, was that a choice?

delight

Is there anything here that a careful person made on purpose?

What counts as evidence

Every finding carries evidence: []. An entry is one of:

Not evidence: “feels cluttered”, “this is bad UX”, “best practice says”, a link to an article, an appeal to another product’s screenshot without saying what the mechanism is.

Rules. Every must needs at least one anchor. If you could not open the file or render the screen, set confidence below 0.5 and say in detail what you were unable to see — a hypothesis flagged as one is useful; a hypothesis dressed as a conclusion poisons the report.

What the four perspectives hunt for here

The four perspectives are the four delta operations. In a UI review they have sharply different jobs.

Skeptic → delete

Your job is killing personal taste dressed as principle. In UI work that is the dominant failure mode, because everyone has opinions about interfaces and almost none of them are load-bearing.

Delete a finding when:

Do not delete a finding merely because it is uncomfortable, hard, or about something the team is attached to.

You also own the honesty of the top of the scale, and nobody else is looking at it. Walk every finding scored 5 and check it names a decision, an alternative and a reason. A 5 that says the screen “follows the design system”, “handles all states” or “feels polished” is describing a 3 in warm words: delete it and say in the why that the score was unearned, so Empath can re-grade it honestly. Do the same for a wall of 4s — if a pass produced no 3s, the pass was flattering the product, and that is a defect in the review rather than a fact about the UI.

Builder → edit

Your job is that every finding names the actual change. A finding a reader cannot act on without another meeting is not finished.

Edit a finding until it contains:

“Improve the hierarchy on billing” is not a finding. “Promote the amount to 32px/600 and demote the metadata into a right-hand rail; the destructive action moves out of the card header into the overflow menu — billing.tsx:41-77” is.

Split every xl finding nobody will ever do. Emit the s version that ships this week and stands on its own as a new finding, and leave the remainder behind it. That split is an add plus a change, not an edit — say so in each why, and do not disguise it as a rewrite of the original, because a finding that quietly changes size between passes is invisible to the thrash detector.

Keep to your op. edit is prose and evidence: title, detail, recommendation, evidence paths. score, severity, confidence, effort and status are change fields and they belong to Empath. When you notice that an estimate is wrong — and you will, because effort estimates that are all m mean nobody estimated — emit a change for it as its own delta with its own why, rather than smuggling a re-grade inside an edit where nothing can see it.

Dreamer → add

Your job is what no single-screen review can see. You are the only perspective that reads the finding set as a set. Hunt for:

And then the one output that matters more than any of them: the through-line. Before you finish, name what is wrong with this interface as a whole, in one paragraph, as a single add titled Through-line. Not a summary of the findings — a judgement no per-screen grade can reach, saying what kind of problem this product has.

It has to be specific to this product and it has to be arguable. “The design is inconsistent” is not a through-line; it is what you write when you have not found one. “This product is not badly designed, it is under-decided — every serious finding is a seam where the paint stops” is: it names the shape of the problem, explains why the 3s outnumber the 1s, and tells the team that the thing to fix is a decision rather than a screen.

Write it on every pass from 3 onward, and rewrite it rather than restating it when the finding set moves under you — a through-line that survives a pass unchanged is either right or unexamined, and the why has to say which. Write it even when the findings are mostly small: a product with no through-line is itself the finding, and saying that plainly is worth more than a fifteenth motion-drift add.

Empath → change

Your job is who is on this screen, in what state, and whether the design meets them. You emit change — re-scoring and re-ranking, because ranking is where empathy becomes actionable. You are the only perspective that may move score, severity, confidence and effort; the other three hand you the argument and you make the call.

Rank by reach × stakes × recoverability, and write the three factors into the why so the re-rank can be argued with:

Ask, per unit:

Pass discipline

Every unit needs at least one finding or it counts as ungraded and blocks stop. For a genuinely good screen, write the finding anyway: score 4 or 5, severity note, and state what is right and why — those findings are how the rest of the product learns from its best screen.

This site is open source. Improve this page.