chore(css-modules): 🤖 Enable linter on CSS files (#945)

* chore: 🤖 add style linter

* chore: 🤖 add base style lint configuration file

* chore: 🤖 add distinction code and css linter commands

* chore: 🤖 create a browser list listing >= 2020

* chore: 🤖 set browser list rc for latest 4 years and filter out obscure browsers

* chore: 🤖 Browser compatibility issues are now properly handled.

* chore: 🤖 ignore edgecase

* refactor: 💡 Selectors with lower specificity should
  come before those with higher specificity

* chore: 🤖 property ordering by logical groups

* chore: 🤖 exclude obscure browsers

* style: 💄 reorder fix

* docs: 📝 browser support

* chore: 🤖 remove deprecated rid-gap

* style: 💄 remove typo

* chore: 🤖 allow empty lines

* docs: 📝 show only top 4 browsers in doc

* refactor: 💡 update stylelinter to prefer BEM's naming convention

* refactor: 💡 rename class names to favour BEM's naming convention (remove double dashes)

* refactor: 💡 rename class names in css module

* chore: 🤖 remove link to BEM's two dashes

* docs: 📝 standard BEM naming

* chore: 🤖 update comment

Author: punkbit

.browserslistrc

@@ -0,0 +1,8 @@
+# NOTE: Modern browsers from the last 4 years with >0.5% market share, but explicitly exclude obscure browsers that have limited CSS feature support
+last 4 years
+> 0.5%
+not and_qq > 0
+not baidu > 0
+not and_uc > 0
+not kaios > 0
+not op_mini all

.llm/CONVENTIONS.md

@@ -27,22 +27,24 @@ 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)
+### CSS Modules (Standard BEM Naming)
 
 When using CSS Modules (migration in progress from styled-components):
 
-- **Follow BEM naming convention**:
+- **Follow standard BEM naming convention** (https://en.bem.info/methodology/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
+  - `.button__icon` - Element (child of block, use double underscore `__`)
+  - `.button_primary` - Modifier (variant/state, use single underscore `_`)
+  - `.button_align-center` - Modifier with hyphenated value
+  - `.button_primary:hover` - Pseudo-classes on modifiers
+  - `.button_primary.button_loading` - Multiple modifiers on same element
 
 - **Example structure**:
   ```css
   .button { /* base styles */ }
   .button__icon { /* icon element */ }
-  .button--primary { /* primary variant */ }
-  .button--primary:focus-visible { /* keyboard focus state */ }
+  .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
@@ -97,7 +99,7 @@ src/components/
 ├── Button/
 │   ├── Button.tsx          # Main component implementation
 │   ├── Button.types.ts     # Type definitions (interfaces, types)
-│   ├── Button.styles.ts    # Styled-components
+│   ├── Button.module.css   # CSS Modules styles
 │   ├── Button.test.tsx     # Unit tests
 │   ├── Button.stories.tsx  # Storybook documentation
 │   └── index.ts            # Public exports

README.md

@@ -18,6 +18,7 @@ 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)
@@ -56,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:

package.json

@@ -377,8 +377,12 @@
     "format:fix": ".scripts/bash/format --write",
     "generate:exports": ".scripts/js/generate-exports",
     "generate:tokens": "node ./.scripts/js/generate-tokens.js && yarn format:fix src/theme/tokens/**/*.ts",
-    "lint": "eslint src --report-unused-disable-directives",
-    "lint:fix": "eslint src --report-unused-disable-directives --fix",
+    "lint": "yarn lint:code && yarn lint:css",
+    "lint:fix": "yarn lint:code:fix && yarn lint:css:fix",
+    "lint:code": "eslint src --report-unused-disable-directives",
+    "lint:code:fix": "eslint src --report-unused-disable-directives --fix",
+    "lint:css": "stylelint \"src/**/*.css\"",
+    "lint:css:fix": "stylelint \"src/**/*.css\" --fix",
     "prepare": "husky",
     "prettify": "yarn format:fix",
     "preview": "vite preview",
@@ -467,6 +471,10 @@
     "storybook": "^10.1.10",
     "storybook-addon-pseudo-states": "^10.1.10",
     "style-dictionary": "^5.0.0",
+    "stylelint": "^17.5.0",
+    "stylelint-config-standard": "^40.0.0",
+    "stylelint-no-unsupported-browser-features": "^8.1.1",
+    "stylelint-order": "^8.1.1",
     "stylis": "^4.3.0",
     "ts-node": "^10.9.1",
     "typescript": "^5.5.3",