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

.changeset/eight-colts-accept.md

@@ -0,0 +1,13 @@
+---
+'@clickhouse/click-ui': minor
+---
+
+This library will now use CSS Modules for styling and because it's distributed unbundled, gives the consumer application full control over bundling and optimisations. You'll only include what you actually use, resulting in smaller bundle sizes and better performance!
+
+**Migration:**
+
+Your bundler must be configured to handle `.module.css` imports from `node_modules`. Most popular bundlers (Vite, webpack, Parcel, Rollup with appropriate plugins) support CSS Modules by default or with minimal configuration.
+
+NOTE: We're currently migrating from Styled-Components to CSS Modules. Some components may still use Styled-Components during the transition period.
+
+To learn more about CSS modules support, check our documentation [here](https://github.com/ClickHouse/click-ui?tab=readme-ov-file#css-modules)

.llm/CONVENTIONS.md

@@ -27,6 +27,26 @@ export interface ComponentProps extends React.HTMLAttributes<HTMLElement> {
 - Use transient props (prefixed with `$`) for styled-component internal state
 - Use `data-*` attributes for styling hooks instead of generated class names
 
+### CSS Modules (BEM Naming)
+
+When using CSS Modules (migration in progress from styled-components):
+
+- **Follow BEM naming convention**:
+  - `.button` - Block (component root)
+  - `.button__icon` - Element (child of block, use double underscore)
+  - `.button--primary` - Modifier (variant/state, use double dash)
+  - `.button--primary:hover` - State pseudo-classes
+
+- **Example structure**:
+  ```css
+  .button { /* base styles */ }
+  .button__icon { /* icon element */ }
+  .button--primary { /* primary variant */ }
+  .button--primary:focus-visible { /* keyboard focus state */ }
+  ```
+- Use CSS custom properties from theme tokens: `var(--click-button-basic-color-primary-background-default)`
+- Always include `:focus-visible` styles for keyboard accessibility, never use `outline: none` without replacement
+
 ### Accessibility (Mandatory)
 
 - Interactive elements need `role`, `aria-label`, `aria-describedby`

.scripts/js/generate-tokens.js

@@ -1,7 +1,9 @@
 import { register } from '@tokens-studio/sd-transforms';
 import StyleDictionary from 'style-dictionary';
+import config from '../../src/theme/theme.config.json' with { type: 'json' };
 
 const themes = ['dark', 'light'];
+const THEME_DATA_ATTRIBUTE = `data-${config.storageKey}`;
 
 await register(StyleDictionary);
 
@@ -17,6 +19,38 @@ StyleDictionary.registerTransform({
   },
 });
 
+StyleDictionary.registerTransform({
+  type: 'name',
+  name: 'name/cti/kebab',
+  transform: (token, options) => {
+    if (options.prefix && options.prefix.length) {
+      return [options.prefix].concat(token.path).join('-');
+    } else {
+      return token.path.join('-');
+    }
+  },
+});
+
+StyleDictionary.registerFormat({
+  name: 'css/themed-variables',
+  format: function ({ dictionary, file }) {
+    const themeName = file.destination.replace('tokens-', '').replace('.css', '');
+    const tokens = dictionary.allTokens
+      .map(token => {
+        const varName = token.path.join('-');
+        const cleanValue = String(token.value).replace(/;+$/, '');
+        return `  --${varName}: ${cleanValue};`;
+      })
+      .join('\n');
+
+    if (themeName === 'light') {
+      return `:root,\n[${THEME_DATA_ATTRIBUTE}="light"] {\n${tokens}\n}`;
+    } else {
+      return `[${THEME_DATA_ATTRIBUTE}="dark"] {\n${tokens}\n}`;
+    }
+  },
+});
+
 StyleDictionary.registerFormat({
   name: 'typescript/es6-theme',
   format: function ({ dictionary, file }) {
@@ -46,10 +80,7 @@ StyleDictionary.registerFormat({
 
 for (const theme of themes) {
   const sd = new StyleDictionary({
-    source: [
-      `./tokens/**/!(${themes.join('|')}).json`,
-      `./tokens/**/${theme}.json`,
-    ],
+    source: [`./tokens/**/!(${themes.join('|')}).json`, `./tokens/**/${theme}.json`],
     preprocessors: ['tokens-studio'],
     platforms: {
       ts: {
@@ -63,6 +94,17 @@ for (const theme of themes) {
           },
         ],
       },
+      css: {
+        transformGroup: 'tokens-studio',
+        transforms: ['name/cti/kebab'],
+        buildPath: 'src/theme/styles/',
+        files: [
+          {
+            destination: `tokens-${theme}.css`,
+            format: 'css/themed-variables',
+          },
+        ],
+      },
     },
   });
 

.storybook/main.ts

@@ -32,9 +32,10 @@ const config: StorybookConfig = {
   },
 
   async viteFinal(config, { configType }) {
-    // Workaround for Storybook 10.0.7 bug where MDX files generate file:// imports
-    // See: https://github.com/storybookjs/storybook/issues (mdx-react-shim resolution)
-    config.plugins = config.plugins || [];
+    config.plugins = (config.plugins || []).filter((plugin) => {
+      const pluginName = plugin && typeof plugin === 'object' && 'name' in plugin ? plugin.name : null;
+      return pluginName !== 'css-external';
+    });
     config.plugins.push({
       name: 'fix-storybook-mdx-shim',
       resolveId(source) {

.storybook/preview.tsx

@@ -1,15 +1,15 @@
-import { useState, useEffect, ReactNode } from 'react';
-import type { Preview } from '@storybook/react-vite';
-import { Decorator } from '@storybook/react-vite';
-import { styled } from 'styled-components';
-import { themes } from 'storybook/theming';
-import { ClickUIProvider } from '@/providers';
+import { useState, useEffect, ReactNode } from "react";
+import type { Preview } from "@storybook/react-vite";
+import { Decorator } from "@storybook/react-vite";
+import { styled } from "styled-components";
+import { themes } from "storybook/theming";
+import { ClickUIProvider } from "../src/providers";
 
 const ThemeBlock = styled.div<{ $left?: boolean; $bfill?: boolean }>(
   ({ $left, $bfill: fill, theme }) => `
       position: absolute;
       top: 0.5rem;
-      left: ${$left || fill ? 0 : '50vw'};
+      left: ${$left || fill ? 0 : "50vw"};
       right: 0;
       height: fit-content;
       bottom: 0;
@@ -22,26 +22,28 @@ const ThemeBlock = styled.div<{ $left?: boolean; $bfill?: boolean }>(
 
 export const globalTypes = {
   theme: {
-    name: 'Theme',
-    description: 'Global theme for components',
-    defaultValue: 'system',
+    name: "Theme",
+    description: "Global theme for components",
+    defaultValue: "system",
     toolbar: {
-      icon: 'circlehollow',
+      icon: "circlehollow",
       items: [
-        { value: 'system', icon: 'browser', title: 'system' },
-        { value: 'dark', icon: 'moon', title: 'dark' },
-        { value: 'light', icon: 'sun', title: 'light' },
+        { value: "system", icon: "browser", title: "system" },
+        { value: "dark", icon: "moon", title: "dark" },
+        { value: "light", icon: "sun", title: "light" },
       ],
       showName: true,
     },
   },
 };
 
-const getSystemTheme = (): 'dark' | 'light' => {
-  if (typeof window !== 'undefined' && window.matchMedia) {
-    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+const getSystemTheme = (): "dark" | "light" => {
+  if (typeof window !== "undefined" && window.matchMedia) {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches
+      ? "dark"
+      : "light";
   }
-  return 'dark';
+  return "dark";
 };
 
 interface ThemeWrapperProps {
@@ -50,27 +52,24 @@ interface ThemeWrapperProps {
 }
 
 const ThemeWrapper = ({ themeSelection, children }: ThemeWrapperProps) => {
-  const [systemTheme, setSystemTheme] = useState<'dark' | 'light'>(getSystemTheme);
+  const [systemTheme, setSystemTheme] = useState<"dark" | "light">(getSystemTheme);
 
   // Listen for system theme changes
   useEffect(() => {
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
     const handleChange = () => {
-      setSystemTheme(mediaQuery.matches ? 'dark' : 'light');
+      setSystemTheme(mediaQuery.matches ? "dark" : "light");
     };
-    mediaQuery.addEventListener('change', handleChange);
-    return () => mediaQuery.removeEventListener('change', handleChange);
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
   }, []);
 
   // Resolve the actual theme: handle "system" and fallback for undefined/null
   const theme =
-    themeSelection === 'system' || !themeSelection ? systemTheme : themeSelection;
+    themeSelection === "system" || !themeSelection ? systemTheme : themeSelection;
 
   return (
-    <ClickUIProvider
-      theme={theme}
-      config={{ tooltip: { delayDuration: 0 } }}
-    >
+    <ClickUIProvider theme={theme} config={{ tooltip: { delayDuration: 0 } }}>
       <ThemeBlock $left>{children}</ThemeBlock>
     </ClickUIProvider>
   );
@@ -91,22 +90,22 @@ const preview: Preview = {
   parameters: {
     options: {
       storySort: {
-        method: 'alphabetical',
+        method: "alphabetical",
         order: [
-          'Introduction',
-          'Buttons',
-          'Cards',
-          'Layout',
-          'Forms',
-          'Display',
-          'Sidebar',
-          'Typography',
-          'Colors',
-          ['Title', 'Text', 'Link'],
+          "Introduction",
+          "Buttons",
+          "Cards",
+          "Layout",
+          "Forms",
+          "Display",
+          "Sidebar",
+          "Typography",
+          "Colors",
+          ["Title", "Text", "Link"],
         ],
       },
     },
-    actions: { argTypesRegex: '^on[A-Z].*' },
+    actions: { argTypesRegex: "^on[A-Z].*" },
     controls: {
       matchers: {
         color: /(background|color)$/i,

README.md

@@ -23,6 +23,7 @@ You can find the official docs for the Click UI design system and component libr
   - [Generating design tokens](#generating-design-tokens)
   - [Local development](#local-development)
   - [Circular dependency check](#circular-dependency-check)
+  - [CSS Modules](#css-modules)
 * [Tests](#Tests)
   - [Functional tests](#functional-tests)
   - [Visual regression tests](#visual-regression-tests)
@@ -144,6 +145,39 @@ By avoiding local preview files, we ensure that component experimentation happen
 
 To get started with the development playground, refer to the Storybook section [here](#storybook).
 
+### CSS Modules
+
+This library uses [CSS Modules](https://github.com/css-modules/css-modules) for styling and is distributed unbundled, giving your application full control over bundling and optimizations. This means you only include what you actually use, resulting in smaller bundle sizes and better performance!
+
+Most modern React frameworks support CSS Modules out of the box, including Next.js, Vite, Create React App, and TanStack Start, with no configuration required.
+
+> [!NOTE]
+> We're currently migrating from Styled-Components to CSS Modules. Some components may still use Styled-Components during this transition period.
+#### Benefits
+
+CSS Modules align naturally with component-level imports. When you import a component like `Button`, its `Button.module.css` is automatically included. If you don't use the component, neither the JavaScript, or CSS will be bundled in your application's output. Only the necessary stylesheets will be included in the output bundle.
+
+#### Custom Build Configurations
+
+Although most modern React setups have CSS Modules built-in, if your build tool doesn't support it by default, you'll need to configure it.
+
+Let's assume you have an old Webpack setup. Here's an example of how that'd look like:
+
+```js
+{
+  test: /\.module\.css$/,
+  use: [
+    'style-loader',
+    {
+      loader: 'css-loader',
+      options: { modules: true }
+    }
+  ]
+}
+```
+
+For other bundlers, refer to their documentation on CSS Modules configuration.
+
 ## Tests
 
 ### Functional tests

package.json

@@ -10,7 +10,9 @@
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
-  "sideEffects": false,
+  "sideEffects": [
+    "**/*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -410,6 +412,8 @@
     "@radix-ui/react-tabs": "1.1.1",
     "@radix-ui/react-toast": "1.2.2",
     "@radix-ui/react-tooltip": "1.1.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
     "dayjs": "^1.11.19",
     "lodash-es": "^4.17.23",
     "react-sortablejs": "^6.1.4",
@@ -470,6 +474,7 @@
     "vite": "^7.3.0",
     "vite-plugin-dts": "^4.3.0",
     "vite-plugin-externalize-deps": "^0.10.0",
+    "vite-plugin-static-copy": "^3.2.0",
     "vite-tsconfig-paths": "^6.0.5",
     "vitest": "^2.1.8",
     "watch": "^1.0.2"