@clickhouse/click-ui 0.2.0-rc.6 → 0.2.0-rc.8

package/README.md

@@ -18,11 +18,13 @@ You can find the official docs for the Click UI design system and component libr
 ## Overview
 
 * [Requirements](#requirements)
+* [Browser Support](#browser-support)
 * [Quick Start](#quick-start)
 * [Development](#development)
   - [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)
@@ -55,6 +57,27 @@ You can find the official docs for the Click UI design system and component libr
 - Nodejs (>= 22.12.x) as runtime
 - Yarn (>= 4.5.3) for development, any other package manager in a host project
 
+## Browser Support
+
+Click UI targets modern browsers from the last 4 years with significant market share (>0.5%). This ensures broad compatibility while allowing the use of modern CSS features.
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | 100+ |
+| Edge | 100+ |
+| Firefox | 99+ |
+| Safari | 15.5+ |
+
+The following browsers are explicitly **not supported** due to limited CSS feature support:
+- QQ Browser
+- Baidu Browser
+- UC Browser
+- KaiOS Browser
+- Opera Mini
+
+> [!NOTE]
+> The browser support list is defined in `.browserslistrc` and enforced via CSS linting during development. CSS features that aren't supported by the target browsers will trigger linting errors.
+
 ## Quick Start
 
 Install the package via npm or your favourite package manager:
@@ -144,6 +167,50 @@ 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.
+
+> [!IMPORTANT]
+> **Next.js apps** must add `@clickhouse/click-ui` to `transpilePackages` configuration (available in Next.js 13+):
+> ```js
+> // next.config.ts
+> module.exports = {
+>   transpilePackages: ['@clickhouse/click-ui'],
+> };
+> ```
+> This is required because Next.js restricts global CSS imports from `node_modules` by default. Transpiling the package allows Next.js to process the CSS through its build pipeline. See the [Next.js example](docs/examples/nextjs-app-router-with-ssr.md) for full setup instructions.
+
+> [!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