@zohodesk/components 1.6.25 → 1.6.26

package/lib/v1/helpers/colorHelpers/paletteUtilities.README.md

@@ -1,6 +1,6 @@
 # Color Helpers
 
-Tailwind-inspired color utility classes and a `colorHelper` for DOT components.
+CSS color utility classes and a `getPaletteClasses` helper for DOT v1 components.
 
 ---
 
@@ -9,407 +9,212 @@ Tailwind-inspired color utility classes and a `colorHelper` for DOT components.
 ```
 colorHelpers/
 ├── background/
-│   └── backgroundColor.module.css   # Background color utilities
+│   └── backgroundColor.module.css
 ├── text/
-│   └── textColor.module.css         # Text color utilities
+│   └── textColor.module.css
 ├── border/
-│   └── borderColor.module.css       # Border color utilities
+│   └── borderColor.module.css
 ├── constants/
-│   └── index.js                     # PALETTE_CONFIG (palette → tone mapping)
-├── colorHelper.js                   # getPaletteClasses + getBgClass, getTextClass, getBorderClass
-└── paletteUtilities.README.md       # This file
+│   └── index.js                  # PALETTE_CONFIG, TONE_INTENSITY
+└── colorHelper.js                # getPaletteClasses (default export)
 ```
 
 ---
 
-## Available Colors
+## CSS Class Patterns
 
-All three CSS files share the same 7 color tones:
+All three CSS modules share the same 7 base tones: `brand`, `grey`, `blue`, `green`, `orange`, `red`, `yellow`.
 
-| Tone | Token Family | Use Case |
-|------|--------------|----------|
-| **default** | `--zdt_v1_palette_default_*` | Default/neutral actions |
-| **grey** | `--zdt_v1_palette_grey_*` | Secondary, muted elements |
-| **blue** | `--zdt_v1_palette_blue_*` | Information, primary actions |
-| **green** | `--zdt_v1_palette_green_*` | Success, positive status |
-| **orange** | `--zdt_v1_palette_orange_*` | Warning, caution |
-| **red** | `--zdt_v1_palette_red_*` | Error, danger, destructive actions |
-| **yellow** | `--zdt_v1_palette_yellow_*` | Alerts, highlights |
+Shades are numeric values defined in `TONE_INTENSITY` per tone (e.g. for `brand`: base `80`, hover `100`, light `10`, lightHover `20`, borderLight `10`).
 
----
-
-## Available Utilities
-
-### Background (`background/backgroundColor.module.css`)
-
-Per color (`default`, `grey`, `blue`, `green`, `orange`, `red`, `yellow`):
+### Background (`backgroundColor.module.css`)
 
 | Class Pattern | Description |
-|---------------|-------------|
-| `.bg-{color}` | Base background |
-| `.bg-{color}-light` | Light background variant |
-| `.hover\:bg-{color}:hover` | Hover state |
-| `.hover\:bg-{color}-light:hover` | Light hover state |
-| `.focus\:bg-{color}:focus` | Focus state |
-| `.focus\:bg-{color}-light:focus` | Light focus state |
-| `.active\:bg-{color}:active` | Active state |
-| `.active\:bg-{color}-light:active` | Light active state |
-| `.selected\:bg-{color}` | Selected state |
-| `.selected\:bg-{color}-light` | Light selected state |
-
-**Utility classes:** `.bg-transparent`, `.bg-white`, `.bg-black`
+|---|---|
+| `bg-{tone}-{base}` | Filled background |
+| `bg-{tone}-{light}` | Light background variant |
+| `hover:bg-{tone}-{hover}` | Filled — hover state |
+| `hover:bg-{tone}-{lightHover}` | Light — hover state |
+| `focus:bg-{tone}-{...}` | Focus state (same shade logic) |
+| `active:bg-{tone}-{...}` | Active state (same shade logic) |
+| `selected:bg-{tone}-{...}` | Selected state (same shade logic) |
 
