> ## Documentation Index > Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt > Use this file to discover all available pages before exploring further. # CLAUDE # Modulus design system Components for the redesigned Silvia product and landing page. Built from a Figma library and a DTCG token file, tested against the existing system via PostHog. Read the root `CLAUDE.md` first: it lists the frozen files and the scoping rules that apply here. ## Figma file ``` 4Audgs6XUkkKEa1KsyZZ3K ``` This is the Modulus design system library. The Figma MCP read tools - `get_metadata`, `get_design_context`, `get_screenshot`, `get_variable_defs` - all require a `fileKey`, and this is it. **Diff a component against Figma before opening its PR.** The node ids that appear in component headers (`Figma component set 130:50`) resolve against this file and nowhere else. Recorded here because it was missing: the only Figma key anywhere in the repo was `2V9wEQpWOOlmWskxgh3MX9` in `components/landing-page-v3.tsx`, which is the landing page file and returns no edit access. Card was therefore built from a written spec with no way to read the real component, which is exactly the situation this line exists to prevent repeating. ## Source of truth `modulus-design-tokens.json` is authoritative. Every value in these components resolves to a token from it. Never hardcode a colour, size, radius, duration or opacity, and never reach for a value that is close enough. **The token file is maintained by hand outside the repo and handed over.** It is not generated, and there is no design-side file to reconcile against. An earlier version of this line said "generated in Figma", which is wrong and cost time: it invites the conclusion that a stale copy should be fixed at a source that does not exist. Do not edit it to fix a component. If a component needs a value the tokens do not have, stop and say so. Because it is handed over, the copy being edited can fall behind `staging`, which has happened repeatedly, each time silently reverting corrections made in the repo. **Read the current file before editing it.** Which command depends on where the copy lives, and getting that wrong is its own failure mode. **Inside the repo**, do not fetch at all. Git already has it, with no network and no chance of writing a stray file: ```bash theme={null} git show origin/staging:tokens/modulus-design-tokens.json ``` **For a copy outside the repo**, fetch over the API and redirect to that copy's own full path, never a bare filename: ```bash theme={null} 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 ``` **The bare filename is the trap.** Run with `> modulus-design-tokens.json` from the repo root and it writes a root-level copy, leaving `tokens/modulus-design-tokens.json` untouched. Everything then reads correctly while the authoritative file is stale, which is the same silent-resolution shape recorded further down: the command succeeded, the file exists, and the wrong one is being edited. Two notes on the API route. The bare `raw.githubusercontent.com` URL returns 404 rather than 401 on this private repo, which reads as "no such file" rather than "not authorised". And `gh` supplies the auth from an existing login, so there is no token to manage. ### Edit the token file as TEXT, never through a JSON round-trip `JSON.parse` followed by `JSON.stringify` does not preserve this file. JavaScript objects order integer-like keys numerically AHEAD of string keys, whatever the insertion order, so a round-trip silently rewrites every group that mixes the two. `primitive/space` holds `2`, `3`, `4` alongside `half` and `2half`, and it comes back with `half` and `2half` moved: measured at 36 lines of churn from an edit that changed three values. **The authored order carries meaning, which is what makes this more than churn.** `primitive/space` is written `$type, 0, half, 1, 2, 2half, 3, …, 26`: `half` sits between `0` and `1` because 2px sits between them, and `2half` between `2` and `3` for the same reason. A round-trip pulls every integer-like key to the front, so all three string keys land after `26` and the off-grid steps stop sitting next to the rungs they are off-grid FROM. Measured, before and after: ``` 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 ``` `$type` is the sharpest of the three, and it is easy to miss because it is not a rung. It declares the group's type and is written FIRST for that reason; a round-trip moves it from index 0 to index 16, behind every numeric step it governs. So the reader scanning for what kind of token this group holds now finds that declaration buried among the values it applies to. Nothing is lost that a parser would notice: the key SET is identical, and so are every value, the leaf count and the parsed object. Only the order moves, which is why this is worth writing down rather than discovering twice. **Measure both sides with the same command.** An earlier version of the listing above showed `half 2half` moving and no `$type` at all, which implied the key had been dropped. It had not: the authored side was read from the raw text and the round-trip side through `Object.keys(...).filter(k => !k.startsWith("$"))`, so one side hid what the other showed. A before-and-after whose halves come from different code paths reports a difference the data does not contain, and it reads exactly like a real finding. **The file is maintained by hand outside the repo**, so a reordering handover fights every future diff on both sides: the next handover arrives looking like it changed hundreds of lines, with the real edit invisible inside the churn. So edit the raw text in place, and **assert the key sequence is byte-identical afterward** rather than trusting that it is: ```bash theme={null} 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; ' ``` The non-zero exit is not decoration. An earlier version of this snippet printed `NO` and exited 0, so wiring it into CI would have produced a job that reports the reorder in its log and passes anyway. That is the shape this file is about, and it shipped inside the guard against it: **a check that states its own failure in prose but not in its exit code is not a check.** The rule two sections down says to prove a new assertion fails with a non-zero exit; this snippet was written after that rule and still did not obey it. **This check must read the raw text, and must NOT parse either side.** The suggestion to "parse both documents and compare their key sequences" arrives looking like a robustness fix and is the one change that destroys the check: `JSON.parse` is the operation being guarded against, so parsing both sides normalises both into the same order and the comparison returns YES for every input, including a file that has just been fully reordered. Measured, on this file against a round-tripped copy of itself: the anchored raw comparison reports the reorder, and a parsed comparison cannot report it at all. A guard that launders its input through the very transform it exists to detect is the canonical check that cannot fail. A leaf-count check is not a substitute. Reordering preserves the count, the parsed object and every value, so counting leaves reports a clean result for a file that has been rewritten. That is the same shape as the section below. ### Counting `$extensions` keys: count keys, not occurrences `com.modulus.` appears **eight** times in the token file and only **six** of those are structural `$extensions` keys. The other two are prose, inside the file-level `$description` that documents the convention. | Where | Count | Load-bearing | | - | - | - | | `$extensions` keys, `unit` and `cssTransform`, on each of `disabled-opacity`, `noise-opacity`, `pulse-floor` | 6 | **yes** | | Prose in the file-level `$description` | 2 | no | This matters because a count is exactly the kind of check someone writes, and a check on the total would pass while a structural key was deleted and a prose mention added; the two errors cancel. The structural count is the one that would break the pipeline. It is also the number that moves. This note first read "five, not seven", which went stale one commit later when `pulse-floor` gained its missing `unit`. **So do not assert either number.** Assert the invariant instead: every token carrying `cssTransform` also carries `unit`, and the reverse. That holds at any count, which a literal does not. ### The three opacity tokens, and the asymmetry that was there `semantic/effect` holds the only tokens where Figma and CSS disagree. Figma stores opacity as percent and the importer writes values verbatim, so each is stored Figma-native and divided by 100 at build time: | Token | `$value` | `unit` | `cssTransform` | Emits | | - | - | - | - | - | | `disabled-opacity` | 60 | `percent` | `divideBy100` | `0.6` light, `0.5` dark | | `noise-opacity` | 4 | `percent` | `divideBy100` | `0` light, `0.04` dark | | `pulse-floor` | 70 | `percent` | `divideBy100` | `0.7` | `pulse-floor` carried the transform **without** the unit until v3.43.0, against the file's own convention that a token whose Figma and CSS values disagree carries both. The token was what was wrong rather than the convention: it is a percent by every observable property: 70 stored, `divideBy100` applied, `0.7` emitted, two siblings of identical shape annotated. Fixed by adding `"com.modulus.unit": "percent"`. **It survived, up to v3.43.0, because nothing read `unit`.** Every consumer read `cssTransform` and only that: `verify-tokens.mjs:1408`, `foundations/tokens.ts:531` and `:921`, and the emission record in `docs/modulus-tokens/`. The annotation was inert documentation, which is exactly how it drifted. **That is now historical. Assertion 24 reads `unit`** and asserts the pairing in both directions, so the gap is closed rather than merely described: a transform without a unit fails, and a unit without a transform fails. Both are negative-tested. `verify-tokens.mjs` is no longer silent on the annotation. Worth knowing that assertion 22 already anticipated the annotation being unreliable, and its own comment says so: it derives its subjects from `cssTransform` **OR** membership of `semantic/effect`, because "a token stops being an opacity by moving, not by losing an annotation". That fallback is why deleting the transform does not create a hole, and equally why a missing `unit` was invisible, since `unit` was not part of that derivation at all. **Note what happened to this passage, because it is the third instance of the shape it describes.** It read "nothing reads `unit`, so no assertion could fire" and was true when written. Assertion 24 landed four commits later in the same pull request and made it false, and it was a reviewer rather than a check that noticed. The count note above went stale the same way, one commit after being written. So: **when writing that nothing checks something, check whether you are about to add the check.** A note describing an absence is only true until someone fills it, and the someone is usually you, in the same branch. ## 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/`, `Modulus/Components//` and `Modulus/Screens//`. 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 **Every exported identifier carries the prefix.** Components, cva recipes and prop types: `ModulusButton`, `modulusButtonVariants`, `ModulusButtonProps`. Where a component is multi-part, every part takes it: all six of Card's, all three of NavGroup's. The `displayName` requirement is separate and narrower. It applies to exported COMPONENTS only, where it matches the export string for string, because a prop type has no runtime value to hang one on. This is the `modulusCn` rule applied to components, and for the reason recorded there. The filename disambiguates the path; only the export name disambiguates the call site. Be precise about what that buys, because it is easy to overstate. **Nothing enforces the prefix itself.** `next lint` is the only linter that runs, and neither `.eslintrc.json` nor `tsconfig.json` carries a naming rule, so a new export that omits the prefix is caught by review and by this document, not by a check. What the prefix does buy is that once the names are distinct, the accident it exists to prevent can no longer happen QUIETLY: `import { ModulusButton } from '@/components/ui/button'` is a compile error because that module has no such export, and so is `import { Button }` from ours. So "the two systems are never mixed in one file" stops being a convention a reader has to already know and becomes a failure at the import site. That is a narrower claim than the compiler enforcing the rule, and it is the true one. The collision is exact rather than theoretical. Measured against `components/ui/` at the time of writing, **nine identifiers clash**: `Button`, `buttonVariants` and `ButtonProps` from `components/ui/button.tsx`, and all six of `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent` and `CardFooter` from `components/ui/card.tsx`. An unprefixed `Button` in a second library is the thing that gets imported by accident, and the window opens the moment the file is on staging rather than at some later date. The house already prefixes a namespaced set this way: `components/silvia-status-indicator.tsx` exports `SilviaStatusIndicator`. **A recipe whose name does not place it folds the component in.** `fieldVariants` and `trackVariants` name nothing once prefixed, and a recipe nobody can place is the one that gets edited by mistake. So `modulusTextFieldFieldVariants`, `modulusSegmentedTrackVariants`, `modulusSegmentedTabVariants`. The doubled `Field` in the first is deliberate: `Field` is the Figma layer this recipe binds to, so keeping it stays greppable against Figma. **Where a component's internal identifier differs from its export, rename it too.** `SegmentedRoot` and `HistoryPanelRoot` exist because a generic component needs its `displayName` set before the `as` cast. An internal name that disagrees with its own `displayName` is the same confusion the prefix exists to remove. ### Scope: the component library, not `foundations/` **The set is fifteen components** as of 9 Sep 2026: ArtifactCard, Button, Card, Chip, Composer, EmptyState, HistoryPanel, HistoryRow, IconButton, NavGroupHeader, RowActions, Segmented, Sidebar, Tag, TextField. The number is the count of `components/modulus/*.tsx` less the story files, so it is checkable in one command rather than trusted from this list, and it is the list that goes stale first. The rule covers the components in `components/modulus/` and their recipes and types. **`components/modulus/foundations/` is exempt**, and the exemption is a decision rather than an oversight. `foundations/blocks.tsx` exports 23 unprefixed functions (`Scope`, `ColourRoles`, `ContrastTable` and the rest); `foundations/tokens.ts` exports 54 (`MODES`, `resolvedHex`, `colourGroups` and the rest). Both are documentation scaffolding rather than library surface. Their consumers, checked rather than assumed: * `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`. So the exemption does NOT rest on "no consumer outside `foundations/`" - there is one. It rests on the narrower and true thing: neither file exports an identifier that collides with anything in `components/ui/`, and no consumer is product code or a component call site, so no import can bind the wrong library. That is the harm the prefix exists to prevent, and it is absent here. Renaming 54 exports plus a script that imports them would be an API break with no collision behind it, and they are already on staging. The condition that would end the exemption is therefore not "gains any external consumer", which is already the case. It is either of: a foundations export starts being imported by product code, or one of them takes a name that clashes with `components/ui/`. Prefix at that point. ### 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 `