​

Modulus design system

​

Figma file

4Audgs6XUkkKEa1KsyZZ3K

​

Source of truth

git show origin/staging:tokens/modulus-design-tokens.json

gh api "repos/CFO-Silvia/Silvia-Web/contents/tokens/modulus-design-tokens.json?ref=staging" \
  -H "Accept: application/vnd.github.raw" > /full/path/to/your/modulus-design-tokens.json

​

Edit the token file as TEXT, never through a JSON round-trip

authored:         $type 0 half 1 2 2half 3 4 5 6 8 9 10 11 12 16 20 24 26
after round-trip: 0 1 2 3 4 5 6 8 9 10 11 12 16 20 24 26 $type half 2half

node -e '
const fs=require("fs"), cp=require("child_process");
const before=cp.execSync("git show origin/staging:tokens/modulus-design-tokens.json").toString();
const after=fs.readFileSync("tokens/modulus-design-tokens.json","utf8");
// Anchored to line start: this file is pretty-printed, so a key is always the
// first thing on its line, and a quoted substring inside a $description value
// never is. An unanchored /"[^"]+":/ would match those too.
const seq=s=>(s.match(/^\s*"[^"]+":/gm)||[]).map(x=>x.trim()).join("|");
const identical = seq(before)===seq(after);
console.log("key sequence identical:", identical ? "YES" : "NO");
if (!identical) process.exitCode = 1;
'

​

Counting $extensions keys: count keys, not occurrences

​

The three opacity tokens, and the asymmetry that was there

​

Hard rules

1. Bind every value to a token. No raw hex, no arbitrary Tailwind values such as p-[13px], no magic numbers.
2. Never use a .sam-* utility class. The nine in globals.css are unscoped and would bypass the theme variant. Rose gold comes from accent-text and the cta-intent pair.
3. Never write to :root. All variables live under the theme variant selector, [data-theme-variant='modulus'] (plus html.dark[...] and html.dark [...] for dark mode).
4. Prefix every Tailwind key modulus-.
5. Title every story Modulus/*, under exactly three groups: Modulus/Foundations/<Topic>, Modulus/Components/<Category>/<Name> and Modulus/Screens/<Area>/<Page>. See the story category table and Story titles below for the eight component categories, the naming rule and the full tree.
6. Prefix every exported identifier Modulus / modulus. Components, cva recipes and prop types alike. Separately, every exported COMPONENT carries a displayName matching its export; a prop type has no runtime value and cannot. See Export naming below for scope and exclusions.
7. Story content names the slot, never the product. Button, Title, Description, Label. See Story content below for the six exceptions and why an unreviewed story that looks approved is the real cost.
8. A claim about WHY a decision was made needs a citation to where it was made. A file and line, a commit sha, a PR link, or a dated quote. If the reason is not recorded anywhere, write that instead of supplying one. See Recorded reasons below.
9. A stylesheet that scopes from the theme variant carries BOTH selector forms. The descendant [data-theme-variant='modulus'] .thing AND the compound [data-theme-variant='modulus'].thing, whenever .thing can sit on an element that also carries the attribute. See Scoping from the variant below.
10. A composition that merges caller input with the component’s own values decides which side wins, and the file says which values are load-bearing and why. The load-bearing side goes LAST. Where the merge function itself resolves conflicts, check that it resolves the right KIND of conflict - modulusCn resolves Tailwind classes and will silently drop an id that reads as a competing utility. See Merging two of the same kind below.

​

Structure

• One component per file, kebab-case: button.tsx, icon-button.tsx
• Stories colocated and same-named: button.stories.tsx
• Variants via class-variance-authority, with variant keys matching the Figma variant property names one to one
• Imports use the @/ alias, which is rooted at the project root
• tags: ['autodocs'] on each story meta, since autodocs is off repo-wide
• modulusCn comes from ./modulus-cn, never cn from @/lib/utils. The Modulus Tailwind keys are token names rather than lengths, so tailwind-merge needs extra class groups to merge them; that configuration lives in components/modulus/modulus-cn.ts so the 142 files importing @/lib/utils keep the stock merger untouched. The export is named modulusCn, not cn, because two functions answering to cn gave a caller no way to tell which one an import { cn } had bound - the filename disambiguates the path, only the export name disambiguates the call site. lib/utils.ts remains the canonical cn for everything outside Modulus. The modulus- prefix reads redundantly inside a modulus/ folder on purpose: this file moves to components/ui/ with the four components, where the prefix is load-bearing
• Storybook-only CSS lives in components/modulus/modulus-storybook.css, imported by each story file. .storybook/preview-head.html and .storybook/preview.tsx are shared with every other story file in the repo and are not ours to edit
• components/modulus/modulus-surface.css IS imported in app/layout.tsx, at line 20, alongside app/modulus-tokens.css at 17. Unlike modulus-storybook.css it is product CSS, not Storybook chrome: it holds the shared surface treatments, currently the noise grain that Card carries and that Composer and Modal will want. The failure mode it guards against is silence: the class is on the element, the token resolves, and the grain simply does not appear, because the rule defining .modulus-surface-noise was never loaded. Nothing errors and nothing warns. THIS BULLET READ “must be imported … when the app is wired up” AND “Storybook-only until that import lands” UNTIL 2026-09-17, AND THE IMPORT HAD ALREADY LANDED. It was describing a state that had ended, in the section whose entire subject is failures that announce nothing - so a reader checking whether the grain reaches production would have been told it does not, by the paragraph they went to precisely because it is hard to check. Found by an audit, not by a reader. The general form: an instruction written in the future tense does not retract itself when it is carried out. Grep app/layout.tsx before repeating any claim here about what it imports; today that is six Modulus stylesheets, and the list moves.
• components/modulus/modulus-tag.css is DELIBERATELY not imported there, and that decision is recorded at app/layout.tsx:34. Not an oversight and not the same case as the bullet above: its rules apply only to a Tag carrying a remove button and to a Tag inside a Composer, and no product Tag is either today, so importing it would change nothing. It becomes required the first time a Tag ships with onRemove or inside a Composer. It holds the two things no utility can express: the @media (hover: hover) gate that stacks Tag’s X on its leading icon and swaps them on hover — on touch the two sit side by side permanently instead, because there is no hover to reveal anything and a swap would mean the icon was never seen on a phone at all — and the @container modulus-composer query that drops Tag’s label when the Composer is too narrow. That query has two thresholds, 450 for a hovering pointer and 470 for touch, because the in-flow X makes the touch Tag exactly 20 wider. Also product CSS, also currently imported from story files (tag.stories.tsx, composer.stories.tsx), also silent when missing — the Tag renders correctly at rest and simply never swaps and never collapses. It is imported by FIVE story files, not the two this used to name: tag.stories.tsx, chat.stories.tsx, composer.stories.tsx, radar.stories.tsx and research.stories.tsx. tag.tsx and composer.tsx name the file in prose and do not import it, which is the code-form-versus- prose trap this document records elsewhere - a bare filename search returns seven hits and five of them are imports. Note the container side has two halves: container-type: inline-size is set by the .modulus-composer-query class that composer.tsx puts on its Card, and the query itself lives in this stylesheet, so neither works alone
• Container queries are used directly, with no Tailwind plugin. @tailwindcss/container-queries is not installed and was not added for this. The plugin only supplies @container/@md: utility classes; the CSS feature needs nothing, and components/preference-modal/preference-modal.module.css already uses it. Prefer a container query to a media query whenever the constraint is how wide a component’s own surface is: a Composer can be 466 wide inside a 1440 window, which is exactly what the Storybook docs page does, and a viewport query is wrong in every such case
• But a container query needs a CONSTANT to compare against, and that is where it stops being the answer. A threshold describes a width only while the thing being fitted has a fixed width. Tag’s label is fixed by its own content, so 450 and 470 describe it. The composer’s mode chip is the same shape of problem with the opposite answer: its label is the MODE, a runtime prop, and the three FULL CHIPS measure 113.41, 120.98 and 183.54 against a compact 74 - so one threshold is wrong for two of them. (The labels inside them are 31.41, 38.98 and 101.54; the chip is the compact 74 plus a label and its 8 gap. Naming the chips rather than the labels matters here, because the chip is what has to fit in the row.) Worse, the row it has to fit in also holds startActions, which is a caller slot. use-composer-compact.ts measures the row instead, and components/modulus/composer.tsx carries the worked comparison. The test is not “is this a width response” - both are - but “is the width I would be comparing against a constant”. If a prop or a caller can change it, measure
• A rounded container holding a filled or bordered child needs to clip, and the library already does — audited 2026-09-11, no exceptions found. The canvas had OptionList 385:566 and every Mode Menu Panel variant carrying a radius with clipsContent false, so a selected row’s fill squared off past the rounded border; Modal / Picker already clipped, which is why it never showed there. The code equivalent does not exist. ModeMenu sets overflow-hidden and OptionList and RowActions set overflow-y-auto on the same element as the radius — and overflow-y: auto with a visible x-axis computes x to auto too, so the box clips on both. Swept every rounded element in 16 stories: 0 bleeds, with a deliberately bleeding element injected into the page each run to prove the detector fires. Two notes for whoever repeats it. The test is CONTAINMENT, not concentricity: a square child at inset p inside radius r is contained when p >= r(1 - 1/√2), not when p >= r. The stricter rule flagged four ArtifactCards that do not bleed — r 16, p 9, and 9 > 4.69. And a rounded element whose children are only text or icons cannot bleed at all, so it is not a finding that it was skipped

​

Export naming

​

Scope: the component library, not foundations/

• blocks.tsx is imported by the four sibling foundations/*.mdx pages, as './blocks'.
• tokens.ts is imported by those pages and by scripts/modulus-tokens/foundations-coverage.ts, which takes 10 of its exports and runs as npm run foundations:report.

​

What the prefix does not reach

• data-slot values. They stay unprefixed: data-slot='button' on ModulusButton. They are kebab-case attributes, scoped by the element they sit on rather than being identifiers, and selectors depend on them. That is why the Axis 1 wording says “matching the component’s UNPREFIXED name”.
• File names. button.tsx stays, since the directory already says modulus. This holds only while the files live here. They are planned to move to components/ui/, where button.tsx and card.tsx ALREADY EXIST, so the filesystem itself collides at that destination and the decision has to be retaken as part of the move. Recorded here so the move does not rediscover it.
• Story titles. Modulus/Components/Action/Button is already namespaced by its first segment, so the last segment drops the prefix rather than repeating it: Button, ChipLarge, SettingRow. A composition with no export of its own takes its file name instead; see Story titles.
• A screen story, which exports nothing at all. A Modulus/Screens file in this folder is a story file with no component beside it, so this rule has nothing to bind to. Stated explicitly because the obvious way to satisfy a naming rule is to produce a name: do NOT add a ModulusChatScreen export so the rule has a subject. The absence of an export is the design, since anything exported here would be a second assembly of a screen the product already assembles from routes and real data. The three Modulus/Screens files under app/ render the route’s own component, which is product code outside this library, so the rule does not reach them either.
• Prose in comments. This one looks like an omission and is not. Short names in prose frequently do not refer to our components at all: Figma's IconButton "Icon size" property names the Figma set, which is not renamed; Button-only attributes in chip.tsx means the HTML <button>; and alongside Button, IconButton and Chip names story titles. A blanket prose rename corrupts all three. Code references inside backticks do follow, because a doc pointer that no longer greps is simply wrong.

• Quoted values. label='Chip' became label='ModulusChip' in 13 places, and the Chip in the docs would have read “ModulusChip”.
• JSX text. <Tag ...>Tag</Tag> puts the component in the tag and the LABEL in the child. Four of those were caught by a guard, and a fifth, <CardTitle>Card {i + 1}</CardTitle>, slipped past it because the text continues into an interpolation instead of ending at the closing bracket.

​

shadcn compliance

​

Axis 1 — conventions. Every component, no exceptions.

​

Axis 2 — primitives. Only where behaviour demands it.

​

Axis 3 — robustness. Three rules, each written after it broke something.

• Segmented paints the ring on the tab while focus lands on a visually hidden radio. The radio is given peer and the tab, its next sibling inside the wrapping <label>, uses peer-focus-visible:. That is the ~ combinator, supported everywhere. Keep exactly one radio and one tab per label: ~ is a general sibling combinator, so a peer sharing a parent with several tabs would ring all the later ones.
• TextField genuinely binds its border, height, padding, radius and fill to the Field wrapper, because that frame is what Figma draws and what holds the optional prefix. It uses focus-within:, which has universal support. That is equivalent to has-[:focus-visible] here and only here, because the input is the only focusable descendant and a focused text input always matches :focus-visible whatever the input modality. Do not copy this to a control whose focusable element is a radio, checkbox or button: those do not match :focus-visible on a mouse click, so focus-within: would show a ring where the old rule did not.

​

Four things that will bite, all measured

​

Story titles

• Foundations: Modulus/Foundations/<Topic>, the topic in plain Title Case words: Colour, Typography, Spacing, Motion, Icons, Logo, Logo Icon, Logo Wordmark.
• Components: Modulus/Components/<Category>/<Name>. <Category> is spelled as in the table above. <Name> is the component the file documents, the one its stories render, without the Modulus prefix: ChipLarge, SettingRow, ModalPanel, ConnectionSuccessDialog. That is the meta component unless the meta points at a wrapper local to the story file, as StatefulSelector does in components/portfolios/portfolio-selector-menu.stories.tsx. A composition with no component of its own takes its file name in PascalCase: Compare, Settings, EntryComposerWithContactStrip, EntryComposerWithComposerStrip.
• Screens: Modulus/Screens/<Area>/<Page>. A screen is a full page, a route, and nothing else. <Area> is the product’s name for the route or family of routes (Chat, Research, Radar, Portfolio, Sign Up). <Page> is Page for the area’s own whole screen. Another route in the area takes that page’s own name: Portfolio/Businesses for /assets-liabilities/businesses, Portfolio/Business for /assets-liabilities/businesses/[businessUuid]. A state of a route that has its own story file takes the canvas frame’s or the state’s name: Radar/Entry, Sign Up/Webview.
• One title per file, one component per title. A file that covered several components is split: the business dialogs were one file under Modulus/Business/Dialogs and are now four, one per dialog, sharing components/business/business-story-fixtures.ts.

• The two entry composer arrangements are in Action, beside their strips. They are not routes, so not Screens, and both strips belong to the entry composer: the Contact Strip is “Entry-screen composer only” (contact-strip.tsx:26), and the Composer Strip is “tucked under the entry-screen Composer” (composer-strip.tsx:26).
• ContactStrip and ComposerStrip are in Action, not Conversation. The Contact Strip’s spec says it “never appears in the conversation view” (contact-strip.tsx:26-27), and the Composer Strip is a checklist under the entry composer, “each one a link” (composer-strip.tsx:26-27).
• Conversation holds MessageSilvia, MessageUser and Thread. Conversation draws the turns and the column that stacks them; GenUI draws what the catalog puts inside a turn. The category’s own recorded reason is the docblock on the meta in message-user.stories.tsx.
• PortfolioSelectorMenu stays in Navigation.
• The logo marks are in Foundations, not a component category, as brand marks shown visually, like Icons.

Modulus/
  Foundations/
    Colour                          foundations/Colour.mdx
    Typography                      foundations/Typography.mdx
    Spacing                         foundations/Spacing.mdx
    Motion                          foundations/Motion.mdx
    Icons                           icons.stories.tsx
    Logo                            logo-lockup.stories.tsx
    Logo Icon                       logo-icon.stories.tsx
    Logo Wordmark                   logo-wordmark.stories.tsx
  Components/
    Action/
      Button                        button.stories.tsx
      Chip                          chip.stories.tsx
      ChipLarge                     chip-large.stories.tsx
      ComposerStrip                 composer-strip.stories.tsx
      ContactStrip                  contact-strip.stories.tsx
      EntryComposerWithComposerStrip  entry-composer-with-composer-strip.stories.tsx
      EntryComposerWithContactStrip   entry-composer-with-contact-strip.stories.tsx
      FilterPill                    filter-pill.stories.tsx
      IconButton                    icon-button.stories.tsx
      Link                          link.stories.tsx
      PromptRow                     prompt-row.stories.tsx
      RowActions                    row-actions.stories.tsx
      SelectableChip                selectable-chip.stories.tsx
    Data Input/
      Checkbox                      checkbox.stories.tsx
      Composer                      composer.stories.tsx
      DateField                     date-field.stories.tsx
      DocumentRow                   document-row.stories.tsx
      SearchField                   search-field.stories.tsx
      Segmented                     segmented.stories.tsx
      Select                        select.stories.tsx
      SettingRow                    setting-row.stories.tsx
      Slider                        slider.stories.tsx
      Switch                        switch.stories.tsx
      TextField                     text-field.stories.tsx
    Navigation/
      AccountRow                    account-row.stories.tsx
      HistoryPanel                  history-panel.stories.tsx
      HistoryRow                    history-row.stories.tsx
      MobileAppBar                  mobile-app-bar.stories.tsx
      NavGroupHeader                nav-group-header.stories.tsx
      NavItem                       nav-item.stories.tsx
      PortfolioSelectorMenu         components/portfolios/portfolio-selector-menu.stories.tsx
      Sidebar                       sidebar.stories.tsx
      TextTab                       text-tab.stories.tsx
      Topbar                        topbar.stories.tsx
    Surface/
      ArtifactCard                  artifact-card.stories.tsx
      Card                          card.stories.tsx
      InfoPanel                     info-panel.stories.tsx
      RadarCard                     radar-card.stories.tsx
    Overlay/
      BusinessAddChoiceDialog       components/business/business-add-choice-dialog.stories.tsx
      BusinessDialog                components/business/business-dialog.stories.tsx
      BusinessLinkAccountsDialog    components/business/business-link-accounts-dialog.stories.tsx
      BusinessRemoveDialog          components/business/business-remove-dialog.stories.tsx
      ConnectionSuccessDialog       components/connection-success/connection-success-dialog.stories.tsx
      Drawer                        drawer.stories.tsx
      ModalPanel                    modal-panel.stories.tsx
      ModalPicker                   modal-picker.stories.tsx
      ModalShowcase                 modal-showcase.stories.tsx
      ModeMenu                      mode-menu.stories.tsx
      OptionList                    option-list.stories.tsx
      Pane                          pane.stories.tsx
      Settings                      settings.stories.tsx
      SettingsModal                 components/settings/settings-modal-loading.stories.tsx
      SettingsUnsavedDialog         components/settings/settings-unsaved-dialog.stories.tsx
      WebviewConnectEscapeDialog    components/dialogs/webview-connect-escape-dialog.stories.tsx
    Feedback/
      Avatar                        avatar.stories.tsx
      EmptyState                    empty-state.stories.tsx
      Tag                           tag.stories.tsx
    Conversation/
      MessageSilvia                 message-silvia.stories.tsx
      MessageUser                   message-user.stories.tsx
      Thread                        thread.stories.tsx
    GenUI/
      ApprovalRequest               genui/approval-request.stories.tsx
      AssetProposal                 genui/asset-proposal.stories.tsx
      BarChart                      genui/bar-chart.stories.tsx
      Compare                       genui/compare.stories.tsx
      DetailCard                    genui/detail-card.stories.tsx
      EmailDraft                    genui/email-draft.stories.tsx
      InfoCard                      genui/info-card.stories.tsx
      LineChart                     genui/line-chart.stories.tsx
      MetricCard                    genui/metric-card.stories.tsx
      MetricChange                  genui/metric-change.stories.tsx
      MetricGrid                    genui/metric-grid.stories.tsx
      PieChart                      genui/pie-chart.stories.tsx
      ProgressBar                   genui/progress-bar.stories.tsx
      ProgressTracker               genui/progress-tracker.stories.tsx
      Scenario                      genui/scenario.stories.tsx
      StatusCard                    genui/status-card.stories.tsx
      Table                         genui/table.stories.tsx
      Timeline                      genui/timeline.stories.tsx
  Screens/
    Chat/Page                       chat.stories.tsx
    Research/Page                   research.stories.tsx
    Radar/Entry                     radar.stories.tsx
    Radar/Page                      radar-page.stories.tsx
    Portfolio/Business              app/(app)/assets-liabilities/businesses/[businessUuid]/_components/business-detail-screen.stories.tsx
    Portfolio/Businesses            app/(app)/assets-liabilities/businesses/_components/businesses-detail-screen.stories.tsx
    Sign Up/Webview                 app/(public)/sign-up/[[...sign-up]]/apple-webview.stories.tsx

​

GenUI

​

Story content

​

The six exceptions, and only these

1. A label the variant cannot express without it. Delete on a destructive button. The tone is illegible without a destructive verb, so the word is carrying variant information rather than pretending to be copy.
2. A size or state story naming its own rung. Small, Medium, Large; Default, Hover, Focus, Disabled. The label IS the axis value.
3. A story whose subject is text behaviour - wrapping, truncation, long labels. Use realistic LENGTH, and say in the story description that this is why. Note that length is what the exception buys, not content: a generic string of the right length is better than a product one, because it satisfies the exception without looking approved.
4. A label paired with an icon, which names the action, because the pairing is the subject. Add beside a plus. This also covers an icon-only control whose aria-label is its only name.
5. A composition story of ONE COMPONENT’S OWN PARTS — Card’s header over content over footer, EmptyState inside a panel. Realistic content is allowed because the subject is how the parts sit together, and placeholder strings of equal length would not exercise the wrapping or the gaps. Say so in the description, and say that the copy is unreviewed. The component is still the subject, so the copy is a concession.
6. A COMPOSITION OF SEVERAL COMPONENTS, WHERE THE ASSEMBLY IS THE SUBJECT - a screen, or a modal built from a shell and eleven components. Here the rule inverts outright rather than being conceded. THE TWO ARE TOLD APART BY HOW MANY COMPONENTS ARE IN PLAY, not by how the copy reads: exception 5 is one component’s parts and the copy is a concession; exception 6 is several components and the copy is the point. They overlapped until 2026-09-16, when both said “the subject is the arrangement” and an author could not tell which applied. Every other story names the slot because the component is the subject; this kind uses REAL content because assembling real data is the thing it demonstrates. One built from Title and Description shows nothing a reader could not get from the component stories it is made of. This is the one exception that is not a narrow carve-out. IT WAS WRITTEN AS “a story in Modulus/Screens” AND THAT WAS THE WRONG AXIS. It named a CATEGORY when what it meant was a KIND, and the two came apart the first time a composition turned out not to be a screen: Settings is an assembly of Modal / Panel and eleven components with real product copy, and it belongs under Overlay because a screen is a route and a modal is something a route opens. Under the old wording, moving it to its correct category would have made its copy a violation — so the category would have had to stay wrong to keep the copy legal. Reworded 15 Sep 2026. The test is now the one the reason always implied: is the SUBJECT of this story the arrangement rather than any one component in it? A screen passes. A composed modal passes. A component story does not, whatever it is filed under.

​

Three calls worth not relitigating

​

Control sizing

​

The whole ladder moved down one rung

           xs      sm      md      lg
height   24→18   36→24   44→36   48→44
pad-x      -      16→12   20→16   24→20

• layout/logo/height: the chrome row binds control-height-lg 44 (topbar.tsx:151, sidebar.tsx:183), so a 20 glyph centres at 46.
• control/composer: chrome is 86 - 2 x 16 padding, a 16 gap, the control/height/md 36 action row and 2 hairlines. composer.tsx was reverted out of the rebind, so md is right here and the 84 above never closed.
• max-lines: mobile-app-bar.tsx:110 binds control-height-lg, so the phone bar is 16 + 44 + 16 = 76 and the usable height at an 812 viewport is 736. Six lines is 232, 31.5 per cent of it; seven is 256, 34.8.
• The conclusion still holds and never moved: six lines stays under the third that was the constraint, seven breaks it.

​

States

• Hover, focus and disabled are drawn in Figma. Match them exactly.
• Pressed is not drawn, being transient. Implement on :active using cta-bg-active for primary neutral, surface-pressed for secondary and tertiary neutral, destructive-bg-active for primary destructive, destructive-ghost-pressed for tertiary destructive, and the flat cta-intent gradient for high-intent.
• Disabled applies disabled-opacity once at the component root. Never on a child, since it compounds.
• Focus uses border-focus at focus-width (2) with focus-offset (2) outside the control, so the control does not shift on focus.
• Transitions use duration-fast (150ms) for controls and duration-base (200ms) for overlays, with easing-standard.

​

One menu row colour convention

• The leading glyph takes the same value as the label, rather than carrying one of its own, so the row lifts as one thing.
• Nested rows sit one step quieter at rest, on text-muted, and lift to text-primary like the rest. The quieter value is a REST value only, so a nested selected row is not a step behind a top-level one.
• A second line stays on text-secondary in every state. Only the primary label moves.

​

Put the colour where BOTH the label and the glyph inherit it

​

The three reach Focus differently, and the difference is forced

​

NavItem’s Focus value is code-only, and the canvas cannot tell you

​

What the convention does NOT yet reach

​

Colour and mode

​

Icons

​

Typography

​

Gradients

​

Measuring in Storybook

window.innerWidth // must be the viewport you think you set

​

A STALLED FRAME cannot be measured, and the pane does not tell you it has one

• document.timeline does not advance, so no CSS transition or animation progresses and getAnimations() shows animations stuck at their start. A WAAPI onfinish never fires; a setTimeout fallback still does, which is how use-mode-roll.ts’s 3x guard was seen working by accident.
• requestAnimationFrame never fires.
• ResizeObserver never delivers, because its delivery hangs off those same steps.

document.hidden          // NOT a reliable discriminator - see below

let n = 0; requestAnimationFrame(function t() { n++; requestAnimationFrame(t); });
await new Promise(r => setTimeout(r, 500));
n // ~30-60 means the frame is live; 0 means every note above applies

​

Two causes at the same pixel: why the right fix reads as no fix

1. overflow-hidden CLIPPED it.
2. The parent’s after:top-full seam strip PAINTED OVER it — a positioned pseudo-element generated after that box, filling surface-page, which is precisely the colour the cut bled to.

• When a fix you believe in produces no change, suspect a second cause at the same coordinate before you suspect the fix. Ask what else terminates at that exact pixel. Here both answers were on the same two elements.
• Check your control can discriminate. A control that produces the same output for both arms has told you nothing, and it is easy to build one by accident — a forced offset that happens to collide with browser chrome, a colour probe on an animated surface. State, before running it, what the failing arm should look like and confirm it looks different.
• Separate the causes physically, not just logically. The measurement that settled this shrank the decorator to 400px so its bottom sat far from any other boundary; the composer then vanished outright and the mechanism was no longer arguable.
• Vary one thing, but enumerate the cells. With two suspects that is four runs, not two, and the diagonal is the only cell that answers the question.

​

On iOS, a blur moves the control out from under the click

1. WebKit does not focus a <button> on tap, so tapping a control beside a focused field BLURS the field.
2. The keyboard dismisses. visualViewport resizes, and anything sized to it
   • the screen shell is - grows back.
3. The control travels down the screen BETWEEN pointerdown and click.

pd BUTTON:Chat | cl DIV:Reply to S

​

Safari reveals a focused field once, and not if it is hidden at that moment

​

A constant that names the row is wrong on every arm with a different row

1. The bar. The one-line bar kept the open arm’s 44 floor (ROW_CONTROL_RUNG) around its 32 controls and measured 62 against a drawn 48. (The 50 it measured next was a different cause - the border sitting outside the padding - and is not this defect.)
2. CHROME_TERMS. The text area’s floor is the rung less the chrome, and the chrome’s row term was a literal 44. On the 32 arm the floor came out 12 short, a single line’s own height took over, and the card landed at 106 under a 108 rung - which the rung then took back in ONE frame at the end of every growth. It showed only as a 2px snap in a frame-by-frame WebKit trace, 106 -> 108.

​

A scroll event is not the reader, so do not decide from one

1. Its own write. scroll is delivered after the write, and on the phone a turn above had reflowed taller in between, so the handler read the thread 24 short and released it. Headless WebKit delivered the event first and never showed it.
2. A clamp. Tapping the bar hid the disclaimer, the thread’s box grew 558 -> 596, and the browser clamped scrollTop 746 -> 708. Separately, the field’s autosize sets height: auto for a moment, the band shrinks, and the thread clamps to that transient end - 326 -> 302 while it was 666 tall. Either way the event reads as a reader scrolling up.
3. The patch for the first swallowed the reader. “Ignore a scroll at the position the pin wrote” also ignored the reader’s scroll BACK to the end, which lands on the same value, so after one round trip the pin never re-armed and the next tap left the thread 60 short. Found by the adversarial review, not by the author.

​

The simulator tool’s text action connects a hardware keyboard

​

Storybook and vitest are not the same React runtime

node -p "require('react-dom/package.json').version"           # 18.3.1
find node_modules -maxdepth 4 -path '*/react-dom/package.json' # one hit
grep -c inert node_modules/react-dom/cjs/react-dom.development.js  # 0

[...document.querySelectorAll('[id]')].map((e) => e.id).filter((i) => /^:r/i.test(i))  // []

​

When the two disagree, believe vitest

node -e "const R=require('react'),{renderToStaticMarkup:r}=require('react-dom/server');
  console.log(r(R.createElement('div',{inert:true})))"   # <div></div>  - dropped

/hover:bg-modulus-surface-hover/.test(el.className) // is the class in className?

const flatten = (list) => [...list].flatMap((r) => [r, ...(r.cssRules ? flatten(r.cssRules) : [])]);
[...document.styleSheets]
  .flatMap((s) => { try { return flatten(s.cssRules) } catch { return [] } })
  .filter((r) => r.selectorText?.includes('bg-modulus-surface-hover'));

​

Layout

​

READ THE REGIME BEFORE READING ANY FIGURE BELOW

• border-subtle is excluded whether the border identifies or reinforces. It measures 1.11 over surface-page and 1.06 over surface-card and surface-raised on the selected-plus-hover composite. A border that close to its background reinforces nothing, so identification never comes into it. IDENTITY CLAIM, NOW FALSE: this used to read “at 1.00 it is not insufficient, it is INVISIBLE - exactly the composite colour”. That was exact pre-v3.44.0, where the composite landed on 225.88 against border-subtle’s own 226. They are no longer the same colour, so the border is now faintly visible rather than absent. The conclusion survives and the reason changed.
• border-strong fails as an IDENTIFIER ON THIS SURFACE, and only here. On the selected-plus-hover composite it measures 2.24 over surface-page and 2.36 over surface-card and surface-raised; on the selected surface WITHOUT hover, 2.44 / 2.57 / 2.57. All six are short of the 3.0 discrimination floor. On the three BARE surfaces it measures 3.07/3.23/3.23 in light and clears - its own $description records those figures. So the corollary quoted below still holds where it was written, and is superseded HERE rather than replaced, which is what CONTRAST_ACCEPTED means by “superseded for the selected case specifically”. Beside a fill that carries the state, as reinforcement, those figures are accepted.

​

Content starts on one edge; only backgrounds may pass it

​

Entry pages are anchored, not topped

​

One implementation, and it is EntryAnchor

​

The cluster is one shape, and Chat keeps a space it does not fill

​

The composer’s centre is the fixed thing, not its top edge

​

Two growth behaviours, and they are not the same act

​

The mobile composer ladder is a decision waiting, not a defect

​

The session page is an exception and stays one

​

Below md the page is topped, not anchored

​

The floor inverts the rule, and that is worth knowing

​

The placement grid is design-time only

​

Message / User has no token

​

The top offset can belong to a component, not the screen

THREAD CARRIES page/top ITSELF, so a page must not add it again

So a screen composing this must not also apply pt-modulus-page-top, or the thread starts 208 down.

• Titled page — the title sits page/top 104 from the viewport top, with the chrome row inside that 104. The screen applies 104 minus the chrome above it, never 104 itself.
• Entry screen — the greeting and composer cluster is anchored on ratio/entry-anchor with 104 as the floor, which is what pt-modulus-entry-anchor-offset computes.
• Delegated — a composed component owns the inset, and the screen binds nothing. The worked example is the Session story of Modulus/Screens/Chat/Page (chat.stories.tsx:564, rendered by SessionScreen at :578): it composes <ModulusThread>, applies no offset of its own, and is correct.

• Do not “fix” a screen that binds no offset by adding one. Check first whether something it composes already owns the inset. Adding a second is the 208 bug, not a repair.
• Do not add an offset alongside an owning component. The two stack, and nothing in the build catches it.

Thread carries pt-modulus-page-top 104 in both arms. This page already has a sticky header in that band.

​

Responsiveness

​

The 768 / 1024 conflict is permanent until components/ui is retired

​

The first-paint flash is a separate defect and does not depend on the number

​

Modals

​

Tailwind keys for the modal, tile, switch and sidebar tokens

​

Keys that resolve to nothing

getComputedStyle(el).width // or whichever property the class should set

const flatten = (list) => [...list].flatMap((r) => [r, ...(r.cssRules ? flatten(r.cssRules) : [])]);
[...document.styleSheets]
  .flatMap((s) => { try { return flatten(s.cssRules) } catch { return [] } })
  .filter((r) => r.selectorText === '.w-modulus-modal-sm');

​

The silent-resolution family, of which the above is one member

​

A shared stylesheet’s shorthand deletes the consumer’s own declaration

• A shorthand is a claim over the whole property. Two stylesheets may share an element only if at most one of them declares any given shorthand. Longhands do not rescue it — measured in both orders — whenever both sheets need the same longhand, which for transition-property they always do.
• Equal specificity plus split ownership means the result is a function of the importer, not of the component. That is why a story file could make one component behave two ways, and why the fix cannot be “fix the order”: the sheets are destined for app/layout.tsx, where the order changes again.
• The repair moves the shared property into ONE declaration and has each consumer supply only the part that genuinely differs — here --modulus-knob-travel-property, the property name, with the timing shared. That failure is then total rather than partial (transition-property: all at 0s if a consumer omits it), so it is guarded by an assertion in __tests__/knob-motion-import.test.ts rather than by a default: every candidate fallback is worse than the check, var(--x, none) invalidating the declaration exactly as no fallback does, and var(--x, width) silently making the 150ms release ramp 200ms.

​

A whole-group spread mints a utility for every leaf, including the nonsense ones

​

A group-level $type is invisible to a leaf-level filter

​

Assertion 17, and the group that had no key at all

17. Every token group in the exported collections has a Tailwind key
      -> 1 group(s) with a CSS variable but no Tailwind key: layout/sidebar.

• It checks groups, not tokens. The config consumes whole groups through modulusGroup, so a new leaf inside a wired-up group needs no config change and correctly does not fail. A new group always fails, which is the case it exists for. When Figma adds one, expect this to go red — that is the check working, not a bug in it.
• It reads tailwind.config.ts as text, with comments stripped, so a group merely named in the prose above a theme.extend block does not count as a reference. Stripping can only remove a reference, never invent one, so it cannot produce a false pass.
• Exemptions are a decision and carry their reason. TAILWIND_KEY_EXEMPT is a Map from collection/group to why it has no key. It currently holds exactly two entries: layout/breakpoint, because theme.screens replaces the Tailwind defaults rather than extending them and is frozen; and figma-only/card, because EXCLUDED_COLLECTIONS drops that whole collection from code export so it has no CSS variable either. Adding an entry is how you say “deliberately no key” — but it needs the reason the rule above demands, and a stale entry naming a group the token file no longer has fails the assertion too, so the exemption list cannot rot.

​

Status indicator semantics

• A ring means unsaved data.
• A pulsing filled disc means a connection or load is running.
• A filled positive disc with a knocked-out tick means saved.

• status-pending at 0.65 over surface-selected over surface-raised in dark measures 2.79. That figure is CURRENT, not inherited - under pre-v3.44.0 values the same placement was 3.64, so it belongs to this regime and not the old one.
• 70 DOES NOT CLEAR 3:1, and this said it did. It measures 2.9972. The first integer opacity that clears is 71, at 3.0393. The claim survived only because 2.9972 rounds to 3.00 at two decimal places, which is the rounding this file’s own ratchet note warns about in the other direction. The floor stays 70 by decision rather than by arithmetic, and that is now what this says.
• A selected AND hovered row there measures 2.6753 at 0.70, not the 2.52 recorded here, and clears 3:1 at opacity 80 (3.0268) rather than 86 - at 86 it is 3.2523. The “fourteen-point swing” was derived from the 86 and goes with it; the real swing from 70 to 80 is ten points.

​

Shadows

​

Figma-only scaffolding

​

When to stop and ask

• A token does not exist for a value a component needs
• A design calls for editing a frozen file. The list is under Read-only. Do not edit these files. in the root CLAUDE.md, alongside the scoping rules this file’s Hard rules restate
• A name would collide with the existing system
• The Figma component and the token file disagree

​

Recorded reasons

• removed on 12 Aug 2026 on instruction: "<quote>" - a dated quote
• see 4a84c40 / PR #3671 - a citation
• the reason is not recorded - the honest form when there is no source

• on the design owner's instruction - names an authority, cites no record
• because the panel separates by its fill alone - supplies a rationale that was never given
• X was invoked to justify Y, and Y then justified Z - a causal chain assembled from two unrelated facts
• a quote that stops before the sentence which qualifies it. A truncated quote is worse than no citation, because it carries the authority of the source while reversing what the source says, and the reader has no reason to go and check a claim that already looks sourced.

1. history-panel.tsx, 12 Aug 2026. “removed on the design owner’s instruction: the panel separates from the content beside it by its surface-page fill alone.” A real instruction existed and said “Remove the panel’s left border entirely” - the left border, with no reason given. The comment widened it to every edge, invented the rationale, and dressed a one-line directive as a ruling. It was then cited back as a recorded decision in four later places, and CodeRabbit absorbed one into its knowledge base.
2. history-panel.stories.tsx, 2 Sep 2026. “The panel separates by fill.” The panel’s fill is surface-page, which is the page’s fill. The seam measures 1.0000:1 in both modes. There is no separation at all.
3. A generated review claim, 2 Sep 2026. “Symmetry was invoked to justify the width binding, and the width binding was then cited to justify separating by fill instead of by border.” No text in the repo says the second half. The symmetry argument is about width parity and mentions no edge at all.
4. A truncated quote of this very file, 2 Sep 2026. A review quoted the Responsiveness section as saying collapsing is a “user action only” and “never a width threshold”, then concluded that production violates it, citing the auto-collapse below 1200px in components/sidebar.tsx. The quote stopped one sentence early. The next sentence reads: “The forced rail between md and lg is not a counter-example: that is the shell answering a viewport it cannot fit, not the nav deciding on its own.” The rule explicitly permits the thing the review flagged as a breach of it.
5. The design owner’s own claim about a check, 3 Sep 2026. “Assertion 25 sitting red across eleven token versions” - offered as the argument for wiring tokens:verify into CI. Assertion 25 passes: exit 0, zero FAIL lines, 31 of 31. It was also introduced on 2026-08-31 in the Modulus rename, and tokens/modulus-design-tokens.json has no commits before that date, so there was no eleven-version window for it to be red across. Both the number and the duration were invented, most likely conflated with the 19 stale contrast claims, where a check genuinely WAS red and nothing ran it. This one is listed because it is the owner’s, and a rule that only catches other people’s claims is not being applied. The shape was identical to the four above: a claim about what happened, carrying a specific citation, plausible enough to pass unchecked. The underlying argument was sound and CI was wired up anyway. Only the evidence for it was fabricated, which is precisely what makes the pattern hard to see.

​

The same rule applied to an automated check

​

A missing signal read as a clean result

1. text.includes passing on the wrong rule. Assertion 32 v1, above. The search could not distinguish “the twin is present” from “some substring resembling it is present”, so a missing twin read as a satisfied invariant. The citation was a search that could not come back empty.
2. A read tool reporting a miss inside its payload. A node lookup that found nothing returned that as ordinary content rather than as an error, so a caller asking whether the call had FAILED saw that it succeeded. The absence arrived dressed as an answer. Recorded here for the first time - it had no entry before this one.
3. Absence of a PASS line read as absence of a failure. Negative-testing the component-manifest assertions, 3 Sep 2026. Fourteen of fifteen deliberate mutations were caught and the fifteenth reported MISSED. The assertion was fine. The mutation had broken the module’s SYNTAX - a regex '[^']*' stopped at an escaped apostrophe inside the string it was rewriting - so nothing ran, no FAIL line was printed, and the harness’s “is the target among the failures?” test could not tell a silent crash from an assertion that declined to fire.
4. A PASS line from an assertion that never ran. An assertion written for the component manifest, 4 Sep 2026. It reported the full count passed and was inert for TWO independent reasons, either of which alone was enough:
   • Placed after the reporting loop. check() pushes to results, and the loop that prints each line and increments failed had already finished. Its result could neither print nor affect the exit code. The count line, printed later still, was arithmetically true and totally uninformative.
   • Calling two helpers that do not exist. Both were invented at the keyboard. Had the check run, each would have thrown ReferenceError, which check() catches as a failure - so the placement bug was masking a second bug that would otherwise have been loud.
   What caught it was checking whether the helpers existed, not reading the output: grep -cE "(const|function) <name>" returned 0 for both. That is the transferable part. A passing check whose helpers do not exist is passing for the wrong reason, and the output cannot tell you so, because a green line is exactly what an inert check produces. Recorded without softening because of where it happened: on a change whose entire subject was checks that cannot fail, in the file that catalogues them. Writing one while documenting them is evidence about how easy the shape is to produce, not an embarrassment to leave out.

