component-css-modules-migration

name	component-css-modules-migration
description	Migrate a click-ui component from styled-components to CSS Modules with byte-for-byte visual regression coverage. Use whenever a component still uses styled-components and is on the CSS Modules migration list.

Component CSS Modules Migration

A repeatable procedure for migrating one click-ui component at a time from styled-components to CSS Modules + cva / cn. The pattern was first executed end-to-end in PR #1034 (ButtonGroup), which is the canonical reference if anything here is ambiguous.

The procedure is built around a strong, single claim: the migration commit changes nothing visible. Visual regression tests captured against the styled-components rendering must pass byte-for-byte against the CSS Modules rendering. No tolerance for "looks the same"; the snapshots either pass or they don't.

Scope rule (hard line)

The migration PR is a pure styling refactor. Everything below is out of scope even when tempting:

• ARIA refinements (adding aria-disabled, removing redundant role="button", plumbing aria-label)
• Adding HTML attributes (type="button", etc.)
• CSS correctness fixes (:hover:not(:disabled), :focus-visible outlines, explicit disabled+active rules that the original didn't have)
• Consumer updates (e.g. adding aria-label="..." to existing consumers)
• New props or JSDoc

If the original styled-components has a bug (hover firing on disabled, missing focus ring, wrong disabled+active color), the migration preserves the bug. Fix it in a separate PR after the migration lands.

The reason this rule exists: the visual regression test is credible only because the migration commit changed nothing visible. If you bundle in a "small" a11y improvement, snapshots regenerate, and the "byte-for-byte" guarantee evaporates. The rule also makes the migration mechanical — there are no judgment calls about which improvements to include.

The only collateral change you may need: a narrow TypeScript widening (e.g. HTMLAttributes<HTMLButtonElement> → ButtonHTMLAttributes<HTMLButtonElement>) when the new test stories need a prop like disabled to typecheck. That's pure TS, no runtime effect — include it in the baseline commit and call it out.

Prerequisites

1. The component still uses styled-components (check src/components/<Name>/<Name>.tsx).
2. The component's design tokens already exist as CSS variables in packages/design-tokens/dist/tokens.css (search for --click-<component-name>-*).
3. The Button precedent is readable: src/components/Button/Button.tsx and src/components/Button/Button.module.css.
4. yarn test:visual and yarn test:visual:update work (they invoke .scripts/bash/playwright-docker, which runs Playwright inside a Linux container; both take a component name to scope the run, e.g. yarn test:visual <Name>). If they don't work, fix the tooling first as its own commit — don't work around it locally.

Commit structure

Two commits. Each must leave main green on its own.

#	Subject	One-line purpose
1	test(<Name>): add visual regression baseline before CSS Modules migration	Capture the current styled-components rendering as snapshots.
2	chore(<Name>): migrate styling from styled-components to CSS Modules	Replace styled-components with .module.css + cva/cn. Snapshots from #1 still pass byte-for-byte.

If you need to fix repo tooling (broken script, version mismatch) to even run yarn test:visual, that goes in its own prep commit before commit 1 — e.g. chore(test:visual): <description>. Don't bundle tooling fixes into the migration.

Commit 1 — Visual regression baseline

Files

• src/components/<Name>/<Name>.stories.tsx — Extend the existing stories. There must be exactly one named story per visual variant the spec wants to screenshot. Reuse the structure from src/components/ButtonGroup/ButtonGroup.stories.tsx. Required scenarios: each type variant, selected/active state, disabled state (including disabled+active if applicable), fill-width / size variants, multi-select if applicable.

  • Each story must render the real component, via args (preferred) or a render that returns the actual component. Never define a *Harness/wrapper component and render it inside render (e.g. render: () => <FooHarness size="xs" />). Storybook's "Show code" copies the story body verbatim, so a harness makes the copyable snippet <FooHarness …> instead of the real <Foo …> a consumer would write.
  • Put any surrounding styling in a decorator, not in the story body. When a story needs padding, a backdrop, or (for invisible primitives like Spacer/Separator) a contrasting block to make the component measurable, move that wrapper into a decorators entry — decorators are not included in "Show code". Use a meta-level decorator when every story in the file shares the wrapper (see src/components/Alert/Alert.stories.tsx); use a story-level decorator (a shared Decorator const spread into each story's decorators) when only some stories need it and others have bespoke renders (see src/components/Icon/Icon.stories.tsx, whose Playground and Icons gallery must stay unwrapped). A decorator can read the story's args via its second argument ((Story, { args }) => …) to vary layout per story (see src/components/Separator/Separator.stories.tsx).
  • The decorator carries the data-testid="<name>-harness" that the Playwright spec screenshots. Keep the exact same test-id, element structure, and inline styles the wrapper had — the screenshot region and the snapshots stay byte-for-byte, and the spec's harnessLocator needs no change.

• tests/<area>/<name>.spec.ts — New Playwright spec. Pick <area> carefully:

  • Never put component specs under tests/utils/. That folder is reserved for shared test helpers like (). Mixing specs and helpers there confuses both human readers and Copilot reviewers.

Files NOT touched in this commit

• <Name>.tsx — the component stays on styled-components.
• <Name>.test.tsx — unit tests untouched.
• Any consumer file.
• Any other tests/**/*.spec.ts file unless the new stories forced an incidental change (rare; if so, put it in its own commit before this one).

Snapshot generation rules

Always generate snapshots fresh via:

yarn test:visual:update <Name>              # e.g. yarn test:visual:update CodeBlock
yarn test:visual:update tests/<area>/<name>.spec.ts   # equivalent, pinned to one file

Both commands run Playwright inside the Linux Docker container (.scripts/bash/playwright-docker), so snapshots are named -chromium-linux.png and match what CI generates on ubuntu-latest. The same snapshots work on any host OS because the runtime is normalized via Docker; you do not need platform-agnostic snapshots.

The name form resolves through the @covers directives (see .scripts/js/resolve-visual-specs) and is the faster way to iterate — the full suite takes ~20 minutes. Use the path form when you need exactly one spec: a name reaches every spec covering that component, so yarn test:visual Button also runs overview.spec.ts and splitbutton.spec.ts. That is fine while iterating, but the acceptance gates below name the path so "zero regenerations" is a claim about this spec alone. yarn test:visual names lists every name available.

Never cherry-pick PNG baselines from another branch or PR. They were captured against a different point in time and may hide drift that landed on main since.

After generating, run yarn test:visual <Name> to confirm green, then git add everything together (stories + spec + snapshots) and commit.

Acceptance

• yarn test:visual tests/<area>/<name>.spec.ts — all green.
• yarn test <Name> — unit tests pass (nothing changed for them).
• yarn build — succeeds.

Commit 2 — CSS Modules migration

Files

• src/components/<Name>/<Name>.module.css — New file. Translates the styled-components rules into CSS. Concrete rules:

  • One CSS variable per theme.click.* reference. Find each ${({ theme }) => theme.click.x.y.z} in the styled-components source and replace with var(--click-x-y-z). The token names already exist in packages/design-tokens/dist/tokens.css.
  • Match the existing selectors exactly. If the source has &:hover (no :not(:disabled) qualifier), write .component:hover — do NOT "improve" it to .component:hover:not(:disabled). If the source has no :focus-visible rule, don't add one. Preserving wrong behavior is the price of byte-for-byte verification.
  • Match cascade order. styled-components emits rules in source order. If the original has &[aria-pressed='true'] defined twice (once before :disabled, once after), the second appearance is doing real work via cascade — replicate that ordering.
  • Use BEM naming per the regex in stylelint.config.js: block, block__element, block_modifier, block_modifier_value. Modifier values use underscores, not dashes.
  • Every block and element must have a base class — even when it has no own styles. A modifier can only exist to modify something, so .block_fill-width requires .block, and .block__icon_size_sm requires .block__icon. Never emit a lone family of modifier classes (.accordion_fill-width with no .accordion, .external-icon_size_* with no .external-icon). This shows up in the TSX as the tell-tale cva('', { variants: … }) — an empty base string means the block/element has no base class. Always pass the base class as cva's first argument: cva(styles.block, { variants: … }). Two consequences:
    • Hoist any declaration shared by every modifier onto the base. If _indicator-dir_start and _indicator-dir_end both set user-select: none, that lives on , and the modifiers keep only what differs.
    Do apply a base class as a bare string literal in the TSX (); that emits an unscoped global class that matches nothing in the CSS Module. The base must be so it resolves to the scoped name.

Files NOT touched in this commit

• Stories, spec, and snapshots from commit 1 — they must not change.
• Unit tests.
• Any consumer file.
• <Name>.types.ts (unless commit 1 already touched it for typecheck reasons).

The byte-for-byte rule

Run yarn test:visual tests/<area>/<name>.spec.ts (the path form, so the result is about this spec and nothing else). Every snapshot must pass with zero regenerations. If even one fails:

1. The CSS doesn't match the styled-components rendering.
2. Open the failing snapshot side-by-side (yarn test:visual:report) and diff the actual vs expected.
3. Fix the CSS to match. Common culprits:
   • Wrong cascade order on conflicting rules → reorder.
   • Missing :disabled[aria-pressed='true'] (or similar) compound selector → add it back.
   • Token name typo → grep tokens.css for the correct CSS variable name.
4. Never regenerate the snapshot to make a "small" difference go away. That breaks the byte-for-byte guarantee and silently lets the migration drift visually.

The only legitimate reason to regenerate is if the snapshot in commit 1 itself was wrong (e.g. captured a flaky animation frame) — and in that case, you go back and fix commit 1, not roll the difference into commit 2.

Acceptance

• yarn test:visual tests/<area>/<name>.spec.ts — all green, zero snapshot changes.
• yarn test <Name> — unit tests pass unchanged.
• yarn lint:css and yarn lint:code — pass with no new errors.
• yarn build — succeeds.
• grep -r 'styled-components' src/components/<Name>/ — empty.
• Manual storybook side-by-side against the previous commit confirms visual parity.

Common pitfalls (from PR #1034)

• Scope creep in the CSS module file. Drafts from prior split PRs may include :hover:not(:disabled), :focus-visible:not(:disabled), or color: disabled-active rules. Audit every selector against the original styled-components and drop the additions.
• Wrong default mode for --update-snapshots. Playwright 1.50+ requires an explicit mode. yarn test:visual:update already passes --update-snapshots=all; if you call playwright directly, you need to pass it yourself.
• Class-name collisions via {...spread}. Spreading consumer props after setting className= silently overrides the variants. Always destructure className (and className: optionClassName for child elements) and merge with cn().
• Prop spread order reversal silently kills consumer overrides. If the styled-components JSX had {...props} last (after aria-disabled, tabIndex, onClick, etc.), the migration must keep it last. Spreading {...props} before the hardcoded attributes flips the precedence and consumer-passed values are silently ignored — TypeScript won't catch it because HTMLAttributes<...> admits those props. Caught post-merge on CardPrimary (#1038) and CardHorizontal (#1039).
• Rebuilding the inline-style object every render. Migrations that translate dynamic props into CSS custom properties via inline style often write the object literal directly in JSX, allocating a fresh reference on every render. Wrap it in useMemo keyed on the underlying values (and any incoming style). On a polymorphic _Name render function this trips react-hooks/rules-of-hooks (PascalCase-only heuristic) — disable that rule on the line with a note. Container and Icon both follow this pattern.
• Inline custom properties leaking into nested instances. Custom properties inherit by default, so any property the component sets inline only when its prop is passed (--container-height, --container-grow, --container-overflow, …) inherits into descendant instances of the same component — a parent <Container fillHeight> stretched every nested to full height. Reset each conditionally-emitted custom property to in the base class with a matching fallback (see the rule above). Visual-regression snapshots do catch this — the component renders fine in isolation — so guard it with a nested-instance computed-style test. Caught in control-plane on (#1059), fixed in #1067.

Checklist

Before marking the PR ready:

• Branch is rebased on the latest main (a fresh forwardRef or unrelated commit may have landed during the work).
• Commit 1 contains only stories, spec, snapshots, and possibly a narrow TS widening — nothing else.
• The new spec starts with a @covers src/components/<Name> directive (CI's visual-regression job throws without it).
• Commit 2 changes only <Name>.tsx, <Name>.module.css, and the changeset.
• If the component reads props from inline CSS custom properties, every conditionally-emitted one is reset to initial in the base class (with a matching var() fallback) so it can't inherit into nested instances, and a nested-instance test guards it.
• Every block and element has a base class (no cva('', …), no lone modifier families); shared declarations are hoisted onto the base and genuinely-empty bases carry a block-no-empty disable.
• Changeset is patch and reads exactly Migrate <Name> from styled-components to css modules with no change in behavior
• yarn test:visual tests/<area>/<name>.spec.ts is green with zero snapshot regenerations between the two commits.
• No styled-components imports remain in src/components/<Name>/.
• No internal links (Linear, Notion, internal Slack/Grafana) anywhere in PR text, commit messages, the changeset, or this skill's adjacent files — click-ui is a public repo.
• Any bundled a11y / type / consumer improvements have been split out into follow-up PR drafts to land after this one.