-### Text (`text/textColor.module.css`)
+**Utility:** `bg-transparent`, `bg-white`, `bg-black` (+ `hover:`, `focus:`, `active:`, `selected:` variants)
 
-Per color (`default`, `grey`, `blue`, `green`, `orange`, `red`, `yellow`):
+### Text (`textColor.module.css`)
 
 | Class Pattern | Description |
-|---------------|-------------|
-| `.text-{color}` | Base text color |
-| `.hover\:text-{color}:hover` | Hover state |
-| `.focus\:text-{color}:focus` | Focus state |
-| `.active\:text-{color}:active` | Active state |
-| `.selected\:text-{color}` | Selected state |
-
-**Special:** `.text-brand-filled` (+ hover/focus/active/selected) — uses `--zdt_v1_palette_default_filled_text` for filled default backgrounds.
+|---|---|
+| `text-{tone}-{base}` | Base text color |
+| `hover:text-{tone}-{textHover\|hover}` | Hover state |
+| `focus:text-{tone}-{...}` | Focus state |
+| `active:text-{tone}-{...}` | Active state |
+| `selected:text-{tone}-{...}` | Selected state |
 
-**Utility classes:** `.text-transparent`, `.text-white`, `.text-black`
+**Special:** `text-brand-filled` (+ state variants) — used for text on filled `brand` backgrounds.
 
-> **Note:** Text has no `-light` variant. The `colorHelper` switches to `filledTextTone` (e.g., `white`) when the background is filled.
+**Utility:** `text-transparent`, `text-white`, `text-black` (+ state variants)
 
-### Border (`border/borderColor.module.css`)
+> Text has no `-light` shade variant. `getPaletteClasses` automatically switches to `filledTextTone` (`white`) when rendering on a filled background.
 
-Per color (`default`, `grey`, `blue`, `green`, `orange`, `red`, `yellow`):
+### Border (`borderColor.module.css`)
 
 | Class Pattern | Description |
-|---------------|-------------|
-| `.border-{color}` | Base border |
-| `.border-{color}-light` | Light border variant (resting state only) |
-| `.hover\:border-{color}:hover` | Hover state |
-| `.focus\:border-{color}:focus` | Focus state |
-| `.active\:border-{color}:active` | Active state |
-| `.selected\:border-{color}` | Selected state |
+|---|---|
+| `border-{tone}-{base}` | Base border |
+| `border-{tone}-{borderLight}` | Light border (resting only) |
+| `hover:border-{tone}-{hover}` | Hover state (always base shade) |
+| `focus:border-{tone}-{...}` | Focus state |
+| `active:border-{tone}-{...}` | Active state |
+| `selected:border-{tone}-{...}` | Selected state |
 
-**Utility classes:** `.border-transparent`, `.border-white`, `.border-black`
-
-> **Note:** Border state classes only use the base tone — no `-light` state variants. The `-light` class is available for the resting state only.
+**Utility:** `border-transparent`, `border-white`, `border-black` (+ state variants)
 
 ---
 
-## Direct CSS Usage (Examples)
-
-Import only the CSS modules you need and compose classes directly.
+## Direct CSS Usage
 
-### Example 1: Status Tag (text + background)
+Import only the modules you need and compose classes directly.
 
-```javascript
+```js
 import bgStyle from './background/backgroundColor.module.css';
 import textStyle from './text/textColor.module.css';
-
-function StatusTag({ status }) {
-  const className = compileClassNames({
-    [bgStyle['bg-green-light']]: status === 'success',
-    [bgStyle['bg-red-light']]: status === 'error',
-    [bgStyle['bg-orange-light']]: status === 'warning',
-    [textStyle['text-green']]: status === 'success',
-    [textStyle['text-red']]: status === 'error',
-    [textStyle['text-orange']]: status === 'warning',
-  });
-
-  return <span className={className}>{status}</span>;
-}
-```
-
-### Example 2: Bordered Card (border + background)
-
-```javascript
-import bgStyle from './background/backgroundColor.module.css';
 import borderStyle from './border/borderColor.module.css';
 
