source: .forge/design/ui/design-system.md · generated — edit the markdown, not this file

Empire Teas CRM — Design System Specification

Status: reviewed — authored 2026-08-18 (Tharinda, with Claude) from the client-approved prototype; reviewed and accepted by Tharinda (lead) 2026-08-21, standing in for the planned Dinil review so Foundation slice 3 is not gated on it. FS-3 may proceed against this spec. Source of truth: this spec + the current prototype at .forge/design/prototypes/crm-current/ (open crm-prototype.dc.html; the original the client approved is frozen at crm/ — Rev 92). Where the two disagree, this spec wins (per .claude/rules/plans.md § UI / Design Adherence). Consumed by: Foundation slice 3 (design-system primitives — the tokens, atoms and FieldRenderer registry in src/ui; the package split was collapsed to one src/{app,features,ui,lib} package by FS-14), every UI-shipping WI plan’s ## UI / Design Adherence section, and the capture app’s visual alignment. Caveat R-03: domain content in the prototype (grade lists, stage names, thresholds) is Altrium’s design, not client-confirmed data. This spec covers the visual system, which the client approved by approving the original prototype’s look (prototypes/crm/); the current prototype draws the same design in the revamped look this spec has since adopted (Rev 92).

Revised since acceptance — see the Revisions section at the end of this document.

One look per pattern, across the whole product. Every element this spec names a pattern for (a selected row, a hover fill, a list row, a card, a badge, a dialog, a button, a page header) is built with that pattern’s values, and the same as its instances already on main. Before building one, find those instances (git grep the pattern’s tokens or selector, such as accent-gold-deep with data-selected) and copy their values. A screen never takes its own variant. When a pattern has to change, even for one screen, the change is a revision here, decided by the lead, and the same PR changes every instance of the pattern. A test that binds the pattern binds every instance (forge-et-fe src/features/email/mailboxTokens.test.ts, Rev 91). Why: each screen that took its own variant had to be reworked after it was built (Rev 84, Rev 91; .forge/lessons.md L-254).

The prototype’s ad-hoc values — over a hundred hex colours, and a spread of sizes, radii and durations that never settled — collapse into the semantic token set below. Components consume tokens, never raw values: not hex, and equally not a hand-picked 14px or r9. The Empire theme supplies the values through the swappable theme layer (architecture, Foundation slice 3), which is what keeps src/ui reusable and the tea app re-skinnable.

The token families are surface/ · border/ · text/ · accent/ · tone/ · brand/ (§2, colour) · type/ (§3) · radius/ · space/ · layout/ · shadow/ · motion/ · icon/ · focus/ · z/ (§4) · bp/ (§9). In every one of them the names are the contract — §9 fixes how each name is written in code.


1. Brand foundations

Element Value Usage
Typeface Inter (variable, weights 400–700) — one face at every level (Rev 18) Everything: page titles, the login headline, body, controls, tables, labels. A single sans-serif system — the modern internal-tool norm; the Fraunces serif was dropped
Logo assets/empire-logo.webp + wordmark “Empire Teas” (Inter 600) over “SALES CRM” eyebrow (gold, letter-spaced) Sidebar header and login panel
Brand moment Login split-screen: radial gradient #3E2618 → #2A5223 → #234B23, cream text #F6F4EC, gold eyebrow, Inter 24px headline (type/display) Login only — the deep-green gradient is reserved for entry/brand surfaces, never in-app chrome
Font delivery Self-hosted woff2 (one face, Inter), subset latin The prototype loads from Google Fonts CDN; the product must not depend on a third-party CDN at runtime

2. Semantic color tokens

Values are the Empire (light) theme, extracted from the approved prototype. The token names are the contract src/ui components are written against.

Surfaces & chrome

Token Value Notes
surface/canvas #F4EEE2 App background (warm cream)
surface/card #FFFFFF Default panel/card (with border/card)
surface/card-warm #FCFAF4 Secondary card, quiet blocks
surface/inset #F7F1E6 Inset wells, code-like blocks
surface/sidebar linear-gradient(165deg, #FFFFFF 0%, #F1E4CE 100%) Sidebar only
surface/topbar rgba(245,238,226,.88) + backdrop-filter: blur(8px) Sticky top bar, layout/topbar-height
surface/field #FDFCF8 Input and control fill (the alternative to plain surface/card)
surface/hover rgba(94,58,30,.10) Transient hover wash on menu items and rows. A table row hovers in surface/card-warm instead (§5 Table), and so do the inbox’s message rows (Rev 56). Absorbs the prototype’s .07 / .10 / .13 — three alphas inside six points, which was drift. Distinct from tone/neutral’s persistent .12 badge fill
surface/scrollbar thumb #CDD6C1 · hover #B6C3A6 Scrollbar chrome, 11px, radius/sm, transparent track
surface/disabled #E4E4E0 The disabled fill of a button, a field (Input, Select, Combobox) and an unchecked checkbox or radio box, and a disabled button’s border too (Rev 34). A neutral grey with none of the palette’s cream or brown, so a disabled control never reads as a secondary button or an ordinary field: 1.27 : 1 from surface/card, 1.10 : 1 from surface/canvas, 1.13 : 1 from surface/inset
border/card #E7E3D7 Panels, dividers
border/control #E0DCCE Inputs, secondary buttons
border/frame #E5D9C6 Sidebar/topbar edges, dropdown borders. Single value: the prototype’s #E6D9C4 appears once against #E5D9C6’s four, so the outlier resolves to the majority
border/row #ECE9DE Table row separators

Text

Token Value Contrast on surface/card Rule
text/primary #2C2117 15.7 : 1 Default body
text/heading #3A1E13 15.3 : 1 Page-level headings (Inter, like everything)
text/strong #5C4C39 8.2 : 1 Emphasised secondary, secondary-button labels
text/secondary #6E5F4E 6.2 : 1 Supporting copy
text/muted #8C7B66 4.1 : 1 (AA-large only) ≥ 18.66px bold or ≥ 24px only (WCAG’s large text is 14pt bold or 18pt, Rev 132); never for body-size meaning-bearing copy
text/faint #A8987F 2.8 : 1 (fails AA) Decorative only — uppercase eyebrows ≥ 10px 600 with letter-spacing, placeholder glyphs. Never for content a user must read
text/disabled #66625A 6.1 : 1 (4.76 : 1 on surface/disabled) The text of a disabled button or field, on surface/disabled only (Rev 34)

Accent & tones

Token Value(s) Usage
accent/gold bg #C8923A, text-on #3A1E13 (5.6 : 1) Primary actions, active states, the alert nav badge, avatar
accent/gold-deep #8A5A12 (5.9 : 1 on white) Gold-outline button text, gold links, the selected indicator and gold text on light surfaces (nav glyph, edge and eyebrow — Rev 30)
tone/positive text #2C5F2D · bg #F4F8EC · border #D5E2C2 Success, done, in-good-standing
tone/ai text #2E5103 · bg #DCE8CF Reserved for AI provenance (see §5, AI chip) — do not reuse for generic success
tone/danger text/bg #B23A2E (5.9 : 1 on white) · tint #FCF5F2 · border #F0DAD2 Errors, overdue, destructive confirms
tone/notice text #5C4A14 · bg #FBF8EE · border #ECE0BE Price-validity banners, gentle warnings
tone/warning-text #A07D18 (3.9 : 1) Large/bold contexts only
tone/neutral bg rgba(94,58,30,.12) · text #685641 (≥ 4.6 : 1 on its own fill over every light surface, sidebar included — Rev 31) Counts, quiet badges
brand/deep-green #234B23 / #2A5223 Login gradient, toast (#2E5103 bg + #EDF1E4 text, 8.0 : 1)

There is no tone/info, deliberately. The Badge spec once listed an info variant that §2 never defined. It is dropped rather than invented: the palette is warm by design — cream, gold, green, brown, red — and an info tone means blue, which would be the only cool hue in the app and a new colour in a look the client has approved. Measured, the prototype contains exactly two cool colours, and both are third-party brand marks rather than a tone (see below). Informational badges use tone/neutral when they are merely factual and tone/notice when they want attention; nothing needed a third option.

The only literal colour outside this table is the Microsoft OAuth provider mark on the login screen — #00A4EF (AD #28: Microsoft is the sole login path; the Google mark #4285F4 retired with the dropped provider — Rev 10). Third-party brand colours must stay exact, so they are not tokenised and not theme-swappable; they are the one legitimate exception to the no-raw-hex rule, alongside §1’s brand foundations.

Accessibility floor (build rule): every text/background pair ships at WCAG AA for its rendered size. The two prototype tokens that fail at body size (text/muted, text/faint) are size/weight-restricted as above — the frontend-reviewer agent checks this.

Colour is never the only channel (build rule). project-prd.md § Accessibility requires that “status must not rely on color alone; age/priority/severity/rotting dots carry text labels too”, and test-strategy.md § Accessibility makes it a T1 obligation. So no state anywhere in the app is communicated by a tone alone — every one pairs its colour with a visible text label, and the dot shape varies too (for hot / cold, the glyph — Rev 107). The component that enforces this is Status indicator (§5); the tones above supply its colour and nothing more. A red dot with no words is a defect, not a style choice.

3. Typography scale

Token family type/*. One token resolves a whole level — face, size, weight, line-height and tracking — so a component asks for type/body, never for 14px. Same contract as §2: the names are what components are written against.

Six sizes (Rev 109): 12, 14, 16, 18, 20 and 24px. Every level takes one of them, in the CRM and the capture app alike, and no font size outside this set is used. Where two levels share a size, weight, casing and tracking tell them apart. The Before Rev 109 column gives each level’s earlier size, which was consolidated from the prototype’s measured sizes at FS-3.

Token Face Size Weight Line-height Tracking Before Rev 109 Used for
type/display Inter 24px 600 1.12 −.015em 40px Login headline only
type/title Inter 24px 600 1.25 −.01em 22px Screen headers
type/stat Inter 20px 600 1.2 — 20px KPI / stat-card values (§6)
type/subhead Inter 18px 600 1.3 — 17px Sub-headings, large emphasis
type/section Inter 16px 600 1.35 — 15px Panel headers
type/card-title Inter 14px 600 1.4 — 14px Card headings, table emphasis, large buttons
type/body Inter 14px 450 1.5 — 13px The app’s working size
type/button Inter 14px 600 1.4 — 13px Button labels at md — lg takes type/card-title, sm takes type/meta’s size (§5); any compact 600-weight label
type/secondary Inter 12px 400 1.45 — 12.5px Supporting text, table cells, menu items
type/meta Inter 12px 500 1.35 — 11.5px Timestamps, counts, small buttons
type/micro Inter 12px 600 1.3 .5px 10.5px Eyebrows — UPPERCASE; column headers and badges take §9’s casing with no transform (Rev 90), text/secondary or a tone color (12px is normal size for WCAG, so never text/muted, §2)

The dashboard’s large figures (24–30px in the original prototype) have no level of their own: every use is on a surface §8 lists as still to design (open item 2), so anything shipping before then takes type/title, which is 24px, the top of the scale.

Some levels are new, because §5 and §6 specify roles the old range table had no entry for: type/stat (the KPI value, §6’s “20–22px/600”), type/subhead, and — added at FS-3 (Rev 8) — type/button, the 600-weight label level §5’s buttons and §6’s Kanban column header both need and which no size-matched token carried. Without them those components had no token at all.

Line-heights are proposed, not measured. The prototype sets one explicitly (the login headline at 1.12); the rest are inferred and are the part of this table most worth checking on screen.

Weights: 600 is the emphasis weight everywhere; 700 only for tiny high-salience marks (alert badge, ✓). Numeric tables use font-variant-numeric: tabular-nums.

type/* is typography; text/* in §2 is colour. A form field’s label is type/meta and text/primary (Rev 107) — two tokens, two families, no overlap.

4. Shape, space, elevation, motion

Five more token families — radius/*, space/*, layout/*, shadow/*, motion/* — plus icon and focus geometry. The rule from §2 and §3 holds throughout: components reference the token, never the number. As in §3, the values are consolidated from the prototype’s measured distribution and are proposed pending an on-screen check at FS-3.

Radius — radius/*

The prototype declares 14 distinct radii. Consolidated to five steps, chosen so nothing moves far:

Token Value Absorbs (measured uses) Used for
radius/xs 6px 4–7 (×35) Chips, dots, small marks; the corners of every gold-bar selected row and its hover (§5 Selected, Rev 91)
radius/sm 9px 8–10 (×183) Default control — buttons, inputs, mini-cards
radius/md 12px 11–12 (×43) Dropdown menus, combobox/search popovers, toasts
radius/lg 16px 14–16 (×52) Cards, panels, modals
radius/xl 20px 18–20 (×48) Large surfaces, the deal drawer
radius/pill 999px 999 Pills, filter toggles
radius/circle 50% — Avatars

Nothing moves by more than 2px — measured, not assumed. radius/xl exists because 18px and 20px are used 48 times between them, more often than 12px; dropping them, as a tighter four-step scale would, is a visible change to a client-approved surface and is not proposed here.

Space — space/*

The prototype is not on a 4px grid, and this scale does not pretend it is. Its two commonest gaps are 9px and 10px, and 18px is its commonest card padding — a strict 4px grid would move roughly 300 declarations by 1–2px. This scale hugs the measured values instead:

Token Value Absorbs (measured uses) Typical use
space/1 2px 1–3 (×47) Badge and chip padding
space/2 4px 4–5 (×27) Tight inline gaps
space/3 6px 6–7 (×61) Icon-to-label
space/4 9px 8–10 (×172) The default gap
space/5 12px 11–13 (×87) Group separation
space/6 18px 14–18 (×85) Card padding
space/7 24px 20–26 (×56) Content gutter
space/8 32px 28+ (×12) Section separation

Defaults: card padding space/6 · content gutter space/7 · common control gap space/4 · tight inline gap space/2.

A pure 4px grid is available as a deliberate tidy-up at FS-3. It would read better for the screens still to be designed (Tea Room, Executive, admin) at the cost of a 1–2px shift across most of the existing layout. That is a design call for the lead, not a silent normalisation, so this scale stays faithful to the approved look until someone chooses otherwise. space/1 at 2px is load-bearing either way: §5’s badge padding is 1–3px, and a 4px floor would visibly grow every badge.

Layout — layout/*

Fixed frame and control dimensions, referenced by the §5 controls and the §6 app frame.

Token Value Notes
layout/topbar-height 64px Sticky, translucent (surface/topbar)
layout/sidebar-width 248px Expanded
layout/sidebar-width-collapsed 76px Icon-only
layout/list-pane-width 360px The two-pane list column; collapsed from 340–380
layout/list-region-block 24rem The list pane’s data region’s minimum height while it holds rows: a taller header grows the pane and the page scrolls, so a few rows stay reachable; a state without rows keeps its own height (BUG-145)
layout/control-h 44px Form inputs and primary controls
layout/control-h-search 40px Search field (38px left icon-pad)
layout/control-h-compact 36px Dense table and toolbar controls
layout/tooltip-max 28ch Tooltip’s maximum width
layout/menu-max 40ch Dropdown menu’s maximum width
layout/listbox-max 52ch Combobox list’s maximum width
layout/listbox-max-block 40vh Combobox list’s maximum height
layout/form-width 58ch (Rev 90) Retired as a modal width — a modal takes one of the layout/dialog-* sizes. Until Rev 90 it was the width of a single-column form in a modal (the create-role form); the PR that moves the modals over removes it if nothing else uses it
layout/dialog-sm 420px (Rev 90) The §5 Modal’s sm size: a confirmation. Added to tokens.css by the PR that moves the modals over
layout/dialog-md 560px (Rev 90) The §5 Modal’s md size: a one-column form of up to about five fields
layout/dialog-lg 800px (Rev 90) The §5 Modal’s lg size: a longer or two-column form, the compose window, a table, the role and template editors
layout/toast-max 60ch Toast’s maximum width
layout/dialog-max 80ch Modal’s maximum width. (Rev 74) The §5 Modal now takes form (layout/form-width) or wide (two layout/list-pane-widths) instead; this token still caps the shadcn dialogs that set their own width (Attach contact, the notes, price-email and Settings dialogs, the alert dialog) and the account briefing’s line length; (Rev 82) New template left the list when it moved onto RecordEditDialog; (Rev 90) every modal takes a layout/dialog-* size instead, and this token is left capping only the account briefing’s line length
layout/login-card 25rem The sign-in card’s width
layout/message-max 34rem The not-found, failure and route-error cards’ maximum width
layout/skeleton-block 12rem The route skeleton’s minimum height
layout/capture-column-max 480px Capture app only — the centred column’s maximum width from bp/tablet up, gutter included (§9 The capture app). Declared as --et-layout-capture-column-max in forge-et-pwa/src/ui/styles/capture.css, not in the shared tokens.css

The three control heights come from §5’s Input row, which stated them as bare pixels — the one place a component spec named a dimension the token layer could not express.

Elevation — shadow/*

Shadow hue is green-black rgba(30,43,30, α) — never pure black.

Token Value
shadow/card 0 1px 2px rgba(30,43,30,.04)
shadow/menu 0 12px 34px rgba(30,43,30,.20)
shadow/modal 0 20px 60px rgba(30,43,30,.30)
shadow/toast 0 8px 30px rgba(30,43,30,.28)
shadow/button-hover 0 6px 16px rgba(200,146,58,.35) — gold-tinted; the one deliberate exception to the green-black rule

Motion — motion/*

Token Value Used for
motion/fast 150ms Hover, focus, colour transitions
motion/sidebar 180ms Sidebar width
motion/base 200ms fadeUp content entry (6px rise)
motion/slow 250ms toastIn
motion/ease ease The single easing curve — no per-component curves

prefers-reduced-motion is mandated (absent from the prototype): under the query every duration above resolves to 0ms and transforms are dropped.

Layering — z/*

The prototype uses nine ad-hoc z-index values (5, 25, 30, 40, 45, 50, 60, 5000, 9999). Five named steps replace them. No component sets a raw z-index — an unnamed value is how a dropdown ends up behind a sticky header six months from now, with no way to reason about the fix.

Token Value Layer
z/base 0 Page content
z/sticky 100 Sticky table header, pinned first column, the bulk-action bar
z/chrome 200 Sidebar and topbar
z/overlay 300 The tablet sidebar drawer and its scrim
z/menu 400 Dropdown menus, combobox popovers, tooltips

Modals and toasts are deliberately absent from the scale. Native-first (§5) means a modal is <dialog> opened with showModal(), and a toast is a [popover] — both render in the browser’s top layer, which sits above every z-index no matter its value. Within the top layer, DOM order decides what paints on top, so the toast container is mounted after the dialog root. This is the main practical reason to prefer the native elements: the perennial “my modal is behind something” bug cannot occur, because the modal is not competing on z-index at all. A menu or tooltip opened inside a dialog must also use [popover], or it is trapped beneath its own dialog.

Under AD #39 (Rev 41) the CRM’s shadcn components do not use the top layer: shadcn’s Dialog, Select list, Popover, Tooltip and Sonner toasts render in a portal at the end of <body> and stack by z-index. So they take this scale: the Select list and tooltips are on z/menu (the adapted components in src/ui/shadcn), and a shadcn Dialog with its scrim goes on z/overlay, with menus inside it on z/menu. Radix keeps the rest of the page inert while a Dialog is open by its own focus trap, not by showModal(), so the two rules below are re-checked when the first shadcn Dialog and toast are built. The paragraph above holds for the in-house components.

Painting above an open modal is not the same as being usable above it — and mount order does not buy the second. showModal() makes everything outside the dialog’s subtree inert, and inertness is decided by subtree membership, not by top-layer order. So a toast mounted after the dialog root renders correctly above the scrim and is still completely inert: measured in Chromium at FS-3, elementFromPoint at its Dismiss button returned the DIALOG, and dismiss.focus() did nothing; both recovered the moment the modal closed. A popover that is a DOM descendant of the dialog — the dropdown menu inside a modal — is fully operable, measured in the same pass. Two rules follow. A toast raised over an open modal is informational only and must be allowed to expire; never give it duration={null} there, or it becomes a toast nobody can dismiss. A control that must be usable above a modal has to live inside that dialog’s subtree — which means a toast viewport hosted in the topmost open dialog, orchestration no primitive can supply. (Corrected at FS-3; the earlier text named mount order as the mechanism, which is true of paint and false of interaction. Finding F-023.)

Icons, focus, borders, scrollbars

  • Icon library: lucide-react (adopted 2026-08-25). It matches the stated language almost exactly — 24×24 grid, round caps and joins, currentColor — with icon/stroke 1.75 and icon/stroke-bold 2.25 set explicitly, overriding its default of 2. Sizes are icon/sm 16px and icon/md 18px. (Rev 110) The sidebar’s navigation glyphs are one step larger, 20px (icon/md plus space/1), set in Sidebar.module.css alone; icon/md stays 18px everywhere else (§6 App frame). Import named icons only (import { Search } from 'lucide-react'), never the barrel, or the whole set ships in the bundle. ISC licence. The capture app uses the same library, so the two apps stay consistent and open item 5’s retheme gets cheaper.
    • This replaces the prototype’s hand-drawn icons, whose geometry is inconsistent anyway — measured viewBoxes of 23, 24, 48 and 400 mixed together, and eight stroke widths from 1 to 2.3. Icons are the least brand-critical element, so the consistency is worth more than the exact glyphs.
    • Keep a named registry — one module mapping a concept to its glyph (icon.account, icon.rotting, icon.attachment), so two features cannot pick different icons for the same idea. Features import from the registry, not from lucide-react directly. (Rev 110) The registry has no cancel concept, because a button that backs out takes no icon (§5 Button — leading icon); Create Draft Prices and Replace and Create on the Pricing import use draftPrices (lucide FilePen), where they used add.
  • Focus (mandated deviation — the prototype has no focus styles): focus/ring-width 2px · focus/ring-offset 2px · focus/ring-color = accent/gold-deep (Rev 31; ≥ 3 : 1 on every light surface a control sits on). Every interactive element shows it on :focus-visible. On a dark surface (the toast) a control draws the surface’s paired text colour instead. A heading or <main> that script focuses after a page change (tabindex="-1") is a reading position, not a control, and draws no ring. A disabled-but-focusable control (aria-disabled, §9) draws the full ring: its disabled look uses muted colours, not element opacity (§5’s Disabled row).
  • Borders are 1px everywhere — there is no width scale, only the §2 colour families (border/card, border/control, border/frame, border/row).
  • Scrollbars: 11px, surface/scrollbar thumb and its hover, transparent track, radius/sm.

5. Core components (src/ui)

Superseded in the CRM by AD #39 (Rev 41): shadcn/ui first. New and changed screens in forge-et-fe use the shadcn components in src/ui/shadcn — Radix UI behaviour, styled on the §2–§4 tokens — adapted to the rules in this section; the paragraph below still describes the in-house src/ui components on screens not yet moved over (.forge/design/ui/shadcn-backfill.md, and for the capture app, which follows by AD #43 (Rev 149), .forge/design/ui/pwa-shadcn.md). The revamped colour layer (Rev 41) now applies to every CRM route except sign-in (Rev 74): each route in forge-et-fe src/app/router.tsx names theme: 'revamp', so the colours no longer change between screens; Rev 41’s route-by-route opt-in describes how it was introduced.

Build posture: native-first (decided 2026-08-25). Where a native HTML element exists and is good, it is the component — <input type="date"> (which the prototype already uses), <select>, <dialog>, real <button>. Native elements arrive keyboard-operable and screen-reader-correct, which is the cheapest way to hold a WCAG 2.1 AA commitment. A headless primitive library is taken only for the two things native cannot do — combobox/typeahead and tooltip — and it supplies behaviour only; every pixel comes from the §2–§4 tokens. Accepted trade-off: native date and select controls render slightly differently across browsers. Confirm the specific library at FS-3 alongside open item 3.

Build posture: layout-first alignment (decided 2026-09-22, from BUG-010). Alignment is done with the layout primitives — flexbox / grid, gap, align-items, and text-box-trim for text beside an icon — never with a pixel nudge added to correct how something looks (transform: translateY/translateX, a negative margin, a position offset). A nudge that fights the box the layout produced is a symptom, not a fix: it is brittle, it chases a sub-pixel target no clean value hits, and it re-breaks when the type scale or the content changes. This holds even when the nudge is token-derived — calc(var(--et-space-1) / 2) is still a magic offset, so “it uses a token” does not exempt it. The legitimate uses of transform / negative margins are designed effects (a hover lift, a toggle-thumb travel, a drawer slide, a documented border overlap), not alignment corrections. For the common “text sits above/below its icon” case, text-box-trim: trim-both; text-box-edge: cap alphabetic (under an @supports guard, so non-supporting browsers keep plain centring) trims the font’s leading so align-items: center centres the letters themselves — the standard fix, no magic value. See BUG-010 in .forge/bugs.md.

Component Spec
Button / primary accent/gold bg, its text-on, no border. Label: md (default) type/button, lg type/card-title — 14px/600. sm takes type/meta’s size, 12px, at type/button’s weight, because type/meta itself is weight 500. Radius: sm + md radius/sm, lg radius/md (login). Hover: slight lift + shadow/button-hover
Button / secondary White bg, border/control, text/strong label at type/button, radius/sm
Button / positive tone/positive tint bg + border + text (“Mark done”, “Request sample”)
Button / danger tone/danger solid bg, white text — destructive/urgent only
Button / danger-outline White (surface/card) bg, tone/danger border and text, the secondary family’s sizes and states (hover, pressed, focus, the one disabled grey, busy) — the trigger of a destructive action (Deactivate, Delete, Disconnect, Archive, Withdraw), so it reads as destructive before it is pressed while the solid danger confirm it opens stays the loudest control (Rev 75). In the CRM’s shadcn Button it is the destructive-outline variant (outline’s fill, border, shadow and sizes in destructive, a 10% destructive wash on hover); a destructive row-menu item takes the menu item’s destructive variant (danger text)
Button / gold-outline White bg, accent/gold border, accent/gold-deep text — refresh/renew actions
Button / ghost-icon White, border/control, radius/sm — close (✕), toolbar icons. Icon-only buttons carry aria-label
Button — leading icon (Rev 100) Every button with a text label carries a leading icon, in every variant and size above and wherever it sits: a page or record header, a data bar, a card, the §6 Save bar, and a modal’s footer (Cancel and the main action included (Rev 110) the main action included). The icon comes from the concept registry (§4, lucide-react at icon/stroke 1.75), sits before the label with the button’s gap, takes the label’s colour, and is aria-hidden: the label names the button. One concept means one icon across the CRM (Save is always the same glyph~~, Cancel always the same~~), so a concept the registry lacks is added to it, never imported straight from lucide-react. While busy the spinner takes the icon’s place (the Busy / loading row), so the button keeps its width. Not covered: a link inside a sentence, a menu item, a tab, a select’s trigger and the values in it, and an icon-only button, which already is one; (Rev 114) and a toast’s own buttons (Undo, Dismiss). (Rev 110) A button that backs out takes no icon: Cancel, and the safe answer in a question — Stay, Keep, Keep It, Keep Editing, Keep Writing, Keep Checking — is text only, in a modal’s footer, a confirmation (ConfirmDialog, shadcn’s AlertDialogCancel) and anywhere else; Rev 103’s use of cancel for them is withdrawn. The corner ✕ (close) and Clear Filters / Clear Search keep their icons
Section settings affordance How a section’s screen reaches its settings sub-view (Rev 25). An outline Button with the settings icon and words naming the destination (“Mailbox settings”) (Rev 85; a ghost-icon button before it), in the same style as the Refresh beside it; the words are its accessible name, with no aria-label over them (L-211), placed in the screen header as the first of the screen’s actions, at the title row’s right end (Rev 84; Rev 25 placed it beside the title), so the primary action stays last — not in the sidebar, not as a bare text link. It navigates to the sub-view (a real <button> driving the router, so tests address it as role: 'button' by name). Rendered only when the sub-view shows something the current screen does not: on /email it is present for a connection in ACTIVE or RECONNECT_REQUIRED and absent with no connection, while loading, and after a failed read, where the sub-view would show the same card or fail the same way (BUG-015, BUG-020). First built by F20-b on /email → /email/mailbox. A section may carry more than one (Rev 59): each is its own ghost-icon button with its own icon concept and accessible name, side by side at the start of the actions, and each follows the rendering rule for its own sub-view. On /email the second is Email templates → /email/templates (F20-d), shown to every email.manage holder in every connection state, loading and a failed read included, because the templates page does not depend on the mailbox. (Rev 70, Rev 71: the templates move to Settings, at /settings/email-templates on settings.manage, and this button goes — forge-et-fe#337; /email keeps the one Mailbox settings affordance.)
Input layout/control-h (forms) / layout/control-h-search (search, 38px left icon-pad) / layout/control-h-compact (dense), radius/sm, border/control, bg surface/field or surface/card, type/body text
Textarea The Input row’s multi-line member (Rev 38): a native <textarea> inside a Field, radius/sm, border/control, bg surface/field, type/body text, padded space/3 × space/4, at least layout/control-h tall; five rows by default, resizable vertically only, so it never widens its column. Takes Input’s states (hover, focus, invalid, the Rev 34 disabled grey) and its disabled mechanism — aria-disabled plus readOnly, never the bare attribute. For text a person pastes or writes over several lines: the lead inquiry (F11-b), notes, F12’s paste box
Rich-text body (Rev 53, confirmed by Rev 62) The Textarea row’s member for formatted text (F20-c’s email body, F20-d’s template body). The editable area takes the Textarea row’s surface and states — surface/field, border/control, radius/sm, type/body, padded space/3 × space/4, invalid in the danger tone, read-only in the disabled grey — at least five lines of body text tall, growing with the text to a maximum and then scrolling inside itself, so the form’s footer stays in reach. It is a contenteditable with role="textbox" and aria-multiline="true", named by its Field’s label through aria-labelledby (a <label for> does not label it) and described by the field’s message. Above it, a toolbar row on shadcn (Rev 62): a group named Formatting of shadcn ghost icon buttons — bold, italic, bulleted list, numbered list, link — each with aria-label and aria-pressed for the format at the selection, aria-disabled while read-only; after the group, a feature’s actions on the body (F20-d’s Insert merge field and Insert template, between the subject and the editable in the Tab order), then a feature’s place (F20-c’s aiDraft); the row wraps. Shortcuts: Ctrl/⌘+B, Ctrl/⌘+I, Ctrl/⌘+U, Ctrl/⌘+Shift+7/8 for the lists, Ctrl/⌘+K for a link. A link is edited in an inline row under the toolbar (Link address Field with a shadcn Input + shadcn outline Apply + Remove link), never window.prompt; Escape there closes the row, not the dialog. A second full-width panel row under the toolbar holds what an action opens (a pick list, a question, a notice), outside the Body field’s wiring, so its controls keep their own names. Text an action inserts goes in at the cursor, the editor keeping its last selection while blurred. Pasted or pre-filled formatting keeps only the email allow-list (paragraphs, line breaks, bold, italic, underline, the two lists, http/https/mailto links); anything else keeps its text and loses its markup. Feature-local in forge-et-fe src/features/email/compose/RichTextBody.tsx: both its consumers, the compose dialog and the template editor, are in the email feature, so it is not promoted to src/ui (Rev 62)
Inline pick list (Rev 62) A searchable list that opens as a full-width row under its trigger (the rich-text body’s panel row), never as a popup — F20-d’s Insert merge field and Insert template. A search box named on screen as Rev 41’s data bar names one: a search icon at its start and a placeholder with the same words as its aria-label, in Title Case (Search Merge Fields, Rev 107). Then the items, each a real button, under optional group headings that name their lists; an item may carry a short qualifier after its label (Shared, Personal). The §5 Combobox behaviours: the search box takes focus as it opens; ↑/↓ move between the search box and the items; Enter or Space chooses; Escape closes and returns focus to the field the text goes into, with preventDefault and stopPropagation so a dialog around it stays open; the result count on a visually hidden status line rendered in every state; a one-line empty state; the matched part of a label at weight 600 in its own span. Chosen over shadcn’s Command in a Popover because Command needs a new package (cmdk) and the inline row follows the link row’s precedent. forge-et-fe src/features/email/templates/PickList.tsx
Safe message body (provisional, Rev 54) How an email body — untrusted content — is shown (F20-c’s message view and the reply dialog’s quoted original; F1-c’s timeline later). A text body is plain text with its line breaks kept, type/body, wrapping anywhere. An HTML body sits in a sandboxed frame: no script or inline handler runs, no form submits, nothing navigates the CRM, and nothing remote loads (no image, stylesheet, font or media — data: images and inline styles only); a link keeps its address only when it is http, https or mailto, and opens in a new tab with no opener and no referrer, while any other link keeps its text and loses its address. Nothing reaches the frame that the cleaner did not see: templates and declarative shadow roots are removed with their content, and the cleaned body is parsed a second time, falling back to its plain text if anything disallowed reappears. The frame takes the column’s width and the CRM’s text style, and its height follows its content up to a growth limit, after which it scrolls inside itself; at 320px markup wider than the column scrolls inside the frame, never the page. No body: This message has no text in type/meta, text/secondary. It renders no control of its own — inert in the interaction-state matrix; links inside the frame belong to the email. React’s raw-HTML prop stays banned: this is the one reviewed way to show untrusted HTML, and a change to its sandbox, policy or link rule is a reviewed decision. forge-et-fe src/ui/components/SafeMessageBody/
Select / checkbox / radio Same border/height family as Input; custom chrome, accent/gold checked state. A checkbox also has a mixed state (Rev 39) — the checked colours with the indeterminate icon concept in place of the tick, kept when disabled — and may hide its label visually while keeping it as its name, for a box in a table cell
Select inside a dialog (Rev 110) Every picker in a form or dialog has one closed look: the shadcn Input’s height, border and card fill, with the muted expand chevron at its end. Two kinds sit behind it. A short fixed list (Region, Customer Type and Currency on the account form; Buyer Type, Lead Source and the Tea Requirements group’s Product Line and Incoterm on the lead form; Role on New User) is shadcn’s Select through OptionSelect (forge-et-fe src/ui/fields/OptionSelect.tsx), which takes { value, label } options; an option with an empty value stays in the list, so a saved value can be taken back (BUG-283), and is what the closed control shows while nothing is chosen. A list the user types to narrow is SearchSelect (shadcn Input + Popover, the Combobox row’s behaviour): Country on the account and lead forms, whose first option, No country, clears it (a Radix Select renders every item even while closed, too slow for about 250 countries), the standard dialog’s Client picker (F26-b Rev 9: shown when the Pricing page has no client in its filter, over the client lookup), and the owner picker (OwnerPicker: the account and lead forms, Change Owner — including the one the offboarding list, OwnedRecordsList, opens — and Change Manager), each option the person’s name with the role on a second line. OwnerPicker was a native <select> because the older Modal clipped a custom list; the shadcn dialog’s Popover is not clipped and stays inside the focus trap. SearchSelect and the tag search (AddTagPicker) take a disabled state (aria-disabled; the list does not open), and SearchSelect an onBlur. The lead’s match dialog’s record search (RecordSearchPicker) is on shadcn Input + Popover in place of react-aria-components’ Combobox, with the same behaviour; the attach-account picker keeps its behaviour (the input is the search text, the chosen record its helper line) with the same chevron. The standard dialog’s Type is not yet on OptionSelect
Badge / pill Tint bg + deep same-hue text at type/micro, radius/pill, padding space/1 × space/4. Tone variants: neutral / positive / notice / danger — there is no info variant (§2). Two provisional points, both needing the prototype on screen at FS-3 subtask 4 (Rev 8): the raw spec said r10+, whose open-ended “+” is read here as the stadium the row’s own name implies — if measured badges are 10px corners it is radius/sm instead; and type/micro is UPPERCASE, so if badge labels are sentence-case it cannot carry them and micro’s casing becomes a per-use rule or a type/badge sibling is added. A tag’s look (F1-e, Rev 74): a tag with no colour is a plain outline (the control border, no fill), so it no longer looks like Neutral; Positive and Notice fill with their tone’s border token (--et-tone-positive-border, --et-tone-notice-border), so the two read apart; Danger is unchanged. One component draws every tag (forge-et-fe src/ui/TagBadge.tsx, its look from src/lib/tags/tagLook.ts). A tag is not a pill (Rev 77): it is a 24px rounded rectangle whose colour is a dot and a tint behind dark text — None plain, then Neutral, Positive, Notice and Danger — with its remove ✕ inside its right end on a 24 × 24 target; pills stay for statuses and the AI’s markers. A record’s tags end with a dashed + Add tag chip the height of a tag, which turns into the tag search in place (AddTagControl); a table row shows its first two tags, each cut at 15 characters with the full name on hover, then a +N button opening every tag in a popover (TagLine). The AI triage tag’s dismiss control (Rev 110): in the lead page’s AI Summary card, the Spam or Duplicate badge (Rev 66’s variants) holds its own dismiss control for a lead.manage holder — a ghost icon-only button at the badge’s end, a 24 × 24 target with a 12px ✕, named Dismiss Tag: (Dismiss Tag: Spam), with a spinner in the ✕'s place while the dismiss runs, as a tag’s remove ✕ sits inside the tag. There is no separate Dismiss Tag button with visible text under the tag (forge-et-fe src/features/leadTriage/TriageTagBlock.tsx)
AI provenance chip tone/ai, UPPERCASE micro label. Every AI-generated artifact carries one, and it names the human’s role: “AI DRAFTED · EDITABLE”, “AI SUGGESTED”, “AI steps · you approve”, “AI draft · you send”. This is the PRD’s human-in-the-loop governance made visible — never omitted, never reused for non-AI content. The chip is one of four required elements — see § AI provenance below.
Status indicator A coloured dot plus a visible text label, always. Dot at icon/sm, radius/circle, tone from §2; label at type/micro (dense surfaces) or type/meta. The dot’s shape also varies by state — solid / ring / half-filled — so the distinction survives greyscale and colour-blindness even if the label is clipped. Distinct from Badge: a badge is a filled pill naming a category, a status indicator is an inline dot + label naming a state. Used for age-in-stage and rotting (F2/F18/F24), lead priority P1–P3 (F11), “what’s stuck” severity (F15), sample-round lifecycle (F6), certification match/mismatch (F9) and quote-readiness items (F7). See § Status indicators below for the per-state vocabulary and the Kanban density consequence. The lead’s hot / cold is the one state shown otherwise: a tinted pill with a glyph and its word (Rev 107, § Status indicators)
Focus marker (Rev 150) Marks a lead whose AI ranking was made for a campaign’s focus (F36-c FR-FC6 and D-29, F11-g FR-V7), in both apps: on the capture app’s To Review rows, after the tier badge, and in the CRM’s Leads table, after the priority in the Priority cell. The capture app’s Plan exhibitor cards carry none. One look: a 24px-tall outlined pill (radius/pill) on surface/card, holding the campaignFocus icon (lucide’s Focus, at icon/sm, aria-hidden) and the word Focus, not uppercased, in tone/neutral text at type/card-title’s weight (600), at type/meta’s size — 12px in the CRM, the capture app’s 14px. In the CRM it is the shadcn outline Button at xs (the shadcn input border, its light shadow and hover fill); in the capture app it is a pill with a border/control border, space/2 between icon and word and space/4 at each side. It is a button of its own, never inside the row’s link or button, and pressing it never opens the lead. Its accessible name is the visible word, then the fixed line: Focus: ranked for the focus of : “” (WCAG 2.1 SC 2.5.3). Its tooltip is the fixed line, Ranked for the focus of : “”, in the Tooltip row’s look (surface/card, border/card, radius/md, shadow/menu, type/meta in text/primary, at most layout/tooltip-max wide, a long word breaking anywhere), below the marker from its start. It shows while any of three holds: a click, tap or Enter pinned it; a mouse is over the marker or the tooltip; the marker has keyboard focus (:focus-visible). A second click, tap or Enter on a pinned marker closes it, and so do Escape, blur, a press outside both and the mouse leaving both. The tooltip adds nothing to what a screen reader hears, because the name already holds its text: the CRM’s does not describe its trigger, and the capture app’s is aria-hidden. In the capture app the button is a 44 × 44px hit area (layout/control-h) around the pill, the tooltip is kept inside the row’s card, and Escape on the marker goes no further, so a sheet around the list stays open; in the CRM the tooltip moves above the marker when there is no room below. The focus text and the campaign name are typed by people and render as text only. forge-et-fe src/ui/components/LeadRankIndicators/LeadFocusMarker.tsx; forge-et-pwa src/ui/FocusMarker.tsx
Card / Panel surface/card, border/card, radius/lg, pad space/6, card shadow. Tinted variants: notice / positive / danger per §2 tones. (Rev 110) A banner — a message across a section or a page — is an Alert (next row), not a tinted Card
Alert / banner (Rev 110) One component draws every banner in the CRM: shadcn’s Alert (forge-et-fe src/ui/shadcn/alert.tsx), with its icon in the first column and the title and description beside it. Three variants: default, on the card (surface/card), for a neutral notice (the Email page’s New mail, Rev 98); destructive, on the destructive-muted tint with its paired text, for a failure — ErrorPanel draws through it (its Try Again, trace line and test ids unchanged), and so do SyncLapsedNotice, SaveErrorSummary and the Email folder tree’s failure panels (FolderTreeNotice, through ErrorPanel); warning, on the warning-muted tint with its paired text, the warning edge and the registry’s warning icon, for a recoverable problem — Rev 80’s connect-failed banner (MailboxConnectBanner), the Deactivate User dialog’s missing-keys notice (MissingKeysNotice), the Pricing page’s warnings (PricingWarnings), the import’s warnings (ImportWarnings) and the publish dialog’s notice (PublishRoundDialog). Both tinted pairs clear 4.5 : 1 for text and 3 : 1 for the icon. It renders role="alert" by default; a caller that announces the message through its own always-mounted status line passes role="none", so it is heard once (Rev 80’s banner pattern). Section banners still drawn by hand move onto it (.forge/owed.md); an inline field error stays the field’s own message (§5 Form fields)
Table One look for every CRM table, the Users table’s (Rev 41, Rev 74): built from shadcn’s Table parts with the shared classes in forge-et-fe src/ui/dataTable.ts, so no table writes its own header, cell or row-height styles. The header row is unshaded and in Title Case (§9, Rev 90; sentence case before it), at the body cells’ size and colour (type/secondary, text/primary), set apart by semibold weight and a bottom rule; body cells are type/secondary, wrapping between words, with a row rule and the row’s hover fill; one row height for skeleton and populated rows; the ⋯ menu in a narrow last cell under a visually hidden Actions header. A row’s actions are always in that ⋯ menu (RowActionsMenu), never buttons in the row (Rev 133), however few there are; a destructive item is marked destructive in the menu. The one exception is a table inside a dialog whose rows each have a single action (the Standards not in this round dialog’s Carry Forward). forge-et-fe’s src/ui/pinnedFirstColumn.test.tsx enforces it (no list table puts buttons in its rows). The table runs to its card’s side edges and scrolls inside it under a sticky header row. A table with many columns may let its header labels wrap onto two lines (the Pricing tables). A raw <table> is not used. (Before Rev 41 this row described a micro/eyebrow header on muted; that look is gone from the CRM.)
Tabs / segmented control Inline text tabs (List / Board / Calendar), active = text/primary + gold underline or pill bg; inactive = text/secondary, hover text/strong (tab labels are body-size text, so text/muted fails AA, §2). Two variants on shadcn’s Tabs (Rev 101): pill (the default) for tabs that sit on their own — (Rev 115) the group filled surface/accent (neutral-100), the selected tab surface/card with the card shadow and text/primary, as the current prototype draws it — and line for a tab strip across the top of a card — no fill, the selected tab underlined in primary at border-width/selected on the strip’s bottom rule, the tabs space/6 apart (the Email list’s Focused and Other). A panel class that sets display also keeps [hidden] hidden, because Radix leaves the panel not chosen in the page with the hidden attribute (Rev 101, .forge/lessons.md L-262). A row of tabs that can outgrow its width moves the tabs that do not fit into a More Views Dropdown Menu after the list, in order, and never moves the selected tab (Rev 116, §6 Saved views)
Modal One look for every modal (Rev 90): a centred card, radius/lg, shadow/modal, no border, over the dimmed backdrop, padded space/7 on every side with space/6 between its parts; used for record detail (deal modal) as well as forms and confirmations. From the top: the title (type/subhead) with its one-sentence description under it (type/body, text/secondary) and the ✕ ghost-icon button at the top right beside them; the body; the buttons, at the right, Cancel first and the main action last, the main action named for what it does (Change Owner, Archive Contact), never OK or Submit. No rule or fill separates the parts. Only the body scrolls: the card is never taller than the viewport less space/7 above and below; past that the body scrolls while the title and the buttons stay in view. A confirmation has no body. Three sizes, and no modal sets its own width (Rev 90): sm, 420px, for a confirmation; md, 560px, for a one-column form of up to about five fields (Change Owner, Change Manager, New Sale, Set Cost); lg, 800px, for a longer or two-column form, the compose window, a table, and the role and template editors (New Account, New Contact, New Lead, Price History). Each narrows with the viewport, space/8 kept at each side; a two-column form has at most two columns. Behaviour (Rev 90): Esc, the ✕ and Cancel close it, except while a save runs, when the main button is busy and Cancel is unavailable; with unsaved edits, ✕ and Esc ask first, and a click outside does nothing. Focus starts on the first field (on Cancel in a destructive confirmation) and goes back to the control that opened it. Errors follow §5 Form fields and validation: a field’s error shows under its field, and a refusal that names no field shows above the fields; the modal stays open, unless the record it acts on is gone. A success closes it and is announced by a toast (Toast, below). Every create flow opens in a Modal (Rev 70, not built yet on every screen), as the Users list’s create-user dialog does: a new account, contact, lead, buying standard, email template or any later record is entered in a modal over its list, never on a page of its own. Creating a user or a role is already a modal; the pages that become modals are an account’s /accounts/new and an email template’s /email/templates/new. Editing a record that has its own page is not done in a Modal (Rev 74): it is the page’s edit mode (§6 Detail page); a Modal edits only what has no page of its own — a tag, a buying standard, a price, a sale’s dates, a follow-up. (Rev 77) On the account, contact, user and role pages that rule is reversed: Edit opens the record’s edit dialog over its page (RecordEditDialog, or the account’s EditAccountDialog) — the title with its ✕, a body that scrolls, then Cancel and Save ; ✕ and Esc ask first when there are unsaved edits, a click outside does nothing, and focus goes back to the control that opened it. The lead page and the email template keep their edit pages. (Rev 82) The email template no longer does: its Edit opens Edit Template over its page in the same frame, at the lg size (Rev 90; it was RecordEditDialog’s 900px wide, which the role editor also used), with Delete Template at the left of the button row; only the lead page keeps an edit page. (Rev 96) The lead page no longer does: its Edit, and the Leads list’s ⋯ Edit, open Edit Lead over the page in the same frame, at the lg size (as New Lead), with Cancel and Save Lead, so every record with a page of its own is edited in a dialog over that page. A destructive confirmation is shadcn’s AlertDialog (ConfirmDialog), at the sm size: the title, one sentence, Cancel first and the destructive action last, in the destructive fill; the button that opens it uses the destructive outline. Every dialog has Cancel, the older ones included. (Rev 74’s two widths — form, 58ch, and wide, 720px — and its footer band with a top rule on surface/card-warm are replaced by Rev 90’s three sizes and unbanded button row.)
Toast Bottom-center, brand/deep-green bg and its paired text, radius/md, shadow/toast, motion/slow; auto-dismiss + manual close. Rendered as a [popover] so it sits in the top layer (§4). A toast may carry one action (Undo), named for what it does; a toast with an action stays until it is acted on or closed, since a message that leaves on its own is one some users never read. New toasts in the CRM are shadcn’s Sonner (src/ui/shadcn/sonner.tsx, AD #39), keeping the placement and the screen-reader announcement; the older src/ui Toast stays where it is used until its screen is moved over (Rev 61). Every success is a toast (Rev 90): when an action completes — a save, a create, an archive, a note added — the CRM says so in a toast, worded with the action’s own name (Archive Contact → “Contact archived”), never in an inline message on the page. An inline message stays only for what a toast cannot hold: a failure, with its Try Again and reference line, and a notice the user must act on or dismiss (a record that changed under them, a missing permission). The inline success messages on the contacts page, the notes sections, the activities list and the leads list, and the account page’s “Account saved”, move to Sonner
Dropdown menu surface/card, border/frame, radius/md, shadow/menu, type/secondary items, hover surface/hover. Accepts an optional trigger?: ReactNode — when supplied it replaces the default string-label Button trigger (the sidebar current-user menu passes its avatar + name + role identity block, §6) while preserving the menu-button ARIA contract (aria-haspopup, aria-expanded, aria-controls, and aria-labelledby pointing back to the trigger); the string-label path is unchanged
Avatar Circle (radius/circle), accent/gold bg, its text-on for initials, 600
Date input Native <input type="date"> (<input type="time"> where a time is needed), styled to the Input row above. A range is two labelled inputs — From / To — validated as a pair, never a custom two-month popover. Used by quote validity (F7), price effective dating (F26), expected close (F2), activity scheduling (F3/F21), and F34’s date custom-field type. Dates display as Fri 18 Sep per §9; the input itself uses the browser’s locale format, which is correct behaviour rather than a deviation
Switch On/off for a setting that applies immediately. Track radius/pill, accent/gold when on, border/control when off, thumb surface/card, motion/fast. A real <input type="checkbox" role="switch"> with a visible label; the label states what being on means, never just the field name. Use a checkbox, not a switch, inside a form that has a Save button — a switch implies the change already took effect. Admin config (F24/F34), settings, mailbox connect
Combobox / typeahead The one place a library is taken. Text input (Input row) that filters a radius/md popover list on type; ↑ ↓ move, Enter selects, Esc closes and restores, matched substring emphasised at weight 600. Announces result count on a live region. Empty state is one line of text, never a blank box. Used by every entity picker — account, contact, product, buying standard, owner (F31’s top-bar search was dropped, PRD Rev 60). (Rev 77) Inside an edit dialog a picker of one value from a known list — the user editor’s Manager — is SearchSelect: the field shows the chosen name, typing filters the list in a popover capped in height, the chevron sits inside the field, and Esc closes only the list, never the dialog around it
Tooltip / popover Short label on hover and on keyboard focus (never hover-only, or it is invisible to keyboard users). surface/card, border/card, radius/md, shadow/menu, type/meta, ~28ch max. Dismissed by Esc. Required by §9’s permission rule — a disabled control’s reason is surfaced this way and duplicated in the accessible name. Never the only home for information a user must have, and never for interactive content — that is a popover, sized to content and focus-trapped
File upload Drop zone: dashed border/control, radius/lg, surface/card-warm, centred icon + “Drop files or browse” — always with a real <input type="file"> behind it, so keyboard and screen-reader users are never dependent on a drag gesture. States: idle · dragover (accent/gold border) · uploading (determinate progress bar) · scanning · failed (tone/danger inline, with the reason and a retry). Accepted types and the size cap are stated in the zone before upload, not discovered by failing (F33, FS-11); on a record’s Attachments card the hint reads PDF, JPEG, PNG, Excel, Word or PowerPoint, up to 25 MB each (F33-a, Rev 102)
Attachment row One file: type icon, filename (truncating from the middle so the extension survives), then uploader · date · size at type/meta, and a download action. A file that has not cleared the virus scan renders in a scanning state — visible, named, and not downloadable — because FS-11 gates visibility on the scan, so “uploaded” and “available” are different moments and the UI must not pretend otherwise. A scan failure renders tone/danger with the file quarantined, not silently missing (F33). On a record (F33-a, Rev 102): the row sits in the record’s Attachments card, with Download for everyone who sees the card and Delete for a holder of the record’s manage key, each named with the file; the scanning state reads Being checked, a refused file reads Refused: this file may contain a virus in tone/danger, and a file not scanned (NOT_SCANNED) shows exactly as a ready one, with no wording that claims or denies a check; Delete turns the row into a confirmation in place — Delete ? with Delete and Cancel, as a note’s delete question — never a second dialog. A received email’s files are tiles instead (Rev 101): see Attachment tile
Attachment tile A file received with an email, drawn as Outlook draws it (Rev 101; BUG-363): tiles in a wrapping row, each seven space/8 steps wide, shrinking to the row at the 320px reflow. A tile is one shadcn outline Button: the type icon, the name (shortened from the middle so the extension survives, read whole) over the size at type/meta, and the download icon at its end in text/secondary, primary while pointed at — always shown, not only on hover, so it reads on a touch screen. The whole tile downloads the file; it is named Download , with the size as its description. Busy, the spinner takes the type icon’s place; a refused download’s error, Try Again and trace line sit under the tiles, that tile’s item taking the full row. Outlook’s click opens a preview, which the CRM does not have, so here the click downloads. (Rev 145) A linked email’s stored files (F20-f): in the reading view of an email linked to a record, a stored file is a ready tile, with no wording that claims or denies a virus check (as Attachment row says for a file not scanned). Three more states show a file that is not stored: Being saved while it is still being copied, Too large to keep with its name and size (a file over the size limit), and Could not be kept (Microsoft could not return it); none of the three downloads. When the email’s list of files could not be read at all, the single line Attachments could not be kept shows in place of the tiles
External link (Rev 69) A link to a page on another site, shown as that site’s host — F11-c’s research source links, one beside each finding. An <a> with target="_blank" and rel="noopener noreferrer"; its text is the host exactly as the URL parser gives it (lower case, an international domain in its xn-- form, so a look-alike host cannot pass for another), followed by the visually hidden (opens in a new tab) (WCAG 3.2.5) and the externalLink icon concept at icon/sm, aria-hidden. A page title, when there is one, is the link’s accessible description (aria-describedby on hidden text — never the title attribute, which only hover shows). text/primary, underlined a space/1 below — there is no link colour token; at least space/7 (24px) tall, because in a finding row it is a flex item, not a link in running text (WCAG 2.2 SC 2.5.8); the host wraps anywhere, so a long host never scrolls the page at 320px. Only an absolute http/https URL becomes a link: anything else (javascript:, a relative path, a scheme-less www.…, an unparsable string) renders as plain text with no icon. Several links to one host in one list carry the same name; the statement beside each and its description tell them apart (WCAG 2.4.4, in context). No disabled, busy or invalid state — §5 gives a link none. forge-et-fe src/ui/components/ExternalLink/
Empty / loading / error states Mandated per component (mostly absent in the prototype): empty = icon + one-line explanation + primary action; loading = skeleton blocks in surface/card-warm; error = tone/danger inline panel with retry — (Rev 110) ErrorPanel, drawn through the Alert’s destructive variant

Interaction states — the matrix every interactive component ships

The prototype specifies hover for three components and nothing else. A component is not done until every row below is answered, and “we forgot the pressed state” is the usual way a build feels unfinished without anyone being able to say why.

State Treatment Notes
Rest Per the component row above —
Hover Primary buttons lift with shadow/button-hover; everything else darkens its surface one step Pointer only — never the sole route to information (see Tooltip)
Focus focus/* ring per §4, on :focus-visible Mandated; the prototype has none
Active / pressed Remove the hover lift and shift the surface one step darker — the control moves toward the press Missing everywhere in the prototype
Disabled (visual) Muted colours, never element opacity (Rev 31). One grey for every control that has a fill (Rev 34): buttons of every family and fields (Input, Select, Combobox) take surface/disabled for the fill and text/disabled for the text. A button’s border takes surface/disabled too, so no control border shows; a field keeps its control border. A checkbox or radio keeps its state colours (unchecked, its box takes surface/disabled), a switch keeps its off track, and each fades only its label to 55%. A menu item keeps text/secondary. not-allowed cursor, shadow removed. The look is the same at rest and on focus, and the focus ring is always full strength aria-disabled="true", never the bare disabled attribute — the control stays focusable and states its reason (§9’s permission rule)
Busy / loading Label stays, aria-busy="true". A spinner replaces the leading icon; width does not change. (Rev 83) The spinner is shadcn’s Spinner, in the flow before the label with the button’s gap, as shadcn’s Button shows it: it replaces a leading icon (an icon-only button’s included), so that button keeps its width, and any other button grows by the spinner and its gap while it waits Required on anything that submits or calls the AI, or the user presses twice
Selected accent/gold-deep left border (a non-text indicator, 3 : 1 — accent/gold fails it on light surfaces), text/primary label; (Rev 115) a pill tab is selected by its surface/card pill (§5 Tabs), not a gold one. The sidebar’s selected entry (Rev 78): a border-width/selected accent/gold-deep bar on the leading edge of a surface/card fill with a border/frame ring, and a semibold text/primary label (§6 App frame). The Email list’s open message (Rev 84): the same border-width/selected accent/gold-deep bar, its outer end rounded, on a surface/card-warm fill; the row hovers in the same rounded fill, and the list is inset space/2 from its card so a fill never meets the card’s edge. The Email folder column’s current folder (Rev 91): the same look as the open message, with the same space/4 leading padding; the folder card’s own padding keeps the fill off its edge. Since Rev 95 the look is on the folder’s row, which holds the fold button (or its space/7 slot) before the link, inset space/2 at the start in place of the space/4 above, its bar inset by the row’s space/2 block padding; and the folder pane’s rail marks its current tile the same way, inset by the tile’s space/3. The rail has no tile for a subfolder, so while one is open its Mailbox tile, or the Folders tile for the user’s folders, has the look, with aria-current="page" on an exact match only. Every gold-bar selected row has radius/xs corners (Rev 91) — the sidebar’s entry, the open message and the current folder, and their hover fills — and its bar is inset from the top and bottom by the row’s block padding, so the bar’s ends sit inside the fill. A new list or nav that marks its selected row uses this look and these values, never its own Table rows, tabs, nav, list-pane selection
Invalid See form validation below Inputs only

Form fields and validation

Input above specifies sizes only. A field is a label + control + optional helper + error slot, and the slot is reserved at rest so nothing reflows when an error appears.

  • Label above the control, always visible, in text/primary (Rev 107), so it reads ahead of the placeholder (text/faint) and the helper text (text/secondary). No placeholder-as-label — it disappears on focus, fails contrast, and is invisible to a screen reader once typing starts. Every form field has a placeholder (Rev 70, Rev 74), in Title Case (Rev 107): a field the person types into says Enter and the field’s name (Company Name → Enter Company Name); a select, a date and a record picker say Select and the name (Select Country, Select Standard). No example values (e.g. BOP1, e.g. +94 77 123 4567) — a format the person needs to know goes in the helper text instead. The placeholder is in text/faint and the label stays above it, so the placeholder adds nothing a reader depends on. One exception: a filter where an empty value means “every one” may state that value as its placeholder (All Clients), in text/secondary, because the reader needs it (Rev 51). Built with enterPlaceholder, selectPlaceholder and titleCase in forge-et-fe src/ui/fields/placeholders.ts.
  • Required is marked on the label (Buying standard *)~~ with the convention stated once per form~~. (Rev 110) The convention is not stated: no form or dialog carries a Fields marked * are required sentence. The * on the label and the field’s required state, which a screen reader announces, carry it, and a sentence a form had for another purpose keeps only that part (A name is enough to start on New Account). Optional fields are unmarked; marking both doubles the noise.
  • Errors: tone/danger border on the control, message beneath at type/meta in tone/danger text with no icon, in the CRM and the capture app alike (Rev 148), aria-invalid="true", and the message linked by aria-describedby. The message names the fix, not the failure — “Enter a date on or after today”, not “Invalid date”.
  • Validation timing: validate on blur, never per keystroke; once a field is invalid, re-validate as it is corrected so the error clears as soon as it is fixed. Nothing is validated before it has been touched.
  • On submit: every field is checked, touched or not, each error shows beneath its field, and focus moves to the first invalid field. There is no error summary at the top of the form (Rev 81). A refusal that names no field the form shows is stated in a message above the form, which is not a list of field errors.
  • Helper text sits under the control at type/meta in text/secondary, and is replaced by the error when there is one.
  • A form field that takes several values from a list (Rev 112) is the multi-choice select of §6 (Rev 99) in a Field: the select trigger’s look, its text the placeholder (Select ) or the count chosen, the chevron; it opens a popover of labelled checkboxes in option order, each toggle applying at once with the popover left open, Escape closing it with focus back on the trigger and Tab from the last box closing it and moving on. Unlike the filter, none checked is no value, not All, and the chosen options show as Badges under the trigger, wrapping, in option order. The trigger carries the Field wiring itself (id, aria-describedby, aria-invalid) and is named by the field’s label and its visible text together. First used by the custom-fields section of the account, contact and lead forms (F34-c spec FR-16).

Status indicators — the per-state vocabulary

Every state below renders as dot + visible text, per the §2 build rule, except hot / cold, which is a glyph + visible text in a tinted pill (Rev 107). The label is the short form; the long form goes in the accessible name.

State Tone Dot Label Where
Fresh / on track tone/positive solid Fresh Deal cards, sample rounds
Ageing (approaching the stage’s rotting threshold) tone/notice half-filled Ageing · <n>d Deal cards (F24 threshold)
Rotting / overdue tone/danger ring Rotting · <n>d Deal cards (F2/F18), quote aging
Priority tone/danger / notice / neutral solid P1 / P2 / P3 The Leads table’s Priority column (— for a lead with no current ranking) and the heading of the lead page’s Priority panel (F11-g FR-V1, FR-V3; Rev 99). Built as LeadPriorityIndicator (forge-et-fe src/ui/components/LeadRankIndicators); the accessible name is Priority P1
Lead engagement — hot / cold tone/danger / tone/neutral no dot: a small tinted pill with a glyph — a flame (leadHot) / a snowflake (leadCold) — and the word (Rev 107) Hot / Cold Lead list and lead detail, beside the priority (F11-g FR-V2, FR-V3; PRD Rev 55). Never a label badge: though both are pills, the indicator carries its glyph and no border, and a migrated Pipedrive: Hot label stays among the lead’s labels. Built as LeadEngagementIndicator (src/ui/components/LeadRankIndicators, Rev 99); in the table its accessible name adds the date it rests on (Hot, buyer last wrote Wed 14 Oct), and in the panel the date is the visible Buyer last wrote line beside it
Severity tone/danger / notice solid Blocked / Slipping “What’s stuck” (F15)
Certification match tone/positive solid Certs match F9
Certification mismatch tone/danger ring <n> missing F9
Checklist item met / unmet tone/positive / tone/neutral solid / ring Ready / Pending Quote readiness (F7), export docs (F10)
Mail sync — healthy / waiting / lapsed (provisional) tone/positive / tone/neutral / tone/danger solid / half-filled / ring Receiving mail / Waiting for mail / Not receiving mail Mailbox connected panel, all three states; inbox at /email, lapsed only (F20-b FR-11 / AC-26)
Price state — current / priced per quote / no current price (provisional) tone/positive / tone/neutral / tone/notice solid / half-filled / ring Current / Priced per quote / No current price A buying standard’s row on the Pricing page’s Standards book and on the account page’s standards panel (F26-b FR-U2)
Round state — draft / can’t publish / published / withdrawn (provisional) tone/neutral / tone/notice / tone/positive / tone/neutral half-filled / ring / solid / ring Draft / Can't publish · <reason> (Standard archived, Quoted per deal, Later price published) / Published / Withdrawn A price row in the Pricing page’s Weekly prices tab (F26-f FR-18)
Round state — corrected (provisional) tone/positive solid Published · Corrected A corrected price’s row in the Weekly prices tab (F26-g FR-19)
Sale state — upcoming / in progress / held (provisional) tone/neutral / tone/positive / tone/neutral ring / half-filled / solid Upcoming / In progress / Held A sale’s row on the Pricing page’s Auction sales tab (F26-g FR-15)
Price email — sent this week (provisional) tone/positive solid Prices sent <date> (Thu 15 Oct); the tooltip and accessible name add the addressee and the sender Beside Send this week’s prices in the account header, when a price email is recorded for the current sale; absent otherwise (F26-d FR-U5)
Price broadcast — sending / sent / some not sent / stopped (provisional) tone/neutral / tone/positive / tone/notice / tone/neutral half-filled / solid / ring / solid Sending prices — <sent> of <total> / Prices sent to <sent> of <total> customers (Prices sent to 1 of 1 customer when the total is 1) / Prices sent to <sent> of <total> — <n> not sent / Stopped — prices sent to <sent> of <total> On its own line below the Pricing screen header’s buttons, from their left edge (Rev 134), for the user’s latest batch against the current sale; absent when there is none (F37-a FR-U5). The noun after the total is singular for a total of one (Rev 131)
Price broadcast customer — waiting / sending / sent / not sent / not known / sent, not marked / skipped / stopped (provisional) tone/neutral / tone/neutral / tone/positive / tone/danger / tone/notice / tone/notice / tone/neutral / tone/neutral ring / half-filled / solid / solid / ring / ring / solid / solid Waiting / Sending / Sent / Not sent — <reason> / Not known — check your Sent Items / Sent — not marked as sent / Skipped — <reason> / Stopped Each customer’s row in the price broadcast’s results dialog (F37-a FR-U4)
Activity due state — overdue / today / upcoming / done (provisional) tone/danger / tone/notice / tone/neutral / tone/positive ring / half-filled / ring / solid Overdue <n>d / Today / Tomorrow, In <n> days or the date (Fri 18 Sep, with the time when set) / Done <date> A follow-up’s due chip on the Activities page and in each record’s Follow-ups panel (F3-a FR-V2)
Dormant tone/notice ring Dormant The account list’s Status cell and the account page header (AccountStatusMarks; F1-b, F1-d). The rule is F1-c’s: an account with no timeline row, or whose newest row is older than the threshold (90 days by default), is dormant (F1-c FR-D1, FR-D2)
Capture kept on the phone — not sent / sending / refused (provisional) tone/notice / tone/neutral / tone/danger ring / half-filled / solid Not sent / Sending / Refused A kept capture’s row under Not Sent on the capture app’s Capture (F36-a FR-R2, Rev 123). In the capture app the label takes the size of the line it sits in (type/meta, never below 14px) and the dot is half icon/sm
Campaign state — upcoming / running / ended (provisional) tone/neutral / tone/positive / tone/neutral ring / half-filled / solid Upcoming · starts <day> (or Upcoming) / Running · day <n> of <m> (or Running) / Ended The campaign card and the Last Campaign row on the capture app’s Plan (F36-a FR-P1, Rev 124). The Sale state row’s tones and shapes, since a campaign runs the same upcoming → under way → over course — one look per pattern. The state is the server’s (CampaignResponse.state); only the day count reads the phone’s date
Captured lead outcome — in the CRM / rejected (provisional) tone/positive / tone/neutral solid / ring In CRM / Rejected A decided lead’s row under Completed on the capture app’s Leads, after its title, and the lead’s page under its company line (F36-a FR-L3, FR-L6; Rev 136). The Checklist item met / unmet row’s tones and shapes: a decision made, or a lead set aside. In the capture app the label takes the size of the line it sits in (type/meta, never below 14px) and the dot is half icon/sm. The state is the server’s (CapturedLeadResponse.status)
Email tracking — sent / opened / clicked (provisional) tone/neutral / tone/positive / tone/positive ring / half-filled / solid Sent / Opened / Clicked; the tooltip and accessible name add the counts and the last time (Opened 3 times · last Mon 9 Nov, 14:02) and the sentence Opens and clicks are estimates. A tracked send: in the message view’s header beside the Sent badge, in its row of a Sent Items list, and on its email entry in the account timeline (F20-g FR-V1–FR-V3). Nothing for an untracked send or a message sent from Outlook

The label wording is provisional where the PRD names none. P1–P3 and rotting are the PRD’s own vocabulary (three priority levels since PRD Rev 55; hot and cold are the PRD’s words, and that row’s tones and shapes are settled by F11-g’s spec, decision 10 — Rev 93, and changed to a glyph pill by Rev 107); the rest — Fresh, Ageing, and above all F15’s Blocked / Slipping pair (the PRD says only “severity” and names no levels) — are proposed here, unverified against Empire’s own language. The structure is the settled contract — dot + shape + visible text label (for hot / cold, glyph + visible text label, Rev 107); the words need Empire’s confirmation before their screens ship, F15’s pair first (open item 14).

The mail-sync row is provisional on the same footing, and its shapes are a feature choice, not a rule of this section. The PRD names no sync states, and the client-approved prototype has no sync indicator at all, so all three labels are this project’s proposal (F20-b spec AC-26). The solid / half-filled / ring trio mirrors the Fresh / Ageing / Rotting run because the three states are a progression, but this section does not require one shape per state — the visible label is what carries a state through greyscale. Waiting takes tone/neutral, not Ageing’s tone/notice, deliberately: a mailbox that has not yet received its first message is not a warning. Waiting also covers “no subscription attempted”, and an unrecognised state falls to Waiting because it makes no claim and offers no action.

The price-state row is provisional on the same footing. The PRD names no price states, so the three labels are this project’s proposal (F26-b spec FR-U2). Priced per quote takes tone/neutral, not a warning tone, deliberately: a private-label standard with no weekly price is normal under OQ-61’s default (quoted per deal). No current price takes tone/notice, because a bulk standard with no published price cannot be quoted. The price itself is never inside the indicator: it sits in its own Price / kg column (§9 Money).

The round-state row is provisional on the same footing. The PRD names no round states, so the labels, tones and shapes are this project’s proposal (F26-f spec FR-18, FR-24). Can’t publish takes tone/notice, because the draft will not go live when the round is published. Withdrawn takes tone/neutral, not a danger tone, because it is a final, expected state, not an error. Every tone and shape pair differs, so greyscale still separates the four. The reason is part of the label; who published or withdrew a price and when, and a withdrawal’s reason, sit in a tooltip on the status, which opens on hover and on keyboard focus and is also the status’s accessible description.

The corrected round state is provisional on the same footing (F26-g spec FR-19, FR-22). Published · Corrected shares Published’s solid tone/positive dot, because a correction is a published price; the label carries the difference. The correction’s reason, who made it and when sit in the status’s tooltip, as they do for Published.

The sale-state row is provisional on the same footing (F26-g spec FR-15, FR-22). The PRD names no sale states, so the labels, tones and shapes are this project’s proposal. The state is the server’s state, worked out against Colombo’s today: In progress includes a sale whose last day has passed until the daily price sweep marks it held. Held takes tone/neutral, not a warning tone, because it is a final, expected state. The shapes run empty → half → full as a sale moves from upcoming to held, and every tone and shape pair differs, so greyscale still separates the three.

The activity due-state row is provisional on the same footing (F3-a spec FR-V2, FR-H1). Overdue, Today, Upcoming and Completed are the PRD’s bucket names (PRD F3); the chip’s wording follows the prototype’s due chip, and the tones and shapes are this project’s proposal. The state is the server’s bucket, worked out against Colombo’s today (F3-a FR-A3), by date only. Upcoming takes tone/neutral, because a follow-up not yet due needs no attention; overdue takes Rotting’s ring, because both mean late. Every tone and shape pair differs, and the label carries the state through greyscale. An overdue row is also highlighted with the tone/danger tint (#FCF5F2, --et-tone-danger-bg) across the row, never by the tint alone: its chip still says Overdue. The activity type shows as a dot plus the type’s label (Call, Meeting, …) — a neutral tone/neutral dot, the same for every type, so the label alone tells the types apart; F3-b may give custom types their own colours when it adds them.

The email tracking row is provisional on the same footing (F20-g spec NFR-5, decisions 2 and 10). The PRD names no tracking states, so the tones and shapes are this project’s proposal. There is no Delivered state: Microsoft Graph confirms no delivery for a sent message (decision 2). Sent takes tone/neutral with a ring, because a send nobody has opened is not yet a signal; Opened and Clicked share tone/positive and differ by shape, half-filled then solid, as engagement grows, so greyscale still separates the three with the word. Mail programs that load images on arrival and link scanners make the counts estimates, so the tooltip says so in every state (decision 10). The tooltip opens on hover and on keyboard focus and is also the indicator’s accessible name, as for the price-email row.

The Kanban card grows, and that is accepted. Adding a visible label to every card’s rotting indicator costs vertical space and departs from the prototype’s approved density. Decided 2026-08-25 in favour of the PRD’s literal wording, because “dots carry text labels too” is the contract and a client seeing colour-only status at UAT is the worse outcome. Use type/micro on cards to keep the cost to one line.

project-prd.md line “turns red when untouched beyond the stage’s rotting threshold” is colour-only phrasing describing the same state. It is the PRD’s shorthand, not a licence — the rendering is dot + label, and the PRD’s own Accessibility section is what governs.

AI provenance — all four elements, not just the chip

project-prd.md § Observability and Audit and architecture.md § AI provenance, governance, resilience and cost both require that every AI output is tagged with its confidence and its source, and flips to an edited state once a human changes it. The chip alone covers one of four. They ship together or the requirement is unmet.

Element Renders as Rule
AI tag The tone/ai chip above Never omitted from an AI-generated artifact
Confidence A numeric percentage at type/meta, adjacent to the chip — Confidence 87% The PRD specifies a confidence % (F11 scores leads P1–P3 with a confidence %; the Lead entity carries confidence 0–100). Show the number. If a tone tints it, the number is still the channel that carries the meaning — the §2 colour rule applies here too
Source A short reference at type/meta naming what the output was derived from, linked where that record is reachable — from: inquiry email, 14 Aug · from: 6 activities, 2 quotes “Tagged with source” per architecture.md. A rep must be able to see what the AI read before approving it — that is what makes the human-in-the-loop review real rather than ceremonial. (Rev 110) The inquiry extraction’s label starts with a capital — from: Pasted inquiry, 9 Oct (F12 FR-E4); the other labels the server writes (email from …, inquiry, lead fields, public web search, inquiry and research, inquiry only) stay lower case for now, and whether all of them take sentence case is open (.forge/owed.md)
Edited state The chip switches to AI DRAFTED · EDITED BY YOU the moment a human modifies the content Tone stays tone/ai — provenance is still AI-originated. The editable affordance wording drops, since it has been taken

Per-field marker. In a form an AI pre-filled (F12’s New lead from inquiry), each field the AI filled carries the chip labelled AI DRAFTED after its label text, on the label’s line and wrapping under it when the column is narrow (AiFieldMarker in src/ui, passed to Field as its labelAddon). It switches to AI DRAFTED · EDITED BY YOU while the person’s value differs from the AI’s, and back when the value is restored; clearing an AI value is an edit. The chip is hidden from assistive technology and the label carries the text “AI drafted” / “AI drafted, edited by you” instead, so a screen reader reads it with the field’s name. The four-element block still appears once, above the fields, with the full AI DRAFTED · EDITABLE wording; its chip shows the edited state when any field is edited. A field the AI left blank has no marker, and fields the person pasted, preset or owns (the inquiry text, the lead source, the owner) are never marked. The per-field chip reads AI DRAFTED rather than the block’s wording because it repeats on every filled field, and the block names the person’s role once.

Research panel (Rev 69). The lead view’s Research panel (F11-c) shows the four elements once, at the top — the chip AI RESEARCH, Confidence <n>% and from: public web search, <date>, never edited, the source not linked — then the company fields, each a sentence-case label with its findings, and one source link per finding (§5 External link) beside the statement it grounds, rather than one sources list for the panel. A nothing found body keeps the four elements when an AI call was made, and shows its sentence alone when none was. The panel is not tinted: tone/ai stays read by AiProvenance alone.

Priority panel (Rev 99). The lead view’s Priority panel (F11-g) is a plain §5 card in the score place. Its heading row holds the title, the priority (§5 Status indicators, done only), the hot / cold indicator and Buyer last wrote (§9’s date form) — the last two in every state that has an answer. A ranked body shows the four elements once, at the top — the chip AI RANKED, Confidence <n>% and from: inquiry and research, <date> or from: inquiry only, <date> (the server’s label as given), never edited, the source not linked — then Why this priority with the reason and Recommended next action with the next action, each a card-title sub-heading over its text, and for an inquiry-only ranking one type/meta note naming why research was not used. Every other state shows its sentence alone, in text/secondary, with no error styling for unavailable. The card is not tinted and the next action has no strip of its own: tone/ai stays read by AiProvenance alone.

Card read (Rev 138). The capture app’s card-read check (F36-b, §9 Research and ranking on Leads) shows the elements once, above its sentence, on a read card only — the chip AI READ, Confidence <n>% and from: business card, <d MMM> (the server’s label as given), the source not linked. A badge’s details are not AI output and carry no chip. (Rev 139) Once Edit Details is saved after the read, the chip reads AI READ · EDITED, without BY YOU, because a teammate may have made the edit: the check’s sentence says who (Edited by you, Edited by ).

Applies to every AI surface: lead triage and scoring (F11), inquiry extraction (F12), account briefing (F13), the quote assistant (F14), the AI dashboard (F15), sequence steps (F25) and the capture app’s scoring (F36).

An at-a-glance form exists and may be reused: the capture POC’s score-ring (../forge-et-pwa-poc apps/web/src/components/score-ring.jsx) renders the number inside a proportional arc tinted by band — three channels at once, so it satisfies the colour rule on its own. It is optional here, and useful where a score must be scannable in a list; the numeric percentage is the requirement either way.

6. CRM patterns (src/features, composed from src/ui)

  • App frame: collapsible sidebar (layout/sidebar-width / layout/sidebar-width-collapsed, gradient, logo header, icon+label nav with count badges — text/strong on the neutral fill for counts, accent/gold for alerts; the icon-only rail shows each entry’s label as a tooltip on hover and focus; the selected entry (Rev 78) has a surface/card fill with radius/xs corners (Rev 91), a border/frame hairline ring and shadow/card, a semibold label in text/primary, its glyph in accent/gold-deep, and a border-width/selected bar in accent/gold-deep on its leading edge, inset from the top and bottom, while a hovered entry keeps the plain surface/hover wash and the selected entry keeps its fill under the pointer; (Rev 110) each entry’s glyph is 20px, icon/md plus space/1, and the 76px icon rail still centres it) + layout/topbar-height translucent topbar (actions; F5-b’s inert global-search box is still there outside the Users routes, though F31 was dropped — PRD Rev 60 — and owed.md tracks its removal) + scrolling canvas. The sidebar’s order (Rev 70, not built yet): Leads first, and Pricing before Email; Users and Roles leave the sidebar for the Settings page (§8), so it reads Leads, Accounts, Contacts, Pricing, Email, Settings. The sidebar’s order is also the landing order (Rev 44), so a user whose role reaches Leads lands on Leads after signing in.

  • List screen (Rev 70, not built yet on every screen): every CRM list screen is a table, laid out as the Users list is (forge-et-fe#201): the title bar with the screen’s primary action, the data bar (search, filters), the table in a card, the pager. Each row ends with a ⋯ menu holding View, Edit, and one action specific to the screen — the demo’s example was Archive on Pricing. Which action each screen gets is decided in that screen’s plan (owed.md). No list table puts action buttons in its rows — not even one or two (Rev 133; §5 Table states the one dialog exception). A plan that wants a row button raises it as a design-system change first. The whole row opens the record, not only its name: a click anywhere on the row opens the record’s page in view mode, as View does, and the row shows a pointer cursor with its hover fill. The row’s ⋯ menu, checkbox and any other control in it act on their own and never open the row. The name cell stays a real link, so the row can be reached and opened from the keyboard, read as a link by a screen reader and opened in a new tab; the click on the rest of the row is a mouse shortcut to the same link. View and Edit open the same page: a row click and View open the record’s page in view mode, which carries its own Edit action; Edit in the ⋯ menu opens that page in its edit mode, at /…/:id/edit (§6 Detail page, Rev 74). A record with no page of its own (a tag) is edited in a Modal from its menu. The one exception is Email (/email), which keeps its message list. The data bar sits above the table’s card, outside it (the Contacts page included, Rev 74), and on the account, lead and contact lists ends with Columns at its inline end (Data table › Column configuration, Rev 108). A filter that takes several values is a multi-choice select (Rev 99): the same trigger as a single-value select — the name inside it, then the value (Priority: All, Priority: P1, Not ranked) and the chevron — opening a popover of checkboxes, one per value, each named by its label, in a group named by the filter; none checked is All, so there is no All row. Each toggle applies at once with the popover left open; Tab moves through the boxes, Space toggles one, Escape closes it and returns focus to the trigger. A long list scrolls inside the popover, and typing moves through it (Rev 106): the popover is no taller than the space between the trigger and the viewport’s edge, and its list scrolls within it; with a box focused, typing letters moves focus to the next box whose label starts with the letters typed within half a second, wrapping at the end, as a single-value select’s typeahead does; while such a burst is under way Space is part of the search (united k reaches United Kingdom) and does not toggle the box. forge-et-fe src/ui/filters/FilterMultiSelect.tsx; first used by the Leads list’s Priority filter (F11-g FR-V4), and since F32-d by every vocabulary, owner and tag filter on the account, lead and contact lists (Rev 106). Less-used filters go in More Filters (Rev 110): a data bar that would otherwise run to several rows keeps its main filters in the row and the rest in a More Filters popover — an outline button at the data bar’s 40px height with the filter icon, reading More Filters (n) while n of its filters are applied, opening a shadcn Popover named More Filters that holds the same controls, one per row, each named as it is in the row (inside its trigger, or by a switch’s visible label). The controls keep their URL state and test ids, Clear Filters clears them too, a control’s own popup opens over the popover without closing it, the first Escape closes the inner popup and the next the popover, with focus back on More Filters, and Tab leaves it as the multi-choice select’s popover does. Inside the popover every trigger that opens a list is as wide as its row, so the triggers line up; a switch keeps its own width. On the Leads list the row is Search, Owner, Pipedrive Owner (while the hand-out runs, F32-c), Priority, Hot / Cold, Sort, More Filters, Clear Filters, and More Filters holds Country, Buyer Type, Lead Source, Tag, AI Tag, Shared with me and Existing customer?. (Rev 147) On the account list the row is Search, Customer Type, Country, Owner, Pipedrive Owner (for a hand-out role), More Filters, Clear Filters, then Columns, and More Filters holds Region, Tag, Shared With Me and Show Archived. Its filters wrap inside a group of their own and the Columns / Save View cell keeps to the end of the first line, so Clear Filters or a wider trigger never pushes it down; below about 600px of content the cell wraps under the filters. forge-et-fe src/ui/filters/MoreFilters.tsx, so the account and contact lists can take it later. The title bar’s primary action is shadcn’s default button — Create user, New account, New role, Compose (on Email below bp/laptop only; from it, Compose is at the top of the folder pane — Rev 95 (Rev 110) on Email the header’s last action at every width) — never the older gold one (Rev 74). Each screen’s target and status: shadcn-backfill.md § Target layouts.

  • Screen header (Rev 76): every list screen’s header is src/ui’s PageHeader, and every record’s page keeps PageHeading (§6 Back navigation, Rev 74) around its title. The title is an h1 drawn by PageTitle: the size every record page’s title has (type/title, 24px, bold — Rev 74, resized at Rev 109), in text/heading, with no margin and tabIndex={-1}. A list screen’s actions sit at the title row’s right end, the primary one last (Rev 72); the title and the actions are centred on one line — align-items: center, never a baseline or a nudge — and the actions wrap under the title when the row is short. A §5 Section settings affordance, when a screen has one, is the first of the actions (Rev 84). A list below a section (Settings › Users) takes PageHeading’s breadcrumb and back arrow through PageHeader’s breadcrumb. A list screen carries a one-line description beneath the title, starting where the title starts, at type/secondary in text/secondary, linked to the heading with aria-describedby, with no closing full stop (§9); other screens may carry one. A purpose-built header that carries more — a record’s marks, facts or a meta line — still uses PageTitle for its h1. Nothing styles h1 globally (base.css stays identical with the capture app’s), so a raw <h1> in src/features fails src/app/pageTitleOnly.test.ts.

  • Two-pane list + detail (superseded for the CRM’s list screens by List screen above, Rev 70, except the Email inbox, a mail reading pane — Rev 73): queue/list column (layout/list-pane-width, filter pills + status filter) beside a detail column — the Lead Triage, Quotes, and Samples pattern. At bp/desktop and bp/laptop the list stays visible and selection highlights; at bp/tablet it collapses to a single pane, where the list drills into the detail and returns via the back affordance below (§9 carries the full reflow table). On the Email inbox the data bar above the panes is the List screen’s: the search box nine space/8 steps wide, as on every list screen, and each filter (~~Folder below bp/laptop, ~~Category) as wide as its text (Rev 101, which replaced Rev 84’s search lined up with the columns). The Email list is one card (Rev 101): the Focused / Other tab strip (§5 Tabs, line variant) across its top on the Inbox, the rows, which alone scroll, and the pager at its foot; from bp/laptop the card runs to the bottom of the window, level with the folder pane and the reading pane. The Email folder pane (Rev 95), from bp/laptop only, is drawn as Outlook’s: a collapse button and Compose at its top, then Mailbox (Inbox, Sent Items, Archive, each with its icon) and Your folders, each folder with subfolders folding them away from a chevron button before it, unread counts as the sidebar’s count badge; collapsed, a rail as wide as the collapsed sidebar with a tile per Mailbox folder and one Folders tile, the choice kept per browser. (Rev 147) On a tile the count badge sits at the icon’s top-right corner: it starts space/2 past the icon’s centre and grows toward the tile’s end, never over the rest of the icon, with space/2 inline padding, and a tile draws a count above 99 as 99+; the open pane draws the exact count. The Scheduled entry (Rev 111, F20-g) sits in the Mailbox group after Archive, before Your folders, with the schedule icon, and on the rail as a tile after the Mailbox folders’ tiles, before the Folders tile; its count badge is the number of emails waiting to send, not an unread count, and when a scheduled email has failed a tone/danger dot named Failed follows the badge; it shows only while the user’s mailbox is connected, and shows its name alone while its count loads or after the count fails to load. Below bp/laptop the folder picker and the header’s Compose stay. (Rev 110) One card, Compose in the header, a Folders drawer: from bp/laptop the folder pane (or its rail), the list and the reading pane sit in one card, with no gap between them, separated by 1px rules in the card’s border colour, each pane scrolling on its own; this replaces Rev 86’s three cards space/5 apart, and the list card above is the middle pane of this one. Compose is the page header’s last action at every width, the primary action at the right end, and is no longer in the folder pane or the rail (replacing Rev 95’s Compose at the pane’s top). Below bp/laptop a Folders outline button with the folder icon, at the start of the data bar, reading Folders: as a filter shows its value, opens a shadcn Sheet drawer from the inline-start edge, titled Folders, holding the same folder tree, Scheduled included, with its loading and failure states, and F20-g’s /email/scheduled puts the same button, reading Folders: Scheduled, under its header; it opens with focus on All mail (Radix’s default skips links), or on the drawer’s first control while the tree has no link; choosing a folder closes the drawer and moves focus to the message list, and Esc or the ✕ closes it with focus back on the button. While the drawer is closed the tree’s failure panels show above the list, as before. The Folder picker (Rev 86’s shadcn Select) is removed. (Rev 130) F20-g’s /email/scheduled is the exception to the one card: it draws the inbox’s header (Email, its line, Mailbox Settings, Refresh, Compose; Mailbox Settings and Compose shown as the inbox shows them for the same connection state, Refresh whenever the list shows) and, while the mailbox is usable, the inbox’s data-bar row with the search box’s room kept empty and inert; from bp/laptop the folder pane is a card of its own and the list is the List screen table card beside it, as tall as its rows, space/5 apart, tops level. Without a usable mailbox, /email’s not-connected prompt carries a Scheduled outline button below its next-step button (stacked, so the next-step button does not move when it arrives), with the entry’s icon, count and failed dot, when the user has a scheduled, failed or uncertain email. An acceptance criterion written against this pattern must say which breakpoint it asserts.

  • Kanban board: horizontally scrolling columns (width: max-content), column header = colored dot + type/button name + count, cards = white radius/sm mini-cards. Board/list toggle via segmented control.

  • KPI row: 4-up stat cards (value type/stat, label micro/eyebrow, delta in tone color). A stat stays at type/stat (20px), below type/title (24px), so it reads as a value rather than a heading.

  • Filter pills row: wrap-flex of toggle pills (priority, status) above lists. (Rev 85) Each pill is a shadcn Button, size sm, rounded-full: the default variant (the primary fill) for the filter in force and outline for the others, as the Leads status pills draw them. A pill that only changes the screen’s state is a <button> with aria-pressed; one that changes the URL (the Weekly prices status filters) is the same Button drawn on a link (asChild) with aria-current.

  • Activity timeline (F1-c; Rev 65): a Card (§5 Card / Panel) headed with the panel’s name at type/card-title (the account page’s Communication timeline), holding an ordered list, newest first, entries space/5 apart. Each entry is two columns:

    • a marker — a space/4 filled circle, no border, in its kind’s colour (table below), centred on the first text line by a box one type/body line high, and hidden from assistive technology;
    • the text — the kind’s name (type/body, text/strong) then the summary (type/body, text/primary, wrapping anywhere), then a meta line (type/meta, text/secondary) with the date and time (§9, absolute — Fri 18 Sep, 14:05) and by , or System for a row no person wrote.

    The kind is always named in text (§2); the colour is decoration. Older entries load 20 at a time with Show older entries below the list; after each load focus moves to the first newly shown entry, and one visually hidden status line announces older entries shown. Entries carry no link and no action in V1 (F20-f adds Reply on email rows). The empty state is the icon and one line, Nothing on this account’s timeline yet., with no action — an exception to §5’s “primary action”, because the timeline’s rows are written by other panels. (Rev 77) The entries are grouped under headings — by Colombo day for the last two weeks (Today, Yesterday, then the date) and by month before that, where each entry also shows its date — with a quiet line marking a gap of three weeks or more between two entries. The marker is the kind’s icon (the §5 icon registry’s glyph) drawn in a strong tone on a small circle filled with a tint of the same colour, rather than a plain dot; the kind’s name moves from the screen into the entry’s accessible text, read before the summary. Filter chips above the list — All, Emails, Calls, Notes, Samples and quotes, Follow-ups — show one kind at a time; the lead row and any unknown kind show under All only. From bp/laptop the list scrolls inside its card (§6 Record page). The marker per kind, from the revamped colour ramps (forge-et-fe src/features/timeline/timelineKinds.ts and AccountTimelinePanel.module.css):

    Kind Name Icon colour Circle fill
    lead Lead neutral-0 primary-700
    note Note neutral-700 neutral-100
    email Email primary-800 primary-100
    call Call success-800 success-100
    activity Follow-up warning-800 warning-100
    sample Sample success-800 success-100
    quote Quote warning-800 warning-100
    order Order neutral-0 success-800
    any other value Entry neutral-600 neutral-100 (the neutral marker)

    (Before Rev 77: a one-colour dot per kind — lead accent/gold, note text/faint, email accent/gold-deep, call text/secondary, activity (named Activity) tone/notice text, sample tone/neutral text, quote tone/warning text, order tone/positive text, any other text/muted.)

  • Current-user menu (F5-b; the prototype’s role switcher): footer of sidebar — avatar + name + role, opens an upward menu holding Sign out (Rev 88: the mailbox settings are reached from the Email screen’s settings button, §5 Section settings affordance, not from this menu). The prototype uses it to switch the demo between roles; the product has no role switching — each user holds exactly one role, and no role is predefined (AD #34: Empire’s administrator builds them, the six recommended ones included). Navigation follows permission keys, not role names: a nav entry is hidden when the user lacks that entity’s view key (F5-b’s hide rule), and the route is guarded on the same key (F5-k), so typing the URL does not reach it.

  • Back navigation (rule from plans.md): every drill-in sub-view (…/[id], …/new, …/edit) renders a back affordance top-left of the content header; modals use ✕. A sub-view is never a dead end. Its form (Rev 74): a breadcrumb above the title (Settings › Users › Nimal Wickrama; the current page is the last item, not a link), and a back arrow beside the h1 on the same line. The arrow is a small ghost icon button with no fill or border, named Back to (Back to Accounts, Back to Al Rifai Trading), whose arrow lines up with the breadcrumb’s first letter. Below bp/tablet the arrow stays on the title’s first line when the title wraps. Both are done by layout, never by a margin offset (§5): the arrow sits in a box one title line tall, centred in it; its glyph is centred in its hover square, which starts at the content edge, and the breadcrumb is inset by the space beside the glyph so its first letter lines up with the arrow. One component draws it for every page: forge-et-fe src/ui/PageHeading.tsx, with BackLink and shadcn’s Breadcrumb.

  • Detail page: an edit or settings page whose content is one column of forms or cards is one column capped at twice layout/list-pane-width, centred in the canvas (margin-inline: auto), with its back link and header inside the same column. Today these are the user editor, the role editor, an account’s New and Edit pages and the Mailbox page; the account’s New page becomes a Modal (§5 Modal, Rev 70). A page whose content is a wide grid or table keeps the full width; none does today. A record’s own page follows the same rule (Rev 70, not built yet): the account page, a contact’s page and the lead page — what a list row’s View opens — are one centred column like the user editor, not the full width. It opens in view mode, with an Edit action. Edit is the same page in edit mode (Rev 74): Edit — the page’s own or the ⋯ menu’s — opens /…/:id/edit, where the page keeps its breadcrumb, back arrow and h1 (the record’s saved name, never Edit ), the §6 Save bar sits at the top, and the record’s fields replace its details in a card, in the order the view shows them. Saving returns to view mode. Leaving with unsaved changes asks first (useLeaveGuard). It is never a dialog over the page. Today: the account, contact, lead, user and role pages; the email template keeps its own editor page. Opening a contact’s Edit from the account page’s contact list goes to the contact’s page and returns to the account after saving; an archived contact has no Edit. Creating a record stays a Modal (§5 Modal). Every record page’s h1 is the same size (type/title at the h1’s bold, 24px/700, Rev 109) in view and edit mode, the account and lead pages included (Rev 74). The message view and the offboarding sub-view are centred in the same column too (Rev 74) — the message view only as a page of its own, below bp/laptop; in the inbox’s reading pane it fills the pane’s width, inset only by the pane card’s padding, as a mail client’s reading pane does (Rev 84). No new token: layout/* is shared byte for byte with forge-et-pwa. (Rev 56, Rev 58, Rev 70, Rev 74) (Rev 77) A record’s own page is no longer a centred column: the account, contact, lead, user, role and email-template pages take the full canvas width as Record page below describes, and Edit on the account, contact, user and role pages opens a dialog over the page (§5 Modal), not an edit mode with a save bar; the lead page keeps its edit page and save bar. The one-column rule stays for the editors that are still pages (the lead’s, the email template’s) and the Mailbox page, whose cap is 2.5 × layout/list-pane-width (Settings sections, Rev 89). (Rev 82) The email template’s editor is a dialog over its page (§5 Modal), so the lead’s is the one editor still a page. (Rev 96) The lead’s editor is a dialog over its page too (§5 Modal): no record is edited on a page of its own, and the one-column rule above holds for the Mailbox page only.

  • Record page (Rev 77): a record’s own page — the account, contact, lead, user, role and email template — is built from forge-et-fe src/ui/recordPage, so they read as one family:

    • The header (RecordHeader): PageHeading’s breadcrumb and back arrow beside the h1 (PageTitle, Rev 76), the record’s marks and meta line under it, the page’s actions at the right, (Rev 147) each the shadcn Button at the default size (36px, 14px text), so the header’s buttons share one height — (Rev 110) with the page’s primary action last, at the far right, as on a list screen’s title bar (Rev 72): on the account page Edit Account, Archive Account or Restore Account, Compose Email, Add Follow-Up, then Send This Week’s Prices; on the lead page Edit, Archive or Restore, Add Follow-Up, then Approve & Send (Send Follow-Up on an approved lead) — then, where the page has key facts to show (not the role’s page, whose access table is its content), the summary strip (RecordSummaryStrip): the record’s key facts, label above value, in one bordered row that wraps on a narrow canvas.
    • The body in two columns from bp/laptop (RecordColumns: a wide and a narrow column, a rail beside a wide one, or halves), one column below it; or in tabs (RecordTabs: shadcn’s Tabs drawn as an underline bar, the selected tab kept in the address, only the selected panel mounted).
    • The lead page’s cards (Rev 100): on Overview, the wide column opens with the AI summary card, then Follow-ups (F3-a), the contact and inquiry details, Tea requirements, Priority and the participants place; the narrow column holds Customer, Tags, Shared with, Attachments (F33-a) and then Research, each its own card (Rev 110) the AI cards come first: the wide column holds AI Summary, Priority, Follow-ups (F3-a), the contact and inquiry details, Tea Requirements, Custom Fields (Rev 113; drawn only when the lead’s record type has an active custom field), (Rev 147) Attachments (F33-a) and the participants place; the narrow column holds AI Research, then Customer, Tags and Shared with and Attachments, each its own card. (Rev 147) One rule for the account and lead pages: the record’s own content, its files included, goes in the wide column, and the short facts about it in the narrow column, which ends with Tags then Shared with; the account page already held Attachments at the end of its wide column. Below bp/laptop the page is one column, the wide column’s cards first, so AI Research follows the participants place there (RecordColumns cannot lift a narrow-column card; whether it should is open, .forge/owed.md). On Notes and email, the Notes card sits beside a column holding the Follow-up draft card above the Email card. (Rev 145) The Emails card (F20-f) follows the Email card in that column (the emails place after compose).
    • Emails (F20-f, Rev 145): the emails linked to a lead or a contact are an Emails card — a §5 Card of compact rows, one per email, each with its direction (sent or received), subject, sender and the date in §9’s format — on the lead page’s Notes and email tab, in the side column after the Email card, and on the contact page after the notes (the emails place after notes). From bp/laptop the lead’s notes still fill the window, the side column’s cards stack, and the Emails list scrolls inside its card, so the page keeps one scroll bar. An email, from either card or from an email row of the account’s timeline, opens a reading dialog: shadcn’s Dialog (the §5 Modal’s counterpart under AD #39), showing the message in the inbox’s sandboxed message frame, its files as §5 Attachment tiles, the mailbox owner’s name and how many colleagues’ mailboxes also hold it, and its linked records as §5 Badges, each carrying Unlink (a 24px target) whose confirmation shows in place inside the dialog, never as a second dialog; Reply closes the dialog before the compose dialog opens. In the Email inbox, a message linked to a record carries a Linked marker, a §5 Badge with its text, so it is not shown by colour alone.
    • Fill the window from bp/laptop where a column holds a long list — the account’s Notes and timeline tab, a contact’s notes, the lead’s notes: the page takes the canvas height, the columns stretch to the bottom of the window and the list scrolls inside its card, so the page has one scroll bar. The scrolling list is a labelled region (role="region", tabIndex={0}, an aria-label), so it can be scrolled from the keyboard. Below bp/laptop the page scrolls as before.
    • Compact rows in a side card — the account’s Contacts card, the contact’s Contact details, the lead’s Customer card: one row per item, a glyph then the value (a name as a link to its page), with the row’s actions at its end as small icon buttons (IconAction: shadcn’s ghost icon-sm button with one glyph, named by its action, the name in a tooltip on hover and on keyboard focus) or a ⋯ menu. A value the user may copy (an email address, a phone number) has a Copy icon button that shows a tick and Copied for a moment, announced politely, and selects the text where the browser refuses the clipboard. A missing value reads No email address or No phone number in muted text rather than dropping the row. A person is shown by PersonAvatar (the §5 Avatar on shadcn’s Avatar, named by the full name, the initials hidden from a screen reader).
    • Shared with (F5-g): the card shows a summary — the faces of the owner and the people the record is shared with, and one sentence (Nimal Wickrama (owner) and 1 colleague.) — with Manage access, or View access for a reader who may not change it. It opens one dialog, Access to : colleagues added as chips with Share with , the owner’s row, each share’s row with its remove ✕ and an inline confirm, and one line saying who else reaches the record through the reporting line or an all key.
    • Notes (F1-e, F11-f): a quiet composer — one Add a note line that opens to a box whose label is hidden (the line names it), which grows with its text from four to ten lines and cannot be resized by hand, with Cancel and Add note, and a confirm before discarding typed text; each note author first, then the date, the text clamped at four lines with Show more, and a ⋯ menu with Edit and Delete, whose delete confirm sits inside the note.
  • Settings sections (Rev 77): a page that answers a few questions about one thing — the Mailbox page — is one centred column of rows, each row’s name as an h2 with one sentence on the left and its card on the right from bp/tablet, stacked below it (MailboxSection). (Rev 89) Its column is capped at 2.5 × layout/list-pane-width (900px), not the Detail page’s twice: each row holds its question beside its card, and twice leaves both too narrow at desktop widths. The Blocked Addresses row (Rev 151, F20-k) sits between Receiving Mail and Disconnect, or directly after Connection when the page shows only that row, and is not shown on the read-failed render. Its card lists the user’s own blocked addresses and domains as compact rows — the value, an Address or Domain badge, the date added and Remove in the outlined destructive style of Disconnect Mailbox — newest first under Block an Address, then the organisation’s entries read-only under Blocked for everyone by an administrator. Remove asks first in the AlertDialog Disconnect uses; Block an Address opens a §5 Modal (shadcn Dialog) with the value, a radio group This address / This domain and the sentence that blocking stops future email linking while email already linked stays until it is unlinked. The inbox message view’s Block Sender (secondary, leading icon, beside Mark as Unread) opens the same dialog with the sender’s address.

  • Save bar (an edit page whose changes are kept until Save): the page’s Discard changes and Save sit in one row at the top of the column, which stays in view (position: sticky in the canvas) while the page scrolls. While anything is unsaved the row says how much, by record name (“3 unsaved changes to Tea Room”), on the --et-warning-muted tint with its paired text; while nothing is unsaved it says “All changes saved” in text/secondary and Discard changes is unavailable (aria-disabled); whether Save is too is the page’s own rule (it waits for a change on the account, contact, lead and user pages; the role editor’s stays available, F5-d AC-20). While a save runs, Save is busy and refuses a second press, and may point at the page’s status line (saveDescribedBy, Rev 74). Each field, permission choice or tick that differs from the record as loaded carries a border-width/selected inline-start edge in the warning tone and a short text note of the change (“was Manage”, “added”, “removed”), so the change is never shown by colour alone. Save and Discard confirm in a toast (§5) naming the record and the count: “Saved 3 changes to Tea Room”; “Discarded 3 changes to Tea Room” with Undo, which restores the discarded edits. Today: the user editor and the role editor (BUG-191), and the account, contact and lead edit pages (Rev 74), with two exceptions: the account and lead edit pages carry no per-field change mark, and the account page shows no save toast, because the account page it returns to says Account saved (owed.md, “Review three choices the edit pages made”). (Rev 61, Rev 74) (Rev 96) The lead no longer has an edit page, so no save bar: Edit Lead is a dialog (§5 Modal), whose save is confirmed by the same toast naming the lead and the count.

Data table (F32) — selection, sorting, bulk actions, pagination

§5’s Table row covers appearance only. F32 requires “a sortable, column-configurable list/table view, saved filtered views, and bulk actions on a selection” for every core entity, so this is one shared component, not a per-screen build.

Part Spec
Sortable header The whole header cell is a <button>; a chevron shows direction and only the active column shows one. (Rev 83) It has no underline on hover: it is a control, not a link, and the faint up-and-down chevron shown on hover or focus marks a column as sortable. aria-sort on the <th>. Sort is server-side and belongs in the URL, so a sorted view can be linked and reloaded. Every CRM table sorts (Rev 74), through the shared SortableHeaderCell: where the server cannot sort a column and the page holds the whole list, the page sorts it (forge-et-fe src/lib/params/clientSort.ts); a paged list never re-sorts a page, and a column neither can sort keeps a plain header (owed.md lists the server sorting still owed). A sortable column that is not the active one shows a faint up-and-down mark on hover and keyboard focus, so it reads as sortable without a chevron at rest. The Leads list keeps its Sort menu beside the headers, and its URL writes the order as <field>,<dir>
Selection Checkbox column pinned first, from bp/tablet up (§9, Rev 68). The header checkbox selects the current page and reports Selected 25 on this page, with a distinct follow-up action to Select all 340 — never one control silently meaning both. Selection survives sort; it is cleared by a filter change, and the clearing is announced. Built (Rev 39): SelectionHeaderCell, SelectionCell, SelectionAnnouncer and the useRowSelection hook in forge-et-fe src/ui. Used (Rev 104): on the offboarding lists and on the account and lead lists (F32-c), where the selection column is the one pinned column while it shows and its header cell stays at the top with a sticky header row (SelectionHeaderCell’s stickyHeader)
Bulk-action bar Appears above the table when ≥1 row is selected, surface/card-warm, radius/lg, holding the count, the F32 actions (edit field, reassign owner, add activity, enrol in sequence, export, delete) and a Clear. Destructive actions confirm in a Modal naming the exact count. Focus moves to the bar when it appears. Built (Rev 39): BulkActionBar in forge-et-fe src/ui. Used (Rev 104): on the account and lead lists with Change Owner (F32-c), inside the list card above the table; the Change Owner dialog and the pass result are src/ui/bulkReassign (ChangeOwnerDialog, PassResult), the client step src/lib/bulkReassign
Pagination Numbered pages with a total (decided 2026-08-25) — 1–25 of 340 plus page controls and a page-size select, footer-right. Offset-based, on the API shape FS-10 settled (Rev 9): 1-based page and size (default 25, maximum 100; out of range is rejected, never clamped) and an exact totalItems with totalPages in every list envelope. Chosen over load-more or infinite scroll because bulk selection needs stable page boundaries and Select all 340 needs a known total. One pager for every list (Rev 74): ListPager (forge-et-fe src/ui/components/ListPager/), the Users list’s — the range, Previous, the page numbers, Next, and Rows per page where the list offers sizes — on the Accounts list, an account’s standards and a user’s owned records too
Column configuration A menu toggling column visibility and order, persisted per user per entity. (Rev 108) Built: the controlled Columns menu, forge-et-fe src/ui/filters/ColumnsMenu.tsx, the last control of the data bar, at its inline end — (Rev 141) followed only by Save View while the list’s default view is open, the two at one height (BUG-485). It is the multi-choice select’s pattern, a popover of checkboxes and not a Dropdown Menu, because a menu item is reached by arrow keys only and a Dropdown Menu closes on each choice. One row per column of the list: the shown columns in their order, then the hidden ones in the default order, each a box named by the column’s header and its Move Up / Move Down icon buttons. Name is listed, checked and unavailable, and never moves; a hidden column’s move buttons are unavailable, as are Move Up on the first column after Name and Move Down on the last shown one (all aria-disabled, so they stay focusable). A move is announced politely (Country moved to position 3 of 7); Reset to Default Columns closes the list. Each change applies at once; on the default view it is stored per user per list (GET / PUT /api/v1/list-preferences/{ACCOUNT|LEAD|CONTACT}), and the first rows wait for that read. A failed read keeps the default columns, says Couldn’t load your column choice; showing the default columns with Try Again beside the trigger, which stays unavailable until a read succeeds; a failed save keeps the choice and says Couldn’t save your column choice; it applies until you leave this list. Hiding the sorted column keeps the sort. Custom-field columns (F34-b) are future work: this menu lists only the columns a list declares
Saved views Named filter+column+sort sets, personal or shared, as a row of §5 tabs above the table, saved with a Save View action on the data bar (Rev 141). The active view is in the URL. (Rev 116) Built on the account, lead and contact lists (forge-et-fe src/ui/filters/ViewsRow.tsx, src/lib/listViews/useListView.ts). Place: a line of its own between the page header and the data bar (on the lead list, between the header and the status pills), outside the card. A tab list whose panel is the list card: shadcn Tabs in the pill variant, named Saved Views, manual activation (the arrow keys, Home and End move focus; Enter or Space opens the focused view, so moving through the tabs reads nothing); the card is the one tabpanel, labelled by the selected tab, so a change of view never remounts the data bar or the table. Order: the default view’s tab first (Default on every list since Rev 141, which replaced All Accounts, New Leads and All Contacts; not stored), then the caller’s own views, then the views others shared, as the server orders them. (Rev 141) The row is drawn only while the caller has a view to choose — one of their own or one shared with them; with none there is no row, and it appears with the first view to choose and goes with the last. The notices under the row (below) and its status line stay in the page without it, in the row’s place. (Rev 141) The selected tab is filled primary with primary-foreground text (the views row only; §5’s pill tabs elsewhere keep surface/card), and the marks on it keep 4.5 : 1 for their text. Marks are secondary Badges with words: Shared on the caller’s own shared view, Shared by (with (deactivated)) on another user’s, Changed on the open view while the list differs from it. A long name is cut with an ellipsis at max-w-48; its accessible name holds it whole, and (Rev 141) a tooltip with the whole name and marks shows only while the name is cut or the marks are hidden below 768px — a tab shown whole has no tooltip; a name is only ever text. Overflow: the tab list never wraps or scrolls; the tabs that do not fit go into a More Views Dropdown Menu after the list, in order, and the default tab and the open view’s tab always stay. (Rev 119) Each tab is drawn at its natural width (flex-initial, never the pill trigger’s flex-1), the width the hidden measuring copy gives fitTabs; the measuring copy sits in a zero-size, overflow-hidden box, so it adds nothing to the page’s width. Below 768px (bp/tablet, through useMediaQuery(mq.tablet)) More Views moves to a line of its own under the tabs, the tab list is capped at the row’s width, the default tab keeps its whole name, and the open tab’s marks are hidden visually (sr-only, still in its accessible name and tooltip), so its name is cut to the room left; 768px and up are as above. The actions (the open view’s actions and its ⋯ menu — F32-d-WI-3.3; (Rev 141) Save View is not among them: it sits at the data bar’s inline end, after Columns and at its height, shown only while the default view is open, with or without the views row) sit at the row’s inline end, and take a line of their own, still at the inline end, only when the tab list’s minimum (the default tab, the open tab and More Views) and the actions cannot share the row. States: (Rev 141) no row while the views are first read (Loading saved views in the row’s status line, which stays in the page); Couldn’t load saved views. Your views are safe. with Try Again and its reference when that read fails, in the row’s place with no tabs, the list still working; the views kept with Showing saved views from , Try Again and its reference when a re-read fails; (Rev 141) no row with no view to choose; a re-read that changes the views shown announces Saved views updated. The failure lines are danger text at type/meta, as a filter’s read error. The URL: view=<id> beside the list’s own parameters, which are always the list’s state; an unsaved column change of the open view is columns=<key>,…, and the stored column choice is untouched. Changed compares the list’s state with the view as this viewer can open it (the filters as sets, the sort, the search, and the columns in order; not the page or the page size). Notices under the row, text-muted-foreground at type/meta: That saved view is no longer available for a view the caller cannot see (its view= and columns= dropped, the list’s other parameters kept); Part of this view’s filter does not apply to you: for a filter the viewer’s role may not set; and, in danger text, Couldn’t open this saved view; showing the list as linked with Try Again when the view cannot be read for another reason. (Rev 118) The actions and dialogs (F32-d-WI-3.3: src/ui/filters/ViewActions.tsx, SaveViewDialog.tsx, RenameViewDialog.tsx, DeleteViewDialog.tsx; src/lib/listViews/useViewWrites.ts). The slot, in order: nothing with the default view open (Save View is on the data bar, Rev 141); with a view open and Changed, Reset and Save as New View for everyone and Save Changes for its owner; then the open view’s ⋯, Actions for (the row ⋯ menu, RowActionsMenu): its owner’s Rename, Share or Stop Sharing, and Delete, or Delete alone for a holder of settings.users.manage on a deactivated owner’s shared view, and no ⋯ on another user’s view otherwise. The ⋯ sits in the slot, never on a tab (a control inside a tab fails axe). The buttons are outline sm with a leading icon (save, undo, add); the slot takes its controls’ width and wraps them. Save View and Save as New View: the §5 Modal frame at md: Name (required, Enter Name), the box Share with everyone who can see this list (unticked), and on the account and lead lists, while the Pipedrive Owner filter is set, The Pipedrive Owner filter is not saved in a view.; Cancel, then Save View. The new view opens in place of the URL and its tab takes focus. Rename View: md, Name filled with the view’s name; an unchanged name sends nothing. Delete ?: the destructive confirmation at sm, focus starting on Cancel, Delete View in the destructive fill, one sentence by ownership and sharing that names the owner in the administrator’s case; deleting the open view opens the default view, whose tab takes focus. A one-field dialog closes without asking when a name has been typed (✕, Esc, Cancel), where §5 Modal asks first for unsaved edits; focus opens on the frame’s ✕ as the built frame puts it, and Enter in Name submits. Refusals in a dialog: a name problem under Name (Enter a name for the view, Use 80 characters or fewer, the duplicate name); the 50-view limit, a refusal of the list’s filters, sort or columns, a failure and a write not confirmed above the fields with the reference, focus moving to the first problem; a stale rename keeps what was typed and offers Reload. Save Changes, Share and Stop Sharing act at once, with no dialog; a refusal is one line under the row, in a polite region of its own: a failure in danger text with Try Again and its reference; a write not confirmed, or Save Changes refused on the list’s state, in danger text with the reference and no Try Again; a stale version in danger text with Reload View, which opens the saved version as a new history entry, so Back returns to the unsaved changes; This view can no longer be changed. The saved views have been reloaded. muted. Toasts: View saved, Changes saved (naming the Pipedrive Owner filter when the list held it), View renamed, View shared, View no longer shared, View deleted. Focus after a control removes itself (Save View, Save Changes, Reset, Delete, a successful Try Again or Reload View) goes to the tab of the view then open, and only when focus has gone nowhere — (Rev 141) or to Save View when the row has gone (the caller’s last view to choose deleted, or a re-read that leaves none while focus was in the row); after Rename, Share and Stop Sharing it stays on the ⋯
Empty and loading Empty distinguishes no records yet (offer the create action) from no matches (offer clear-filters) — they are different problems and the same message for both is a common annoyance. Loading is skeleton rows, keeping the header and row height so nothing jumps. (Rev 83) A re-read after a sort, a filter, a search or a page change looks the same: skeleton rows in place of the rows, as many as were shown, under the header, with no visible Updating… line above the table; a re-read of the same request keeps the rows; a polite status announces the update

At bp/tablet the table scrolls horizontally inside its card with the first column pinned (§9), and the bulk-action bar stays fixed above it.

There is no global search (F31 dropped, Rev 46; PRD Rev 60). Each list screen has its own search box in its filter row, searching that list’s records only. (The prototype’s top-bar search box is not built. An inert placeholder from F5-b is still on main outside the Users routes; its removal is tracked in owed.md.)

Charts

Three are needed, all described in the PRD, and all hand-drawn in SVG from the §2 tokens — which is what the approved prototype already does, takes no dependency, and keeps them visually part of the app rather than a library’s idea of a chart.

Chart Content Where
Pipeline funnel Stage-by-stage counts and value, Private Label / Bulk toggle, footer stats: open value, weighted forecast (F24 stage probability), won this quarter, in final negotiation Dashboard (F17)
Leads by source Horizontal bars across Website / Trade Fair / Referral / Email / Other Dashboard (F17, from F11’s lead-source field)
Price history Line, green family on surface/card, one series per standard (PRD Rev 23 dropped the per-market axis; the prototype draws one series per standard since 2026-09-15) Account section + Pricing screen (§8, F26)

Rules for all three: never colour alone — every series carries a label or direct annotation, per §2. Values are type/meta, tabular-nums. Each chart has a text alternative — a caption or an adjacent table — so the data is reachable without seeing the picture; a screen-reader user must not be told only “chart”. Empty and single-data-point states are specified, not left to render as an empty box. No animated entry beyond motion/base.

The prototype’s dashboard figures are literal placeholders, not computed (.forge/design/prototypes/feature-detail.md). Treat its charts as a look reference, never as evidence the calculation exists.

Drag has a keyboard equivalent — always

project-prd.md § Accessibility requires “keyboard navigation of lists/boards/forms/calendar”, and test-strategy.md § Accessibility is explicit that an axe scan cannot verify “that a Kanban board can be operated without a mouse” — it is a manual walkthrough, recorded as evidence when the screen ships. So this is a build requirement, not an enhancement.

Three surfaces drag in V1: the pipeline Kanban (F2), the sample board (F6), and calendar drag-to-reschedule (F21).

The required non-drag path is an explicit move action on the item itself — Move to stage…, Move to round…, Reschedule… — reachable by keyboard from the focused card, opening the §5 dropdown menu of valid targets. It is the required path rather than a fallback for three reasons: it is discoverable (a visible menu item, not an undocumented key combination), it announces itself to a screen reader, and it is also the usable path on tablet, where dragging a card across a horizontally scrolling column is awkward at best. An emulated keyboard drag (pick up / arrow / drop) may be layered on top; it never substitutes for the move action.

Each of the three surfaces must therefore satisfy:

Requirement Detail
Reach every card by keyboard Cards are in the tab order in visual order, column by column
Move without a pointer The move action is on the card, opens a menu of valid targets, and is operable by Enter / arrows / Enter
Cancel cleanly Esc closes the menu and returns focus to the card, with no state change
Confirm the result The same toast the drag path raises, plus an ARIA live-region announcement naming the item and its new stage / round / time
Keep focus sensible After the move, focus lands on the moved card in its new position — never on <body>

The same rule generalises: if any future interaction is only reachable by pointer gesture, it ships with a keyboard-reachable equivalent in the same work item. Retrofitting one is far more expensive than building it alongside.

7. Tea-domain widgets (src/features + src/ui/fields)

Built from core primitives, never forked: sample round tracker (F6 lifecycle chips + rounds), buying-standard price grid + price-validity banner (tone/notice, F26), certification chips + mismatch warnings (tone/danger, F9), quote readiness checklist (F7 gate — positive/neutral per item, gold CTA when ready), margin entry block, destination-market price history graph (line, green family on surface/card; not built — one price per standard per week has no market axis, and price history is the list under History in the Tea Room’s round, F26-f).

8. Screen inventory (prototype-covered vs to-design)

In the prototype: since Rev 92 the current prototype (prototypes/crm-current/) is drawn to match the built CRM — Login · Accounts (list page; record page with Overview, Buying standards, Notes and timeline) · Contacts · Leads (list page; record page) · Activities · Email · Pricing (Standards, Weekly prices, Auction sales) · Settings (landing page, Users, a user’s page, Roles, the role editor, the three tag pages, Custom Fields, Lead Research (Rev 137), Email templates, Email Block List (Rev 151)) — plus the Phase 2 screens below in the same look, marked not built yet. The frozen original (prototypes/crm/), the client-approved look, has: Login · Dashboard (KPI row, morning briefing, what’s stuck, funnel, leads-by-source, high-priority) · Lead Triage (queue + AI detail, F11/F12/F16) · Pipeline (board + management table) · Accounts (list + AI briefing + contacts/timeline/opps/orders + buying standards & prices, F26/F1) · Samples (board + detail, F6) · Quotes (readiness checklist, line items F26, additional costs F7, margin, approve) · Activities (list/calendar F21, sequences F25) · Pricing (the Buying Standards book — every client’s standards, add / edit / archive, the Tea Room weekly publish flow, reached by permission; F26 — a team proposal, see below. The Products screen was removed 2026-09-15, PRD Rev 27: the standard is the sellable record, so there is no catalog screen) · Inbox (F20) · deal modal (F3 linked activities, F33 attachments).

The Pricing screen and the account’s pricing section are ours, not the client’s. They were added 2026-09-11 to put the bulk-pricing UI where the settled data model says it belongs — a price hangs off a client’s Buying Standard (forge-et-be/docs/data-model.md §2.1), and the Tea Room publishes a round across the whole book. Everything else in the frozen original’s list above carries the client’s 2026-07-03 approval (the current prototype’s added screens — Contacts, the Settings pages — do not); these two do not, and neither do the Import this week’s sheet and Email this week’s prices affordances on them (both mocks, sourced from a September 2026 follow-up meeting with no debrief filed). Read design/prototypes/README.md before citing them as settled. Rendering on them follows §9 exactly, by permission key (AD #34): the Pricing screen and its cost, floor, profit % and LKR build-up render for holders of buying_standard.view (which covers the whole build-up — there is no separate cost key); editing standards, costs and the floor needs buying_standard.manage; the publish controls need price.publish; a role without buying_standard.view has neither the nav entry nor the route. An account page shows that account’s standards with only the final published USD price under account.view. In the recommended configuration the Tea Room holds buying_standard.manage and price.publish and the Administrator holds buying_standard.view (read-only); that split is Empire’s configuration, not code. Until 2026-09-24 this line said “cost/floor/profit % are Tea Room only, publishing is Tea Room only, the Administrator gets the screen read-only” — the same split, written as role rules.

Not in the prototype — design at spec time from these tokens: Executive read-only views, Users & roles admin (F5, all behind settings.manage since Rev 71; access.manage before) — user list, create-user with its one role assigned at creation (the administrator pre-creates every user; no invitation), role change, manager (“reports to”), deactivate and reactivate (never delete; a refusal names what blocks it — the user is you, is the last administrator, has direct reports, or owns records) — F5-c; the roles editor over the catalog — F5-d; the effective-permissions viewer — F5-e (mechanics settled by AD #34, answering OQ-51) — Record sharing (F5-g) — the share list on a record and the share picker, which offers only eligible people (§9) — Bulk reassignment (F5-h) — moving a leaving user’s records to someone else before deactivation (Rev 100: inside the Deactivate User modal; there is no separate offboarding screen or Offboard User link) — Admin config (F24/F34), Import/Export (F23), Settings/mailbox connect (resolved 2026-09-23, Rev 25 — the mailbox connect screen is /email/mailbox, designed by F20-a, and the way in from its section is the §5 Section settings affordance: a ghost-icon button beside the section’s screen title, built by F20-b on /email. A later section that needs a settings sub-view uses the same affordance rather than inventing a second one), Settings › Tags (F1-e, Rev 44) — configuration shared across sections is reached from a sidebar Settings entry, last in the sidebar and shown only to settings.manage holders; its first page renames, colours, retires and restores the account, contact and lead tags. Settings becomes a page of links (Rev 70, not built yet): /settings lists the configuration items — the lead, account and contact tags, the email templates, Users and Roles (which leave the sidebar) and any later one — and each opens its own page, in place of the tabs it shows today. One permission opens all of it (Rev 71): the Settings entry, the page and every item on it — the tags, the email templates, Users and Roles — are shown and guarded on settings.manage, which AD #34 (refined 2026-10-26) makes the one key for configuration and for user and role administration; the seeded IT Admin role holds it. email.manage opens none of them. Each card still names its key, so an item can take a permission of its own if Empire asks for one (owed.md). The page’s layout (Rev 74): the cards sit in named sections — Users & administration (Users, Roles), Tags (Account, Contact and Lead tags), (Rev 137) Records (Custom Fields, F34-c), Research (Lead Research, F11-i) and Email (Email templates, and (Rev 151) Email Block List, F20-k) — each section a type/subhead heading with a one-line description over a rule, then a grid of three equal cards a row, which wraps to fewer as the page narrows and keeps the three columns when a section has fewer cards. On each card the icon, in its tinted square, sits beside the card’s title, with the description under both at the card’s full width; the whole card is the link. (Rev 83) A card shows the pointer with its hover fill and no underline on its title. A Settings page holding one setting (Rev 137, Lead Research): the title bar (breadcrumb, back arrow, h1, the card’s line), then one card at the page’s content width holding a §5 Switch whose label says what on means, with its explanation under the label in text/secondary and Last changed by , . in the note style once a person has changed it. (Rev 147) The card is a settings row: the label, in the card-title weight, leads the first column with the explanation and Last changed by under it; the second column, at the row’s end and centred on the label’s line, holds On or Off in text/secondary (drawn only, as the switch says its state) and then the switch; the explanation never runs under the switch. The switch saves when flipped, with no Save button; it is aria-disabled and keeps its value while the write runs, then shows the outcome: saved — a success toast; changed by someone else (409) — the page re-reads and an inline notice above the card says so, until the next flip; refused, or an outcome that could not be confirmed (then re-read) — a failure toast with Dismiss. (Rev 151) The Email section’s line reads Saved text to start an email from, and addresses whose email is never linked to a record. The Email Block List page (Rev 151, F20-k) (/settings/email-block-list, on settings.email_block_list.manage) uses the tag pages’ title bar and §5 Table: the organisation’s blocked addresses and domains with Address or Domain, Kind, Added By and Added, newest first, Remove in the row’s ⋯ menu behind the same AlertDialog as the Mailbox page’s, and Block an Address in the title bar opening the Mailbox page’s dialog; empty, it reads No addresses are blocked for everyone. Each tag page’s table is the §5 Table (Rev 74): the status as a dot and a word, Edit and Retire or Restore in the row’s ⋯ menu; (Rev 100) the Name column is the tag’s name as plain text, and the Colour column draws the tag’s look — the record’s tag badge in the tag’s tone — holding the colour’s word (None, Neutral, Positive, Notice, Danger), so the colour is still not the only signal (WCAG 1.4.1) — Contacts (F1-f, Rev 50) — a Contacts sidebar entry after Accounts opens /contacts, a list on the §6 data-table pattern with search, an archived switch and, for account.all holders, a No account filter; a contact’s name opens a read-only contact view (a §5 Modal) holding F1-e’s tags and notes; edit, archive, restore and Attach to account are row actions (since Rev 70 the contact has its own page, and since Rev 74 it is edited on that page; a contact’s email address and phone number are plain text in the table, on its page and in the account page’s contact list — never a mailto: or tel: link) — Email templates (F20-d, Rev 62) — moving to Settings (Rev 70, not built yet): the templates become a Settings item, reached from the Settings page rather than the inbox header, because they serve the drafts other screens generate (leads, pricing), while mail on the Email page is written by hand; the route under Settings is set in the PR that moves them. Today /email/templates, reached by the inbox header’s Email templates button (Rev 59), is a Rev 41 list — the title bar with New template, a data bar of Shared / Mine tabs and a name search, the table (Name, Subject, Last changed) in a card; its editor ((Rev 82) now a dialog over the template’s page), /email/templates/new and /email/templates/{id}, is a §6 Detail page holding Name, Subject and the rich-text body with Insert merge field; the compose dialog’s toolbar gains Insert template — and the capture app’s re-theme (its own PWA shell, same tokens — the screens come from the POC, ../forge-et-pwa-poc apps/web, whose ad-hoc Tailwind values are remapped onto these tokens; open item 5). There is no audit-viewer screen in V1 (AD #36). The prototype’s sidebar role switcher is a demo affordance, not a management screen — see §6.

9. Conventions

  • Capitalization (Rev 90): Title Case for titles, navigation, actions, field labels and the CRM’s placeholders (Rev 107); sentence case for everything else.
    • Title Case: the navigation; every title — a screen’s, a card’s or section’s, a modal’s (a question included: Archive Contact?, Leave Without Saving?), a tab’s, a fieldset’s legend, an empty state’s heading; every button and menu item that acts; a link that stands on its own (Show More, Back to Accounts); a table’s column headers; a field’s label, on a form and in a record’s read-only view; in the CRM, a field’s or a search box’s placeholder (Enter Company Name, Search Leads, Find or Create a Lead Tag — Rev 107); and the accessible name of an icon-only button. For example Account Tags, Mark Done, Generate Quote, Save Changes, Sign Out, Last Contacted, Email Address, Buyer Type. A column header and the label of the same field read the same.
    • Sentence case: the capture app’s placeholders (the CRM’s are Title Case, Rev 107), the words shown in a placeholder’s place while it loads (Loading types), a search box’s aria-label (Search leads, which its placeholder repeats in Title Case), helper text, tooltips, descriptions, every message (a toast, an error, an empty state’s sentence, a banner), a link inside a sentence, a checkbox or radio label that reads as a sentence (“Send me a copy”), and the values the app shows — a status, a tag, a product line, a badge, a filter pill, a select’s options, a radio option that is a value, and a menu whose items are values (a filter or status menu) (“In progress”, “Private label”). A toast keeps sentence case even when it repeats a button’s words (Archive Contact → “Contact archived”), and a field’s error message keeps it when it names the field (“Email address is required”).
    • How a title is cased: capitalise the first and the last word and every word between, except these short words: a, an, the, and, but, or, nor, for, so, yet, as, at, by, in, of, on, per, to, via, vs. These particles take a capital when they follow a verb: In, On, Out, Up, Off, Down (Sign In, Turn On, Sign Out, Follow Up, Log Off, Set Up); a test helper takes both lists. Each part of a hyphenated word is capitalised (Sub-Floor Approval, Follow-Up), as is the word after a colon. Names, codes and units keep their own casing (Microsoft 365, FOB, ISO 22000, Pipedrive, Price per kg, USD/kg), and a name the user typed (a record’s, a tag’s) is shown as typed, also inside an icon-only button’s name (Remove Tag followed by the tag’s name).
    • Unchanged: UPPERCASE only through the micro/eyebrow style; no trailing period on a label or a one-sentence helper.
    • Scope and the move over: the CRM (forge-et-fe) and, since Rev 105, the capture app (forge-et-pwa), whose screens are cased by the same rule. A new screen or dialog is built in Title Case; an existing screen keeps sentence case until the PR that recases it, which recases the whole screen, so no screen mixes the two. A label quoted in an earlier revision, elsewhere in this document or in an approved spec keeps the casing it was written in and is read in this rule’s casing; but a spec whose requirement or acceptance criterion states the casing rule itself (F1-b, F1-d, F1-e, F1-f, F11-b, F11-d, F11-f, F12, F20-a, F20-b, F20-d) gets a revision in the PR that recases its screen. A test that asserts a label’s text changes in that PR.
  • One word for one action, the same on every screen (Rev 133):
    • Creating a record: the button that opens the flow and the dialog’s title read New (New Lead, New Account, New Role, New Sale); the dialog’s submit reads Create . Every place that opens the same dialog (a tab, a warning, an empty state, another page) uses the same words.
    • Trying a failed action again: Try Again on every screen of the CRM, never Retry (Rev 132, BUG-447). A section of this document that still names Retry is read as Try Again.
    • A field: the same label on the create form, the edit form and the table’s column header (Starts and Ends, not Start Date on one and Starts on another).
    • A plan checks its screen’s buttons and labels against these and against the screens already built, and frontend-reviewer checks the diff.
  • data-testid on interactive elements that semantics cannot uniquely address — <feature>-<element>[-<qualifier>]; selectors prefer getByRole/getByLabel first (coding-standards.md §4).
  • Icons: see §4 — lucide-react at icon/stroke 1.75, imported through the concept registry.
  • The page title follows the route (WCAG 2.1 SC 2.4.2, Level A): every route sets document.title to <Screen name> — <App name>, the app name being the one in index.html (Accounts — Empire Teas CRM, Capture — ET Capture), with the record’s name first on a record page once it has loaded (Ceylon Leaf Ltd — Accounts — Empire Teas CRM). The screen name is the route’s handle.title in the route table — a record route’s is its section’s name (roles/:id → Roles) — read by one component in src/app (RouteTitle in forge-et-fe), never set by hand in a feature; a record page publishes only its loaded record’s name, with useRecordTitle (src/lib/recordTitle.tsx), and RouteTitle puts it first. A unit test fails a route with no title. Axe does not catch a missing title, so the size matrix asserts it on every page state.
  • Dates: Fri 18 Sep in-app; add the year only when the date is not in the current year. Date inputs use the browser’s locale format (§5) — that is correct, not a deviation.

Money, weights and percentages

A tea-export CRM is mostly numbers, and until now the only rule was “tabular-nums”. These are presentation rules. They deliberately do not set precision or rounding: coding-standards.md § Formatting is not computation puts those server-side, once, “so the displayed figure and the stored figure cannot disagree”. The UI renders what it is given.

Kind Renders as Grounding
Money ISO code then amount, thousands-separated, 2 decimals — USD 85,000.00 Never a bare $: Empire quotes into 70+ countries and a lone symbol is ambiguous. USD is the base; other currencies are display conversions (data model §2.10 R2)
Unit price USD 4.25 / kg — at least 2 decimals, up to 4: trailing zeros are trimmed down to two, and a non-zero digit is never dropped (11.2500 → USD 11.25 / kg, 11.2575 → USD 11.2575 / kg — Rev 33, F26-b Q-15) Stored NUMERIC(12,4), but the data model notes price moves “are quoted in cents”, so cents are the meaningful unit. The UI trims rather than rounds, because it renders what it is given. Confirm against the real Tea Room price list when it arrives (~late Sep) — if quotes never move in fractions of a cent, the four-decimal case simply never appears
Quantity / weight kg, thousands-separated, trailing zeros trimmed — 20,000 kg, 1,250.5 kg Stored NUMERIC(14,3); uom defaults to kg
Margin / GP % One decimal — 32.4% Server-computed as (unit_price − cost_at_quote) / unit_price. The client never computes this — coding-standards.md treats a client-derived margin as an authorization hole, because F7’s floor gate depends on it
Probability / confidence Whole numbers — 70%, 87% Stage probability and AI confidence are both 0–100 integers

Four rules that apply to all of them:

  • Never convert units for display. 20,000 kg stays 20,000 kg — it does not become 20 MT. A rep comparing one figure in kg against another in tonnes will get it wrong, and the conversion buys nothing.
  • Separators are fixed, not locale-derived — comma for thousands, point for decimals. The app is single-locale English; a separator that varies by browser makes a screenshot pasted into an email ambiguous about whether 4,250 is four thousand or four and a quarter.
  • Absent is not zero. A missing value renders —, never a blank cell and never 0. This is load-bearing: the data model notes a null cost makes the margin expression null, and a null margin displayed as 0.0% would read as a catastrophic loss on a quote that simply has no cost recorded yet.
  • Negatives take a minus sign — −USD 1,200.00 — never parentheses, and never colour alone (§2).

Numerics are right-aligned in tables and always font-variant-numeric: tabular-nums, so columns of figures line up digit-for-digit.

Viewport and breakpoints — bp/*

Desktop-first, tablet supported down to 768px. project-prd.md § Accessibility commits to “usable on desktop and tablet” and test-strategy.md § Browsers & Viewports asserts a tablet viewport on every core screen, so tablet is a build target rather than a courtesy. The previous 1024px floor excluded portrait tablet, which would have left the test suite checking a width nothing was designed for.

Token Min width Target
bp/tablet 768px Tablet portrait — the floor. Below this is unsupported for the CRM
bp/laptop 1024px Tablet landscape / small laptop
bp/desktop 1280px The design target — every screen is drawn at this width first

What reflows below bp/desktop: (proposed — same status as the §3/§4 scale values: these behaviours are design calls not yet verified against any built screen; confirm each on screen at FS-3)

Region ≥1280 (design target) 1024–1279 768–1023 (tablet portrait)
Sidebar (§6) Expanded, layout/sidebar-width Collapsed to icons, layout/sidebar-width-collapsed Collapsed; opens as an overlay, not a push
Two-pane list + detail (§6) Side by side Side by side, list at layout/list-pane-width Single pane — the list drills into the detail, with the §6 back affordance
KPI row (§6) 4-up 4-up 2-up, two rows
Kanban (§6) Horizontal scroll Horizontal scroll Horizontal scroll, roughly one column in view
Content gutter space/7 space/7 space/6
Tables (§5) Full columns Full columns Horizontal scroll inside the card; first column pinned, and the row ⋯ column pinned at the end (Rev 94)

Touch targets: 24 × 24px minimum, which every §5 control already clears. This is what the contract requires — the PRD targets WCAG 2.1 AA, and the applicable rule is WCAG 2.2’s SC 2.5.8 Target Size (Minimum) at 24 × 24. The familiar 44 × 44 figure is SC 2.5.5, Level AAA, plus a platform convention (Apple HIG), not a conformance requirement here. The distinction matters: 44 × 44 would make §5’s 36px compact control unusable on tablet and remove a variant the dense table and toolbar layouts depend on, so layout/control-h-compact stays available at every breakpoint. If Empire later asks for AAA, that is a costed change request, not a default.

Phone layouts (<768px) stay out of V1 scope for the CRM — the capture app is the mobile surface, and it needs its own touch scale (open item 11). But every CRM page reflows at 320 CSS px (lead decision, 2026-09-27): WCAG 2.1 SC 1.4.10 Reflow is Level AA, and 320px is what a 1280px desktop shows at 400% zoom. Below bp/tablet a page stacks to one column with no horizontal page scroll and no control clipped off-screen; content that is genuinely two-dimensional (the Kanban board, wide data tables) may scroll inside its own region, as SC 1.4.10 allows. A data table’s first column is pinned only from bp/tablet up; below it nothing is pinned and the table scrolls inside its region, because at 320px a pinned column can leave less room beside it than the last column needs, which puts that column’s controls under it (Rev 68). Wherever the first column is pinned, a table’s row ⋯ column is pinned at the inline end too, so reaching a row’s menu never scrolls the table (Rev 94). This is zoom support, not a phone design — no phone-specific pattern is built for the CRM.

Tablet is a PRD commitment, not a proposal commitment. The accepted proposal never uses the word tablet — it commits only to “a responsive web application”. So the 768px floor is a team decision (2026-08-25) taken to satisfy the PRD and the test suite, not something the client bought, and the per-screen reflow work it implies lands against R-ARCH-001’s already-thin window. Raising the floor back to bp/laptop remains a legitimate scope lever.

The capture app (F36) — the mobile surface

This document’s header says it is consumed by “the capture app’s visual alignment”, and until now it said nothing about phones. The CRM’s floor is bp/tablet; the capture app is the phone surface and takes the same tokens with three deliberate departures.

Phone first, and tablet and desktop supported too (lead decision, 2026-09-27). The capture app is designed at phone width, but it must also work on a tablet (768–1023px, portrait and landscape — a rep may carry an iPad at a stand) and on a desktop browser (≥1024px — reviewing captures at a desk). At those widths the phone layout holds, centred in a readable column with a maximum content width rather than stretched edge to edge; the 44 × 44px targets and 14px body text stay at every width; nothing scrolls horizontally; and it works in both orientations (never locked — WCAG 2.1 SC 1.3.4). Like the CRM, it reflows at 320px.

Departure Capture app CRM Why
Target width 360–430px ≥768px It is used one-handed, standing, in an exhibition hall
Touch target 44 × 44px minimum 24 × 24 (§9 viewport) Not a conformance rule — a usability one. A rep is standing, holding a phone in one hand mid-conversation, often in poor light. The CRM figure is the AA floor for a seated user with a mouse; it is the wrong figure here
Body type type/secondary and type/meta step up to 14px, so all running text is 14px type/body is 14px; type/secondary and type/meta are 12px 12px at arm’s length under exhibition lighting is too small

How the capture app implements the body type and the column (Rev 32). forge-et-pwa/src/ui/styles/capture.css is the capture app’s own token layer — not one of the files it copies from forge-et-fe, and loaded after the theme so its values win. It re-values type/body, type/secondary and type/meta to type/card-title’s size at type/body’s weight, so every line of running text is at least 14px at the body weight; it leaves the uppercase type/micro eyebrow as it is. It also declares layout/capture-column-max (--et-layout-capture-column-max, 480px, §4). From bp/tablet up, the shell’s header row, the connection bar’s row, the screen’s column inside <main> and the bottom tab bar’s row sit in one centred column no wider than that token, with the space/6 gutter inside it, all lined up for any safe-area insets; the header bar’s and the tab bar’s background and border, and <main> itself, span the viewport, so the space beside the column scrolls <main> too (Rev 125). Below bp/tablet the phone layout is unchanged. The shell has no side menu at any width: the header and the bottom tab bar are the chrome at every width (Rev 120). The bp/tablet condition is read from breakpoints.ts at runtime (a hook switching a class), never written into a CSS @media (§ Theming mechanics rule 3).

The tab bar’s selected tab (Rev 121). The selected tab’s icon and label are accent/gold-deep and its label is semibold (type/button’s weight), with aria-current="page"; there is no bar or line above, below or beside it, and §5 Selected’s gold bar does not apply to this tab bar. The weight is the cue that does not depend on colour (WCAG 1.4.1): the selected and unselected label colours are about 1.04 : 1 apart. Hover, where a pointer can hover, is the surface/hover wash only.

Everything else — colour, radius, spacing, motion, the status-indicator and AI-provenance rules — is shared. Open item 5’s retheme maps the POC’s ad-hoc Tailwind values onto these tokens; it does not fork them.

Shell chrome. Respect env(safe-area-inset-*) on all four edges — notches and home indicators, which no desktop layout has to think about. Detect standalone display mode and drop any in-app browser affordance when installed. The install prompt is a dismissible card, shown only when the app is genuinely installable, with an install message as the fallback on iOS, where no browser offers a prompt (the POC’s install-banner began this). (Rev 148, F36-a Rev 7) On iOS that message is one line in the card’s secondary text (type/meta), the same on an iPhone, an iPod and an iPad: In Safari, tap Share, then Add to Home Screen.; there is no list of steps, and the card keeps Not Now. The card shows on the same devices and browsers as before (isIos()). The wording is checked against the iOS and iPadOS Safari current at the build. The camera needs a secure context, which is why the POC serves dev over HTTPS. The main area is the only thing that scrolls (Rev 125): the shell fills the viewport, the header and the bottom tab bar stay fixed at its edges, and <main> between them scrolls, so the tab bar never covers a control at any page length or size, as the CRM’s shell does; a route change starts <main> at its top.

A failed upload is a set of states, not an error (revised 2026-10-11, Rev 47). The app opens with no signal (its shell is cached), and architecture.md § Trade-Show Capture App requires that a capture whose upload fails is kept on the phone and sent again when the app is open with a connection (F36-a, PRD Rev 64). There is no background sync and no full offline mode: the earlier design here, an offline queue that sent on its own, was F36-e, which is dropped.

State Renders as
Online No indicator. Connectivity is not news
No connection A persistent bar at the top of the shell — tone/notice, one line: No connection — captures are kept on this phone and sent when you're back online. It reassures rather than warns, because the rep can keep working
Not sent A capture whose upload failed appears in the list with a Not sent status indicator (§5 — dot + label, per the colour rule), and the shell shows the count. The list is Not Sent · on This Phone under Submit for Research on Capture; the count is a tone/notice banner on Leads with View, which opens that list (Rev 123). A capture sent while online and still awaiting its first answer is not listed: it joins the list only when that send ends without a confirmation, at once when accepted with no connection, and Kept on this phone. It’s sent when you’re back online. is its toast (Rev 123)
Sending When the app is open with a connection, each Not sent item becomes Sending and clears individually as it lands, never all at once; a Send Now control on the list’s label row starts it by hand, and with no connection it is unavailable with Sending needs a connection. under the label (Rev 123). The count of those sent is a toast, 2 captures sent. (Rev 123)
Refused tone/danger on the individual item with the reason and Try Again — for a refusal the server gave, not for a lost connection. It stays on the list until the rep removes it (Rev 123). Never a silent drop, and never a blanket failure that loses which capture failed

Two hard rules. A capture is visibly accepted the moment it is taken — the rep is mid-conversation and cannot wait for a round trip. And nothing is ever lost to a closed tab: a capture that has not been sent is stored on the phone (IndexedDB), not held in memory.

⚠️ The POC does not implement this. Verified 2026-08-25: it has Workbox shell caching via vite-plugin-pwa and an in-memory upload loop, but nothing that keeps a failed capture — no IndexedDB. Its install banner nonetheless says “works offline”. So keep-and-retry is new work in F36-a, not a port (it feeds OQ-55, the F36 scope delta).

Sign-in and sign-out are the CRM’s (Rev 49). The capture app signs in and out with Microsoft through the backend exactly as the CRM does, and follows § Session expiry and return-to-route as written — the same login-screen notices, a deliberate sign-out with no notice, and a sign-out the server does not confirm keeping the rep signed in. On a phone passed between reps at a stand, that last rule is what stops the next rep capturing as the last one. The sign-out control meets the 44px target above. A sign-out with captures not yet sent asks first (F36-a FR-R3, Rev 123): on Settings, the sm Modal Sign Out? says how many there are and, online, offers Cancel, Sign Out and Keep Them and Send Now (which sends them, then signs out when none is left); with no connection the server cannot confirm a sign-out, so Sign Out and Keep Them is unavailable with Signing out needs a connection. under it, and the rep stays signed in with the captures. On No Access a line says how many are kept, and Sign Out is unavailable with the same sentence while there is no connection. A sign-out never deletes a capture: it waits on the phone for the rep who took it.

The camera surface (Rev 122). Capture’s camera panel is a dark surface whose pixels are whatever the camera sees, so no control sits on the live camera view: the shutter, Retake, Scan Again and Choose a Photo are below the panel. The one element drawn over the camera view is the hint chip (Fit one card in the frame), and it sits on a solid backing, never a translucent one, so its text holds its contrast over any frame. Four capture-only colour tokens, declared in forge-et-pwa/src/ui/styles/capture.css and nowhere else:

Token Value Use Measured (themeContrast.test.ts)
--et-capture-camera-surface #1a120b the panel’s fill, and the darker camera-off stripe camera-on on it, ≥ 4.5 : 1
--et-capture-camera-stripe #2c2117 the lighter camera-off stripe camera-on on it, ≥ 4.5 : 1
--et-capture-camera-control #000000 the hint chip’s solid backing camera-on on it, ≥ 4.5 : 1
--et-capture-camera-on #f2ece3 the text on the panel and on the chip —

The panel’s sizes are capture.css layout tokens too: its height (layout/capture-camera-h, 34dvh, between layout/capture-camera-min 180px and layout/capture-camera-max 360px), the round shutter (layout/capture-shutter, 72px) and the framing guides (layout/capture-guide-box 160px, layout/capture-guide-corner 28px, layout/capture-guide-stroke 3px), drawn in accent/gold-bright. When the camera is refused, missing or held by another app, the panel shows the camera icon, one sentence saying which, and what to do next, on the stripes; in Business Card, Choose a Photo is below the panel; in Badge QR nothing is offered, since a badge needs the camera.

The capture app’s toast (Rev 122) is §5’s Toast, placed above the bottom tab bar rather than at the viewport’s foot, so it never covers a tab; its Dismiss ring takes the fill’s paired text colour (§4), and its announcement is a visually hidden role="status" node mounted for the app’s whole life.

The sheet (Rev 124) is the capture app’s bottom-sheet form of the CRM’s Sheet — §6’s Folders drawer on the Email page (Rev 110): a title, ✕ (Close, 44px), Esc to close, and focus back on the control that opened it. Below bp/tablet it is anchored to the bottom edge, full width, its top corners radius/xl, at most 85% of the viewport’s height, rising with motion/slow (none under prefers-reduced-motion); from bp/tablet it is a centred layout/dialog-sm dialog with every corner radius/xl, the breakpoint read at runtime as for the column. It is built on the native <dialog> opened with showModal(), because the capture app has no component library: the page behind is inert, and its body scrolls inside the sheet under a fixed header. Focus moves to its title when it opens. A success while a sheet is open is also said in the sheet’s own polite status line, since the toast’s role="status" node is outside it and inert; a write that closes the sheet writes its toast after the sheet has closed. A §5 sm Modal opens over a sheet (an archive confirmation), and the browser stacks the two. Used for the campaign picker and its form (F36-a FR-P1), and for Add Exhibitors and Sort and Filter.

The campaign comes first on Plan (Rev 124). Plan leads with the active campaign: a running or upcoming campaign’s card (name as h2, its state on the Campaign state row, its dates and booths visited, a progress bar when booths are planned, Switch Campaign and New), then its plan; an ended campaign’s Plan Your Next Show panel, its Last Campaign row with View Plan (which opens its plan, ?view=plan, so Back returns to the panel) and Archive ; and Plan a Show with none chosen, or Plan Your First Show when no campaign exists. Which one shows follows the server’s state, never the phone’s clock; only the day count in Running · day 2 of 5 reads the phone’s date. The picker lists the campaigns under Running, Upcoming and Ended (an empty group left out), with No Campaign, Edit and Archive on each row, New Campaign, and a collapsed Archived (N) list with Unarchive. Choosing a campaign is kept on the phone and needs no connection; every campaign write needs one, and offline its control is unavailable with Needs a connection. under it.

The shell’s failure screens (Rev 120). Their headings — That page doesn’t exist., Couldn’t load this page. — are messages, in sentence case with a full stop; their buttons are labels, in Title Case (Back to Leads, Reload the Page), and the not-found route’s page title is Page Not Found.

The existing-client check’s region (Rev 127; F36-d FR-U1, FR-U6, FR-U8). On Capture the check sits under the read badge and above Badge read. Check it’s the right person., full width in the column. It is one box in Notice’s shape (§5 Alert / banner): a 1px border, radius/md, padding space/4 × space/5, the icon (icon/md, aria-hidden) in the first column and, space/4 beside it, the title (type/card-title size, semibold as a strong) and its lines. A line that leads with the account’s name sets the name in a strong and the rest at type/body in text/primary; every other line is type/secondary in text/secondary. Its five looks:

State Surface and border Icon
Checking the CRM for {company}…, Customer check pending surface/card-warm, border/card the loader, spinning (stopped under prefers-reduced-motion), or Wi-Fi off; text/secondary
Already in the CRM — an account, a contact with no account, several capture/match-bg, capture/match-border building, person or people; accent/gold-deep
Not found among the accounts you can see surface/card, border/card sparkle; accent/gold-deep
Check failed tone/danger fill, border and text alert; with Try Again (Button outline, the rotate icon) below the text, inside the box

The live part is one role="status" element that stays mounted from Checking… to the answer, so the answer is announced politely; Try Again sits after it, outside it, so the region announces the sentence alone, and a first answer arriving moves no focus. A retry from Try Again keeps Check failed on screen, with Try Again busy (a spinner in place of its icon, the label and width kept) and focused, never Checking…; when the retry’s answer replaces it, and focus is on nothing then and was on Try Again or on nothing at the press (a tap in WebKit or iOS Safari focuses no button), focus moves to the region, a section named by its title (tabIndex={-1}); a retry that fails again keeps Try Again and its focus. While checking, the box keeps the usual answer’s height — six lines of type/body plus its padding, the account answer’s height at 390px, where its account and counts lines wrap — so the screen below does not jump when the answer arrives. The two capture-only colours are declared once, in forge-et-pwa’s capture.css: capture/match-bg #f4eee2 (the prototype’s accent fill, hsl(40 45% 92.2%)) and capture/match-border accent/gold-deep at 35%. On capture/match-bg, text/primary measures 13.6 : 1, text/secondary 5.3 : 1 and accent/gold-deep 5.1 : 1 (themeContrast.test.ts). The titles and lines are messages, in sentence case; Try Again is a label, in Title Case.

On the lead’s page (Rev 143; F36-d FR-U3, FR-U8). The same region sits on every captured lead’s page, To Review and Completed, after the outcome panel and before the unread-card notice and the booth note (F36-a FR-L6’s place). It reads E-2 once for each set of the lead’s company, email and website and each trigger: the page opening (a reload included), the connection coming back, and the lead read again after a failed write (F36-d Wave-2 contract Rev 1). A read of the lead that changes none of the three sends no check and changes nothing on screen. An answer the page already holds stays on screen while a new check is due or runs, after a check fails, or while there is no connection, and gets one foot line under its lines: Checking again… with the small spinning loader in text/secondary; Checked {how long ago} (the app’s relativeTime wording, kept current once a minute) with the Wi-Fi-off icon in text/secondary, while there is no connection; or Check failed with the alert icon, in tone/danger text, its words semibold, followed by Try Again outside the live element, inside the box. Checking again… and Check failed are inside the live element, so they are announced. Checked {how long ago} changes each minute, so it is drawn outside the live element, in the same place: the live element and the foot are two rows of one grid, whose second column starts where the live element’s text does. Nothing changes on screen, and the minute’s change is not announced. The foot line is type/secondary, its icon icon/sm, space/3 from the words and space/2 below the answer’s lines; the box keeps its answer’s look. Under an earlier answer, Try Again sits on capture/match-bg, and themeContrast.test.ts holds its boundary, border/control, at 3 : 1 or more against that fill. With no answer to keep, the page shows Customer check pending in the quiet box with one of three lines and icons: It runs when you’re back online. (Wi-Fi off), It runs once the card is read. (the spinning loader, a card not yet read) and It runs once the details are added. (the clock, a badge with no company, email or website). A not_checkable answer is never kept as an earlier result. Try Again’s busy state and where focus goes after it (F36-d WI-1.2 plan Rev 2) apply to Check failed under an earlier answer as to Check failed alone.

The To Review row’s existing-customer marker (Rev 143; F36-d FR-U4). A To Review row whose lead is already in the CRM, among the records the rep reaches, shows Existing account or Existing contact. It is §5’s Badge / pill shape (radius/pill, padding space/1 × space/4, no border) on capture/match-bg, with its words and icon in accent/gold-deep: a building for an account, a person for a contact, at icon/sm, space/3 from the words. The words are type/meta in the type/button weight. The marker sits on its own line of the row’s top line, after the name and F36-c’s tier badge, on To Review rows only. A row whose existingCustomer is null, or a value the app cannot read, shows no marker. accent/gold-deep measures 5.1 : 1 on capture/match-bg (Rev 127), and themeContrast.test.ts holds it at 4.5 : 1 or more. A badge on a fill that §5 does not list is a revision the lead decides, so this look is for Nanndish’s decision (F36-d WI-2.4 plan Decision 4).

The convert dialog’s In the CRM row (Rev 143; F36-d FR-U5, FR-U6; F36-d Wave-3 contract D-8, D-9). Convert to Lead’s sheet shows the page’s check as the fact In the CRM, last in its facts list, worded by the answer: {account} is already an account (owner {name}), {name} is already a contact, or FR-U1’s several sentence; there is no row for not found, not checkable or no answer. The answer is the newest one checked on the lead’s current company, email and website; an answer about earlier values counts as no answer (Wave-3 contract Rev 2). The owner is named, never you (contract D-9). When the answer can be linked, the link check box (Link the lead to this account, Link the lead to this contact) follows the facts list and comes before It moves to Completed here…. It is §5’s check box in a 44px label row (layout/control-h), the box at icon/md in accent/gold, space/5 from its label. It is ticked when the dialog opens and again when the offer names other records. After a refused link it is shown unticked while the dialog’s answer is still the one the refused link came from (Wave-3 contract Rev 2). While the convert runs it is unavailable (aria-disabled): its row takes the not-allowed cursor and its label text/disabled, the look of §5’s Disabled row for the capture app’s other controls. After a refused link, the sheet closes and D-8’s sentence, The account or contact in the CRM has changed, so the lead wasn’t converted. The customer check has run again., is the status line above the action bar.

Research and ranking on the plan (Rev 128, F36-c). An exhibitor’s research state is shown in words, never by colour alone:

Where State Renders as
Plan card Ranked The tier badge on the top line and the score at the right, in the tier’s colour; no AI line and no reason
Plan card Not ranked No score; one type/meta line in text/secondary under the company: Researching… with a spinner, Not researched yet — will retry, Not researched — AI research is off, or Research failed
Booth page Ranked Under the visit box, §5 AI provenance’s four elements once — the chip AI RANKED, Confidence <n>%, from: public web search, <d MMM> (or from: the show's exhibitor list, <d MMM> when ranked from the list row), never edited — then Why Visit, Recommended Next Action, and the Company Snapshot
Booth page Company Snapshot The research’s findings, not a written paragraph: each company field as an uppercase micro label, each finding followed by a link showing its source’s host, opening in a new tab (§5 External link); only absolute http/https URLs become links. No Talking Points, no separate Sources list
Booth page Ranked from the list row, nothing found A type/meta line under the provenance: No reliable public information was found about this company — ranked from the show’s list.
Booth page Ranked from the list row, research pending, or research failed A research notice (below)
Booth page Ranked from the list row, research asked for again (Rev 135) After a successful Research Again on a booth ranked from its list row with its research pending, the tier and the score ring stay, and the pending notice under the provenance becomes a brand box with a spinner: Researching this booth… (Researching this exhibitor… without a booth code), with Research Again only while the booth offers it, until the booth is ranked again or its state changes

The research notice. One box holding an icon and the sentence, with the action under the sentence and lined up with it — never a separate full-width button below the box. Information is tone/neutral with border/card and text/secondary (an info icon): This company has not been researched yet — ranked from the show’s list. It is ranked again once researched. A failure takes tone/notice (a warning icon): Research failed. It is retried once a day. The action is Research Again: a text button in primary with a refresh icon, type/body semibold, keeping the capture app’s 44px touch target with no visible border or fill; it is underlined on hover where a pointer can hover (Rev 139: as forge-et-pwa builds both Research Again and F36-b’s text actions). A notice with no action (Not researched yet — will retry) has the same box without the action row. The same text action serves any notice-like box in the capture app (Rev 129): Edit Details and, after it, Read Again (Rev 140) under the card-read check on a lead’s page, and Remove What Was Found under the Role, which takes tone/danger text because it removes something.

The segmented switches — the Leads page’s sections (To Review / Completed) and the Capture screen’s mode (Business Card / Badge QR) — are the shared Tabs, drawn as the CRM’s saved-view tabs are (§6 Saved views, Rev 141; Rev 153, BUG-527): the track filled --et-accent (#f4eee2) with no outline, and the selected tab filled accent/gold (the CRM’s primary, #8a5a12) with accent/gold-on (white) text, at 44px. The fill differs from the track by 5:1, so the selected tab differs by more than colour of text. A tab’s count is a surface/card pill, its figures text/secondary on a tab not selected and accent/gold on the selected one.

Research and ranking on Leads (Rev 129, F36-c). A captured lead’s research state is shown in words, never by colour alone, as an exhibitor’s is:

Where State Renders as
To Review row Ranked, or ranked from the booth note and the card The tier badge after the name, the score ring at the right, the why under the captured-by line, cut after two lines
To Review row Researching The Researching badge with a spinner after the name, and the empty ring
To Review row Not ranked No ring; one type/meta line in text/secondary in place of the why: Not researched — add the company, Not researched — AI research is off, Not researched yet — will retry, or Research failed
To Review row Card being read (Rev 138, F36-b) Reading the card… as the title, with a spinner before it (icon/sm, text/secondary, hidden from assistive technology), and the list item aria-busy; a card that already has a name or a company keeps that title and shows the spinner and Reading the card… as its second line
To Review row Card not read (Rev 138, F36-b) Card not read as the title and Add the details as the second line
Completed row A decided lead Its outcome status indicator after the name (§ Status indicators — the per-state vocabulary, Captured lead outcome; Rev 136), and the ring at the right when its research was ranked
Leads header Any lead researching The Updating live pill (a status, so sentence case)
Lead page Ranked Under the booth note (Booth Note · Used in the Research), §5 AI provenance’s four elements once — the chip AI RANKED, Confidence <n>%, from: public web search and the booth note, <d MMM> (or from: the booth note and the card, <d MMM> when ranked without research) — then Why This Lead, Recommended Next Action, and the Company Snapshot
Lead page Company Snapshot As the booth page’s, with the person’s Role first, its finding followed by its source link; no summary paragraph, no Pain Points, no Sources list
Lead page Nothing found A type/meta line under the provenance: No reliable public information was found about the company — ranked from the booth note and the card.
Lead page Not enough detail to look up A type/meta line under the provenance: Not enough company detail to look up — ranked from the booth note and the card. Add the company or website with Edit Details to research it.
Lead page Research pending A research notice (information): The company has not been researched yet — ranked from the booth note and the card. It is ranked again once researched., with Research Again; after it, Researching this lead… with a spinner under the provenance, the tier kept
Lead page Researching A brand box with a spinner: Researching this lead…
Lead page Not researched A research notice with no action: Add the company or website with Edit Details to research this lead. (no company), Not researched — AI research is off., or Not researched yet — will retry. It is researched automatically once it can be.
Lead page Research failed A research notice (failure): Research failed. It is retried once a day., with Research Again
Lead page Role removed The Role row reads What was found about was removed by , . The removal asks first in a dialog — Remove What Was Found?, This removes what was found about and stops the app looking them up again for this lead., Cancel and Remove (destructive) — and a toast confirms it. Not offered on a converted lead
Lead page Card-read check The box under the captured-by line, on a lead in To Review only: one box and one tone in every state (the research notice’s information box — surface/inset, border/card, text/secondary), the icon naming the state; the sentence, then Edit Details as a text action under it in every state, and Read Again after it when the server allows a new read (Rev 138, F36-b). No box on a converted or rejected lead
Lead page Card-read check, card being read (Rev 138) A spinner (still under reduced motion) and Reading the card…; the box is aria-busy
Lead page Card-read check, card still being read after 10 minutes (Rev 140) The spinner kept, the box still aria-busy, and one paragraph in the same tone: Reading the card… This is taking longer than usual., then Edit Details and Read Again. Shown when the server says a new read is allowed (canReadAgain), never worked out from the phone’s clock
Lead page Card-read check, Read Again (Rev 140) After Edit Details, in one action row with space/6 between the two text actions (they have no padding of their own), wrapping under Edit Details at 320px; the refresh icon, a spinner while it is sent. It asks nothing first; the toast Reading the card again. confirms it and the box turns to the card being read. With no connection it is unavailable (aria-disabled) with Needs a connection. under the row. Its outcome messages (a refusal, Not confirmed — check before trying again. and its follow-up) are one status notice under the box, shared with Edit Details
Lead page Card-read check, card read (Rev 138) The sparkle in tone/ai; §5 AI provenance’s row first — the chip AI READ, Confidence <n>%, from: business card, <d MMM> (the server’s label as given) — then Read from the card by AI. Check the details before converting.
Lead page Card-read check, reading off (Rev 138) An info icon and Card reading is off. Add the details from the card photo.
Lead page Card-read check, could not be read (Rev 138) A warning icon and The card could not be read. Add the details from the card photo. (nothing read, or the photo unreadable)
Lead page Card-read check, could not be read just now (Rev 138) A warning icon and The card could not be read just now. (the reader unavailable)
Lead page Card-read check, badge (Rev 138) The QR icon and Read from the badge. Check the details before converting. — no confidence or source
Lead page Card-read check, edited (Rev 139) Once Edit Details is saved, the marking Edited by you (or Edited by ) takes the place of Check the details before converting. on a read card and a badge, and follows the sentence in every other state; a read card’s chip reads AI READ · EDITED (§5’s edited state, the tone unchanged). On a read card the marking shows only for a save made after the read
Lead page Edit Details (Rev 139) §5’s sheet (Edit Details; a bottom sheet below bp/tablet, a centred dialog from it): the provenance line at type/meta semibold with its icon — Read from the card by AI. Correct anything it read wrong., Read from the badge., or the card-read check’s sentence for a card being read or not read; Enter a name, a company or both.; Name, Job Title, Company, Email, Phone, Website and Country (a select of countries by English name, Choose a country first), every field but Name and Company marked (optional); Saving checks the CRM for this company and person again. on surface/inset; then Cancel and Save Changes. Saved with neither a name nor a company, Enter a name or a company. shows under both. A teammate’s change while it is open is one status notice: The card was read while you were editing. (or This lead changed while you were editing.), These details changed: . and What you typed is kept. A save is confirmed by the toast Changes saved.
Lead page No name and no company (Rev 138) Convert to Lead is not offered; under the customer check a status notice (§5 Alert / banner, not a live region of its own) says To convert this lead, add a name or a company with Edit Details., in every card-reading state and on a badge
Lead page Review Reject in every state, and Convert to Lead in every state once the lead has a name or a company; research never blocks the review

Notifications (Rev 129, F36-c). The capture app’s alerts are in the app only:

  • The bell in the header: a 44px icon button with a count badge (9+ above 9, none at 0), named Notifications, unread.
  • The sheet drops from under the header and, from bp/tablet, sits at the top of the centred column (layout/capture-column-max), never beside a side menu. Header: Notifications, the new pill and ✕. Two groups, New and Earlier, each under a 44px row with an uppercase micro label; Mark All as Read sits on the New row at 44px. Each item: the kind’s icon in a 36px circle, the name, the kind’s word in its tone — Ready to review and Converted tone/positive, Rejected tone/neutral — the company and, for a teammate, captured by or by , and the age, all at 14px; an unread item has a dot and a tinted row. A rejected item shows no reason. (Rev 153) Clearing (F36-c Rev 11, BUG-523): Clear All, a 44px primary text button, sits in the header before ✕ whenever an item is listed; each item ends with a 44px ✕ clear button in text/secondary, centred on the row’s height, named Clear: <kind’s word>, . Neither asks first. Offline both are unavailable, and one line under the header, Marking read and clearing need a connection. at 14px text/secondary on the group-row fill, describes them and Mark All as Read. A clear that fails shows Couldn’t clear. Try again. under the header, in the stale band’s tone/notice colours with its warning icon, until the next clear or the sheet closes. When the header row is too narrow for the title, the pill, Clear All and ✕ (320px with a two-digit pill), Clear All and ✕ wrap together to a line of their own at the row’s end, so the title never breaks.
  • The sheet’s data states: loading — three skeleton rows of an item’s shape, and no badge on the bell; refreshing — no visible change (Notifications updated is announced only when the list changed); empty — the bell-off icon in a 48px circle and No notifications yet.; couldn’t load — a warning icon, Couldn’t load notifications., Your leads are safe — this is a connection problem., an outline Retry and Reference , selectable to copy; couldn’t refresh — the last list under a tone/notice band, Showing notifications from HH:mm — couldn’t refresh., with Retry as a text action, and the bell keeps its last count. With no connection, Mark All as Read is aria-disabled with Needs a connection. under the row.
  • The Ready to review notice shows under the header on any tab, at the top of the centred column from bp/tablet, for a new lead the user captured — a teammate’s goes to the bell only — and never on that lead’s own page. It is one card in tone/positive (border and icon) whose icon and words form one button, ending in a chevron, with the dismiss a separate button beside it; the button’s name starts with its visible text and says what it opens: one lead — Ready to review and · , opening the lead; several in one read — leads ready to review, opening To Review. Dismiss is a separate 44 × 44px ✕. It closes after 8 s, never while the pointer is over it or focus is inside it, never takes focus, and is announced in a polite status region. There is no View button.
  • After Submit for Research the toast reads Submitted · you’ll be told when it’s ready.
  • The Leads tab carries the To Review count as a badge, named Leads, ready to review.

Theming mechanics — how a token is named in code

Tokens are CSS custom properties named --et-<family>-<name>: the spec name with / → - and an --et- prefix. The prefix is namespacing rather than decoration — both frontends and all three shared packages read the same variables.

Spec name CSS custom property
surface/card --et-surface-card
text/primary --et-text-primary
accent/gold --et-accent-gold, plus --et-accent-gold-on for the text-on colour
tone/positive --et-tone-positive-text · --et-tone-positive-bg · --et-tone-positive-border
type/body --et-type-body-size · -weight · -line · -face · -tracking
radius/sm --et-radius-sm
space/4 --et-space-4
layout/control-h --et-layout-control-h
shadow/card --et-shadow-card
motion/base --et-motion-base

Three rules:

  1. A multi-value token expands to one property per value (tones, type levels) — never a shorthand string a component has to parse.
  2. No color segment. surface, text, tone, accent and border are already unambiguous, and --et-color-text-primary reads worse than --et-text-primary.
  3. Breakpoints are the exception. Custom properties cannot be used inside a media query, so bp/* values live in the build config, not in the token file.

Components reference tokens only; the Empire theme file is the single place values live. Both frontends ship light mode only — the CRM (forge-et-fe) and the F36 capture PWA (forge-et-pwa). Dark mode is not in V1 — neither Phase 1 nor Phase 2 — and is a future-release item only if Empire requests it; the token layer is what makes it cheap to add then.

Where the tokens live — the split is what makes the theme swappable, so it belongs in the contract rather than in FS-3’s discretion:

  • src/ui owns the contract: the token names above, plus a neutral fallback value for each, so it builds, tests and renders in isolation without an app supplying anything.
  • The app owns the Empire values: one theme file per app overriding those properties. A different client is a different theme file and nothing else.

Settled at FS-3, then simplified by FS-14: the token contract (names + neutral fallbacks) and the atoms live in src/ui; the Empire values live in one theme file per app (src/ui/styles/theme-empire.css). The pnpm-workspace split that once made the shared UI library and the app separate packages is collapsed to a single src/{app,features,ui,lib} package (AD #31).

Tailwind v4 is adopted in the CRM for the shadcn/ui components (AD #39, Rev 41), and in the capture app on the same terms (AD #43, Rev 149), whose own src/ui/styles/shadcn.css maps the colour names onto those its theme-crm.css declares. Tailwind v4 derives utility class names from specifically-named properties (--color-*, --radius-*, --text-*), so --et-surface-card alone produces no utility. forge-et-fe’s src/ui/styles/shadcn.css aliases the names shadcn uses onto the --et-* set in one @theme inline block (--color-primary: var(--et-primary), --radius-md: var(--et-radius-sm), --text-sm: var(--et-type-body-size), …), so a class such as bg-primary draws the token’s value and a theme swap still changes it. Tailwind’s preflight reset is not imported, and its source scan is limited to the shadcn components and the features moved over.

FS-3 must rename, not only re-value. The provisional tokens.css shipped at FS-1 in both frontends uses a different shape (--et-color-surface, --et-color-text-muted) and collapses six surface roles to two, six text roles to two, and six tones to one. Its own header comment promises the values are replaced wholesale at FS-3; the names have to be replaced too, or the swap-one-file reskin this layer exists for does not hold. Except where the names collide: FS-1’s --et-space-1…5 and --et-radius-sm/-md already spell what this section’s rule makes of the contract’s space/1…5 and radius/sm|md, at different values (provisional --et-radius-sm is 4px; radius/sm above is 9px) — for those families there is nothing to rename, a grep for surviving old names proves nothing, and the FS-3 spec verifies their re-value by rendered-value assertion instead (.forge/specs/foundation/003-design-primitives-spec.md FR-T3/AC-2).

Permission rendering — how a control the user may not use appears

Decided 2026-08-21, resolving the cross-cutting half of OQ-53. This is a single shared guard component built in Foundation slice 3 and driven by the permission model from slice 6 (then (role, resource, level); now AD #34’s catalog — model note below) — not a per-screen judgement call, or it will drift within weeks.

Model note (revised 2026-09-24, AD #34 / AD #35; 2026-09-27, AD #37): the driver behind the guard is the minimal permission catalog — (role, permission_key) grants (no scope since AD #37) over <entity>.view / <entity>.manage per entity (manage implies view) plus a short list of special keys (settings.manage, email.manage, price.publish, quote.approve_sub_floor; access.manage until Rev 71), with per-record shares widening reach but never authority. Nothing in the rendering rule changes. The guard consumes a PermissionDecision (FS-3 plan Decision 13) that is agnostic to how the backend computed it: “the role can never do this anywhere” (hidden) is the user’s effective permission set lacks the key, and the contextual disabled-with-reason case is unchanged — “not in reach” (not owned, not shared, outside the team) is a contextual case. For F5’s screens: the role editor (F5-d) renders the catalog grouped by its UI-group metadata, with one none / view / manage choice per entity, an All records tick beside each entity that has an owner (hidden while none is chosen and shown once view or manage is chosen — AD #37, Rev 79), and a tick per special key (a key that requires another, such as Publish weekly prices, stays shown and is blocked, with its reason under it, until one of those is chosen — Rev 57) — there is no category chip and no outward-acting warning any more; the effective-permissions viewer (F5-e) answers “why can this person see this?” and sits behind settings.manage (Rev 71). Both are design-at-spec-time surfaces under §8’s Users & roles admin entry. The 2026-09-07 note (AD #30), amended 2026-09-11 (AD #32), described a read / edit / execute category on each permission and a warning on roles holding outward-acting permissions; Rev 12 and Rev 16 record it, and Rev 24 supersedes it.

The rule: disable when the block is contextual, hide when it is permanent for that role.

Case Render Why
The user’s role could do this, but not to this record right now (wrong stage, not the owner, quote already issued) Disabled, with a reason The state can change. A missing control reads as “the feature is broken”; a disabled one produces the right question — “why can’t I approve this?” — which is exactly the ticket you want when a role is misconfigured
The user’s role can never do this anywhere in the app — it lacks the key; principally a read-only role such as the recommended Executive / Management role Hidden A control that stays grey forever is noise on every screen, every day. Nobody asks “why can’t I edit?” when read-only is the whole job description of their role

Two hard constraints on the disabled case:

  1. Never the bare HTML disabled attribute. Use aria-disabled="true" and keep the control focusable, with the reason surfaced on activation (and as an accessible name). A natively disabled control is skipped by screen readers and explains nothing. Biome’s a11y rules are errors in both frontends, and a blanket “disable everything” rule is the fastest way to fail that gate at scale.
  2. The reason is required, not optional. “You do not have permission” is not a reason; name the condition (“Approving a below-floor quote needs the below-floor approval permission”). Name the permission, never a role: who holds a permission is Empire’s configuration (AD #26, AD #34), so a message naming a role goes stale the day the configuration changes. A disabled control with no explanation is worse than a hidden one — it tells the user they have a problem and withholds what it is.

Session expiry and return-to-route

Decided in F5-a, promoted to a cross-feature convention in F5-b (FR-13) so every protected route signals an expired or missing session the same way and a user who is bounced to sign-in lands back where they were.

  • On a 401 or a missing session, the shared authenticated gate redirects to /login and carries the attempted route in the router’s state.from — it does not strip or rewrite it. The gate renders no authenticated chrome before the session resolves, so there is no flash of a page the user is about to be redirected off.
  • After a successful sign-in, the login step returns the user to state.from when one is present, and otherwise to the default landing (the first permission-accessible destination — see the navigation/landing rule the app frame applies, F5-b). Router state does not survive the full-page Microsoft redirect, so the attempted route is also kept for the round trip in the tab’s session storage, written just before the redirect and read once when the session is confirmed. Only a same-origin path is accepted (one leading /; never //, /\, a scheme, or the login page itself), and any storage failure falls back to the default landing (BUG-054).
  • This is one shared rule, not a per-feature choice. A feature that adds a protected route inherits it by mounting inside the shared authenticated gate; it must not preserve the attempted route in its own way, and must not drop it.
  • An involuntary expiry says so; a first visit and a sign-out stay silent (BUG-007). When the redirect ends a session that was established — a mid-session 401, or a reload that lost the session — the login page shows exactly one polite notice (“Your session expired. Please sign in again.”), as a role="status" region in the warm notice tone, never the danger tone of a sign-in failure. A genuine first visit (never authenticated) and a deliberate sign-out render no notice — a login screen that cannot tell an expiry from a first visit is the defect this rule closes. Because the only user-observable expiry path is a page reload, and an in-memory flag cannot survive a reload, the “was authenticated” fact is carried by a persisted per-browser marker set when a session is established and cleared on sign-out. A just-failed re-authentication (?login=failed) takes precedence over the expiry notice, so the actionable failure message stands alone; so does ?login=unavailable, the message for a sign-in the environment cannot sign (F5-a Rev 5, design-system Rev 31).
  • A backend that is down says so, and can be retried in place. When the first /me fails with anything other than a 401 (the backend is down, a 5xx, a network error), the session still settles as signed out (fail-closed), and the login page shows one role="status" notice in the notice tone (“The service isn’t available right now.”) with a Try again button that re-runs the session check without leaving the page. Both ?login= markers take precedence over it, as over the expiry notice.
  • A failed sign-out keeps the user signed in (BUG-052). Sign-out changes the screen only when the server confirms it (or answers 401, meaning the session is already gone). Any other failure leaves the user signed in and shows “Sign-out didn’t complete. Try again.” next to the user menu, in a live region whose role="alert" is on the message only, so an empty region never counts as an alert. The sign-out item is disabled while a sign-out is in flight. The server session cannot be cleared by the app (the SESSION cookie is host-only on api.*, AD #33), so showing “signed out” while it is still live would leave the next person on a shared PC signed in as the last one.
  • A page that fails to load offers a reload (BUG-053). An error while loading the login page (for example a tab left open across a deploy, whose old chunks are gone) or inside the sign-in gate shows the shared error screen with Reload the page, which does a full reload. It never offers “Back to the dashboard” there, which would loop back to the same failure.

Permission changes and deactivation while signed in

Decided by AD #34 (2026-09-24); the frontend half is built by F5-k. It sits beside the session-expiry rule because both answer “what happens to a signed-in user when something changes on the server”.

  • A role or permission change applies on the user’s next request, with no sign-out. The backend re-reads the user’s grants on every request (no grant cache), so the server is already correct; the frontend’s job is to catch up. The app re-reads GET /api/v1/me after any 403 and whenever the window regains focus, and the navigation, the route guards and the permission guard re-render from the new permission set. What a screen the user can no longer reach shows after the re-read — the app frame’s landing rule (F5-b) or a no-access state — is F5-k’s spec decision. A 403 from a CSRF refusal triggers the same harmless re-read.
  • A background re-read never throws the user out on its own. A failure other than a 401 is kept inside the re-read and leaves the current screen as it is; the next request that fails shows its own error in the normal way.
  • Deactivation is the one change that ends a session. The backend deletes the user’s sessions, so their next request is answered 401 and the session-expiry rule above takes over: they land on /login with the involuntary-expiry notice, and signing in again is refused.
  • The share picker offers only eligible people (AD #35, F5-g). People who already reach the record (its owner, their managers, holders of the entity’s all key, anyone it is already shared with) are not listed — the lead’s worked example offers only the colleagues who cannot yet see the record, and the existing shares appear in the record’s shared-with list with Remove; people whose role cannot view that kind of record are not listed either — hidden, not disabled, because no action of the sharer can make them eligible. Sharing and removing a share need manage access to the record, and their controls follow the hidden-versus-disabled rule above. A share to a deactivated user is shown as deactivated and can be removed.

10. Open items

# Item Needed by
1 Dinil review of this spec (visual ACs in feature specs cite it from then on) Before Foundation slice 3
2 Executive read-only views (six-role gap, §8). The Tea Room half is now drawn — the Pricing screen and the account’s buying-standards section landed in the prototype 2026-09-11 as a team proposal; what remains for F26 is Empire’s confirmation of that shape, plus the two mocked affordances on it (sheet import, emailing prices) and the add / edit / archive-standard modals (2026-09-15) Executive: before their features’ specs. Tea Room: F26’s spec, as a confirm-or-change rather than a design-from-scratch
3 Confirm Tailwind (+ tokens as theme) vs CSS-modules at slice 3 Closed 2026-10-09 (Rev 41): CSS Modules at FS-3; Tailwind v4 with the tokens as its theme, for the shadcn/ui components, from AD #39 —
4 Fraunces/Inter self-host bundle (woff2 subsets) Closed at FS-3 (Rev 67): Inter only (Fraunces dropped, Rev 18), self-hosted from @fontsource-variable/inter, latin subset (forge-et-fe src/ui/styles/fonts.css) —
5 Capture-app theme mapping — remap the POC’s screens (../forge-et-pwa-poc apps/web, ad-hoc Tailwind values) onto these tokens; same tokens, own PWA shell Before the capture stream starts (Phase 2, from 26 Oct)
14 Confirm the status-label wording with Empire — the §5 vocabulary is proposed where the PRD names no levels, F15’s Blocked / Slipping severity pair first. The structure (dot + shape + label) is settled; only the words are open F15’s spec at the latest; ideally alongside the item-1 review

Known gaps, deliberately deferred (recorded 2026-08-25 — see Rev 1). Found in the review that produced Rev 1 and left for later by decision, not oversight. Listed here so the deferral is tracked rather than lost.

# Item Needed by
6 Three PRD requirements have no design coverage. Closed 2026-08-25 (Rev 2) — all three are now specified: Status indicator (§5 + the §2 colour build rule), AI provenance’s four elements (§5), and Drag has a keyboard equivalent (§6) ✅ Done
7 Components in scope but absent from §5. Closed 2026-08-25 (Rev 3) — all nine specified: date input, switch, combobox, tooltip, file upload and attachment row (§5); interaction-state matrix and form validation (§5); data table, global search results, charts (§6) ✅ Done
8 tone/info referenced but never defined. Closed 2026-08-25 (Rev 5) — the variant is dropped, not invented: the palette is warm by design and the prototype’s only two cool colours are the Microsoft and Google OAuth marks. Informational badges use tone/neutral or tone/notice ✅ Done
9 §5 specifies components in raw hex. Closed 2026-08-25 (Rev 5) — three new tokens (surface/field, surface/hover, surface/scrollbar), border/frame resolved to one value, and §5–§7 rewritten to reference tokens throughout. Verified: zero raw hex or rgba() remains in those sections ✅ Done
10 No z-index scale, no icon library, no number/currency formatting. Closed 2026-08-25 (Rev 4) — z/* layering (§4), lucide-react (§4), and money / weights / percentages (§9). One part remains open: no font-display strategy against the < 2 s load NFR — see item 13 ✅ Mostly done
11 The capture app has no mobile spec. Closed 2026-08-25 (Rev 4) — §9 gains “The capture app (F36) — the mobile surface”: touch scale, type step-up, safe areas, shell chrome, and the five offline states. Item 5’s retheme is unaffected and still open ✅ Done
13 No font-display strategy for the self-hosted Fraunces/Inter bundle (§1), against the PRD’s < 2 s load target. swap risks a visible reflow on the Fraunces headline; optional risks the fallback sticking. Needs a decision with the woff2 subsetting in item 4 Closed at FS-3 (spec Q-7; Rev 67): font-display: swap, with a metric-tuned fallback face that removes the reflow (forge-et-fe src/ui/styles/fonts.css) —
12 §5–§7 still quote raw values and have not been rewritten onto the §3/§4 tokens. Closed 2026-09-02 (Rev 8, confirmed at the lead’s review of PR #42) — §5–§7 are rewritten in token terms; the decisions and the three sites this row did not name are recorded in Rev 8. Two points remain provisional pending the on-screen pass at FS-3 subtask 4 — badge radius and badge casing — flagged at the Badge row itself rather than left here ✅ Mostly done

Revisions

Rev 1 — 2026-08-25 — the non-colour half of the token layer, and tablet

Three gaps were found in review and fixed. A first pass made claims that did not survive checking against the prototype source; this entry describes what actually landed, after that correction.

  • Changed — §3 and §4 are now named token tables. Typography, radius, space, layout, elevation, motion, icon and focus geometry were prose ranges (“13.5–14px”, “r8–9”, “150–250ms”). A range cannot be a contract: two developers pick differently, both are right, and forge-et-fe/CLAUDE.md’s standing ban on raw px outside the token file is unsatisfiable without names. Only colour had names before this, so “the token names are the contract” was true of about half the system.
  • Values are measured, not inherited. The first pass collapsed the ranges the old prose quoted, and that prose was under-counting: the prototype declares 14 radii (not 7 — including 18px and 20px, used 48 times between them), 33 font sizes, and 8 icon stroke widths (not 1.7–1.8). Every scale is now derived from the measured distribution, each token records what it absorbs and how often, and the values are labelled proposed — confirm on screen at FS-3. Two type levels (type/stat, type/subhead), a fifth radius step, three control-height tokens and a second icon stroke exist because §5/§6 name roles that otherwise had no token at all.
  • The 4px grid claim is withdrawn. The prototype is not on a 4px grid — its commonest gaps are 9px and 10px, its commonest card padding 18px. space/* now hugs those values, and the pure-grid tidy-up is recorded as a design call for the lead rather than performed silently. space/1 is 2px because §5’s badge padding is 1–3px and a 4px floor would visibly grow every badge.
  • Added — §9 states the CSS custom-property naming convention (--et-<family>-<name>), which had never been written down. The consequence was already live: the spec said surface/card, the FS-1 plan said --surface-card, and the shipped token file says --et-color-surface. §9 now also settles where the token file lives (contract plus fallbacks in src/ui, Empire values in the app) and records that forge-et-fe/CLAUDE.md contradicts itself on this today. FS-3 must rename the provisional tokens, not only re-value them; the FS-1 files are untouched by this revision.
  • Added — three named breakpoints and a reflow table (§9), replacing a viewport bullet that floored at 1280px while the PRD commits to tablet and the test strategy asserts a tablet viewport — the suite would have checked a width nothing was designed for. Portrait tablet (768px) is in scope, recorded as a team decision because the accepted proposal never mentions tablet; it commits only to “a responsive web application”. The floor is a scope lever, not an obligation, and §9 says so.
  • Touch targets are 24 × 24, not 44 × 44. The first pass imposed 44 × 44 and used it to make §5’s 36px compact control desktop-only. That is WCAG 2.1 SC 2.5.5, Level AAA; the PRD targets AA, where the applicable rule is WCAG 2.2 SC 2.5.8 at 24 × 24. The stricter figure was over-commitment against the contract and removed a variant the dense layouts need. The compact control stays available at every breakpoint.
  • Fixed — §6 no longer contradicts §9. The two-pane pattern said “the list stays visible”; the reflow table makes it single-pane at bp/tablet. §6 now states the behaviour per breakpoint and notes that an acceptance criterion must say which one it asserts.
  • Not changed. §2 (colour), §5, §7, §8 and the permission-rendering rule are untouched. The gaps found in the same review are recorded as open items 6–12 rather than fixed — including item 12, the §5–§7 values that do not yet map cleanly onto the new scales, which is FS-3’s first task.
  • Scope note. This revision changes an accepted spec and is recorded per .claude/rules/specs.md. It reverses no Architecture Decision and adds no colour. Two judgement calls inside it belong to the lead, not to this document: whether portrait tablet is in scope at all, and the radius and spacing consolidations, which move a client-approved look by up to 2px.

Rev 2 — 2026-08-25 — the three PRD requirements the spec had no rendering for

Closes open item 6. Each of these was already required by project-prd.md and architecture.md; none had a visual form here, so a feature spec citing §5 would have had nothing to write a visual AC against.

  • Added — Status indicator (§5) and a colour build rule (§2). project-prd.md § Accessibility requires that status “must not rely on color alone” and that “age/priority/severity/rotting dots carry text labels too”; test-strategy.md § Accessibility makes it a T1 obligation. §5 gains a Status indicator — coloured dot + visible text label, always, with the dot’s shape varying too so the distinction survives greyscale — plus a per-state vocabulary table covering rotting/ageing (F2/F18/F24), lead priority (F11), severity (F15), certification match (F9) and checklist items (F7/F10). §2 gains the matching build rule alongside the contrast floor.
    • Decision (developer, 2026-08-25): text labels everywhere, the PRD’s literal reading, in preference to satisfying WCAG 1.4.1 with dot shape alone. This makes Kanban cards taller and departs from the prototype’s approved density — accepted, because a client seeing colour-only status at UAT is the worse outcome. type/micro keeps it to one line.
    • Noted in place: the PRD’s own “turns red when untouched” phrasing is colour-only shorthand for the same state, not a licence.
  • Added — AI provenance’s four elements (§5). project-prd.md § Observability and Audit and architecture.md § AI provenance… both require every AI output to carry confidence and source and to flip to an “edited by you” state once a human changes it. §5’s chip covered one of the four. All four are now specified, applying across F11–F16, F25 and F36.
    • Decision (developer, 2026-08-25): follow the PRD and architecture literally — confidence renders as a numeric percentage (the PRD scores leads “P1–P4 with a confidence %”; the Lead entity carries confidence 0–100). Source names what the output was derived from, linked where the record is reachable, because a rep must see what the AI read for the human-in-the-loop review to be real. The capture POC’s score-ring is recorded as an optional at-a-glance form, not a substitute.
  • Added — “Drag has a keyboard equivalent” (§6). project-prd.md § Accessibility requires keyboard navigation of boards and the calendar, and test-strategy.md states plainly that axe cannot verify a Kanban board is operable without a mouse. Three surfaces drag in V1 — the pipeline Kanban (F2), the sample board (F6) and calendar drag-to-reschedule (F21). Each now requires an explicit move action on the item (Move to stage…, Reschedule…) as the primary non-drag path, with a five-row conformance table (tab order, menu operation, Esc cancel, live-region announcement, focus landing). Emulated keyboard drag may be layered on but never substitutes.
    • Why the menu rather than emulated drag: it is discoverable, it announces itself, and it is the usable path on tablet — where, since Rev 1 put the floor at 768px, dragging a card across a horizontally scrolling column is the worst case in the app.
  • Sibling repos: nothing to change, verified rather than assumed. forge-et-fe’s three UI packages are deliberately empty stubs (“Contents arrive at FS-3”), forge-et-pwa has no components, and forge-et-be’s core-ai is a module marker with no AI code. The code these three rules govern does not exist yet; FS-3 builds it against this spec. One consequence to carry into the backend’s API conventions (FS-10): confidence and source must be exposed on every AI-produced payload, or the frontend cannot render what §5 now requires.
  • Not changed. §2’s colour values, §3, §4, §7 and §8 are untouched by this revision. Open items 7–12 remain deferred.

Rev 3 — 2026-08-25 — the nine missing components

Closes open item 7. Each of these serves a feature already in V1 scope, and each was absent from a §5 list that read as complete — so a spec author would have found no component to cite and quietly invented one per screen.

  • Added to §5: Date input (F7 validity, F26 effective dating, F2 expected close, F3/F21 scheduling, F34’s date field type), Switch (F24/F34, settings), Combobox / typeahead (F31 and every entity picker), Tooltip / popover (required by §9’s own permission rule, which had no component to surface a reason with), File upload and Attachment row (F33, FS-11).
  • Added to §5 — two cross-cutting gaps that were not on the list. An interaction-state matrix: the prototype specifies hover for three components and nothing else, so pressed, visual disabled, busy and selected were undefined everywhere. And form fields and validation: §5 gave input sizes only — no label rule, no required marking, no error appearance, no validation timing, no submit behaviour. Both are the kind of gap that reads as an unfinished build without anyone being able to name why.
  • Added to §6: Data table (F32’s sorting, selection, bulk-action bar, pagination, column configuration and saved views as one shared component rather than a per-screen build), Global search results (F31 — seven record types, grouped, visibility-scoped; the prototype’s search is decorative and omits contacts), and Charts.
  • Decision (developer, 2026-08-25): native-first. Native HTML where it exists and is good — <input type="date"> as the prototype already uses, <select>, <dialog>, real <button> — with a headless library taken only for combobox and tooltip, the two natives cannot do. Rationale: native elements are keyboard- and screen-reader-correct on arrival, which is the cheapest way to hold the WCAG 2.1 AA commitment, and forge-et-fe currently carries zero UI dependencies. Accepted trade-off: native date and select controls render differently across browsers. The specific library is confirmed at FS-3 with open item 3.
  • Decision (developer, 2026-08-25): charts follow the PRD, hand-drawn in SVG. The three the PRD names — pipeline funnel with its Private Label / Bulk toggle and footer stats (F17), leads-by-source across the five F11 sources (F17), price history per destination market (§7/F26). No chart library: the approved prototype already hand-draws its two, all three are simple shapes, and it keeps them token-native. Each carries a text alternative so the data is reachable without seeing the picture.
  • Decision (developer, 2026-08-25): numbered pagination with a total. 1–25 of 340, offset-based. Chosen over load-more and infinite scroll because F32’s bulk selection needs stable page boundaries and Select all 340 needs a known total. This is a cross-repo commitment — FS-10 has not yet settled the API’s pagination shape, and it must match; a cursor-only API would not support this UI.
  • Sibling repos untouched, as with Rev 2 — forge-et-fe’s UI packages are still empty stubs and FS-3 builds all of this against the spec. Two things for FS-3 to carry: the headless-library choice needs a dependency decision (an ASK FIRST action), and the FieldRenderer registry (extension point 10) is what lets the data table render F34 custom fields without naming a field type.
  • Not changed. §2’s colour values, §3, §4, §7 and §8 are untouched. Open items 8–12 remain deferred; item 12’s §5–§7 reconciliation now covers the new rows too.

Rev 4 — 2026-08-25 — layering, icons, number formatting, and the capture app’s mobile surface

Closes open items 10 (mostly) and 11. Each was small to state and awkward to retrofit, and two of them turned up a fact worth more than the fix.

  • Added — z/* layering (§4). The prototype carries nine ad-hoc z-index values (5, 25, 30, 40, 45, 50, 60, 5000, 9999); five named steps replace them, and no component sets a raw one. Modals and toasts are deliberately outside the scale: native-first (§5) makes a modal a <dialog> and a toast a [popover], both of which render in the browser’s top layer, above every z-index regardless of value. That is the main practical dividend of the native-first decision — the “my modal is behind something” bug becomes structurally impossible rather than carefully avoided.
  • Decision (developer, 2026-08-25): icon library is lucide-react (§4). It matches the stated language almost exactly — 24×24 grid, round caps and joins, currentColor, stroke overridden to icon/stroke 1.75 — is ISC-licensed and tree-shakeable, and is already what the capture POC uses, so the two apps stay consistent and item 5’s retheme gets cheaper. It replaces the prototype’s hand-drawn icons, whose geometry was inconsistent anyway (measured viewBoxes of 23, 24, 48 and 400; eight stroke widths from 1 to 2.3). A concept registry is required so two features cannot pick different glyphs for the same idea, and named imports only, or the whole set ships.
  • Added — money, weights and percentages (§9). §9 previously said only “tabular-nums”. The rules are grounded in the data model’s real grains (NUMERIC(12,4) per-kg USD FOB, (14,3) kg quantity, (12,2) amounts) and are explicitly presentation only: coding-standards.md § Formatting is not computation puts rounding and precision server-side, and the same file treats a client-computed margin as an authorization hole, since F7’s floor gate depends on it. Notable rules — ISO code rather than a bare $ (Empire quotes into 70+ countries); never convert kg to tonnes for display; separators fixed rather than locale-derived; and absent renders —, never 0, because the data model makes the margin null when cost is null and 0.0% would read as a catastrophic loss on a quote that simply has no cost yet.
    • One value is provisional: per-kg prices display at 2 decimals because the data model records that price moves “are quoted in cents”, though storage allows 4. Flagged to confirm against the real Tea Room price list (~late Sep).
  • Added — the capture app’s mobile surface (§9). The header claimed this document covers the capture app; it said nothing about phones. Now specified: 360–430px target, 44 × 44 touch targets (a usability choice, deliberately stricter than the CRM’s 24 × 24 AA floor, because the user is standing and one-handed), a type step-up from 13px, env(safe-area-inset-*), standalone detection, the install prompt, and the secure-context requirement for the camera. Everything else is shared with the CRM.
  • Finding — the POC does not implement offline queuing, though it advertises it. Verified 2026-08-25: vite-plugin-pwa gives Workbox shell caching only, and capture.jsx’s “queue” is an in-memory file loop — no IndexedDB, no background sync — while its install banner reads “works offline” and architecture.md requires that “capture works on flaky exhibition Wi-Fi by queuing submissions”. So the app’s defining behaviour is new work for F36, not a port. Five offline states are now specified (online / offline / queued / syncing / failed), with two hard rules: a capture is visibly accepted the instant it is taken, and the queue is persisted rather than held in memory. This feeds OQ-55 — the F36 scope delta — and the capture stream’s sizing should reflect it.
  • Sibling repos untouched. lucide-react is a decision recorded here, not an install — adding it to forge-et-fe and forge-et-pwa is FS-3’s job and an ASK FIRST dependency action at that point.
  • Still open: item 13 (new — font-display strategy, split out of item 10), plus items 8, 9 and 12. Items 8 and 9 — tone/info referenced but undefined, and the raw hex still inside §5 — are the two most worth closing next, since both are small and both sit in the token layer FS-3 builds first.

Rev 5 — 2026-08-25 — the last of the colour layer: tone/info and the raw hex in §5

Closes open items 8 and 9. Both sat in the token layer FS-3 builds first, and both turned out to be answerable from the prototype rather than by preference.

  • tone/info is dropped, not defined. The Badge spec listed an info variant §2 never declared. Measuring the prototype settled it: it contains exactly two cool-hued colours, and both are third-party brand marks — Microsoft #00A4EF and Google #4285F4 on the AD #5 dual-provider login buttons. There is no blue in this palette because the palette is warm by design, so an info tone would have introduced a new hue into a look the client has approved, to serve a variant nothing had asked for. Informational badges use tone/neutral when merely factual and tone/notice when they want attention.
  • Recorded the one legitimate exception to the no-raw-hex rule: those two OAuth marks. Third-party brand colours must stay exact, so they are deliberately not tokenised and not theme-swappable — alongside §1’s brand foundations, which is the layer where literal values belong.
  • Three tokens added, one resolved, and §5–§7 rewritten in token terms.
    • surface/field (#FDFCF8) — the input fill, which §5 had been naming as a bare hex.
    • surface/hover (rgba(94,58,30,.10)) — the transient hover wash, absorbing the prototype’s .07 / .10 / .13. Three alphas inside six percentage points was drift, not intent. It stays distinct from tone/neutral’s persistent .12 badge fill, which is a different job.
    • surface/scrollbar — the two sage values Rev 1 had left explicitly untokened as “browser chrome”. That exception was not worth keeping once everything around it had a name.
    • border/frame resolved to a single value. It had carried two (#E6D9C4 / #E5D9C6), which is not a token. Measured, #E5D9C6 appears four times against the other’s one, so the outlier resolves to the majority.
    • Component rows now reference shadow/button-hover, layout/control-h*, brand/deep-green, radius/* and the new surfaces instead of restating values. Verified: zero raw hex or rgba() remains anywhere in §5, §6 or §7 — the header’s “tokens, never raw values” rule is now true of the component specs, not just asserted above them.
  • Sibling repos untouched, as with Rev 2–4. The three new tokens land in tokens.css at FS-3 with the rest of the rename.
  • Two items remain: 12 and 13. Item 12 — the size values in §5–§7 that still do not map cleanly onto the §3/§4 scales (r8–10, r9–11, the Kanban’s 12px/600 against type/meta’s 11.5px/500) — is the last content gap, and unlike the colour sweep it needs real decisions rather than measurement, which is why it stays FS-3’s first task. Item 13 is the font-display strategy.

Rev 6 — 2026-08-28 — PR #28 review fixes: menu radii, provisional flags, FS-10 pointers

  • Fixed — §5/§6 no longer contradict §4 on menu radii. Rev 5’s token rewrite set Toast and Dropdown menu to radius/lg (16px) where §4’s scale maps both to radius/md (12px) — the prototype’s measured r12, so this undoes an accidental 4px upsize of client-approved surfaces. Rev 3’s combobox and global-search popovers align to radius/md with them: §4’s layering table already groups combobox popovers with dropdown menus and tooltips (z/menu, and Tooltip was radius/md all along), and two near-identical list menus with different corners would be exactly the drift Rev 5 set out to remove. §4’s radius/md row now names popovers so the family mapping is explicit.
  • Flagged in place what Rev 2’s vocabulary invented. P1–P4 and rotting are PRD vocabulary; Fresh, Ageing and especially F15’s Blocked / Slipping are not — the PRD says “severity” and names no levels. The §5 table now says so, and open item 14 tracks confirming the words with Empire (F15’s pair first, ideally with the item-1 review). The structure — dot + shape + visible label — stays the settled contract; only the words are open.
  • Flagged the §9 reflow behaviours as proposed, the same status the §3/§4 scale values already carry — they are design calls not yet verified against any built screen, and the table now says so instead of reading as settled.
  • Surfaced the two FS-10 seam commitments at their consumer. Rev 2–3 recorded that every AI-produced payload must expose confidence + source, and that pagination must be offset-based with a known total — but only inside this frontend-facing document, which the author of FS-10 (backend API conventions) has no reason to open. Both now sit on FS-10’s row in architecture.md § Foundation Backlog (its Rev 24). Recorded here so the two documents cannot silently diverge on who committed what.
  • Not changed: everything else. Items 12 and 13 remain FS-3’s first task, untouched — the radius fix above corrects a wrong token reference, which is a different thing from item 12’s unconverted raw values, and converting those piecemeal would half-do work FS-3 should do once.

Rev 7 — 2026-08-28 — §9’s rename example corrected: the name-colliding families

  • §9’s “rename, not only re-value” blockquote no longer lists --et-space-1 as a name to replace. Its own naming rule maps the contract’s space/1 to exactly that spelling, so for space/1…5 and radius/sm|md the provisional and contract names are identical and only the values differ (provisional --et-radius-sm is 4px; contract radius/sm is 9px) — there is nothing to rename, and a grep for surviving old names cannot tell a missed re-value from a landed contract token. The blockquote keeps a non-colliding example and now states the collision explicitly, pointing at the FS-3 spec’s FR-T3, whose AC-2 verifies those names by rendered-value assertion where its AC-1 grep is blind. Found during the FS-3 spec’s lead review (PR #31, 2026-08-28).
  • Not changed: no token, value, scale, or component moves — a documentation correction only. Items 12 and 13 remain FS-3’s first task.

Rev 8 — 2026-09-01 — open item 12 closed: §5–§7 rewritten onto the §3/§4 tokens

Status: confirmed at the lead’s review of PR #42 (2026-09-02). The decisions below were prepared as proposals for the FS-3 subtask-1 value pass and are settled by that review, including the type/button name, which stands — the type/label rename was offered and not taken. The only points still open are the two that need the theme on screen at subtask 4, flagged at the Badge row and repeated under Still provisional below.

  • Item 12’s list was partly self-resolving, and its remainder is now decided. Checked against the §3/§4 scales as they stand, four of the values item 12 called ambiguous sit wholly inside one token’s absorb band and needed a rewrite rather than a decision: r8–10 → radius/sm, r11–12 → radius/md, r14–16 → radius/lg, pad 16–18 → space/6. Eight more sites were mechanical on the same test (r8, r9, r9–10, r10, r16, Button/lg’s 14.5px → type/card-title, badge vertical pad 1–3px → space/1, menu items 12.5px → type/secondary). Recorded so a later reader can see they were checked, not assumed.
  • The genuine decisions. Input radius r9–11 → radius/sm (§4 names radius/sm “default control — buttons, inputs, mini-cards”; radius/md is the overlay step, and an input on it is rounder than the button beside it). Input text 13–14px → type/body (type/card-title is a 600-weight heading token). Table body 12.5–13px → type/secondary, the token §3 already names for table cells. Badge horizontal padding 7–9px → space/4 (vertical padding is only space/1, so space/3 crowds a pill). KPI 20–22px/600 → type/stat, dropping the 22: 22px is type/title, which is Fraunces, so taking it would change the face of a numeric value.
  • type/button added to §3 — the weight mismatch was structural, not one value. Item 12 framed it as a single row (§6’s Kanban header, 12px/600 against type/meta’s 11.5px/500). It is at least three sites: both button families specify weight 600 at every size, and no small size-matched token carries 600 — type/micro is the only one and it is UPPERCASE. Rather than punch a weight-override hole in §3’s “one token resolves a whole level” contract, §3 gains one row: type/button, Inter 13px/600/1.4. md buttons and the Kanban header take it (lg already had type/card-title at 600; sm keeps a raw 11.5px — see the Button row); the Kanban header moves 12 → 13px, inside §3’s stated 1.5px tolerance. The name stands as type/button — type/label was offered as a rename should a button-named token on a column header read wrong, and was not taken at the PR #42 review. The alternatives considered and rejected were a documented weight override (sets a precedent every later component can widen) and re-weighting type/meta to 600 (breaks 171 mostly-not-600 measured uses).
  • Three sites item 12 did not name, found in the §5–§7 sweep. Badge radius r10+ (the “+” is open-ended, not a two-step ambiguity), Button/sm’s 600 against type/meta’s 500, and whether badge labels are uppercase — which decides whether type/micro can carry them at all. The first and third stay provisional; the second is resolved by type/button.
  • §3 contradicted itself on the 8.5–9px outlier, and no longer does. The type/micro row’s Absorbs column already read 8.5–10.5 (×96) while the paragraph below it listed 8.5–9px (×4) as an unsnapped outlier awaiting an FS-3 decision — the table had swallowed the value the prose said was open. Resolved by folding it into type/micro, which is what the table already claimed. The second outlier, 24–30px (×16, all on the dashboard), stays untokenized: every use is on a surface §8 lists as still to design (open item 2), so a token invented now would guess at screens nobody has drawn.
  • §6’s app frame now references the layout/* tokens it had been restating as numbers (248/76px → layout/sidebar-width / -collapsed, 64px → layout/topbar-height). Same class of gap as item 12, in a section item 12 did not cover.
  • Still provisional, and flagged in place rather than here. Badge radius reads as radius/pill (the row is named “Badge / pill” and §4 has the token) and badge type as type/micro; both need the prototype on screen at FS-3 subtask 4, where the alternatives are radius/sm and a sentence-case type/badge sibling. Item 13 (font-display) is untouched — it belongs with open item 4 in the same subtask.
  • One decided value will not be seen this slice. §5’s plain Table is deferred to F32 (FS-3 spec Q-5), so type/secondary for its body is settled on paper but unverified on screen. Noted at the row.
  • Not changed: §1, §2, §9’s conventions, and every §3/§4 scale value — no token moves, and the only addition is type/button. This Rev converts §5–§7 onto the existing scales and resolves the values that had no clean mapping; it does not revisit the scales themselves, which Q-6 keeps as measured and confirms on screen at subtask 4.

Rev 9 — 2026-09-03 — FS-10 settled the pagination seam

  • The §6 pagination row’s “matching whatever FS-10 settles” is now a settled shape. FS-10’s API conventions (forge-et-be/docs/api/collections.md) bind every list endpoint to 1-based page and size (default 25, maximum 100; a value out of range is rejected with 400 rather than clamped) and answer in one envelope — items[] plus page { number, size, totalItems, totalPages } — where totalItems is the exact count of the filtered set, computed in the same request. That is what 1–25 of 340 and Select all 340 need: a known total and stable page boundaries, the latter guaranteed by an id tie-break the API appends to every sort. A page past the last is 200 with no items and the true totals, so a table whose data shrank underneath it recomputes rather than errors. Sort is sort=<field>,<asc|desc> on the response record’s camelCase names, repeatable — the URL-carried sort the Sortable-header row already requires.
  • The §5 AI-provenance commitment Rev 6 surfaced is met on the same slice. Every AI-produced payload carries aiProvenance { confidence (integer 0–100), source { label, ref }, edited, editedAt } (forge-et-be/docs/api/payloads.md), so confidence and source are on the wire as Rev 2–3 required.
  • Not changed: the row’s decision (numbered pages with a total) or any token; the row’s wording now names the settled shape instead of the open question.

Rev 10 — 2026-09-04 — the login screen loses Google and the password form (AD #28)

  • Changed: §1’s literal-colour exception narrows to the single Microsoft provider mark (#00A4EF); the Google mark (#4285F4) is retired with the dropped provider. The login screen’s F5 build carries one provider button and no email/password form — sign-in is by company Microsoft account only (AD #28; PRD Rev 20). The CRM prototype was brought onto this shape in the same change, so no drift is left standing between the two.
  • Not changed: the login split-screen brand moment, the type/display headline, and every token — this is a content change to one screen, not a token change.

Rev 11 — 2026-09-04 — §4’s toast-over-modal claim corrected: inertness is subtree, not mount order

  • What was wrong. §4 stated that because DOM order decides within the top layer, “the toast container is mounted after the dialog root” — offered as the mechanism that makes a toast usable above an open modal. The paint half is right and was confirmed visually. The interaction half is wrong: showModal() inerts everything outside the dialog’s subtree, and inertness ignores top-layer order entirely, so no amount of care with mount order can make that toast clickable.
  • How it was found. Measured in Chromium at FS-3 subtask 10 while proving the §4 top-layer claims rather than assuming them — with a modal open, elementFromPoint at the toast’s Dismiss button returned the DIALOG and dismiss.focus() was a no-op; both recovered on close. A dropdown menu that is a DOM descendant of the dialog stayed fully operable in the same pass, which is what identifies subtree membership as the real variable.
  • What §4 now says. Paint order and usability are separated explicitly, with the two rules that follow: a toast over a modal is informational only and must be allowed to expire (never duration={null} there), and anything that must be usable above a modal has to live inside that dialog’s subtree — a toast viewport hosted in the topmost open dialog, which is orchestration rather than a primitive and is not built until a screen needs one.
  • Traceability. FS-3 finding F-023; the limit is documented on the Toast component itself, so the constraint is visible at the call site and not only here.

Rev 12 — 2026-09-07 — § Permission rendering annotated for the configurable role model (AD #30)

  • Changed: § Permission rendering gains a model note: the guard’s driver is now the configurable permission model — a code-declared permission catalog with (role, permission_key, scope) grants (AD #30 / PRD Rev 21) — not (role, resource, level). The rendering rule itself is untouched; the note maps “the role can never do this anywhere” onto the user’s effective permission set lacks the key, and names the two F5 surfaces the model adds under §8’s Users & roles entry (a catalog-grouped role editor showing each permission’s category and warning on outward-acting grants; an effective-permissions viewer).
  • Why: the section named the model it is driven by, and that model changed on 2026-09-07. Without the note a reader would build the FS-6 driver against the superseded shape. FS-3 plan Decision 13’s PermissionDecision union is agnostic to the backend model and is not affected — recorded so nobody reopens the approved FS-3 plan for this.
  • Impact: none on FS-3 (in dev). F5’s role editor and effective-permissions viewer are design-at-spec-time surfaces, not new components in this spec.
  • Approved by: Tharinda, 2026-09-07 — with AD #30.

Rev 13 — 2026-09-10 — the package split collapses to one src/{app,features,ui,lib} package (AD #31, FS-14)

  • Changed: §5–§7 titles and the “Consumed by” / “Where the tokens live” notes repointed off the former three-package UI workspace split onto the single-package layout — the token contract + atoms + FieldRenderer registry in src/ui, generic and tea screens in src/features. No token, component or screen requirement changed; only where the code lives.
  • Why: AD #31 (2026-09-09, FS-14) collapsed the frontend pnpm-workspace split into one package. This spec is the token/component contract those packages were written against, so its layout references had to follow or read as stale.
  • Impact: none on any FS-3 requirement, AC or shipped component — forge-et-fe and forge-et-pwa already moved the files in the FS-14 PRs; this is the doc catching up. The swappable-theme contract (names + fallbacks in src/ui, Empire values in each app’s theme-empire.css) is unchanged.
  • Approved by: Tharinda, 2026-09-09 — the AD #31 lead sign-off (the FS-14 cascade carries it).

Rev 14 — 2026-09-11 — §8 gains the Tea Room pricing screens (as a proposal); open item 2 halved

  • §8 screen inventory. The prototype’s bulk pricing moved off the catalog product and onto the account (a “Buying standards & prices” section) and a new Pricing screen — the Tea Room’s workspace, which §8 had listed as not in the prototype. The inventory now lists both, Accounts and Products are restated (Products is a catalog with a standards summary line, not a price board), and a paragraph marks the two new surfaces as team proposals rather than client-approved, alongside the two mocked affordances on them (Import this week’s sheet, Email this week’s prices to contacts) whose only source is a September 2026 follow-up meeting with no debrief filed.
  • Why it belongs in this spec at all: §8 is the list a feature spec reads to decide whether it is rendering an approved screen or designing one. Leaving the Tea Room screens in the to-design column after they exist would send F26’s spec to design something that is drawn; moving them without the proposal marker would send it to render something Empire has never seen. Both halves are load-bearing.
  • §10 open item 2 is halved, not closed — the Executive read-only views are still to design; the Tea Room half becomes a confirm-or-change against the drawn screens.
  • §9 Permission rendering is unchanged and was followed, not extended. The new screens hide what a role can never do (cost columns, publish controls, the Pricing nav entry) rather than greying it. One point worth recording because it is the failure the rule exists to prevent: the first cut hid the Pricing nav entry but left the route reachable, and the catalog’s “view prices” link walked a Sales Manager straight onto the screen. Hiding an entry point is not access control when a second entry point exists — the guard belongs on the screen.
  • No token, component or pattern changed.

Rev 15 — 2026-09-11 — the price-history chart is one series per standard (PRD Rev 23)

  • §6 Charts: the price-history row loses its per-destination-market series — PRD Rev 23 (2026-09-11) records one price per standard per week, so the chart is one series per standard, placed on the account section and the Pricing screen (§8), not the Products catalog. The prototype still draws per-market series pending a follow-up PR.
  • Why: a spec reading §6 would otherwise design a market filter the model no longer has.
  • No token, component or pattern changed.

Rev 16 — 2026-09-11 — §9’s category list is read / edit / execute (AD #32)

  • §9 Permission rendering, model note: the role editor shows three categories, not four — AI is not a grantable level (AD #32 / PRD Rev 24): system-run AI is not a permission, and user-invoked AI assist rides on the permission it serves. The hidden-vs-disabled rule and the PermissionDecision seam are unchanged.
  • Why: F5’s role editor would otherwise render a chip for a category the catalog no longer declares.
  • No token, component or pattern changed.

Rev 17 — 2026-09-15 — the Products screen is gone; the Pricing screen is the Buying Standards book (PRD Rev 27)

  • §8 screen inventory: Products is removed from the in-prototype list; Pricing is restated as the Buying Standards book — every client’s standards, add / edit / archive, the weekly publish — reached by permission, not role (AD #26). §6 price-history row: one series per standard, now drawn. Open item 2: the add / edit / archive-standard modals join the confirm-or-change list for F26.
  • Account section (F1/F26): shows no cost or profit — it is a sales view, and price plus profit % would reconstruct cost; both render on the Pricing screen and the quote only, behind the cost permission. Cost visibility is therefore a matter of which screen, not only which role.
  • Why: harness PR #88 (2026-09-15) removed the catalog from the prototype and PRD Rev 27 records the model — the Buying Standard is the sellable record for bulk and private label.
  • No token, component or pattern changed.

Rev 18 — 2026-09-18 — one typeface: Fraunces dropped, Inter everywhere

  • §1 typography: the two-face system (Fraunces display + Inter UI) becomes a single sans-serif system — Inter at every level. type/display and type/title change face from Fraunces to Inter (sizes, weights and tracking unchanged); the §1 table collapses the Display/UI typeface rows into one “Typeface: Inter” row; the logo wordmark and the login headline are Inter; font delivery ships one face. The Fraunces @font-face and the @fontsource-variable/fraunces dependency are removed from both frontends.
  • Numbers are unchanged and are NOT monospace: figures stay Inter with font-variant-numeric: tabular-nums for column alignment (the modern data-UI standard, not a mono face). The only monospace in the codebase remains the crash/error surface, which is conventional and unchanged.
  • Why: the CRM is an internal, data-dense tool, where a single sans-serif is the modern norm (Linear/Stripe/GitHub) — more consistent, one fewer font to load, and no legibility cost since all functional text was already Inter (the Fraunces serif was a brand accent on headings only). The prototype’s serif was never a client commitment — the prototype aligned Empire on features, not the visual brand (source-trust.md: the prototype is “our design” for the visual layer) — so this is a team decision, noted to Empire as an FYI in the weekly update, not a sign-off ask.
  • Scope: forge-et-fe and forge-et-pwa (theme + shared fonts.css/tokens.css, byte-synced; the dependency dropped from both). No component, layout or token name changed — only the face the display/title levels resolve to.

Rev 19 — 2026-09-20 — §9 session-expiry convention + §5 DropdownMenu trigger slot (F5-b WI-1.2, FR-13 / OQ-1)

  • §9 gains “Session expiry and return-to-route”: F5-a’s session-expiry behaviour is promoted to a documented cross-feature convention (FR-13/AC-13, discharging F5-a’s W-2) — a 401 or missing session redirects to /login preserving the attempted route in the router state.from, no authenticated chrome renders before the session resolves, and post-sign-in returns the user to state.from (or the default landing). A protected route inherits the rule by mounting inside the shared authenticated gate; it must neither reimplement nor drop it.
  • §5 Dropdown menu records the new optional trigger?: ReactNode slot (OQ-1, approved at the F5-b WI-1.2 plan review): when supplied it replaces the default string-label Button trigger while preserving the menu-button ARIA contract (aria-haspopup/aria-expanded/aria-controls/aria-labelledby); the string-label path is unchanged. The sidebar current-user menu (§6) passes its avatar + name + role identity block as the trigger.
  • Why: F5-b’s app frame consumes both — the frame mounts inside F5-a’s authenticated gate (which already preserves state.from), and the sidebar-footer current-user menu needs the identity block itself to be the single clickable trigger, which the fixed string-label Button could not express.
  • Scope: .forge/design/ui/design-system.md §5 + §9 only; no token, component or layout renamed. The trigger? prop ships in forge-et-fe WI-1.2 as an additive, backward-compatible change to the shipped DropdownMenu. W-3 (flip §9’s “proposed” sidebar reflow to “confirmed”) remains a Wave-2 ship-time action, not this revision.

Rev 20 — 2026-09-21 — §9 light-only scope made explicit for both frontends (all V1 phases)

  • §9 dark-mode note: the “Dark mode is not in V1” line now states the scope in full — both frontends (the CRM forge-et-fe and the F36 capture PWA forge-et-pwa) ship light mode only; dark mode is out for all of V1 (neither Phase 1 nor Phase 2) and becomes a future-release item only on Empire’s request.
  • Why: team decision (lead, 2026-09-21). The prior wording read as CRM-only and V1-implicit; stating it explicitly removes any read that the PWA or a later phase might carry a dark theme. Consistent with F5-b spec Rev 1 (AC-14/NFR-1 light-only) and .forge/test-strategy.md §Deliberately Not Tested.
  • Scope: §9 wording only; no token, component or layout changed. Mirrored into the PRD Accessibility NFR (PRD Rev 33).

Rev 21 — 2026-09-21 — §9 gains the expiry-notice rule (BUG-007)

  • §9 “Session expiry and return-to-route” gains a fourth bullet: an involuntary expiry (a session that was established, ended by a mid-session 401 or a reload that lost it) surfaces one polite role="status" notice in the notice tone on the login page; a genuine first visit and a deliberate sign-out stay silent; ?login=failed takes precedence. Records that the “was authenticated” fact rides on a persisted per-browser marker because the only observable path is a reload, which an in-memory flag cannot survive.
  • Why: BUG-007 — the login page could not tell an expiry from a first visit, so the expiry went unexplained. Rev 19 promoted only the route-preservation half of F5-a’s W-2; this completes it with the notice half the FR always carried but no AC or convention encoded. Discharges the W-2 “owed: promote the notice to a cross-feature convention once F5-b lands” item.
  • Scope: §9 wording only; no token, component or layout changed. The implementing code and tests are forge-et-fe (BUG-007 fix PR); F5-a spec Rev 2 adds the matching acceptance criterion.

Rev 22 — 2026-09-22 — §5 gains the “layout-first alignment” build posture (BUG-010)

  • §5 gains a “Build posture: layout-first alignment” paragraph beside the native-first one: alignment is done with layout primitives (flexbox/grid, gap, align-items, text-box-trim for text beside an icon), never with a pixel nudge (transform: translateY/X, negative margin, position offset) added to correct appearance — and this holds even when the nudge is token-derived, since a calc() on a token is still a magic offset. Designed effects (hover lift, toggle travel, drawer slide, documented border overlap) are the legitimate exception. Names text-box-trim (under @supports) as the standard fix for text-beside-icon centring.
  • Why: BUG-010 — the top-bar search placeholder was first fixed with a token-derived translateY nudge that read slightly off and chased a sub-pixel target; the standard text-box-trim fix has no magic value. An audit of both frontends found BUG-010 was the only such nudge (the token-only rule already bars raw px), but it slipped through because it was token-derived — so the convention targets the approach, not just raw literals. Enforced by frontend-reviewer dimension 6 and carried as a dev-facing rule in each FE repo’s CLAUDE.md.
  • Scope: §5 wording only; no token, component or layout renamed. Companion changes: frontend-reviewer.md, forge-et-fe/forge-et-pwa CLAUDE.md.

Rev 23 — 2026-09-23 — open item 5’s due point follows the capture stream into Phase 2

  • §10 open item 5 (capture-app theme mapping): “before the capture stream starts (~week 8)” becomes Phase 2, from 26 Oct. Gate 3 placed the capture stream alongside the Phase 2 work (PRD Rev 35, client/project-timeline.md §2).
  • Scope: the due point only; the task itself is unchanged.

Rev 24 — 2026-09-24 — permissions by key, the access-model screens, and mid-session changes (AD #34, AD #35, AD #36)

  • §6: the sidebar “Role switcher” entry becomes the current-user menu — the product has no role switching (one role per user, none predefined); a nav entry hides when the user lacks that entity’s view key, and the route is guarded on the same key (F5-k).
  • §8: the Pricing screens’ rendering is restated by permission key — buying_standard.view (the whole build-up, costs included), buying_standard.manage, price.publish, and account.view for the account page’s final USD price — with the Tea Room / Administrator split named as the recommended configuration. The Users & roles entry drops “mechanics open: OQ-51”, sits behind access.manage, and lists the settled screens: users (F5-c), roles editor (F5-d), effective-permissions viewer (F5-e), sharing (F5-g) and bulk reassignment (F5-h); no audit-viewer screen in V1.
  • §9 Permission rendering: the model note is rewritten to AD #34’s catalog — no category chip and no outward-acting warning in the role editor; the effective-permissions viewer behind access.manage; “not in reach” named as a contextual (disabled) case. The hidden-case example names a read-only role rather than a fixed role, and the reason example names the permission, not the Managing Director, with the rule that a reason never names a role. The rendering rule itself is unchanged.
  • §9 gains “Permission changes and deactivation while signed in”: grants apply on the next request; the app re-reads /me after a 403 and on window focus; a background re-read never signs the user out; deactivation is the one change that ends a session and hands over to the session-expiry rule; the share picker does not list people who already reach the record, nor people whose role cannot view the record type.
  • Why: the lead’s access-model decisions of 2026-09-24 (AD #34 access model, AD #35 ownership and sharing, AD #36 audit trail). Rationale: .forge/engagement-log.md § AD #34, AD #35, AD #36.
  • Scope: §6, §8 and §9 wording only; no token, component or layout renamed. Rev 12 and Rev 16 stay as written — they record the model notes of their day. The prototype’s superseded access and sharing behaviour is listed in .forge/design/prototypes/feature-detail.md (F5).

Rev 25 — 2026-09-23 — §8’s “Settings/mailbox connect” resolved; §5 gains the section settings affordance (F20-b AC-32)

Written 2026-09-23 on the F20-b wave-1 branch as “Rev 23”; renumbered Rev 25 when that branch merged after Rev 23 and Rev 24 reached main first (an unmerged claim yields — .claude/rules/tracker.md, L-057).

  • §8: the open “Settings/mailbox connect — design at spec time” entry is resolved, not annotated. The connect screen itself is /email/mailbox (F20-a); the open half was how a user reaches it, and that is now the §5 row below.
  • §5 gains a Section settings affordance row: a Button / ghost-icon with the settings icon concept and an accessible name naming the destination, in the screen header beside the level-1 title, navigating to the section’s settings sub-view. It renders only where the sub-view holds something the current screen does not — on /email, present for ACTIVE and RECONNECT_REQUIRED, absent with no connection, while loading and after a failed read (the BUG-020 absence rule, generalised by F20-b FR-10b / AC-25c).
  • Two icon concepts added to the registry with it: settings (lucide Settings) and attachment (lucide Paperclip, the inbox row’s attachment indicator, F20-b AC-20b).
  • Why: F20-b spec FR-10b and AC-32 — BUG-015 shipped because no acceptance criterion said a way into /email/mailbox existed, and F20-a’s minimal fix was a bare text link. Without this write-back §8 stays open and the next section invents a second affordance. W-1 answered 2026-09-23 (Dinil): the affordance is accepted as our design and becomes the pattern later screens follow. It is not client-approved — the prototype’s Inbox does not contain it, and Empire first sees it at the demo (the D-6 / OQ-52 divergence is recorded in the F20-b spec rather than absorbed here).
  • Not covered: the inbox sync indicator and its labels are F20-b wave 2’s and stay provisional under §5’s status-label rule.
  • Scope: §5 one row, §8 one entry. No token changed. Implementing code: forge-et-fe src/features/email/InboxToolbar.tsx, src/ui/icons/registry.ts (F20-b-WI-1.2).

Rev 26 — 2026-09-24 — §5 gains a provisional mail-sync row (F20-b AC-26)

  • §5 status table gains a Mail sync row, marked provisional: Healthy tone/positive solid Receiving mail; Waiting tone/neutral half-filled Waiting for mail; Lapsed tone/danger ring Not receiving mail. The connected panel at /email/mailbox shows all three; the inbox at /email shows the lapsed state only, as a tone/danger Card above the list. A note beneath the table records that the shape trio is this feature’s choice mirroring Fresh / Ageing / Rotting rather than a §5 rule, and that Waiting takes tone/neutral rather than tone/notice on purpose.
  • Why: F20-b FR-11 and AC-26 replace F20-a’s neutral “Mail sync arrives with the inbox” line with a real indicator, and §5’s table had no row for it. The three states come from the frozen F20-b Wave-2 contract, which names the third (Waiting — connected, nothing ingested yet) so the implementation and the browser suite do not each invent it.
  • What this does not settle: the wording. It is this project’s proposal: the PRD names no sync states, §5 already states that labels are provisional where the PRD names none, and W-1 (answered 2026-09-23) accepted the settings affordance as our design but did not reach the sync indicator. Nothing is closed by this revision.
  • Scope: §5 one row and one note. No token or component changed. Implementing code: forge-et-fe src/features/email/syncState.ts (labels and sentences), SyncIndicator.tsx, SyncLapsedNotice.tsx (F20-b-WI-2.2). If another branch claims Rev 26 first, this entry renumbers — an unmerged claim yields.

Rev 27 — 2026-09-27 — §3 and §5 stop recommending text/muted for normal-size text (BUG-019 follow-up)

  • Changed — three rows now name text/secondary where they named text/muted: §3’s type/micro row (column headers, eyebrows, badges), §5’s Table header row, and §5’s Tabs inactive state (with hover moving to text/strong, so hover still darkens one step and stays short of the active text/primary).
  • Why: §2 limits text/muted (4.1:1 on white) to ≥ 14px bold or ≥ 18.66px, and all three rows describe text below that — type/micro is 10.5px/600 and tab labels are body size — so each row told a developer to ship a WCAG AA failure. §2 and the PRD accessibility commitment win over the three rows. forge-et-fe#43 already moved the code (the Tabs component included) and added src/test/mutedTextBand.test.ts, which fails any rule that pairs a normal-size type token with --et-text-muted; before this revision, a developer who followed §3 or §5 for a list screen’s column headers would have been failed by that test.
  • Not changed: no token value. text/muted stays for large text and non-text (icons, chevrons), where the 3:1 rule applies and it passes. text/faint is untouched — its low contrast on placeholders is a deliberate trade-off recorded in .forge/bugs.md BUG-019, not a defect.
  • Scope: §3 one row, §5 two rows. No code changes; the code already matches.

Rev 28 — 2026-09-27 — the supported sizes of both apps, and CRM reflow at 320px

  • Changed — § Viewport and breakpoints: the CRM stays desktop-first with the 768px tablet floor, and every CRM page now reflows at 320 CSS px (WCAG 2.1 SC 1.4.10 Reflow, Level AA — a 1280px desktop at 400% zoom): one column, no horizontal page scroll, no control clipped off-screen; genuinely two-dimensional content (Kanban, wide tables) may scroll inside its own region. Zoom support, not a phone design.
  • Changed — § The capture app: phone first, and tablet (768–1023px, both orientations) and desktop (≥1024px) supported. The phone layout holds in a centred column with a maximum content width; the 44 × 44px targets and 14px body text stay at every width; orientation is never locked (SC 1.3.4).
  • Why: lead decisions, 2026-09-27, from an audit of the built screens that found them clean at these sizes apart from four defects (BUG-028 to BUG-031). The proposal commits only to “a responsive web application”, so none of this changes scope; the checks that hold it are delivered as F40.
  • Not changed: tokens, components, the 24 × 24px CRM target floor and the 44 × 44px capture floor.

Rev 29 — 2026-09-27 — §8 model note: the role editor has no scope choice (AD #37)

  • Changed — §8 Permission-aware rendering, model note: grants are (role, permission_key); the role editor (F5-d) shows one none / view / manage choice per entity, an All records tick beside each entity that has an owner — enabled only once view or manage is chosen — and a tick per special key, in place of a scope per entity. The share-picker bullet names holders of the entity’s all key instead of all-scope holders.
  • Why: AD #37 (lead decision, 2026-09-27; PRD Rev 43).
  • Not changed: the hidden versus disabled-with-reason rendering rule, tokens, components.

Rev 30 — 2026-09-28 — the selected indicator and sidebar counts use the darker tokens (fe#28 review)

  • Changed — §2 accent/gold-deep usage, §5 Selected, §6 App frame:
    • The selected indicator (a left border, the nav glyph) uses accent/gold-deep.
    • Gold text on a light surface (the sidebar’s “Sales CRM” eyebrow) uses accent/gold-deep.
    • Sidebar count badges use text/strong on the neutral fill.
    • The icon-only rail shows each entry’s label as a tooltip on hover and focus, which §5’s Tooltip row already asked for.
  • Why: lead decision, 2026-09-28, on the post-merge /forge-review-pr of forge-et-fe#28.
    • accent/gold measured 1.87–2.75 : 1 as the nav glyph and edge on the rail, below WCAG 1.4.11’s 3 : 1 for non-text.
    • As the 10.5px eyebrow, accent/gold measured 2.19–2.75 : 1, below 4.5 : 1 for text.
    • accent/gold-deep measures 4.02–5.91 : 1 in the same places.
    • The sidebar count badge’s tone/neutral text measured 3.10–4.46 : 1.
    • Built by forge-et-fe#71, whose src/app/sidebarContrast.test.ts computes these pairs from the theme files.
  • Not changed: no token value. accent/gold keeps its fills (primary buttons, the pill background, the alert badge, the avatar) and the focus ring.
  • Open for the lead:
    • tone/neutral text is 4.46 : 1 on the generic §5 Badge’s own tinted fill, just short of AA (StatusIndicator, on white, is 5.46 : 1). Fixing it means changing the §2 value.
    • The accent/gold focus ring measures 2.19–2.75 : 1 against the sidebar, below 3 : 1. It is an app-wide token.

Rev 31 — 2026-09-28 — the focus ring and the neutral tone clear their contrast minimums

  • Changed — §4 Focus:
    • focus/ring-color is accent/gold-deep, not accent/gold.
    • On the toast’s dark fill, the Dismiss control draws the fill’s paired text colour (brand/deep-green-on) as its ring.
    • A heading or <main> that script focuses after a page change draws no ring.
    • A disabled control’s look uses muted colours, not element opacity, and is the same at rest and on focus, so its ring is always full strength (§5 Disabled row). A disabled primary, danger or positive button is therefore cream at rest.
  • Changed — §2 tone/neutral: the text value is #685641, not #7A6650.
  • Changed — the tablet drawer (§9): its scrim is no longer in the Tab order; Tab wraps inside the open drawer, and Esc or a visible close button in the drawer’s header closes it.
  • Changed — §9 Session expiry: ?login=unavailable takes the same precedence over the expiry notice as ?login=failed (F5-a Rev 5).
  • Why: lead decisions, 2026-09-28, closing the two items Rev 30 left open, plus what the reviews of forge-et-fe#71 and #73 found.
    • accent/gold as the ring measured 2.19–2.75 : 1 against the sidebar, below SC 1.4.11’s 3 : 1 for a focus indicator. accent/gold-deep clears 4 : 1 on every light surface that holds a focusable control, the tone tints included.
    • accent/gold-deep would measure 1.55 : 1 on the toast’s deep-green fill (accent/gold measured 3.32 : 1 there), which is why the toast takes its own paired colour.
    • The 55% disabled opacity faded the ring to 2.1–2.4 : 1, which undercut §9’s reason for keeping those controls focusable. Lifting the opacity only on focus made a disabled secondary button look enabled when focused and a disabled primary one change colour, so the disabled look drops opacity altogether. Open for the lead: in Empire, a disabled primary button is only faintly different from an enabled secondary one (fill 1.12 : 1 apart).
    • The generic Badge’s neutral text measured 4.46 : 1 on its tinted fill over a card, and 3.76 : 1 at the sidebar’s end. At #685641 it measures 5.72 : 1 over a card and 4.62 : 1 at the sidebar’s end, and it clears 4.5 : 1 on the canvas, the warm card and the inset too. An intermediate #77634D passed only on a card and was not kept.
    • A focused heading is not operable, so SC 2.4.7 does not require a ring on it, and the full-width box drawn on every page change was noise.
    • The scrim was a keyboard-reachable button whose ring fell outside the viewport.
    • Built by forge-et-fe#73 (ring, toast, disabled controls, badge, headings) and forge-et-fe#74 (scrim). Their suites compute these pairs from the theme files in both themes. The capture app takes the same ring and neutral values in forge-et-pwa#28; it has no toast and no disabled-but-focusable control. forge-et-pwa#29 re-copies its drifted shared files.
  • Not changed: the ring’s width and offset; accent/gold for fills and for the form fields’ focused border; the neutral theme’s values, which already passed.

Rev 32 — 2026-09-28 — §9 The capture app: the column token and the capture-only stylesheet (F40 FR-15, FR-16)

  • Changed — §4 Layout: a new row, layout/capture-column-max = 480px (--et-layout-capture-column-max), marked capture app only: the maximum width of the capture shell’s centred column from bp/tablet up, gutter included.
  • Changed — § The capture app: a paragraph stating how the capture app meets its body-type and column rules. forge-et-pwa/src/ui/styles/capture.css, the capture app’s own token layer loaded after the theme, re-values type/body, type/secondary and type/meta to type/card-title’s size at type/body’s weight, and declares layout/capture-column-max. From bp/tablet up the shell’s header row and <main> sit in one centred column no wider than that token; below bp/tablet the phone layout is unchanged.
  • Why: F40 W-1 (resolved 2026-09-28): the column’s maximum width is 480px, as a capture-only token named in a design-system revision. F40 W-2 (resolved 2026-09-28): every line of running text — body, secondary and meta — is at least 14px at the body weight, and the uppercase eyebrow is exempt. Rev 28 required the centred column and the 14px text but named no token and no mechanism. The token cannot live in tokens.css, which the capture app keeps as a byte copy of forge-et-fe’s, so it lives in the capture app’s own stylesheet.
  • Not changed: no shared token value — tokens.css, base.css, fonts.css and breakpoints.ts are unchanged in both apps, and the CRM’s type/body stays 13px; the CRM; type/micro (exempt by W-2); type/button (outside W-2’s list and unused by the capture app today — whether a future capture button label steps up is left open); the 44 × 44px capture target floor.
  • Scope: §4 one row, § The capture app one paragraph. Implementing code: forge-et-pwa src/ui/styles/capture.css, src/app/AppLayout.tsx, src/app/AppLayout.module.css, src/ui/useMediaQuery.ts (F40-WI-1.2). If another branch claims Rev 32 first, this entry renumbers — an unmerged claim yields.

Rev 33 — 2026-09-30 — §5 gains a provisional price-state row; §9 says how a unit price is trimmed (F26-b FR-U2, Q-15)

  • §5 status table gains a Price state row, marked provisional: Current tone/positive solid Current; Priced per quote tone/neutral half-filled Priced per quote; No current price tone/notice ring No current price. A note beneath the table records why Priced per quote is neutral and No current price is a notice, and that the price sits in its own column, never inside the indicator.
  • §9’s Unit price row now says a unit price shows at least two decimals and up to four, trimming trailing zeros and never dropping a non-zero digit, because the UI renders what it is given and does not round (F26-b spec Q-15). The earlier text said “2 decimals”, which would have required the browser to round a four-decimal API value.
  • Why: F26-b spec Rev 1 (FR-U2) shows each buying standard’s price state on the Pricing page’s Standards book and on the account page’s standards panel, and §5’s table had no row for it. The 2026-09-30 re-review found that the first draft named labels only, with no tone or dot shape, so its visual acceptance criterion could not be checked.
  • What this does not settle: the wording. It is this project’s proposal: the PRD names no price states, and §5 already states that labels are provisional where the PRD names none. Nothing is closed by this revision.
  • Scope: §5 one row and one note; §9 one row. No token or component changed. Implementing code: forge-et-fe, in the shared place F26-b’s plan chooses for the price display (src/ui or src/lib, F26-b FR-U5). If another branch claims Rev 33 first, this entry renumbers — an unmerged claim yields.

Rev 34 — 2026-09-30 — §2 and §5: disabled buttons and fields take one grey (BUG-035)

Written as Rev 33 on the BUG-035 branch, and renumbered because F26-b’s Rev 33 merged first (an unmerged claim yields).

  • Changed — §2: two new tokens, surface/disabled #E4E4E0 and text/disabled #66625A.
  • Changed — §5 Interaction states, Disabled row: every control that took the surface/inset disabled fill now takes surface/disabled, and its text takes text/disabled. That is a button of every family, Input, Select, Combobox, and the unchecked box of a checkbox or radio. A button’s border takes the fill’s colour, so no control border shows; a field keeps its control border. §5 keeps one disabled look for every control, still the same at rest and on focus, with no element opacity.
  • Decision: the lead’s option B2, extended the same day to fields, recorded in .forge/bugs.md BUG-035 (Tharinda, 2026-09-30). This closes the item Rev 31 left open for the lead. The options considered and rejected are listed there, grey for buttons only among them.
  • Why: after Rev 31, a disabled primary button differed from an enabled secondary one only by its fill (surface/inset, 1.12 : 1 from white) and a label one step lighter, and a disabled field was the same cream as an ordinary one. Measured in the Empire theme:
    • The grey fill is 1.27 : 1 from a card, 1.24 : 1 from a field’s enabled fill (surface/field), 1.10 : 1 from the canvas and 1.13 : 1 from inset. It has none of the palette’s cream or brown, so it does not read as one of them.
    • text/disabled is 4.76 : 1 on the fill, which clears 4.5 : 1 for normal-size text.
    • The focus ring (accent/gold-deep) is unchanged. It sits on the surface around the control (5.91 : 1 on a card, 5.12 : 1 on the canvas) and measures 4.64 : 1 against the new fill.
    • Accepted: with the border matching the fill, a disabled button’s edge is faint (about 1.1 : 1 against the canvas). WCAG exempts inactive controls, and the grey fill is the signal.
  • Not changed: the no-opacity rule, the not-allowed cursor, the reason carried in the accessible name (§9), a checked checkbox or radio (its state colours), a switch’s off track, a menu item’s disabled text, and every existing token value.
  • Scope: §2 two rows, §5 one row. Implementing code:
    • forge-et-fe: the two names and their neutral fallbacks in src/ui/styles/tokens.css (the contract owns every name, §9 Theming mechanics); the Empire values in theme-empire.css; the proof theme’s own values in theme-neutral.css; the disabled rules in Button, Input, Select, Combobox, Checkbox and Radio; the regression check in src/app/disabledFocusRing.test.ts. For each of the six controls, in both themes and the fallback, that check holds the fill to 1.2 : 1 from the fill the control draws when enabled and 1.08 : 1 from each surface it sits on.
    • forge-et-pwa: tokens.css re-copied byte for byte with its recorded hash updated; the same Empire values in theme-empire.css, held to the same floors by src/ui/styles/themeContrast.test.ts. No capture control is disabled yet; one that gains the state takes this look.

Rev 35 — 2026-09-30 — §9: sign-in and sign-out failures (BUG-052, BUG-053, BUG-054)

If another branch merges a Rev 35 first, this entry takes the next free number (an unmerged claim yields).

  • Changed — §9 Session expiry and return-to-route:
    • the attempted route survives the Microsoft redirect in the tab’s session storage, validated as a same-origin path that is not the login page (BUG-054);
    • three new bullets: a backend that is down shows a notice with Try again; a failed sign-out keeps the user signed in and says so (BUG-052); a page that fails to load offers Reload the page (BUG-053).
  • Decision: the lead’s, 2026-09-30, from the post-merge /forge-review-pr of forge-et-fe#21 (.forge/engagement-gate-runs.md § Post-merge /forge-review-pr backfill — 2026-09-30; .forge/bugs.md BUG-052 to BUG-054).
  • Scope: §9 only. Implementing code: forge-et-fe#101.

Rev 36 — 2026-10-04 — §9: the page title follows the route (WCAG 2.4.2)

If another branch merges a Rev 36 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §9 Conventions: every route sets document.title (<Screen name> — <App name>, the record’s name first on a record page) from its handle.title through one component, and the size matrix asserts it.
  • Decision: the lead’s, 2026-10-04, from the project audit (finding F-15, .forge/audits/2026-10-04-project-audit.md).
  • Scope: §9 only. Implementing code: the audit’s fix PRs in forge-et-fe and forge-et-pwa.

Rev 37 — 2026-10-05 — §4: ten layout measures become tokens

If another branch merges a Rev 37 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §4 Layout: layout/tooltip-max, layout/menu-max, layout/listbox-max, layout/listbox-max-block, layout/form-width, layout/toast-max, layout/dialog-max, layout/login-card, layout/message-max and layout/skeleton-block. The components had written these measures as literal ch, vh and rem values, in CSS Modules and in inline styles, which the token-literal scan did not read until it learned those units and every component with an inline style.
  • Decision: the second project audit (.forge/audits/2026-10-05-project-audit-2.md), under the standing rule that every written value is a token.
  • Scope: §4 only. Implementing code: the audit’s fix PRs in forge-et-fe (and forge-et-pwa, which carries tokens.css byte-for-byte).

Rev 38 — 2026-10-05 — §5 gains a Textarea row (F11-b WI-1.3)

Claimed as Rev 37 on the F11-b branches and renumbered Rev 38 when it met main, where the second project audit’s §4 entry had already taken Rev 37.

  • Added — §5 Core components: a Textarea row beneath Input — the Input row’s chrome and states on a native multi-line control, vertical resize only, aria-disabled plus readOnly when disabled.
  • Why: the lead form’s inquiry text is a pasted message (PRD F11; F11-b spec FR-C1), which a single-line Input would show on one line, and src/ui had no multi-line control.
  • Decision: the developer’s, 2026-10-05 (F11-b WI-1.3 plan, Decision 9), with the component’s interaction-manifest row.
  • Scope: §5 one row. No token changed. Implementing code: forge-et-fe src/ui/components/Textarea/ (exported from the src/ui barrel, with its row in src/test/interactionMatrix.tsx).

Rev 39 — 2026-10-07 — §5 and §6: row selection and the bulk-action bar built in src/ui (F5-h WI-1.3)

If another branch merges a Rev 39 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §6 Data table, Selection and Bulk-action bar rows: a Built pointer to the shared parts. Row selection is table parts with display props, as the sortable header is: SelectionHeaderCell (a <th> whose checkbox reads unchecked, mixed or checked over the current page), SelectionCell (the row’s box, the column pinned first, a selected row drawing a 1px accent/gold-deep leading edge), SelectionAnnouncer (one visually hidden status line for every change), and the useRowSelection hook with its resolveSelection helper. “All N” is a mode with an excluded set, so unticking one row after Select all keeps the other N − 1. BulkActionBar is the bar: a named region on surface/card-warm with radius/lg, the count, an optional Select all <total> <noun>, the consumer’s actions and Clear, in flow above the table rather than vertically sticky; it takes focus when it appears, Select all leaves focus on it, and Clear returns focus to the header checkbox.
  • Added — §5 Select / checkbox / radio row: the checkbox’s mixed state, and a label that is hidden visually but kept as the box’s name.
  • One icon concept added to the registry with it: indeterminate (lucide Minus), the mixed checkbox’s glyph.
  • Why: F5-h’s offboarding lists are the first that select rows (F5-h FR-U3), and §6 makes selection one shared component rather than a per-screen build, which F32-c and F32-b reuse.
  • Decision: the developer’s, 2026-10-07 (F5-h WI-1.3 plan, Decisions 1–15); the lead’s at plan approval for the “all N” mode, the in-flow bar, the “on this page” wording and the disabled mixed box keeping its state colours.
  • Scope: §5 one row, §6 two rows. No token changed. Implementing code: forge-et-fe src/ui/components/RowSelection/, src/ui/components/BulkActionBar/, src/ui/components/Checkbox/ and src/ui/icons/registry.ts (exported from the src/ui barrel, with their rows in src/test/interactionMatrix.tsx).

Rev 40 — 2026-10-08 — §5 status indicators: three priority levels and a hot / cold row

  • Changed — §5 Status indicators: the Priority row’s labels are P1 / P2 / P3; its three tones already mapped one to a level. The vocabulary note and the Confidence row read P1–P3.
  • Added — §5 Status indicators: a provisional Lead engagement — hot / cold row: Hot solid in tone/positive, Cold ring in tone/neutral, shown beside the priority. It is provisional because the tones and shapes are this project’s proposal; F11-g’s spec settles them.
  • Why: PRD Rev 55 (lead decision, 2026-10-08): three priority levels, and hot/cold as a separate indicator of how recently the buyer last wrote, not a relabelling of the priority.
  • Scope: §5, one row changed and one added. No token changed. No code yet: F11-g builds both.

Rev 41 — 2026-10-09 — shadcn/ui becomes the CRM’s component library (AD #39); the Users screen is the first moved over

If another branch merges a Rev 41 first, this entry takes the next free number (an unmerged claim yields).

  • Changed — the component set (§5) and the build posture. In forge-et-fe, new and changed screens use the shadcn/ui components in src/ui/shadcn (Radix UI underneath, Tailwind v4 classes mapped onto the --et-* tokens), adapted to this spec’s rules: disabled as aria-disabled with the §5 disabled look, base.css’s focus ring, registry icons, the Field wiring, sentence case. The §5 rows still say how each component behaves and looks; where a §5 row names a src/ui component, its shadcn counterpart is now the one to use. The in-house src/ui components stay on screens not yet moved over, listed in .forge/design/ui/shadcn-backfill.md. The capture app keeps its CSS Modules.
  • Changed — “Tailwind is not adopted” (§ Theming) now says how Tailwind v4 is mapped onto the tokens; open item 3 closed.
  • Added — the revamped colour layer (forge-et-fe src/ui/styles/theme-revamp.css): the primary, neutral and status scales and shadcn-style semantic tokens (background / foreground, card, popover, primary, secondary, muted, accent, destructive, success, warning, border, input, ring, sidebar), from the CRM design-system artifact. A route opts in with handle.theme: 'revamp', which re-points the existing colour names at the new semantic tokens; every text pair is held to 4.5:1 and every control edge to 3:1 by revampContrast.test.ts. The Users routes are the first. It becomes every route’s theme when the backfill is done.
  • Added — a screen’s three parts, on the Users list: a title bar (the h1 and the primary action), a data bar (search, filters and Clear filters on one row) and a body (the table in a card, its pager under it). The Users list is the reference for list screens moved over.
  • Changed for the Users routes only (each is scoped to data-et-theme="revamp", so other routes are unchanged until they are moved over):
    • The data bar has no labels above its controls. §5 Forms’ “Label above the control, always visible” stays the rule for form fields. In a filter bar each control names itself on screen with the same words as its accessible name: the search box by its search icon and the placeholder “Search users” (also its aria-label), and a dropdown filter by its name inside the trigger (“Status: All”, the word labelling the trigger). A placeholder alone never names a control.
    • Status indicator: the dot is half the §5 size (8px; the solid / ring shapes hold), and the label takes the text style of where it sits — in a table, the body cells’ size, weight and colour — instead of type/micro. It stays a dot plus a word, never a Badge.
    • Tables: the table scrolls inside its card (both ways, under a pinned header row) while the title bar, data bar and pager stay on screen. The header row is unshaded and in sentence case (no uppercase transform), at the body cells’ size and colour (type/secondary, text/primary) and set apart by semibold weight and its bottom border, instead of §5’s type/micro header on muted. The table runs to the card’s side edges: the card has no side padding around the table (the pager and the empty and error states keep theirs), and the scroll area keeps a thin scrollbar with an equal gutter on the left, so that strip is the only space beside the table and the table sits evenly in the card. Popups (the Select list, tooltips) sit on z/menu, above sticky cells.
    • Pagination: numbered, shadcn’s Pagination — Previous, the page numbers with a gap where pages are skipped (always seven items once there are more than seven pages), Next — with the range (1–25 of N) and Rows per page kept.
    • The app frame: no top bar; the sidebar toggle is an icon-only button in the sidebar header, and below bp/laptop the icon rail stays on screen to hold it.
  • Why: AD #39 — the in-house primitives left each screen to get spacing, sizing, alignment and layering right by itself; the Users screen, rebuilt on shadcn with these settings, is the pattern the other screens follow.
  • Decision: the lead’s for adopting shadcn/ui (AD #39, approval reported by Nanndish, 2026-10-09); Nanndish’s for each Users-screen setting above, chosen from mockups in the session of 2026-10-08/09.
  • Scope: §5 and the build posture; § Theming; open item 3. Implementing code: forge-et-fe src/ui/shadcn/, src/ui/styles/shadcn.css, src/ui/styles/theme-revamp.css, src/app/RouteTheme.tsx, src/features/users/, and the revamp-scoped rules in src/ui/components/StatusIndicator/ and src/ui/components/ErrorPanel/.

Rev 42 — 2026-10-10 — §5 AI provenance: the per-field marker (F12-WI-2.3)

Rev 41 is claimed by the open branch feature/ad-39-shadcn-ui; this entry takes the next number above every claim. If another branch merges a Rev 42 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5 AI provenance, a Per-field marker paragraph: in a form an AI pre-filled, the tone/ai chip labelled AI DRAFTED after the label of each field the AI filled, switching to AI DRAFTED · EDITED BY YOU while the person’s value differs from the AI’s; hidden from assistive technology, with “AI drafted” / “AI drafted, edited by you” read with the field’s label; the four-element block once above the fields, its chip edited when any field is; no marker on a field the AI left blank.
  • Why: F12’s pre-filled New lead form needs to show which fields the AI filled, not only that the form came from the AI (F12 spec FR-U3, NFR-7, AC-18), and §5 described the chip only for a whole artifact. F12 spec FR-H1 names this §5 row.
  • Decision: the developer’s, 2026-10-09 (F12-WI-2.3 plan, Decisions 8 and 15), at plan approval.
  • Scope: §5, one paragraph. No token changed, and tone/ai stays read by src/ui’s AiProvenance.module.css alone. Implementing code: forge-et-fe src/ui/components/AiProvenance/AiProvenance.tsx (AiFieldMarker, exported from the src/ui barrel, with its row in src/test/interactionMatrix.tsx) and the optional labelAddon on src/ui/components/Field/Field.tsx and src/ui/components/CheckboxGroup/CheckboxGroup.tsx.

Rev 43 — 2026-10-10 — §5 gains a provisional round-state row (F26-f FR-24)

If another branch merges a Rev 43 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5 Status indicators, a provisional Round state row: Draft tone/neutral half-filled Draft; Can’t publish tone/notice ring Can't publish · <reason>, the reason in words (Standard archived, Quoted per deal, Later price published); Published tone/positive solid Published; Withdrawn tone/neutral ring Withdrawn. A note beneath the table records why Can’t publish is a notice and Withdrawn is neutral, and that who and when sit in the status’s tooltip.
  • Why: F26-f’s Weekly prices tab shows each price row’s state (F26-f spec FR-18), and FR-24 asks for the rows, marked provisional, as F26-b did for the price state (Rev 33).
  • What this does not settle: the wording and the tones. They are this project’s proposal; the PRD names no round states.
  • Decision: the developer’s, 2026-10-10 (F26-f WI-1.2 plan, Decisions 10 and 20), at plan approval.
  • Scope: §5, one row and one note. No token or component changed. Implementing code: forge-et-fe src/features/pricing/RoundStatus.tsx (the vocabulary over StatusIndicator, feature-local because one screen uses it).

Rev 44 — 2026-10-10 — §8: a sidebar Settings entry for configuration shared across sections (F1-e)

Rev 43 is claimed by the open F26-f branches (feature/F26-f-plan and its work-item branches); this entry takes the next number above every claim. If another branch merges a Rev 44 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §8, a Settings line in “Not in the prototype”: configuration that no one section owns gets a sidebar entry, Settings, shown only to a settings.manage holder and placed last in the sidebar (after Roles, because the sidebar’s order is landing order). Its first page is Settings › Tags (/settings/tags, F1-e), where the account, contact and lead tag vocabularies are renamed, coloured, retired and restored. Later configuration that spans sections (F24 pipelines, F34 custom fields) adds pages under it.
  • Unchanged: the §5 Section settings affordance stays the way into one section’s own settings sub-view (for example /email → /email/mailbox). The two do not overlap: a section’s own settings use the affordance; vocabularies and configuration shared by several sections use the sidebar entry.
  • Why: F1-e spec Decision 5 and FR-T1. The tag vocabulary is shared by accounts, contacts and leads (and deals later), so no section’s header is the right place for it, and §8 says a section’s settings use the affordance “rather than inventing a second one” — this entry records where the line falls.
  • Scope: §8, one line. No token or component changes; the page is a §6 data table with §5 Modals.

Rev 45 — 2026-10-11 — §4: layout/list-region-block, the list pane’s data-region floor (BUG-145)

  • Added — §4 Layout, layout/list-region-block (24rem): the minimum height of a two-pane list’s data region while it holds rows (a state without rows — loading, a failure, an empty state — keeps its own height). When the pane’s header (title, actions, status pills, search, filters) is taller than the screen leaves, the pane grows past the column and the page scrolls, instead of the region shrinking until no row shows. Declared in forge-et-fe tokens.css and theme-empire.css; forge-et-pwa carries the shared tokens.css byte copy.
  • Why: BUG-145. At 1280 × 720 the lead list’s header is taller than the screen, so the scrolling region shrank to its 24px padding and sat below the bottom edge. The browser gate saw no overflow or clipped control, so only the F5-g design vision pass found it.
  • Scope: one token, used by the lead list pane (LeadListPane.module.css). The §6 two-pane pattern is unchanged; a later two-pane list uses the same token. When the page scrolls, the detail column scrolls with it; keeping it in view (sticky) would be a separate change, tracked as BUG-146.

Rev 46 — 2026-10-11 — §6: global search is dropped

  • Removed — §6 “Global search results (F31)”: replaced by a short “Search” entry. There is no top-bar search across record types; each list screen keeps its own search box in its filter row.
  • Why: the lead dropped F31 on 2026-10-11 (PRD Rev 60).
  • Scope: the search-field input size (layout/control-h-search) and the Combobox stay; list search boxes use them.

Rev 47 — 2026-10-11 — §9: the capture app keeps and retries failed uploads

  • Changed — §9, the capture app’s offline states: Offline / Queued / Syncing / Sync failed become No connection / Not sent / Sending / Failed. A capture whose upload fails is kept on the phone and sent again when the app is open with a connection, automatically or by Send now; there is no background sync.
  • Why: the lead dropped F36-e, the offline queue, on 2026-10-11 (PRD Rev 64); F36-a carries the retry.
  • Unchanged: a capture is accepted the moment it is taken, and nothing is lost to a closed tab.

Rev 48 — 2026-10-11 — stale search and price-history wording corrected

  • Fixed — §5 Combobox, §6 app frame and Search, the prototype screen list: they no longer describe a global search box in the top bar (F31 dropped, PRD Rev 60); the §6 Search entry notes the inert placeholder still on main, whose removal owed.md tracks. The prototype’s destination-market price history graph is marked not built: one price per standard per week has no market axis, and price history is the History list in the Tea Room’s round (F26-f FR-22).
  • Why: an independent consistency review of the 2026-10-11 scope changes (PRD Rev 65).

Rev 49 — 2026-10-12 — §9: the capture app signs in and out like the CRM

  • Added — §9, the capture app: it signs in and out with Microsoft through the backend exactly as the CRM does, and follows § Session expiry and return-to-route as written. Its sign-out control meets the 44px target.
  • Why: decided 2026-10-12. The capture app’s sign-in was already the CRM’s (2026-09-23, F36-a); sign-out was written down nowhere.
  • Left to F36-a: what a sign-out does to captures not yet sent on a shared phone.

Rev 50 — 2026-10-12 — §8: the contacts page and its contact view (F1-f); the contact icon

If another branch merges a Rev 50 first, this entry takes the next free number.

  • Added — §8, “Not in the prototype”: the contacts page (F1-f) — a Contacts sidebar entry after Accounts, gated on account.view, opening /contacts: a list on the §6 data-table pattern (a feature-local table like the accounts list, until F32’s shared table exists) with search, sort, an archived switch, numbered pagination and, for an account.all holder, a No account filter. A contact’s name opens a read-only contact view, a §5 Modal holding F1-e’s Tags and Notes; the writes (edit, archive, restore, Attach to account) are row actions, so no Modal opens over another, and a component inside the view confirms in place.
  • Added — the icon registry gains a contact concept for the sidebar entry, drawn with lucide’s Contact glyph; the glyph can change without touching the nav list, as for every concept key.
  • Why: F1-f spec FR-N1, FR-L1, FR-V1–V4 (PRD Rev 56; Phase 1 criterion C7). The prototype shows contacts only inside the account detail.

Rev 51 — 2026-10-12 — §5: a filter’s empty value as its placeholder

If another branch merges a Rev 51 first, this entry takes the next free number.

  • Changed — §5 Form fields: placeholders still show format examples only, in text/faint, with one exception: a filter where an empty value means “every one” may state that value as its placeholder (the Pricing Client filter’s All clients), in text/secondary (about 6.0 : 1 on surface/field, the input’s own fill), because the reader needs it. Combobox carries it as emptyValue, which styles the placeholder text/secondary; placeholder stays faint.
  • Why: BUG-161 — the empty Client filter was blank although it lists every client’s standards. “Choose a client” would have wrongly suggested a choice is required. text/faint (about 2.8 : 1) is never for text a user must read (§2), and WCAG 1.4.3 applies to placeholder text, which axe does not check (forge-et-fe#231 review, finding 1; the lead chose the darker colour, 2026-10-12).

Rev 52 — 2026-10-12 — §5 gains provisional sale-state and corrected round-state rows (F26-g FR-22)

Rev 51 is claimed by the open branch docs/BUG-158-161-166-close. If another branch merges a Rev 52 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5 Status indicators, a provisional Sale state row: Upcoming tone/neutral ring Upcoming; In progress tone/positive half-filled In progress; Held tone/neutral solid Held. A note beneath the table records that the state is the server’s (an In progress sale can be past its last day until the sweep marks it held), why Held is neutral, and that the shapes run empty → half → full.
  • Added — §5 Status indicators, a provisional Round state — corrected row: tone/positive solid Published · Corrected, with its note: the dot is Published’s because a correction is a published price, and the reason, who and when sit in the status’s tooltip.
  • Why: F26-g’s Auction sales tab shows each sale’s state (F26-g spec FR-15), and its Weekly prices tab shows a corrected price (FR-19); FR-22 asks for both rows, marked provisional, as F26-f did for the round state (Rev 43).
  • What this does not settle: the wording and the tones. They are this project’s proposal; the PRD names no sale states and no corrected state.
  • Decision: the developer’s, 2026-10-12 (F26-g WI-1.2 plan, Decisions 10 and 19), at plan approval.
  • Scope: §5, two rows and two notes. No token or component changed. Implementing code: forge-et-fe src/features/pricing/AuctionSalesTable.tsx (the sale-state vocabulary over StatusIndicator, feature-local because one screen uses it); the corrected state’s rendering is F26-g WI-1.3’s (RoundStatus.tsx), which follows this row.

Renumbered 2026-10-13 when main was merged into feature/F20-c-plan: main holds Rev 51 (BUG-161) and Rev 52 (F26-g), so F20-c WI-1.2’s entry is Rev 53 and WI-1.3’s is Rev 54, as each entry’s own claim note provides.

Rev 53 — 2026-10-12 — §5 gains a provisional Rich-text body row (F20-c WI-1.2)

Rev 51 is claimed by the open branch docs/BUG-158-161-166-close; this entry takes the next number above every claim. If another branch merges a Rev 52 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5 Core components: a provisional Rich-text body row beneath Textarea — the Textarea row’s surface and states on a contenteditable editor, a toolbar row of ghost-icon buttons with aria-pressed (bold, italic, bulleted list, numbered list, link) whose end holds a feature’s place, the keyboard shortcuts, the inline link row, and pasted or pre-filled formatting limited to the email allow-list.
  • Why: F20-c’s compose dialog has a formatted body (spec FR-C1, FR-S8, decision 7), and nothing in §5 described one. The editor is Tiptap 3.31.4, approved at the WI-1.2 plan review (D-1); its schema is the allow-list, the same list the server’s cleaner keeps (WI-1.1).
  • What this does not settle: whether the row moves to src/ui. It is provisional and feature-local under §0’s rule of two; the next feature that uses the editor (F20-d’s templates) confirms or revises it and promotes the component.
  • Decision: the developer’s, 2026-10-12, at the F20-c WI-1.2 plan review (Decision 17).
  • Scope: §5, one row. No token changed. Implementing code: forge-et-fe src/features/email/compose/RichTextBody.tsx and its stylesheet; the five formatting concepts join the icon registry (bold, italic, bulletList, numberedList, link).

Rev 54 — 2026-10-12 — §5 gains a provisional Safe message body row (F20-c WI-1.3)

Rev 51 is on main and Rev 52 is claimed by the F20-c WI-1.2 branch this work is stacked on (checked after git fetch on 2026-10-12: no harness branch claims a higher number); this entry takes the next number. If another branch merges a Rev 53 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5 Core components: a provisional Safe message body row beneath Rich-text body — a text body as text with its line breaks; an HTML body in a sandboxed frame with no script, form, top navigation or remote resource, links limited to http, https and mailto and opening in a new tab with no opener; the frame’s height following its content up to a growth limit; wide markup scrolling inside the frame at 320px; This message has no text for no body; inert in the interaction-state matrix.
  • Why: F20-c’s message view and the reply dialog’s quoted original show email bodies, which are untrusted (spec FR-I3, NFR-1), and no §5 primitive showed untrusted HTML. Both, and F1-c’s timeline Reply later, need the same one, so it is a shared src/ui component rather than a feature-local one.
  • What this does not settle: the frame’s look inside an email (the email’s own styles follow the CRM’s base text style and win), and the effect of a future CRM Content-Security-Policy on the frame, which only a deployed environment serves (F20-c WI-1.1’s cloud-gated register block, item (e)). The next consumer (F1-c) confirms or revises the row.
  • Decision: the developer’s, 2026-10-12, at the F20-c WI-1.3 plan review (Decision 9, allow-same-origin kept on the frame).
  • Amended 2026-10-13, before this entry reached main: the wave PR’s review (forge-et-fe#249) found that a declarative shadow root (<template shadowrootmode>) passed the cleaner unvisited and kept links of any scheme in the frame. The row now states that templates and shadow roots are removed with their content, and that the cleaned body is parsed a second time and falls back to plain text if anything disallowed reappears.
  • Scope: §5, one row. No token changed. Implementing code: forge-et-fe src/ui/components/SafeMessageBody/ (SafeMessageBody.tsx, safeSrcDoc.ts, frameHeight.ts and the stylesheet); forge-et-fe CLAUDE.md’s untrusted-HTML bullet names it.

Rev 55 — 2026-10-13 — §5 gains a provisional activity due-state row, the overdue-row tint and the activity type dot (F3-a FR-H1)

Revs 53 and 54 are claimed by open branches (next-id.py ds-rev, 2026-10-13). If another branch merges a Rev 55 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5 Status indicators, a provisional Activity due state row: Overdue tone/danger ring Overdue <n>d; Today tone/notice half-filled Today; Upcoming tone/neutral ring Tomorrow, In <n> days or the date; Done tone/positive solid Done <date>. Each is a status indicator with its visible label.
  • Added — the note beneath the table: the state is the server’s bucket against Colombo’s today; an overdue row also takes the tone/danger tint (#FCF5F2, --et-tone-danger-bg) across the row, with the chip’s text still saying Overdue; the activity type shows as a neutral dot plus the type’s label, which F3-b may colour for custom types.
  • Why: F3-a’s Activities page and Follow-ups panels show each follow-up’s due state, highlight overdue rows and mark the type (F3-a spec FR-V2), and its FR-H1 and AC-28 ask for these rows here.
  • What this does not settle: the wording of the chip and the tones and shapes. The bucket names are the PRD’s; the rest is this project’s proposal. The dot shapes are this revision’s choice, since F3-a’s spec names only the tones.
  • Decision: the developer’s, 2026-10-13, at the F3-a spec approval.
  • Scope: §5, one row and one note. No token or component changed. Implementing code: forge-et-fe, in F3-a’s feature folder over StatusIndicator; F3-a’s plan names the files.

Rev 56 — 2026-10-14 — §6 gains the Detail page rule: one capped column, centred (BUG-154, BUG-155)

  • Added — §6, a Detail page bullet:
    • The rule. An edit or settings page whose content is one column of forms or cards is one column capped at twice layout/list-pane-width, centred in the canvas, with its back link and header inside the column. That covers the user editor, an account’s New and Edit pages, and the Mailbox page.
    • The exception. A page whose content is a wide grid or table keeps the full width; the role editor is the case today.
    • Not covered yet. The account page, the message view and the offboarding sub-view (BUG-137).
  • Changed — §1, the surface/hover row: it now says a table row and the inbox’s message rows hover in surface/card-warm instead, as §5 Table already said (BUG-155).
  • Why: the plans capped these columns but said nothing about where to place them. On a wide screen the user editor, the account edit page and the Mailbox page sat against the left edge of the canvas, with the right side empty. Nanndish decided on 2026-10-08 to centre them (BUG-154, BUG-155).
  • Scope: §1, one token row’s wording; §6, one bullet. No new token: the existing cap is reused, because layout/* is shared byte for byte with forge-et-pwa. Implementing code: forge-et-fe UserEditor.module.css, AccountFormPage.module.css, AccountFormRoute.module.css, MailboxRoute.module.css, InboxToolbar.module.css and InboxList.module.css, in forge-et-fe#257.

Rev 57 — 2026-10-14 — §9: a special key that needs another is blocked, like All records (BUG-167)

  • Changed — the §9 model note: a special key’s tick whose key requires another (the catalog’s requiresOneOf) is enabled only once one of those is chosen, and shows its reason while it is not — the same pattern as the All records tick. Today that is Publish weekly prices, which needs View or Manage on Pricing; choosing None on Pricing clears it.
  • Why: BUG-167. The lead decided on 2026-10-14 that price.publish is held only beside buying_standard.view or buying_standard.manage (PRD Rev 71, FS-6 Rev 16, F5-d Rev 3).
  • Scope: §9, one sentence. No new token or component: the blocked tick reuses the All records tick’s pattern.

Rev 58 — 2026-10-14 — §6 Detail page: the role editor is one centred column too (BUG-141)

Drafted as Rev 57; renumbered to Rev 58 on 2026-10-16 because main took Rev 57 for BUG-167 (next-id.py ds-rev).

  • Changed — §6, the Detail page bullet: the role editor moves from the full-width exception into the rule, and the exception now names no page.
  • Why: Rev 56 kept the role editor at full width for its “permission matrix”, but the editor is one column of permission-group cards, each a row of choices, which fits the 720px cap with nothing overflowing (measured at 1280px, 768px and 320px). At full width it sat against the left edge as the user editor did before BUG-154. Nanndish decided on 2026-10-14 to centre it (BUG-141).
  • Scope: §6, one bullet. Implementing code: forge-et-fe RoleEditorForm.module.css and RoleEditorRoute.module.css, with the role editor added to e2e/browser/shell/detail-page-column.spec.ts, in forge-et-fe#262.

Rev 59 — 2026-10-15 — §5: a section may carry more than one settings button (F20-d)

Rev 58 is claimed by an open branch. If another branch merges a Rev 59 first, this entry takes the next free number.

  • Changed — §5 Section settings affordance: a section may carry more than one settings button, each with its own icon concept and accessible name, and each rendered by the rule for its own sub-view. The email section gains Email templates → /email/templates, shown in every mailbox-connection state, while Mailbox settings keeps its rule.
  • Why: the F20-d spec (approved 2026-10-15, decision 6, FR-D1) puts the templates screen in the email section, beside the mailbox settings, because templates are the email section’s own configuration; a user may write templates before connecting a mailbox.
  • Scope: §5, one row. The icon concept for templates is chosen at F20-d’s plan from the icon registry; no new token.

Rev 60 — 2026-10-14 — §5 Attachment row gains the compose variant; File upload takes several files; four file-type icons (F20-h WI-1.2)

Drafted as Rev 59; renumbered to Rev 60 on 2026-10-15 because forge-et-harness#700 also adds a Rev 59 (next-id.py --check-pr 710).

  • Added — §5 Attachment row, the compose variant (F20-h’s compose dialog, spec FR-C2, FR-C5): one file per row — the type icon at icon/sm in text/secondary, the name shortened from the middle so its extension stays visible (the full name read by a screen reader), and a meta line in type/meta and text/secondary holding the size and the state. It has no uploader, date or download action: an email upload is the user’s own, made now, and is never downloaded through the CRM. Its actions are Remove, and Retry on a failed upload that a new upload can fix; each is named with its file. States, in sentence case:

    • uploading — “Uploading” and a determinate progress bar (shadcn Progress);
    • ready — the size only; a file not scanned (NOT_SCANNED) is ready too, with no wording that claims it was checked;
    • being checked — §5’s scanning state, “Being checked”;
    • refused — tone/danger: the state text in tone/danger-text, a tone/danger-border leading edge, “Refused: this file may contain a virus. Remove it to send the email.”;
    • failed — tone/danger, the reason, with Retry when it can succeed;
    • unavailable — “No longer available. Remove it and attach the file again.”;
    • removed — for a forwarded original only: “Removed — not forwarded”, with Undo.

    The row is a flex line with a space/4 gap and space/3 block padding, set off by a 1px border/row hairline; below the dialog’s width its actions wrap under the text. It is built as the src/ui component AttachmentRow (no shadcn counterpart; a CSS Module on the tokens), its actions shadcn Buttons supplied by the caller. F33’s record attachments add the uploader, date and download parts.

  • Changed — §5 File upload: the src/ui FileUpload (no shadcn counterpart) gains multiple (the prompt then reads “Drop files here, or”), browseLabel (the visible control’s word in place of Browse, which also starts the input’s accessible name) and icon (the zone’s concept, upload by default). A caller with several files keeps the zone idle and draws a determinate bar per file in its rows; the zone’s own bar stays indeterminate for one-file callers that cannot report progress.

  • Added — §4, the registry: fileText (lucide FileText: PDF, Word), fileSpreadsheet (FileSpreadsheet: Excel), filePresentation (Presentation: PowerPoint) and fileImage (FileImage: JPEG, PNG). A file of another or unknown type draws attachment.

  • Added — src/ui/shadcn gains progress: shadcn’s Progress, added with the CLI and made determinate (value and max reach Radix’s root, so it exposes aria-valuenow and aria-valuemax).

  • Two themes in one dialog (intentional, until the dialog is moved over). F20-c’s compose dialog is listed in src/app/shadcnBackfill.json and is still on the older Modal, Button, Input and LoadingSkeleton, and the Email routes do not opt into theme: 'revamp'. The attachment sections’ shadcn Buttons (variant="outline", --et-input), Skeleton and Progress (--et-primary) therefore take the revamp tokens and look different from F20-c’s Send and Cancel until the dialog is moved to shadcn (shadcn-backfill.md, the Compose email dialog row). The shadcn classes are not overridden with CSS Modules.

  • Why: F20-h attaches files to an email (spec FR-C1–FR-C5); §5’s Attachment row and File upload described a record’s stored file, not an email’s.

  • Decision: the developer’s, 2026-10-13, at the F20-h WI-1.2 plan review (## UI / Design Adherence, Decisions 20 and 25).

  • Scope: §4, four registry concepts; §5, the Attachment row and File upload rows. No token changed. Implementing code: forge-et-fe src/ui/components/AttachmentRow/, src/ui/components/FileUpload/FileUpload.tsx, src/ui/shadcn/progress.tsx, src/ui/icons/registry.ts, and in src/features/email/compose/ ComposeAttachmentsSection.tsx and ForwardAttachments.tsx.

Rev 61 — 2026-10-14 — §6 gains the Save bar; §5’s toast may carry one action, and new toasts are Sonner (BUG-191)

Drafted as Rev 58; renumbered to Rev 61 on 2026-10-16: main took Rev 57 and Rev 60, forge-et-harness#700 holds Rev 59, and the role-editor revision above took Rev 58 (next-id.py ds-rev).

  • Added — §6, a Save bar bullet: on an edit page whose changes are kept until Save, the buttons sit in a row that stays in view, says how many changes are unsaved (or that all are saved), and marks each changed field, permission choice or tick with an edge and a text note. Save and Discard confirm in a toast naming the record and the count; the Discard toast offers Undo.
  • Changed — §5, the Toast row: a toast may carry one action, and a toast with an action stays until it is acted on or closed. New toasts in the CRM are shadcn’s Sonner (AD #39); the older src/ui Toast stays where it is used until its screen is moved over (shadcn-backfill.md).
  • Why: on the user and role editors the only feedback was a small line (“Role saved”, “Changes discarded”) at the left of the page while the buttons were at the right; nothing showed that edits were unsaved; on a long role the buttons scrolled out of view; and a mistaken Discard could not be undone. The UI/UX review found these on 2026-10-14 and Nanndish decided the design (BUG-191). It replaces BUG-159’s line in the live region.
  • Scope: §5, one row; §6, one bullet. No new token: the warning tint, border-width/selected and text/secondary exist. The sonner package was approved by Nanndish on 2026-10-14. Implementing code: forge-et-fe src/ui/shadcn/sonner.tsx, RoleEditorForm.tsx and UserEditorForm.tsx.

Rev 62 — 2026-10-15 — §5 Rich-text body confirmed on shadcn, the inline pick list, two icons, and §8’s email templates (F20-d WI-1.2)

Drafted as Rev 60; renumbered to Rev 61 on 2026-10-16, because F20-h’s Rev 60 reached main first, then to Rev 62 the same day, because forge-et-harness#690 also adds a Rev 61 (next-id.py --check-pr 708).

  • Changed — §5 Rich-text body:
    • No longer provisional.
    • Its toolbar and link field are on shadcn (AD #39): ghost icon buttons with aria-pressed, and a shadcn Input and outline buttons in the link row.
    • It gains a slot for a feature’s actions after the Formatting group, a panel row under the toolbar, and insertion at the cursor.
    • It stays feature-local in src/features/email/compose/, because both consumers are in the email feature. This revises Rev 53’s expectation that the second consumer would promote it to src/ui.
  • Added — §5 Inline pick list:
    • A searchable list opened as a row under its trigger, its search box named by a search icon and a placeholder identical to its aria-label (Rev 41’s data-bar pattern).
    • It keeps §5 Combobox’s keyboard and announcement behaviour.
    • It is used for Insert merge field and Insert template instead of shadcn’s Command in a Popover, which would need the cmdk package. The developer kept the inline list at the WI-1.2 plan review.
  • Added — §4 icons: two concepts in the registry. emailTemplate is lucide LayoutTemplate, used for the inbox header’s Email templates and Insert template. mergeField is lucide Braces, used for Insert merge field.
  • Added — src/ui/shadcn: tabs, radio-group and alert-dialog, adapted as the existing components are.
    • The alert dialog sits on z/overlay with the Modal’s scrim and card.
    • Its action and cancel take buttonVariants; they do not use the adapted Button with asChild, which fails (BUG-201).
    • It is not opened inside the compose dialog, whose native <dialog> is in the top layer (§4).
  • Added — §8: the email section’s templates list and editor (/email/templates, /email/templates/{id}, /email/templates/new), built on Rev 41 and §6 Detail page, and Insert template in the compose dialog.
  • Why: F20-d (spec decision 7, FR-S1–FR-S6, FR-C1–FR-C6, NFR-5) is the rich-text body’s second consumer and moves its toolbar onto shadcn.
  • Decision: the developer’s, at the F20-d WI-1.2 plan review (Decisions 3–7, 24), 2026-10-15.
  • Scope: §5, two rows; §8, one item. No token changed. Implementing code, all in forge-et-fe:
    • src/features/email/compose/RichTextBody.tsx;
    • src/features/email/templates/ (PickList.tsx, EmailTemplatesScreen.tsx, TemplateEditorForm.tsx, InsertTemplate.tsx);
    • src/features/email/InboxToolbar.tsx;
    • src/ui/shadcn/{tabs,radio-group,alert-dialog}.tsx;
    • src/ui/icons/registry.ts.

Rev 63 — 2026-10-16 — §5: a provisional Price email status row (F26-d)

  • Added — §5 Status indicators, a provisional Price email — sent this week row: Prices sent <date>, tone/positive, solid dot, shown beside Send this week’s prices in the account header when a price email is recorded for the current auction sale; the tooltip and accessible name add the addressee and the sender. With none, nothing is shown.
  • Why: F26-d spec FR-U5 and FR-D1 — the rep needs to see that this week’s prices already went to the customer before sending again.
  • Decision: the developer’s, in the F26-d spec (2026-10-16). Provisional because the PRD names no wording; F26-d’s review may change it.
  • Scope: §5, one row. No token changed. Implementing code: F26-d’s action in forge-et-fe src/features/, named by its plan.

Rev 64 — 2026-10-16 — §5: shadcn’s Checkbox, and Send this week’s prices built (F26-d WI-1.2)

If another branch merges a Rev 64 first, this entry takes the next free number (an unmerged claim yields).

  • Added — src/ui/shadcn: checkbox, adapted as radio-group is:
    • disabled renders as aria-disabled; the box stays focusable and announced, and neither a press nor Space changes it.
    • The tick is the registry’s selected icon.
    • The button is a 24px box around the 16px square it draws, meeting the 24 × 24px target floor.
    • Inside a Field it takes the field’s aria-describedby and aria-invalid.
  • Implemented — the account header’s Send this week’s prices and its preparation dialog:
    • The dialog is shadcn’s Dialog as F1-f left it, on z/overlay, at layout/dialog-max through the caller’s module class.
    • It uses F1-f’s frame: a header row with its own ✕, a scrolling body, and a footer on surface/card-warm.
    • To is a radio group and Also copy a set of checkboxes, each a §5 labelled group field.
    • With 49 contacts ticked, the unticked boxes are unavailable and the field’s helper reads At most 49 contacts can be copied.
  • Changed — §5’s provisional Price email — sent this week row (Rev 63) is implemented. The status indicator sits in a focusable ghost button inside a tooltip trigger, so the tooltip opens on keyboard focus, as RoundStatus does for the round states. The row stays provisional until F26-d’s review.
  • Kept — /accounts/:id stays on the Empire theme. The shadcn parts draw the Empire values through shadcn.css; the page moves to the revamped colour layer with its shadcn-backfill.md row (F26-d spec Rev 1, WI-1.2 plan Decision 22).
  • Why: F26-d spec FR-U1–FR-U6 and NFR-5; AD #39.
  • Decision: the developer’s, at the F26-d WI-1.2 plan review (Decisions 7, 15 and 22), 2026-10-16.
  • Scope: §5; no token changed. Implementing code, all in forge-et-fe:
    • src/ui/shadcn/checkbox.tsx;
    • src/features/priceEmail/ (AccountPriceEmailAction.tsx, PriceEmailDialog.tsx, PriceEmailMarker.tsx).

Rev 65 — 2026-10-19 — §6: the activity timeline’s entry layout and kind markers; §5: the Dormant row (F1-c FR-H1)

If another branch merges a Rev 65 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §6 Activity timeline: the entry layout as built — a Card with the panel’s name, an ordered list newest first, each entry a marker, the kind’s name and the summary, then a meta line with the date and time and by or System; Show older entries, 20 at a time, with focus on the first new entry and one status line; no link or action on an entry in V1; and the empty state with no action, an exception to §5’s “primary action” because the timeline’s rows come from other panels.
  • Added — §6, the marker colour per kind: a table of the eight kinds and the neutral marker for any other value, each an existing §2 token. The marker colours are separate from Rev 55’s neutral activity-type dot on F3-a’s Follow-ups panel: that dot marks a follow-up’s type, these mark a timeline row’s kind.
  • Recorded — two markers sit just under the 3:1 floor on purpose. The theme’s comments set 3:1 on surface/card as the floor for icons and other non-text marks. lead (accent/gold, 2.75:1) and note (text/faint, 2.81:1) fall just short: both are the prototype’s own colours and are plainly visible as a 9px dot, WCAG does not require the floor here because the marker is hidden from assistive technology and the kind is named in text, and no other token gives the prototype’s gold or faint brown. Every other marker reaches 3:1. sample takes tone/neutral text, not the prototype’s mid green, which has no token.
  • Added — §5 Status indicators, the Dormant row as built: tone/notice, ring, label Dormant, in the account list’s Status cell and the account page header (AccountStatusMarks). The rule is F1-c’s (FR-D1, FR-D2).
  • Why: F1-c spec FR-H1 and AC-20 — §6 described the timeline in one line, and §5 had no Dormant row although the code already shows the mark.
  • Decision: the developer’s, in the F1-c spec (2026-10-13); the marker colours at the F1-c WI-1.2 plan review (Decision 7), 2026-10-19.
  • Scope: §5, one row; §6, one bullet and its table. No token changed. Implementing code: forge-et-fe src/features/timeline/ (AccountTimelinePanel.tsx, TimelineEntryItem.tsx, timelineKinds.ts, AccountTimelinePanel.module.css).

Rev 66 — 2026-10-19 — §5: the lead row’s AI tag, and the AI tag badges’ variants (F11-d WI-1.2)

Renumbered from Rev 65 on 2026-10-19: F1-c’s plan PR #774, opened before F11-d’s #788, holds Rev 65 (.claude/rules/id-numbering.md rule 5). If another branch merges a Rev 66 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5 AI provenance, a list-row form: a list row may carry an AI judgement as the tone/ai chip labelled AI followed by the word in a shadcn Badge, with no confidence and no source, when the row opens the record whose panel shows all four elements. The lead row is the one use: its Spam or Duplicate tag, next to the lead’s labels and outside them, opening the lead view whose AI summary panel carries the chip AI SUMMARY, Confidence <n>% and from: <source>. The row’s Existing customer? marker is a shadcn Badge on outline, with no chip.
  • Added — §5 Badge, the AI tag’s variants: Spam takes the shadcn destructive variant and Duplicate the secondary variant, on the row and in the panel’s tag block. The word carries the meaning, so colour is never the only channel (§2); a dismissed tag shows Tag dismissed by , in type/meta and no badge.
  • Why: F11-d spec FR-V4 asks the row to show the AI tag “with the AI marker”, visibly different from a label a person set, and FR-V2 asks for a Spam or Duplicate badge in the panel. §5 says the four provenance elements “ship together or the requirement is unmet”; the row departs from that, so the departure is recorded here rather than absorbed, as Rev 42 recorded the per-field marker.
  • Decision: the developer’s, at the F11-d WI-1.2 plan review (Decision 20), 2026-10-19.
  • Scope: §5, two rules. No token changed, and tone/ai stays read by src/ui’s AiProvenance.module.css alone. Implementing code, all in forge-et-fe:
    • src/features/leads/LeadRowAiMarkers.tsx (rendered by LeadRow.tsx);
    • src/features/leadTriage/TriageTagBlock.tsx.

Rev 67 — 2026-10-26 — §10: items 4 and 13 closed, as FS-3 built them

Takes the number forge-et-harness#783 held, which closed unmerged (.claude/rules/id-numbering.md rule 2); placed here in number order, though written after Rev 69.

  • Closed — §10 item 4 (the self-hosted font bundle): FS-3 self-hosts Inter only (Fraunces was dropped at Rev 18) from @fontsource-variable/inter, latin subset.
  • Closed — §10 item 13 (the font-display strategy): FS-3 decided font-display: swap (FS-3 spec Q-7), with a metric-tuned fallback face that removes the reflow on arrival.
  • Why: the harness review of 2026-10-26 found both items still listed as open, while forge-et-fe main’s src/ui/styles/fonts.css records both as built and decided.
  • Scope: §10, two rows struck through. No rule or token changed.

Rev 68 — 2026-10-21 — §9: a table’s first column is pinned from bp/tablet up only (BUG-232)

Numbered after Rev 67, which forge-et-harness#783 holds unmerged (.claude/rules/id-numbering.md rule 5). If another branch merges a Rev 68 first, this entry takes the next free number.

  • Changed — § Viewport and breakpoints, the 320px reflow: a data table’s first column is pinned only from bp/tablet up. Below it nothing is pinned, and the table scrolls inside its own region, which SC 1.4.10 allows. The breakpoint table’s Tables row (first column pinned at 768–1023) is unchanged.
  • Why: BUG-232. At 320 × 640 the app keeps a 76px sidebar rail, so the contacts table’s scroll region is 206px wide. The pinned Name column took 101px of it and the Actions cell needed 154px. Scrolled to its end, the row’s Edit sat under the pinned column with 18.7px of it showing, below the 24px target floor (axe target-size). Any table whose last column is wider than the room beside its pinned column does the same at 320px.
  • Decision: the lead’s (Tharinda, 2026-10-21): keep the 320px reflow and pin the first column from bp/tablet up, across every table, rather than redesign the row actions below bp/tablet or narrow the rail.
  • Scope: every table that pinned its first column at every width. They now read usePinnedFirstColumn (forge-et-fe src/ui/pinnedFirstColumn.ts) and carry data-pin-first from bp/tablet up. The shadcn tables give their first-column cells PINNED_CELL and PINNED_CORNER; the CSS-module tables select on [data-pin-first]. The tables are the contacts, accounts, users and buying-standards tables, the account page’s Buying standards panel, the weekly prices round table, the auction sales table, the not-in-round dialog, the roles table, and the offboarding lists’ selection column (RowSelection). src/ui/pinnedFirstColumn.test.tsx fails any stylesheet that pins at the inline start outside [data-pin-first], and any class string that pins with a bare left-0. No token changed.

Rev 67 is claimed on an unmerged branch (docs/shadcn-backfill-leads). If another branch merges a Rev 69 first, this entry takes the next free number (an unmerged claim yields).

  • Added — §5, the External link row: ExternalLink in src/ui — the host as the text, the hidden (opens in a new tab), the externalLink icon concept, a page title as the accessible description, rel="noopener noreferrer", at least 24px tall, wrapping anywhere, and plain text for anything that is not an absolute http/https URL. Same-host links in one list share a name and are told apart by their context, which meets WCAG 2.4.4 in context.
  • Added — §5 AI provenance, the research panel: the four elements once at the top of the panel, then the company fields with one source link per finding; a nothing found body keeps the provenance when an AI call was made. The panel is not tinted.
  • Recorded — the departures from the capture-app POC’s Company snapshot, the nearest reference (the CRM prototype has no research panel): one link per finding rather than one Sources list, so a reader sees which page grounds which statement; the link wraps rather than truncating, so the part of a host that tells two sites apart stays visible; sentence-case labels rather than the POC’s uppercase eyebrow (§9); no summary paragraph and no talking points, which the spec does not have.
  • Why: F11-c spec FR-V1 and FR-V2 (each finding links to its source, through a new ExternalLink in src/ui), and FR-H2’s last item, which asks for this revision in the frontend wave’s harness PR (AC-31).
  • Decision: the developer’s, at the F11-c WI-1.4 plan review (Decisions 9, 17 and 25), 2026-10-21.
  • Scope: §5, one row and one paragraph. No token changed, and tone/ai stays read by src/ui’s AiProvenance.module.css alone. Implementing code, all in forge-et-fe:
    • src/ui/components/ExternalLink/ and the externalLink concept in src/ui/icons/registry.ts;
    • src/features/leadResearch/ (LeadResearchPanel.tsx, ResearchPersonBlock.tsx).
  • Added — §6, a List screen bullet: every CRM list screen is a table laid out as the Users list is, each row ending with a ⋯ menu of View, Edit and one action specific to the screen (the demo’s example was Archive on Pricing). The third action is not decided for any screen yet; each is decided in that screen’s plan (owed.md). The whole row opens the record in view mode, not only its name; the row’s controls (the ⋯ menu, a checkbox) act on their own, and the name stays a real link, which is the keyboard and screen-reader path and lets the record open in a new tab. View and Edit open the same record page: a row click and View open it in view mode, with its own Edit action; the menu’s Edit opens it with the edit form already open. Email (/email) is the one exception and keeps its message list.
  • Changed — §6, the Two-pane list + detail bullet: marked superseded for the CRM’s list screens. It stays described until the Leads list, its last use, becomes a table.
  • Changed — §6, the Detail page bullet: a record’s own page — the account page, a contact’s page, the lead page — is one centred column like the user editor, not the full width. The account page leaves the “not covered yet” list. Every record page opens in view mode with an Edit action, the user and role pages included, which today open straight into their editor.
  • Changed — §6, the App frame bullet: the sidebar’s order puts Leads first and Pricing before Email, and Users and Roles move to the Settings page: Leads, Accounts, Contacts, Pricing, Email, Settings. Because the sidebar’s order is the landing order (Rev 44), a user whose role reaches Leads lands on Leads after signing in; the demo accepted that.
  • Changed — §5, the Modal row: every create flow opens in a modal over its list, as the Users list’s create-user dialog does — a new account, contact, lead, buying standard, email template or any later record. Creating a user or a role is a modal already; an account’s /accounts/new and an email template’s /email/templates/new pages become modals, and §6 Detail page says so for the account. Editing an existing record is not changed by this rule.
  • Changed — §5 Form fields, the placeholder rule (reversed): every form field’s placeholder is Enter and the field’s name in lower case (Company name → Enter company name). No example values (e.g. BOP1, e.g. +94 77 123 4567) — before this revision placeholders showed format examples only. A format the person needs goes in the helper text. The label stays above the control, so the text/faint placeholder carries nothing a reader depends on. Rev 51’s filter exception (All clients) stands, because a filter is not a form field. The demo’s wording covers text fields; select, date and picker controls are to be decided (owed.md).
  • Changed — §8, Settings › Tags: Settings becomes a page of links. /settings lists the configuration items (the lead, account and contact tags, the email templates, Users and Roles, any later one) and each opens its own page, in place of today’s tabs. Each item keeps its own permission: the Settings entry shows to a role holding the key of any item on it, and each item is shown and guarded on its own key — Users and Roles on access.manage, the tags on settings.manage — so the seeded IT Admin role, which holds access.manage alone (AD #34), still reaches Users and Roles. Until now Settings showed only to settings.manage holders (Rev 44). Each item is a card on the page, the whole card its link, with a one-line description (decided by Nanndish, 2026-10-23): Account tags, Contact tags and Lead tags as three cards with a page each (/settings/tags/account, /contact, /lead), Email templates (/settings/email-templates, on email.manage), Users (/settings/users) and Roles (/settings/roles); each page has a ← Settings back link, and the inbox header’s Email templates button goes.
  • Changed — §8, Email templates: the templates move from the Email page to Settings. They serve the drafts other screens generate (leads, pricing); mail on the Email page is written by hand. Their route under Settings is set in the PR that moves them.
  • Not built: none of this is in the code yet, except that the Users list is already the table the rule describes. Each screen’s target and status are in shadcn-backfill.md § Target layouts. The order of work: the Leads list first, then the lead page, then the other screens one PR each.
  • Superseded work, kept for comparison: the two-pane Leads list on shadcn (forge-et-fe#303, a draft, recorded by forge-et-harness#783’s Rev 67) and the tabbed lead detail built after it (branch feature/shadcn-lead-detail in forge-et-fe, stacked on #303). Neither merges as it is; they are kept so the table can be compared with them. The lead page that View opens is designed afresh, not taken from the tabbed detail.
  • Approved specs this contradicts, each revised in the PR that builds the change (.claude/rules/specs.md; owed.md): F11-b (the two-pane leads list, and the first lead opened on arrival), F11-f (the lead detail’s column order), F20-d (templates reached from the inbox header), F1-e (Settings › Tags as tabs, and Settings shown to settings.manage holders only), F1-b and F1-d (the account’s New page at /accounts/new), F5-b (the sidebar’s entries, with Users and Roles in it), F5-c and F5-d (the users and roles lists in the sidebar, their records opening straight into the editor), and every list screen’s spec where a row opens its record only from the name (F1-b, F1-f, F26-b, F5-c, F5-d); a spec that fixes a placeholder’s text is revised in the PR that changes that placeholder. The client-approved prototype also shows leads as list plus detail (.claude/rules/source-trust.md); telling Empire is an owed.md row.
  • Why: the demo showed the screens working differently from one another. The account and contact pages open at the full width while the user editor is a centred column, and the lists use different layouts; one table pattern, one row menu and one detail-page width make every screen work the same way, with the Users screens as the model. The email templates move because they are used for drafts other screens generate, not for the mail composed by hand on the Email page. Creating a record works two ways today — the Users list’s create-user dialog, the account’s New page — so every create flow becomes a modal. Many form fields had no placeholder, and those that had one showed an example value; the UI/UX engineer set one wording for all of them. A table row opens its record only from the name today, which is a small target; the whole row becomes the target. Users and Roles move to the Settings page in the same way as the email templates, beside the other configuration.
  • Decision: Tharinda, Nanndish, Dinil, Biseni and the UI/UX engineer, at the internal demo on 2026-10-21; approved by the lead (Tharinda). More decisions from the same demo are still to be recorded (owed.md).
  • Scope: §5, the Modal row and the Form fields placeholder rule; §6, one new bullet and three changed; §8, two changed passages. No token changed, and no code changed by this revision.

Rev 71 — 2026-10-26 — §8: one permission, settings.manage, opens the whole Settings page

  • Changed — §8, Settings: Rev 70’s “each item keeps its own permission” is replaced. The Settings entry, the /settings page and every item on it — Account tags, Contact tags, Lead tags, Email templates, Users, Roles — are shown to, and their routes guarded on, settings.manage. A role holding it sees every card; a role without it has no Settings entry and sees the no-access state on any Settings address. email.manage no longer shows Settings or opens the email templates.
  • Changed — §8, Email templates: the templates pages need settings.manage. A holder of it without email.manage writes shared templates only: New template offers no Kind choice and the template is shared, because a personal template belongs to the caller’s own mailbox. A role holding email.manage alone uses templates in the compose dialog but does not create or edit any, personal ones included (decided by Nanndish, 2026-10-26).
  • Changed — §8, Users & roles admin: behind settings.manage instead of access.manage, which AD #34’s refinement of 2026-10-26 folds into it.
  • Kept for later: each card in forge-et-fe src/features/settings/settingsPages.ts still names its key, the page filters on it and each route is guarded on it, so an item can take a permission of its own if Empire asks for a role that sees only some Settings pages (owed.md).
  • Why: unticking a role’s Emails permission hid the Email templates card while the role still held Manage settings. The Settings permission should decide the whole Settings page, and nothing else should.
  • Decision: Nanndish, 2026-10-26. It depends on AD #34’s refinement, signed off by Tharinda on 2026-10-27.
  • Scope: §5’s Section settings affordance row (its Email templates button goes), §8, three passages, and §9’s model note (the special keys and the effective-permissions viewer’s key). No token changed. Implementing code: forge-et-fe src/app/navConfig.ts, src/app/router.tsx, src/features/settings/settingsPages.ts, src/features/email/templates/ (presetKindFor), and forge-et-be branch feature/settings-manage-absorbs-access.

Rev 72 — 2026-10-26 — §5 and §6: plain first columns in tables, the primary action last in a title bar, no clear button in search fields, and the contacts data bar (feedback after the internal demo)

Numbered after Rev 70 and Rev 71, which an earlier open PR (docs/crm-ui-restructure) holds unmerged (.claude/rules/id-numbering.md rule 5). If another branch merges a Rev 72 first, this entry takes the next free number.

  • Changed — §6, data tables: a table’s first column is set in the body’s regular weight, not bold, and its name link has no underline, at rest or on hover. The row shows it can be opened through Rev 70’s whole-row opening and the pointer. A sortable column header keeps its underline on hover, because for a column that is not sorted it is the only sign the column can be sorted. A row action shown as a link (the Accounts list’s Edit) is not underlined either; Rev 70 moves row actions into the ⋯ menu.
  • Changed — §6 List screen, the title bar: when a title bar has two actions, the primary one comes last, at the row’s right end, with the secondary (outline) one to its left. On the Leads list that is New lead from inquiry, then New lead, in the title bar and in No leads yet. This reverses the order the F12 WI-2.3 plan’s Decision 12 chose; the F12 spec (FR-U1, AC-16) says only that the two sit side by side, so it needs no revision.
  • Changed — §5, search fields: a search field shows no clear button. Chromium and WebKit draw an “x” on type="search" and Firefox draws none, so the CRM hides the browser’s own in every search field, for one look in every browser.
  • Changed — §6 List screen, the data bar: the contacts page’s filter row is the data bar the other list screens use: one row of 40px controls on one line, with no labels above them — the search box with its glyph, named by an aria-label that its placeholder repeats (“Search contacts”, replacing the “Name or email” hint), Account as a select named inside its trigger, Show archived as the data bar’s switch. The /email filter takes the same search box, named Search mail (its placeholder too), and loses its visible Filter mail label, as the Accounts and Leads search boxes have none.
  • Why: UI changes asked for after the internal demo: no “x” in search bars, New lead on the right with New lead from inquiry to its left, no underline and no bold first column in the tables, a contacts Show archived that was neither aligned with the fields nor the same size as the other pages’ switches, and an Email search bar with a placeholder and the other pages’ fill. The Email search box was first given the placeholder under its Filter mail label; the review of forge-et-fe#343 found that gave one control two names (§5 Form fields), and the developer chose the Accounts and Leads form.
  • Decision: Nanndish’s, 2026-10-26 (in session), from the demo feedback.
  • Scope: §5, one rule; §6, three rules. No token changed. Implementing code, all in forge-et-fe (forge-et-fe#343): src/ui/styles/shadcn.css and src/ui/components/Input/Input.module.css (the clear button); src/ui/filters/DataBarControls.tsx (FilterSearch, the data bar’s search box); the tables in src/features/{leads,accounts,users,roles,settings,pricing,email/templates}; src/features/leads/LeadsScreen.tsx; src/features/accounts/ContactsFilters.tsx; src/features/email/InboxToolbar.tsx.

Rev 73 — 2026-10-27 — §5 and §6: the Email inbox as a mail reading pane

  • Changed — §6, the Two-pane list + detail bullet: the Email inbox keeps the pattern, as a mail client’s reading pane, when Rev 70 replaced it with the List screen for the CRM’s list screens. From bp/laptop up, the message list sits at layout/list-pane-width and the open message beside it. Below bp/laptop, it is a single pane, unchanged: the list drills into the message, which has its ← Email.
  • Added — §6, the inbox’s two panes fill the canvas: from bp/laptop up, the panes take the height the title row and the search leave, and each scrolls inside its own card, with the pager under the list. The page does not scroll. Below a floor of 5 × space/8 the panes stop shrinking and the canvas scrolls instead; no supported window size reaches it.
  • Added — §6, the message view’s layout: the header, with Reply (primary), Reply all, Forward and Refresh at the end of the subject’s row, so the actions stay in reach however long the message is; the From, To and Cc fields one line each, the term in its own column; then the body under a 1px divider, with no card of its own. The same layout serves the reading pane and the single-pane page (F20-c spec Rev 5).
  • Added — §5, an empty state with no action: the reading pane with no message open shows the empty state’s icon and one line, “Select a message to read it here”, centred in the pane, with no action. The way forward is to choose a row in the list beside it, so the line shows only while the list has rows; while it loads, after it fails and with no mail the pane is a plain card, never zero-state copy beside an error. It is a second exception to §5’s “primary action”, after the account timeline’s (Rev 65, §6 Activity timeline).
  • Why: the Email screen’s move to shadcn/ui (forge-et-fe#348). The developer asked for an Outlook-style inbox: the list on the left and the open message on the right, both filling the page. With the actions under the body, a short email left them above an empty pane, a long one scrolled them out of sight, and the body’s own card inside the pane’s card read as a text field.
  • Decision: Dinil’s, 2026-10-27 (in session), each change checked in the running app.
  • Scope: §5, one exception; §6, one bullet changed and two rules added. No token changed. Implementing code, all in forge-et-fe (forge-et-fe#348): src/features/email/EmailRoute.tsx and .module.css, InboxList.tsx, MessageView.tsx and .module.css.

Rev 74 — 2026-10-28 — §5, §6 and §8: one way of working across the CRM’s screens — edit on the record’s own page, one table look, back navigation, dialog widths and footers, placeholders, the Settings page (UI revamp)

  • Changed — §6 Detail page and §5 Modal: a record is edited on its own page. A record with its own page — the account, contact, lead, user and role — is edited on that page in edit mode, at /…/:id/edit, from the page’s Edit and from the list’s ⋯ Edit alike. The page keeps its breadcrumb, back arrow and h1 (the record’s saved name, never Edit ); the §6 Save bar sits at the top, with the unsaved-change count, Discard changes with Undo, and Save ; the record’s fields replace its details in a card, in the view’s order. Save waits for a change, except on the role editor (F5-d AC-20). Saving returns to view mode; leaving with unsaved changes asks first. Creating stays a Modal over the list. A record with no page of its own — a tag, a buying standard, a price, a sale’s dates, a follow-up — is edited in a Modal. Opening a contact’s Edit from the account page’s contact list goes to the contact’s page and returns to the account after saving; an archived contact has no Edit there, as in the contacts table. The email template keeps its own editor page. This replaces Rev 70’s “the menu’s Edit opens it with the edit form already open” where that form was a dialog over the page (the contact and the lead); the account’s edit page loses its Edit title and its bottom Cancel / Save changes row; the shared SaveBar gains saveDescribedBy, which points Save at the page’s status line while a save runs.
  • Changed — §5 Table and §6 Data table: one look for every table. Every CRM table takes the Users table’s look from one set of classes (forge-et-fe src/ui/dataTable.ts): the header row’s bottom rule now draws (under separate borders a row’s own border was never painted), the table runs to its card’s side edges, one row height, the ⋯ menu in a narrow last cell. The tag tables move to it — the status as a dot and a word, Edit and Retire or Restore in the ⋯ menu — and so do Roles, Email templates, the Pricing tables and dialogs, and the offboarding tables, the last six moving from a raw <table> to shadcn’s Table.
  • Changed — §6 Data table, sorting: every table sorts, by the shared SortableHeaderCell; where the server cannot sort a column and the page holds the whole list, the page sorts it; a paged list never re-sorts a page. An inactive sortable column shows a faint up-and-down mark on hover and focus. The Leads list keeps its Sort menu and writes the order to its URL as <field>,<dir> (the old values are still read).
  • Changed — §6 Data table, pagination: ListPager on every list — the Accounts list, an account’s standards and a user’s owned records join the Users list’s.
  • Changed — §6 Back navigation: every page with a back link has a breadcrumb above its title and a small ghost back arrow, with no fill, beside the h1, named Back to , whose arrow lines up with the breadcrumb; at the 320px reflow the arrow stays on the title’s first line (PageHeading). Both alignments come from layout (a box one title line tall; the glyph centred in its hover square and the breadcrumb inset to line up with it), not margin offsets (§5).
  • Changed — §6 Detail page: the account page, the message view and the offboarding sub-view are centred in the two-list-pane column like the user editor. Every record page’s h1 is the same size, the default h1 (26px/700); the account and lead pages had a smaller title.
  • Changed — §5 Modal: two widths — form (58ch) for a one-column form or a confirmation, wide (two list-pane widths, 720px, the New account dialog’s) for a two-column form, the compose window or a table; a two-column form in it has at most two columns. Before, a Modal took the width of its content, which left Set cost about 245px wide. The footer reads Cancel, then the main action at the right, on a band with a top rule on surface/card-warm; the older dialogs gain Cancel, and New follow-up gains the band.
  • Changed — §5 Form fields, placeholders: a typed field says Enter ; a select, a date and a record picker say Select . This closes Rev 70’s open point on select, date and picker controls. The remaining example placeholders were replaced.
  • Changed — §5 Badge, tag looks (F1-e): a tag with no colour is a plain outline, so None no longer looks like Neutral; Positive and Notice fill with their tone’s border token, so they read apart.
  • Changed — §6 List screen: the title bar’s primary action is shadcn’s default button (Compose, New account, New role); the Contacts page’s search and filters sit above the table’s card, as on Users; New lead from inquiry carries the AI sparkle icon (§5 AI provenance).
  • Changed — the contacts’ values: a contact’s email address and phone number are plain text in the contacts table, on the contact’s page and in the account page’s contact list — never a mailto: or tel: link.
  • Changed — the Email page: Compose shows only while the mailbox is connected and usable; with no mailbox, one that needs reconnecting, while it is read or after a failed read, the page offers the connect step instead. On the Email templates page the search box comes before the Shared / Mine tabs.
  • Changed — §8 Settings: the cards sit in named sections — Users & administration, Tags, Email — three equal cards a row, each card’s icon beside its title.
  • Changed — §6 Current-user menu: the sidebar’s account menu opens upward from its trigger, with its animation running the same way.
  • Changed — the colour layer (Rev 41): every CRM route except sign-in is on the revamped colour layer, so colours and buttons no longer change between screens.
  • Approved specs this contradicts, each revised in this PR: F1-b (the account edit page, and AC-13b’s unavailable Save, which is now busy), F1-d (the account page’s contact Edit as a Modal, and Edit on archived contacts), F1-e (the tag colours, and the tag table’s buttons and focus targets), F1-f (the contact’s email and phone links, and its edit as a Modal), F11-b and F11-f (the lead’s edit as a Modal over the page), and F20-c (AC-31’s Compose in every state of the Email page).
  • Why: after the internal demo the screens still worked differently from one another: some records were edited in a dialog and others on a page, the tables did not match the Users table, the back link sat above the title on some pages and beside it on others, dialogs had different widths and button orders, and the tag colours None and Neutral (and Positive and Notice) could not be told apart. Editing on the record’s page was chosen over editing in dialogs because the largest forms — an account, a role’s permissions, an email template — do not fit a dialog, an edit page has an address (Back, reload and a shared link work), and the user and role pages already worked that way.
  • Decision: Nanndish’s, 2026-10-27 and 2026-10-28, in session; editing on the record’s page (the option of three he was shown) chosen on 2026-10-28. Made under AD #39’s direction that the CRM’s screens follow the Users screens.
  • Scope: §5, the Badge, Table and Modal rows and the Form fields placeholder rule; §6, the List screen, Back navigation, Detail page and Save bar bullets and the Data table sorting and pagination rows; §8, the Settings passage and the Contacts entry. No token changed. Implementing code, all in forge-et-fe branch feature/ui-revamp: src/ui/dataTable.ts, src/ui/PageHeading.tsx, src/ui/shadcn/breadcrumb.tsx, src/ui/components/BackLink/, src/ui/components/Modal/, src/ui/components/SaveBar/, src/ui/components/ListPager/, src/ui/components/SortableHeaderCell/, src/ui/TagBadge.tsx, src/ui/fields/placeholders.ts, src/lib/tags/tagLook.ts, src/lib/params/clientSort.ts, src/app/router.tsx; the edit pages in src/features/accounts/ (AccountFormPage.tsx, ContactEditForm.tsx, ContactFormFields.tsx, ContactPage.tsx) and src/features/leads/ (LeadEditPage.tsx, LeadFormDialog.tsx); the tables across src/features/{accounts,leads,settings,roles,users,pricing,email/templates}; src/features/settings/SettingsRoute.tsx; src/features/email/InboxToolbar.tsx.

Rev 75 — 2026-10-28 — §5: Button / danger-outline for destructive triggers

  • Added — §5, the Button / danger-outline row: a quieter outlined danger family for the trigger of a destructive action — Deactivate, Delete role, Disconnect, Withdraw — and the menu item’s destructive variant for a destructive row-menu item (Archive, Remove, Withdraw). The confirm the trigger opens keeps solid danger. Measured: tone/danger text and border on the card at 5.94:1, and the hover wash at 4.69:1 or more, in every theme.
  • Why: BUG-157 — a destructive trigger looked like every other secondary button, so the action was marked as destructive only once its dialog was open.
  • Decision: Nanndish’s, 2026-10-08, changing F5-d WI-2.2 plan Decision 6 (solid red only on the confirm, so the destructive action is not the loudest control beside Save) while keeping its reasoning; built at the lead’s direction, 2026-10-28.
  • Scope: §5, one row added. No token changed. Implementing code, all in forge-et-fe: src/ui/shadcn/button.tsx (destructive-outline), src/ui/components/Button/ (danger-outline), and the triggers in UserActivationCard.tsx, OffboardDeactivateSection.tsx, DeleteRoleAction.tsx, ConnectedPanel.tsx, RoundSummaryBar.tsx, AccountsTable.tsx, StandardsTable.tsx and RoundTable.tsx; contrast pinned by src/app/destructiveTriggerContrast.test.ts. Other destructive triggers (contact Archive, sharing Remove, note Delete, the template Delete) are not yet moved; they are listed in .forge/owed.md.

Rev 76 — 2026-10-29 — §6: one screen header, with a description on every list screen

  • Added — §6, the Screen header bullet: every list screen’s header is PageHeader (title, actions, an optional breadcrumb and a description), and every record’s page keeps Rev 74’s PageHeading; every screen’s h1 is drawn by PageTitle, at the size Rev 74 gives every record page’s title (twice type/body, 26px, bold); the title and actions are centred on one line; a one-line description under the title is required on list screens.
  • Changed — the table header (BUG-168): Rev 74’s shared data-table classes already give the tables BUG-168 named (the Pricing standards book, weekly prices, auction sales, the account’s Buying standards panel and the Settings tag tables) the Users table’s header row; BUG-168’s fix adds a test that holds each of them to it. Rev 74’s one exception stays: the standards book and weekly prices tables wrap their labels and sit them on the bottom line, so their ten and fourteen columns fit at 1024px.
  • Why: BUG-163 — nothing styled h1, so each screen’s title took whatever size its own module or the browser gave it; BUG-164 — the Leads title and New lead sat on a baseline, which Nanndish decided on 2026-10-08 to centre; BUG-165 — only Pricing had a description, and Nanndish decided on 2026-10-08 that every list screen has one; BUG-168 — table headings differed from page to page.
  • Decision: Nanndish’s, 2026-10-08 (centring; a description on every list screen); built at the lead’s direction, 2026-10-28. The title size is Rev 74’s, chosen by the lead on 2026-10-29 over type/title when this change and Rev 74 met. The description wording per screen is in forge-et-fe#356, approved by the lead as written on 2026-10-29.
  • Scope: §6, one bullet added. No token changed. Implementing code, all in forge-et-fe (forge-et-fe#356): src/ui/components/PageHeader/, every screen’s header, src/app/pageTitleOnly.test.ts, src/app/tableHeaderStyle.test.ts and e2e/browser/shell/screen-header.spec.ts.

Rev 77 — 2026-10-30 — §5 and §6: full-width record pages, edit dialogs over the page, the tag, notes, compact-row and sharing patterns (UI revamp preview)

  • Changed — §6 Detail page, and new §6 Record page: a record’s own page (the account, contact, lead, user, role and email template) takes the full canvas width, built from src/ui/recordPage: the header (breadcrumb, back arrow, PageTitle, marks, actions) with a summary strip of key facts, then two columns or tabs. From bp/laptop, a page whose column holds a long list (the account’s Notes and timeline tab, a contact’s notes, the lead’s notes) fills the window and the list scrolls inside its card, a labelled region reachable from the keyboard. This reverses Rev 70’s and Rev 74’s centred column for record pages.
  • Changed — §5 Modal and §6 Detail page: editing. Edit on the account, contact, user and role pages opens a dialog over the page (RecordEditDialog; the account’s EditAccountDialog), with Cancel and Save in the footer band, asking first on ✕ or Esc with unsaved edits, ignoring a click outside, and returning focus to its opener. This reverses Rev 74’s “never a dialog over the page” for those four records; the lead and the email template keep their edit pages, and the §6 Save bar stays on the lead’s. The edit addresses (/…/:id/edit) are kept: the contact’s shows the contact’s page with the dialog open, the user’s and the role’s redirect to the page with the dialog open, and the account’s redirects to the account page. The confirmations these pages added or moved (leaving with unsaved edits, removing a note, a share or a contact’s draft) are shadcn’s AlertDialog (ConfirmDialog); Delete role keeps its §5 Modal confirm for now.
  • Changed — §5 Badge / pill, the tag (F1-e): a tag is a 24px rounded rectangle, not a pill: a dot and a tint behind dark text, its remove ✕ inside its right end on a 24 × 24 target; the colour names stay None, Neutral, Positive, Notice, Danger. A record’s tags end with a dashed + Add tag chip that becomes the tag search in place (AddTagControl); a table row shows two tags, cut at 15 characters, then +N opening the rest in a popover (TagLine).
  • Added — §6 Record page, the notes pattern (F1-e, F11-f): a quiet Add a note line that opens to a box with a hidden label, growing from four to ten lines with no resize handle, Cancel and Add note, and a confirm before discarding; notes author first, clamped at four lines with Show more, each with a ⋯ menu of Edit and Delete and its delete confirm inside the note.
  • Added — §6 Record page, compact rows: the account’s Contacts card, the contact’s Contact details and the lead’s Customer card show one row per item, a glyph then the value, with row actions as small icon buttons named by tooltip (IconAction) or a ⋯ menu; a copyable value has a Copy icon button (a tick and Copied, announced); a missing email or phone reads No email address / No phone number; a person is a PersonAvatar.
  • Added — §6 Record page, Shared with (F5-g): a summary of faces and one sentence in the card, with Manage access or View access opening one Access to dialog (chips and Share with , the owner’s row, each share with its ✕ and an inline confirm, the reach line). It replaces the share dialog and the separate remove-share dialog.
  • Changed — §6 Activity timeline (F1-c): entries grouped by day for two weeks and by month before that, the kind’s icon on a tinted circle as the marker, filter chips by kind, and in-card scrolling from bp/laptop. The marker table changes: each kind has an icon colour and a circle fill from the revamped ramps (primary-*, success-*, warning-*, neutral-*) in place of one colour from the semantic tokens, and activity is named Follow-up, not Activity.
  • Added — §6 Settings sections: the Mailbox page as rows of a question and its card (F20-a).
  • Added — §5 Combobox, SearchSelect: a one-value picker inside an edit dialog (the user’s Manager), whose Esc closes only its list.
  • Kept, from main, on these pages: every h1 is PageTitle (Rev 76, BUG-163); the Delete role and Disconnect mailbox triggers are danger-outline (Rev 75, BUG-157).
  • Approved specs this contradicts, each given a revision with the preview: F1-b Rev 11 (the account edit dialog), F1-c Rev 3 (the timeline), F1-d Rev 10 (the account page and its Contacts card), F1-e Rev 9 (the tag and the notes), F1-f Rev 6 (the contact page and its edit dialog), F5-c Rev 12 and F5-d Rev 8 (the user and role pages and their edit dialogs), F5-e Rev 2 (the access table and reporting line on the user’s page), F5-g Rev 1 (Shared with), F11-b Rev 5 (the leads table’s tag line), F11-f Rev 5 (the lead’s Customer card and notes), F20-a Rev 10 (the Mailbox page), F20-b Rev 4 (the inbox search width), F20-d Rev 3 (the template’s view), F26-b Rev 7 (the account’s standards table), F26-c Rev 4 (the import as numbered steps), F26-f Rev 1 (the Weekly prices tab) and F26-g Rev 3 (the Auction sales tab and the Pricing page warnings).
  • Why: the UI revamp preview, built to see the screens working before each is reviewed against its spec: one option was chosen per screen from design artifacts shown to Nanndish (Compact rows, Grouped by day, Quiet composer, Summary in the card, Centred dialogs, Record page, Settings sections, Tidied tabs). The record pages use the canvas width because their two columns and tabs need it; the edit dialogs keep the reader on the record they were looking at.
  • Decision: Nanndish’s, 2026-10-28 to 2026-10-30, in session (UI revamp preview, forge-et-fe#364). Rev 74’s choice of edit pages was also his; the dialogs replace it for the four records named above. Rev 70’s centred record page was the lead’s (Tharinda, 2026-10-21), so this revision’s reversal of it waits for his agreement.
  • Approved by: Nanndish (UI revamp preview, forge-et-fe#364); Tharinda agreed to the reversal of Rev 70 and Rev 74 on 2026-11-02.
  • Scope: §5, the Badge / pill, Modal and Combobox rows; §6, the Detail page and Activity timeline bullets (the timeline’s marker table among them), and two bullets added (Record page, Settings sections). No token was added or changed: the timeline markers now read existing ramp tokens. Implementing code, all in forge-et-fe (forge-et-fe#364): src/ui/recordPage/, src/ui/overlays/RecordEditDialog.tsx and ConfirmDialog.tsx, src/ui/TagBadge.tsx, src/ui/tags/, src/ui/notes/, src/ui/IconAction.tsx, src/ui/PersonAvatar.tsx, src/ui/shadcn/avatar.tsx, src/ui/fields/SearchSelect.tsx, src/features/sharing/, src/features/timeline/, src/features/email/MailboxSection.tsx, and the account, contact, lead, user, role and template pages.

Rev 78 — 2026-11-02 — §6: the selected sidebar entry

  • Changed — §6, the App frame bullet: the selected sidebar entry has a surface/card fill with a border/frame hairline ring and shadow/card, a semibold label in text/primary, and a border-width/selected (3px) bar in accent/gold-deep on its leading edge, inset from the top and bottom, in place of Rev 30’s 1px accent/gold-deep edge on the surface/hover wash. Its glyph stays accent/gold-deep. A hovered entry keeps the plain surface/hover wash, and the selected entry keeps its white fill under the pointer.
  • Why: the selected entry and a hovered one used the same wash, told apart only by the 1px edge, which was easy to miss.
  • Decision: Nanndish’s, 2026-11-02, in session, after checking it in the browser. It takes only the selected-entry part of a sidebar proposal shown to him; the proposal’s other changes (Rev 70’s order, groups, counts, a price line, the toggle’s place and a 56px rail) are not part of this revision.
  • Changed — §5, the Interaction states row Selected: names the sidebar’s selected entry as its own shape, pointing at §6.
  • Known limitation: in Windows forced-colours mode the fill, the ring and the bar are dropped, leaving the semibold label and aria-current; the existing owed.md row on forced colours covers it with the other selected rows.
  • Scope: §5, the Selected row; §6, the App frame bullet. No token was added or changed. Implementing code, in forge-et-fe (forge-et-fe#373): src/app/Sidebar.module.css, a comment in src/ui/styles/theme-revamp.css, and src/app/sidebarContrast.test.ts, which measures the active glyph and bar against the white fill (3 : 1), the bar against its ring and the rail beside it (3 : 1) and the count badge on the selected entry (4.5 : 1).

Rev 79 — 2026-11-02 — §8: the role editor’s All records box is hidden while None is chosen

  • Changed — §8 Permission-aware rendering, model note: the role editor’s All records box is hidden while an area is set to None and shown once View or Manage is chosen, where the note said it was shown and enabled only then. A key that requires another (Publish weekly prices) is unchanged: it stays shown, blocked, with its reason under it, until one of those is chosen, so the two no longer behave “the same way”.
  • Why: the role editor of the UI revamp preview (forge-et-fe#364) hides the box, and the lead kept that form (F5-d Rev 9, AC-19).
  • Decision: Tharinda’s (lead), 2026-11-02, in session.
  • Scope: §8, the model note’s role-editor sentence. No token or component changed; the code is already on main (src/features/roles/RoleAccessEditor.tsx).

Rev 80 — 2026-11-02 — §5 and §6: the mailbox connect — the Mailbox menu item, the connect-failed banner and its two-button rule, the mailbox screen on shadcn (F20-i)

  • Added — §6 Current-user menu: a Mailbox item, before Sign out, for a user whose role holds email.manage (a permission key, never a role name — AD #26), opening /email/mailbox; absent for everyone else. It is the way to the mailbox settings when there is no connection, where the Email screen shows no settings affordance (FR-19). The menu is shadcn’s DropdownMenu (Radix: not modal; a disabled item stays aria-disabled and reachable, so Sign out while a sign-out runs keeps its reason in its name), opening upward (side="top", Rev 74), with shadcn’s Avatar on the accent/gold pair and layout/control-h-compact, and at least as wide as its trigger (min-inline-size: var(--radix-dropdown-menu-trigger-width), BUG-008). As in every Radix menu, Tab does not leave an open menu: Esc closes it and returns focus to the trigger.
  • Added — §6, the connect-failed banner: when a mailbox connect fails — the automatic connect on load, or Try again / Reconnect anywhere — every CRM page shows Your mailbox could not be connected, with the reason in plain words when Microsoft gave one, in a full-width banner at the top of the page canvas, above the page’s own header and outside the route’s loading boundary. It is the warning tone (warning-muted fill, warning-muted-foreground text, warning edge — a recoverable problem, not a destructive one), with Dismiss (ghost, close icon). It is announced once, by one visually hidden polite status line that is always mounted; the visible banner is not a live region (role="none"). It stays until Dismiss, a successful connect or the next page load (a Try again that fails keeps it, and its status line announces the new failure; a Try again that goes to Microsoft keeps it, busy, until the page unloads), so it follows the user to another page in the same visit; a reload, or a return to the page from the browser’s back/forward cache, does not show it again. When Dismiss or a successful Try again removes it while focus was on it, focus moves to the page’s heading.
  • Added — §6, the two-button rule: the banner carries its own Try again on every page except where the page shows its own FR-16 button — /email/mailbox and the Email screen — where the page’s button is that page’s Try again and the banner shows the message alone. The rule follows what the page renders, so the message view below bp/laptop, which has no FR-16 button, gets the banner’s Try again. The banner’s button is named “Try again: connect your mailbox” for assistive technology (its visible text first), because a page’s own read-failure Try again can sit on the same page.
  • Added — §5/§6, the FR-16 button: the mailbox screen and the Email screen show one button from the server’s nextStep — Try again (TRY_AGAIN, and a CONNECT_NOW the CRM does not act on by itself — the automatic connect starts only from a page load’s first check or when the Email screen opens, once per load), Reconnect (RECONNECT, after the user disconnected), a “Connecting your mailbox” line with no button while the automatic connect runs, and nothing for NONE; shadcn’s default (primary) Button. On the Email screen it replaces the list (with no Compose, Rev 74) when the connection is not ACTIVE, and sits above the list in a card (“Reconnect your mailbox to finish setting it up”, Compose kept) when an ACTIVE connection still has a next step; on the mailbox screen an ACTIVE connection with a next step keeps the connected panel, with the sentence and the button above its status row.
  • Changed — the copy (the developer’s wording at implementation): the reasons — INTERACTION_REQUIRED and LOGIN_REQUIRED “Microsoft needs you to sign in again”, CONSENT_REQUIRED “Microsoft needs your permission to connect your mailbox”, ACCOUNT_SELECTION_REQUIRED “Microsoft needs you to choose an account”, ACCESS_DENIED “Permission to connect your mailbox was declined” — each shown as a second sentence after the message, both with full stops (§9); an unknown reason shows the message alone. The prompt’s sentences: no connection “Your mailbox is not connected”; after a disconnect “You disconnected your mailbox. It stays disconnected until you reconnect it.”; a connection that needs reconnecting keeps its reason sentence (statusReasonCopy). F20-a’s Connect Microsoft 365 mailbox button and Try connecting again banner are gone.
  • Changed — §5 Section settings affordance: unchanged on /email (present for a connection, absent without one); with no connection the user reaches /email/mailbox from the current-user menu’s Mailbox (FR-19).
  • Changed — the mailbox screen: on shadcn (AD #39), in Rev 77’s Settings sections layout (the Connection, Receiving mail and Disconnect rows) — Card, Button (primary for the FR-16 button, at the top of the Connection row when an ACTIVE connection still has a next step; destructive-outline for Disconnect mailbox, BUG-157; destructive for the confirming Disconnect), SkeletonLines for loading; the Disconnect confirmation is the shadcn AlertDialog at the form width with the footer band (Cancel, then Disconnect at the right, on surface/card-warm with a border/card top rule — Rev 74 §5 Modal). It leaves shadcn-backfill.md.
  • Why: F20-i connects the mailbox by itself after sign-in (FR-17), so a failed connect can surface on any page, not only on the mailbox screen; one message in one place, with one Try again per page, is what the user sees whichever start failed.
  • Decision: Tharinda’s, 2026-10-29 (the banner form and the two-button rule — F20-i-WI-1.3 plan D-10, D-22); the reason and prompt copy is the developer’s call at implementation.
  • Scope: §5, the FR-16 button; §6, the Current-user menu bullet, the Settings sections pattern’s Mailbox page and the connect-failed banner with its two-button rule; the Section settings affordance row’s note. No token changed. Implementing code, all in forge-et-fe (forge-et-fe#382): src/features/email/connect/ (MailboxConnectProvider.tsx, MailboxConnectBanner.tsx, NextStepAction.tsx, connectMarkers.ts, connectReturnPath.ts, startMailboxConnect.ts, mailboxConnectContext.ts), src/features/email/MailboxRoute.tsx, ConnectedPanel.tsx and .module.css, ReconnectRequiredPanel.tsx, NotConnectedPrompt.tsx, EmailRoute.tsx, SyncIndicator.tsx, mailboxApi.ts, useMailboxConnection.ts; src/app/CurrentUserMenu.tsx and .module.css, src/app/AppLayout.tsx, src/app/router.tsx (src/ui/shadcn/avatar.tsx reached main first, in forge-et-fe 6c5daf77).

Rev 81 — 2026-11-02 — §5: no error summary at the top of a submitted form

  • Changed — §5 Form fields and validation, the On submit bullet: a submit that finds errors no longer shows a summary at the top of the form (2 fields need attention with a link per error). Each error shows beneath its field, as before, and focus moves to the first invalid field. A refusal from the server that names no field the form shows is stated in a message above the form; that message was already separate from the summary in every form except the email template editor, which now puts those lines in its problem message. The user and role editors and the New user and New role dialogs keep their own box (“The role was not saved” and the like), but only for reasons no field can show; it no longer lists field errors as links, and it appears only when there is such a reason.
  • Why: every error is already shown beneath its field, so the summary repeated each message a second time at the top of the form.
  • Decision: Nanndish’s, 2026-11-02, in session.
  • Accessibility: the change keeps form error handling within WCAG 2.1 AA: SC 3.3.1 (Error Identification) is met by the message beneath each field, tied to its control by aria-describedby with aria-invalid="true", and SC 3.3.3 (Error Suggestion) by those messages naming the fix; focus moving to the first invalid field announces that field’s error without a separate alert. Given up: the count of errors announced on submit and the links that jump from the top of a long form to each field.
  • Scope: §5, the On submit bullet. No token changed. Removed component: FormErrorSummary in forge-et-fe src/ui/components/ and its uses in the CRM’s forms; the account form, which moved focus to the summary, now moves it to the first invalid field. Changed: the field links in the user and role editors’ summaries (src/features/users, src/features/roles). The specs that named the summary carry revision entries: F11-b, F20-c, F20-d, F26-b, F3-a and F5-d.

Rev 82 — 2026-11-02 — §5 and §6: the email template is edited in a dialog over its page

  • Changed — §5 Modal and §6 Detail page: Edit on an email template’s page opens Edit template over the page in RecordEditDialog, as on the account, contact, user and role pages since Rev 77, in place of the template’s edit page: the title row with its ✕, the body that scrolls, the footer band with Delete template at its start and Cancel and Save template at its end. The dialog is RecordEditDialog’s wide size (2.5 × layout/list-pane-width, 900px, as the role editor’s), for the rich-text body; it is wider than the §5 Modal’s wide (two layout/list-pane-widths). /settings/email-templates/:id/edit opens the page with the dialog open. A save closes it with the toast Template saved. The New template dialog moves onto the same frame, its action reading Create template. Only the lead page keeps an edit page.
  • Why: with the four other records edited in a dialog over their page, the template’s separate editor page was the odd one out, and the dialog keeps the reader on the template they were looking at.
  • Decision: Nanndish’s, 2026-11-02, in session: option A (the same dialog as Edit user) of three dialog designs shown to him.
  • Scope: §5, the Modal row; §6, the Detail page bullet; the layout/dialog-max row’s list of dialogs it caps. No token was added or changed. Implementing code, in forge-et-fe (branch feature/F20-d-edit-template-dialog): src/features/email/templates/, an optional onEscape on src/ui/overlays/RecordEditDialog.tsx, and src/ui/shadcn/alert-dialog.tsx, whose question now locks the scrolling of an edit dialog’s body under it as it locks <main> (at 320 × 640 the body scrolls, and inert under the question it failed axe’s scrollable-region-focusable); this covers every RecordEditDialog. F20-d Rev 5 carries the same change.

Rev 83 — 2026-11-02 — §5 and §6: busy buttons, a table’s re-read, no hover underline on controls, one search width

  • Changed — §5 Interaction states, the Busy / loading row: a busy button shows shadcn’s Spinner (src/ui/shadcn/spinner.tsx, the registry’s spinner, lucide’s LoaderCircle) in the flow before the label, with the button’s gap, in place of a leading icon. A button with a leading icon keeps its width; any other button grows by the spinner and its gap while it waits. This replaces the spinner laid over the button’s start padding, which kept the width but drew the ring almost against the button’s edge. It applies to the shadcn Button and to the older src/ui Button, so the sign-in button and the AI buttons change too.
  • Changed — §6 Data table, the Empty and loading row: a table re-reading after a sort, a filter, a search or a page change draws skeleton rows in place of its rows, as many as it showed, under its header, as its first load does; the visible Updating… line above the table, which pushed the rows down and back on every request, is gone, and a polite status announces the update. A re-read of the same request (after a write in a row, a retry) keeps the rows, with no visible line either: the row holds the control that started the write, and replacing the rows would drop its focus. F1-f Rev 8, F11-b Rev 7 and F26-f Rev 2 carry the change into those lists’ states. A list shown as cards rather than a table (Activities, an account’s Contacts section) is unchanged.
  • Changed — §6 Data table, the Sortable header row, and the Settings page’s cards: neither underlines on hover. A sortable header is a control, marked by its chevron hint; a Settings card keeps its hover fill. Inline text links (breadcrumbs, a contact’s name, Show more) keep their hover underline.
  • Changed — the account page’s Standards search: the same width as every other list’s search (calc(var(--et-space-8) * 9), shrinking with the row and never growing to fill it), where it alone filled its row.
  • Why: UI fixes Nanndish asked for on 2026-11-02, and from two options each shown to him: skeleton rows for a table’s re-read (Option B), and shadcn’s spinner leading the label for a busy button (Option A).
  • Decision: Nanndish’s, 2026-11-02, in session.
  • Scope: §5, the Busy / loading row; §6, the Empty and loading and Sortable header rows and the Settings page’s card sentence; coding-standards §3.2, the Refreshing row. No token was added or changed. F1-e Rev 10 carries the table re-read rule into the tag pages. F5-d Rev 11 rewords AC-21, whose busy Save kept its width; F11-f Rev 6 renames the lead’s Archive / nurture button Archive, a label change no design-system row names. Implementing code, in forge-et-fe (branch feature/F20-d-edit-template-dialog, with F20-d Rev 5): src/ui/shadcn/spinner.tsx, src/ui/shadcn/button.tsx, src/ui/components/Button/, src/ui/icons/registry.ts, src/ui/components/SortableHeaderCell/SortableHeaderCell.tsx, src/features/settings/SettingsRoute.module.css, src/features/accounts/AccountStandardsPanel.module.css, and each list screen’s table.

Rev 84 — 2026-11-03 — §5 and §6: the Email header’s settings button with the actions, the inbox search at the list’s width, rounded list rows, the message filling the reading pane

  • Changed — §5 Section settings affordance: the button is the first of the screen’s actions, at the title row’s right end before Refresh and Compose, where Rev 25 placed it beside the title. Its look (a ghost icon button), its accessible name and its rule for when it shows are unchanged. §6 Screen header says the same. PageHeader loses its titleAside slot, which nothing else used.
  • Changed — §6 Two-pane list + detail: the Email inbox’s search box is as wide as the columns left of the reading pane, so its edges line up with them. On main today that is the message list, layout/list-pane-width (360px). F20-i’s folder column (forge-et-fe#386, a draft) adds a column of half that width before the list; with it, the search spans the folder column, the gap and the list (owed.md). Every other list screen keeps Rev 83’s search width of nine space/8 steps (288px).
  • Changed — §5 Selected, the Email list’s open message: it now matches the sidebar’s selected entry. The row has a radius/md fill, and a border-width/selected accent/gold-deep bar with a rounded outer end replaces the square 1px left border. Hovered rows get the same rounded fill. The list is inset space/2 from its card, and each row sits space/1 clear of the separators, so no rounded fill touches a straight edge. A row’s height is unchanged. The row’s inline padding is space/4 (it was space/3), so the text clears the bar. In forced-colours mode selection is still not shown, as before; aria-current marks the open row.
  • Changed — §6 Detail page, the message view in the reading pane: from bp/laptop up, the open message fills the reading pane’s width, inset only by the pane card’s space/6 padding, as Outlook’s reading pane does. Before this it kept Rev 74’s centred column, capped at twice layout/list-pane-width (720px), which left blank bands either side on a wide window (about 250px each side at 1920px). As a page of its own, below bp/laptop, the message view keeps the centred column.
  • Why: UI fixes Nanndish asked for on 2026-11-03. The gear beside the title stood apart from the header’s other buttons. The 288px search box ended short of the 360px list under it. The open message’s square edge did not match the rounded selected entry in the sidebar. The message in the reading pane sat centred with blank space on both sides, unlike Outlook’s reading pane.
  • Decision: Nanndish’s, 2026-11-03, in session.
  • Scope: §5, the Section settings affordance and Selected rows; §6, the Screen header, Two-pane list + detail and Detail page bullets. No token was added or changed. F20-b Rev 5 rewords FR-10b and AC-25b (“beside the Email title”) and records the search width against FR-10’s Rev 4. Implementing code, in forge-et-fe (forge-et-fe#388, branch feature/email-header-polish): src/features/email/InboxToolbar.tsx, InboxToolbar.module.css and InboxToolbar.test.tsx, src/features/email/InboxList.module.css, src/features/email/MessageView.tsx and .module.css, src/features/email/EmailRoute.test.tsx, src/ui/components/PageHeader/PageHeader.tsx and .module.css, and two test names in e2e/browser/mailbox/inbox.spec.ts and connect-screen.spec.ts.

Rev 85 — 2026-11-03 — §5 and §6: the settings button with its words, one look for filter pills, paged Settings tag tables

  • Changed — §5 Section settings affordance: an outline Button with the settings icon and the words naming the destination (Mailbox settings), in Refresh’s style, where it was a ghost icon button. The words are its accessible name, with no aria-label over them (L-211), so the name F20-b AC-25b gives it is unchanged; its place (Rev 84) and its rule for when it shows are unchanged too (BUG-332).
  • Changed — §6 Filter pills row: every filter pill is a shadcn Button, size sm, rounded-full, in the primary fill when it is the filter in force and the outline otherwise — the Leads status pills’ look. A pill that changes the URL is the same Button drawn on a link, with aria-current. The Weekly prices status filters, hand-styled links whose selected fill was the near-black text colour, now follow it (BUG-333).
  • Changed — the Settings tag pages’ tables (§6 Data table, Pagination and Empty and loading): each pages under the shared ListPager, 25 a page by default with 50 and 100 offered, the page and its size in the URL; the paging is in the browser, since both tag lists are read whole and sorted there (F1-e D-9), and a new order returns to page 1 (BUG-336). Their first load is the table’s header over skeleton rows, as every list’s is; below bp/tablet, where the tags are blocks, it stays skeleton lines (BUG-335). F1-e Rev 11 carries both into FR-T2.
  • Unchanged, and now applied to Users: Rev 83’s re-read rule — skeleton rows under the header while another page, sort or filter is read. The Users list was built before Rev 83 and kept its old rows; it now draws skeleton rows as Contacts does (BUG-334). The Roles list sorts in the browser over a list it has already read, so a sort reads nothing and shows no skeleton.
  • Why: UI fixes Nanndish asked for on 2026-11-03: the gear was the only unlabelled action in the Email header; the Weekly prices filters did not look like the Leads ones; the Settings tables did not load or page like the lists outside Settings.
  • Decision: Nanndish’s, 2026-11-03, in session — the icon with the words Mailbox settings.
  • Scope: §5, the Section settings affordance row; §6, the Filter pills row bullet. No token was added or changed. F1-e Rev 11 rewords FR-T2. F20-b AC-25b (a button found by its accessible name) and F26-f FR-16 (the filters’ content and aria-current) are unchanged. Implementing code, in forge-et-fe (branch fix/BUG-332-ui-consistency): src/features/email/InboxToolbar.tsx; src/features/pricing/RoundSummaryBar.tsx and .module.css; src/features/users/UsersScreen.tsx and UsersTable.tsx; src/features/settings/SettingsTagsRoute.tsx, TagSettingsTable.tsx and .module.css, and the new tagSettingsPage.ts; with their tests.

Rev 86 — 2026-11-03 — the live inbox: folder column, folder picker, unread mark, category chips (F20-i)

  • Changed — §6 Two-pane list + detail: from bp/laptop, the Email screen (/email) has three panes:

    • a folder column at half layout/list-pane-width (calc(var(--et-layout-list-pane-width) / 2), no new layout/* token);
    • the list at layout/list-pane-width;
    • the reading pane, taking the rest.

    There is space/5 between the panes. Each is a shadcn Card that scrolls inside itself, and the page does not scroll. Rev 84’s search box spans the folder column, the gap and the list. Below bp/laptop (768px and the 320px reflow) the screen stays one pane, and a folder picker (shadcn Select, label Folder) sits beside the search box in the data bar: on one row at 768px (the search flexible, the picker an equal share, at most layout/form-width), stacked full width at 320px.

  • Added — the folder column:

    • It is a nav named Folders of router links in nested lists, always expanded, in the API’s order: Inbox, Sent Items, Archive, then the user’s folders.
    • A subfolder indents space/4 per level. A long name truncates, with its full text as title.
    • The unread count follows the name in type/secondary at the semibold weight (type/card-title’s weight) and is read as “ unread”. There is no count at 0.
    • The current folder has aria-current="page" and a accent/gold-deep leading border on surface/card-warm. Whether it takes Rev 84’s rounded selected look is open (.forge/owed.md).
    • The column has its own states: loading (a skeleton); an error with nothing loaded (Retry, with the list beside it showing the Inbox); and stale after a failed refresh (the tree kept, its load time, Retry). Below bp/laptop the two failure panels show above the list, and the picker is a one-line skeleton while the tree loads.
    • The picker lists every folder in tree order, with the count after the name. A subfolder’s item is indented and named “, in ” for assistive technology.
  • Added — §5 and §6, the list row:

    • The unread mark: a dot (accent/gold-deep, space/3 across, hidden from assistive technology) before the counterpart, a visually hidden "Unread, " at the start of the row link’s name, and the subject at weight 600 (type/card-title’s) over the read subject’s type/body. Unread is told by text and weight, not colour alone.
    • Category chips: the message’s Outlook category names after the preview, as shadcn Badge outline chips in one neutral style, with a visually hidden “Categories:” before them. They carry no Outlook colours, because MailboxSettings.Read is not consented. They are text only and wrap, and a long name truncates with its title. The message view uses the same component (CategoryNames, Rev 87).
  • Added — §6 pagination, the live inbox:

    • The pager has no total: “Messages 51–100”, then Previous and Next (outline, sm). It is hidden when there is one page and nothing before it.
    • On the last page of a capped search only, one line of type/secondary in text/secondary above the pager reads “Showing the first 1,000 results — narrow the search to see more”.
  • Copy as built (the developer’s call, F20-i WI-2.4 plan § UI / Design Adherence › Copy):

    State Copy Action
    List loading “Loading your mail” —
    List refreshing “Refreshing your mail” —
    Empty folder “No mail in ” — the folder’s name from the tree, else “Inbox”, “Sent Items” or “Archive”, else “this folder” Check for new mail
    No matches No mail in <folder name> matches "<text>" Clear search
    List error, nothing loaded “We couldn’t reach Microsoft to load your mail. Nothing was lost.” Retry
    Stale list “We couldn’t reach Microsoft to refresh your mail. Showing mail as of Retry
    Folder column loading “Loading your folders” —
    Folder error “We couldn’t load your folders from Microsoft. Nothing was lost.” Retry
    Stale folders “We couldn’t refresh your folders. Showing folders as of Retry
    Folder not found “This folder is not in your mailbox” Go to Inbox
    Range “Messages –” —

    The polite status line says the range, the loading and refreshing lines, the empty sentences and the not-found sentence. It says nothing for the error states, whose panels are alerts.

  • Why: F20-i FR-2, FR-6, FR-7, FR-9, FR-12, FR-13; AC-32a, AC-34, AC-48c, AC-52a, AC-55. The prototype has no folder column, picker, unread mark, category names or pager; the spec is authoritative.

  • Decision: built as F20-i WI-2.4 plan § UI / Design Adherence. The reading pane at 1024px, measured on 2026-11-03, gives about 298px of message (382px at 1280px). That is readable for ordinary mail, while a wide HTML message scrolls inside its frame. It is reported to the lead and not changed (F20-i WI-2.6 test-verify record, § By hand).

  • Scope: forge-et-fe src/features/email/EmailRoute.tsx, EmailRoute.module.css, FolderColumn.tsx, FolderColumn.module.css, FolderPicker.tsx, InboxToolbar.tsx, InboxToolbar.module.css, MessageRow.tsx, CategoryNames.tsx, InboxList.tsx, InboxList.module.css, InboxPager.tsx. No token was added or changed.

Rev 87 — 2026-11-03 — the live message view: categories, Mark as unread, Bcc, the attachment list (F20-i)

  • Changed — §6 Two-pane list + detail, the message view (/email/messages/:id, Rev 73’s layout kept): the message is read live by its Graph id.
    • The title row: after Reply (primary), Reply all and Forward, the second group is Mark as unread then Refresh (Refresh message in the reading pane), both shadcn Button outline. The groups wrap under the subject when the row is narrow.
    • The read toggle: after the user marks the message unread, the same button reads Mark as read. A press shows the refreshing state with the content kept, both buttons busy. The status line then says “Message marked as unread” or “Message marked as read”.
    • A failed Mark as unread shows an ErrorPanel under the header (coding-standards §3.2, L-191):
      • when the refusal is known: “We couldn’t mark this message as unread. Nothing was changed.”, with Try again and the TraceLine;
      • when the outcome is unknown (no answer, or a 5xx with no problem body): “We couldn’t confirm whether this message was marked as unread. Refresh the message to check.”, with Refresh message.
    • The meta row gains the message’s Outlook categories after the date, through the inbox row’s CategoryNames (shadcn Badge outline, one neutral style, text only — Rev 86).
    • The header fields gain Bcc on a message the user sent, when it has one.
    • The attachment list replaces the “Has attachments” note, under the header fields. It has one AttachmentRow per file the body does not show inline, in the read’s order. Each row has Download: a shadcn Button outline, sm, named Download . The press fetches the file through the CRM’s API client and saves it under its name from the message read, so the CRM page never navigates. While it runs the button is busy. A refusal shows an inline error under that row, with Try again and the TraceLine, mapped by the problem’s code as FR-13’s states are; focus stays on Download or moves to Try again. (The lead’s decision, 2026-11-04, replacing a link to the download URL, which replaced the CRM tab with the problem’s JSON when the download failed.) A message whose only attachments are inline shows no list.
    • A gone connection: when the live read says the connection is gone, the view shows the inbox’s NotConnectedPrompt with F20-i FR-16’s button. The connect-failed banner then leaves out its own Try again on that page, under Rev 80’s two-button rule, which follows what the page renders.
  • Added — §5 Attachment row, the received-file variant: it shows the type icon, the name shortened from the middle (read whole), the size as the meta line, and a download action. It has no uploader, no date and no Remove, since a received file has none of them. An untrusted name renders as text, path separators and control characters included.
  • Why: F20-i FR-4, FR-7, FR-9, FR-13, FR-15, FR-16; AC-32b, AC-52b. The prototype’s message detail has no categories, read toggle, Bcc or attachment list; the spec is authoritative. Mark as read as the toggle’s second label is the lead’s decision at the plan review (F20-i WI-2.5 plan D-7, 2026-11-03).
  • Decision: built as F20-i WI-2.5 plan § UI / Design Adherence. Two changes are recorded in its ### Failed Approaches: the FR-16 button in the view (D-4), and the unknown-outcome copy.
  • Scope: forge-et-fe src/features/email/MessageView.tsx, MessageView.module.css, MessageAttachments.tsx, useMessageReadState.ts, and CategoryNames.tsx (reused, unchanged). No token was added or changed.

Rev 88 — 2026-11-03 — §6: the current-user menu loses its Mailbox item (F20-i)

  • Removed — §6 Current-user menu: the Mailbox item Rev 80 added before Sign out. The menu holds Sign out only. The mailbox settings (/email/mailbox) are reached from the Email screen’s settings button (§5 Section settings affordance), which is unchanged, including its rule for when it shows.
  • Changed — Rev 80’s reason no longer applies: Rev 80 added the item as the way to the mailbox settings with no connection, where the Email screen shows no settings button. With no connection the Email screen already shows the same Try again or Reconnect button as the mailbox screen, in place of the list (Rev 80’s FR-16 button), and the connect-failed banner carries Try again on every other page, so the item led to a page that offered nothing the user could not do where they were. That is the same reason the Email screen hides its settings button in that state (BUG-015, BUG-020). Disconnect stays reachable: it applies only to a connection, and with a connection the Email screen shows the settings button.
  • Why: two ways to the same page, one in the sign-out menu, where nobody looks for email settings. Raised by Nanndish and the developer on 2026-11-03.
  • Decision: Tharinda’s (lead), 2026-11-03, in session.
  • Scope: §6, the Current-user menu bullet. No token or component changed. F20-i Rev 4 changes FR-19 and AC-40 to match. Implementing code, in forge-et-fe (branch fix/F20-i-remove-menu-mailbox): src/app/CurrentUserMenu.tsx and CurrentUserMenu.test.tsx, and the browser specs that opened the menu on Mailbox (e2e/browser/shell/current-user-menu.spec.ts, shell/a11y.spec.ts, auth/signin-session-signout.spec.ts, size-matrix/arrange.ts).

Rev 89 — 2026-11-03 — §6: the Mailbox page’s column is 2.5 × layout/list-pane-width (BUG-304)

  • Changed — §6 Settings sections and Detail page: the Mailbox page’s centred column is capped at 2.5 × layout/list-pane-width (900px), not the twice (720px) that Rev 77 kept for it under the Detail page rule. The other one-column pages keep twice.
  • Why: each Settings sections row holds its question and one sentence beside its card from bp/tablet; at twice the width both columns are too narrow at desktop widths. The code has used 2.5 since the UI revamp preview built the layout (forge-et-fe 8cea3c56), and BUG-304 found the design system still saying twice.
  • Decision: Tharinda’s (lead), 2026-11-03, in session: keep 900px rather than narrow the page.
  • Scope: §6, the Settings sections and Detail page bullets. No token changed. Code, in forge-et-fe (forge-et-fe#397): src/features/email/MailboxRoute.module.css (comment only; the style was already 2.5), e2e/browser/shell/centredColumn.ts (the cap factor) and e2e/browser/mailbox/inbox.spec.ts (the column test checks 2.5, unmarked).

Rev 90 — 2026-11-03 — §3, §5 and §9: one look and three sizes for every modal; every success is a toast; Title Case for titles, buttons, headers and field labels

  • Changed — §5 Modal, the look: every modal is one centred card, padded space/7 on every side with space/6 between the title, the body and the buttons, and no rule or fill between them. Rev 74’s footer band (a top rule on surface/card-warm, running to the dialog’s edges) and RecordEditDialog’s title row with a rule under it are dropped. What Rev 74’s band was for is kept: only the body scrolls, so the title and the buttons stay in view on a long form. Cancel first and the main action last, at the right, is unchanged.
  • Changed — §5 Modal, the sizes: three sizes, sm 420px, md 560px and lg 800px, replace Rev 74’s form (58ch) and wide (720px) and RecordEditDialog’s 900px wide, and no modal sets a width of its own. The role and template editors, which were 900px, take lg. Each size keeps Rev 74’s space/8 at each side as the viewport narrows.
  • Added — §5 Modal, the title and the main action: the title is type/subhead with a one-sentence description under it in type/body and text/secondary, and the main action is named for what it does (Change Owner, Archive Contact), never OK or Submit. A destructive confirmation is the sm size, its action in the destructive fill, opened by a destructive-outline button (Rev 75’s button rule, restated here).
  • Changed — §5 Modal, the behaviour stated once: closing (Esc, ✕, Cancel, refused while saving; with unsaved edits ✕ and Esc ask first and a click outside does nothing, which Rev 77 stated for the edit dialogs only), where focus starts and returns, errors placed as §5 Form fields and validation places them, and a success closing the modal with a toast. They were each screen’s own until now, and are written to agree with the approved specs that state them (F1-f FR-C, AC-20, AC-28).
  • Added — §3 Layout: layout/dialog-sm, layout/dialog-md and layout/dialog-lg, for the PR that moves the modals over to add to tokens.css. layout/form-width and layout/dialog-max are no longer modal widths.
  • Changed — §5 Toast: every success is a toast, worded with the action’s own name. An inline message stays only for a failure with its Retry and reference, and for a notice the user must act on or dismiss. The inline success messages on the contacts page (F1-f WI-1.3 Decision 31, made before Sonner was in the repo), the notes sections, the activities list, the leads list and the account page move to Sonner.
  • Changed — §9 Capitalization: Title Case now covers every title (a screen’s, a card’s or section’s, a modal’s, a tab’s), every button and menu item, a table’s column headers and an icon-only button’s accessible name, where it covered only the navigation, screen names and proper nouns; field labels, on forms and in read-only views, are Title Case too, so a column header and its field’s label match. Placeholders, helper text, tooltips, messages (a field’s error included) and the values the CRM shows keep sentence case. The words a title leaves in lower case, and the particles that take a capital after a verb, are listed, so a test can check a label. A new screen is built in Title Case and an existing one is recased whole by its own PR; a spec whose requirement states the casing rule gets a revision in that PR. §5 Table says the header row is in Title Case, §3’s type/micro row no longer puts column headers and badges in UPPERCASE (they had not been since Rev 41), and the §5 Modal row’s examples are recased. The capture app keeps the rule before this revision.
  • Why: the UI/UX designer found the modals inconsistent. About forty modals are built from four parts (the shadcn Dialog and AlertDialog, RecordEditDialog, ConfirmDialog), most setting their own width and padding in their own CSS, so similar forms open at different sizes and with different frames. Some screens confirm an action with a toast and others with an inline message (“Note added” on a record’s notes), so the same kind of outcome looks different from screen to screen. Three modal patterns were drawn on the CRM’s tokens and compared: a centred card (chosen), a framed panel with header and footer bands, and a side sheet for forms. The designer also asked for Title Case: under §9’s old rule a screen’s name was Title Case and the titles inside it were not, so Settings › Account tags sat under Settings.
  • Decision: Nanndish’s, 2026-11-03, in session, on the UI/UX designer’s recommendation: the centred card, with the buttons kept in view on a long form. Title Case for titles, buttons and table headers: Nanndish’s, 2026-11-04, in session; for field labels too: Nanndish’s, 2026-11-05, in session.
  • Scope: §3, the layout/form-width and layout/dialog-max rows and three new layout/dialog-* rows; §3, the type/micro row; §5, the Modal, Table and Toast rows; §9, the Capitalization bullet. No colour or type token changes. coding-standards.md §7.1’s workflow-naming rule, which pointed at §9, keeps sentence case for CI names, and frontend-reviewer’s check 20 states the new rule. The code is not moved yet: the casing moves in its own forge-et-fe PRs (.forge/owed.md); the modals and the success messages move over in forge-et-fe PRs, one per screen or area, as the shadcn backfill does (.forge/owed.md). Until a modal is moved it keeps its current frame; a new or changed modal uses this row. Approved specs that state the old frame — F11-b (FR-C1, the New lead dialog at wide with a footer), F20-c (the compose window at wide, 720px), F20-d (the template editor at 2.5 × layout/list-pane-width and its footer band), F5-d (the role editor in RecordEditDialog’s wide) and F26-d (the price-email dialog at layout/dialog-max) — are not edited by this revision; the PR that moves each screen adds a revision to its spec.

Rev 91 — 2026-11-05 — §4, §5 Selected and §6 App frame: one gold-bar selected look across the CRM, on radius/xs corners (F20-i)

  • Changed — §5 Selected: the folder column’s current folder takes the look Rev 84 gave the Email list’s open message: a surface/card-warm fill and a border-width/selected accent/gold-deep bar on the leading edge, its outer end rounded, with the list row’s space/4 leading padding. The link hovers in the same rounded fill. It replaces Rev 86’s square 1px accent/gold-deep leading border, and settles the question Rev 86 left open.
  • Changed — §4 radius scale, §5 Selected, §6 App frame: every gold-bar selected row — the sidebar’s selected entry, the Email list’s open message and the folder column’s current folder — and its hover fill has radius/xs (6px) corners, not radius/md (12px). Its bar is inset from the top and bottom by the row’s block padding.
  • Why: with radius/md, the folder link (27.5px tall, two thirds of a list row) left the bar’s top and bottom ends outside the rounded fill. The lead compared four options rendered from the app’s CSS and chose the smaller corner, which keeps the folder column compact. The lead then required the same corner on every selected look in the product, so that the three never differ.
  • Decision: Tharinda’s (lead), 2026-11-05, in session.
  • Scope: §4’s radius/xs row, §5 the Selected row, §6 the App frame bullet. No token value or component changed. Code, in forge-et-fe (forge-et-fe#403): src/app/Sidebar.module.css .navLink, src/features/email/InboxList.module.css .row, src/features/email/FolderColumn.module.css .link. src/features/email/mailboxTokens.test.ts asserts the one corner on all three.

Rev 92 — 2026-11-05 — header and §8: a current CRM prototype in the built look, beside the frozen original

  • Changed — the header and §8 Screen inventory: a new current prototype, .forge/design/prototypes/crm-current/, draws the screens forge-et-fe has on dev — the flat sidebar in navConfig.ts order, no top bar, Inter only, the revamp colours, and Accounts, Contacts, Leads, Activities, Email, Pricing and the Settings pages laid out as the app lays them out. Dashboard, Pipeline, Samples and Quotes keep their content in the same look and are marked Phase 2 · not built yet. The original, prototypes/crm/, is frozen as the client approved it. The header names the current prototype as the source of truth beside this spec; the §8 line lists both sets of screens.
  • Why: client demos show the built app and then the prototype for what is not built yet, and the original had drifted from the app built against this design system, so the two looked like different products. A capture-app pair, pwa/ and pwa-current/, follows the same rule.
  • Decision: Tharinda’s (lead), 2026-11-05, in session: keep the originals as they are, keep one current copy per app, and update it in place with every UI change (design/prototypes/README.md, .claude/rules/plans.md § Required Sections).
  • Scope: the header and §8. No token, component or rule here changed: the current prototype follows this document rather than the other way round. Its role editor still draws the permission catalog that AD #34 and AD #37 replaced (design/prototypes/README.md).

Rev 93 — 2026-11-05 — §5 status indicators: hot / cold settled

  • Changed — §5 Status indicators: the Lead engagement — hot / cold row is no longer provisional. Hot is tone/positive with a solid dot, Cold is tone/neutral with a ring dot, each with its word, shown beside the priority on the lead list and the lead view; the vocabulary note under the table says the row is settled.
  • Why: the approved F11-g spec (decision 10, FR-V2, FR-V3). Migrated Pipedrive leads carry Pipedrive’s own Hot / Warm / Cold as labels prefixed Pipedrive:, shown as label badges; the system’s status is a status indicator in another place and shape, so the two are never mistaken for each other.
  • Approved by: Dinil Gamage, 2026-11-05, with the F11-g spec.

Rev 94 — 2026-11-05 — §9: a table’s row ⋯ column is pinned at the inline end wherever its first column is pinned (BUG-310)

  • Changed — § Viewport and breakpoints, the breakpoint table’s Tables row and the 320px reflow paragraph: from bp/tablet up, where a data table pins its first column (Rev 68), it also pins its row ⋯ column at the inline end. Below bp/tablet neither is pinned, as before.
  • Why: at 768 × 1024 the leads table is wider than its region, so reaching a row’s ⋯ menu scrolled the table to its end. There the Est. value sort button sat under the pinned Name header with 22.7px clear, below the 24px target floor (axe target-size; BUG-310). With the ⋯ column pinned, reaching it scrolls nothing.
  • Decision: Nanndish’s, 2026-11-04, from BUG-310’s options (pin the ⋯ column; a page-check exemption; end-of-scroll space for one table). On 2026-11-05 he kept it after a scroll sweep showed the same overlap at other scroll positions, including a tag’s +N button passing under the pinned ⋯ button, which is BUG-345.
  • Scope: the nine tables with a row ⋯ menu: Accounts, Contacts, Leads, Users, Roles, Email templates, Tag settings, the price round table and the Standards table. Their ⋯ cells take DATA_TABLE_MENU_CELL and the column header DATA_TABLE_HEAD_MENU (forge-et-fe src/ui/dataTable.ts, from PINNED_END_CELL and PINNED_END_CORNER in src/ui/pinnedFirstColumn.ts), with the card’s fill so the columns passing under stay hidden. The auction-sales table and the not-in-round dialog keep plain buttons in their last column and are unchanged. src/ui/pinnedFirstColumn.test.tsx fails a table that pins its first column and has a row ⋯ menu whose menu column is not pinned. No token changed. The current prototype (prototypes/crm-current/) draws no pinned columns, so it is unchanged.

Rev 95 — 2026-11-05 — §5 Selected and §6 Two-pane list + detail: the Email folder pane as Outlook’s, collapsible to a rail (F20-i)

  • Changed — §6 Two-pane list + detail: from bp/laptop, F20-i’s folder column is a folder pane. Open, at the same width (half layout/list-pane-width): a ghost icon button that collapses it and Compose (primary, with its icon) at the top; then two groups, each under a type/secondary semibold name in text/secondary — Mailbox (Inbox, Sent Items and Archive, each with its own icon) and Your folders (the user’s folders, each with the folder icon). A folder with subfolders has a chevron button before it that folds them away for the visit; the others keep its space, so names line up. A folder’s unread count is the sidebar’s count badge (§6 App frame), and its name is semibold while it has unread mail. Collapsed: a rail as wide as the collapsed sidebar (layout/sidebar-width-collapsed), with the open button, Compose as a primary icon button, a tile per Mailbox folder (icon, name in type/meta, its own folder’s count badge at the icon’s top right, as the open pane counts it) and, below a hairline, one Folders tile for the user’s folders, carrying their total unread count, which opens the pane. The collapse button, and each of the rail’s icon-only buttons and tiles, shows its full name in a tooltip on hover and on focus, never a hover-only title (§5 Tooltip). The choice is kept per browser; a first visit opens the pane. While collapsed, the search box spans the rail, the gap and the list, and the tree’s failure panels show above the list. Below bp/laptop nothing changes.
  • Changed — §5 Selected: the folder pane’s current folder keeps Rev 91’s look, now on the folder’s row (fold button and link), inset by its space/2 block padding; the rail’s current tile has the same look, inset by its space/3. The rail draws no tile for a subfolder, so a Mailbox tile has the look while one of its subfolders is open, and the Folders tile while the current folder is one of the user’s; aria-current="page" stays on an exact match only.
  • Changed — Compose on the Email page: from bp/laptop it is at the top of the folder pane, as Outlook’s New mail is, not in the screen header (F20-c Rev 9). Below bp/laptop it stays the header’s last action.
  • Why: the folder column was a card of plain text links, which did not read as a mail client’s folder pane. Three Outlook-style designs were compared (a new-Outlook pane, a classic dense tree, and a pane that collapses to a rail); Nanndish chose the collapsible pane, with Compose in the pane and the state kept per browser. The design’s own selected look (a fill with no bar) gave way to Rev 91’s one look per pattern.
  • Decision: Nanndish’s, 2026-11-05, in session.
  • Scope: §5 the Selected row and §6 the Two-pane list + detail bullet. No token was added or changed: the rail reuses layout/sidebar-width-collapsed, the badge the sidebar’s count badge. F20-i Rev 5 and F20-c Rev 9 record it against FR-13 and FR-E4. Code, in forge-et-fe branch feature/email-folder-rail: src/features/email/FolderColumn.tsx and .module.css, EmailRoute.tsx and .module.css, InboxToolbar.tsx and .module.css, folderPanePreference.ts on the shared src/lib/browser/storedFlag.ts (which the sidebar’s preference also uses now), seven concepts in src/ui/icons/registry.ts (compose, folderInbox, folderSent, folderArchive, folder, paneCollapse, paneExpand), their tests, the AC-54a keyboard walk in e2e/browser/mailbox/inbox-a11y.spec.ts, and three page states (email-folders-collapsed, -loading, -error, from bp/laptop). mailboxTokens.test.ts binds the row’s and the tile’s selected look and the rail’s track. The current prototype’s Email screen (prototypes/crm-current/) draws the pane in the same change.

Rev 96 — 2026-11-05 — §5 and §6: the lead is edited in a dialog over its page

  • Changed — §5 Modal, §6 Detail page and §6 Save bar: Edit on a lead’s page, and Edit in the Leads list’s row ⋯ menu, open Edit Lead over the lead’s page in RecordEditDialog, as on the account, contact, user, role and email-template pages, in place of the lead’s edit page and its save bar: the title row with its ✕, the lead’s fields in a body that scrolls, and Cancel and Save Lead in the button row. The size is lg (Rev 90), as New Lead. /leads/:id/edit still opens the lead’s page with the dialog open, so a link or bookmark to it keeps working. A save closes the dialog with the toast that names the lead and the count of changes; Save Lead with nothing changed closes it with no request; Cancel, the ✕ and Esc close it, asking Leave without saving? first when there are unsaved edits, and are refused while a save runs. Discard changes and its Undo go with the save bar. The lead’s page stays mounted under the dialog, so a note being typed on it is kept, and moving between the lead’s view and edit addresses does not ask about it; leaving the lead while the dialog is open asks Leave without adding the note?, as leaving the page does. With this, every record that has a page of its own is edited in a dialog over that page.
  • Why: with the account, contact, user, role and email template edited in a dialog over their page, the lead’s separate edit page was the one record that worked differently.
  • Decision: Nanndish’s, 2026-11-05, in session.
  • Scope: §5, the Modal row; §6, the Detail page and Save bar bullets. No token was added or changed. Implementing code, in forge-et-fe (branch feature/lead-edit-dialog): src/features/leads/ — EditLeadDialog.tsx in place of LeadEditPage.tsx, LeadFormDialog.tsx (the edit form in RecordEditDialogFrame, without the save bar), LeadPage.tsx (the view always rendered, the dialog over it) and LeadNotesSection.tsx (its leave guard lets the move between the lead’s view and edit addresses through). On main today RecordEditDialog’s default width stands in for lg; forge-et-fe#419, which builds Rev 90’s sizes, makes size required, so whichever of the two merges second passes size="lg" to the lead’s frame. F11-b Rev 8 and F11-f Rev 7 carry the same change.

Rev 97 — 2026-11-05 — the live inbox: All mail, the category filter, the Focused and Other tabs (F20-i)

  • Added — §6 Two-pane list + detail, the folder pane and picker: All mail is the first row of the folder pane’s Mailbox group (Rev 95), above Inbox, with its own icon (the registry’s folderAllMail) and no unread count; it is the first Mailbox tile of the collapsed rail. It links to /email?folder=allmail, takes the row’s and the tile’s selected look and aria-current="page" there, and shows only with the tree (loaded or stale). Below bp/laptop the picker’s first item is All mail.

  • Added — §6 List screen data bar, the Email screen: after the search box, a category filter (the shared FilterSelect, “Category: All”, at most layout/form-width) offering the categories on the messages loaded in the current folder this visit, sorted, the chosen one kept while selected. While a search is active it is aria-disabled and described by a line on its own row directly under the search box, in type/secondary text/secondary: “The category filter and the Focused and Other tabs don’t apply to a search” on the Inbox, “The category filter doesn’t apply to a search” elsewhere. At 768px the filter wraps under the search box and the picker; at 320px every control stacks.

  • Added — §5 Tabs / segmented control, the Inbox: Focused (the default) and Other, shadcn pill tabs named “Focused or other mail”, in the data bar after the category filter, so the list card and the reading pane start level (§6 Two-pane list + detail). They show on the Inbox only, never on another folder, All mail or a search. Manual activation: the arrow keys move, Enter or Space chooses; the list is the one tab panel.

  • Added — §6, All mail’s line: “All mail is still being prepared in Outlook — some messages may not show yet”, type/secondary text/secondary, text only, above the panes (where the screen’s notices sit, so the list card and the reading pane still start level) while Outlook fills the search folder; not an alert, no action.

  • Copy as built:

    Where Copy
    Folder pane, rail and picker “All mail”
    Category filter name “Category”, first option “All” (the trigger reads “Category: All”)
    Tabs “Focused”, “Other”; the tab list’s accessible name “Focused or other mail”
    All mail’s line “All mail is still being prepared in Outlook — some messages may not show yet” (also appended to the polite status line)
    Filters-off line, on the Inbox “The category filter and the Focused and Other tabs don’t apply to a search”
    Filters-off line, elsewhere “The category filter doesn’t apply to a search”
    Empty, a category chosen No mail in <folder name> has the category "<name>", with Clear category (focus moves to the filter)
    Empty, Focused tab “No Focused mail in Inbox”, with Check for new mail
    Empty, All mail “No mail in All mail”, with Check for new mail
    No matches in All mail No mail in All mail matches "<text>", with Clear search
  • Casing: the new controls follow the Email screen’s current sentence case (Clear category beside the existing Clear search and Check for new mail), because Rev 90 recases an existing screen whole in its own PR (.forge/owed.md, “Recase the CRM to design-system Rev 90’s Title Case”); that PR takes in Clear category and decides All mail, which F20-i FR-5 fixes as the copy.

  • Layout as built: at bp/laptop the category filter sits beside the search box from a nine-space/8 basis, at most layout/form-width; with the picker (below bp/laptop) its basis is layout/form-width, so at 768px it takes a second row and at 320px it stacks full width. The tabs follow the category filter in the data bar at their own width, wrapping to the next row when the row is full. All mail’s line sits above the panes, beside the folder tree’s notices. Nothing sits above the list card in the list pane. No @media rule.

  • Why: F20-i FR-5, FR-6, FR-7, FR-8, FR-12; AC-33b, AC-36, AC-49b, AC-57b, AC-62, AC-63. The frozen prototype draws none of these; the spec is authoritative.

  • Decision: built as F20-i WI-3.2 plan § UI / Design Adherence, with the tabs during a search as F20-i-Wave-3-contract.md Rev 1 pins them. The tab row and the line moved out of the list pane at the wave’s browser check, because above the list card they broke §6’s level start (WI-3.2 ## Progress, the Step 5e repair). All mail’s place in the pane and the rail is F20-i spec Rev 5’s rule for whichever of the folder rail and wave 3 merged second; its icon concept was the orchestrator’s call at that merge (Tharinda’s session, 2026-11-05).

  • Scope: forge-et-fe src/features/email/FolderColumn.tsx, FolderPicker.tsx, CategoryFilter.tsx, InboxTabs.tsx, InboxToolbar.tsx, InboxToolbar.module.css, EmailRoute.tsx, EmailRoute.module.css, src/ui/filters/DataBarControls.tsx (FilterSelect gains optional disabled, triggerRef and fullWidth) and src/ui/icons/registry.ts (folderAllMail). No token was added or changed. The current prototype (prototypes/crm-current/) does not yet draw All mail, the category filter, the tabs or the two lines; that is an .forge/owed.md row (“Draw the live inbox in the current CRM prototype”).

Rev 98 — 2026-11-05 — §6: inbox threads and the New mail notice (F20-i)

  • Changed — §6 Two-pane list + detail, the inbox row (Rev 86’s row kept): loaded messages that share a conversation are one thread row, at the place of the first of them, built from the newest loaded message (counterpart, subject, time, preview, its category chips). After the counterpart (and any “+N”) a shadcn Badge secondary shows the number of loaded messages, the number only with a visually hidden " messages". The row is unread — the dot, "Unread, " and the strong subject — when any loaded message is, and carries the attachment mark when any has attachments. It links to /email/threads/{newest message's Graph id}, and is selected (Rev 84’s look) while any of its messages is open. A conversation with one loaded message is an ordinary row.
  • Added — §6, the thread view (/email/threads/:id): the message view (Rev 73, Rev 87) of the message shown open — the conversation’s newest once the conversation read answers — with one section between the header and the header fields:
    • while the conversation read runs, three skeleton lines named “Loading the earlier messages”;
    • on its failure, an ErrorPanel “We couldn’t load the earlier messages in this thread. Nothing was lost.” with Retry (outline, the retry icon) and the TraceLine, the open message kept;
    • when the backend left out the oldest, one line of type/secondary in text/secondary: “Only the latest messages of this thread are shown.”;
    • an ordered list named Earlier messages, oldest first, every message but the open one, separated by 1px border/row dividers. Each is a disclosure: a full-width shadcn Button ghost, left-aligned, inset space/3 by space/4, with the counterpart (the unread dot, a visually hidden "Unread, " and the strong weight when unread) and the time at the line’s end, then the preview on one line with an ellipsis. Expanded, its panel (indented space/4) shows that message’s fields, attachment list and body, the open message’s own layout; its read shows “Loading the message”, or “We couldn’t load this message. Nothing was changed.” with Retry, or “This message was deleted or moved”. Expanding an unread message marks it read.
    • one visually hidden polite status line, mounted in every state of the section, reads “ earlier messages” (“1 earlier message”) once the conversation read has answered and is empty otherwise, so a screen reader hears the section settle (the lead, 2026-11-05, at the forge-et-fe#424 review);
    • On NOT_FOUND, or a conversation of the open message alone, the section is not drawn. Below bp/laptop the thread view is a page of its own with ← Email and the breadcrumb, as the message view is.
  • Added — §6, the New mail notice: at the top of the list pane, above the list, the list’s width: a shadcn Alert (default variant, role="none") with the email icon, “New mail”, and Show (outline, sm) at the line’s end, wrapping under the line at the 320px reflow. One visually hidden polite line, always mounted with the list, holds “New mail” while the notice shows (Rev 80’s banner pattern). Show reloads the first page of the current view and moves focus to the Email heading.
  • Why: F20-i FR-9, FR-10, FR-11, FR-13; AC-8b, AC-35, AC-37, AC-52c, AC-61. The prototype’s Inbox shows every message of a thread in full; the spec collapses the older ones with the newest open (FR-10) and is authoritative. The prototype has no new-mail notice.
  • Decision: built as F20-i WI-4.2 plan § UI / Design Adherence. The copy “ messages”, Earlier messages, “Loading the earlier messages”, the two error sentences and “This message was deleted or moved” are the developer’s call at implementation (WI-4.2 plan § UI / Design Adherence › Copy), as proposed there.
  • Scope: forge-et-fe src/features/email/MessageRow.tsx, InboxList.tsx, InboxList.module.css, inboxThreads.ts, ThreadView.tsx, ThreadRoute.tsx, ThreadOlderMessages.tsx, ThreadOlderMessages.module.css, MessageView.tsx (MessageContent extracted), NewMailNotice.tsx, EmailRoute.tsx. No token was added or changed.

Rev 99 — 2026-11-05 — §5 and §6: the multi-choice data-bar filter, the Priority panel, and where the priority shows (F11-g)

Written as Rev 99: F20-i merged Rev 95, 97 and 98 to main while this entry was open, and Rev 96 is claimed by an open branch (python3 .claude/lib/next-id.py ds-rev, 2026-11-06).

  • Added — §6 List screen, the data bar: a filter that takes several values is a multi-choice select. Its trigger is the single-value select’s (Priority: All, Priority: P1, Not ranked), and it opens a popover of labelled checkboxes, one per value, in a group named by the filter; none checked is All, and each toggle applies at once with the popover left open. Tab moves through the boxes, Space toggles one, and Escape closes the popover and returns focus to the trigger. It is a popover of checkboxes, not a menu of checkbox items, because a filter is a form choice: a menu item is reached by arrow keys only and the menu closes on each choice. shadcn’s multi-select pattern (Command in a Popover) needs cmdk, a package the CRM does not have (the Inline pick list row made the same choice).
  • Added — §5 AI provenance, a Priority panel paragraph beside Rev 69’s Research panel: the heading row with the priority, the hot / cold indicator and Buyer last wrote ; the four elements once (AI RANKED, Confidence <n>%, from: inquiry and research, <date> or from: inquiry only, <date>, never edited, the source not linked); then Why this priority and Recommended next action, and the inquiry-only note. The card is not tinted.
  • Changed — §5 Status indicators: the Priority row’s Where is the Leads table’s Priority column and the Priority panel’s heading, not the “lead triage queue” the original prototype drew; the Priority and Lead engagement — hot / cold rows name their implementation, and the hot / cold row says where its date goes.
  • Why: F11-g spec FR-V1 (the panel), FR-V3 (the row indicators) and FR-V4 (the Priority filter, “more than one allowed”). No data-bar control on main takes more than one value, and One look per pattern makes a new pattern a revision here.
  • Decision: built now by the developer’s decision of 2026-11-05 (F11-g WI-1.2 plan Decisions 9 and 19). Tharinda confirmed the multi-choice data-bar pattern on 2026-11-05 (reported by Dinil), before the F11-g wave 1 frontend PR merged.
  • Scope: §5 (Status indicators, two rows; AI provenance, one paragraph) and §6 (List screen, one rule). No token changed. Implementing code, in forge-et-fe (F11-g WI-1.2): src/ui/filters/FilterMultiSelect.tsx, src/ui/components/LeadRankIndicators/LeadRankIndicators.tsx, src/features/leadRanking/LeadRankingPanel.tsx, and their callers src/features/leads/LeadRankingFilters.tsx and LeadsTable.tsx.

Rev 100 — 2026-11-06 — §5, §6 and §8: a leading icon on every button; the tag tables’ colour column; deactivation reassigns in a modal; the lead page’s cards reordered

  • Added — §5, a Button — leading icon row: every button with a text label carries a leading icon from the concept registry, dialog buttons and the save bar included; the icon is aria-hidden, one concept keeps one glyph across the CRM, and the busy spinner takes its place. Links inside sentences, menu items, tabs, selects and icon-only buttons are not covered. Until now only some screens (the Email page) drew icons on their buttons.
  • Changed — §8, the Settings tag pages’ table: the Name column shows the tag’s name as plain text, and the Colour column draws the tag badge in the tag’s tone, holding the colour’s word. Until now the Name column drew the badge and the Colour column showed the word alone (the UI revamp’s tag design, Rev 74).
  • Changed — §8, users and deactivation (F5-c, F5-h): one Deactivate User action replaces the pair Deactivate user and Offboard user. A user who owns no records and has no direct reports gets the sm confirmation, as today. A user who still owns records or has direct reports gets an lg modal, Deactivate , holding what the offboarding screen held — the owned records, reassigned in bulk, and the direct reports, given a new manager — with Deactivate User as its main action, available once nothing is left to move. AD #35 is unchanged: deactivation is still refused while the user owns a record or has a direct report, and the modal is how the administrator clears that. The /settings/users/:id/offboard screen and its link go. A deactivated user who still owns records (the state BUG-093’s race can leave) is offered Reassign Records on their page, which opens the same modal without the deactivation step.
  • Added — §6 Record page, the lead page’s cards: the AI summary card is first in Overview’s wide column; Research leaves the wide column for the narrow one, after Customer, Tags and Shared with; the Follow-up draft moves to the Notes and email tab, above the Email card. Until now the wide column held the details, Tea requirements, then the summary, research, draft, priority and participants places (F11-f FR-V Rev 5).
  • Why: the toasts, the modal frame and Title Case that the same review asked for are Rev 90’s and are being moved over (.forge/owed.md); these four were not covered by it. Buttons drew icons on some screens and not others. The tag’s look in the Name column made the name harder to read and left the Colour column as a word. The offboarding screen did nothing a deactivation did not need, so the two actions read as two ways to do one thing. On the lead page the AI summary is what a salesperson reads first, the draft belongs with the notes and the mail it follows up, and the research is reference material beside the record.
  • Decision: Nanndish’s, 2026-11-06, in session: the four changes, every button (dialog buttons included) for the icons, the reassignment in a modal opened by Deactivate User, and the AI summary at the top of Overview’s wide column.
  • Scope: §5, one row added; §6 Record page, one bullet added; §8, two passages changed. No token changed, and no code changed by this revision. The code moves in forge-et-fe PRs (.forge/owed.md), each updating the current prototype (prototypes/crm-current/) for its screens. Approved specs that state the old behaviour get a revision in the PR that changes their screen: F1-e (the tag table’s columns), F5-c and F5-h (the Deactivate button, the Offboard user link and the offboarding screen, FR-U1–FR-U7 and AC-10), F11-f (FR-V Rev 5’s column order, FR-S1’s place order and AC-27), F11-c (FR-V1, the research place) and F11-h (FR-V1, the draft place).

Rev 101 — 2026-11-06 — §5 and §6: the Email screen’s data bar, list card, attachment tiles and action order (BUG-360 to BUG-364)

Written as Rev 101: Rev 100 was written at the same time on another branch, forge-et-harness#1170 (python3 .claude/lib/next-id.py ds-rev, 2026-11-06). Rev 100’s leading icon on every button applies to this revision’s buttons too, as each screen moves over.

  • Changed — §6 Two-pane list + detail, the Email data bar (BUG-360, BUG-361): the search box is nine space/8 steps (288px), the width on every other list screen, instead of Rev 84’s width of the columns left of the reading pane (552px with the folder pane open); the Category filter, and the Folder picker below bp/laptop, are as wide as their text, as the Leads and Accounts filters are, at most layout/form-width, instead of a fixed 288px slot. The data bar holds only the search and the filters.
  • Changed — §5 Tabs and §6, the Focused / Other tabs (BUG-361): they move from the data bar (Rev 97) to a tab strip across the top of the list card, in the new line variant of shadcn’s Tabs (no fill, the selected tab underlined in primary at border-width/selected), because they switch the list rather than filter it, as Outlook’s do above its message list. The list card and the reading pane still start level. Their behaviour is unchanged: Inbox only, gone during a search, manual activation. The record page’s tab bar draws a different underline over the pill (RecordPage.module.css); whether it moves onto line is the lead’s decision, in .forge/owed.md.
  • Changed — §6, the Email list card (BUG-362): one card holds the tab strip, the rows (or the loading, empty or error state) and the pager. The strip, the refreshing line and the footer are set in where the row text starts, and the pager is drawn as the Contacts list’s in-card pager, with no rule above it. The card clips nothing, so a focused tab’s ring stays whole; from bp/laptop it runs to the bottom of the window, level with the folder pane and the reading pane, and only the rows scroll. The list had stopped at half the pane’s height because the empty panel Radix keeps for the tab not chosen was drawn: its class set display: flex, which beats the hidden attribute. §5 Tabs now says a panel class that sets display keeps [hidden] hidden (.forge/lessons.md L-262).
  • Added — §5 Attachment tile (BUG-363): a received email’s files are Outlook-style tiles in a wrapping row, the whole tile one button that downloads the file, with the type icon, the name over the size, and a download icon at its end. The Attachment row stays for files being attached in compose and on records.
  • Changed — §6, an open message’s actions (BUG-364): Refresh and Mark as unread, then Forward, Reply all and Reply: the primary action last, at the right end, as Rev 72 sets for every screen, right-aligned so Reply stays at the right edge when the actions wrap under the subject.
  • Why: Nanndish’s UI review of the Email screen, 2026-11-06: the filters were out of proportion and unlike the other screens’, the search box too long, the list short and scrolling in a small box, the attachments unlike Outlook’s, and the primary Reply first where every other screen’s primary action is last.
  • Decision: Nanndish’s, 2026-11-06, on the Email Screen Redesign artifact (https://claude.ai/artifact/Mw9xaBAjGoxAbbSGMnM7Cy): the proposal as drawn, the search at 288px rather than layout/search-max, the tabs moved into the list card, the tiles downloading on click, and Reply moved to the right end.
  • Scope: §5 (Tabs, one variant; Attachment row, one sentence; Attachment tile, a new row) and §6 (Two-pane list + detail, one paragraph). No token changed; the download icon concept is added to the icon registry. Implementing code, in forge-et-fe: src/ui/shadcn/tabs.tsx, src/ui/icons/registry.ts, and in src/features/email, InboxToolbar, CategoryFilter, FolderPicker, InboxTabs, InboxList, EmailRoute, MessageAttachments and MessageView, with their stylesheets.

Rev 102 — 2026-11-06 — §5 Attachment row gains the record variant; the record card’s upload hint (F33-a)

  • Added — §5 Attachment row, the record variant (F33-a’s Attachments card on the account, contact and lead pages, spec FR-P2–FR-P8): one file per row — the type icon from the registry (fileText for PDF and Word, fileSpreadsheet, filePresentation, fileImage, attachment otherwise), the name shortened from the middle with its extension visible (read whole by a screen reader), and the meta line uploader · date · size in type/meta. Download shows to everyone who sees the card; Delete shows to a holder of the record’s manage key; the zone and Delete show disabled with the reason when the permission is denied-contextual and are absent when it is denied-permanent; each action is named with the file. States, in sentence case:

    • ready (CLEAN or NOT_SCANNED) — the meta line and Download; a NOT_SCANNED file carries no wording that claims or denies a check;
    • being checked (PENDING) — “Being checked”, no Download;
    • refused (INFECTED) — tone/danger: “Refused: this file may contain a virus”, no Download, Delete for a manager;
    • uploading — “Uploading”, a determinate bar (shadcn Progress) and Cancel;
    • failed — tone/danger, the reason (the type or size refusal, the no-permission reason, or the transport failure), Retry when the failure can be retried, and Remove;
    • confirming delete — the row becomes Delete ? with Delete and Cancel, in place, never a second dialog, in the order of a note’s delete question; whether Rev 77’s order (Cancel first) covers such inline questions is the lead’s open decision (.forge/owed.md);
    • delete failed and download failed — the row restored with Delete failed or Download failed and Retry.

    It carries the uploader, date and download parts Rev 60’s compose variant left to F33.

  • Changed — §5 File upload: the record card’s zone, shown only to a manager, states PDF, JPEG, PNG, Excel, Word or PowerPoint, up to 25 MB each before any upload and takes several files (multiple); the zone stays idle and each file draws its own bar in its row, as Rev 60 set for callers with several files.

  • The card: a shadcn Card headed Attachments — the zone, then uploading rows above the list (newest choice first), then the files, with Show more while the server has more. Empty: No files yet and the line Artwork, buyer POs, spec sheets and certificates. Error on the first read: Files could not be loaded with Retry. A failed re-read keeps the rows, with a band saying the list is shown as of a stated time and Retry. One polite status line announces uploads, deletions and failures; there is no toast. The card’s buttons carry no leading icon, and its successes are not toasts, until the account, contact and lead pages move onto Rev 100’s icons and Rev 90’s toasts (.forge/owed.md), as their other cards do. At 320px a row’s actions wrap under its text.

  • Why: F33-a attaches files to accounts, contacts and leads (spec FR-P1–FR-P9, FR-H3); §5’s Attachment row described a record’s file only in outline, written before scanning was switched off.

  • Decision: Dinil’s, with the F33-a spec (approved 2026-11-06); the leading icons and the status line without a toast at the F33-a-WI-1.2 plan review (2026-11-06).

  • Scope: §5, the Attachment row and File upload rows. No token changed and no registry concept added. Implementing code: forge-et-fe src/features/attachments/ (F33-a-WI-1.2); the current prototype draws the card on the three pages (prototypes/crm-current/).

Rev 103 — 2026-11-07 — §5 and §9: how Rev 90’s toasts and Rev 100’s icons were applied across the CRM (forge-et-fe#442)

  • Changed — §5 Toast, a success inside a dialog that stays open: the success is still a toast (notifySuccess). When the toast region cannot be heard at that moment — a native modal <dialog> is open, or an ancestor of the region is inert or aria-hidden (toastRegionHidden(), forge-et-fe src/ui/toastRegion.ts) — the dialog also says the same sentence in its own polite status line, so a screen reader hears it once. Radix dialogs leave live regions audible, so inside them the toast alone is heard. A notice the user must act on or dismiss (a lead that is no longer available, a list read that failed) stays inline in the screen’s own notice element, as Rev 90 says, never as a toast that outlives its screen.
  • Changed — §5 Attachment row, the record card (Rev 102): its buttons now lead with their icons and its upload and delete successes are toasts, with the status line kept for progress, failures and the no-permission reason, because forge-et-fe#442 moves the account, contact and lead pages onto Rev 100’s icons and Rev 90’s toasts — the condition Rev 102 set.
  • Changed — §5 Button — leading icon (Rev 100), concepts used for repeated actions: Reload and Reload the Round use refresh, Retry and Try Again use retry; the safe answer in a question (Cancel, Keep Editing, Keep Writing, Stay) uses cancel; Show All … (dropping a status filter) uses clearFilter.
  • Changed — §9 Capitalization, a provider’s sign-in button: the Microsoft button reads Sign in with Microsoft, Microsoft’s own wording for it, as a name keeps its own casing; the screen’s other titles and buttons take Title Case (Sign In).
  • Why: forge-et-fe#442 applied Rev 90 and Rev 100 across every screen; its review found successes raised inside dialogs, sticky notices made into app-wide toasts, and one action drawn with two glyphs on different screens. These rules are what that PR does.
  • Decision: taken in the overnight run of 2026-11-07 under Nanndish’s instruction to finish the PR without stopping for questions, each the option closest to Rev 90 and Rev 100 that changes behaviour least; for Nanndish to confirm or reverse in review of forge-et-fe#442.
  • Scope: §5, the Toast, Attachment row and Button — leading icon rows; §9, one case under Capitalization. No token changed. Implementing code: forge-et-fe#442 (src/ui/notifySuccess.ts, src/ui/toastRegion.ts, src/features/leads/useLeadsNotice.tsx, src/features/attachments/, src/features/auth/LoginRoute.tsx).

Rev 104 — 2026-11-08 — §6: row selection and Change Owner on the account and lead lists (F32-c)

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-08; Rev 103 is held by an open harness PR.

  • Changed — §6 Data table, Selection and Bulk-action bar rows: a Used pointer beside Rev 39’s Built one. The account list and the lead list now select rows for a role holding the entity’s manage key, and the bar offers Change Owner (F32-c spec FR-6, FR-7). On those lists the selection column is the one column pinned at the inline start while it shows, and Name scrolls with the rest, as on the offboarding tables; without the column, Name is pinned as before (§9 Tables, Rev 68). The lists’ header row is sticky, so the selection header cell stays at the top too, on the corner’s level, with the header row’s fill and rule (SelectionHeaderCell’s new stickyHeader, styled in RowSelection.module.css). The bar sits inside the list card, above the table and outside its scroll region; Select all … and Clear gain their leading registry icons (selectAll, clearSelection), and Change Owner its own (changeOwner), as Rev 100 sets.
  • Moved — the Change Owner dialog and the pass result leave the users feature for forge-et-fe src/ui/bulkReassign/ (ChangeOwnerDialog, PassResult), shared by the offboarding lists and the two lists; the dialog is now §5’s Rev 90 frame at md with a Title Case title (Change the Owner of 3 Accounts), one sentence under it, New Owner, then Cancel and Move 3 Accounts with their icons; the result is shadcn’s Card in the same tones. The client step that turns a selection into requests is src/lib/bulkReassign/ (runChangeOwnerPass, useBulkChangeOwner). On the two lists a pass that moved every record is reported by a toast (§5 Toast, Rev 90) and any other by the inline result; the offboarding lists keep the inline result for both.
  • Why: F32-c brings the bulk Change owner action forward from F32-b so the import owner can hand imported records out (F32-c spec Context); §6 already defined the selection and the bar as shared parts for it (Rev 39).
  • Decision: Tharinda’s, at the F32-c-WI-1.2 plan review, 2026-11-08: only the selection column is pinned (no second pinned column, which would narrow the 768px scroll area), and a clean pass is a toast.
  • Scope: §6, two rows. No token changed; four registry concepts added (cancel, changeOwner, selectAll, clearSelection, the glyphs Rev 100’s batch names). Implementing code: forge-et-fe src/features/accounts/, src/features/leads/, src/ui/bulkReassign/, src/lib/bulkReassign/ (F32-c-WI-1.2); the current prototype draws the selection column, the bar and the dialog on the Accounts and Leads list pages (prototypes/crm-current/).

Rev 105 — 2026-11-08 — §9: the capture app takes Rev 90’s casing

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-08.

  • Changed — §9 Capitalization, Scope and the move over: the capture app (forge-et-pwa) follows the same casing rule as the CRM. Titles, navigation, buttons and menu items that act, standalone links, column headers, field labels and icon-only buttons’ names are Title Case; placeholders, helper text, tooltips, messages and the values shown stay sentence case. Before this revision the capture app kept the rule before Rev 90: sentence case, with Title Case only for the navigation, screen names and proper nouns.
  • Why: one rule for both apps. The capture app’s F36 screens are still to be built, so only the app shell’s few labels have to be recased (Page not found, Reload the page, Back to the dashboard), and a rule that differed between the two apps would be one more thing to get wrong.
  • Decision: Tharinda’s, 2026-11-08, in session, settling the question Rev 90 left open in .forge/owed.md.
  • Scope: §9, one bullet. Casing only: the capture app’s other differences from the CRM (CSS Modules rather than shadcn/ui, its own sizes and target size) are unchanged. frontend-reviewer check 20 states the rule for both apps. The current capture-app prototype (prototypes/pwa-current/) still shows the POC’s sentence case; it is recased as its screens are built (.forge/owed.md).

Rev 106 — 2026-11-08 — §6: the multi-choice filter’s long list scrolls, and typing moves through it; the list filters take several values (F32-d)

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-08, which printed Rev 106: Rev 105 is held by an open harness PR. The F32-d-WI-1.2 plan, written before that, calls this revision Rev 105.

  • Changed — §6 List screen, the multi-choice select (Rev 99): two behaviours, for every instance, the Leads list’s Priority filter included. The list scrolls inside the popover when it is taller than the space between the trigger and the viewport’s edge (Radix’s measured available height), so a long list never runs off the screen. Typing moves focus: with a box focused, a printable key moves focus to the next box whose label starts with the letters typed within the last 500 ms, wrapping at the end — one letter, or the same letter again, moves on from the focused box, and several letters stay on it while it still matches, as a single-value select’s typeahead does; while such a burst is under way Space is part of the search and does not toggle the box, and otherwise Space toggles it as before. The trigger, the popover and the boxes look as they did.
  • Used — every vocabulary, owner and tag filter on the account, lead and contact lists is now this select (F32-d spec FR-F2, FR-F3): the account list’s Customer Type, Country, Region, Tag and Owner; the lead list’s Country, Buyer Type, Lead Source, Tag and Owner, where Unassigned excludes the named owners (ticking it clears them, ticking an owner clears it); and the contacts page’s new Customer Type, Country, Region (its account’s) and Tag, after Account. F32-c’s Pipedrive Owner filter on the account and lead lists stays a single-choice select (F32-d-WI-1.2 plan Decision 16); choosing a name while Owner is empty sets Owner to the signed-in user, and does nothing to a lead list’s Unassigned. The filter names are in Title Case, as forge-et-fe#442 recased these three screens (§9 Capitalization, Rev 90); the option values stay in sentence case. The current prototype draws the three data bars with the built labels in this casing. A chosen value the options do not hold — a retired or unknown tag in the URL, an owner the directory does not name — gets an option after the others (<name> (retired), Unknown tag, Selected tag, Loading…, Unknown person), so the trigger names the filter applied and the box can be unticked; a failed option read shows its message and Retry beside the trigger, which the message describes.
  • Why: the Country filter has about 250 values and the Tag and Owner filters as many as the server reads. Without the scrolling list the popover runs off a 320px screen, and without typeahead a keyboard user who could jump to United Kingdom in the single-value select it replaces would tab through up to 250 boxes (WCAG 2.1.1 is met either way; it is not usable).
  • Decision: Tharinda (the lead), 2026-11-08, at the F32-d-WI-1.2 plan approval (that plan’s Notes Q-1): accept both behaviours, with the Space rule during a typeahead burst.
  • Scope: §6, one rule. No token changed. Implementing code, in forge-et-fe (F32-d-WI-1.2): src/ui/filters/FilterMultiSelect.tsx (the two behaviours, a test id computed from the value, describedBy), and its callers src/features/accounts/AccountsFilters.tsx, src/features/accounts/ContactsFilters.tsx and src/features/leads/LeadFilters.tsx; the current prototype draws the three data bars with the Priority filter’s popover, whose list now scrolls (prototypes/crm-current/).

Rev 107 — 2026-11-09 — §3, §5 and §9: form labels in text/primary, Title Case placeholders, a hot / cold pill, the buying-standards toolbar off the table’s card, the Weekly Prices refresh line in the filter row

  • Changed — §3’s note and §5 Form fields: a form field’s label is text/primary, not text/secondary, so it reads ahead of the placeholder and the helper text, which keep their colours (text/faint and text/secondary). The same colour goes on the labels drawn outside Field: the contact form’s Other Emails legend, the compose dialog’s From, the standard dialog’s Client, and the custom-field dialog’s Type and Options. A source test pins them (forge-et-fe src/ui/components/Field/formLabelColour.test.ts). Loading words shown in a placeholder’s place (Loading types, Loading roles) are status text and stay sentence case. A section eyebrow inside a form (the lead form’s Tea Requirements) and a read-only record view’s labels keep text/secondary.
  • Changed — §5 Form fields and §9 Capitalization (reversing Rev 70’s lower-case wording and Rev 90’s sentence case for placeholders): every placeholder in the CRM is in Title Case — Enter Company Name, Select Country, Search Leads, Find or Create a Lead Tag, Write What Was Said or Agreed — by §9’s rule for a title (the short words lower case; acronyms, codes and units as written). enterPlaceholder and selectPlaceholder build it, and titleCase cases a placeholder built from a search box’s aria-label; the aria-label itself keeps its wording (Search leads), so a screen reader’s name does not change. A field’s error message built from its label stays a sentence (labelInSentence). The capture app keeps sentence-case placeholders (Rev 105) until a PR of its own recases them.
  • Changed — §5 Status indicators, the Lead engagement — hot / cold row (replacing Rev 93’s dots): Hot is a small pill tinted tone/danger with a flame glyph and the word, Cold a pill tinted tone/neutral with a snowflake glyph and the word, neither with a border; the word is type/meta at weight 600 (--et-type-card-title-weight), so it reads as a state beside the body-weight cells; both glyphs are new registry concepts (leadHot, leadCold). The glyph and the word carry the status, so it does not rest on colour. The tone/positive dot read as “good” rather than “warm”.
  • Changed — the account page’s Buying Standards tab (F26-b FR-U5): the heading, Manage Standards, the search box and Show Archived Standards sit on the page, and only the table and its pager are in the card below them, as the Leads list keeps its data bar off the table’s card. The card is shadcn’s Card in the list screens’ table-card shape — no side padding, the table running to its edges, the loading, error, stale and empty states set in from them — so the panel’s backfill entry loses Card.
  • Fixed — the Pricing page’s Weekly Prices tab: the round summary’s Refreshing the round summary line sits at the end of the status-filter row, with a spinner, instead of on a line of its own above the summary, and the row keeps the line’s place, unseen and unread, while nothing refreshes, so a re-read no longer pushes the table down even where the filters wrap (F26-f FR-16’s quiet line keeps its words and test id).
  • Decision: Nanndish’s, 2026-11-09, in session.
  • Approved specs this contradicts, revised in this change: F11-g (decision 10, FR-V2, FR-V3 and AC-23 — the hot / cold indicator’s tone and shape); F1-b NFR-1, F1-e NFR-8 and F11-b NFR-3 (sentence-case placeholders). Specs that say sentence case for everything else by reference to §9 (F1-d, F1-f, F11-d, F11-f, F12, F11-g NFR-8) are read through §9 and need no revision. A spec that quotes a placeholder’s lower-case text is read in this casing, as §9 Scope and the move over reads a quoted label.
  • Scope: §3’s note, §5’s Form fields rule and Status indicators row, §9’s Capitalization. No token changed. Implementing code, in forge-et-fe: src/ui/components/Field/Field.module.css, src/ui/fields/placeholders.ts, src/ui/filters/DataBarControls.tsx, src/ui/components/LeadRankIndicators/ (the pill and its CSS module), src/ui/icons/registry.ts, src/features/accounts/AccountStandardsPanel.tsx, src/features/pricing/RoundSummaryBar.tsx, and every screen whose placeholder was a literal. The current prototype (prototypes/crm-current/) is not yet redrawn with these changes (owed.md).

Rev 108 — 2026-11-09 — §6: the Columns menu on the account, lead and contact lists (F32-d)

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-09, which printed Rev 108: Rev 107 is held by an open harness PR. The F32-d-WI-2.2 plan, written before that, expected Rev 107.

  • Changed — §6 Data table, Column configuration: the row records the built menu. The Columns trigger (an outline button at the data bar’s 40px height, leading with the columns icon) is the data bar’s last control, at its inline end, after Clear Filters when that shows. It opens a popover of checkboxes, the multi-choice select’s pattern (Rev 99) and not a §5 Dropdown Menu, for the multi-choice select’s reasons. One row per column: the shown columns in their order, then the hidden ones in the default order; each row is the column’s box, named by its header, and its Move Up / Move Down icon buttons with tooltips. Name is listed, checked and unavailable; a hidden column has no position, so its move buttons are unavailable; Move Up on the first column after Name and Move Down on the last shown column are unavailable too. Every unavailable control is aria-disabled and stays focusable. A one-line helper heads the popover (Name is always shown first. Hidden columns are listed last.), and Reset to Default Columns closes it. Tab leaves the popover as the multi-choice select’s does; after a move or a toggle, focus stays on the pressed control in the row’s new place, with the popover open. A visually hidden status line announces a move (Country moved to position 3 of 7), a reset (Default columns restored) and a failed save.
  • Changed — the stored choice: on the default view each change is stored at once, per user per list, and the list’s first rows wait for the stored choice to be read, showing the table’s skeleton meanwhile. A failed read draws the default columns, says Couldn’t load your column choice; showing the default columns with Retry and its reference beside the trigger, and keeps the trigger unavailable until a read succeeds, so no change overwrites a choice the user never saw. A failed save keeps the choice on screen and says Couldn’t save your column choice; it applies until you leave this list, with Retry and its reference. Hiding the column the list is sorted by keeps the sort; no header then shows it (on the lead list the Sort control still names it).
  • Changed — §6 List screen: one phrase: on the account, lead and contact lists the data bar ends with Columns.
  • Changed — the Column configuration row’s sentence on F34 custom fields appearing “automatically via the FieldRenderer registry” now says custom-field columns are future work (F34-b): the menu lists only the columns a list declares.
  • Added — three registry icon concepts: columns (lucide Columns3), moveUp (ArrowUp) and moveDown (ArrowDown). Reset to Default Columns uses the existing refresh, as Reset List does.
  • Casing: §9 (Rev 90) — Title Case for the trigger, the popover’s name, the column labels, Reset to Default Columns and the move buttons’ names (Move Country Up); sentence case for the helper line, the announcements, the notices and the tooltips’ wording where it is not an action name.
  • Why: F32-d FR-C1 to FR-C3 and NFR-3 (spec Rev 4): each list’s columns can be hidden, shown and reordered from the keyboard, and the choice follows the user to any device.
  • Decision: Tharinda (the lead), 2026-11-09, at the F32-d-WI-2.2 plan approval (that plan’s Notes Q-1 to Q-5): the trigger at the data bar’s inline end, the popover of checkboxes with both move buttons on every row, the hidden sorted column kept, §9’s casing, and the save-failure wording.
  • Scope: §6, one row and one phrase. No token changed; three registry concepts added. Implementing code, in forge-et-fe (F32-d-WI-2.2): src/ui/filters/ColumnsMenu.tsx and src/ui/filters/popoverTabOut.ts (the Tab handling, moved out of FilterMultiSelect unchanged), src/lib/listViews/ (the column rules, the API client and useStoredColumns), the three tables and screens in src/features/accounts/ and src/features/leads/; the current prototype draws the Columns menu on the three data bars and tables that follow it (prototypes/crm-current/).

Rev 109 — 2026-11-10 — §3: the type scale moves to six sizes, 12, 14, 16, 18, 20 and 24px

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-10, which printed Rev 109: Rev 107 is held by an open harness PR and Rev 108 is on main.

  • Changed — §3 Typography scale: every type/* level takes one of six sizes. type/display 40 → 24px; type/title 22 → 24px; type/stat stays 20px; type/subhead 17 → 18px; type/section 15 → 16px; type/card-title stays 14px; type/body 13 → 14px; type/button 13 → 14px; type/secondary 12.5 → 12px; type/meta 11.5 → 12px; type/micro 10.5 → 12px. Weights, line-heights, faces and tracking are unchanged. Each level moves to the nearest size in the set; the two that sit halfway were decided: type/body (and with it type/button) goes up to 14px rather than down to 12px, and the login headline goes down to 24px rather than keeping 40px as an exception.
  • Changed with it — screen and record titles: every screen’s and record page’s h1 was twice type/body (26px, Rev 74), which would have become 28px; it is now type/title’s 24px at the h1’s bold (§6 Screen header, Detail page), in forge-et-fe src/ui/components/PageHeader/PageHeader.module.css and src/ui/PageHeading.module.css. The capture app’s three h1s that took the browser’s default size (2em, 28px) take type/title too. Measured in the browser after the change, on the CRM’s Settings, Users, Roles, tag, email-template and user pages and the capture app’s two routes: no visible text renders at a size outside the set.
  • Changed with it: §1’s login headline (24px); §5’s sm button label, which takes type/meta’s size (12px) and is no longer a raw size; §6’s KPI row wording; the capture-app departure table (the CRM’s body is now 14px too, so the capture app’s step-up applies only to type/secondary and type/meta, which it still raises to 14px through capture.css). §3’s measurement notes from FS-3 are replaced by a Before Rev 109 column.
  • Why: a smaller set of sizes on whole pixels, the same in both apps. Three groups of levels now share a size (type/display and type/title at 24px; type/card-title, type/body and type/button at 14px; type/secondary, type/meta and type/micro at 12px), and weight, casing and tracking tell them apart.
  • Decision: Nanndish, 2026-11-09, in session: the six sizes, body at 14px, the login headline at 24px, and both apps.
  • Scope: the --et-type-*-size values in forge-et-fe and forge-et-pwa (src/ui/styles/theme-empire.css, and src/ui/styles/tokens.css, which stays a byte copy between the two), the title sizes above, and comments in both repos that quoted an old size. Apart from the titles, every font size in both apps reads a type/* token, and shadcn’s text-xs, text-sm, text-base and text-lg map onto them (forge-et-fe src/ui/styles/shadcn.css). The current CRM prototype (prototypes/crm-current/) moves each literal font size to the nearest size in the set (12.5px and below → 12, 13–14.5 → 14, 15–16 → 16, 17–18 → 18, 19–21 → 20, 22 and above → 24). This revision does not change the current capture-app prototype (prototypes/pwa-current/): since F36-a it has its own source/ folder and saved versions, and it still sets sizes outside the six. Whether it takes the six sizes at once or screen by screen as F36 builds them is open in owed.md (“Bring the current capture-app prototype onto the 12–24px type scale”). The frozen originals are never edited.

Rev 110 — 2026-11-11 — §4, §5 and §6: no icon on Cancel, no required-fields sentence, the primary header action last, one banner component, one look for the pickers in a dialog, the Email page in one card, More Filters on the Leads list (UI polish round 2)

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-11, which printed Rev 110: Rev 109 is held by an open harness PR (forge-et-harness#1266).

  • Changed — §5 Button — leading icon (Rev 100) and §4’s registry: a button that backs out takes no icon — Cancel, Stay, Keep, Keep It, Keep Editing, Keep Writing and Keep Checking are text only, wherever they sit. shadcn’s AlertDialogCancel takes no icon, ConfirmDialog loses its cancelIcon prop, and the registry loses its cancel concept, which withdraws Rev 103’s use of cancel for the safe answer in a question. The corner ✕ (close) and Clear Filters / Clear Search keep their icons, and every other labelled button keeps Rev 100’s leading icon.
  • Changed — §5 Form fields and validation, the Required rule: no form or dialog states the convention in a Fields marked * are required sentence. The * on a required field’s label stays, with the field’s required state. A sentence that also said something else keeps that part: A new sale is scheduled. (New Sale), Saved to 's standards book. (the standard dialog), and A name is enough to start as New Account’s helper.
  • Changed — §6 Record page, the header: the page’s primary action is the last header button, at the far right, as Rev 72 set for a list screen’s title bar. The account page reads Edit Account, Archive Account / Restore Account, Compose Email, Add Follow-Up, Send This Week’s Prices; the lead page reads Edit, Archive / Restore, Add Follow-Up, Approve & Send (Send Follow-Up). Before this, Send This Week’s Prices sat between Compose Email and Add Follow-Up, and Approve & Send came before Add Follow-Up.
  • Changed — §4 registry: Create Draft Prices and Replace and Create on the Pricing import use a new concept, draftPrices (lucide FilePen), in place of add.
  • Changed — §4 icon sizes and §6 App frame: the sidebar’s navigation glyphs are 20px (calc(icon/md + space/1)), set in Sidebar.module.css only; icon/md stays 18px. The 76px icon rail still centres them.
  • Changed — §6 Record page, the lead page’s cards (replacing Rev 100’s order): Overview’s wide column holds AI Summary, Priority, Follow-ups, the contact and inquiry details, Tea Requirements and the participants place; the narrow column holds AI Research, then Customer, Tags, Shared with and Attachments. Below bp/laptop the page is one column, the wide column’s cards first, so AI Research comes after them on a tablet: RecordColumns cannot lift a narrow-column card, and this is left as it is.
  • Changed — §5 Badge / pill, the AI triage tag’s dismiss: the Spam / Duplicate badge in the AI Summary card holds its own dismiss control — a ghost icon-only button, a 24 × 24 target with a 12px ✕, named Dismiss Tag: , a spinner in its place while pending, test id lead-triage-dismiss — replacing the separate Dismiss Tag button with visible text under the tag (F11-d FR-V2).
  • Changed — §6 Two-pane list + detail, the Email page: from bp/laptop, the folder pane, the list and the reading pane are one card (test id email-panes), separated by 1px rules in the card’s border colour with no gaps, each pane scrolling on its own, the folder pane still collapsing to its rail; this supersedes Rev 86’s space/5 between three cards. Compose is the page header’s last action at every width, and is no longer at the top of the folder pane or in the rail (superseding Rev 95’s placement). Below bp/laptop, a Folders outline button with the folder icon at the start of the inbox data bar (inbox-folders-open), reading Folders: as a filter shows its value (named Folders Inbox; a long name cut with an ellipsis), because no other place on that screen names the folder, opens a shadcn Sheet drawer from the inline-start edge, titled Folders (inbox-folders-drawer), holding the same folder tree; it opens with focus on All mail, or on the drawer’s first control while the tree has no link; choosing a folder closes it and moves focus to the message list, and Esc or the ✕ returns focus to the button. The Folder picker (Rev 86’s Select, FolderPicker) is removed. New page states email-folders-drawer and email-folders-drawer-loading (below bp/laptop; email-folders-loading now runs from bp/laptop up).
  • Added — §6 List screen, More Filters: the Leads list’s data bar keeps Search, Owner, Pipedrive Owner (during the hand-out), Priority, Hot / Cold, Sort, More Filters and Clear Filters in the row. More Filters — an outline button at 40px with the filter icon, reading More Filters (n) with n of its filters applied (test ids leads-more-filters, leads-more-filters-popover) — opens a shadcn Popover named More Filters holding, one per row, Country, Buyer Type, Lead Source, Tag, AI Tag, Shared with me and Existing customer?; every trigger inside is as wide as its row, so they line up, and a switch keeps its own width. The URL state and the test ids do not change, and Clear Filters clears them too. A new page state, leads-more-filters-open.
  • Added — §5 Alert / banner, a row: shadcn’s Alert is the one banner component. It gains a warning variant (warning-muted tint, its paired text, the warning edge, the registry warning icon), and destructive now draws the destructive-muted tint with its paired text. ErrorPanel draws through the destructive variant (its API, Retry and test ids unchanged). Moved onto Alert: SyncLapsedNotice, SaveErrorSummary and FolderTreeNotice (through ErrorPanel) as destructive; MissingKeysNotice (until now a Card), PricingWarnings and ImportWarnings as warning. MailboxConnectBanner (Rev 80) and PublishRoundDialog’s notice use the warning variant in place of hand-typed classes. Card / Panel says a banner is an Alert, and the Empty / loading / error states row names ErrorPanel. Section banners still drawn by hand move over later (.forge/owed.md).
  • Changed — §5 AI provenance, the Source row: the inquiry extraction’s source label is Pasted inquiry, (from: Pasted inquiry, 9 Oct), where it was lower case. Only that label changed; the other labels the server writes stay lower case because approved text writes them so (F11-h’s wave-1 contract, Rev 69’s and Rev 99’s examples), and whether all of them take sentence case is open (.forge/owed.md).
  • Added — §5 Select inside a dialog, a row: every picker in a form or dialog shares one closed look (the shadcn Input’s height, border and card fill, a muted chevron). A short fixed list is shadcn’s Select through a new wrapper, OptionSelect ({ value, label } options; an empty-value option stays so a saved value can be cleared, BUG-283): the account form’s Region, Customer Type and Currency, the lead form’s Buyer Type and Lead Source and its Tea Requirements Product Line and Incoterm, and New User’s Role. A list the user searches is the Popover-based SearchSelect: Country on the account and lead forms (first option No country, which clears it; a Radix Select was too slow for about 250 countries), the standard dialog’s Client picker (F26-b Rev 9) and OwnerPicker (the account and lead forms, Change Owner — the offboarding list’s, in OwnedRecordsList, included — and Change Manager), which leaves its native <select> — kept only because the older Modal clipped a custom list — and shows each person’s role on a second line. SearchSelect and AddTagPicker gain disabled (aria-disabled, the list does not open) and SearchSelect gains onBlur. RecordSearchPicker (the lead’s match dialog) is rebuilt on shadcn Input + Popover in place of react-aria-components’ Combobox, with the same behaviour, and AttachAccountPicker keeps its behaviour with the matching chevron. The standard dialog’s Type select is unchanged.
  • Fixed — a dialog’s ✕ beside its title (BUG-156’s rule): the record dialogs, the Notes dialog, the Settings dialogs and the price email dialog drew their 32px ✕ at the top of the title’s 36px row, 2px above the title’s centre. One shared part, src/ui/overlays/DialogCloseButton.tsx, now draws the ✕ centred in a row as tall as the title (layout/control-h-compact), so a one-line title centres on it and a wrapped title runs on below; no token changed. Found by the browser gate (see-and-add’s the title’s line centres on the ✕) during this delivery.
  • With Revs 111 to 113, which reached main first: F20-g’s Scheduled entry (Rev 111) is in the Folders drawer’s tree as it is in the pane, and /email/scheduled uses the drawer below bp/laptop in place of its picker, with Compose in its header at every width. Cancel Email on that list is an action, not a Cancel button, so it keeps its leading ✕ through a new registry concept, cancelScheduled (lucide X). The lead page’s Custom Fields card (Rev 113) stays after Tea Requirements, which now puts it before the participants place, not before Priority.
  • Why: the CRM UI polish tracker, items #49 (the Cancel icon), #52 (the required-fields sentence), #51 (the primary header action), #55 (the draft-prices icon), #57 (the sidebar icons), #54 (the lead page’s cards), #47 (the triage tag’s dismiss), #40 and #50 (the Email page), i04 (the Leads filters), i14 (one banner component), #53 (the provenance label), and #43 and #48 (the dropdowns inside dialogs). A Cancel icon added nothing to a word every user knows; the required-fields sentence repeated what the * says; the primary action was the only header button not at the far right; the Leads data bar ran to several rows at laptop widths; the Email page’s three cards and gaps did not read as one mail client, and Compose moved between the header and the pane with the width; banners were drawn several ways by hand; and the pickers in one dialog looked different from each other, the native selects drawing the browser’s own list.
  • Decision: Nanndish Satgunarajah’s, 2026-11-11, in session, from the CRM UI Polish Tracker artifact.
  • Approved specs this contradicts, revised in this change: F3-a (FR-V5, AC-24, AC-25 — the header order and the Follow-ups card’s place on the lead page), F1-d (FR-S1 — the actions order), F11-h (FR-V2, FR-V3, AC-25 — Approve & Send first), F11-f (FR-S1 and FR-V1, already revised on this branch as F11-f Rev 13), F11-d (FR-V2, FR-V5, NFR-8, AC-26 — the dismiss control), F20-c (FR-E4, AC-31 — Compose), F20-i (FR-13, AC-32a — the picker and the folder pane), F5-g (FR-L4 — Shared with me on the lead list), F11-b (FR-L4, AC-11 — the lead filters), F12 (FR-E4, FR-U3, AC-9, AC-18 — the source label) and F1-b (FR-C2, F1-b Rev 15 — the required-fields sentence as the first line of the account form). No approved spec requires a Cancel icon by name, and F1-b FR-C2 is the only one that required the required-fields sentence. Draft specs it affects: F11-e and F25-a, each given a dated note that its header actions go before the record page’s primary action (.claude/rules/specs.md); and F20-g, a draft on the open forge-et-harness#1243, whose Scheduled entry is drawn in the removed FolderPicker, with space/5 between the Email page’s panes and the header Compose only below bp/laptop — its owner has the .forge/owed.md row “Build F20-g’s Scheduled entry on design-system Rev 110’s Email page”. F26-d FR-U1 names no position for Send This Week’s Prices, so it needs no revision. No approved spec names a native select or react-aria-components’ Combobox for the fields the Select inside a dialog row moves (F1-b, F11-b, F11-f, F5-c, F5-h and F32-c speak of selects and an owner or account picker without naming the control; F5-c Rev 12 already names shadcn’s Select and the search select), so none is revised for it.
  • Scope: §4, the icon sizes and the registry; §5, the Button — leading icon, Badge / pill, Card / Panel and Empty / loading / error states rows, new Alert / banner and Select inside a dialog rows, the Form fields Required rule and the AI provenance Source row; §6, the App frame, List screen, Two-pane list + detail and Record page bullets. No token changed; one registry concept added (draftPrices) and one removed (cancel). Implementing code, in forge-et-fe branch feature/ui-polish-round-2: src/ui/shadcn/alert-dialog.tsx, src/ui/overlays/ConfirmDialog.tsx, src/ui/icons/registry.ts, the forms and dialogs that carried the required-fields sentence, src/app/accountPanels.ts, src/app/leadPanels.ts, src/features/pricing/CreateStep.tsx, src/app/Sidebar.module.css, src/features/leads/LeadView.tsx, src/features/leadTriage/TriageTagBlock.tsx, src/features/email/EmailRoute.tsx, FolderColumn.tsx, FolderDrawer.tsx, InboxToolbar.tsx (FolderPicker.tsx deleted), src/ui/shadcn/sheet.tsx (new, on Radix Dialog, no new dependency), src/features/leads/LeadFilters.tsx, src/ui/filters/MoreFilters.tsx (new), src/ui/shadcn/alert.tsx, src/ui/components/ErrorPanel/ErrorPanel.tsx and the notices named above, src/ui/fields/OptionSelect.tsx (new), SearchSelect, OwnerPicker, RecordSearchPicker, AddTagPicker, AttachAccountPicker and the account, lead and user forms that use them, src/ui/overlays/DialogCloseButton.tsx (new) and the four dialogs that draw their ✕ with it (RecordEditDialog, NotesDialog, SettingsDialog, PriceEmailDialog); in forge-et-be branch feature/polish2-lead-notes, lead/service/InquiryExtractor.java (the source label). The current prototype (prototypes/crm-current/) is redrawn with these changes in the same delivery (its README’s 2026-11-11 bullet), except the lead page’s Follow-ups card, which it has never drawn (.forge/owed.md).

Rev 111 — 2026-11-09 — §5 status indicators: the email tracking row (F20-g); §6: the Scheduled folder entry

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-11, which printed Rev 111: Rev 109 and Rev 110 are held by open harness PRs (#1266, #1274). The F20-g-WI-1.9 plan, written before that, expected Rev 107.

  • Added — §5 Status indicators, a provisional Email tracking row: Sent tone/neutral ring Sent; Opened tone/positive half-filled Opened; Clicked tone/positive solid Clicked; the tooltip and accessible name add the counts, the last time and Opens and clicks are estimates. A note beneath the table records why there is no Delivered state, why Sent is neutral and why the counts are called estimates.
  • Changed — §6 Two-pane list + detail: the Email folder pane gains the Scheduled entry, in the Mailbox group after Archive and on the rail as a tile after the Mailbox tiles, before the Folders tile; its count badge is the number waiting to send, not an unread count, and a tone/danger dot named Failed marks a failed send.
  • Why: F20-g adds open and link tracking to a single email (spec FR-V1–FR-V3); NFR-5 asks for the indicator as a new provisional §5 row, dot plus visible text. FR-V4 adds the Scheduled entry to the folder pane that §6 describes (Rev 95).
  • Decision: the F20-g spec’s NFR-5, approved by Dinil on 2026-11-09.
  • Scope: §5, one row and one note, and §6, one sentence. No token changed. The other wave-1 surfaces use existing patterns and add no row: the Track Opens and Clicks checkbox (the shadcn Checkbox, Rev 64), Send Later and Schedule Send (leading icons, Rev 100; Title Case, Rev 90), the scheduling toast (§5 Toast), Cancel’s alert dialog, the Scheduled folder entry (§6 folder pane, Rev 95, with the sentence above) and its list (§5 table). Implementing code: forge-et-fe (F20-g-WI-1.5, WI-1.6, WI-1.7); the current prototype draws the checkbox, Send Later, the Scheduled folder and list, and the indicator in the message view, a Sent Items row and a timeline entry (prototypes/crm-current/).

Rev 112 — 2026-11-09 — §5: a form field that takes several values (F34-c)

Numbered with python3 .claude/lib/next-id.py ds-rev; renumbered Rev 112 on 2026-11-11 under .claude/rules/id-numbering.md rule 5, because three open PRs opened before F34-c’s checkpoint PR (forge-et-harness#1266, #1274, #1281) add Rev 109 to Rev 111.

  • Added — §5 Form fields and validation: a form field that takes several values from a list is the §6 multi-choice select (Rev 99) inside a Field. It keeps the select trigger’s look, popover of checkboxes and keyboard rules, with three differences from the filter: none checked means no value, not All; the chosen options show as Badges under the trigger, in option order; and the trigger carries the Field wiring and is named by the label and its visible text together.
  • Not changed — dates: a custom date field is the native <input type="date"> of §5 Date input, as every other date field is; no new rule.
  • Why: F34-c’s custom fields need a multi-select in the account, contact and lead forms (spec FR-16), built only from shadcn parts. §5 had no form multi-select, and a plan may not give a screen a variant of its own (.claude/rules/plans.md § Required Sections). Reusing the filter’s trigger keeps the field the same height and look as the single-select beside it.
  • Decision: Tharinda (the lead), 2026-11-09, at the F34-c-WI-2.2 plan approval (that plan’s review pass 1, finding I2).
  • Scope: §5, one rule. No token changed. Implementing code, in forge-et-fe (F34-c-WI-2.2): src/ui/fields/customFieldRenderers.tsx; the current prototype draws it in the account, contact and lead forms (prototypes/crm-current/).

Rev 113 — 2026-11-09 — §6: the Custom Fields card on the account, contact and lead pages (F34-c)

Numbered with python3 .claude/lib/next-id.py ds-rev; renumbered Rev 113 on 2026-11-11 under .claude/rules/id-numbering.md rule 5, with Rev 112 above.

  • Added — §6 Record page: a read-only Custom Fields card, a §5 card headed Custom Fields holding a definition list of the record type’s active custom fields, each its label (as the administrator typed it) above its value. On the account page it fills the customFields place on Overview, after the profile card and before Attachments (F1-d FR-S1). On the contact page it sits in the rail after the contact card and before Attachments. On the lead page it sits in the Overview’s wide column after Tea requirements and before Priority (the lead page’s card list above names it). It is drawn only when the record type has an active custom field; with none, nothing is drawn — no heading and no box.
  • Not changed — empty values: a field with no value shows —, §9’s absent-value rule, as Tea requirements does beside it. No exception is made.
  • Why: F34-c spec FR-17 adds the card, and §6’s lead card list is meant to be complete. The position after the record’s own details matches the contact and account pages.
  • Decision: Tharinda (the lead), 2026-11-09, at the F34-c-WI-2.3 plan approval (its review pass 1, I1 and I2; spec Rev 2).
  • Scope: §6, one rule. No token changed. Implementing code, in forge-et-fe (F34-c-WI-2.3): src/features/customFields/RecordCustomFieldsPanel.tsx and the three compositions in src/app; the current prototype draws the card on the three pages (prototypes/crm-current/).

Rev 114 — 2026-11-11 — §5: a toast’s own buttons carry no leading icon

Numbered with python3 .claude/lib/next-id.py ds-rev.

  • Changed — §5 Button — leading icon (Rev 100): the “Not covered” list adds a toast’s own buttons (Sonner’s action and cancel, such as Undo and Dismiss).
  • Why: a toast is a short message with at most two small buttons, and an icon beside each crowds it. None of the CRM’s toast buttons carried one (useDiscardOffer.ts, useActivityRowActions.ts, F34-c’s custom-field failure toast), so the rule now says what is built.
  • Decision: Tharinda (the lead), 2026-11-11, settling the .forge/owed.md row raised by frontend-reviewer on forge-et-fe#474, which Nanndish, owner of Rev 100, was asked to decide.
  • Scope: §5, one clause. No token or code changed.

Rev 115 — 2026-11-11 — §5: the pill tab list’s fill, and how a pill tab shows it is selected

Numbered with python3 .claude/lib/next-id.py ds-rev.

  • Changed — §5 Tabs / segmented control: the pill variant names its group’s fill, surface/accent (neutral-100, #f4eee2), and its selected tab, surface/card with the card shadow and text/primary. The tab text, text/secondary (#6e5f4e), is 5.33:1 on the fill.
  • Changed — §5 Selected: the clause “or accent/gold pill background” is removed; a pill tab has never been selected by a gold pill (forge-et-fe src/ui/shadcn/tabs.tsx draws it bg-card).
  • Why: the row named no group fill, and TabsList used bg-muted, which the revamp maps to neutral-50, the page background, so only the selected tab was visible. The current prototype draws the group shaded; the lead decided on 2026-11-11 that the app follows it (the .forge/owed.md row raised by F34-c wave 1’s design vision pass). frontend-reviewer on forge-et-fe#506 found both rows’ gaps.
  • Scope: §5, two rows. No token changed. Implementing code: forge-et-fe#506 (bg-muted → bg-accent). The record page’s tabs keep their own transparent strip, and the inbox uses the line variant.

Rev 116 — 2026-11-12 — §6: the saved views row on the account, lead and contact lists (F32-d); §5: tabs that overflow

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-12, which printed Rev 116: Rev 115 is held by an open harness PR. The F32-d-WI-3.2 plan, written before that, expected Rev 114.

  • Changed — §6 Data table, Saved views: the row records the built views row: its place between the page header and the data bar (the lead list: between the header and the status pills); a manual pill tab list named Saved Views whose one panel is the list card; the order (the default view, own views, shared views); the Shared, Shared by and Changed marks as secondary Badges; the long-name tooltip; the overflow into More Views with the default and open tabs kept; the actions slot at the inline end, on its own line only when the tab list’s minimum and the actions cannot share the row; the data states and their copy; view= and columns= in the URL and what Changed compares; and the gone, dropped-filter and unreadable notices.
  • Added — §5 Tabs / segmented control: one sentence: a row of tabs that can outgrow its width moves the rest into a More Views menu after the list and never moves the selected tab.
  • Casing: §9 (Rev 90) — Title Case for the default tabs (All Accounts, New Leads, All Contacts; the spec’s All accounts read in §9’s casing), More Views, Retry and the tab list’s name; sentence case for the marks, the notices and the announcements.
  • Why: F32-d FR-V7, FR-V10, FR-V11, FR-C3 and NFR-1 to NFR-5 (spec Rev 5): a list’s saved views are opened from a row of tabs, the open view is in the URL, and the row has its own data states.
  • Decision: Tharinda (the lead), 2026-11-12, at the F32-d-WI-3.2 plan approval (that plan’s Notes Q-1 to Q-4): the row above the data bar in the pill variant (Q-1), the open view’s ⋯ menu beside its actions rather than on its tab (Q-2, spec Rev 5), leaving a Changed view without a question (Q-3), and the unreadable view’s wording (Q-4).
  • Scope: §6, one row; §5, one sentence. No token changed and no icon concept added (More Views uses expand). Implementing code, in forge-et-fe (F32-d-WI-3.2): src/ui/filters/ViewsRow.tsx and viewTabsFit.ts, src/lib/listViews/ (the saved-view reads, the URL rules, the adapter type and useListView), the three adapters and screens in src/features/accounts/ and src/features/leads/; the current prototype draws the row on the three lists (prototypes/crm-current/). The dialogs, the tab’s ⋯ menu and Save View are F32-d-WI-3.3’s.

Rev 117 — 2026-11-12 — §6: the Email folder picker says a subfolder’s parent after its count

Numbered with python3 .claude/lib/next-id.py ds-rev.

  • Changed — §6, the Email folder picker below bp/laptop (Rev 86): a subfolder’s item is named “ unread, in ” (“Ceylon 2 unread, in Buyers”), where it was “, in ” before the count. The parent stays visually hidden; the visible text, the name and its count, is one run of the item’s name (WCAG 2.1 SC 2.5.3, Label in Name). An item with no unread mail is “, in ”, as before.
  • Why: BUG-401: axe’s label-content-name-mismatch failed the subfolder item, because the hidden “, in Buyers” sat between the visible “Ceylon” and “2”.
  • Scope: §6, one rule. No token changed. Implementing code: forge-et-fe#518 (src/features/email/FolderPicker.tsx).

Rev 118 — 2026-11-12 — §6: the saved views’ actions, ⋯ menu, dialogs and write notice (F32-d)

Numbered after Rev 116 (this feature’s, on main) and Rev 117, which forge-et-harness#1315 holds; python3 .claude/lib/next-id.py ds-rev printed Rev 118 on 2026-11-12.

  • Added — §6 Data table, Saved views: the actions slot (which actions each caller gets and their order), the open view’s ⋯ menu in the slot rather than on its tab, the Save View / Save as New View, Rename View and Delete ? dialogs (frames, fields, the share sentence, the Pipedrive Owner line), where each refusal shows and how a stale version is reloaded, the write notice under the row for the writes with no dialog, the toasts, and where focus goes after each action.
  • Stated, not changed — §5 Modal: the save and rename dialogs hold one field and close without asking when a name has been typed, as CustomFieldDialog and ChangeOwnerDialog do; their focus opens on the frame’s ✕, as on every RecordEditDialogFrame dialog (Biome’s a11y rules forbid autoFocus).
  • Casing: §9 (Rev 90, Rev 107) — Title Case for the buttons (Save View, Save Changes, Save as New View, Reset, Retry, Reload, Reload View, Cancel, Rename View, Delete View), the menu items (Rename, Share, Stop Sharing, Delete), the dialog titles, the Name label and its Enter Name placeholder; sentence case for the share sentence, the descriptions, the messages, the notices and the toasts.
  • Why: F32-d FR-V3, FR-V4 and FR-V8, AC-5b, AC-9, AC-10, AC-14c and AC-21b (spec Rev 5): a user saves, changes, renames, shares and deletes views from the views row.
  • Decision: Tharinda (the lead), 2026-11-12, at the F32-d-WI-3.3 plan approval (that plan’s Notes Q-1 to Q-6): Share and Stop Sharing act at once (Q-1); Save Changes acts at once (Q-2); the one-field dialogs close without asking (Q-3); Reload View opens the saved version as a new history entry and the rename dialog’s Reload keeps the typed name (Q-4); Save Changes saves what the list shows (Q-5); and every string the work adds (Q-6).
  • Scope: §6, one row extended. No token changed and no icon concept added (the slot uses save, undo and add; the dialogs cancel, save, edit, delete and refresh; the notice retry and refresh). Implementing code, in forge-et-fe (F32-d-WI-3.3): src/ui/filters/ViewActions.tsx, SaveViewDialog.tsx, RenameViewDialog.tsx, DeleteViewDialog.tsx; src/lib/listViews/ (savedViewsApi.ts’s writes, savedViewRefusals.ts, savedViewsMutations.ts, viewActionSet.ts, useViewWrites.ts); the three screens. The current prototype draws the actions and dialogs on the three lists with the built test ids (prototypes/crm-current/).

Rev 119 — 2026-11-12 — §6: the saved views row below 768px, and tabs at their natural width (F32-d)

Numbered after Rev 118 (this feature’s, on feature/F32-d-wave-3); python3 .claude/lib/next-id.py ds-rev printed Rev 118 on 2026-11-12, before that revision was renumbered from 117.

  • Changed — §6 Data table, Saved views: below 768px, More Views moves to a line of its own, the tab list is capped at the row’s width, the default tab keeps its whole name, and the open tab’s marks are hidden visually but kept in its accessible name and tooltip, so its name is cut to the room left. At every size each tab is drawn at its natural width, the width the measuring copy gives fitTabs, and the measuring copy adds nothing to the page’s width.
  • Why: F32-d AC-20 and NFR-2 (no horizontal page scroll at 320px). WI-3.4’s browser run found every list page scrolling sideways once views existed (the measuring copy widened <main>), the open tab and the default tab wider than the row at 320 with a view open, and More Views drawn over a two-mark open tab at 1024 and 1280 (the pill trigger’s flex-1 stretched the tabs past what fitTabs measured).
  • Decision: Tharinda (the lead), 2026-11-12 (the F32-d-WI-3.2 plan’s ## Notes): More Views on its own line and the marks hidden visually below 768px, 768px and up unchanged. Drawing the tabs at their natural width carries out WI-3.2 Decision 9 and needed no new decision.
  • Scope: §6, one row. No token changed and no icon concept added. Implementing code, in forge-et-fe on feature/F32-d-wave-3: c4e19d4e, b335209c and 28320643 (src/ui/filters/ViewsRow.tsx, viewTabsFit.ts and their tests). 320px is reflow support, not a designed layout (PRD § Accessibility), so the current prototype, drawn at 768px and up, is unchanged.

Rev 120 — 2026-11-13 — §9 The capture app: the tab bar in the centred column, no side menu, and the failure headings as messages

Numbered with python3 .claude/lib/next-id.py ds-rev.

  • Changed — §9 The capture app, the column: from bp/tablet up the bottom tab bar’s row joins the header row and <main> in the layout/capture-column-max column, with the bars spanning the viewport, and the shell has no side menu at any width. The column’s width and the bp/tablet condition are unchanged.
  • Added — §9 The capture app, the shell’s failure screens: their headings (That page doesn’t exist., Couldn’t load this page.) are messages, in sentence case; their buttons are labels in Title Case (Back to Leads, Reload the Page), and the not-found page’s title is Page Not Found (Rev 90, Rev 105; the decision .forge/owed.md’s casing row asked the first F36 PR to record).
  • Why: the capture app’s centred column at every width is this section’s rule and F36-a NFR-1’s (“desktop (≥ 1024px, the centred column)”), and the design system ranks above the prototype, whose desktop drew a side menu; F36-a-WI-1.2 builds the header and tab bar at every width and redraws pwa-current/ to match (plan Decision 11, under Nanndish’s overnight delegation of 2026-11-12, for his review). A desktop side menu later would be a revision of this rule, tracked in .forge/owed.md (“Decide the capture app’s desktop layout beyond the centred column”).
  • Scope: §9, two rules. No token changed. Implementing code: forge-et-pwa F36-a-WI-1.2 (src/app/AppLayout.tsx, src/app/TabBar.tsx, src/app/RouteErrorElement.tsx, src/app/NotFoundRoute.tsx); prototype: pwa-current/source/src/components/nav.jsx, App.jsx.

Rev 121 — 2026-11-13 — §9 The capture app: the selected tab is a semibold label, with no bar above it

Numbered with python3 .claude/lib/next-id.py ds-rev.

  • Added — §9 The capture app, the tab bar’s selected tab: its icon and label are accent/gold-deep, its label semibold (type/button’s weight), with aria-current="page" and no bar or line above, below or beside it. §5 Selected’s gold bar does not apply to this tab bar. Hover stays the surface/hover wash.
  • Replaces: the 3px border-width/selected accent/gold-deep bar along the selected tab’s top, which forge-et-pwa#128’s review had added (F36-a-WI-1.2 plan deviation 8). forge-et-pwa’s theme-crm.css no longer declares --et-border-width-selected, which only that bar used.
  • Why: Nanndish’s keyboard walkthrough of forge-et-pwa#128 on 2026-11-13: there should be no line above the selected item in the tab bar. The selected and unselected label colours are about 1.04 : 1 apart, so colour alone fails WCAG 1.4.1; Nanndish chose the semibold label as the cue that does not depend on colour, over a pill behind the icon.
  • Scope: §9, one rule. No token added; --et-border-width-selected leaves the capture app only (the CRM keeps border-width/selected). Implementing code: forge-et-pwa a643164 on feature/F36-a-wave-1 (src/app/TabBar.module.css, src/ui/styles/theme-crm.css, src/ui/styles/themeCompleteness.test.ts); prototype: pwa-current/source/src/components/nav.jsx, pwa-prototype.html rebuilt, and the screenshots re-taken with screenshots/capture.mjs.

Rev 122 — 2026-11-13 — §9 The capture app: the camera surface, its tokens, and the toast above the tab bar

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 121 on 2026-11-13; renumbered Rev 122 on 2026-11-14, when it reached a branch beside the selected-tab revision (forge-et-harness#1379), which had taken Rev 121.

  • Added — §9 The capture app, the camera surface: no control sits on the live camera view; the hint chip, the one element drawn over it, sits on a solid --et-capture-camera-control backing and draws --et-capture-camera-on; the four capture-only colour tokens, their values and the contrast themeContrast.test.ts measures; the panel’s size tokens; and the camera-off panel’s content in each mode.
  • Added — §9 The capture app, the toast: §5’s Toast, placed above the bottom tab bar, with its Dismiss ring in the fill’s paired text colour and its announcement in a live region mounted for the app’s whole life.
  • Why: F36-a NFR-2 and AC-36 (contrast on the camera view), FR-C1 to FR-C4 (the card camera, the badge reader, Choose a Photo), and design-system §5 Toast (“every success is a toast”). The screens accepted on 2026-11-12 draw every control below the panel, so no camera-surface focus ring exists to measure; the spec revision that says so is owed (.forge/owed.md).
  • Decision: Claude under Nanndish’s overnight delegation of 2026-11-12, for his review (F36-a-WI-2.2 plan Decision 11, deviations 2 to 7). The colour values are read from the prototype’s capture.jsx (the panel’s #1a120b and #2c2117 stripes); the chip’s backing is the prototype’s 50 % black made opaque.
  • Scope: §9, two rules; four colour tokens and seven layout tokens added, in capture.css only, so the CRM and the shared tokens.css are unchanged. Implementing code: forge-et-pwa F36-a-WI-2.2 (src/ui/styles/capture.css, src/features/capture/CameraPanel.tsx, src/features/capture/CaptureRoute.tsx, src/ui/toast/Toaster.tsx); prototype: pwa-current/source/src/screens/capture.jsx, App.jsx.

Rev 123 — 2026-11-14 — §9 The capture app: the not-sent states, Refused, and signing out with captures not sent

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 123 on 2026-11-14.

  • Changed — §9 A failed upload is a set of states: Not sent names where the list and the count are (Not Sent · on This Phone on Capture; a tone/notice banner with View on Leads), that a capture sent online and awaiting its first answer is not listed, and the kept toast; Sending puts Send Now on the list’s label row, unavailable with Sending needs a connection. while there is no connection, and makes the sent count a toast (2 captures sent.); the Failed row is renamed Refused, its Try again written Try Again (§9 casing), and says a refused capture stays until the rep removes it. The rest of each row’s wording is kept.
  • Changed — §9 Sign-in and sign-out are the CRM’s: its last sentence (“What a sign-out does to captures not yet sent is F36-a’s to settle”) is replaced by the rule: Sign Out? on Settings with the count, Cancel, Sign Out and Keep Them and Send Now online; offline, Sign Out and Keep Them unavailable with Signing out needs a connection.; on No Access, a count line and Sign Out unavailable offline; a sign-out never deletes a capture.
  • Added — § Status indicators: the row Capture kept on the phone — not sent / sending / refused (tone/notice ring, tone/neutral half-filled, tone/danger solid; provisional).
  • Why: F36-a FR-R1 to FR-R3 and AC-16 to AC-19, with AC-18 as F36-a spec Rev 3 settles it against FR-A6 (a sign-out the server does not confirm keeps the rep signed in, and offline it confirms none). Refused matches the status label the row shows; Failed named no label the rep sees.
  • Decision: Claude under Nanndish’s overnight delegation of 2026-11-12, for his review (F36-a-WI-2.3 plan Decisions 10 to 13, deviations 1 to 9; the Refused rename and the Hold Sending demo switch are listed in that plan’s ## Notes).
  • Scope: §9, two rules, and one status row. No token added. Implementing code: forge-et-pwa F36-a-WI-2.3 (src/features/capture/NotSentList.tsx, src/features/leads/NotSentBanner.tsx, src/features/settings/SignOutPrompt.tsx, src/features/auth/NoAccessRoute.tsx, src/ui/StatusIndicator.tsx, src/ui/Modal.tsx); prototype: pwa-current/source/src/screens/capture.jsx, today.jsx, settings.jsx, App.jsx, context/connection.jsx, pwa-prototype.html rebuilt, and the screenshots re-taken with screenshots/capture.mjs (new phone/83–86).

Rev 124 — 2026-11-15 — §9 The capture app: the sheet and the campaign-first Plan; § Status indicators: the campaign state

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 124 on 2026-11-15.

  • Added — §9 The sheet: the capture app’s bottom-sheet form of the CRM’s Sheet (§6’s Folders drawer, Rev 110) — title, ✕, Esc, focus back to the opener — anchored to the bottom edge below bp/tablet (top corners radius/xl, at most 85% of the viewport’s height) and a centred layout/dialog-sm dialog from it, on the native <dialog> with showModal(); its body scrolls inside, focus moves to its title on open, and a success while it is open is also said in its own status line.
  • Added — §9 The campaign comes first on Plan: the card for a running or upcoming campaign, Plan Your Next Show with the Last Campaign row, View Plan and Archive for an ended one, Plan a Show or Plan Your First Show with none; the picker grouped Running, Upcoming, Ended with Edit, Archive and the collapsed Archived (N) list; the state from the server, the day count from the phone; choosing needs no connection, every write needs one.
  • Added — § Status indicators: the row Campaign state — upcoming / running / ended, on the Sale state row’s tones and shapes (tone/neutral ring, tone/positive half-filled, tone/neutral solid; provisional).
  • Why: F36-a FR-P1, FR-P2 and FR-L7, AC-26 and AC-35. One look per pattern (.forge/lessons.md L-254): a campaign’s three states are a sale’s, so they reuse its mapping rather than add a second one; the sheet follows the CRM’s existing Sheet rather than adding a pattern.
  • Decision: Claude under Nanndish’s overnight delegation, for his review (F36-a-WI-3.3 plan Decisions 14 and 15, deviations 1 to 13); Tharinda accepted the bottom sheet and the campaign-state row on 2026-11-13 (that plan’s ## Notes, The lead’s acceptance).
  • Scope: §9, two rules, and one status row. No token added. Implementing code: forge-et-pwa F36-a-WI-3.3 (src/ui/Sheet.tsx, src/features/plan/, src/features/capture/CampaignLine.tsx, src/lib/campaign/); prototype: pwa-current/source/src/components/campaign-sheet.jsx, screens/plan.jsx, screens/capture.jsx, lib/campaigns.js, pwa-prototype.html rebuilt, and the screenshots re-taken with screenshots/capture.mjs (new phone/74a, 75a, 78, 79).

Rev 125 — 2026-11-15 — §9 The capture app: the main area scrolls above the tab bar

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 125 on 2026-11-15.

  • Changed — §9 Shell chrome: the shell fills the viewport and <main> is its only vertical scroll region, between the fixed header and the bottom tab bar; a route change starts <main> at its top.
  • Changed — §9 How the capture app implements the body type and the column: <main> spans the viewport and the screen’s column inside it takes the 480px cap and the gutter, so a wheel or a drag beside the column scrolls <main>; the header, connection bar and tab bar rows line up with the column for any safe-area insets, and from bp/tablet up <main> reserves its scrollbar’s width on both sides (scrollbar-gutter: stable both-edges) so the column stays centred where scrollbars take space. The document itself does not bounce (overscroll-behavior-y: none on html and body). Before, the document scrolled and the tab bar was sticky, so it could cover the control at the bottom edge of a long screen until the page was scrolled.
  • Why: axe’s target-size rule failed whichever control the sticky bar covered, by page length and screen size. It was accepted twice as an exemption (Submit for Research, F36-a-WI-2.2; the Not Sent buttons, WI-2.3), and the plan list (WI-3.4) made an exemption per control unworkable. The CRM’s shell already scrolls its main area (one look per pattern, .forge/lessons.md L-254).
  • Decision: Nanndish, 2026-11-15 (.forge/owed.md, “Make the capture app’s main area scroll above its tab bar, and drop the two tab-bar exemptions”). Both exemptions are removed from forge-et-pwa e2e/support/axeExemptions.ts in the same change.
  • Scope: §9, one rule. No token added. Implementing code: forge-et-pwa src/app/AppLayout.tsx, AppLayout.module.css, TabBar.module.css and what relied on the document scrolling, on feature/F36-a-wave-2 (forge-et-pwa#132).

Rev 126 — 2026-11-15 — § Status indicators: the price broadcast (F37-a)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 126 on 2026-11-15.

  • Added — § Status indicators, two provisional rows: Price broadcast — the batch’s status beside Send prices to customers on the Pricing screen (Sending prices — <sent> of <total>, tone/neutral half-filled; Prices sent to <sent> of <total> customers, tone/positive solid; … — <n> not sent, tone/notice ring; Stopped — …, tone/neutral solid); and Price broadcast customer — each customer’s state in the results dialog, from Waiting to Stopped.
  • Why: the F37-a spec (FR-U4, FR-U5): the PRD names no batch states, so the labels, tones and shapes are this project’s proposal, using only §2’s status tones (there is no tone/info) and §5’s solid / ring / half-filled rule. Not known takes tone/notice because the email may have gone out; Not sent takes tone/danger because it did not.
  • Decision: Tharinda, 2026-11-15, with the F37-a spec.
  • Scope: § Status indicators, two rows. No token added. Implementing code: the F37-a waves in forge-et-fe.

Rev 127 — 2026-11-15 — §9 The capture app: the existing-client check’s region and its two match colours

Numbered with python3 .claude/lib/next-id.py ds-rev on 2026-11-15 against origin/main, where Revs 122–126 are and feature/F36-d-wave-1 does not yet have them.

  • Added — §9 The capture app, The existing-client check’s region: its place under the read badge on Capture, its five looks (checking and pending on surface/card-warm; Already in the CRM on capture/match-bg inside capture/match-border, with a building, person or people icon in accent/gold-deep; not found on surface/card with the sparkle icon; Check failed on tone/danger with Try Again), one role="status" element kept from Checking… to the answer with the action outside it, and the six-line loading height (measured: the account answer is 142px at 390px).
  • Added — two capture-only tokens, declared once in forge-et-pwa’s capture.css: capture/match-bg (--et-capture-match-bg, #f4eee2) and capture/match-border (--et-capture-match-border, accent/gold-deep at 35%). text/primary (13.6 : 1), text/secondary (5.3 : 1) and accent/gold-deep (5.1 : 1) are measured on the fill.
  • Why: the prototype draws Already in the CRM on its accent fill (crm-match.jsx, screenshot 44), and no theme token holds it in the capture app: theme-crm.css points the quiet surfaces at the muted canvas, which the pending state uses, so the account answer would have looked like the pending one (F36-d WI-1.2 plan Decision 8). Contact-only and several take the account’s look, since FR-U1 files all three under Already in the CRM.
  • Departs from the prototype in: 14px lines (the capture app’s floor) where crm-match.jsx draws 12–12.5px, and a loading box that keeps the answer’s height where the prototype’s is one line (F36-d FR-U8); both are .forge/owed.md rows to draw into pwa-current. The not-found wording is F36-d FR-U1’s (Not found among the accounts you can see), not New to the CRM.
  • Scope: §9, one region. Implementing code: forge-et-pwa on feature/F36-d-WI-1.2-badge-check (src/ui/CustomerCheckRegion.tsx, src/ui/CustomerCheckRegion.module.css, src/ui/icons.tsx, src/ui/styles/capture.css, src/ui/styles/themeContrast.test.ts, src/ui/styles/captureStyles.test.ts). The prototype drawings of the states it does not show are F36-d-WI-1.3’s.
  • Added 2026-11-16 — the retry (F36-d WI-1.2 plan Rev 2, Nanndish’s option (a)): while Try Again’s request runs, Check failed stays on screen with Try Again busy and focused, not Checking…. When the retry’s answer replaces it, focus moves to the region, a section named by its title with tabIndex={-1}. A retry that fails again keeps Try Again and its focus. Code: forge-et-pwa 716f0ca on feature/F36-d-wave-1. pwa-current’s crm-match.jsx still draws the retry as Checking… (.forge/owed.md).

Rev 128 — 2026-11-13 — §9 The capture app: research and ranking on the plan, and the research notice (F36-c)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 121 on 2026-11-13; renumbered Rev 128 on 2026-11-16, when main had reached Rev 126 and open PRs held Rev 127.

  • Added — §9 The capture app, Research and ranking on the plan: the plan card’s states (tier and score when ranked; one type/meta line and no score otherwise), and the booth page’s: §5 AI provenance’s four elements once under the visit box with the chip AI RANKED, Why Visit, Recommended Next Action, and the Company Snapshot as findings with a source link each, in place of the drawn paragraph, Talking Points and Sources list.
  • Added — §9 The capture app, The research notice: an icon and the sentence in one box, tone/neutral for information and tone/notice for a failure, with Research Again as a text action under the sentence, lined up with it. Dinil judged the first drawing’s full-width outline button below the box clumsy (2026-11-13), and a text action beside the sentence squeezed it to four lines at phone width.
  • Why: F36-c FR-PL1, FR-PL3 and decision D-13 change the accepted plan screens; the prototype-first rule (.forge/design/prototypes/README.md) draws them before F36-c-WI-1.4’s plan is approved (owed.md).
  • Scope: §9, two rules. No token changed. Prototype: pwa-current/source/src/screens/plan.jsx, components/exhibitor-detail.jsx, components/common.jsx (AiProvenance), lib/leads.js, lib/api.js, demo/store.js, with re-taken screenshots. Implementing code: forge-et-pwa F36-c-WI-1.4.

Rev 129 — 2026-11-16 — §9 The capture app: research on Leads, removing what was found about a person, and the notifications (F36-c)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 129 on 2026-11-16.

  • Added — §9 The capture app, Research and ranking on Leads: the To Review row’s states (ranked, researching, and not ranked as one text/secondary line with no ring), the Completed row, the Updating live pill, and the lead page’s: the provenance under the booth note (from: public web search and the booth note or from: the booth note and the card), the Company Snapshot with the Role first, the nothing-found and not-enough-detail lines, the research notices (pending, not researched, failed) and Researching this lead…, the person removal with its dialog and the removed line, the card-read check with Edit Details as a text action, and Reject and Convert to Lead in every state.
  • Added — §9 The capture app, Notifications: the bell, the sheet with its 44px group rows and its kinds’ tones (Converted tone/positive), its loading, refreshing, empty, couldn’t-load, couldn’t-refresh and no-connection states, the Ready to review notice for one lead and for several, the capture toast’s wording and the Leads tab badge.
  • Changed — §9 The research notice: its text action also serves Edit Details under the card-read check and Remove What Was Found (in tone/danger) under the Role.
  • Replaces (prototype): on the lead’s page, the POC’s summary paragraph, Pain Points and Sources list, its Reading the card and researching… box, its recapture failure sentence and the outline Edit Details button beside the card-read sentence; on the To Review row, the Failed badge and its warning sentence; in the sheet, Converted to the CRM in primary and a rejected item’s reason; on the notice, the View button (the card is the tap target — Dinil, 2026-11-16, F36-c spec Rev 4) and the first lead’s name and more for several.
  • Why: F36-c FR-LD2, FR-LD5 to FR-LD8, FR-NT7 to FR-NT9 and decision D-13 change the accepted Leads and notification screens; the prototype-first rule (.forge/design/prototypes/README.md) draws them before F36-c-WI-2.4’s and WI-2.5’s plans are approved (owed.md). Each change was looked at and accepted by Dinil, screen by screen, on 2026-11-16.
  • Decision: Dinil, 2026-11-16 (the drawings, the text-action Edit Details, Remove What Was Found kept in the capture app as the only way to remove a rejected lead’s person finding, and the notice without View).
  • Scope: §9, two rules added and one widened. No token changed. Prototype: pwa-current/source/src/components/lead-row.jsx, lead-detail.jsx, exhibitor-detail.jsx (CompanySnapshot takes children; ResearchNotice exported), notifications-bell.jsx, ready-notice.jsx, screens/today.jsx, screens/settings.jsx (a Notifications demo state), context/connection.jsx, App.jsx, lib/api.js, demo/store.js, with re-taken screenshots (phone/10a, 21, 21b–21g, 30–30e, 31, 32, 32a). Not drawn: the lead page at waiting_for_card, because F36-b’s card-reading panel is not in the prototype yet. Implementing code: forge-et-pwa F36-c-WI-2.4 and WI-2.5.

Rev 130 — 2026-11-16 — §6: the Scheduled list in the inbox’s frame, and its not-connected state (F20-g)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 130 on 2026-11-16.

  • Changed — §6 Two-pane list + detail, the Scheduled list (/email/scheduled): it draws the inbox’s header — the title Email and its line, then Mailbox Settings, Refresh and Compose in the inbox’s places — and, while the mailbox is usable, the inbox’s data-bar row with the search box’s room kept empty (hidden and inert), so moving between the inbox’s folders and Scheduled moves nothing above the panes. Scheduled is named by the pane’s current entry, the Folders button and the table’s caption. From bp/laptop the folder pane is a card of its own and the list is the §6 List screen table card beside it (no side padding, as tall as its rows), the two with the panes’ gap between and their tops level.
  • Added — §6, the not-connected state: on /email, the not-connected prompt carries a Scheduled outline button below its next-step button (stacked, so the next-step button does not move when it arrives), with the folder entry’s icon, count and failed dot, when the user has a scheduled, failed or uncertain email; on /email/scheduled, a card above the list says Your mailbox is not connected. Reconnect it to send these emails. with the next-step button, and a failed row’s ⋯ menu offers only Dismiss.
  • Why: F20-g spec Rev 4 (FR-V4): the emails that fail when the mailbox is not usable must stay reachable; and Dinil found the list screen’s own header made the page jump against the inbox’s other folders, and the list read as part of the pane when it shared the pane’s card.
  • Decision: Dinil, 2026-11-16, looking at the built screens locally.
  • Scope: §6, one sentence group added to Two-pane list + detail, marked “(Rev 130)”. No token changed. Prototype: crm-current/ draws it in a follow-up (owed.md, “Draw F20-g Rev 4’s Scheduled changes in the current CRM prototype”). Implementing code: forge-et-fe branch feature/F20-g-scheduled-access.

Rev 131 — 2026-11-16 — § Status indicators: the price broadcast status in the singular (F37-a)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 131 on 2026-11-16.

  • Changed — § Status indicators, the provisional Price broadcast row (Rev 126): the label that ends in the noun reads it in the singular when the total is one — Prices sent to 1 of 1 customer, and Prices sent to <sent> of <total> customers otherwise. It is the row’s only label that ends in customers; the other three (Sending prices — <sent> of <total>, … — <n> not sent, Stopped — …) carry no noun after the total. Tones and shapes unchanged.
  • Why: the built status (F37-a-WI-1.5, forge-et-fe priceBroadcastResultsModel.ts batchStatus) writes customer for a total of one, as its live region’s end text does (Finished: sent to 1 of 1 customer); the row read customers for every total.
  • Decision: Tharinda, 2026-11-15, with the F37-a-WI-1.5 plan (its ## Notes item 3).
  • Scope: § Status indicators, one row. No token changed. Prototype: crm-current/ draws the singular (F37-a-WI-1.7’s correction to the built screens). Implementing code: forge-et-fe F37-a-WI-1.5.

Rev 132 — 2026-11-16 — §2 text/muted’s large-text sizes in pixels, and Try Again in place of Retry (BUG-399, BUG-447)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 132 on 2026-11-16.

  • Corrected — §2 text/muted: WCAG 2.1 SC 1.4.3 states large text in points: 18pt, or 14pt at weight 700. In CSS pixels that is 24px, or 18.66px bold. The row said 18.66px, or 14px bold, which read the points as pixels (BUG-399). Under §3’s scale this keeps type/stat (20px) and type/subhead (18px) off text/muted. forge-et-fe’s src/test/mutedTextBand.test.ts and the token comments use the same sizes.
  • Changed — the CRM’s button for trying a failed action again is Try Again, never Retry (BUG-447): §5 Alert / banner, Toast and Attachment tile, and §6 Column configuration and Saved views, now name it Try Again. The capture app (§9 The capture app) is unchanged. The rule itself is in §9’s One word for one action (Rev 133), whose Trying a failed action again item names Try Again; another section that still names Retry is read as Try Again.
  • Prototype: crm-current/crm-prototype.dc.html: every Retry label, comment and demo toast now says Try Again.
  • Why: the lead chose Try Again on 2026-11-16, because the CRM already used it most.
  • Decision: Tharinda, 2026-11-16.
  • Scope: §2 one row, §5 and §6 wording, and §9’s Trying a failed action again item. No token changed. Implementing code: forge-et-fe (BUG-399, BUG-447).

Rev 133 — 2026-11-16 — §5 Table, §6 List screen and §9: row actions are always a ⋯ menu; one word for one action (BUG-444 to BUG-446)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 133 on 2026-11-16.

  • Changed — §5 Table and §6 List screen: a list table’s row actions are always in the row’s ⋯ menu (RowActionsMenu), never buttons in the row, however few. The one exception is a table inside a dialog whose rows each have a single action (the Standards not in this round dialog’s Carry Forward).
  • Withdrawn — Rev 94’s exception “the auction-sales table … keep plain buttons in their last column”. It was written when that column held one Edit dates button; BUG-422 added Delete Sale beside it under the exception, which is how the Auction Sales table came to differ from every other CRM table (BUG-444). The table now has the ⋯ menu, pinned as Rev 94 pins the others.
  • Added — §9, One word for one action: creating a record reads New on the opening button and the dialog title and Create on the submit, wherever the dialog is opened from (BUG-446: Add a Sale, New Sale and Add Sale named one action); a field has one label on its forms and its column header (BUG-445).
  • Why: the lead found the Auction Sales table’s row buttons on 2026-11-16, and an audit of the Pricing page that day found the wording differences. Each followed an older screen or an exception no check covered, so the rule and a test now cover them.
  • Enforced by: forge-et-fe’s source test that fails a file under src/features using the plain actions cell (DATA_TABLE_ACTIONS_CELL) outside a short allow-list, and frontend-reviewer’s check of row actions and action wording.
  • Decision: Tharinda (lead), 2026-11-16.
  • Scope: §5 Table, §6 List screen, §9. No token change. Implementing code: the BUG-444 fix in forge-et-fe; crm-current draws the menu.

Rev 134 — 2026-11-17 — § Status indicators: the price broadcast status sits below the Pricing header’s buttons (F37-a)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 134 on 2026-11-17.

  • Changed — § Status indicators, the provisional Price broadcast row (Rev 126): the status sits on its own line below the Pricing screen header’s buttons, from their left edge and after them in the tab order, not beside Send prices to customers. For a user who may send prices, the line keeps its height from the first paint, empty while the batch is read and when there is none, so nothing below the header moves when the status arrives: the taller of one compact control and two text lines, at every width, since the label wraps at narrow widths.
  • Why: the status arrives after its read; beside the buttons it moved Import Weekly Prices under the pointer whenever the header wrapped (320px, possibly 768px; lesson L-208). Found by the forge-et-fe#552 wave review.
  • Decision: Tharinda, 2026-11-17 (F37-a spec Rev 5, FR-U5).
  • Scope: § Status indicators, one row. No token changed. Prototype: crm-current/ draws it below the buttons. Implementing code: forge-et-fe 74172406 (PricingActionsPlace’s status line).

Rev 135 — 2026-11-17 — §9 The capture app: the booth page after Research Again on a booth ranked from its list (F36-c)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 135 on 2026-11-17.

  • Added — §9 Research and ranking on the plan, a Booth page row, Ranked from the list row, research asked for again: after a successful Research Again on a booth ranked from its list row with its research pending, the tier and the score ring stay and the pending notice under the provenance becomes a brand box with a spinner, Researching this booth… (…exhibitor… with no booth code), with no action, until the booth is ranked again or its state changes. The lead page’s Research pending row already drew the same rule for a lead (Rev 129).
  • Why: it records F36-c FR-LD7 for the booth: a successful Research Again at ready with researchPending “keeps the tier and shows Researching this lead… under it”. WI-1.4 had kept the pending notice instead; its plan’s Rev 2 (2026-11-17, from the forge-et-pwa#146 review) changed the booth page to follow the spec, and this row is that change’s design-system record.
  • Decision: taken from the spec under Dinil’s standing answer for the overnight run of 2026-11-17 (spec first; .forge/plans/F36-c/F36-c-overnight-log.md N-4, WI-1.4 plan Rev 2); approved by Dinil Gamage (dinil-gamage) on 2026-11-17 with WI-1.4 plan Rev 2.
  • Scope: §9, one row added. No token changed. Prototype: pwa-current/source/src/components/exhibitor-detail.jsx (the box in place of the pending notice) and lib/api.js (Research Again on a pending booth keeps it ranked while the demo researches it), with the screenshot phone/88a-booth-research-requested added. Implementing code: forge-et-pwa BoothResearch.tsx and BoothDrawer.tsx (F36-c-WI-1.4, wave PR review fix A-I2).

Rev 136 — 2026-11-16 — § Status indicators: the captured lead’s outcome; §9 The capture app: the review’s wording and states (F36-a)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 130 on 2026-11-16; renumbered Rev 136 on 2026-11-17 when main was merged into the F36-a wave 4 harness branch (forge-et-harness#1448), because main already held Rev 130 to Rev 135 (F20-g, F37-a, F36-c).

  • Added — § Status indicators — the per-state vocabulary, Captured lead outcome (provisional): In CRM (tone/positive, solid) and Rejected (tone/neutral, ring), on a Completed row after its title and on the lead’s page under its company line, where the prototype drew a filled badge: §5 keeps a filled badge for a category and a dot with a label for a state (F36-a WI-4.2 deviation 4, as WI-3.3 deviation 4 did for the campaign state).
  • Changed — §9 Research and ranking on Leads (Rev 129): the Completed row’s outcome is that status indicator, not a badge, so the design system says one thing; F36-c’s ring beside it is unchanged.
  • Drawn with the build (prototype, F36-a WI-4.2 deviations 6 to 12): the booth note labelled Booth Note with a 1px border all round and no left bar (F36-c’s FR-LD5 adds · used in the research); Convert to Lead’s sentence becomes a lead in the CRM, with the booth note. and its Source as Trade Fair · , the CRM lead’s source and source detail; Reject Lead as the reject sheet’s button; No reason given; the converted panel naming the converter as the owner (Owner: you · converted 20h ago); the review’s running text at 14px; Capture in both nothing-exists states; the no-match lines with a full stop and Clear, named Clear search and filter; Show More Leads after fifty rows; and, behind the prototype’s No Connection switch, the search and chips unavailable with Search and filters need a connection. and every write on the lead’s page unavailable with Needs a connection.
  • Why: F36-a WI-4.2 builds Leads and the lead’s page (F36-a FR-L3 to FR-L7); the prototype is kept in step with the build (.claude/rules/plans.md § Required Sections). The frame changes (the lead’s page in the booth page’s drawer, Leads without the running-campaign bar, no Delete Lead) were drawn before the plan was approved and are recorded in .forge/design/prototypes/README.md.
  • Decision: decided by Claude, for Nanndish’s review, in F36-a WI-4.2’s plan (§ UI / Design Adherence, deviations 4 and 6 to 12), approved by Nanndish on 2026-11-16.
  • Scope: § Status indicators, one row added; §9, one row’s wording changed. No token changed. Prototype: pwa-current/source/src/components/lead-row.jsx (OutcomeIndicator), lead-detail.jsx, review-dialogs.jsx, screens/today.jsx, with re-taken screenshots. Implementing code: forge-et-pwa F36-a WI-4.2.

Rev 137 — 2026-11-18 — §8: the Settings page’s Records and Research sections, and the Lead Research page (F11-i)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 137 on 2026-11-18.

  • Added — §8 The page’s layout: the Records section (Custom Fields, built by F34-c and not recorded here until now) and the Research section after it (What the CRM looks up in public sources about a new lead.), holding the Lead Research card (the registry’s research glyph, Telescope), before Email. The In the prototype list gains Custom Fields and Lead Research.
  • Added — §8, A Settings page holding one setting: the Lead Research page (/settings/lead-research, on settings.lead_research.manage) is the pattern: one card with a §5 Switch labelled Search for the person named on a lead, its two explanation lines, Last changed by, saved when flipped and aria-disabled while it saves, and the four write outcomes — a success toast (Person search turned on. / off.); an inline notice for a change made elsewhere (Someone else changed this setting. The page now shows the current value.), held in an always-mounted polite status element above the card and cleared by the next flip, with no Dismiss; a failure toast with Dismiss for a refusal (The setting couldn’t be saved.) and for an unknown outcome, which re-reads (The change couldn’t be confirmed. The page now shows the stored value.). The data states: the labelled skeleton in the card, The setting couldn’t be loaded. with Try Again, and Couldn’t refresh — showing the last value. with Try Again above the card, the switch kept.
  • Drawn with the build (prototype, F11-i WI-1.2 deviations 1 to 8): the card title, breadcrumb and h1 Lead Research in Title Case (§9, Rev 90; the role editor keeps the catalog label Lead research); Try Again, not Retry (Rev 132); the card’s line under the h1 without its full stop (BUG-165); the Telescope glyph on the card, where the drawing had a magnifier; failure toasts with Dismiss that stay, and with no danger icon, as the built toast has none (§5 Toast, Rev 103); no 720px cap on the card, which takes the page’s content width as the Custom Fields card does; the conflict notice above the stale panel, because the notice is the always-mounted status element above the data region; and the date in Last changed by as formatInstantDate’s (Thu 12 Nov, the year only when not this year).
  • Why: F11-i WI-1.2 builds the page (spec FR-V1 to FR-V4); the prototype is kept in step with the build (.claude/rules/plans.md § Required Sections).
  • Decision: decided by Claude, for Dinil’s review, in F11-i WI-1.2’s plan (§ UI / Design Adherence, deviations 1 to 8), approved under Dinil’s overnight delegation on 2026-11-18; the casing and Try Again settled by spec Rev 2.
  • Scope: §8, one sentence changed and one added; the In the prototype list. No token or component changed. Prototype: crm-current/crm-prototype.dc.html — the leadResearch screen, _lrView, and the Lead Research card in the Settings landing. Implementing code: forge-et-fe F11-i WI-1.2 (src/features/leadResearchSettings).

Rev 138 — 2026-11-17 — §9 The capture app: the card-read check’s states and the card-reading rows; §5 AI provenance for a card read (F36-b)

Numbered with python3 .claude/lib/next-id.py ds-rev --count 3, which printed Rev 137 to Rev 139 on 2026-11-17; renumbered Rev 138 to Rev 140 on 2026-11-18, when Repo hygiene on forge-et-harness#1475 found Rev 137 already held (Rev 139 and Rev 140 are F36-b WI-3.3’s and WI-3.4’s).

  • Changed — §9 Research and ranking on Leads, the lead page’s Card-read check row: split into its states — card being read (a spinner, Reading the card…, the box aria-busy), card read (§5’s provenance row above the sentence), reading off, could not be read, could not be read just now, and badge — in one box and one tone, the icon naming the state, shown on a lead in To Review only, with Edit Details in every state and Read Again when the server allows a new read.
  • Added — §9, two To Review rows: a card being read (Reading the card… as the title with a spinner, or as the second line under a name or company already saved) and a card not read (Card not read over Add the details); and a lead-page row for a lead with neither a name nor a company: no Convert to Lead, and the status notice To convert this lead, add a name or a company with Edit Details. under the customer check. The Review row now says Convert to Lead needs a name or a company.
  • Added — §5 AI provenance, a Card read paragraph: the chip AI READ, Confidence <n>% and from: business card, <d MMM>, once, on a read card only.
  • Why: F36-b FR-U2 and FR-U3 give the card read these states, and F36-b WI-3.2 built them in forge-et-pwa (src/features/leads/cardRead/); the prototype is kept in step with the build (.claude/rules/plans.md § Required Sections). Rev 129 drew the box for a read card and a badge only.
  • Drawn from the app: the box takes the research notice’s values (WI-3.2 subtask 5’s recorded deviation), and the line beside the missing Convert to Lead has the one sentence F36-b WI-3.3 gave it in every state (WI-3.2 had first given each state its own sentence, replaced on the same branch before the wave ships).
  • Decision: decided by Claude, for Dinil’s review, in F36-b WI-3.2’s plan (§ UI / Design Adherence, Decisions 7, 8, 10, 11 and 14), approved by Dinil on 2026-11-16.
  • Scope: §9, one row changed into seven and three rows added, the Review row reworded; §5, one paragraph added. No token changed. Prototype: pwa-current/source/src/lib/card-read.js and demo/card-read-scenarios.js (new, ?cardRead=<state>), components/lead-detail.jsx, components/lead-row.jsx, demo/store.js, lib/api.js, with the screenshots phone/10c-leads-card-not-read and phone/20a–20d added and phone/20, 21, 31 and the other lead pictures that show the box re-taken. Implementing code: forge-et-pwa F36-b WI-3.2 (forge-et-pwa#149).

Rev 139 — 2026-11-17 — §9 The capture app: Edit Details and the card-read check’s edited marking; §5 AI provenance’s edited chip for a card read (F36-b)

Numbered with python3 .claude/lib/next-id.py ds-rev --count 3, which printed Rev 137 to Rev 139 on 2026-11-17; renumbered with Rev 138 above on 2026-11-18.

  • Added — §9 Research and ranking on Leads, a lead-page Edit Details row: the sheet’s provenance line, Enter a name, a company or both., the seven fields in order with Country a select of countries by English name (Choose a country first) and every field but Name and Company (optional), the CRM line, Cancel and Save Changes; Enter a name or a company. under Name and Company when both are blank; the status notice for a change made while the sheet was open; the toast Changes saved.
  • Added — §9, a Card-read check, edited row: Edited by you or Edited by in place of Check the details before converting. on a read card and a badge, after the sentence in the other states; on a read card only for a save made after the read.
  • Added — §5 AI provenance, the Card read paragraph: the edited chip AI READ · EDITED, the editor named in the sentence.
  • Changed — §9 The research notice: the text action is underlined on hover, with no fill, as forge-et-pwa builds it (WI-3.3 Decision 3 and deviation 8, the same as F36-c’s built Research Again).
  • Why: F36-b FR-E1, FR-E2, FR-E7 and FR-U3, which F36-b WI-3.3 built in forge-et-pwa (src/features/leads/lead/EditDetailsSheet.tsx, TextAction.tsx); the prototype is kept in step with the build. The prototype’s sheet had asked for both a name and a company, had no Country, and its labels were below the capture app’s 14px floor.
  • Decision: decided by Claude, for Dinil’s review, in F36-b WI-3.3’s plan (§ UI / Design Adherence, deviations 1 to 8, Decisions 3, 5, 12 and 14), approved by Dinil on 2026-11-16; the edited chip without BY YOU is that WI’s recorded deviation (its plan’s ### Failed Approaches).
  • Scope: §9, two rows added and one paragraph’s sentence changed; §5, one sentence added. No token changed. Prototype: pwa-current/source/src/components/lead-detail.jsx (EditLeadDialog, the box’s marking), lib/api.js (updateLead), demo/store.js (each lead’s country), with phone/23 and phone/24 re-taken and phone/23a-lead-edit-details-scrolled and phone/24a-lead-edited added. Implementing code: forge-et-pwa F36-b WI-3.3 (forge-et-pwa#150).

Rev 140 — 2026-11-17 — §9 The capture app: Read Again and the card still being read after 10 minutes (F36-b)

Numbered with python3 .claude/lib/next-id.py ds-rev --count 3, which printed Rev 137 to Rev 139 on 2026-11-17; renumbered with Rev 138 above on 2026-11-18.

  • Added — §9 Research and ranking on Leads, two lead-page rows: the card-read check for a card still being read after 10 minutes (the spinner kept, Reading the card… This is taking longer than usual., Edit Details and Read Again, from the server’s canReadAgain), and Read Again — after Edit Details, space/6 apart, wrapping at 320px, the toast Reading the card again., unavailable with Needs a connection. offline, its outcome messages in the one status notice under the box.
  • Changed — §9 The research notice: its list of text-action users gains Read Again.
  • Why: F36-b FR-U3 and FR-U5, which F36-b WI-3.4 built in forge-et-pwa (ReadAgainAction.tsx, useReadAgainOutcome.ts, the view reading-long); the prototype is kept in step with the build.
  • Drawn from the app: the space/6 gap between the two text actions is WI-3.4’s recorded deviation (CardReadPanel.module.css .actions { column-gap: var(--et-space-6) }; the text actions have no padding, so without it they touched); the prototype draws the actions without padding and 18px apart to match.
  • Decision: decided by Claude, for Dinil’s review, in F36-b WI-3.4’s plan (§ UI / Design Adherence, Decisions 2, 3, 6, 10 and 14), approved by Dinil on 2026-11-16.
  • Scope: §9, two rows added and one sentence changed. No token changed. Prototype: pwa-current/source/src/demo/card-read-scenarios.js (?cardRead=reading-long), components/lead-detail.jsx (the slow-read sentence, Read Again offline), with phone/20e-lead-card-reading-long added. Implementing code: forge-et-pwa F36-b WI-3.4 (forge-et-pwa#151).

Rev 141 — 2026-11-19 — §6 Saved views: no row without a view, Default, Save View beside Columns, the selected tab and the tooltip (F32-d Rev 6, BUG-488)

Numbered with python3 .claude/lib/next-id.py ds-rev --count 1, which printed Rev 141 on 2026-11-19.

  • Changed — §6 Data table, Saved views: the row is drawn only while the caller has a view to choose (one of their own or one shared with them), and not while the views are first read; a failed first read shows its line in the row’s place with no tabs; the notices and the status line stay in the page without the row; the default tab is Default on every list; Save View leaves the row’s actions slot for the data bar’s inline end, after Columns and at its height, shown while the default view is open, with or without the row, and the slot holds nothing with the default view open; the selected tab is filled primary with primary-foreground text, on the views row only; a tab has a tooltip only while its name is cut or its marks are hidden below 768px; focus goes to Save View when the row goes while focus is in it. §6 Column configuration says Save View follows Columns.
  • Why: F32-d Rev 6 (FR-V7, FR-V8, FR-V11, NFR-1), from Nanndish’s UI review list of 2026-11-19 (items 2 to 5), and BUG-488 (the selected tab barely differed from the others).
  • Decision: decided with Nanndish on 2026-11-19: only Save View moves (the open view’s actions stay on the views row), the row shows for a view shared with the caller, the default tab is renamed Default, the selected tab takes the brand fill, and the tooltip stays for a cut name. Accepted the same day (forge-et-fe#586’s review, finding 8): for a caller with views, a first load moves the data bar and table down by the row’s height when row 1 answers, since holding that height while loading would move the page up for every caller with none (F32-d Rev 6).
  • Scope: §6 Saved views only; §5’s pill tabs elsewhere are unchanged. No token changed. Prototype: crm-current is updated in the forge-et-fe change that builds it (F32-d Rev 6, BUG-488, BUG-485).

Rev 142 — 2026-11-19 — §9 The capture app: iPhone and iPad install steps, and the Leads section switch without its outline (F36-a Rev 4, BUG-486)

Numbered after Rev 141 in the same change.

  • Changed — §9 Shell chrome: on iOS the install card’s fallback is a numbered list of steps, written for Safari and for the device the app is open on (an iPhone or iPod, or an iPad), in place of the one line Tap Share, then Add to Home Screen.; the card shows on the same devices and browsers as before.
  • Added — §9, The Leads page’s section switch: the To Review / Completed switch is drawn without the track’s outline; the Capture screen’s mode switch keeps it.
  • Why: Nanndish’s UI review list of 2026-11-19 (items 7 and 8); F36-a Rev 4 (FR-SC1, AC-7) and BUG-486.
  • Decision: decided with Nanndish on 2026-11-19: the steps show on iPhone and iPad only, under the card’s existing show and hide rules; the outline is removed on the Leads page only.
  • Scope: §9, one sentence changed and one paragraph added. No token changed. Prototype: pwa-current and its Settings and Leads screenshots are updated in the forge-et-pwa change that builds it.

Rev 143 — 2026-11-19 — §9 The capture app: the customer check on the lead’s page, the To Review row’s marker, and the convert dialog’s In the CRM row (F36-d)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 143 on 2026-11-19: main holds up to Rev 140, and open harness PR #1519 holds Rev 141 and Rev 142.

  • Added — §9 The existing-client check’s region, On the lead’s page (F36-d WI-2.3): the region’s place on every captured lead’s page; the foot line under an earlier answer (Checking again…, Checked {how long ago}, Check failed with Try Again) with its icons, tones and spacing; the three Customer check pending lines and their icons; and that Try Again’s busy state and focus apply under an earlier answer too.
  • Added — §9 The To Review row’s existing-customer marker (F36-d WI-2.4): §5’s Badge / pill shape on capture/match-bg with accent/gold-deep words and icon, its place after the name and the tier badge, and the contrast held by themeContrast.test.ts. No new token.
  • Added — §9 The convert dialog’s In the CRM row (F36-d WI-2.7, built from the plan file F36-d-WI-3.2-convert-link-row-plan.md): the fact’s words for each answer, the owner named and never you, the link check box (§5’s check box in a 44px row, icon/md in accent/gold, ticked when the dialog opens and when the offer changes, unavailable while the convert runs), and the link-refusal sentence as the status line above the action bar.
  • Changed in place after the wave PR review, 2026-11-19 (this revision is on the wave’s harness branch and not yet on main, so it is edited rather than followed by a new revision; Nanndish’s decisions in the review of forge-et-pwa#185):
    • On the lead’s page: E-2 is read once for each set of checked values and trigger, not for each copy of the lead, and a read that changes nothing shows nothing new (Wave-2 contract Rev 1, forge-et-pwa 31f7ea0). The offline Checked {how long ago} foot, which changes each minute, is drawn outside the live element, in the same place, so the minute’s change is not announced; Checking again… and Check failed stay inside it (6f3a7d8; element screenshots of the region at 320, 390, 768 and 1280px in Chromium are byte-identical before and after). Under an earlier answer, Try Again’s boundary, border/control, is held at 3 : 1 on capture/match-bg by themeContrast.test.ts (1ee4994).
    • The convert dialog’s In the CRM row: the row uses only an answer checked on the lead’s current values, and after a refused link the box is shown unticked for that same answer (Wave-3 contract Rev 2, 3e3e872). While the convert runs, the box’s row takes the not-allowed cursor and its label text/disabled (1ee4994).
  • Why: F36-d wave 2 builds the check on the lead’s page (FR-U3, FR-U8), the marker on To Review rows (FR-U4) and the link on convert (FR-U5, FR-U6, FR-L1). Each work item’s plan drafted its §9 text for the orchestrator, because an app-repo work item does not edit a harness document; the orchestrator wrote it at the wave’s Stage 12.
  • Departs from the prototype in: the busy Try Again under an earlier answer is not drawn (the prototype shows Checking again… there); the prototype draws Try Again as a pill indented to the text column, where the build puts the outline button at the box’s left edge; the lead page’s foot icon is icon/sm (16px) where the drawing has 14px, since §4 has no 14px icon token; and the convert dialog’s box is 18px, space/5 from a regular-weight label, in accent/gold, where review-dialogs.jsx draws 20px, 10px from a medium-weight label, in the primary button colour. Each drawing difference is a .forge/owed.md row owned by Nanndish. Against §5’s Disabled row, which fades a check box’s label to 55%, the unavailable link box’s label takes text/disabled, as the capture app’s other controls’ text does.
  • Decision: the region’s and the dialog’s text follow the approved F36-d WI-2.3 and WI-2.7 plans (approved by Nanndish on 2026-11-18) and the frozen Wave-3 contract (D-8, D-9). The marker’s look is for Nanndish’s decision (F36-d WI-2.4 plan Decision 4): a badge on a fill that §5 does not list is a revision the lead decides.
  • Scope: §9, three paragraphs added. No token changed. Prototype: pwa-current/source/src/components/crm-match.jsx (CrmMatchBadge, the lead-page region) and review-dialogs.jsx (ConvertDialog), with screenshots phone/10, 10b, 22 to 22h, 25 to 25d and 44h. Implementing code: forge-et-pwa on feature/F36-d-wave-2 — src/ui/CustomerCheckRegion.tsx and .module.css, src/ui/icons.tsx, src/features/leads/lead/LeadCustomerCheck.tsx (WI-2.3); src/features/leads/LeadRowCustomerSlot.tsx and .module.css, src/ui/styles/themeContrast.test.ts (WI-2.4); src/ui/Checkbox.tsx and .module.css, src/features/leads/lead/ConvertSheet.tsx, src/lib/customerCheck/convertRow.ts (WI-2.7); after the review, src/lib/customerCheck/useCustomerCheck.ts, src/features/leads/lead/LeadActions.tsx, and src/ui/CustomerCheckRegion.tsx and .module.css (31f7ea0, 3e3e872, 6f3a7d8), and src/ui/Checkbox.module.css and src/ui/styles/themeContrast.test.ts (1ee4994).

Rev 144 — 2026-11-19 — §9 The capture app: the iOS install steps’ type and place in the card (F36-a Rev 4)

Numbered after Rev 143, which forge-et-harness#1525 holds.

  • Changed — §9 Shell chrome: the iOS install steps are in the row’s secondary text, type/meta, not type/body as Rev 142 said, and sit on a line of their own under the row, lined up with the row’s text, so the icon tile stays level with the title.
  • Why: the review of forge-et-pwa#186 found that Rev 142’s type/body did not match the card as built or the prototype, and that the list inside the row’s text pushed the icon tile down to the middle of the card.
  • Scope: §9, one sentence changed. No token changed. Prototype: pwa-current already draws the list this way.

Rev 145 — 2026-11-19 — §5 Attachment tile’s states for a linked email’s files; §6 the Emails card, the reading dialog and the Linked marker (F20-f)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 145 on 2026-11-19.

  • Changed — §5 Attachment tile: in the reading view of an email linked to a record, a stored file is a ready tile with no wording that claims or denies a virus check, as §5 Attachment row already says for a file not scanned; the tile gains three states for a file that is not stored — Being saved, Too large to keep (with the file’s name and size) and Could not be kept — and when the email’s list of files could not be read, the single line Attachments could not be kept shows in place of the tiles.
  • Added — §6 Record page, Emails: the Emails card, a §5 Card of compact rows, on the lead page’s Notes and email tab in the side column after the Email card (the emails place after compose), its list scrolling inside its card from bp/laptop, and on the contact page after the notes (the emails place after notes); the reading dialog (shadcn’s Dialog, the linked records as §5 Badges each with Unlink, whose confirmation shows in place, and Reply closing the dialog before compose opens); and the inbox’s Linked marker, a §5 Badge with its text. The lead page’s card list under Notes and email names the new card.
  • Why: the F20-f spec (approved 2026-11-19): FR-7 and FR-15 (a linked email’s files are kept in the CRM, within a size limit, and some may not be kept), D-6 (no file is virus-scanned while scanning is off, so a stored file shows as a ready one), FR-16 (the lead and contact pages list the linked email, and an email opens in a dialog over the page) and FR-17 (the inbox shows what is linked).
  • Decision: Tharinda (lead), with the F20-f spec, 2026-11-19.
  • Scope: §5, the Attachment tile row; §6, the Record page bullet (one sentence on the lead page’s cards and a new Emails item). No token changed and no icon concept added. Prototype: crm-current gains the Emails card, the reading dialog, the Linked marker and the Link to Record picker in F20-f’s delivery.

Rev 147 — 2026-11-19 — §6 and §8: the rail’s count badge, the record pages’ card rule, header button sizes, the account list’s More Filters, and the Lead Research settings row (BUG-503 to BUG-507)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 147 on 2026-11-19.

  • Changed — §6 Two-pane list + detail (the Email folder rail, BUG-507): a tile’s count badge starts space/2 past the icon’s centre and grows toward the tile’s end, with space/2 inline padding, and a tile draws a count above 99 as 99+; before, the badge was pinned by its end and grew over the icon.
  • Changed — §6 Record page: the header’s actions are each the shadcn Button at the default size (BUG-503: the lead page’s Edit was sm and Archive the older src/ui button); the lead page’s Attachments card moves to the wide column, after Custom Fields, and one rule now covers the account and lead pages — the record’s own content in the wide column, short facts in the narrow one, ending with Tags then Shared with (BUG-505; F11-f Rev 15).
  • Changed — §6 List screen, More Filters: the account list’s row and popover (BUG-504): Region, Tag, Shared With Me and Show Archived move into More Filters, as on the Leads list; the filters wrap in their own group and the Columns / Save View cell keeps to the first line’s end. The Leads and contact lists keep one wrapping row for now (owed.md).
  • Changed — §8 A Settings page holding one setting: the Lead Research card is a settings row — the label leads, and On or Off and the switch sit at the row’s end (BUG-506).
  • Not changed — §5 Busy: BUG-508 (the icon drawn beside a busy button’s spinner) was a defect in how button.tsx applied Rev 83’s rule, not a change to the rule.
  • Why: Nanndish’s second UI review list of the CRM, 2026-11-19 (items 1 and 3 to 6).
  • Decision: decided with Nanndish on 2026-11-19, from the recommendations he accepted in the session: More Filters on the account list as on Leads; Tags before Shared with, which is last, with Attachments in the wide column on both pages; the settings-row layout with a state word.
  • Scope: §6 Two-pane list + detail, Record page (the header and the lead page’s cards) and List screen; §8, one sentence added. No token or component changed. Prototype: crm-current/crm-prototype.dc.html is redrawn in the same delivery — the rail badges, the account list’s More Filters, the lead’s Attachments card and the Lead Research row; the Settings landing’s Lead Research card also gains the page key it lacked, without which no demo role could open that page. Implementing code: forge-et-fe fix/BUG-501-crm-ui-fixes.

Rev 148 — 2026-11-19 — §9 The capture app: one line to install on iOS; §5 a field’s error has no icon (F36-a Rev 7, BUG-510)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 148 on 2026-11-20; drafted as Rev 145, which F20-f reached main with first (id-numbering rule 5).

  • Changed — §9 Shell chrome: on iOS the install card shows one line, In Safari, tap Share, then Add to Home Screen., the same on every iOS device, in place of Rev 142’s numbered steps for an iPhone and an iPad (and Rev 144’s place for them). When the card shows is unchanged.
  • Changed — §5 Form fields and validation, Errors: says that the message has no icon, in the CRM and the capture app alike. The CRM’s fields already draw none; the capture app’s Field drew an alert icon before the message, which BUG-510 removes.
  • Why: Nanndish, 2026-11-19, after seeing F36-a Rev 4 built: the card needs only a short message; and the capture app’s field errors should look like the CRM’s.
  • Scope: §5, one bullet; §9, one sentence. No token changed. Prototype: pwa-current’s Settings screen (its iPad demo and screenshot 82a removed, 82 retaken) and lead-detail.jsx’s field error (screenshot 24 retaken) are updated in the change that builds it.

Rev 149 — 2026-11-20 — §9 The capture app: its controls come from shadcn/ui, at its own sizes (AD #43)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 149 on 2026-11-20.

  • Changed — the build posture for the capture app: like the CRM since Rev 41 (AD #39), the capture app’s new and changed screens use shadcn/ui components (forge-et-pwa’s src/ui/shadcn, Radix UI underneath, Tailwind v4 classes mapped onto the --et-* names theme-crm.css declares). Its own sizes stay: every control at least 44 × 44px (layout/control-h), labels at the 14px working size and the body weight, bottom sheets as shadcn’s Sheet from the bottom, and the phone’s own date picker. Rev 105’s note that the capture app uses CSS Modules rather than shadcn/ui no longer holds; CSS Modules stay for a screen’s layout.
  • Why: AD #43 (2026-11-20) — the two apps are one product to Empire’s staff, and one component library keeps them consistent.
  • Decision: Tharinda (lead), with AD #43, reported by Nanndish, 2026-11-20.
  • Scope: the capture app’s components only; no token changed and no icon concept added. Screens move one PR each (.forge/design/ui/pwa-shadcn.md); a screen whose look changes in its move is redrawn in pwa-current and its screenshots in that PR. The first is the error pages’ buttons. They keep their colours and 44px height; the outline buttons gain the CRM outline button’s light shadow (shadow/card) and its hover fill (--et-accent, in place of surface/hover), and the not-found page’s Back to Leads takes the CRM’s control radius (radius/sm) in place of radius/md.

Rev 150 — 2026-11-20 — §5: the Focus marker, in the CRM and the capture app (F36-c)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 150 on 2026-11-20.

  • Added — §5 Focus marker: the marker F36-c’s wave 3 built for a lead whose ranking was made for a campaign focus, as built in both apps — where it sits (the capture app’s To Review rows, the CRM’s Leads table), its look (a 24px outlined pill with the campaignFocus icon and the word Focus in tone/neutral), its accessible name, and its tooltip (the fixed line, in the Tooltip row’s look, and when it opens and closes). No change to either app.
  • Why: F36-c FR-DC2 and D-29 leave the marker’s exact look to a design-system revision, and the review of forge-et-fe#589 found the design system had no entry for this pattern shared by the two apps (.forge/owed.md, now closed).
  • Decision: Dinil Gamage, 2026-11-20: the marker is accepted as built, and he settles it himself, in place of the lead’s decision the owed.md row and the CRM marker’s code comment waited for.
  • Scope: §5, one row added. No token changed and no icon concept added (campaignFocus is already in the CRM’s registry, and the capture app draws the same glyph in src/ui/icons.tsx). The capture app’s marker is a plain button with a CSS Module, built before AD #43 (Rev 149); it moves onto shadcn with its screen. Prototype: already drawn — crm-current/crm-prototype.dc.html (f36cFocusPill, f36cFocusTip) and pwa-current/source/src/components/focus.jsx (FocusMarker). Implementing code: forge-et-fe src/ui/components/LeadRankIndicators/LeadFocusMarker.tsx and LeadRankIndicators.module.css (.focusMarker), read from src/lib/leadRanking/leadRankingFocus.ts; forge-et-pwa src/ui/FocusMarker.tsx and FocusMarker.module.css, read from src/lib/research/researchLabels.ts.

Rev 151 — 2026-11-21 — §6 and §8: the email block list screens (F20-k)

  • Added — §6 Settings sections: the Mailbox page’s Blocked Addresses row, its compact entry rows, the add dialog and Remove’s question, and the inbox message view’s Block Sender (F20-k FR-1, FR-3, FR-4; spec AC-14, AC-15).
  • Added — §8 The page’s layout: the Email Block List card in the Email section, the section’s line with its new clause (spec AC-24), and the Email Block List page on the tag pages’ layout and table (F20-k FR-2, D-3).
  • Why: F20-k gives each user a block list on the Mailbox page and the administrator one on a Settings page of its own (AD #41). The screens are drawn in the current prototype before WI-2.3 and WI-3.2 are planned (.forge/design/prototypes/README.md § The current prototype leads).
  • Scope: §6, one passage added to the Settings sections bullet; §8, one phrase, one passage and the In the prototype list. No token or component changed. Prototype: crm-current/crm-prototype.dc.html — the Mailbox page’s section, the add dialog, Remove’s question, Block Sender, and the Settings card and page (F20-k-WI-1.1). Implementing code: forge-et-fe F20-k-WI-2.3 and WI-3.2.

Rev 153 — 2026-11-21 — §9 The capture app: the CRM’s filled tabs; no version on Settings; the booth note ends under its box; notifications can be cleared (BUG-526, BUG-527, BUG-523, BUG-524)

Numbered with python3 .claude/lib/next-id.py ds-rev, which printed Rev 153 on 2026-11-21: drafted as Rev 151 on 2026-11-20, renumbered because F20-k’s Rev 151 reached main first and forge-et-harness#1604 holds Rev 152 (id-numbering rule 5).

  • Changed — §9, the segmented switches: Leads’ sections and Capture’s mode are drawn as the CRM’s saved-view tabs: the --et-accent track with no outline, the selected tab filled accent/gold with accent/gold-on text, and the count a surface/card pill. This replaces Rev 142’s paragraph, under which the selected tab was a framed surface/card tab on a surface/inset track, and Capture’s track kept an outline that Leads’ did not.
  • Changed — §9, Settings: shows no version line. The bundle’s version is on the document root as data-app-version, as the CRM’s has been since F5-b.
  • Changed — §9, the booth note: the line under the box is drawn only while an error or the count shows, so the card ends under the box. §5’s rule, that a field keeps the line under its control so an error appearing moves nothing, still holds for every other field.
  • Changed — §9, the notifications bell’s sheet: Clear All in the header and a ✕ clear button on each item (F36-c Rev 11); the offline line moves under the header and covers marking read and clearing.
  • Why: Nanndish, 2026-11-20, after reviewing the built capture app: the selected tab should match the CRM’s view tabs in the primary button’s fill (three options drawn; he chose the first), the version line is not needed, the booth note card had blank space under its box, and read notifications piled up in the bell with no way to remove them.
  • Scope: §9, one paragraph rewritten and one sentence added to the bell’s sheet. No token added; the tabs read --et-accent, one of the five CRM names a capture component may read (theme-crm.css). The shadcn move of Leads and Capture (pwa-shadcn.md rows 5 and 6) keeps this look. Prototype: pwa-current/source/src/screens/today.jsx, capture.jsx and settings.jsx, components/notifications-bell.jsx and App.jsx, rebuilt, with its screenshots retaken. Implementing code: forge-et-pwa src/ui/Tabs.module.css, src/ui/Field.tsx (reserveMessageLine), src/features/settings/SettingsRoute.tsx and src/main.tsx; for clearing, src/ui/Sheet.tsx (its headerAction slot), src/features/notifications/NotificationsSheet.tsx, NotificationRow.tsx and useNotificationClearing.ts, and forge-et-be capture/notification with migration V81.

Generated from .forge/design/ui/design-system.md by .claude/lib/render-docs-html.js. Markdown is canonical.