@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/docs/CSSGuidelines.md

@@ -0,0 +1,893 @@
+# CSS Guidelines
+
+CSS/Styling conventions for the Mixtape Design System.
+
+## Table of Contents
+
+- [PostCSS Pipeline](#postcss-pipeline)
+- [BEM Naming](#bem-naming)
+- [File Organization](#file-organization)
+- [Custom Media](#custom-media)
+- [Design Tokens](#design-tokens)
+- [Custom Property Fallbacks](#custom-property-fallbacks)
+- [Color Scheme (light-dark)](#color-scheme-light-dark)
+- [Logical Properties](#logical-properties)
+- [Cascade Layers](#cascade-layers)
+
+---
+
+## PostCSS Pipeline
+
+The build process transforms non-standard CSS syntax into valid browser CSS. Understanding these transforms is essential for reading and writing component styles.
+
+### Plugins & What They Do
+
+| Plugin | Syntax it handles | Output |
+|---|---|---|
+| `postcss-design-tokens` | `token("spacing.m")` | CSS custom property value |
+| `@csstools/postcss-global-data` | `@media (--medium-up)` | Custom media available globally |
+| `postcss-mixins` | `@define-mixin`, `@add-mixin` | Inline CSS |
+| `postcss-preset-env` (stage 0) | Modern CSS syntax | Cross-browser CSS |
+| `postcss-prepend-layer` | (automatic) | Wraps all CSS in `@layer design-system.*` |
+
+### token() Function
+
+The `token()` function is provided by `postcss-design-tokens` and resolves values from `src/tokens.js` at build time:
+
+```css
+/* Source */
+@custom-media --medium-up (width >= token("breakpoint.m"));
+padding: token("spacing.m");
+
+/* Compiled output */
+@custom-media --medium-up (width >= 900px);
+padding: 1rem;
+```
+
+Token paths mirror the structure of `src/tokens.js`. See the [Design Tokens](#design-tokens) section for available categories.
+
+### SVG Images
+
+SVG files are referenced with a plain `url()` — Vite inlines them as a data URI (or hashes them as an asset) at build time:
+
+```css
+background-image: url("../images/icon-close.svg");
+```
+
+### Custom Media Queries
+
+Custom media queries (defined in `src/_custom-media.css`) use `@csstools/postcss-global-data` to make them available to every file without needing an explicit `@import`. At build time they compile to standard `@media` queries:
+
+```css
+/* Source */
+@media (--medium-up) { ... }
+
+/* Compiled output */
+@media (width >= 900px) { ... }
+```
+
+The full list of available custom media names is in the [Custom Media](#custom-media) section.
+
+---
+
+## BEM Naming
+
+### Structure
+
+Block Element Modifier (BEM) methodology is **strictly enforced** by Stylelint.
+
+```css
+/* Block: Component/standalone entity */
+.mx-card {
+}
+
+/* Element: Part of block */
+.mx-card__header {
+}
+.mx-card__body {
+}
+.mx-card__footer {
+}
+
+/* Modifier: Variation of block or element */
+.mx-card--reversed {
+}
+.mx-card--block {
+}
+.mx-card__header--large {
+}
+```
+
+### Naming Rules
+
+✅ **Allowed:**
+
+```css
+.mx-component                    /* Block */
+.mx-component__element           /* Element */
+.mx-component--modifier          /* Modifier */
+.mx-component__element--modifier /* Element with modifier */
+```
+
+❌ **Not Allowed:**
+
+```css
+.mx-component-element           /* Wrong separator */
+.mx-component.modifier          /* Not BEM */
+.mx-componentElement            /* camelCase not allowed */
+.component                      /* Missing mx- prefix */
+```
+
+### Prefix Convention
+
+All design system classes use the `mx-` prefix:
+
+- **mx** = Mixtape
+- Prevents conflicts with consumer styles
+- Clear namespace for design system components
+
+### Nesting with &
+
+```css
+/* ✅ GOOD - Use & for nesting, reduce specificity */
+.mx-card {
+  display: flex;
+}
+
+.mx-card--reversed {
+  flex-direction: row-reverse;
+}
+
+.mx-card__media {
+  & img {
+    aspect-ratio: var(--ratio);
+  }
+}
+```
+
+### Stylelint Enforcement
+
+Your `.stylelintrc.json` enforces BEM:
+
+```javascript
+"selector-class-pattern": [
+  "^([a-z])([a-z0-9]+)((-[a-z0-9]+)+)?(((--)?(__)?)([a-z0-9]+)((-[a-z0-9]+)+)?)?(((--)?(__)?)([a-z0-9]+)((-[a-z0-9]+)+)?)?$",
+  {
+    message: "Expected class selector to be BEM selector matching either .block__element or .block--modifier"
+  }
+]
+```
+
+---
+
+## File Organization
+
+### Component Structure
+
+Components provide multiple CSS files for flexibility:
+
+```
+Component/
+├── component.css               # Public API - imports all partials
+├── _component-base.css         # Base styles (partial)
+├── _component-modifiers.css    # Modifier variations (partial)
+```
+
+#### Example: Button component
+
+```
+Button/
+├── button.css                  # Full button styles (imports both partials)
+├── _buttons.css               # Base button styles
+└── _buttons-styles.css        # Button style variations
+```
+
+### Import Patterns
+
+You can import the **full component** or **individual partials** depending on your needs:
+
+#### Option 1: Import Full Component (Recommended)
+
+```css
+/* Gets all button styles */
+@import "@pnx-mixtape/mxds/src/Atom/Button/button.css";
+```
+
+This is the simplest approach and includes all styles for the component.
+
+#### Option 2: Import Partials (Granular Control)
+
+```css
+/* Import only what you need */
+@import "@pnx-mixtape/mxds/src/Atom/Button/_buttons.css";
+@import "@pnx-mixtape/mxds/src/Atom/Button/_buttons-styles.css";
+
+/* Then override specific styles */
+.mx-button--primary {
+  --button-background: var(--colour-brand-primary);
+}
+```
+
+Use this when you:
+
+- Only need specific parts of a component
+- Want to customize before other styles load
+- Need finer control over what's included
+
+### Partial Files Convention
+
+Files prefixed with underscore are **partials**:
+
+- `_component-base.css` - Internal partial, can be imported separately
+- `component.css` - Public API, imports all partials
+
+**Why use partials?**
+
+- Modular - Import only what you need
+- Customizable - Override between partial imports
+- Flexible - Mix and match for your use case
+
+---
+
+## Custom Media
+
+### Always Import
+
+This is only required if you're not using something like [@csstools/postcss-global-data](https://www.npmjs.com/package/@csstools/postcss-global-data).
+
+Import custom media in every CSS file that uses them:
+
+```css
+/* MUST be first import in every file */
+@import "../../_custom-media.css";
+
+.mx-component {
+  display: block;
+
+  @media (--medium-up) {
+    display: flex;
+  }
+}
+```
+
+### Available Breakpoints
+
+```css
+/* Mobile first breakpoints */
+@media (--x-small-up)    /* >= 375px */
+@media (--small-up)      /* >= 600px */
+@media (--medium-up)     /* >= 900px */
+@media (--large-up)      /* >= 1200px */
+@media (--x-large-up)    /* >= 1800px */
+
+/* Desktop first breakpoints */
+@media (--x-small-down)  /* < 375px */
+@media (--small-down)    /* < 600px */
+@media (--medium-down)   /* < 900px */
+@media (--large-down)    /* < 1200px */
+@media (--x-large-down)  /* < 1800px */
+
+/* Between breakpoints */
+@media (--x-small-to-small)  /* 375px to 600px */
+@media (--small-to-medium)   /* 600px to 900px */
+@media (--medium-to-large)   /* 900px to 1200px */
+@media (--large-to-x-large)  /* 1200px to 1800px */
+
+/* Special breakpoints */
+@media (--global-nav-up)     /* >= 720px - Navigation breakpoint */
+@media (--global-nav-down)   /* < 720px */
+@media (--collapse-card-up)  /* >= 400px - Card collapse */
+@media (--collapse-card-down) /* < 400px */
+@media (--sidebar-up)     /* >= 720px - Sidebar breakpoint */
+@media (--sidebar-down)   /* < 720px */
+
+/* Interaction */
+@media (--touch)  /* Touch devices (no hover) */
+@media (--mouse)  /* Mouse devices (has hover) */
+```
+
+### Mobile First Approach
+
+```css
+/* ✅ GOOD - Mobile first */
+.mx-component {
+  /* Mobile styles (default) */
+  display: block;
+  padding: 1rem;
+
+  /* Tablet */
+  @media (--medium-up) {
+    display: flex;
+    padding: 2rem;
+  }
+
+  /* Desktop */
+  @media (--large-up) {
+    padding: 3rem;
+  }
+}
+
+/* ❌ BAD - Desktop first */
+.mx-component {
+  display: flex; /* Desktop default */
+
+  @media (--medium-down) {
+    display: block; /* Override for mobile */
+  }
+}
+```
+
+---
+
+## Design Tokens
+
+### How Tokens Work
+
+Design tokens in `src/tokens.js` are used during the build process to generate `src/constants.css`, which defines all CSS custom properties. Load this file once at the page level to make all custom properties available globally. Components can then use these custom properties for consistent styling.
+
+**Workflow:**
+
+1. Define/override tokens in `src/tokens.js`
+2. Build process generates `src/constants.css` with CSS custom properties
+3. Components use the custom properties
+
+### Using Custom Properties
+
+```css
+.mx-component {
+  /* Colors */
+  color: var(--colour-foreground);
+  background: var(--colour-background);
+
+  /* Spacing */
+  padding: var(--spacing-m);
+  margin-block-start: var(--spacing-l);
+
+  /* Typography */
+  font-size: var(--font-size-m);
+  line-height: var(--line-height);
+
+  /* Layout */
+  max-inline-size: var(--container-max-width);
+  gap: var(--spacing-s);
+
+  /* Borders */
+  border-radius: var(--border-radius);
+}
+```
+
+### Available Token Categories
+
+The `src/tokens.js` file defines tokens in these categories:
+
+- `colour.*` - Colors (text, background, brand, etc.)
+- `spacing.*` - Spacing scale (xxs, xs, s, m, l, xl, xxl)
+- `font.*` - Typography (size, family, weight, lineHeight)
+- `layout.*` - Layout values (measure, gutter, etc.)
+- `radius.*` - Border radius (s, m, l)
+- `border.*` - Border properties
+- `breakpoint.*` - Breakpoint values
+- `shadow.*` - Box shadows
+- `transition.*` - Transition values
+
+These are converted to CSS custom properties like:
+
+- `colour.text.primary` → `--colour-text-primary`
+- `spacing.m` → `--spacing-m`
+- `font.size.body` → `--font-size-m`
+
+### Overriding Tokens
+
+In your project, override tokens before the build process:
+
+```javascript
+// project-tokens.js
+import tokens from "@pnx-mixtape/mxds/tokens"
+
+// Override existing tokens
+tokens.colour.brand.primary = "rgb(0, 92, 250)"
+tokens.spacing.m = "1.5rem"
+
+// Add new tokens
+tokens.colour.brand.tertiary = "rgb(100, 200, 50)"
+
+export default tokens
+```
+
+Then configure your build tool (Vite, Webpack, etc.) with [postcss-design-tokens](https://www.npmjs.com/package/postcss-design-tokens) to use your project tokens instead of the default ones.
+
+The build process will generate custom properties based on your overridden tokens.
+
+#### Swapping the type scale
+
+Every `--font-size-*` (other than `--font-size-m`, which is the anchor) is derived from a single ratio via `pow()`, so swapping `font.size.ratio` reshapes the whole scale at once. The `global.typeScales` table exposes the eight standard musical scales — pick the named ratio rather than hard-coding a number:
+
+```javascript
+import tokens, { global } from "@pnx-mixtape/mxds/tokens"
+
+// Tighter UI-style scale (less display-y, denser)
+tokens.font.size.ratio = global.typeScales.perfectFourth // 1.333
+tokens.font.size.ratioSmall = global.typeScales.majorSecond // 1.125
+
+// Or editorial / display-heavy
+tokens.font.size.ratio = global.typeScales.goldenRatio // 1.618
+```
+
+Available scales:
+
+| Name              | Ratio | Feel                                         |
+| ----------------- | ----- | -------------------------------------------- |
+| `minorSecond`     | 1.067 | Very tight — UI/dense data                   |
+| `majorSecond`     | 1.125 | Tight                                        |
+| `minorThird`      | 1.2   | Compact (current mobile default)             |
+| `majorThird`      | 1.25  | Balanced                                     |
+| `perfectFourth`   | 1.333 | Generous body / UI hybrid                    |
+| `augmentedFourth` | 1.414 | Display-leaning (current desktop default)    |
+| `perfectFifth`    | 1.5   | Punchy display                               |
+| `goldenRatio`     | 1.618 | Editorial / magazine                         |
+
+`ratio` controls the desktop scale; `ratioSmall` is applied automatically below the `--medium-down` breakpoint, so you can pick a more dramatic ratio for desktop and a tighter one for mobile without writing any media queries.
+
+### Generated Custom Properties
+
+The `src/constants.css` file (generated from tokens by PostCSS) looks like this:
+
+```css
+:root {
+  --colour-text-primary: rgb(0, 0, 0);
+  --colour-background-secondary: rgb(245, 245, 245);
+  --spacing-m: 1rem;
+  --font-size-m: 1rem;
+  /* ... many more custom properties ... */
+}
+```
+
+**Load this file once at the page level** - it defines all custom properties in `:root`, making them available globally to all components without duplication.
+
+---
+
+## Custom Property Fallbacks
+
+### Cascading Fallback Pattern
+
+Components use a **cascading fallback pattern** with custom properties, allowing consumers to override values at different levels without modifying component CSS.
+
+**Pattern:**
+
+```css
+property: var(--override, var(--default));
+```
+
+This creates an override point that consumers can set, falling back to the design system default if not set.
+
+### Example: Background Component
+
+```css
+.mx-background--primary {
+  /* Allows consumer override, falls back to design system default */
+  background-color: var(--background, var(--colour-background));
+  color: var(--foreground, var(--colour-foreground));
+
+  /* Multiple fallback levels for flexibility */
+  --scheme: var(--primary-scheme, var(--colour-primary-scheme, var(--colour-scheme)));
+}
+```
+
+### How It Works
+
+**1. Component defines fallback chain:**
+
+```css
+.mx-card {
+  padding: var(--card-padding, var(--spacing-m));
+  background: var(--card-background, var(--colour-background));
+  border: var(--line-width, 2px) solid var(--line-colour, var(--colour-border));
+}
+```
+
+**2. Consumer overrides at any level:**
+
+```css
+/* Override globally */
+:root {
+  --line-colour: blue; /* Changes all components using --line-colour */
+}
+
+/* Override specific component */
+.mx-card {
+  --card-padding: 2rem; /* Only affects cards */
+}
+
+/* Override specific instance */
+.hero-card {
+  --card-background: var(--colour-primary);
+}
+```
+
+### Common Override Points
+
+Components expose these common override variables:
+
+**Spacing:**
+
+- `--card-padding` → `--spacing-m`
+- `--section-gap` → `--spacing-xl`
+- `--gap` → `--spacing-s`
+
+**Colors:**
+
+- `--background` → `--colour-background`
+- `--foreground` → `--colour-foreground`
+- `--line-colour` → `--colour-border`
+
+**Borders:**
+
+- `--line-width` → `1px` or `2px`
+- `--border-radius` → design system default
+
+**Typography:**
+
+- `--font-weight` → `--font-weight-bold`
+- `--font-size` → size-specific default
+
+### Benefits
+
+✅ **No component CSS modification** - Override via custom properties  
+✅ **Scoped changes** - Target specific components or instances  
+✅ **Global changes** - Set at `:root` for site-wide updates  
+✅ **Graceful fallbacks** - Always falls back to design system defaults  
+✅ **Inheritance** - Child elements inherit parent overrides
+
+### Real Example
+
+```css
+/* Component CSS (in design system) */
+.mx-blockquote {
+  padding-inline-start: var(--line-gap, var(--gap));
+  border-inline-start: var(--line-width, 6px) solid var(--line-colour, var(--colour-border));
+}
+
+/* Consumer override (in your project) */
+.special-quote {
+  --line-colour: var(--colour-accent);
+  --line-width: 10px;
+}
+```
+
+**Result:** The blockquote uses custom colors and width without touching component CSS.
+
+---
+
+## Color Scheme (light-dark)
+
+### Automatic Light/Dark Mode
+
+The design system uses the CSS `light-dark()` function and `color-scheme` property for automatic light/dark mode support.
+
+### How It Works
+
+**1. Set color-scheme:**
+
+```css
+.mx-background--primary {
+  color-scheme: var(--scheme, var(--colour-scheme));
+}
+```
+
+The `color-scheme` property tells the browser which color scheme is in use (light or dark), affecting system UI and enabling `light-dark()`.
+
+**2. Use light-dark() for colors:**
+
+```css
+.mx-background--primary {
+  --line-colour: light-dark(var(--colour-primary-darker), var(--colour-primary-lighter));
+}
+```
+
+The `light-dark()` function automatically picks the first value in light mode, second value in dark mode.
+
+### Background Component Example
+
+```css
+:where([class*="mx-background--"]) {
+  background-color: var(--background, var(--colour-background));
+  color: var(--foreground, var(--colour-foreground));
+  color-scheme: var(--scheme, var(--colour-scheme));
+}
+
+.mx-background--primary {
+  --scheme: var(--primary-scheme, var(--colour-primary-scheme, var(--colour-scheme)));
+  --background: var(--colour-primary);
+  --line-colour: light-dark(var(--colour-primary-darker), var(--colour-primary-lighter));
+  --colour-foreground-alt: var(--colour-primary-light);
+}
+
+.mx-background--reverse {
+  --scheme: var(--reverse-scheme, var(--colour-reverse-scheme, dark));
+}
+```
+
+### Setting Color Scheme
+
+**Global (page level):**
+
+```css
+:root {
+  --colour-scheme: light; /* or dark */
+}
+```
+
+**Per section:**
+
+```css
+.dark-section {
+  --scheme: dark;
+}
+
+.light-section {
+  --scheme: light;
+}
+```
+
+**Automatic (user preference):**
+
+```css
+:root {
+  color-scheme: light dark; /* Supports both */
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --colour-scheme: dark;
+  }
+}
+```
+
+### Using light-dark()
+
+**Syntax:**
+
+```css
+property: light-dark(<light-value>, <dark-value>);
+```
+
+**Examples:**
+
+```css
+/* Text colors */
+color: light-dark(var(--colour-text-dark), var(--colour-text-light));
+
+/* Backgrounds */
+background: light-dark(#ffffff, #000000);
+
+/* Borders */
+border-color: light-dark(var(--colour-primary), var(--colour-primary-light));
+
+/* Shadows */
+box-shadow: light-dark(0 2px 8px rgba(0, 0, 0, 0.1), 0 2px 8px rgba(255, 255, 255, 0.1));
+```
+
+### When to Use
+
+**Use `light-dark()` for:**
+
+- Colors that need to adapt to light/dark mode
+- UI elements with different appearances per mode
+- Borders, shadows, and subtle UI details
+
+**Use `color-scheme` for:**
+
+- Declaring which mode a section uses
+- Enabling `light-dark()` function
+- Affecting browser chrome (scrollbars, form controls)
+
+### Benefits
+
+✅ **Automatic switching** - Browser handles light/dark logic  
+✅ **No JavaScript required** - Pure CSS solution  
+✅ **Respects user preference** - Works with `prefers-color-scheme`  
+✅ **Scoped modes** - Different sections can use different schemes  
+✅ **System integration** - Browser chrome matches color scheme
+
+### Complete Example
+
+```css
+/* Define color scheme modes in constants.css */
+:root {
+  --colour-scheme: light;
+  --colour-primary: #003366;
+  --colour-primary-light: #6699cc;
+}
+
+/* Component uses light-dark() */
+.mx-component {
+  color-scheme: var(--colour-scheme);
+  border-color: light-dark(var(--colour-primary), var(--colour-primary-light));
+}
+
+/* Consumer changes scheme for a section */
+.dark-hero {
+  --scheme: dark;
+}
+```
+
+**Result:** The hero section automatically uses dark mode colors while rest of page uses light mode.
+
+---
+
+## Logical Properties
+
+### Use Logical Properties
+
+**ENFORCED** by stylelint-use-logical-spec plugin.
+
+```css
+/* ✅ GOOD - Logical properties (RTL-friendly) */
+.mx-component {
+  padding-inline: 1rem; /* left/right in LTR, right/left in RTL */
+  padding-block: 2rem; /* top/bottom always */
+  margin-inline-start: 1rem; /* left in LTR, right in RTL */
+  margin-block-start: 1rem; /* top always */
+  border-inline-end: 1px solid; /* right in LTR, left in RTL */
+  inset-inline-start: 0; /* left in LTR, right in RTL */
+}
+
+/* ❌ BAD - Physical properties */
+.mx-component {
+  padding-left: 1rem; /* Doesn't flip for RTL */
+  padding-right: 1rem;
+  margin-top: 1rem; /* OK but inconsistent */
+  border-right: 1px; /* Doesn't flip for RTL */
+  left: 0; /* Doesn't flip for RTL */
+}
+```
+
+### Property Mapping
+
+| Physical         | Logical                |
+| ---------------- | ---------------------- |
+| `padding-left`   | `padding-inline-start` |
+| `padding-right`  | `padding-inline-end`   |
+| `padding-top`    | `padding-block-start`  |
+| `padding-bottom` | `padding-block-end`    |
+| `margin-left`    | `margin-inline-start`  |
+| `margin-right`   | `margin-inline-end`    |
+| `border-left`    | `border-inline-start`  |
+| `border-right`   | `border-inline-end`    |
+| `left`           | `inset-inline-start`   |
+| `right`          | `inset-inline-end`     |
+| `top`            | `inset-block-start`    |
+| `bottom`         | `inset-block-end`      |
+| `width`          | `inline-size`          |
+| `height`         | `block-size`           |
+| `max-width`      | `max-inline-size`      |
+| `min-height`     | `min-block-size`       |
+
+### Shorthand Logical Properties
+
+```css
+/* Inline (horizontal in LTR) */
+padding-inline: 1rem; /* Both sides */
+margin-inline: 1rem 2rem; /* Start and end */
+
+/* Block (vertical) */
+padding-block: 1rem; /* Top and bottom */
+margin-block: 1rem 2rem; /* Start and end */
+
+/* Inset (position) */
+inset: 0; /* All sides */
+inset-inline: 0; /* Left and right in LTR */
+inset-block: 0; /* Top and bottom */
+```
+
+### Exception: Float
+
+`float` is exempt from logical properties (no logical equivalent):
+
+```css
+.mx-component {
+  float: left; /* OK - Exception defined in config */
+}
+```
+
+---
+
+## Cascade Layers
+
+All design system CSS is wrapped in cascade layers for **proper specificity control**.
+
+### Layer Order
+
+```css
+@layer popover-polyfill, design-system.defaults, design-system.atoms, design-system.layouts, design-system.utilities, design-system.components;
+```
+
+### Using Layers
+
+```css
+/* Automatically handled by build process */
+@layer design-system.components {
+  .mx-card {
+    /* Component styles */
+  }
+}
+
+@layer design-system.utilities {
+  .mx-text--center {
+    /* Utility styles */
+  }
+}
+```
+
+### Layer Benefits
+
+- ✅ **Predictable specificity** - Layers override regardless of selector specificity
+- ✅ **Easy overrides** - Consumer styles automatically override design system
+- ✅ **No !important needed** - Layer order handles precedence
+- ✅ **Better organization** - Clear separation of concerns
+
+### Consumer Overrides
+
+Consumers can easily override design system styles:
+
+```css
+/* Consumer styles (unlayered) always win */
+.mx-card {
+  padding: 3rem; /* Overrides design system */
+}
+
+/* Or use their own layers */
+@layer my-app {
+  .mx-card {
+    padding: 3rem; /* Also overrides */
+  }
+}
+```
+
+---
+
+## CSS Checklist
+
+Before shipping styles:
+
+- [ ] BEM naming convention followed
+- [ ] `mx-` prefix on all classes
+- [ ] Custom media imported at top of file (if needed)
+- [ ] Mobile-first responsive approach
+- [ ] Custom properties used (not hardcoded values)
+- [ ] Logical properties used (not physical)
+- [ ] Cascade layers applied
+- [ ] Stylelint passes (`pnpm lint-css`)
+- [ ] Styles work in RTL mode
+- [ ] Tested across breakpoints
+- [ ] No descending specificity issues
+- [ ] Performance checked (no expensive selectors)
+
+---
+
+## Stylelint Configuration
+
+Key rules from `.stylelintrc.json`:
+
+```javascript
+{
+  "extends": ["stylelint-config-standard"],
+  "plugins": ["stylelint-use-logical-spec"],
+  "rules": {
+    "selector-class-pattern": "...",  // BEM enforcement
+    "selector-nested-pattern": "^&",  // Must nest with &
+    "liberty/use-logical-spec": [true, { "except": ["float"] }],
+    "no-descending-specificity": null,  // Disabled for flexibility
+    "import-notation": "string"
+  }
+}
+```
+
+---
+
+## Related Documentation
+
+- [Code Quality Guidelines](./CodeQuality.md)
+- [Component Architecture](./ComponentArchitecture.md)
+- [Design Tokens](../src/tokens.js)
+- [Custom Media](../src/_custom-media.css)