1. Place it where it gates. In verify-figma-axes.mjs and verify-tokens.mjs that means above the Report section, so the result is in results before the print loop reads them and before failed is counted. Verify by looking for the assertion’s own PASS/FAIL line in the output, not the summary count, which stays true while saying nothing.
2. Prove it fails. Mutate the thing it guards and confirm the assertion names it, with a non-zero exit. An assertion never observed failing is indistinguishable from one that cannot.

​

The inverse: a signal arriving from the wrong place

1. The marker count, and it is the worst of these because it overrode someone who was right. grep -c "data-theme-variant='modulus'" over the ten component files returned at least 1 for every one, so all ten were reported as stamping their own root. None did. button.tsx’s single occurrence is at line 19, inside the header comment - “carrying data-theme-variant='modulus'. Outside that scope every…” - and Chip’s and IconButton’s are the same sentence. A subagent had reported those three as unstamped and was corrected on the strength of this count; the count was then published in an issue before anyone checked it. Matching the attribute as CODE - a line that is only the attribute - gives the real answer: on staging at that moment, zero roots carried it, and row-actions.tsx’s one marker was on its portal rather than its root.
2. The test count. A test file was described as having 33 tests. Running it gives 14 - six components times two cases, plus two compound-selector cases. The number had been asserted rather than measured, and the arithmetic that would have caught it is the arithmetic the file’s own structure hands you.
3. The icon count, wrong three times running before the shape was named. Same cause each time, which is what makes it worth listing beside the other two: a repeated wrong number is evidence about the METHOD, not about whoever was unlucky with it.
4. A file read from a CHECKOUT, reported as a fact about the BRANCH. Twice on 3 Sep 2026, and both times the answer looked definitive. Asked whether tokens:verify passed on staging, the run was npm run tokens:verify from a worktree on another branch with only staging’s ci.yml checked out - so the reported 32/32 was that branch’s script, not staging’s. Asked whether control/composer/max-lines existed, the token file was read from a worktree still on an older branch, and the answer came back “not present, v3.42.0” while staging had it at v3.43.0. A third read landed in a DIFFERENT session’s worktree and was right only by luck, that branch being the one that introduced the token. A file read from a checkout is a claim about that checkout, not about the branch, and the two diverge silently the moment anything merges. There is no error and no warning; the file simply says something else. Use git show <ref>:<path>, or git archive <ref> into a temporary directory when a whole tree is needed - and treat the working directory as a claim about nothing but itself.
5. A tsc filter that could not see the file the commit added, and the only one of these to reach CI. Local typecheck was run as npx tsc --noEmit | grep -E "button|chip|row-actions" and reported clean. CI’s Typecheck job then failed on two TS2322s in __tests__/theme-variant-aschild.test.tsx - a path containing none of those three substrings, so the filter discarded the errors before anyone saw them. The commit added that file. A second blind check compounded it: vitest does not typecheck, so twelve green tests said nothing about types. The runtime assertions were correct throughout; the file simply did not compile. THE SECOND INSTANCE, 8 Sep 2026, generalises both halves. A filter is not what failed there; a filter naming the SUBJECT was. The inverted method above - run whole, assert no error names a file in the diff - was applied to a RowActions fix and immediately named __tests__/row-actions-nested-contrast.test.tsx: onPin does not exist on that component (onPinnedChange does) and children is required. A filter spelling row-actions would have caught both by luck of the filename. A filter naming the component under test - RowActions, text-secondary, the recipe - would not have, because the errors were in the harness, not in the subject. The general case, and the reason the inverted method is the rule rather than a longer filter:

   A filter naming the subject misses the harness. The files a change breaks include the ones that TEST it, and those name the subject only by convention. Assert over the DIFF, which contains both, rather than over a pattern describing what you think you touched.

   And the vitest half is the general case too, not a detail of that one commit: on 8 Sep the suite reported 48 passed on the very file tsc was failing, in the same minute.

   A green test suite says nothing about whether the file compiles. vitest strips types rather than checking them, so passing assertions and a non-compiling file are fully compatible. Neither is evidence about the other, and reporting a green suite as though it covered types is the same move as citing a gate for a property it does not test - see the gate-as-evidence entry below.

