Frontend V2 Theming
Designfrontend-v2-themingFrontend V2 Theming is an Agent Skill for design published in the rommapp/romm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Theming, design tokens, colors, and visual language in the RomM v2 frontend. Use when styling v2 components, picking colors, adding/using CSS variables, working with light/dark themes, or whenever you'd reach for a hex/rgba literal. Covers the token pipeline (src/v2/tokens/index.ts → build:tokens → tokens.css), the .r-v2 scope classes, the zero-hex-literal policy, and shared state semantics. Trigger on any color/theme/token work under frontend/src/v2/.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/rommapp/romm/blob/HEAD/.claude/skills/frontend-v2-theming/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/frontend-v2-theming, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
RomM v2 — Tokens, Theming & Visual Language
Tokens are the only source of truth for theming. Zero hex/rgba() literals in v2 components. If a value is missing, add a token. Every component must work in both v2-dark and v2-light.
Token pipeline
src/v2/tokens/index.ts is the source. It feeds two consumers:
src/v2/styles/tokens.css— generated byscripts/build-tokens.ts(npm run build:tokens, hooked intopredev/prebuild). Do not hand-edit. This is how the vast majority of tokens are consumed:var(--r-color-...)in CSS.- Direct JS/TS imports of named exports (
colorCanvas,colorCoverArt,layout, …) for the few cases needing a token value in JavaScript — baking colors into an SVG string (utils/covers), canvas/QR backgrounds (Player/Ruffle.vue,ShowQRCodeDialog), and the virtualiser's pixel math (Gallery/listColumnsreadinglayout).
v2 has no Vuetify theme of its own. tokens.css emits a palette block per theme under .r-v2.r-v2-dark / .r-v2.r-v2-light; RomM.vue toggles those classes on <html>. v2 surfaces never read Vuetify's runtime theme.
Caveat: a wrapped Vuetify component still resolves
color="primary"against Vuetify's own registered themes (src/plugins/vuetify.ts, sourced from v1's@/styles/themes). They mirror the brand tokens by hand (both#8B74E8), so they line up, but it's a parallel source. Prefervar(--r-...)over thecolorprop.
Adding a new token
- Add it to
src/v2/tokens/index.tswith a semantic, role-based name (--r-color-danger, not--r-color-red). - Provide both dark and light values.
- Consume via
var(--r-...)(CSS) or the named export (JS). - Run
npm run build:tokensto regeneratetokens.css. - If the JS→CSS variable name needs an exception (e.g.
--r-nav-h), add an entry toNAME_OVERRIDESin the generator.
Where the scope classes live — and why <html>
.r-v2, .r-v2-dark, .r-v2-light go on <html> (RomM.vue toggles them whenever uiVersion or the active theme changes). Vuetify teleports overlays (VDialog, VMenu, VTooltip) to <body> > .v-overlay-container, outside <v-app>. Only <html> covers both the regular tree and the teleports — without it, overlays lose their tokens.
Diagnostics — when var(--r-color-...) resolves to nothing on an overlay
- Check
RomM.vue's watch ondocumentElement.classList(load-bearing). - Check that the teleported component carries a
content-classtying it back to scope (e.g.RDialogusescontent-class="r-dialog"). - Never "fix" it by swapping the token for a hex literal — that hides the bug and breaks the dual theme.
Visual language
- Single visual vocabulary. Every surface (dialog, menu, popover, card, toolbar) reads as a sibling — same blur, curvature, depth. No standalone "dialog look" vs "menu look".
- Canonical references when designing: ask the user before consulting
https://mockup.thebirdcage.tv/. They decide whether the mockup or existing primitives take priority. - State semantics are shared across primitives (don't reinvent per component):
- hover (neutral, or brand-tinted on selected rows)
- selected/checked (
--r-color-brand-primary) - active/favorite (
--r-color-fav) - focus (modality-gated; visible only on
key/pad— seefrontend-v2-input) - busy/pending · disabled
- Implementation gotchas:
RDialogships unscoped<style>at the bottom that strips Vuetify defaults from.v-overlay__content. Load-bearing — without it the--r-radius-cardcorners disappear.- Every dialog goes through
RDialog; every menu throughRMenu.
Color-literal policy: zero exceptions
Outside src/v2/tokens/index.ts (the source-of-truth TS module) and the generated src/v2/styles/tokens.css, no hex or rgba() literals exist anywhere in v2. Everything previously "excepted" is now a token or a color-mix:
- Cover-overlay glass →
--r-color-overlay-*(fixed dark glass; never theme-flips). - Cover artwork placeholder & shimmer →
--r-color-cover-placeholder,--r-color-cover-placeholder-bright. - Panel / tooltip / shimmer-sweep →
--r-color-panel,--r-color-panel-border,--r-color-tooltip-bg,--r-color-shimmer-sweep. - Backdrop scrims (
global.css) →color-mix(in srgb, var(--r-color-bg) X%, transparent). - Status tints →
color-mix(in srgb, var(--r-color-status-base-{success,warning,danger,info}) X%, transparent). - Brand-tinted backgrounds (selected rows, focus rings) →
color-mix(in srgb, var(--r-color-brand-primary) X%, transparent). - Black/white shadows →
color-mix(in srgb, black X%, transparent)(CSS named color, not a hex literal). - Metadata-provider chips →
--r-color-provider-*. Player canvas →--r-color-canvas-bg,--r-color-canvas-bg-deep. - Emphasis pill (always-white-on-dark "Play" CTA over cover art) →
--r-color-overlay-emphasis-bg/-fg/-bg-hover.
If a literal would otherwise be needed, the answer is: add a token (steps above), then consume via var(--r-color-...) or the named export.
Style conventions
- Scoped
<style>by default; unscoped only for teleport overrides. - BEM-ish class names:
.feature__element--modifier. Prefixes:.r-v2-...for app-shell surfaces outside components;.r-...for globally shared utilities/tokens. - No plain CSS where a Vuetify utility class covers the case (
d-flex,pa-4,align-center).