@clicktap/ui 2.3.2 → 2.3.3

package/docs/migrations/2026/09/ui-2026-09-24-semantic-color-token-lint-rule.md

@@ -0,0 +1,283 @@
+# IMPROVEMENT: literal palette colors are a lint error in `@clicktap/ui`, and the 136 existing ones are resolved
+
+**Date:** 2026-09-24
+**Package:** `@clicktap/ui`
+**Affects:** 54 files under `src/components/**` — every component listed in "What changed" below — plus the new root-level `eslint.rules.no-literal-palette-color.mjs` and the two eslint configs that reference it.
+**Classification:** IMPROVEMENT
+**Breaking:** No API change, and no prop, export or class-name contract moves. **Visual:** 76 of the 118 swaps resolve to the exact same light-theme value and render identically. The other 42 do not — they are listed component by component under "Rendering changes" and are all one step along a neutral ramp, except `UploadImage`, whose hover background **appears for the first time** because the class it had was a typo.
+**Ticket:** CTAP-1904
+
+## Problem
+
+Four tickets described the same defect: a component styled with a literal Tailwind palette utility
+instead of a semantic token. It is invisible in a light-themed app and wrong — sometimes illegible —
+in a re-themed one. CTAP-1123 did the original sweep, CTAP-1304 fixed `BreadcrumbLink`, CTAP-1834
+asked for the token set, CTAP-1902 fixed `Dialog`'s `bg-white`.
+
+Review missed it three times running, so the convention needed a machine check. And a rule without
+the sweep would fail 54 files on day one; a sweep without the rule would regress, which is exactly
+the history above. Both land here.
+
+## The survey
+
+Measured on this branch's merge-base with `master`, over `src/**/*.{ts,tsx}`, excluding
+`*.stories.*` / `*.test.*` / `*.spec.*`:
+
+| | Count |
+|---|---|
+| Textual matches | 140 across 55 files |
+| …of which sit inside a **comment** (a docblock `@example`, a note naming a class in prose) | 4 |
+| **Literals in code — what the rule reports** | **136 across 54 files** |
+| Matches in stories / tests / specs, which the rule excludes on purpose | 28 across 6 files |
+
+The ticket's survey said 139 across 54 files. The difference is accounted for: it was measured after
+CTAP-1902's `Dialog` fix, which is on PR #3030 and not yet in `master`, so `Dialog`'s `bg-white` is
+the 140th match here; and the ticket counted textually, where an AST rule does not see the four
+matches that live in comments. The ticket's "34 hits in stories/tests" is 28 by this regex — the
+gap is arbitrary-value classes such as `bg-[#222]`, which are deliberately out of scope.
+
+Resolution of the 136:
+
+| | Count |
+|---|---|
+| Swapped to a semantic token | 118 |
+| Annotated as deliberate, with a reason | 17 |
+| Deleted as dead code (`shadow-slate-200` with no `shadow` utility beside it, so it painted nothing) | 1 |
+
+## The rule
+
+`clicktap/no-literal-palette-color`, defined in `eslint.rules.no-literal-palette-color.mjs` at the
+workspace root and turned on for `libs/frontend-modules/ui/src/**` only.
+
+**Why a custom rule.** `no-restricted-syntax` — the mechanism the repo already uses for the
+`z.string().trim()` convention — can match a string against a regex, but its message is a fixed
+string: it can say the line has a literal palette color and not *which* one. A `cn()` call in this
+package routinely carries a dozen classes over several lines, so naming the offender is the
+difference between a usable error and a hunt. An AST rule also skips comments for free, which is
+what keeps a docblock explaining this very convention from being an error.
+`eslint-plugin-tailwindcss` is not a dependency of this workspace and has no "these colors are off
+limits" rule, so it would have meant a new dependency *and* this rule.
+
+**What it flags:** `bg-`, `text-`, `border-`, `ring-`, `ring-offset-`, `fill-`, `stroke-`, `from-`,
+`via-`, `to-`, `divide-`, `outline-`, `decoration-`, `shadow-`, `caret-`, `accent-`, `placeholder-`
+— with an optional side/axis segment (`border-t-`, `divide-y-`) — followed by `white`, `black`, or
+one of the 22 named ramps with a numeric step. Variant prefixes and the important modifier pass
+through (`dark:hover:!bg-white` is reported as `bg-white`), and the opacity modifier is reported as
+part of the class (`bg-black/30`).
+
+**What it does not flag, deliberately:**
+
+- **`transparent`, `current`, `inherit` are not colors.** They carry no theme decision and repaint
+  themselves, so `bg-transparent` and `text-current` stay legal. The ticket asked for this call to
+  be stated: it is stated.
+- **Arbitrary values** — `shadow-[0_8px_24px_rgba(0,0,0,0.1)]`, `bg-[#222]`. `theme.css` publishes
+  no `--shadow-*` token, so flagging them would produce hits with nowhere to go. Minting those
+  tokens is CTAP-1834's business.
+- **Stories, tests, specs and fixtures.** Excluded twice over: by the config block's `ignores`, and
+  by a filename check inside the rule itself, so it holds however the rule is wired up.
+- **Comments.** The rule visits string and template nodes only.
+
+**Where it runs.** In both `libs/frontend-modules/ui/eslint.config.mjs` and the root
+`eslint.config.mjs`, for the same reason `eslint.rules.trim-form-strings.mjs` lives in both:
+`lint-staged` resolves the **root** config on commit while `nx run frontend-module-ui:lint` resolves
+the package's, and a rule known to only one passes one and fails the other. Both wirings were
+verified live. The `files` glob is what keeps the rule inside the library: `nx run frontend:lint`
+and `nx run admin:lint` report zero hits from it, which is intended — the rule is about what the
+library hardcodes, not about what an app writes for its own pages.
+
+## The annotation convention
+
+Some literals are right, so the rule has an opt-out that requires a reason:
+
+```tsx
+// theme-literal: a scrim is black in every theme; its opacity is the lever, not its hue
+'bg-black/30 backdrop-blur-sm',
+```
+
+The marker covers its own line and the next line of **code** — it resolves forward past a second
+comment line and past the `}` that closes a `{/* … */}` JSX comment, so a reason may run to two or
+three lines and survives prettier reflowing a ternary. The regex requires text after the colon: a
+bare `// theme-literal:` does not suppress anything (proven below). This is the shape the repo
+already uses for `// no-trim:`, `// blank-ok:` and `// no-persist:` rather than a third one, and it
+has one practical advantage over `// eslint-disable-next-line`: `eslint --fix` from the root deletes
+a disable directive naming a rule that run does not know, and a plain comment survives that.
+`// eslint-disable-next-line clicktap/no-literal-palette-color -- reason` still works.
+
+There is **no** file-level or package-level suppression anywhere in this change. Every one of the 17
+exemptions is a single line carrying its own reason.
+
+### The 17 deliberate literals
+
+| Component | Class | Why it stays |
+|---|---|---|
+| `ModalOverlay` | `bg-black/30` | A scrim is black in every theme; its opacity is the lever. |
+| `Checkbox` | `stroke-white`, `fill-white` | The tick and the indeterminate dash are drawn **on the filled control**, so they take their contrast from that fill, not from the page. |
+| `ProductCardSwatches` | `ring-white`, `bg-white` ×2, `bg-slate-400` ×2, `text-white` | Every one is drawn on the swatch's **own** color, which comes from product data. `needsBorder` is the component's own light/dark test for that color. A re-themed `--color-fg-inverse` would make the check vanish on half a catalog. |
+| `SwatchColor` | `ring-white`, `text-white` | The same marks, in the filter-sidebar rendering of the same swatch. |
+| `GemIcon` | `text-purple-500` | Purple *is* the premium/upgrade signal the glyph carries. |
+| `LockIcon` | `text-yellow-500` | Amber *is* the restricted/permission signal. |
+| `StarIcon` | `text-amber-400` | A filled rating star is gold in every theme. (Its empty state already used `text-fg-subtle` and still does.) |
+| `PermissionRequired` | `bg-yellow-100` | The chip tint pairs with `LockIcon`'s deliberately literal amber. |
+| `UpgradePrompt` | `bg-purple-100` | The chip tint pairs with `GemIcon`'s deliberately literal purple. |
+| `Radio` | `text-red-300` | A faded danger for the disabled-invalid state. |
+
+The ticket named four that must survive — `ModalOverlay`, `Checkbox`, `ProductCardSwatches`, `Icon`.
+Each was read in context and confirmed. `SwatchColor` is the same swatch mark as
+`ProductCardSwatches` rendered in the filter sidebar and is annotated on the same grounds.
+
+### Deferred to CTAP-1834
+
+Three of the annotations are annotations only because the token set has no role for them. They are
+not judgments that a literal is right forever; no token is invented here:
+
+- **A warning surface** and **a brand/premium surface** — `bg-yellow-100` in `PermissionRequired`,
+  `bg-purple-100` in `UpgradePrompt`. `--color-danger-surface` exists; there is no `warning`/`info`
+  equivalent, and nothing for a brand tint at all.
+- **A muted danger** — `text-red-300` in `Radio`. `--color-danger-ring` is red-200 and is
+  documented as the invalid focus ring's value; using it as disabled text would be role abuse.
+- **Shadows.** `shadow-[0_8px_24px_rgba(0,0,0,0.1)]` in `Dialog` and `shadow-[0_0_0_2px_#222]` in
+  the two swatch components are out of the rule's scope entirely, as the ticket directed.
+
+## What changed
+
+Every swap and its role token. `theme.css` defines each token as the literal Tailwind value the
+components used before the CTAP-1123 sweep, so "same value" below means byte-identical in the
+default theme.
+
+**Same light-theme value (76 occurrences) — nothing renders differently:**
+
+| Literal | Token | n |
+|---|---|---|
+| `bg-white` | `bg-surface` | 25 |
+| `text-white` | `text-fg-inverse` | 17 |
+| `bg-slate-200` | `bg-border-subtle` | 9 |
+| `bg-slate-300` | `bg-border` | 8 |
+| `outline-slate-500` | `outline-fg-muted` | 5 |
+| `bg-slate-500` | `bg-fg-muted` | 3 |
+| `bg-slate-400` | `bg-border-emphasis` | 2 |
+| `border-slate-500` | `border-fg-muted` | 2 |
+| `outline-white` | `outline-fg-inverse` | 2 |
+| `border-white` | `border-surface` | 1 |
+| `fill-slate-300` | `fill-border` | 1 |
+| `stroke-slate-300` | `stroke-border` | 1 |
+
+**Different light-theme value (42 occurrences):**
+
+| Literal | Token | Direction | n |
+|---|---|---|---|
+| `text-slate-600` | `text-fg-muted` (slate-500) | one step lighter | 7 |
+| `text-slate-800` | `text-fg` (slate-900) | one step darker | 6 |
+| `text-slate-700` | `text-fg` (slate-900) | two steps darker | 4 |
+| `text-slate-700` | `text-fg-muted` (slate-500) | two steps lighter | 2 |
+| `text-slate-300` | `text-fg-subtle` (slate-400) | one step darker | 4 |
+| `bg-slate-600` | `bg-fg-muted` (slate-500) | one step lighter | 3 |
+| `text-black` | `text-fg` (slate-900) | a hair lighter | 3 |
+| `border-gray-200` | `border-border-subtle` (slate-200) | same lightness, faint hue shift | 2 |
+| `bg-slate-50` / `fill-slate-50` / `bg-gray-50` | `*-surface-subtle` (slate-100) | one step darker | 3 |
+| `border-slate-100` / `outline-slate-100` | `*-border-subtle` (slate-200) | one step darker | 2 |
+| `border-gray-100` | `border-border-subtle` (slate-200) | one step darker | 1 |
+| `text-slate-100` | `text-fg-inverse` (`#fff`) | a hair brighter | 1 |
+| `text-gray-600` | `text-fg-muted` (slate-500) | one step lighter | 1 |
+| `stroke-slate-800` / `fill-slate-800` | `stroke-fg` / `fill-fg` (slate-900) | one step darker | 2 |
+| `text-green-700` | `text-success` (green-600) | one step lighter | 1 |
+
+Where the same literal maps to two tokens, the role decided it. `text-slate-700` is the label on an
+unselected swatch pill whose selected twin is `text-fg-inverse` on `bg-surface-inverse` — that is
+the full-emphasis foreground, `text-fg`. The same class on `EmptyResults`' action links, whose hover
+was already `text-fg`, is the muted end of a ladder, so `text-fg-muted`.
+
+### Rendering changes, component by component
+
+A consumer who overrode one of these through `className` may have been working around the bug;
+`cn` is tailwind-merge, so their override still wins and they lose nothing by dropping it.
+
+| Component | What visibly changes in the default (light) theme |
+|---|---|
+| `Accordion` | Trigger focus ring slate-100 → slate-200. |
+| `Badge` (`faded`) | Label slate-800 → slate-900. |
+| `CollectionFilterChips` | Top rule gray-100 → slate-200 (a step darker). |
+| `CollectionFilters` | Group heading slate-800 → slate-900; the two "clear" links' hover slate-700 → slate-900; the trigger and footer rules gray-200 → slate-200 (same lightness, a faintly cooler hue). |
+| `CollectionToolbar` | Sort label gray-600 → slate-500 (lighter). |
+| `EmptyResults` | Empty-state icon and the `\|` separator slate-300 → slate-400 (darker); heading slate-800 → slate-900; the two action links slate-700 → slate-500 (lighter at rest; their hover was already `text-fg`). |
+| `FeatureGate` — `AccessDenied`, `PermissionRequired`, `UpgradePrompt` | Body copy slate-600 → slate-500 (lighter). |
+| `Input` | Password-reveal toggle hover slate-600 → slate-500 (lighter). |
+| `Link` | Hover slate-800 → slate-900; disabled and disabled-hover slate-300 → slate-400 (darker, so more legible). |
+| `Menu`'s `ContextMenu` | Panel gray-50 → slate-100 and its arrow slate-50 → slate-100 (both a step darker). |
+| `Pagination` | Control hover slate-50 → slate-100; page-item border slate-100 → slate-200; the `<nav>` text slate-600 → slate-500. |
+| `PasswordCheck` | A met requirement's label green-700 → green-600 — which also makes it agree with its own check icon, already `text-success`; the strength segments past the current strength slate-600 → slate-500. |
+| `PhoneInput` | Country-dropdown text and the dial-code-only input state slate-600 → slate-500. |
+| `CircularProgressbar` | Progress arc and the centered value slate-800 → slate-900. |
+| `ProductPrice` | Price and label `#000` → slate-900. |
+| `ProductCardSwatches`, `SwatchText` | Unselected pill label slate-700 → slate-900. |
+| `Tab` | Labels slate-800 → slate-900; the selected label on `solid`/`enclosed` slate-100 → `#fff`; the `solid` overlay slate-600 → slate-500 — under `mix-blend-color`, which takes only hue and chroma, and those two are within 0.003 of each other, so this one is not observable. |
+| `UploadImage` | **The only new rendering.** The class was `hover:bg-slate-100s` — a typo, not a utility, so it never painted. It is now `hover:bg-surface-subtle`, so the control gains the hover background it was always meant to have. Its `hover:text-black` also becomes slate-900. |
+| `Accordion` (`shadow` variant) | Nothing. `shadow-slate-200` set a shadow *color* with no `shadow` utility beside it, so it painted nothing; it is deleted. |
+
+Everything not in that table renders exactly as before: `Button`, `Checkbox`, `ContextMenu`,
+`CreditCardInput`, `CreditCardExpirationInput`, `DateInput`, `Dialog`, `Divider`, `DobInput`,
+`Drawer`, `LinkAsButton`, `Loader`'s `Pulse`, `Meter`, `ModalOverlay`, `NumberInput`, `PinInput`,
+`LinearProgressbar`, `Radio`, `Select` (all four files), `Skeleton`, `Slider`, `Switch`, `TabList`,
+`TimeInput`, `ToggleButton`, `Tooltip`, and the three `Icon` glyphs.
+
+## On `Dialog.spec.tsx`
+
+CTAP-1902 put a rendered-DOM assertion into `Dialog.spec.tsx` that fails on any literal palette
+utility reaching the panel. That file arrives with PR #3030 and is not in `master`, so nothing here
+touches it — and it should **stay**. The two checks do not overlap: the lint rule is static and sees
+string literals in that one file, while the spec asserts on what actually reached the DOM, so it
+still catches a literal arriving through a `tv()` variant assembled elsewhere, a HeroUI default, or
+a consumer's `className`. The rule can also be switched off on a line by an annotation; the spec
+cannot. Belt and braces, on purpose.
+
+## Consumer Impact
+
+**No action needed to upgrade.** No prop, export or type changes. Class names on the rendered DOM do
+change (`bg-white` becomes `bg-surface`), so a consumer asserting on a literal class name in a test —
+or targeting one in a CSS selector — needs to update that assertion; nothing else does.
+
+**You can now re-theme.** The point of the sweep: overriding `--color-surface`, `--color-fg` and the
+rest under a class, an attribute or a media query now repaints these components, where before it
+repainted only the ones CTAP-1123 had already converted.
+
+```css
+:root[data-theme='dark'] {
+  --color-fg: oklch(98% 0 0);
+  --color-surface: oklch(20% 0.02 260);
+  --color-surface-subtle: oklch(25% 0.02 260);
+}
+```
+
+**Drop workaround overrides.** If you were passing `className="bg-slate-900 text-white"` to a
+component purely because it hardcoded a light surface, remove it and set the token instead.
+
+**Contributing to the package.** Write the token, not the literal. If a literal is genuinely right,
+say why on the line above with `// theme-literal: <reason>` — the reason is required, and a bare
+marker does not suppress anything.
+
+## Verification
+
+```
+nx run frontend-module-ui:lint       0 errors (1 pre-existing react-hooks warning in ModalOverlay)
+nx run frontend-module-ui:typecheck  passed
+nx run frontend-module-ui:test       24 suites, 136 tests, all passed
+nx run frontend:lint                 0 errors, 0 hits from this rule
+nx run admin:lint                    0 errors, 0 hits from this rule
+```
+
+The rule was proven to fail before it was trusted to pass. Putting `bg-white` back into `Dialog`:
+
+```
+libs/frontend-modules/ui/src/components/Dialog/Dialog.tsx
+  64:7  error  `bg-white` is a literal palette color: a re-themed app cannot repaint it. …
+               clicktap/no-literal-palette-color
+✖ 2 problems (1 error, 1 warning)
+```
+
+and adding a reason-less `// theme-literal:` above it did **not** silence it:
+
+```
+  65:7  error  `bg-white` is a literal palette color: …  clicktap/no-literal-palette-color
+✖ 2 problems (1 error, 1 warning)
+```
+
+Both were reverted.