-function Card({ children, variant }) {
-  const className = compileClassNames({
-    [bgStyle['bg-blue-light']]: variant === 'info',
-    [bgStyle['bg-red-light']]: variant === 'error',
-    [borderStyle['border-blue']]: variant === 'info',
-    [borderStyle['border-red']]: variant === 'error',
-  });
-
-  return <div className={className}>{children}</div>;
-}
-```
-
-### Example 3: Interactive Button (text + background + border + hover)
-
-```javascript
-import bgStyle from './background/backgroundColor.module.css';
-import textStyle from './text/textColor.module.css';
-import borderStyle from './border/borderColor.module.css';
-
-function Button({ label, variant }) {
-  // Primary: blue bg, white text, blue border
-  const primaryClasses = compileClassNames({
-    [bgStyle['bg-blue']]: true,
-    [bgStyle['hover:bg-blue']]: true,
-    [textStyle['text-white']]: true,
-    [borderStyle['border-blue']]: true,
-    [borderStyle['hover:border-blue']]: true,
-  });
-
-  // Danger: red bg, white text, red border
-  const dangerClasses = compileClassNames({
-    [bgStyle['bg-red']]: true,
-    [bgStyle['hover:bg-red']]: true,
-    [textStyle['text-white']]: true,
-    [borderStyle['border-red']]: true,
-    [borderStyle['hover:border-red']]: true,
-  });
-
-  return <button className={variant === 'danger' ? dangerClasses : primaryClasses}>{label}</button>;
-}
-```
----
-
-## Using `colorHelper.js`
-
-### Named Exports
-
-Three utility functions return individual CSS module classes:
-
-```javascript
-import { getBgClass, getTextClass, getBorderClass } from './colorHelper';
-```
-
-#### `getBgClass({ state?, tone, isLighter? })`
-
-Returns a background CSS class from `backgroundColor.module.css`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tone` | `string` | Yes | Color tone (`default`, `grey`, `blue`, `green`, `orange`, `red`, `yellow`, `white`, `black`) |
-| `state` | `string` | No | State prefix (`hover`, `focus`, `active`, `selected`). Omit for base class. |
-| `isLighter` | `boolean` | No | `true` → appends `-light` to the tone |
-
-**Generated key pattern:** `[state:]bg-{tone}[-light]`
-
-```javascript
-getBgClass({ tone: 'blue' })                                  // → paletteBgStyle['bg-blue']
-getBgClass({ tone: 'blue', isLighter: true })                  // → paletteBgStyle['bg-blue-light']
-getBgClass({ state: 'hover', tone: 'red' })                    // → paletteBgStyle['hover:bg-red']
-getBgClass({ state: 'hover', tone: 'red', isLighter: true })   // → paletteBgStyle['hover:bg-red-light']
-```
-
-#### `getTextClass({ state?, textTone })`
-
-Returns a text CSS class from `textColor.module.css`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `textTone` | `string` | Yes | Text tone (`brand`, `grey`, `blue`, `green`, `orange`, `red`, `yellow`, `white`, `black`, `brand-filled`) |
-| `state` | `string` | No | State prefix (`hover`, `focus`, `active`, `selected`). Omit for base class. |
-
-> **Note:** `textTone` has no `isLighter` equivalent. Use `filledTextTone` (e.g. `white`) directly when needed.
+// Status tag: light bg + colored text
+<span className={`${bgStyle['bg-green-10']} ${textStyle['text-green-80']}`}>Success</span>
 
-**Generated key pattern:** `[state:]text-{textTone}`
+// Info card: light bg + light border
+<div className={`${bgStyle['bg-blue-10']} ${borderStyle['border-blue-10']}`}>{children}</div>
 