6. A git ls-tree pathspec that matched no files, read as “the system has no precedent.” Asked on 4 Sep 2026 whether any component animates anything, the search was git ls-tree -r origin/staging -- 'components/modulus/*.tsx' feeding a per-file grep. The pathspec matched nothing, so every grep ran over nothing, and the empty output was reported as “no component uses any motion class - the build would be the first, with no precedent.” segmented.tsx carried duration-modulus-base ease-modulus-standard in two places at the time, and the control case that would have exposed it - a pattern known to match - was never run. The cost was the precedent itself, not the wrong claim. segmented.tsx had already recorded, at lines 326-328, “at fast the text lands first and the pill catches up” - the measured description of a bug the build then went on to make: a chip whose fill ran at fast 150 while its chevron turned at base 200, landing one state change in two pieces 50ms apart. The house had met this and written it down. A working search would have handed over the answer instead of the bug. An empty result has two explanations, and “it does not exist” is the less likely one. Run the pattern against a case known to match before believing the emptiness.
7. THREE PROSE HITS IN ONE TRACE, ON THE SAME QUESTION, 2026-09-21. Asked which routes reach components/ui/responsive-dialog.tsx, a git grep -l over symbol names returned three files that do not use it: app/(app)/layout.tsx appeared to render <PlaidLinkButton /> (it is a comment explaining where the singleton really lives), and drawer.tsx and research-ideas.tsx appeared to import modal-showcase (both prose). A fourth, components/modulus/modal-showcase.tsx, appeared to consume responsive-dialog and does not - its mention sits in a comment about the 768/1024 conflict itself. TWO WERE CAUGHT AND ONE SHIPPED INTO A REPORT, which is the part worth recording: the two obviously-wrong ones were checked because a product file importing a Storybook showcase looked odd, and the plausible one went through unexamined and was corrected afterwards by a second pass. Plausible is what makes a prose hit dangerous, not obscurity. The habit that fixes all four is the same and costs nothing: match the CODE FORM. ^import and ^\s*<Component return the real consumers; a bare symbol grep returns the documentation as well, and this repo’s files carry more prose than code. Density is the reason it keeps happening here rather than a run of bad luck. The worst offenders for false hits are the best-documented files, so the pattern gets worse exactly where the header is longest.

