@clicktap/ui 2.3.1 → 2.3.3

package/docs/migrations/2026/09/ui-2026-09-23-interactive-elements-cursor-pointer.md

@@ -0,0 +1,84 @@
+# BUGFIX: interactive elements show a pointer cursor under Tailwind v4
+
+**Date:** 2026-09-23
+**Package:** `@clicktap/ui`
+**Affects:** `src/components/Button/Button.tsx`, `ResendCode/ResendCode.tsx`, `Select/ComboBoxSelect.tsx`, `Collection/EmptyResults/EmptyResults.tsx`, `Collection/CollectionFilters/CollectionFilters.tsx`.
+**Classification:** BUGFIX
+**Breaking:** No API change. **Visual:** hovering an enabled button in any of the affected components now shows a pointer cursor instead of the default arrow. Disabled states are unchanged (still `not-allowed` where they had it, still no explicit cursor where they didn't).
+**Ticket:** CTAP-1874
+
+## Problem
+
+Tailwind v4's Preflight changed the `<button>` reset from `cursor: pointer` to `cursor: default`, so
+a class that used to be unnecessary now is. `Button` and `ResendCode` never set `cursor-pointer`
+explicitly — they relied on the browser/Tailwind v3 default — so under Tailwind v4 they drew the
+arrow cursor on hover instead of a hand. `Input`'s password-reveal toggle already set
+`cursor-pointer` explicitly, which is what made this an inconsistency rather than a design decision:
+the library already knew to do this, just not everywhere.
+
+The ticket asked for a grep of the rest of the package for `<button` without a cursor class rather
+than stopping at the two reported components. That turned up three more raw `<button>` elements
+missing it: the combobox's dropdown-arrow toggle (`ComboBoxSelect`), and the "Clear search" / "Clear
+all filters" text buttons in `EmptyResults` and `CollectionFilters` (the last of these appears at
+three call sites: the search-clear icon, the desktop sidebar, and the mobile filter drawer).
+`Pagination`, `ButtonSelect` and `MultiButtonSelect` already had `cursor-pointer` and needed no
+change.
+
+## What changed
+
+Added `cursor-pointer` to the enabled state of every affected button, alongside `disabled:cursor-not-allowed`
+where a disabled state exists:
+
+| Component | Before | After |
+|---|---|---|
+| `Button` | no cursor class | `cursor-pointer disabled:cursor-not-allowed` |
+| `ResendCode` | `disabled:cursor-not-allowed` only | `cursor-pointer disabled:cursor-not-allowed` |
+| `ComboBoxSelect` (arrow toggle) | no cursor class | `cursor-pointer disabled:cursor-not-allowed` |
+| `EmptyResults` (both actions) | no cursor class | `cursor-pointer` (no disabled state on these buttons) |
+| `CollectionFilters` (all three call sites) | no cursor class | `cursor-pointer` (no disabled state on these buttons) |
+
+`Button` gaining `disabled:cursor-not-allowed` is new — it had no cursor handling in either state
+before this fix — and matches the pattern already established by `ResendCode` and `Input`.
+
+## Consumer Impact
+
+**No action needed to upgrade.** This only adds a `cursor-pointer` (and, for `Button`, a
+`disabled:cursor-not-allowed`) utility to the base class list; nothing is removed, and `className`
+already merges last via `cn`/tailwind-merge, so a consumer overriding cursor at the call site
+continues to win.
+
+**Drop any hand-rolled workaround.** If you were passing a `className`/`buttonClassName` purely to
+restore the pointer cursor under Tailwind v4, remove it:
+
+```tsx
+// BEFORE
+<ResendCode buttonClassName="cursor-pointer underline" ... />
+
+// AFTER
+<ResendCode ... />
+```
+
+## Verification
+
+New/updated specs, run via `nx run frontend-module-ui:test`:
+
+- `Button.spec.tsx` — `cursor-pointer` asserted for all four `variant` aliases (`primary`,
+  `secondary`, `tertiary`, `link`).
+- `ResendCode.test.tsx` — `cursor-pointer` asserted while enabled; `disabled:cursor-not-allowed`
+  still asserted while disabled.
+- `Select/ComboBoxSelect.spec.tsx` (new) — `cursor-pointer` on the dropdown-arrow toggle, rendered
+  through the public `<Select searchable>`.
+- `Collection/EmptyResults/EmptyResults.spec.tsx` (new) — `cursor-pointer` on both "Clear search" and
+  "Clear all filters".
+- `Collection/CollectionFilters/CollectionFilters.spec.tsx` (new) — `cursor-pointer` on the
+  search-clear icon button and the desktop "Clear all filters" button.
+
+All ten new/changed assertions were confirmed to fail against the pre-fix code (missing
+`cursor-pointer` in the rendered className) before the fix landed, then pass after.
+
+⚠️ **Not independently re-verified against a live Tailwind v4 build.** The tests assert the utility
+class is present in the rendered `className`; they cannot show the class actually resolves to a
+hand cursor in a given consumer's compiled CSS (e.g. if a consumer's Tailwind config purges
+`cursor-pointer` for some reason). The mechanism reported in the ticket — Preflight's `cursor:
+default` reset on `<button>` under Tailwind v4 — was not independently reproduced in a browser as
+part of this fix; it was taken from the ticket's own evidence.

package/docs/migrations/2026/09/ui-2026-09-24-dialog-semantic-surface-tokens.md

@@ -0,0 +1,81 @@
+# BUGFIX: `Dialog` paints from semantic tokens instead of literal `bg-white`
+
+**Date:** 2026-09-24
+**Package:** `@clicktap/ui`
+**Affects:** `src/components/Dialog/Dialog.tsx` — every `<Dialog>` that does not already pass its own background in `className`.
+**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.
+**Ticket:** CTAP-1902
+
+## Problem
+
+`Dialog`'s base class list carried the literal `bg-white` and set no text color at all. In an app
+whose semantic tokens resolve dark, the panel painted white while the text inherited the app's
+light `--color-fg` — so the dialog was not merely off-brand, it was **illegible**.
+
+The same class list already used `border-border-emphasis`, a semantic token, which is what makes
+this read as a class the CTAP-1123 sweep missed rather than a deliberate choice. A reader could
+not tell which colors in it were intentional.
+
+Measured, rendering `<Dialog aria-label="probe">hi</Dialog>` with no `className` and reading the
+resulting class attribute:
+
+**Before**
+
+```
+p-8 outline-0 max-w-max w-screen absolute top-2/4 left-2/4 -translate-x-1/2 -translate-y-1/2
+max-h-[calc(100dvh-2rem)] overflow-y-auto shadow-[0_8px_24px_rgba(0,0,0,0.1)] rounded-lg
+bg-white border border-solid border-border-emphasis
+```
+
+**After**
+
+```
+p-8 outline-0 max-w-max w-screen absolute top-2/4 left-2/4 -translate-x-1/2 -translate-y-1/2
+max-h-[calc(100dvh-2rem)] overflow-y-auto bg-surface text-fg
+shadow-[0_8px_24px_rgba(0,0,0,0.1)] rounded-lg border border-solid border-border-emphasis
+```
+
+## What changed
+
+* `bg-white` → `bg-surface`, the token the rest of the package's surfaces use. `theme.css`
+  defines `--color-surface: #fff`, so the shipped default renders identically.
+* `text-fg` added, so the panel's contrast is self-contained rather than inherited from whatever
+  encloses the dialog. `--color-fg` is the slate-900 those apps were already inheriting.
+* The shadow stays the literal `shadow-[0_8px_24px_rgba(0,0,0,0.1)]`, now with a comment in the
+  source saying so is deliberate. `theme.css` publishes no `--shadow-*` token, and inventing one
+  from inside a bugfix would enlarge the package's public token surface; that belongs with the
+  theming work in CTAP-1834. Unlike the background it also degrades gracefully — a 10%-black drop
+  shadow goes near-invisible on a dark ground rather than wrong.
+
+`Dialog.spec.tsx` is new and permanent. Beyond asserting the two tokens it fails on **any**
+literal palette utility reaching the rendered panel, so a later edit cannot quietly reintroduce
+one here. It verified the failure against the pre-fix source before the fix landed.
+
+## Consumer action
+
+None.
+
+A consumer that passes its own background or foreground still wins outright — `cn`/tailwind-merge
+drops the base class, and that is covered by tests now. Measured:
+
+```
+<Dialog className="bg-admin-surface"> →  … text-fg shadow-[…] rounded-lg
+                                          border border-solid border-border-emphasis bg-admin-surface
+<Dialog className="text-admin-fg">   →  … bg-surface shadow-[…] … text-admin-fg
+```
+
+`text-fg` is a text-**color** for tailwind-merge, not a font size, so it does not collide with a
+caller's `text-lg` or with the package's own `typography-*` scale.
+
+An app that wants the old unconditional white keeps it by overriding the token
+(`--color-surface: #fff`, which is already the default) or by passing `className="bg-white"`.
+
+## Still open
+
+The rest of the package is not swept. A survey of `libs/frontend-modules/ui/src` (excluding
+stories and tests) found **139 literal palette utilities across 54 component files** after this
+fix — `Collection` (31), `FeatureGate` (10), `Tabs` (8), `Pagination` (7), `TimeInput` (6),
+`Select` (6), `DateInput` (6) lead it. A lint rule that fails on literal color utilities was
+considered here and deliberately deferred: turning it on means fixing or annotating all 139, which
+is its own piece of work. It should be a separate ticket, landing the rule and the sweep together.

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,44 @@
 [
+  {
+    "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": "@clicktap/ui",
+    "date": "2026-09-23",
+    "title": "BUGFIX: interactive elements show a pointer cursor under Tailwind v4",
+    "classification": "BUGFIX",
+    "breaking": "No API change. **Visual:** hovering an enabled button in any of the affected components now shows a pointer cursor instead of the default arrow. Disabled states are unchanged (still `not-allowed` where they had it, still no explicit cursor where they didn't).",
+    "affects": "`src/components/Button/Button.tsx`, `ResendCode/ResendCode.tsx`, `Select/ComboBoxSelect.tsx`, `Collection/EmptyResults/EmptyResults.tsx`, `Collection/CollectionFilters/CollectionFilters.tsx`."
+  },
+  {
+    "path": "2026/09/ui-2026-09-23-drawer-viewport-clamp.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-09-23",
+    "title": "BUGFIX: `Drawer` no longer silently becomes a full-screen takeover",
+    "classification": "BUGFIX",
+    "breaking": "No API change. **Visual:** a `left`/`right` drawer wider than 88% of the viewport, or a `top`/`bottom` drawer taller than 88% of it, now leaves a visible sliver of the page instead of covering it entirely. A drawer that already fit is unchanged.",
+    "affects": "`src/components/Drawer/Drawer.tsx`, `Drawer.types.ts` — every `<Drawer>` whose `size` (or default) exceeds the viewport along its opening axis."
+  },
   {
     "path": "2026/09/ui-2026-09-19-dialog-scrolls-within-viewport.md",
     "module": "libs/frontend-modules/ui",

package/package.json

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