chore(css-modules): 🤖 initial css modules setup

[punkbit]

Why?

Provide the initial setup foundations for CSS Modules for migrating from Styled-Components in a sustainable and iterative manner.

This library will now use CSS Modules for styling and is distributed unbundled, giving your application full control over bundling and optimisations. This means you only include what you actually use, resulting in smaller bundle sizes and better performance!

⚠️ WARNING: Depends on #773 and #784; these should be merged first.

Regression risk assessment

The migration workflow provides visual regression tests, including changes to tests to include every relevant component state. For example, the following are implementations of it in practice:

chore: 🤖 support local visual regression testing via docker
#931

chore: 🤖 GitHub action for visual regression (development environment based [initial version])
#932

It ensures consistent visual regression snapshots by enabling local testing within a Dockerized environment. This prevents false positive diffs caused by operating system variations, e.g., macOS vs. linux.

Introduces a GitHub Action for visual regression testing within the CI/CD pipeline. Unlike our existing Chromatic implementation, which relies on Storybook stories and cloud-managed snapshots, this action executes tests using screenshots managed directly within the development environment (curated by author). This ensures snapshots remain tightly coupled with the implementation code.

It's important to note that the CI/CD process runs in every pull request contribution, under a matching Linux instance encountered in the local dev setup for an accelerated feedback loop.

Furthermore, these visual regression tests differ from the cloud-based regression testing Chromatic, as they're closer to local development setup, e.g. a contributor can run them in their environment immediately. Comparatively, the Chromatic setup provides feedback at a later stage of contribution, e.g. only running in the Cloud, causing the feedback loop to be much slower. While Chromatic automatically generates tests based on Storybook story screenshots, the local regression test suite allows the contributor to curate these for proper assessment and more in line with the intended implementation and behaviour checkup, e.g. can assess components singularly, compose scenarios with multiple components, and run interactive userflows to cause state changes.

Finally, it runs on Playwright but is adapted to Chromatic's extension, allowing for easier interchangeability.

Bug tracking

The Click UI has issues tracked, which can further any reports found during any test or release.

For example, during the migration process, there's an opportunity to snapshot and enhance checkups for proper testing against expected behaviour. If differences or unexpected behaviour's detected, these can be compared to the original Styled Component version and resolved comparatively, e.g. on visual regression testing, a local development suit is made available to help catch during time of contribution. Before, visual regression tests are solely base in Chromatic, which are autogenerated.

How?

• Process static CSS imports
• Stores raw stylesheets in distribution
• Makes distributed components import stylesheets from distribution
• Provide documentation

Preview?

demo-button-ss-to-css-migration-states.mov

Demonstrates computed CSS Module in DOM

Distribution showcasing Button.module.css (in-place)

dist
├── cjs
│   └── components
│       └── Button
│           ├── Button.cjs
│           ├── Button.cjs.map
│           └── Button.module.css
├── esm
│   └── components
│       └── Button
│           ├── Button.js
│           ├── Button.js.map
│           └── Button.module.css
└── types
    └── components
        └── Button
            └── Button.d.ts

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
click-ui	Ready	Preview, Comment	Feb 4, 2026 7:27pm

[changeset-bot]

🦋 Changeset detected

Latest commit: dc3dbf8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clickhouse/click-ui	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[EvandroLG]

Both tokens-dark.css and tokens-light.css are generated files, so we might run into annoying merge conflicts. Maybe we should add them to .gitignore and generate them at build time instead, WDYT?

Also, I’d add a comment to these files warning that they shouldn’t be edited manually. Something like:

/* AUTO-GENERATED — DO NOT EDIT */

[github-actions]

Claude finished @punkbit's task in 3m 13s —— View job

---

Code Review

• Gathering context
• Reading CLAUDE.md and CONVENTIONS.md
• Reviewing changed files
• Posting review feedback

---

Great work on this foundational PR! The CSS Modules setup is clean and well-structured. Here's the full review of the current state.

✅ Previously flagged issues — all resolved

• aria-disabled / aria-busy using || undefined — no false emitted on interactive buttons (Button.tsx:77-78)
• background-repeat: no-repeat on all four shimmer variants (Button.module.css:218–240)
• sideEffects: ["**/*.css"] — **/*.module.css redundancy removed (package.json:13)

✅ What's solid

• BEM naming: Consistent throughout — .button, .button__icon, .button--primary, etc.
• Token compliance: All visual values use CSS custom properties (--click-button-*), no hardcoded values
• forwardRef: Correctly implemented
• className forwarding: cn(buttonVariants(...), className) properly merges consumer classes
• focus-visible: All four variants have :focus-visible outlines; outline: none is never used without a replacement
• prefers-reduced-motion: Shimmer animation correctly disabled (Button.module.css:260-264)
• Tests: Button.test.tsx covers disabled state, loading state (all variants), click-blocking, and aria-disabled — good behavioral coverage
• Changeset: Correct minor bump with bundler migration note for consumers
• cva.ts wrapper: Clean pattern — re-exporting CVA + cn for className merging makes sense for a component library migration
• Unbundled distribution: cssExternalPlugin + viteStaticCopy approach correctly keeps .module.css files alongside compiled JS in dist/cjs and dist/esm

💡 Suggestion (non-blocking)

transition: font on base .button is dead code (Button.module.css:17):

/* current */
transition: font var(--click-transition-default);

The CSS font shorthand is not an animatable property per spec — browsers silently ignore this transition. Font changes between states (hover, active, disabled) will always be instant. The per-state rules already add their own transition: var(--click-transition-default) for the TO-state transition, so this line only affects the return-to-base transition, which also doesn't animate font. No visual regression, just dead code worth cleaning up.

Fix this →

Acknowledged / Deferred

• type prop shadowing native <button type> — noted with a TODO in the code, tracked for follow-up. Understood.
• pointer-events: none on .button--loading — cursor: not-allowed is the better accessibility choice here per the discussion. Current approach is correct.
• tokens-dark.css / tokens-light.css as committed files — move to build-time generation tracked in chore(monorepo): 🤖 Design tokens as a package (initial) #946.

---

The build pipeline, BEM naming, token usage, accessibility attributes, and test coverage are all well-done. Ready to merge once the dependency on #773 and #784 is satisfied. 🙌

[workflow-authentication-public]

📚 Storybook Preview Deployed

✅ Preview URL: https://click-qi04bmplb-clickhouse.vercel.app

Built from commit: bec00f1aa222257c4ea451c1170f3e53465390b3