docs(analytics): /analytics v1 "Ledger" — visual & interaction design package

[martasl00]

The visual and interaction design package for /analytics v1 "Ledger" — the missing half of a spec that says of itself "wireframes are structural, not visual", so that #1986, #1989, #1990 and #1991 can each cite one source instead of re-deciding the same questions apart from one another.

Docs only. One file: docs/plans/mockups/analytics-ledger-2003.html. No application code is touched.

Live version: https://claude.ai/code/artifact/d1e9bc65-197f-408d-aadd-29a77e1dd169

What it contains

17 frames covering the page at 1440, tablet and phone; the loading, recalculating, error and empty states; a fresh instance; the degradation rule; the microcopy contract; and a handover table. Every colour, radius, shadow and spacing value is a token copied from apps/web/src/index.css, and every component is transcribed from an existing primitive in apps/web/src/shared/ui/ with the line range it came from.

Read this part first

The last commit is a design-system audit rather than a design round: the page was re-read against the live index.css instead of against the notes of the round that transcribed it. Two findings would otherwise have reached implementation.

The .status-strip ladder was written against a rule that no longer applies. index.css:6241-6260 already overrides the auto-fit line the earlier rounds argued with, so the measured "three columns plus an orphan at 768px" never described the running app. Worse, the correction would have lost the cascade: a base repeat(3) plus one 768–1023.98 query is beaten by the shipped @media (min-width: 1024px) { repeat(4) } — same specificity, later in the file — giving four columns on the desktop the page is designed for. The rule now restates all three steps under a .status-strip--analytics modifier.

Card edits were unscoped. min-height, the value row's wrap and the strip columns were edited on the bare classes the dashboard at / also renders, while the file claimed the dashboard was untouched. All three are now scoped, so the claim holds in fact rather than only in prose. #1990 should implement this as a page-level modifier on the strip, not as an edit to the primitive.

One defect this surfaced in the app itself

.data-table__cell--right (index.css:2770, specificity 0,1,0) loses to .data-table th, .data-table td { text-align: left } (index.css:2797, 0,1,1) whatever the source order — so every right-aligned column in the product renders left-aligned today: orders, products, sync jobs, connection diagnostics, bulk batch progress and the dashboard, wherever a column declares align: 'right'.

The mockup fixes it locally by qualifying with the type selector, which is the same one-line fix index.css needs. It is deliberately not fixed in this PR — it predates this epic and touches six pages, so it should be its own issue rather than a stray line in a docs change.

Figures the platform cannot produce yet

Six of the twelve figures on the strip are blocked, and so are all six period-over-period deltas. On two cards — Returns & refunds, and Cancellations — both figures are blocked.

Those two cards stay drawn, and that is deliberate. The brief was to choose the figures a seller needs; a figure the platform cannot serve yet is a requirement rather than an omission, and a requirement drawn to scale is what a backend issue can be written against. They carry an explicit state (dashed border, Data order tag, muted figures) so nothing on them is mistaken for a measurement.

Frame 14 turns every one of those markers into a list — figure, what is missing, and the shape of the answer — generated from the same calls that render the markers, so the page and the backlog cannot drift. The register audits the finished page: a marker nobody filed appears as an Unfiled row instead of being dropped.

The useful thing for planning is the asymmetry it makes visible. Everything under placedAt is one column plus an index on data OpenLinker already holds, and it unblocks the range filter, all six deltas and the daily rate at once. Returns and refunds are a different order of magnitude — no entity exists anywhere in the repo, so it is a capture problem before it is a reporting one.

Cost to #1990, stated up front

• KpiCard gains five props (metric, qualifiers, delta, info, planned). All additive; the dashboard strip renders unchanged when they are absent.
• DataTable needs a footer — the Total row and the per-currency subtotals. The component has no footer API today, so this is a component change of the same size as the card's, not a stylesheet addition.
• The "no new primitive" acceptance criterion holds in the sense that matters (no new component), but neither of the above is free.

Closes #2003

🤖 Generated with Claude Code

https://claude.ai/code/session_01KNExZyQ1nVYybNyTSm6YWB

[piotrswierzy]

Tech-lead review — 🔄 Substance approved; two things to record before #1990 starts

Reviewed the single added file (docs/plans/mockups/analytics-ledger-2003.html, 4,865 lines) against docs/frontend-ui-style-guide.md, docs/frontend-architecture.md, apps/web/src/shared/ui/index.ts, apps/web/src/shared/theme/tokens.ts and apps/web/src/index.css at main (648cfc6).

This is the strongest design package I've reviewed in this repo, and the token discipline is real rather than claimed.

Verified

