Brief 11, Salesforce Lightning Design System
The screen. SA-04417, the gearbox oil-change program Northwind Field runs for Ridgeline Wind Cooperative. One record, in SLDS's record shape: highlights panel, path, tabbed detail, related lists in the right rail.
Direction
Archetype. Shell, in the SLDS record-page shape. Under 1024px the rail's three lists become the Related tab, so exactly one of the two is ever on screen.
Data stance. Prose-first. The activity timeline is the record; the fields are what the sentences refer to.
Density. SLDS default (Comfy). 13px body, the 4px spacing scale, 32px controls.
The bold thing. The path is a state machine with four states, not three. Each stage carries its guidance for success and its exit condition. One stage is held by something outside the path (an approval that expires before a board sits) and it carries the warning colour and names the date and the record holding it up. The stage behind it is grey and says which stage it waits on, so the warning colour means one problem rather than two.
Generators
slds_tokens.py --theme hooks
slds_tokens.py --theme primitive --grep duration --format css
slds_tokens.py --contrast
tokens.css is the first command's output and nobody edits it. The hooks set carries no duration, which is why the second command exists: motion-tokens.css holds the six SLDS duration primitives and nothing else.
Pointer states on the path
All six stages answer a pointer, because all six are real targets: clicking one changes the guidance panel, and a completed one moves the record back to it. The refusal lives one level down, on the panel's action button, which carries a real disabled treatment and its reasons. A held stage that read as unhoverable would suppress the affordance on the two stages an account manager most wants to open.
Each state hovers and presses two steps down its own ramp, so a pointer never paints a stage the colour of a state it is not in:
| State | Rest | Hover | Press |
|---|---|---|---|
| Complete | brand-base-95 | brand-base-90 | brand-base-80 |
| Current | brand-base-50 | brand-base-40 | brand-base-30 |
| Blocked | warning-base-90 | warning-base-80 | warning-base-70, ink to warning-base-20 |
| Waiting, not started | neutral-base-95 | neutral-base-90 | neutral-base-80 |
Two of these were self-assignments before state-probe.mjs found them: a completed stage's rest colour was the generic hover colour, and the blocked rule repainted the stage its own background to stop the generic hover reaching it. Both are the same defect, a control that looks inert to a pointer, and the completed stage is the one this page made clickable.
The second state
A record you can only partly see. Preview as in the global header switches the page between the agreement's owner and a field technician, and the technician's render is the honest one. The annual value and the margin read Not available to your role. Two of the three contacts stay hidden. A no-access message takes the place of the files list and names who can share it. Edit, Send for signature and Add on the contacts list go disabled together under one sentence naming whose they are, and the path's stage control goes disabled too, giving both its reasons where a stage is refused for two. Field-level security and sharing are the states an SLDS screen has to render, and the platform's own guidance warns against showing an action the running user cannot perform.
Measured
color-neutral-base-10oncolor-neutral-base-100, the body text: 17.76:1color-neutral-base-100oncolor-brand-base-50, the primary action: 4.63:1color-border-base-3on white, every control boundary: 3.07:1color-border-base-1on white, rules between rows only: 1.66:1color-warning-base-30oncolor-warning-base-90, a held stage: 7.66:1color-neutral-base-30oncolor-neutral-base-95, a waiting stage: 8.78:1color-neutral-base-40oncolor-neutral-base-95, its edge marker: 6.03:1color-brand-base-20oncolor-brand-base-95, a complete stage: 12.29:1
Deviations
Light only. The hooks set carries one set of values, and inside Lightning Experience the theme belongs to the org rather than to a component.
Easing. SLDS tokenizes durations and not easings, so transitions run the ease-in-out keyword over the generated duration tokens.
Type and spacing in rem. Colour, radius, shadow, font family, and duration all come from the token files as var(). Type and spacing follow SLDS's published modular and 4px scales, the values its slds-text-* and slds-p-* utilities carry, since no SLDS stylesheet ships with this page.
A larger record name. font-scale-4 (25.6px) runs larger than a Lightning Experience page header and gives the page one focal size.
<button> rather than <lightning-button>. lwc_lint.py reports 16 native-control warnings and every one of them is right about an LWC template. Off the platform no base-component runtime exists, and a custom element with no definition takes neither focus nor a keypress, so the native control is the accessible answer here.
APCA. Body text at 13px is SLDS's density and clears WCAG 2.2 AA at 17.76:1. APCA asks for 15px at weight 400 and disagrees.
Uplift round (2026-10-29)
Archetype unchanged (shell, SLDS record page). What changed and why:
- Path as chevrons, in Salesforce's own states. Complete is the success green, current the brand blue, held the warning colour, waiting grey. Each state still hovers and presses two steps down its own ramp. The first table above is superseded: a complete stage is now
success-base-50/40/30(white on it 4.65:1). On a phone the path is six segments, with the stage's name in the guidance below. - Key fields per stage. The guidance panel now shows each stage's required fields. Legal review's (liability cap, counsel, board date) are real inputs; completing the stage validates them with inline errors, advances the path, writes a stage-change entry to the timeline and offers Undo. Completed stages show what was captured.
- The hold is drawn. A calendar strip from today shows the finance approval lapsing on Oct 17 and the board sitting on Nov 12, with the gap hatched. Typing a board date redraws it live; a date on or before Oct 17 lifts the hold when the stage is completed.
- Edit. The Edit action puts the Liability cap and Crane hire in edit mode on the Details tab with a save bar.
- Locale and figures. en-US throughout (US dollars, month-first dates, 12-hour times). Every relative date counts from the page's own today, Sep 11, 2026. Annual value is now $486,720 so it divides: 9 turbines x 2 visits x $27,040; 36 months is $1,460,160. Pricing approval Jul 19 plus 90 days is Oct 17; renewal notice is 90 days before Oct 31, 2029 (Aug 2). Work orders read as drafts (2 of 18 planned in year one), since the agreement is unsigned.
- Phone. Actions move to a bottom bar; Complete stage there validates the key fields.
- Field-level security. The technician view now also hides the margin quoted in the July timeline entry.
- Highlights panel reads as an SLDS 2 header card: object tile, compact-layout fields, the annual value set large.
- Design notes recomposed: numbered direction lines, five contrast swatches with ratios (white on brand 4.63, edge 3.07, complete 4.65, held 7.66, waiting 7.73).
Round two: the first screen (2026-10-29)
A critic scored the first fold 5.5/10: small type throughout, a path in a thin band, three columns of 12px text competing. The fold now has one figure, one band and one problem.
- Highlights panel carries one hero figure. The annual contract value, $486,720, is set at 1.3 times
font-scale-10(about 65px at 1440), one step past the generated ramp, which stops at 52px. It is the only deviation from the published scale and is a clamp, so it falls tofont-scale-10on a phone. Its proof sits directly under it: 9 turbines x 2 visits x $27,040 a visit, then $1,460,160 over 36 months. All of it is field-level secured; the technician sees a dashed box naming what is withheld and from whom. The record name drops tofont-scale-4, so there is one focal size. The four compact-layout fields move into a quiet 2x2 beside it. - The path is a band. Stages are 100px tall with the stage name at
font-scale-1, the current stage atfont-scale-3and wider (1.7 against 0.9 for a completed one), and the held stage wider again (1.45) with a third line, "No approval for 26 days". Chevron overlap is now derived from one depth and one gap so the gap stays even. - One thing owns the screen below it. The held-stage alert moved to the wide left column and became the card: "26 days" at
font-scale-9, the sentence that explains it (approval dated Jul 19, lapses Oct 17, board sits Nov 12), the calendar, then "The fix". The stage guidance and the key fields are the narrow right column, unchanged in function. The guide went from three columns to two. The headline, sentence and calendar all follow the board date typed in the form. - Phone. The hero stays at
font-scale-10; the path head collapses into one line naming the stage ("Legal review, Stage 4 of 6, Countersigned is held") and the guidance toggle is dropped there. The held card is first under the path. - Dates still agree. Jul 19 plus 90 days is Oct 17; Oct 17 to Nov 12 is 26 days; the renewal notice is 90 days before Oct 31, 2029 (Aug 2); 9 x 2 x $27,040 = $486,720.
Round nine: the world-class pass (2026-11-09)
Archetype unchanged. The page was scored against the platform's own record page, walked as the account manager and as the field technician, and driven at 320 to 1920 in 10px steps, on an emulated phone at 360 and 390, at 200% zoom and at 1920. What changed and why:
- Every action now does something.
Send for signature,Log a visit,Log a call,New task,Email counsel,AddandView all 18 work ordersused to be buttons with no behaviour. They open one native<dialog>(focus trapped, Escape and the backdrop close it, focus returns to the button), full screen on a phone. The four activity actions write a real timeline entry under the author's name (Priya for the owner, Devin when previewing as the technician) with an Undo;Addadds a contact and the counts follow. - Send for signature is a pre-flight, not a form. It lists the two recipients and two checks: Legal review is complete, and the finance approval is in force when the board sits. While either fails the send button is disabled with its reason in the footer, in the same dashed treatment as the stage button. Clear both (a cap and a board date on or before Oct 17) and it sends, writes the entry and offers Undo.
- The eighteen visits are listed. Nine turbines in two rounds (Nov 16 to 30, 2026 and May 17 to 27, 2027), weekdays only, skipping Thanksgiving. The two raised work orders match the rail; a third turbine carries the plate-serial flag the survey entry describes.
- Weekdays on the calendar. The three marks read Fri Sep 11, Sat Oct 17 and Thu Nov 12, so the approval is seen to lapse on a Saturday. They follow the board date typed in the form.
- The path holds at tablet widths. Between 768 and 1100px the labels broke mid-word (Comple-te, Countersign-ed). That band now keeps the stage name and carries status in the icon and colour; the words stay in the button for a screen reader. Chevron overlap is derived from one depth again: two stale copies of the stage rule (one with a stray parenthesis) had been fighting, which closed the gaps between stages.
- The phone is a product. Under a coarse pointer every control is 44px and inputs are 16px (so iOS does not zoom on focus). The path head names the stage on one line with the hold under it. Timeline dates sit above each entry, as the platform's mobile timeline does, instead of dangling below. Dates carry non-breaking spaces so "Nov 12" never wraps to "12.", and the term and renewal dates wrap as units.
- Focus. The Activity panel's own ring was clipped by the card it sits flush in; it now draws inside the edge.
- Type floor. Avatars, tile labels, chips and badges are 12px, not 10 and 11.
Left, with reasons: the page stays light only (the hooks set emits one value set, and the theme belongs to the org). The approval is dated Sunday Jul 19, which the arithmetic fixes (Jul 19 plus 90 days is Oct 17, 26 days before Nov 12); it reads as a finance date, not a working day.
Round ten: the harsh second read (2026-11-09)
Archetype unchanged. A cold reader scored the page 31/40 against Salesforce's own record page (path, highlights panel, activity timeline, toasts, modals), not the 34 of round nine. Driven afterwards at 1440, 1920, and on an emulated phone (touch, 3x) at 390 and 360, with the dark scheme checked (the page stays light, so it renders identically). What changed:
- Sending had no way back. The sent state is now on the page: a "Sent for signature" chip by the record name, the header button turns from primary to a status button, and Countersigned says it is waiting for the signed PDF. That button opens a dialog with a Recall action, which writes a timeline entry and offers Undo. Saving an edit to the agreement now offers Undo too (it had none).
- Results landed out of sight. A new call, visit, task or email switches to the Activity tab, scrolls the entry into view (on a phone, clear of the toast and the action bar) and takes focus with a visible ring. On a phone, tapping a stage put its guidance 600px below the viewport behind the bar; the path head now names the selected stage and its state, the guidance sits straight under the path for any stage that is not the held one, and the page scrolls when the heading would be hidden.
- The page did not change after the act. A new task now lands in Upcoming and overdue, in date order, with its due date and a relative day count, instead of in September stamped today. Countersigned cannot be marked complete until the agreement has been sent for signature, and says so beside the button.
- The urgent line was last. In the held card, the fix now follows the sentence that explains the hold and comes before the calendar. It is set at body size in ink (it was small and grey), says the task already exists and how overdue it is, and a button opens that task in the timeline, expanded and focused.
- Looks clickable, is not. The account name was a blue underlined link to the top of the page; it is text. The Related tab on a phone had no Add for contacts (only the hidden rail did); it has one now.
- Help where the figure is. Turbines covered, 9 of 14, now says the other five on the register are not in this quote.
- Undo returns focus to a control that exists on the screen (the Activity tab, the stage, or whichever Edit button is visible), not to nothing.
Inventions, named: (1) Recall from signature, and what it writes to the timeline. (2) Countersigned cannot be completed before the agreement is sent. (3) The line "Priya already has this as a task", which restates the existing overdue task. (4) A new task's due date is the date typed, with no time.
Left: the phone action bar's Complete stage is disabled without a reason of its own when the current stage is held (the reason is in the card above it, severity 1). The Account name has no record to open, so it is plain text and not a lookup. Edit still covers only two fields.
Round eleven (2026-11-10)
Archetype unchanged. A cold reader scored the page 33/40 and found two defects in the board-date field, both reproduced as reported before editing.
- A sentence went stale while the date was typed. Typing a board date redrew the headline and the calendar, but the block title ("Countersigned cannot be reached yet"), the fix ("Ask Marisol TreviƱo to extend the current approval") and the line "The proposed start, Nov 1, 2026, falls 11 days before the board sits" kept the saved date. With Oct 10 typed the start is after the board, so the line was false; with Nov 20 typed it said 11 days instead of 19. The block title and the fix are now redrawn with the headline from one place (
holdHead,fillFix), for the typed date and again for the saved one when the field returns to it. The start line appears only while the board sits after the proposed start and counts from the date drawn. When the typed date is on or before the day the approval lapses, the title reads "Countersigned is not held on this date" and the fix reads "Nothing to extend. Completing Legal review saves this date and clears the hold." The task line and its button go with the request they belonged to. The path above stays on the saved date, as before; the calendar caption already says to complete the stage to save the typed one. - A date that cannot be used was dropped silently. Typing 13/45/26 (or a past date, or nothing) and leaving the field left the junk in the box and quietly drew the saved date. Leaving a date field now validates it, as the SLDS field error does: red border, an error under the field that says what to enter and what the calendar is drawn from ("Enter the date as MM/DD/YYYY, for example 11/12/2026. The calendar stays on the saved date, Nov 12, 2026."), the typed value kept, the same text read out through the live region, and a line under the calendar, "Not drawn from what you typed. Enter a valid date to redraw it." Typing again clears both. The error also survives a trip to another stage and back; switching stage used to wipe it while the junk stayed in the box.
Inventions, named: (1) the title "Countersigned is not held on this date" and the fix "Nothing to extend" for a typed date that clears the hold; both only restate the rule the page already uses (held when the board sits after the approval lapses). (2) The calendar sentence appended to the board field error. (3) Blur validation on date fields; the form-level summary still appears only on Mark complete.
Left: the path stage ("No approval for 26 days") still follows the saved date, not the draft, as in round ten. The phone bar still says Complete stage where the form says Mark Legal review complete.
Round thirteen (2026-11-10)
Archetype unchanged. A cold reader scored the page 34/40 and would ship it, with one change: the phone action bar called one act "Complete stage" where the guide button calls it "Mark Legal review complete". Reproduced as reported at 390 and 360 (touch, 3x): bar "Complete stage", guide button "Mark Legal review complete".
- One name for the act. The bar button now reads "Mark <stage> complete", written by
syncBarfrom the current stage, so it follows the path exactly as the guide button does (Legal review, then Countersigned, and back after Undo). The desktop name was kept: it says which stage the act closes, which "Complete stage" does not. There is no dialog for this act; the toast reports the result ("Legal review is complete. ...") and is not a second name for the act. - The other bar actions agree. Edit is "Edit" in the header and the bar; Log a visit is "Log a visit" in the header, the bar and the dialog title. Send for signature is header only, as before.
- The longer label fits. Bar buttons take 8px side padding and a 1.25 line height, so the label wraps to two lines inside 44px at 390 and 360 and the bar keeps one height for every stage name. At 320px and under the bar font is the 12px floor, which keeps "Mark Countersigned complete" and "Mark Pricing approved complete" to two lines.
Inventions, named: none beyond the label. When every stage is done the bar button (disabled) names the last stage, "Mark In service complete", as the guide's own disabled buttons name theirs.
Round fifteen (2026-11-10)
Archetype unchanged. A cold reader (r14) would ship it with one note: while a what-if board date is typed, the path still says "Held, No approval for 26 days" and the block says "Countersigned is not held on this date". Reproduced as reported at 1440: type 10/10/2026 in "Cooperative board meets", Tab. The same disagreement held for a later date (11/20/2026: path 26 days, block 34 days).
- The two parts no longer contradict. While the typed date differs from the saved one, the block opens with a dashed row, a "What-if, not saved" chip and one sentence: "Drawn from the board date you typed, Oct 10, 2026. The path above shows the saved date, Nov 12, 2026." The path is therefore the saved record, said so by the row. The row goes away when the field returns to the saved date, and it is not shown for a date that cannot be used (the existing error and "Not drawn from what you typed" line cover that case). Written in
redrawAxiswith the rest of the block's what-if text. - Toast. It sat at the top centre, over "Service agreements" and, once scrolled, over the path. It now sits at the bottom centre on every width (the phone keeps its offset above the action bar). A role switch dismisses it: its Undo belonged to the previous role's act, and on a phone it covered the next block.
- 390px first fold (sev 1 c): not changed. The path head ("Stage 4 of 6, Countersigned is held") is at y 616 of 844 at 390, inside the first fold; the block itself is below it by design since round ten.
Inventions, named: (1) the chip text "What-if, not saved" and its sentence; (2) a dashed edge for a not-yet-real state, borrowed from the page's own disabled-button treatment; (3) dismissing the toast on a role switch. SLDS has no preview marker on the path, so the path was left as the saved state and the block carries the label.
Round seventeen (2026-11-10)
Archetype unchanged. A cold reader (r16, 37/40) would ship it with one note: on a phone the first screen is the highlights panel and the path is six unnamed icons, so the held-stage story starts a long scroll down. Reproduced at 390x844 and 360x780 (touch, 3x): the only words about the hold were "Stage 4 of 6, Countersigned is held", at page y 636 (390) and 654 (360), with no day count; the block that explains it began below the action bar's edge.
- The path head names the hold, with its days. On a phone the line under the stage name now reads "Legal review Stage 4 of 6, current stage" on one row (name and step count together, as SLDS's mobile path does), and under it, in the warning ink with the warning icon, "Countersigned is held. No approval for 26 days." It shows whichever stage is selected, since the hold belongs to the record, and it follows the saved date. It is written in drawTrack with the rest of the path.
- The highlights panel is compact on a phone. Record name 16px on one line with a 32px tile; hero figure at font-scale-9 (it was font-scale-10); tighter gaps and padding; the Term field drops its renewal-notice line and the Turbines field drops its dots (the renewal date is in Details, the dots restate 9 of 14). The panel is 371px tall at 390 and 360 (476 and 494 before). The held sentence is now at y 537 at both widths (636 and 654 before), and the held block's title and the track are inside the first fold above the action bar.
- Sev 1, the path says Held beside a what-if date. The round-fifteen row ("What-if, not saved") was in the preview for the reviewer's repro (10/10/2026, Tab) and they still read the path as contradicting the block. The path now says whose date it draws: while a typed date differs from the saved one the held stage reads "Saved date: no approval for 26 days" and the phone line ends "on the saved date." Both return to the plain wording when the field returns to the saved date or the stage changes. Written by redrawAxis calling drawTrack when the what-if state flips.
Inventions, named: (1) the words "Saved date:" and "on the saved date"; (2) the phone held line and its wording, which restate the desktop stage text; (3) hiding the renewal line and the dots on a phone only. Hero size on a phone is one scale step down from round two.
Left: the toast still covers hold-block text while it lasts (sev 1 c); it is bottom centre by round fifteen and has Undo and a close button.
Round nineteen (2026-11-10)
Archetype unchanged. A cold reader (r18, 34/40, ship: no) found that a phone user cannot send the agreement for signature. Reproduced as reported at 390 and 360 (touch, 3x): after Legal review closes, "Mark Countersigned complete" is disabled with "Send the agreement for signature first. The button is at the top of the record.", and #act-sign is 0 x 0 inside .hl__acts, which is display: none under 768px. The bar held Edit and Log a visit only.
- Every header action is on the phone. The bar is now Edit, More, and the stage button. More opens a short list above the bar with Log a visit and Send for signature (the header's other two actions; Edit stays in the bar). Send for signature reads "Sent for signature" once sent, as the header button does, and opens the same dialog (the pre-flight, or Recall). It is a disclosure button (
aria-expanded,aria-controls), not an ARIA menu, so it needs no arrow-key model: focus goes to the first item, Escape returns focus to More, a tap outside or Tab away closes it, and picking an item puts focus back on More first, so the dialog returns focus to a control that stays on screen. The bar's z-index is now above the toast, because the toast sits in the same band and covered the list. - The reason names the control, not a place. The disabled stage button's reason now reads "Send the agreement for signature first. Choose Send for signature." at 768px and up, and "... Choose More, then Send for signature." under 768px (two spans, one hidden by the same breakpoint that shows the bar).
- Driven to Countersigned complete (cap, board 10/09/2026, Mark Legal review complete, More, Send for signature, Send, start date 11/01/2026, Mark Countersigned complete) at 390, 360, 1440 and 1920.
Inventions, named: (1) the label "More" and moving Log a visit behind it on a phone only; (2) the two reason sentences.
The toast (sev 1, second pass)
Defect, measured at 1440 and 390: the bottom-centre toast covered the disabled stage button and its reason (desktop) and the stage guidance (phone) for as long as it showed.
One rule: the toast covers none of the text the act just changed. Where it sits: top centre under the global header on 768px and up (SLDS's place; top: 3.75rem, clear of the 57px header at scroll 0), and directly above the action bar on a phone (as in round fifteen). This puts the toast at the top on desktop again; round fifteen had moved it to the bottom for covering "Service agreements" and the path, and the rule below is what makes the top safe. reveal() runs after every act that raises a toast: it takes the elements the act changed, finds the band the toast (and on a phone the bar) leaves free, and scrolls the page only if they are not already inside it (centred in the band, or top-aligned if taller than it). What each act changed: a stage move or move back, the stage's eyebrow and guidance, plus the stage button and its reason on desktop or the path head on a phone; an activity entry (call, visit, task, email, send, recall), that timeline entry, which land() now places with the same function instead of its own 72 and 240 pixel margins; an edit save, the two Details values; an added contact, its new row in whichever list is showing. Focus after a stage move or an edit save no longer scrolls on its own (preventScroll), so reveal() is the only scroll.
Measured after each act (stage Legal review, send, stage Countersigned, move back, edit save, call, task, email, visit, contact) at 1440, 1920, 390 and 360: toast rect against every text rect of the changed elements, and whether those rects lie inside the viewport above the bar. Result: zero covered and zero off-screen in all 40 cases; no page errors, no horizontal overflow. As a negative control the same script with the toast forced to the middle of the screen reports covered text on the stage acts. The toast does still cover other text, such as the highlights panel at the top of the page on desktop; that is text the act did not change.
Inventions, named: (1) top: 3.75rem as the offset under the header; (2) scrolling the page after an act, where before only a new timeline entry was scrolled to.