• Match the code form, not the token. An attribute is a line that is only that attribute, or a hit inside JSX; a bare string search over a file that documents itself will find the documentation. The same goes for a class, an import, or a call - these files carry long headers, so prose hits outnumber code hits in the ones with the least code.
• Print the matches, never just the count. grep -c throws away the only evidence that would show the count is wrong. grep -n costs nothing and makes instance 1 self-evident on sight.
• When a count contradicts another source, diff the two SETS. Instance 1 was a count contradicting a person. The count won because it looked like a measurement. Listing both sides - which files, which lines - decides it in one step and cannot be won by whichever number sounds more precise.

git diff --name-only origin/staging...HEAD > /tmp/changed
npx tsc --noEmit 2>&1 | grep -E 'error TS' > /tmp/errs
while read -r f; do
  grep -qF "$f" /tmp/errs && echo "ERRORS IN $f"
done < /tmp/changed

​

A gate offered as evidence for a claim the gate does not test

• The 215/212 and 77/80 are exact. Verified.
• “Every recorded figure stays exact” is TRUE of the token file’s own canonical Contrast X light, Y dark, worst case claims.
• It is FALSE of CONTRAST_ACCEPTED in scripts/modulus-tokens/verify-tokens.mjs, which is the one artefact in the repo that had recorded the STACK as its worst background. Fifteen of its seventeen text and border entries name the stack in their // worst: comment.

