refactor(design-system): migrate single-color tokens to @theme + lint @utility /N footgun (#1849)

* refactor(design-system): migrate single-color semantic tokens to @theme + lint @utility /N footgun

Closes #1653. Tailwind v4 auto-generates the `/N` opacity-modifier
pipeline (`color-mix(in oklab, var(--color-X) N%, transparent)`)
only for colors declared in `@theme`. Tokens emitted as
`@utility name { @apply ... }` bypass that pipeline entirely, so
`text-link/70`, `bg-surface/50`, etc. silently compile to nothing —
the workaround from #1626 was `text-inverse opacity-70`.

Migrate the 11 single-color semantic tokens whose class names match
Tailwind's color-utility convention (`bg-X`, `text-X`, `border-X`)
and have no cross-prefix collision:

  bg-surface, bg-surface-hover, bg-surface-inset, bg-surface-inset-hover
  bg-container, bg-container-hover, bg-container-inset, bg-container-inset-hover
  bg-nav-indicator
  text-link
  border-tertiary

After migration, `--color-surface`, `--color-container`, etc. live
in `@theme` and Tailwind auto-generates every prefix variant
(`bg-surface`, `text-surface`, `border-surface`, plus
`/10`..`/100`). The original utility class names are preserved
(now via auto-generation instead of `@utility` blocks), so every
existing callsite continues to work.

NOT migrated, by design:

- **inverse family** (`bg-inverse`, `text-inverse`, `bg-inverse-hover`,
  `border-inverse`): bg- and text- variants have *different* colors,
  cannot share one `--color-inverse`. Renaming the family
  (`bg-strong-surface` + `text-on-strong-surface`) would touch
  ~61 view files and trade one footgun for semantic loss; deferred
  until a concrete `bg-inverse/N` use case appears.
- **primary/secondary/subdued/destructive** (cross-prefix collision):
  `text-primary` (gray.900) and `border-primary` (alpha-black.300)
  carry deliberately distinct values, can't share `--color-primary`.
  Same for the secondary/subdued pairs. Migrating either alone
  would force a rename of the other.
- **button-bg-*, tab-item-*, tab-bg-group**: class names don't
  follow Tailwind's `<prefix>-<name>` convention, so
  auto-generation would emit `bg-button-bg-primary` not
  `button-bg-primary`.
- **composites** (`bg-loader`, `bg-overlay`, `shadow-border-*`,
  `border-divider`): compile to multiple properties or
  alias-reference other utilities — must stay as @utility.

Add an `erb_lint` DeprecatedClasses rule covering the
@utility-only tokens with `\d+` regex modifiers so any future
`text-inverse/70` etc. fails CI with the explanation that
`opacity-N` is the workaround and #1653 is the tracking issue.
Verified the rule fires on synthetic input; verified zero new
violations on the existing app.

Stats: `@utility` blocks dropped from 45 → 34; @theme primitives
grew from 183 → 194.

* fix(review): cover remaining @utility /N footgun tokens in erb_lint

CodeRabbit flagged that the new DeprecatedClasses /N rule missed
seven still-defined @utility color tokens: border-destructive,
border-solid, button-bg-secondary-strong, button-bg-secondary-strong-hover,
button-bg-disabled, button-bg-ghost-hover, button-bg-outline-hover.
Without them, classes like button-bg-disabled/50 pass lint while
Tailwind silently drops the class.

Adding the patterns surfaced two pre-existing offenders
(border-destructive/30, border-destructive/20). Swap both to solid
border-destructive — the @utility override defines red-500 (light)
while --color-destructive in @theme is red-600, so the /N modifier
was rendering an off-shade rather than the intended faded variant.

Verified the rule fires on synthetic input for all seven new
patterns, then verified zero remaining violations on the new
patterns across app/**/*.erb.

* chore(erb_lint): add trailing newline to .erb_lint.yml

Per review feedback on #1849. Some editors flag the missing newline;
keeps style consistent with the rest of the codebase.
This commit is contained in:
Guillem Arias Fauste
2026-05-20 18:20:38 +02:00
committed by GitHub
parent 25bb394378
commit e67ff3e3dc
5 changed files with 72 additions and 103 deletions

View File

@@ -14,6 +14,17 @@
--color-destructive: var(--color-red-600);
--color-info: var(--color-blue-600);
--color-shadow: --alpha(var(--color-black) / 6%);
--color-link: var(--color-blue-600);
--color-tertiary: var(--color-alpha-black-100);
--color-surface: var(--color-gray-50);
--color-surface-hover: var(--color-gray-100);
--color-surface-inset: var(--color-gray-100);
--color-surface-inset-hover: var(--color-gray-200);
--color-container: var(--color-white);
--color-container-hover: var(--color-gray-50);
--color-container-inset: var(--color-gray-50);
--color-container-inset-hover: var(--color-gray-100);
--color-nav-indicator: var(--color-black);
--color-gray-25: #FAFAFA;
--color-gray-50: #F7F7F7;
--color-gray-100: #F0F0F0;
@@ -202,6 +213,17 @@
--color-destructive: var(--color-red-400);
--color-info: var(--color-blue-500);
--color-shadow: --alpha(var(--color-white) / 8%);
--color-link: var(--color-blue-500);
--color-tertiary: var(--color-alpha-white-200);
--color-surface: var(--color-black);
--color-surface-hover: var(--color-gray-800);
--color-surface-inset: var(--color-gray-800);
--color-surface-inset-hover: var(--color-gray-800);
--color-container: var(--color-gray-900);
--color-container-hover: var(--color-gray-800);
--color-container-inset: var(--color-gray-800);
--color-container-inset-hover: var(--color-gray-700);
--color-nav-indicator: var(--color-white);
--budget-unused-fill: var(--color-gray-500);
--budget-unallocated-fill: var(--color-gray-700);
--shadow-xs: 0px 1px 2px 0px --alpha(var(--color-white) / 8%);
@@ -212,70 +234,6 @@
}
}
@utility bg-surface {
@apply bg-gray-50;
@variant theme-dark {
@apply bg-black;
}
}
@utility bg-surface-hover {
@apply bg-gray-100;
@variant theme-dark {
@apply bg-gray-800;
}
}
@utility bg-surface-inset {
@apply bg-gray-100;
@variant theme-dark {
@apply bg-gray-800;
}
}
@utility bg-surface-inset-hover {
@apply bg-gray-200;
@variant theme-dark {
@apply bg-gray-800;
}
}
@utility bg-container {
@apply bg-white;
@variant theme-dark {
@apply bg-gray-900;
}
}
@utility bg-container-hover {
@apply bg-gray-50;
@variant theme-dark {
@apply bg-gray-800;
}
}
@utility bg-container-inset {
@apply bg-gray-50;
@variant theme-dark {
@apply bg-gray-800;
}
}
@utility bg-container-inset-hover {
@apply bg-gray-100;
@variant theme-dark {
@apply bg-gray-700;
}
}
@utility bg-inverse {
@apply bg-gray-800;
@@ -336,14 +294,6 @@
}
}
@utility text-link {
@apply text-blue-600;
@variant theme-dark {
@apply text-blue-500;
}
}
@utility shadow-border-xs {
box-shadow: var(--shadow-xs), 0px 0px 0px 1px var(--color-alpha-black-50);
@@ -400,14 +350,6 @@
}
}
@utility border-tertiary {
@apply border-alpha-black-100;
@variant theme-dark {
@apply border-alpha-white-200;
}
}
@utility border-divider {
@apply border-tertiary;
}
@@ -555,11 +497,3 @@
@apply bg-alpha-black-700;
}
}
@utility bg-nav-indicator {
@apply bg-black;
@variant theme-dark {
@apply bg-white;
}
}