-```javascript
-getTextClass({ textTone: 'green' })                    // → paletteTextStyle['text-green']
-getTextClass({ state: 'hover', textTone: 'white' })    // → paletteTextStyle['hover:text-white']
-getTextClass({ textTone: 'brand-filled' })               // → paletteTextStyle['text-brand-filled']
+// Interactive element: filled bg + white text + hover bg
+<button className={`${bgStyle['bg-brand-80']} ${bgStyle['hover:bg-brand-100']} ${textStyle['text-brand-filled']}`}>
+  Click
+</button>
 ```
 
-#### `getBorderClass({ state?, tone, isLighter? })`
-
-Returns a border CSS class from `borderColor.module.css`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tone` | `string` | Yes | Color tone (`default`, `grey`, `blue`, `green`, `orange`, `red`, `yellow`) |
-| `state` | `string` | No | State prefix (`hover`, `focus`, `active`, `selected`). Omit for base class. |
-| `isLighter` | `boolean` | No | `true` → appends `-light` to the tone (resting state only by convention) |
-
-**Generated key pattern:** `[state:]border-{tone}[-light]`
-
-```javascript
-getBorderClass({ tone: 'blue' })                       // → paletteBorderStyle['border-blue']
-getBorderClass({ tone: 'blue', isLighter: true })      // → paletteBorderStyle['border-blue-light']
-getBorderClass({ state: 'hover', tone: 'red' })        // → paletteBorderStyle['hover:border-red']
-```
-
-#### Internal Helpers (not exported)
-
-- **`toTone(tone, isLighter)`** — returns `'{tone}-light'` if `isLighter` is truthy, else `'{tone}'`
-- **`withState(state, key)`** — returns `'{state}:{key}'` if `state` is truthy, else `'{key}'`
-
 ---
 
-### Default Export: `getPaletteClasses`
+## `getPaletteClasses`
 
-For components accepting `palette`, `bgAppearance`, `borderAppearance`, and `paletteShade` props.
+Computes all 15 CSS class keys for a palette in one call.
 
-```javascript
+```js
 import getPaletteClasses from './colorHelper';
 ```
 
-#### Palette → Tone Mapping (from `PALETTE_CONFIG`)
+### API
+
+```js
+getPaletteClasses({ palette, appearance, hoverAppearance, selectedAppearance })
+```
 
-| Palette | Tone (bg/border) | Text Tone | Filled Text Tone |
-|---------|-------------------|-----------|-------------------|
-| `default` | `brand` | `brand` | `brand-filled` |
-| `primary` | `blue` | `blue` | `white` |
+| Parameter | Type | Description |
+|---|---|---|
+| `palette` | `string` | One of the 12 palette names (see table below) |
+| `appearance` | `{ bg?, border?, text? }` | Resting state |
+| `hoverAppearance` | `{ bg?, border?, text? }` | Hover / focus / active states |
+| `selectedAppearance` | `{ bg?, border?, text? }` | Selected state |
+
+Each key in an appearance object accepts:
+- `true` — use the palette's own tone
+- `false` / omitted — no class produced
+- `'paletteName'` — use a different palette's tone (e.g. `text: 'brand'`)
+
+### Palettes (`PALETTE_CONFIG`)
+
+| Palette | Tone | Text tone | Filled text tone |
+|---------|------|-----------|-----------------|
+| `brand` | `brand` | `brand` | `brand-filled` |
+| `brandLighter` | `brand` (light shades) | `brand` | `brand` |
+| `info` | `blue` | `blue` | `white` |
+| `infoLighter` | `blue` (light shades) | `blue` | `blue` |
 | `secondary` | `grey` | `grey` | `white` |
+| `secondaryLighter` | `grey` (light shades) | `grey` | `grey` |
 | `danger` | `red` | `red` | `white` |
+| `dangerLighter` | `red` (light shades) | `red` | `red` |
 | `success` | `green` | `green` | `white` |