• Token containment holds. All 107 oklch() literals are confined to the transcribed :root / html[data-theme='dark'] block at mock.html:193-397, and the single raw hex (#ffffff, mock.html:201) is a byte-faithful copy of index.css:202. Every rule below the token block reads through var(--…) — top consumers --space-3 ×34, --space-2 ×31, --text-muted ×30, --font-mono ×28. Radii come only from --radius-{xs,sm,md,lg}.
• Accent and status hues obey the reservation rule. Status tones appear only as status-*-soft/border/fg on genuine status surfaces; accent use is limited to the guide's sanctioned list (primary button, segmented-control active fill, KPI top-rule at mock.html:877).
• The odd type sizes vindicate the transcription, not the mockup. .eyebrow: 0.76rem and .data-table-skeleton__table: 0.92rem match index.css:1992 / index.css:3245 exactly, and .page-title: 1.5rem/700 (mock.html:680) correctly records the running app — .page-title carries no font-size in index.css, so h2 inherits the UA 1.5em/bold. The guide's "page title 28 / 600" is what's stale here.
• A11y is designed in, not bolted on. Nine :focus-visible rules all via --shadow-focus; 16 .sr-only usages; aria-live/role="status" on all four transient states; delta colour paired with an aria-hidden arrow and a full sr-only sentence (colour never the only signal); 11 tabular-nums sites. The deliberate Popover-over-Tooltip choice at mock.html:2915 — because Radix Tooltip bails on pointerType === 'touch' — is exactly right for a first-class-mobile surface.
• Responsive parity honoured. Both tables use the real cardView prop below 767.98px rather than the narrower .data-table--stackable, and the only horizontal scroll is inside .data-table__container, a documented exception.
• No new primitives. Every component maps to an existing export in shared/ui/index.ts; the eleven new CSS rules are page-scoped modifiers.
• Finding the .data-table__cell--right specificity defect (0,1,0 vs index.css:2797's 0,1,1) and declining to fix it here is the correct call.

The findings below are pre-implementation questions and one guide-sync obligation — not corrections to the design.

IMPORTANT

1. The style guide isn't updated, and three divergences require it. This PR changes exactly one file. The guide is explicit at frontend-ui-style-guide.md:621 — "Never introduce a row height that isn't on this list without updating the guide first" — and its own precedent for a parity-matrix departure (the picker modal, :652) lives in the guide, not in a mockup. Three items qualify:

• mock.html:874 — .status-strip--analytics .kpi-card { min-height: 9.5rem } (152 px) against the guide's KPI card | auto, ~96 px row (:618).
• mock.html:1233-1246 — the six-card 1 → 2 → 3 ladder against the parity matrix's KPI strip | 1 × 4 → 2 × 2 → 1 × 4 (:645). The reasoning in the comment is sound (six cards can't honour a 4-wide step without an orphan row) and the intent is preserved; it just needs recording where the next author will look.
• mock.html:3076 — the package's own observation that cardView is opt-in while the guide's Tables row (:643) reads as automatic. The mockup literally says "Worth a line in the guide so the next page does not rediscover it." Agreed — write it.

Add a Documented departure — /analytics six-card strip paragraph, the 9.5rem analytics-card height in the Density table, and one clarifying clause on the Tables parity row. Cheapest here, since this is already a docs PR; otherwise make it a named checklist item on #1990. Please don't leave it implicit.

2. The DataTable footer has no card-view answer. The package flags this itself at mock.html:3011: "a footer has no obvious card equivalent, and this mockup does not answer it — both tables carry totals in the desktop table only." Since mobile is first-class, a seller on a phone loses the Total row and the per-currency subtotals entirely. This is the one substantive hole and it should be closed before #1990 starts — a totals summary line above the card stack, or a pinned first card, are both cheap. The same paragraph should state whether the new footer API is DataTable-generic or analytics-local.

3. Two primitive API changes are named but not reflected in the catalog. KpiCard gains metric / qualifiers / delta / info / planned, and DataTable gains a footer (mock.html:2924, :2926, :3011). The guide documents both components' API surfaces (:510 for DataTable), so these belong in the same sync as finding 1.

SUGGESTION

• mock.html:1199 — .kpi-card__qualifier-value: 0.9375rem (15 px) is the one authored size off the canonical scale (:432-440: 11/12/13/14/17/28/32). Use 0.875rem or 1.0625rem. Unlike 0.76rem/0.92rem, this one isn't inherited from index.css.
• mock.html:1031-1033 — frozen-column classes are renamed (.data-table__cell--sticky / --sticky-edge) and the boundary is always-on, while the shipped implementation is .data-table__sticky-col gated behind .data-table--sticky-scrolled (index.css:2833+). The accent-tinted edge itself is the shipped pattern, so this is naming + gating only — but #1990 should use the shipped classes and inherit the gating rather than transcribe these.
• mock.html:553 — @media (max-width: 720px) is off-ladder. It only governs mockup chrome (.gap-legend--card, .build-gaps__row), never a page surface — worth a one-line marker so it can't be copied into app CSS.
• File the .data-table__cell--right specificity issue as an issue now. The analysis is correct and the blast radius (six pages) is real; keeping the fix out of this PR is right, but a defect described only inside a mockup is easy to lose.

Merge readiness: 🔄 Substance is sound and implementable as specified. Merge once finding 2 has an answer recorded in the file and finding 1's guide sync is either committed here or written as an explicit #1990 checklist item; finding 3 and the suggestions can ride along with either.

[piotrswierzy]

Tech-lead re-review — 🔄 Two items unchanged, and the window has narrowed

Head moved 2709429c → bd288978. Diffed against merge-base(origin/main, head) = de7594e7, since the recorded base is stale: 4 files, +5,390, docs only.

The new work is real but orthogonal to my open findings — docs/specs/metrics-analytics-dashboard.md plus .claude/rules/analytics-metrics.md making that spec authoritative over the mockup's popover copies. That's a good addition and it closes a drift channel I hadn't flagged. It's also, as I'll come back to, exactly the mechanism my finding 1 is asking for.

Prior findings

1. Style guide not updated — ❌ not addressed. frontend-ui-style-guide.md is untouched by this PR. On main the Density table still reads KPI card | auto, ~96 px with no analytics entry, against the mockup's 9.5rem (152 px) — and the guide's own instruction at :626 is categorical: "Never introduce a row height that isn't on this list without updating the guide first."

The parity-matrix departure is still declared only inside the mockup. It has been revised since my review — now 3×2 → 2×3 → vertical ("New rule 6" at :3046) with better reasoning, since auto-fit gives six ~200 px columns at 1280 px — but a revised divergence recorded in the wrong file is still recorded in the wrong file. Same for the cardView-is-opt-in observation. The mockup itself still says "Worth a line in the guide so the next page does not rediscover it."

2. DataTable footer has no card-view answer — ❌ not addressed. :3146 is verbatim unchanged. On a surface the guide declares first-class-mobile, a seller on a phone loses the Total row and the per-currency subtotals.

The round-7 rationale added since my review raises the stakes rather than settling them: the file now argues the footer is the evidence — "a table whose claim and proof cannot be seen together fails at the only job it has" (:4143). That is precisely the property mobile currently loses. The document now contains its own strongest argument against its own open question.

3. KpiCard / DataTable API changes not in the catalog — ❌ not addressed. KpiCard appears nowhere in the guide (zero grep hits on main), and the DataTable entry documents no footer. Both still named only in the mockup's handover table.

Suggestions: .kpi-card__qualifier-value: 0.9375rem still the one authored size off the canonical scale; frozen-column classes still renamed and always-on vs the shipped .data-table__sticky-col gated behind .data-table--sticky-scrolled; off-ladder @media (max-width: 720px) still unmarked. The .data-table__cell--right specificity defect — ✅ discharged: #2031 exists, correctly scoped, closed 2026-08-14, and the issue found more than the mockup did (Orders/Products had independently grown --end-suffixed workarounds).

Timing — a correction to what I said last time

I previously said these were "about to be built" by #2115. That's not right: #2115 implements #1986 (the route shell), not #1990 (the KPI strip and tables). So the card height, the six-card ladder and the footer are still ahead of the work that needs them.

That's better than I implied — but it's the next issue, not a distant one. The window to record these is open and narrow.

The pattern you just demonstrated

The metrics spec + .claude/rules pairing is the right shape: name one file canonical, mark the mockup copy explicitly a copy, and state an on-divergence rule ("the spec wins, say so rather than silently picking one"). You've applied it to metric definitions. Finding 1 is the same problem for the visual system, and you've now built the precedent for solving it.

CI: all 8 green on bd288978. mergeable_state: behind — needs a main refresh. Docs-only.

Merge readiness: 🔄 The substance remains the strongest design package in this repo and I'm not asking for design changes. But both open items are open in the same words as five days ago, and one of them is a decision the implementer will otherwise make silently under deadline. Merge once:

1. Finding 2 has an answer recorded in the file — a totals summary above the card stack, a pinned first card, or an explicit "desktop-only, accepted, here's why". Any of the three. What isn't acceptable is shipping #1990 with the question still marked open.
2. Finding 1 is either committed here (three small edits: the analytics row in the Density table, a Documented departure — /analytics six-card strip paragraph, one clause on the Tables parity row) or written as a named checklist item on #1990 — not left implicit in a mockup comment.

Finding 3 and the suggestions can ride with either. Given the metrics-spec precedent, folding the guide sync in here is the cheaper path.