​

A stale figure with live arithmetic beside it

240 x (1 - 15/255) = 225.88

Arithmetic shown beside a figure proves the figure FOLLOWS FROM ITS OPERANDS. It says nothing about whether the operands are current. It verifies the DERIVATION and not the CLAIM.

Round for display, never for comparison. A figure shown at 2dp against a threshold of 3.0 has half a unit of its last displayed digit in which to be wrong, and it is silent in exactly the band where it matters most - AT the threshold. Compare at full precision and display the rounded value beside it, never the rounded value alone.

A measurement is evidence about a WORKING TREE AT AN INSTANT, not about a component. Your own edit ages it exactly like anyone else’s. Re-derive after every change you make between taking a figure and publishing it - especially a revert, which reads as “undoing” and therefore as “returning to the state the measurement described”, when it does the opposite if the measurement was taken from the changed state.

Editing a description to match the code, and then editing the code, is two correct acts that compose into a wrong record. Neither commit is a mistake on its own; the defect is entirely in the ORDER and in nobody re-reading the first after the second. When a change moves a binding, grep the token file and this file for the OLD rung name before committing it - the prose that cited it is exactly the prose that is now wrong, and it will not conflict, fail a test, or show up in a diff you are reading.

Re-deriving a figure checks whether it FOLLOWS from today’s operands. It does not check whether it ever followed from any. Where a derivation is written out, count its terms against the RENDERED element once - gaps, borders and padding included - instead of re-resolving the rungs it names. A derivation that omits a term is wrong at every value of the terms it keeps, and re-resolving those terms forever will never say so.