+| `successLighter` | `green` (light shades) | `green` | `green` |
+| `warning` | `orange` | `orange` | `white` |
+| `warningLighter` | `orange` (light shades) | `orange` | `orange` |
 
-Unknown palettes return `DUMMY_OBJECT` (empty frozen object).
+`*Lighter` palettes use `light` / `borderLight` shades from `TONE_INTENSITY` instead of `base`.
 
-#### Parameters
+### Return Value
 
-| Parameter | Values | Effect |
-|-----------|--------|--------|
-| `palette` | `default` \| `primary` \| `secondary` \| `danger` \| `success` | Selects the color tone config from `PALETTE_CONFIG` |
-| `bgAppearance` | `'none'` \| `'default'` \| other | `'default'` → base bg + state bg; `'none'` → no bg, no state bg, no filled text logic; other → no base bg but state bg + filled text logic |
-| `isSelected` | `boolean` | `true` → folds selected-state classes into `bg`, `text`, and `border` (replaces their resting values with the `selected` state class) |
-| `borderAppearance` | `'none'` \| `'onHover'` \| other | `'none'` → transparent base, no state borders; `'onHover'` → transparent base, with state borders; other → visible base + state borders |
-| `paletteShade` | `'lighter'` \| other | `'lighter'` → `-light` variant for bg and base border; also keeps text as `textTone` instead of `filledTextTone` |
+```js
+{
+  bg, hoverBg, focusBg, activeBg, selectedBg,
+  text, hoverText, focusText, activeText, selectedText,
+  border, hoverBorder, focusBorder, activeBorder, selectedBorder
+}
+```
 
-#### Text Tone Logic
+Each key is a CSS module class string, or `''` if not applicable for that appearance configuration.
 
-The text color depends on both `bgAppearance` and `paletteShade`:
+> `border` always has a value — when `bg: false` and no `border` key is set, it defaults to `border-transparent`.
 
-| Condition | Base text (`text`) | State text (`hoverText`, etc.) |
-|---|---|---|
-| `bgAppearance: 'default'` + default shade | `filledTextTone` (e.g. `white`) | `filledTextTone` |
-| `bgAppearance: 'default'` + `'lighter'` shade | `textTone` (e.g. `blue`) | `textTone` |
-| `bgAppearance:` other (not `'none'`) + default shade | `textTone` | `filledTextTone` |
-| `bgAppearance:` other (not `'none'`) + `'lighter'` shade | `textTone` | `textTone` |
-| `bgAppearance: 'none'` | `textTone` | `textTone` |
+### Text Tone Resolution
 
-> **Key insight:** `baseTextTone = isFilledBg && !isLighter ? filledTextTone : textTone`. `stateTextTone = hasBgState && !isLighter ? filledTextTone : textTone`. This means state text can differ from base text when `bgAppearance` is not `'default'` but also not `'none'`.
+| Background state | Text produced |
+|---|---|
+| Filled (`bg: true`, non-lighter palette) | `filledTextTone` (`white`) |
+| Light (`bg: true`, `*Lighter` palette) | `textTone` (`brand`) |
+| No background (`bg: false` or omitted) | `textTone`, or `''` if `text` not set |
 
-#### Return Value
+### Examples
 