package/docs/migrations/index.json

@@ -1,4 +1,24 @@
 [
+  {
+    "path": "2026/09/ui-2026-09-24-semantic-color-token-lint-rule.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-09-24",
+    "title": "IMPROVEMENT: literal palette colors are a lint error in `@clicktap/ui`, and the 136 existing ones are resolved",
+    "classification": "IMPROVEMENT",
+    "breaking": "No API change, and no prop, export or class-name contract moves. **Visual:** 76 of the 118 swaps resolve to the exact same light-theme value and render identically. The other 42 do not — they are listed component by component under \"Rendering changes\" and are all one step along a neutral ramp, except `UploadImage`, whose hover background **appears for the first time** because the class it had was a typo.",
+    "affects": "54 files under `src/components/**` — every component listed in \"What changed\" below — plus the new root-level `eslint.rules.no-literal-palette-color.mjs` and the two eslint configs that reference it."
+  },
+  {
+    "path": "2026/09/ui-2026-09-24-dialog-semantic-surface-tokens.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-09-24",
+    "title": "BUGFIX: `Dialog` paints from semantic tokens instead of literal `bg-white`",
+    "classification": "BUGFIX",
+    "breaking": "No. It is a change of default, and the default only moves where a consumer has re-themed the tokens: an app on the shipped light theme sees **no visual change at all** (`--color-surface` is `#fff`, the exact value `bg-white` produced, and `--color-fg` is the slate-900 such an app already inherited). A dark-themed app stops getting a white panel and gets its own surface. No API change, and the `className` escape hatch is untouched.",
+    "affects": "`src/components/Dialog/Dialog.tsx` — every `<Dialog>` that does not already pass its own background in `className`."
+  },
   {
     "path": "2026/09/ui-2026-09-23-interactive-elements-cursor-pointer.md",
     "module": "libs/frontend-modules/ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",