List page recipe

A live page, a screenshot, a brief or a PRD is read for what it means: the things on the page, what each knows, how it moves through its life, what people do with it and what they look for first. That reading is written down twice, as the thing's model (system/model/, what exists, shared by every page that shows it) and the page's intent (what this page is for). The page description is then built from those by the rules (build.mjs), never transcribed from the original: how the original draws, places, orders or clicks things is left behind, and only becomes evidence when it says something about meaning (a per-row Send button says a draft's next step is Send). Questions are about meaning only; what the system decides is never asked. Where neither meaning nor a rule decides something (whether a date shows its time of day), the default is the option closest to the existing product; the builder may suggest another, as a suggestion. Identifiers keep the source's format exactly (“#0003”, “#29599975514”): people recognise and search them; the description records it (format) and sample data follows it. When the source shows none, it's a question. A label that puts several values in one line (“Vendor 100001846 #0003”, “Mykola • Job”) is read apart into its fields, each with the thing it belongs to (the vendor's name, the vendor order's own number): that's a requirement, written in the model; how the parts show is the rules'. When the source doesn't say whose a value is, it's a question.

Why: Copying a page's presentation carries its accidents into the system, and every list ends up looking like the page it came from instead of like the system. Reading meaning is also how a PRD will be read, so existing pages and new requirements go through the same door.

survey · Product designer, 15 Oct 2026

A list page's title is the label of the menu item that opens it, word for word; the description names the menu item, never a title.

Why: One source: renaming the menu renames the page, and the selected menu item and the header can't disagree.

schema check · D28

What clicking a row does is the system's, decided by the thing, never copied from the original. A thing with its own full-screen window (a workspace like the job's, opened by Edit or something like it; the model's workspace) opens it: the row, the name link and Open in the ··· menu (named after it: Open job, with the expand icon) all go there, and the record beside the list is Quick look, second in the ··· menu. Anything else peeks: the record beside the list from 1280 up, a side sheet below. Checkbox clicks never open; the row's name is always a real link.

Why: Where a thing has a window of its own, that's where people work on it: a quick look first is a detour on every row. The record beside the list stays a click away for a glance (for now). Lists of things without one are triaged, and a peek suits them.

renderer · D30, D69, D17, I6, I7, L-source, Product designer, 19 Oct 2026: a thing with its own full-screen window opens it from the row

Each column declares one of the types in the types table. The type decides alignment, format, sort direction, the filter picker and where the value sits on a phone; the description never sets those one by one. A value in the name's lines or the record's heading reads as its type does in its column: “5 items”, “$1,900.00”, “Labor and materials”, never a bare number.

Why: One answer per column covers six decisions, so pages come out alike and the survey stays short.

schema renderer check · Tables on phones research (Figma, Oct 2026), Product designer, 14 Oct 2026, Product designer, 15 Oct 2026

Every field (in the filter, sort, group and column menus) and every action (on the record, the bulk bar and in menus) has an icon, and it comes from the vocabulary (system/model/icons.json), never picked for a page: a field by what its key means, else by the record it links to, else by its type; an action by its label, else by its verb; a “Change <field>” action takes the field's icon. One meaning, one icon, everywhere: the pencil is Edit and nothing else. A meaning the vocabulary doesn't cover stops the build: the builder proposes a Font Awesome icon, and it joins the vocabulary once approved. No stand-in icon, ever. A source's own icons aren't copied (L-source); its tooltip words are evidence of meaning.

Why: Icons picked page by page drift: the same action gets different icons, and an unknown one gets whatever's nearest (every new action showed as Edit). A vocabulary keeps them learnable across the product.

check renderer · D58, Product designer, 15 Oct 2026

Priority 1 is the row's name: exactly one column, type name, never hidden. 2 is the key figure (left unused when the list has none), 3 the status; higher numbers leave first as the screen narrows and beside an open peek. Numbers needn't be consecutive.

Why: What survives at each width is decided once, not per breakpoint. NN/g: lead with a readable name.

schema check · D17, Tables on phones research, Product designer, 14 Oct 2026

The name column's title starts with words a person recognises (customer, job, item); numbers and codes go to its detail line. A field with its own column in the table isn't repeated on the name's second line: one place per row. On a phone, where the columns go, the row's bottom line shows the first of them (the job), so nothing is lost there.

Why: People read about the first two words of each row (NN/g); “INV-1199 · Lucia Ruiz-Ortega” spends them on the number.

check · D32, Tables on phones research, Product designer, 15 Oct 2026

What sits before a row's name is a slot (leading), filled from the model, not from what the original draws there: a thumbnail when the thing has pictures (a placeholder for rows without one); otherwise an avatar when the row is a person or company, or is known by one (its title leads with a customer or vendor: the avatar is theirs); otherwise nothing. An icon only when the model gives the thing one. Never by habit, never because another list has one.

Why: The slot helps a scanning eye find a row by who or what it's about. Filled for any other reason it's decoration, and filled by copying it carries the original's accidents.

check · D55, L-source, Product designer, 15 Oct 2026

A status column lists its values in lifecycle order, each with a stage (new, draft, waiting, won, underway, done, lost, late, neutral). The stage picks the colour: a dot on the status's card, a plain tinted badge in the rows; a list never picks colours itself. The status shapes (dashed, quarter, half, three quarters, slash) are the job list's own and appear nowhere else. When the source colours its statuses, the stage keeps the same colour family (its red is our red, its amber our amber), within what the status means; a colour no fitting stage has is a question. When cards and badges name a status differently (Unsent, Not sent), the badge's word wins.

Why: The same stage looks the same in every list. The shapes were drawn for a job's progress; on another list's statuses they'd promise a meaning they don't have. The label carries the meaning, so colour is never the only signal.

schema renderer · D12, Product designer, 14 Oct 2026: shapes for the job list only, dots elsewhere, Product designer, 15 Oct 2026

Sample data is built from the model, one coherent story per row: its status decides the steps it went through (the lifecycle's path, endings from where they come from), the steps decide its dates (in order, never after today), and a field that belongs to a step it didn't reach stays empty (no sent date on a draft, no decline reason on a cancelled order). The record's activity is that story: each step it reached as its event (“Sent to {vendor}”, with when, who and a note where the model has them), then the next step, dashed. The sample covers what testing needs: every status has rows, with zeros and empty fields among them, and one row in twelve carries the longest kind of name (a vendor's full legal name with its trades), so the layout is tested at its worst; ids in the source's format; a category's values only as the model lists them (a waiver that's only been seen as None stays None until someone says what else it can be); reasons and names that read like real ones, and a linked company a real company, never a placeholder such as the catalog's “In-house”; a company's name, its trade and what it provides agree (Cedar Electric does electrical work); what's set aside (cancelled, inactive) is rare, as in a real list. The renderer checks its sample against the lifecycle and says on the page where it doesn't hold.

Why: Sample data that contradicts itself (a declined order that was never sent) hides real problems and invents fake ones; read from the model, it tests the design the way real data will.

renderer · D62, Product designer, 15 Oct 2026, D63

Above the list is one of two summaries, never tabs. KPIs, the default: the few figures that say how the list is doing and what needs someone (money owed, overdue, paid in the last 30 days, missing documents, a rate), at most four, as a row of cards. A KPI that's a slice of rows filters the list when picked, one at a time, its chip named after it; a calculated one (win rate, collected) doesn't. KPIs may overlap; they don't add up. The lifecycle, when the page is where people move rows through their statuses (its tasks act on two statuses or more: jobs, vendor orders): All, then the statuses in the lifecycle's order, endings included, one card each, adding up to All. An ending counts the last 30 days and says so; a rare ending (lost or set aside, under a tenth of rows) stays in the Status filter unless a figure needs it (Declined, for win rate). One calculated figure may join the row. Either way: money where the key figure is, the count beside it, any window named; a filter the page opens with is its default view; segments (Top customers, Submitted by vendors) are saved views; a list with no KPI worth showing (the catalog) has no summary.

Why: Products split this in two (research board, 19 Oct): lifecycle rows that show every status, endings included (Stripe, Xero, Deel), and KPI figures that cut across them (Mercury, QuickBooks, Midday). A row of work queues did neither: it dropped endings people need (Paid, Declined) and gave a steady state a card. Tabs were ruled out to keep one summary pattern.

schema check · D17, I8, D66, D67, Research: What earns a summary card (Figma, 19 Oct), Product designer, 19 Oct 2026

At most one main action: “Create <noun>” for records the business makes, “Add <noun>” for records it keeps (customers, items). In the page header from tablet up; floating above the tab bar on phones.

Why: One primary per view (D4); a name that says what you'll get.

check renderer · D4, D29

Selection is on only when the list has bulk actions, and then the bulk bar replaces the page's floating action. On phones selection is a mode (long press, or Select) rather than a checkbox column. When checkboxes show but the actions don't, the actions stay unresolved until someone says (the checker accepts that while the question is open).

Why: A checkbox column costs every row width; on a phone it buys a rare task.

Survey asks when the page doesn't show it: “I can see checkboxes. What can people do to several {nouns} at once, and is any of it destructive?” Default: Leave the bulk actions unresolved and say so; never invent them.

check renderer survey · D17, Tables on phones research, Bulk actions bar research, Product designer, 14 Oct 2026

The bulk bar shows at most three actions (two from 768 to 1099 wide), in the order the description lists them, most important first; the rest go in More. More never holds just one action: if only one would be left over, the third slot goes into More with it. Delete lives at the end of More, in red after a rule; it comes out onto the bar, as the last slot, only when every action fits without a More. A menu (Change status) is one slot. Phones have their own rule: up to two actions, More, then Delete when the selection allows it; one action fewer while a label wouldn't fit its place.

Why: A bar that grows with the list's actions turns into a toolbar; three slots and More is as many as anyone scans. A phone's bar has four places a quarter of the width each, so there the labels decide.

renderer · D36, Bulk actions bar research

Destructive actions (tone danger) come last in any list of actions, after a rule, and always ask first; the confirmation's button is named for the outcome (“Delete 3 jobs”) beside a safe way out, focused first.

Why: Nothing irreversible sits where a hurried thumb lands.

check renderer · D4, Secondary, ghost and danger buttons research

A thing's next step comes from its lifecycle: for each status, the one action that moves it on (Send for a draft, Mark approved while it waits), where there's an obvious one. A per-row button in the original is evidence of one, nothing more. Rows carry no buttons: the step is the record's first action for that status and the first in the row's ··· menu (after Open); everything else a row can do follows it in the record's More and the ··· menu.

Why: Bolster's lists lean on a per-row next step (Pending jobs, Send, Archive). The record, a click away, now does that job: the step stays one click from the row, and the rows stay readable.

Survey asks when the page doesn't show it: “When a {noun} is {status}, what moves it on, if anything?” Default: No next step for a status whose next move isn't plain from the evidence.

schema renderer survey · Dry run on Bolster's lists, Oct 2026, Product designer, 14 Oct 2026: no Next step column; the record replaces it

A record lists, under Related, a link to each record its thing connects to in the model (record fields): the job and the vendor of a vendor order, and the ones reached through them (the job's client). Its kind on the left, its name (and avatar) as the link. They stay out of the record's fields, and actions that only go to one of them (View job) aren't repeated in its menus. Teammates are people on the record (Created by), not related records. The other way round too: what points at the thing (a vendor's vendor orders, its bills, its bid requests, the jobs it worked on, through its orders) is in the model's has, and the record links to each list with its count, None yet when there are none.

Why: A record is where people go from one thing to the next; the things it connects to should be one click away, wherever the source hid them.

check renderer · Product designer, 15 Oct 2026, Product designer, 16 Oct 2026 (subs and vendors)

Every list declares one default sort on a sortable column. One arrow at a time: a second arrow in an original is noise, not a second sort. People change it from the column headers; that's a view state, not a new default.

Why: The order a list opens in is a decision, not an accident of the database.

Survey asks when the page doesn't show it: “Which order should the list open in?” Default: What people look for first, from the page's intent; otherwise the latest activity, newest first, or the main date if there's no activity column.

schema check survey · Product designer, 14 Oct 2026

Each filter is a column, and its picker follows the column's type. The toolbar shows Add filter and the filters that are applied, never empty ones. At most three are pinned (usually status, owner and a date): they come first in Add filter's menu, the rest after them.

Why: A toolbar of empty filters is a form; one Add filter keeps it calm, and pinning puts the filters people reach for most at the top of its menu.

check · List page layout research, Filter value pickers research, Product designer, 14 Oct 2026, Add filter, then chips (concept round 2, 8 Oct 2026)

A list with a date column offers the date range picker on its main date (created, issued, due), even if the original has none: ten presets, then Custom with From and To and two months (D37). Lists without a meaningful date leave it out. Saved views hold a preset id or a span relative to today (..-91 is more than 90 days ago).

Why: “Last 30 days” is the most common question asked of any list.

check survey · List page layout research, Product designer, 14 Oct 2026

Search names its columns, and its placeholder lists them in plain words: “Search by client, job, address or number”.

Why: An empty field that says “Search” leaves people guessing what will match.

schema check · Table rows research, Product designer, 14 Oct 2026

The survey asks whether people need to group the list at all; when they don't, Display settings has no Group by. When they do, it offers the list's status, person and category columns by default. Other groupings can be suggested where values repeat across many rows (a customer or vendor, a city, a trade); never by values that differ on nearly every row (names, numbers, amounts, exact dates).

Why: Grouping helps some lists and not others, so it's asked, not assumed. Status, person and category cover most needs; a suggestion can cover the rest, but a group per row isn't a group.

Survey asks every time: “Do people need to group this list? I'd offer {defaults}; {suggestions} could work too, or something else they sort it into piles by.” Default: Grouping offered by the list's status, person and category columns; the list opens ungrouped.

check survey · Product designer, 14 Oct 2026

“132 jobs”, “Jobs you create show up here”, “Delete 3 jobs?”: every sentence about rows is built from the noun, so no list writes its own.

Why: Consistent copy without anyone writing it.

schema renderer · D28

A figure's explanation names statuses and labels exactly as the screen shows them: {status} for a status, [Label] for any other label.

Why: The note beside the cards can't say “won” when the cards say Booked.

check · D27

Below 768 a row is an item, not a table row: the id and a date top left, the key figure top right, the name across the full width (wrapping to two lines, never cut on the first), then the place or description bottom left and the status bottom right. No checkbox column: selecting is a mode (Select, or a long press).

Why: Our phone rows cut 24 of 25 job names; every source says lead with the name and let it wrap.

renderer · D32, Tables on phones research

The front office reads the source for meaning (L-source): on a live page it explores read-only (its menus, filters, a row's record, the bulk bar, every card) for evidence of what things exist, their lifecycle and actions, and what people need. It asks, rather than guesses, only what that evidence can't settle about meaning: what a column holds, what a status means, what people can do to several at once. Never how the page should look or behave: the system decides that. Seven questions at most in one message, most important first; the rest take their defaults and are listed as assumptions. Contradictions in the evidence (a card count the rows contradict) are always worth a question. A value the builder can't name for sure (a bare number on a line, a column of dashes) is always asked, never guessed.

Why: The live page answers most questions a screenshot leaves open (cut-off cards, menu items, what a click opens), and a confident guess that's wrong costs more than a question.

Survey asks when unclear: “Which of these statuses means the work is won, underway, done or lost?” Default: Read from the status names when they're unambiguous (Paid is done, Declined is lost).

survey · Product designer, 14 Oct 2026: explore pages in Chrome rather than describe screenshots

Headers, statuses, cards, views and buttons are in sentence case: “In progress”, “Past due”, “Create job”. Names of people, companies and products keep their capitals.

Why: The system writes everything in sentence case; Title Case reads as shouting in a dense table.

check · CLAUDE.md