-```javascript
-{
-  bg,          // isSelected → selected bg (if bgAppearance !== 'none'); else base bg (only if bgAppearance === 'default')
-  hoverBg,     // getBgClass({ state: 'hover', tone, isLighter }) — if bgAppearance !== 'none'
-  focusBg,     // getBgClass({ state: 'focus', tone, isLighter }) — if bgAppearance !== 'none'
-  activeBg,    // getBgClass({ state: 'active', tone, isLighter }) — if bgAppearance !== 'none'
-  text,        // isSelected → selected text class; else getTextClass({ textTone: baseTextTone })
-  hoverText,   // getTextClass({ state: 'hover', textTone: stateTextTone })
-  focusText,   // getTextClass({ state: 'focus', textTone: stateTextTone })
-  activeText,  // getTextClass({ state: 'active', textTone: stateTextTone })
-  border,      // isSelected → selected border (if borderAppearance !== 'none'); else resting border
-  hoverBorder, // getBorderClass({ state: 'hover', tone }) — if borderAppearance !== 'none'
-  focusBorder, // getBorderClass({ state: 'focus', tone }) — if borderAppearance !== 'none'
-  activeBorder // getBorderClass({ state: 'active', tone }) — if borderAppearance !== 'none'
-}
+**Filled button**
+```js
+getPaletteClasses({
+  palette: 'brand',
+  appearance: { bg: true, text: true, border: true },
+  hoverAppearance: { bg: true, text: true, border: true }
+});
+// bg → bg-brand-80 | text → text-brand-filled | border → border-brand-80
+// hoverBg → hover:bg-brand-100 | hoverText → hover:text-brand-filled
 ```
 
-> **Note:** State border classes always use the base tone (no `isLighter`), even when the resting border uses `-light`.
-
-#### Example: Filled Primary Button
-
-```javascript
-const classes = getPaletteClasses({
-  palette: 'primary',
-  bgAppearance: 'default',
-  borderAppearance: 'visible',
-  paletteShade: 'default',
+**Ghost button (no bg, with border)**
+```js
+getPaletteClasses({
+  palette: 'brand',
+  appearance: { bg: false, border: true },
+  hoverAppearance: { bg: false, border: true },
+  selectedAppearance: { bg: false, border: true }
 });
-// classes.bg           → 'bg-blue'           (bgAppearance: 'default' + default shade)
-// classes.hoverBg      → 'hover:bg-blue'
-// classes.text         → 'text-white'        (filledTextTone — bgAppearance: 'default' + not lighter)
-// classes.hoverText    → 'hover:text-white'  (filledTextTone — hasBgState + not lighter)
-// classes.border       → 'border-blue'       (visible appearance)
-// classes.hoverBorder  → 'hover:border-blue'
+// bg → '' | border → border-brand-80 | hoverBorder → hover:border-brand-80
+// selectedBorder → selected:border-brand-80
 ```
 
-#### Example: Light Danger Tag
-
-```javascript
-const classes = getPaletteClasses({
-  palette: 'danger',
-  bgAppearance: 'default',
-  borderAppearance: 'none',
-  paletteShade: 'lighter',
+**Text-only with selected fill**
+```js
+getPaletteClasses({
+  palette: 'brand',
+  appearance: { bg: false, text: true },
+  hoverAppearance: { bg: false, text: true },
+  selectedAppearance: { bg: true, text: true }
 });
-// classes.bg           → 'bg-red-light'      (bgAppearance: 'default' + lighter shade)
-// classes.hoverBg      → 'hover:bg-red-light'
-// classes.text         → 'text-red'          (textTone — lighter shade overrides filledTextTone)
-// classes.hoverText    → 'hover:text-red'    (textTone — lighter shade)
-// classes.border       → 'border-transparent' (borderAppearance: 'none')
-// classes.hoverBorder  → undefined           (no state borders with 'none')
+// text → text-brand-80 | hoverText → hover:text-brand-100
+// selectedBg → selected:bg-brand-80 | selectedText → selected:text-brand-filled
 ```
 
-#### Example: Ghost Secondary Button
-
-```javascript
-const classes = getPaletteClasses({
-  palette: 'secondary',
-  bgAppearance: 'none',
-  borderAppearance: 'onHover',
-  paletteShade: 'default',
+**Cross-palette override (black text, brand on hover)**
+```js
+getPaletteClasses({
+  palette: 'brand',
+  appearance: { bg: false, text: 'black' },
+  hoverAppearance: { bg: false }
 });
-// classes.bg           → undefined           (not filled)
-// classes.hoverBg      → undefined           (bgAppearance: 'none')
-// classes.text         → 'text-grey'         (textTone — not filled)
-// classes.hoverText    → 'hover:text-grey'   (textTone — bgAppearance 'none' → no filled text)
-// classes.border       → 'border-transparent' (onHover → transparent base)
-// classes.hoverBorder  → 'hover:border-grey' (onHover → state borders present)
+// text → text-black | hoverText → ''
 ```
 
-#### Example: Hover-fill Button (bgAppearance: non-standard value)
-
-```javascript
-const classes = getPaletteClasses({
-  palette: 'primary',
-  bgAppearance: 'hover-fill',  // any value that isn't 'none' or 'default'
-  borderAppearance: 'visible',
-  paletteShade: 'default',
+**Tinted outline (lighter palette)**
+```js
+getPaletteClasses({
+  palette: 'brandLighter',
+  appearance: { border: true },
+  hoverAppearance: { border: true }
 });
-// classes.bg           → undefined            (not 'default' → no base bg)
-// classes.hoverBg      → 'hover:bg-blue'     (not 'none' → state bg present)
-// classes.text         → 'text-blue'          (baseTextTone — not filled, so textTone)
-// classes.hoverText    → 'hover:text-white'   (stateTextTone — hasBgState + not lighter → filledTextTone!)
-// classes.border       → 'border-blue'        (visible)
-// classes.hoverBorder  → 'hover:border-blue'
+// bg → '' | border → border-brand-10 (borderLight shade) | hoverBorder → hover:border-brand-100
 ```
-
-> This shows a key behavior: the base text is the normal tone, but **state text switches to `filledTextTone`** because the hover/state background will be filled (dark).
-
-> **Note on `isSelected`:** Pass `isSelected: true` to fold the selected state into `bg`, `text`, and `border`. Instead of the resting class, each returns its `selected:` variant class. There are no separate `selectedBg`/`selectedText`/`selectedBorder` return keys.
-
----
-
-## Behavior Summary
-
-| Property | Lighter shade (`paletteShade: 'lighter'`) | Default shade |
-|----------|-------------------------------------------|---------------|
-| **Background** | Uses `-light` variant (e.g. `bg-blue-light`) | Uses base (e.g. `bg-blue`) |
-| **Base text** | Always `textTone` (e.g. `text-blue`) | `filledTextTone` when filled (e.g. `text-white`), else `textTone` |
-| **State text** | Always `textTone` (e.g. `hover:text-blue`) | `filledTextTone` when `bgAppearance !== 'none'` (e.g. `hover:text-white`), else `textTone` |
-| **Border (base)** | Uses `-light` variant if not transparent (e.g. `border-blue-light`) | Uses base if not transparent (e.g. `border-blue`) |
-| **Border (states)** | Always base tone (e.g. `hover:border-blue`) | Always base tone |
-
----
-
-## FAQ
-
-**Q: Why do text classes have no `-light` variant?**  
-A: Text on a light background should stay the base color for readability. When the background is filled (dark), text switches to a contrasting tone (e.g. `white`) instead.
-
-**Q: Why do border state classes not use `-light`?**  
-A: Border hover/focus/active/selected states always use the full-intensity base tone for visibility, even when the resting border uses a lighter shade.
-
-**Q: What happens if I pass an unknown palette to `getPaletteClasses`?**  
-A: It returns `DUMMY_OBJECT` (an empty frozen object), so no classes are applied.
-
-**Q: Can I use CSS classes directly without `getPaletteClasses`?**  
-A: Yes. The CSS modules are standalone. `getPaletteClasses` is a convenience for components that accept palette/appearance/shade props.
-
-**Q: When does state text differ from base text?**  
-A: When `bgAppearance` is neither `'none'` nor `'filled'` with default (non-lighter) shade. Base text uses `textTone` (colored), but state text uses `filledTextTone` (e.g. `white`) — because the hover/state will show a filled background.
-
----
-
-**Last Updated:** March 2026