​

The one sentence all of these reduce to

A search can prove presence and never absence. A negative result is the BEGINNING of the check, not its end.

A check attached to a claim is not evidence for the claim unless it can fail in the direction the claim runs. A one-directional ratchet, a correct derivation over dead operands, and a figure rounded to a coarser precision than its own threshold all pass while saying nothing.

​

Every gate here checks SHAPE, and every divergence has been a VALUE

Before adding a gate, say which of the claim’s terms it evaluates. If the answer is a NAME, it cannot see a value move, and every divergence recorded in this file so far has been a value.

​

Merging two of the same kind

modulusCn('p-4', 'p-2', 'hint-1')  =>  'p-2 hint-1'

​

Reordering alone is not the fix, because undefined after a spread DELETES

{...props}
aria-hidden={closedBox ? true : props['aria-hidden']}
inert={modulusInert(closedBox || Boolean(props.inert))}

​

Why this is a rule and not a comment

a utility in the same conflict group as another would be dropped silently, and the description it names would stop being announced

​

Scoping from the variant

[data-theme-variant='modulus'] .modulus-surface-noise,
[data-theme-variant='modulus'].modulus-surface-noise {

​

Why Storybook cannot catch any of this

1. A component that does not stamp the scope on its own root still renders correctly in Storybook, because the decorator supplies it. The variables only fail to resolve where no ancestor has it.
2. A descendant-only selector still matches in Storybook for the same reason. It only stops matching where the root is the scope.