EpicNext semantic theme contrast design

Goal

Guarantee readable text and controls across every built-in light/dark preset, including the complete admin panel, without flattening intentional status colors or graphical previews.

Root cause

EpicNext calculates readable foregrounds for a limited set of theme values, while admin pages still contain hundreds of fixed Tailwind colors and raw hex values. Fixed gray, white, green, red, amber, and blue classes cannot adapt to arbitrary preset surfaces. The result is low-contrast or invisible copy when a preset changes luminosity.

Semantic token contract

Runtime theme generation will expose adaptive tokens for:

normal, muted, subtle, and disabled text;
surface, elevated surface, dropdown, input, and overlay content;
admin sidebar background, text, muted text, active item, and border;
success, warning, error, and info foregrounds on page surfaces;
success, warning, error, and info foregrounds on solid semantic backgrounds;
subtle semantic backgrounds and borders for badges, notices, and statuses.

Every token is derived independently for light and dark mode from the active complete preset. Readable foregrounds must meet WCAG AA 4.5:1 for normal text. Decorative borders and non-text graphics are not forced to meet text contrast.

Component migration

Admin components will use semantic utilities instead of palette-specific Tailwind colors. The migration covers layout, navigation, tables, forms, notices, badges, statuses, and action feedback across src/app/admin and src/components/admin.

Intentional graphical colors remain local in favicon/image previews, catalog artwork, color pickers, and user-authored preview content. These exceptions must be explicit and are not used for ordinary text.

The admin sidebar will stop using a fixed purple/black palette and will consume dedicated sidebar tokens. Public components touched by the audit will use the same semantic text and status tokens.

CSS architecture

theme-css.ts remains the single runtime generator. It will emit semantic variables for each palette. globals.css will define reusable semantic classes for text hierarchy, notices, badges, tables, inputs, and admin navigation. Component code will select meaning (success, muted, warning) rather than a concrete color.

No global override of arbitrary Tailwind utility classes will be introduced because that would make third-party and graphical components unpredictable.

Verification

Automated verification will include:

contrast tests for every semantic foreground/background pair in every preset and mode;
contract tests requiring every runtime semantic variable;
a source audit that rejects new risky hard-coded text/background combinations in admin UI outside an explicit graphical allowlist;
complete test suite, typecheck, and production build;
a final diff audit ensuring the existing local package.json change is not staged.

2.9 KiB Raw Blame History