← Back to the screen

Design system portfolio

Design record: Kiln & Co

The four direction lines behind this page, the generator command that produced its tokens, and the pairs it was measured against.

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

  1. The index: nine orders, eight inside the 7-day filter; the strip counts 30 days.
  2. Selection: rows checked, the filter bar replaced in place, with their sum.
  3. The typed confirmation, phrase derived from the targets (#1046 or cancel 3 orders).
  4. Filtered to nothing: Refunded with the 7-day filter on, with a pottery illustration and a Clear filters action.
  5. A name that breaks the column (Theodora Achebe-Lindqvist).
  6. An order page, fulfilled in parts (#1044): two fulfillment cards, payment ledger, timeline, notes, customer, tags.
  7. 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.
  8. Mark as paid, Fulfill items, and the bulk Mark as fulfilled all write the model and report in a banner or toast.
  9. 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:

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

Round four

Round eight (2026-10-29)

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

  1. The money was recomputed from ORDERS to 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.

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.

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."

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.

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).

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.