Merchant admin for a studio pottery in Victoria BC: the order index, one order, and a refund that works its own totals out. Three views in one document, reached by hash (#/orders, #/orders/1044, #/orders/1048/refund).
Direction
Archetype: index, extended to index + resource page + calculation. The first cut was a bare list. A merchant admin is judged on what happens when a row is opened, so the list now gives way to the order page, and the order page to a refund. The list still leads in the sense that matters: the first screen (round two) opens the way Shopify's own Home and Analytics do. Net sales is one large figure over a hand-drawn running-total chart (SVG, tokens only, labelled at the line end, one annotation: the 8 Sep collection launch, plus the one August order refunded in full). Paid is the blue, the amber sliver is what is still owed. Beside it a "Needs you" card holds the two jobs, in Polaris's own warning and caution surfaces, each opening its saved view. The table defaults to "Needs you first": the unpaid order, then orders still to ship, then the settled rest, which step back to secondary text. The sidebar's selected item has a start bar, and its count and a "New" mark are badges in badge tones. Arithmetic that must agree: net sales 3,578.54 less 288.96 awaiting payment is 3,289.58 paid; refunding #1048 in full returns 194.88, leaving 3,383.66 net. The picker panel now sets position-try-order: normal, because the hero moved the sort select into the zone where the UA default flipped it upward.
Data stance: one model, nothing typed twice. ORDERS holds integer cents and quantities. The strip, the chart, the saved-view tab counts, every row, the footer, the sidebar count, the order page and the refund all read it. A refund writes to it and every one of those moves. Totals are lines plus shipping plus tax, to the cent: GST 5% plus PST 7% on BC retail, GST only on wholesale and on Alberta. Dates are relative to Thu 11 Sep 2025 in en-CA; money is Intl.NumberFormat('en-CA', CAD) with a true minus for refunds.
Density: Polaris default. 13px body text, 12px cell padding, 32px controls, --p-space-* everywhere else. Below 768px the sidebar becomes a bottom tab bar and the table becomes stacked cards.
The bold thing: a refund is a calculation, not a form. Steppers set how many of each item goes back; tax is worked out per line and per type, exact on the last cent (refunding everything returns exactly what was charged). The button names its amount ("Refund $194.88"). Shipping over what was charged shows an inline error and keeps the button off. After it succeeds the Payment card gains a ledger row and a Net payment line, the badges and timeline change, and the index strip, tabs and row follow.
The selection state from the first cut is kept: checking rows swaps the filter bar for the bulk bar in the same slot (both 32px), and cancelling asks for a typed phrase, with the destructive button absent until it matches.
Generator
polaris_tokens.py --both
The audit that decided the theme:
polaris_tokens.py --contrast --theme light
The states on the page
- The index: nine orders, eight inside the 7-day filter; the strip counts 30 days.
- Selection: rows checked, the filter bar replaced in place, with their sum.
- The typed confirmation, phrase derived from the targets (
#1046orcancel 3 orders). - Filtered to nothing: Refunded with the 7-day filter on, with a pottery illustration and a Clear filters action.
- A name that breaks the column (
Theodora Achebe-Lindqvist). - An order page, fulfilled in parts (#1044): two fulfillment cards, payment ledger, timeline, notes, customer, tags.
- Dirty page: editing the note or a tag raises the contextual save bar (Discard, Save). Leaving with edits asks first in a dialog; Stay returns focus to the title.
- Mark as paid, Fulfill items, and the bulk Mark as fulfilled all write the model and report in a banner or toast.
- The refund page, including its error state and its after state.
Where focus goes
Every bulk action empties the selection, which hides the bar the button was in, so returning focus to the opener drops it on <body>. Focus lands on the banner that reports the outcome instead. After the typed gate it is handed over only once the dialog has actually closed, since focus cannot leave an open modal and closing one restores focus over anything set in the meantime.
The gate itself focuses the dialog, not the phrase field. The count, the targets and the refund total are what the screen is for, and dropping the caret into the input puts every one of them behind the reader.
Light only
Polaris ships one finished theme. In dark-experimental, color-text-brand, color-text-critical, and color-text-success are still the light values on a dark surface: 1.49:1, 1.40:1 and 1.31:1. That is why the theme's name ends in -experimental.
tokens.css applies that theme under @media (prefers-color-scheme: dark) with the guard :root:not([data-theme="light"]). The page pins data-theme="light" on <html> and declares color-scheme: light, which is the generator's own opt-out. A dark-preferring browser therefore gets the theme that passes. This is a recorded deviation from CONTRACT.md section 5.
Measured contrast
Every pair the page leans on, in WCAG 2.2:
--p-color-texton--p-color-bg-surface, the body at 13px: 13.20:1--p-color-text-critical-on-bg-fillon--p-color-bg-fill-critical, the gate's destructive button: 5.81:1--p-color-text-criticalon--p-color-bg-fill, the bulk bar's cancel: 9.46:1--p-color-text-linkon--p-color-bg-surface, the order number: 6.11:1--p-color-text-secondaryon--p-color-bg-surface-secondary, the column headers at 12px: 5.78:1--p-color-texton the four badge tints: 11.16:1 success, 9.68:1 warning, 10.94:1 caution, 9.63:1 critical
APCA disagrees with WCAG at Polaris's 13px body size. That size is the system's published body scale and the contract's bar is WCAG 2.2 AA, so 13px stands.
Warnings kept, with the reason
copy_lintjargon, once per row: "Select order #1048" on the row checkboxes.IndexTablepublishes that accessible name, and CONTRACT.md section 1 gives the system precedence over taste.copy_linttitle-case:Orders ยท Kiln & Co, a proper noun in the<title>.craft_lintno-primary-action: the five saved-view tabs. They are peers in atablist, and weight plus fill distinguish the selected one.craft_lintno-primary-actionmay also name the summary strip and the sidebar sub-items: peer groups, where no one item should be primary.
Round four
- The sales chart was a flat line for three weeks. The store now holds forty-eight orders: #1001 to #1039 (13 Aug to 2 Sep, a little under two a day, more on Saturdays, three trade accounts) are real orders with real rows and order pages, hidden by the "last 7 days" filter and shown when it is taken off. #1040 moved to 3 Sep so order numbers still run in time order. Net sales is $11,242.14 over 48 orders, $10,953.18 paid.
- Counts agree: the footer now counts what the filter and the tab count ("8 orders", "Showing 3 of 8" when a search narrows it, "48 orders" with the date filter off).
- The refund note on the chart reads "#1040 refunded", right-aligned to its step, so it stays inside the plot at 390px.
- The page keeps itself on the light theme: anything that sets another data-theme on the root is put back.
Round eight (2026-10-29)
- Fourth design-note row tinted and rounded. The tint is deliberate (it marks "The one bold decision") and stays. The rounding was not: four rounded corners made it read as a pill dropped into a table. It now runs edge to edge, and only its last-row corners follow the card.
- Filter tabs cut off at "Made to order 2" (390). The five views sat behind a sideways scroll. Under 48rem they wrap onto a second line, so all five show.
- Stray dot above the tab bar (390). Real, and a specificity bug: the sidebar's selected-item start bar is
.nav__item[aria-current]:not(.nav__sub .nav__item)::beforeand the tab bar's top bar was the plainer selector, so the sidebar's offsets and width won and the bar collapsed to a 2px dot 8px left of the tab. The tab bar's rule now carries the same selector and setswidth: auto. - One move: the refund calculation on the first screen. The Net sales card now carries a line from the model's latest refund, "Latest refund, #1040: $132.00 items + $15.00 shipping + $7.35 GST + $10.29 PST = $164.64", with the order number linking to its page. It is the same arithmetic the refund page does, read from
ORDERS, so it moves when a refund is made and hides when there is none. The refund page itself is still reached through an order, as in Shopify.
Round nine (2026-11-09)
Held against Shopify's own Orders index and order detail, and done as the merchant: tabs, search, the "Needs you first" sort, rows selected and a bulk action, an order opened, a refund issued, every popover, dialog and toast open. Then a real-phone emulation at 360 and 390 (coarse pointer, 3x), 200% zoom and
- The money was recomputed from
ORDERSto the cent: $11,242.14 over 48
orders, $164.64 refunded, $288.96 awaiting, $10,953.18 paid, the refund breakdown, every order total against its lines, GST 5% and PST 7% on the same base, every weekday against its date. Nothing was off.
- The stacked table now follows its own width, not the window. At 768 to 860 the sidebar leaves the table about 480px, and the desk layout overflowed sideways. The table wrapper is now a size container and the stacked-card rules are an
@container ordersquery at 43.5rem; a ResizeObserver restores the table roles from the same threshold. A width sweep from 320 to 1920 in 10px steps over five routes finds no horizontal overflow. - Refund total stays reachable on a phone. The total sat below the fold of a long form. A bar above the tab bar now shows the total and a Refund button once the summary card scrolls out of view (an IntersectionObserver at 0.99), and clicks the real button. It hides again when the card is visible.
- Touch targets at the system's own size. Under a coarse pointer, buttons, fields, chips, tabs, steppers, checkboxes, icon buttons and the dismiss cross are 44px (2.75rem), with the stacked-card checkbox column widened to match.
- Bulk bar on a phone. The filter bar no longer sticks together with the bulk bar (they stacked to a third of the screen). Deselect moved beside the count, and the actions are one nowrap row.
- Smaller defects. The select chevron no longer drifts when the list opens (
rotateis applied beforetransform, so the centring now usesmargin-block: auto); the tab focus ring is drawn inside the tab so the tab list's overflow does not clip it; the stacked card's urgency bar is on the first cell, so it no longer collides with the checkbox; the line-item name is plain text, not a link that went nowhere; the "#1040" link in the sales card is a styled link; the "#1040 refunded" chart label has a surface behind it so the $10,000 gridline no longer runs through the words. - "Net sales" is now "Total sales". Shopify's net sales excludes shipping and tax. The figure here ($11,242.14) is lines plus shipping plus both taxes, which Shopify calls total sales. The arithmetic was right; the name was not.
- Not changed. Polaris is light only, so there is no dark pass: the page pins
data-theme="light"and the dark renders match the light ones. The left navigation items other than Orders are still stubs, as in the other rounds.
Round ten (2026-11-09)
A second cold read, as the merchant clearing the day's orders: fulfil, mark paid, refund, cancel, each at 1440, 390 and 360 (coarse pointer, 3x) and 1920, then Undo, Esc and Tab in every dialog. Heuristics 28/40 before, 32/40 after.
- A commit with no way back (severity 3). Fulfil (one order or a selection), Mark as paid and Refund each landed on one press. Now: fulfil carries a "Email a shipping confirmation" checkbox (in the card on the order page, in the dialog for a selection) and ends in a banner with Undo that restores the items and the fulfilment; Mark as paid and Refund ask first in one shared dialog (
#ask) that names the amount, the method and whether the customer is emailed. The refund dialog also says it can't be undone. - Cancel told the merchant the wrong money (severity 3). An unpaid order was listed with its whole total as "Refund total" and the banner said the money was on its way back. Refund is now what was paid less what was already refunded; an unpaid order reads "Not paid", and a selection with nothing paid says no money moves.
- A shipped order could be canceled (severity 3). The banner then said the stock was back in the shop. A selection holding anything that has shipped now opens a blocking dialog listing those orders and pointing to Refund.
- Fulfilling an order the studio is still owed for or has not fired (severity 2). The bulk dialog opens with a warning band naming unpaid and made-to-order orders and the 15 Sep firing; the order card's first line says the payment is pending. The bulk dialog also skips already-fulfilled orders and says so; the old banner counted them as fulfilled.
- Rows did not move after the act (severity 2). "Needs you first" kept fulfilled rows where they were. The list now re-sorts after an act and on return to the index.
- A disabled Refund with no reason (severity 2). The line under the order number now says "Nothing to refund until the payment arrives" or "Fully refunded", and the button is described by it.
- Focus did not return to a fixed button (severity 1).
closeModaltestedoffsetParent, which is null for the fixed phone refund bar. It testsgetClientRects()now. - One fact two ways (severity 1). The Needs you badge said "6 to act on" in markup and "5 orders" once script ran; the markup now says 5.
- The design-notes line for the bold decision mentions the last question.
Inventions, none in the original brief: a shipped (any item fulfilled) order cannot be canceled, only refunded; the shipping confirmation checkbox starts ticked; Undo cannot recall an email; Mark as paid asks the merchant to do it once the money is in their account. The fulfilment line follows the order's shipping method: Canada Post for standard shipping, the freight carrier for wholesale freight, the studio for local delivery (fixed after the first read, which had every order "Handed over at the studio"). Not done: Undo goes with the banner, so it is gone after leaving the page; Mark as paid, Refund and Cancel have no Undo, by design.
Round thirteen (2026-11-10)
Reviewer, round 11 (35/40): "cancelling orders leaves nothing behind and the dark theme is withheld."
- A canceled order vanished (reproduced). Bulk-cancel #1045 and #1046 at 1440: the rows were deleted (8 to 6 visible, 48 to 46 orders), no status, no tab, no Undo. Now the rows stay. Each order carries a Canceled badge in the Fulfillment column, a payment badge that says where the money went (Refunded if it had been paid, Voided if not), and a struck-through total. A new Canceled tab counts them; All keeps them; Unfulfilled, Unpaid, Made to order and Refunded do not. Sales, owed, refunded, the chart and the To fulfill count leave them out, and the sales line says "2 canceled" (check: 11,242.14 - 119.84 - 288.96 = 10,833.34, as before). The order page has a Canceled card, a Voided or Refunded ledger, a timeline line, a disabled Refund that says why, and no Mark as paid. A canceled order cannot be canceled again or fulfilled, and its refund address opens the order. The banner now has Undo, the page's own pattern for undoable acts (the toast here is only for "not part of this preview"); Undo puts every order back and removes the cancel refund line.
- Dark is withheld on purpose, left as is. The "Light only" section above records it with a measured reason: in
dark-experimentalthe brand, critical and success text colours are the light values on a dark surface, 1.49:1, 1.40:1 and 1.31:1, so there is no finished Polaris dark scheme to take from the tokens. The page also says so in its own "Light only" design note. No dark scheme added.
Inventions, none in the brief: Undo is offered only until the merchant leaves the page, and the refund goes out at that moment (the dialog and banner say so; the old "can't be undone" line is replaced); an order canceled before payment is shown as Voided; the dialog and banner say the stock is back in the shop. Not done: a canceled order's items are not modelled as stock counts.
Round fifteen (2026-11-10)
Reviewer, round 14 (34/40): one severity 2 and four severity 1 notes. All five reproduced at 1440 and 390 before editing.
- Sidebar count stale on the order page (severity 2). After refunding #1048 the Orders badge read 5 on the order page and 4 only on the list; the Unfulfilled tab and the Needs you badge were stale the same way.
renderStrip()andrenderTabCounts()only ran with the list.show()now runs both for the order and refund routes too, and the refund confirm runs them before it navigates. Fulfil, undo and cancel already calledrender(); driven at 1440, 390, 360 and 1920: refund 5 to 4, cancel 4 to 3, fulfil 3 to 2, undo 2 to 3, each read on the order page. - Shipping read 9 beside 8.00 in the summary (severity 1). An amount over the limit was clamped in the totals while the field kept the error. An amount that is not allowed is now not counted: the Shipping row reads "Check the amount" at $0.00 and the total drops to match the disabled Refund button. The error and the field are unchanged.
- Cancel confirm hidden until the phrase was typed (severity 1). The button is now always in the footer, disabled, and a line under the field says "Cancel 1 order turns on when you type the phrase." (
aria-describedby). It is hidden once the phrase matches; the polite status line still announces the change. This replaces the older "absent until it matches" decision above. - Sticky refund bar over the tab bar on phones (severity 1). Two bars stacked (about 124px). Under 48rem the refund is a task of its own with a back arrow, so the tab bar is hidden on that route and the total bar takes the bottom edge alone (68px, safe-area padding kept). Tablet and desktop unchanged.
- No chart mark for the #1048 refund (severity 1). The label was limited to orders placed before 8 Sep. Any order refunded in full now gets "#id refunded", so "#1048 refunded" sits above the line end, right-aligned to the plot.
Inventions: the shipping row wording "Check the amount"; the disabled-reason sentence; hiding the phone tab bar on the refund route only. Not done: the Export banner that pushes the page down and the dead nav items (severity 1, left as stubs by design).
Round seventeen (2026-11-10)
Reviewer, round 16 (35/40): one reservation on the refund, two severity 1 notes still open. All three reproduced at 1440 before editing (refund #1048, shipping 9.50 against the 8.00 limit; sidebar Home clicked; vase-only refund then the list).
- A total that was not what was typed (reproduced). With 9.50 in the shipping field and the error showing, the summary dropped shipping to $0.00 and showed a total, so the reader saw a figure that matched neither the field nor the order. The field still keeps exactly what was typed (9.50, abc) and its inline error. The summary no longer shows a figure while the shipping amount is not valid: Items still shows what the quantities make, Shipping, GST and PST show a dash (tax follows shipping), the Refund total is a dash in secondary text, and a critical line under it says "The refund total waits on a valid shipping amount." Refund stays disabled, and so does the phone total bar, which reads "Waits on shipping amount" over a dash. The moment the field is valid the figures come back ($152.32 at 8.00, $151.77 at 7.50).
refundFiguresreturnswaiting; the confirm handler also refuses it. - Nav items that only toasted (severity 1). Nine items (Home, Drafts, Abandoned checkouts, Products, Customers, Discounts, Marketing, Analytics, Settings) were buttons answering "X isn't part of this preview." They are now plain items with
aria-disabled="true", drawn in the disabled text and icon tokens, no hover, no pointer, no click handler, no toast. Orders is the one destination, as before. None of them could go somewhere real within the page without inventing a section, so they are drawn as not available. - No chart mark for the #1048 refund (severity 1, reproduced for a partial refund). Only an order refunded in full was labelled. Any order with money returned is now labelled in the same plain-text grammar, above the line at its refund: "#1048 refunded" for a full refund, "#1048 partially refunded" (the badge's own words) for a part. #1040 is unchanged.
Refund arithmetic rechecked after the change: vase-only refund 128.00 + 8.00 shipping + 6.80 GST + 9.52 PST = 152.32; the mug after it 38.00 + 1.90 + 2.66 = 42.56; together 194.88, the order total, so the chart label turns to "refunded". The list strip after the vase refund reads 11,089.82 total sales (11,242.14 less 152.32), 316.96 refunded (164.64 for #1040 plus 152.32) and 10,800.86 paid (10,953.18 less 152.32).
Inventions, none in the brief: the dash as the "not yet known" figure; the wording "The refund total waits on a valid shipping amount." and "Waits on shipping amount"; "partially refunded" as a chart label; disabled nav as the answer to the stubs. Not done: the Create order button still answers with a toast ("Draft orders aren't part of this preview."); it is not a nav item and was not in this round.