Interface themes

An interface (Classic, Slant, Cabinet…) is a theme: a simple folder, read from disk like mods and skins, which you delete to remove it. The player chooses their theme in Skins → Interface (setting uiTheme, the theme's identifier).

Why data and not code

Scripts never have access to the DOM, the CSS, or the JavaScript of the WebView, and every value that enters the page is validated in Rust (AGENTS.md). A theme is therefore data: a manifest, a token file (a strict subset of CSS), and images. The themes crate (crates/themes) validates everything against a contract of typed tokens, then the host publishes the interfaces event to the page with only the values that passed. The page sets them as CSS variables under [data-direction="<id>"]. The structural CSS (plates, buttons, tabs, list, graphs) stays in the application and reads only these tokens: a third-party theme restyles the whole interface without markup or script, and cannot execute or load anything.

Where themes are

Search order: themes/ next to prism.exe (in development: the repository's themes/ folder, found by walking up to Cargo.lock), then <data>/themes (PRISM_THEMES_DIR changes this folder). If the same identifier appears twice, the first wins and the second is reported. Each folder is named after its identifier (lowercase letters, digits, hyphens, 32 characters at most).

themes/<id>/
  theme.json     the manifest
  tokens.css     the tokens
  preview.png    (optional) preview; without it, the picker card is drawn using the tokens
  images/…       (optional) images referenced by image-type tokens

theme.json

tokens.css

One :root { --pv-x: value; … } block and up to two @media (max-width: <n>px) { :root { … } } blocks for narrow windows (320 to 4000 px). Nothing else: no other selector, property, @import, @font-face, nesting, url(), expression, or var() outside colors. /* … */ comments are allowed. Limits: 64 KiB per file, 200 declarations, 600 characters per value, images of 4 MiB at most. A missing token keeps the application's neutral value: a theme can be partial. A rejected file removes its theme from the list, with a precise message (line number, token, reason) in the log.

The token contract

Value types:

• color: colour: #rgb, #rrggbb, #rrggbbaa, rgb() / rgba() / hsl() / hsla() (numbers, comma or space syntax with / alpha), color-mix(in srgb, <color> [n%], <color> [n%]), transparent, white, black, and var(--pv-<color token>) (the only reference allowed, pointing to another color-type token, for example the accent).
• length: length: number + px, em, rem, %, vw, vh, vmin, vmax (or 0), clamp(a, b, c), min(a, b), max(a, b).
• font: font stack: 1 to 8 families (names in quotes or plain words: letters, digits, spaces, ., _, -), the last one a generic family (sans-serif, serif, monospace, system-ui, ui-monospace, cursive); PrismLegacy is the game font.
• weight: weight: integer from 1 to 1000.
• opacity: number from 0 to 1.
• easing: ease, ease-in, ease-out, ease-in-out, linear or cubic-bezier(x1, y1, x2, y2) (x from 0 to 1, y from -4 to 4).
• clip: shape: none, polygon(x y, …) (3 to 16 points, coordinates as lengths or calc(<n>% ± <n>px)) or inset(1 to 4 offsets [round 1 to 4 radii]).
• layers: gradients: none or 1 to 4 linear-gradient(…) / repeating-linear-gradient(…) separated by commas (angle 90deg or to right, 2 to 12 stops: color + 0 to 2 positions).
• filter: filter: none or up to 6 functions among saturate, brightness, contrast, grayscale, sepia, opacity, hue-rotate(<n>deg), blur(≤ 12px).
• image: image: none or image("relative/path.png") (an image file from the theme's folder: png, jpg, webp, gif, svg).
• case: none, uppercase, lowercase or capitalize.
• scheme: dark or light.
• choice: a single word taken from the token's list (see "Layout choices"). Any other word, several words, an empty value, a number or a var() is rejected.

Layout choices

A theme can change how menus are built, still purely as data: a choice token takes one word from a closed list (checked by Rust, then by the page). The page sets each valid choice as a data-layout-<name> attribute on <html>; the application's stylesheets (theme/layout.css and the components) react to it with grid-template-areas, order, and variables. A theme provides no selector and no CSS: only these words. The first word of each list is the current layout: an omitted (or rejected) choice defaults to that word, so a theme that says nothing about it changes nothing.

Replay progression graph

The progression graph (combo, accuracy, and map density on a shared time axis) is tuned with the same tokens. The component reads these keywords (data-graph-* attributes on <html>) with no per-theme markup; zoom, panning, popovers, the legend, and the hiding of miss intervals do not change.

The three curves remain distinguishable, whatever the theme does. Combo is always solid, accuracy is always dashed, and density is always an area or bars (this is not configurable). As for color, combo, accuracy, and the middle of density must differ pairwise by at least 30° of hue (for grays: 25% lightness); otherwise the entire theme is rejected at load time, with the names of the two tokens. Judgement tier colors and ratingColor are never tokens; --pv-rating-dark and --pv-tier-dark only darken their text.

The game's sizes (spacing --pv-s*, durations --pv-dur*, --pv-stagger) belong to the application; under prefers-reduced-motion, durations and --pv-shift-base drop to zero regardless of the theme.

The map artwork remains visible, whatever the theme. The map image behind the menus is part of the game's identity: a theme can tint it (--pv-shade), darken it, blur it, desaturate it, or recolor it (--pv-art-filter), but never remove it or bury it. The validator (crates/themes/src/artwork.rs) computes the share of the image's light that reaches the screen, averaged over the window: each --pv-shade gradient counts for the average of its opacity along its axis, layers compose, and the filter counts for its brightness() and opacity(). The rules: at least 20% of the image visible; no --pv-shade layer covers more than 90% on average (an opaque flat fill is rejected); in the filter, brightness ≥ 0.25, opacity ≥ 0.4, and contrast ≥ 0.5. The check also applies to every @media block. The player keeps their switch: "Black background" (Video → In-game background) hides the image in game; song select is not affected, and background brightness (backgroundBrightness) does not change either. For readable plates without hiding the image, prefer translucent plates (opacity of 0.7 to 0.85).

A theme does not change the geometry of an icon button. An icon button (IconButton, the "?" help buttons, the export and import icons) is a square whose side comes from the --pv-h-md tokens (--pv-h-sm for the small size) and whose shape comes from --pv-clip-sm; the icon is centered inside it (display: inline-grid; place-items: center, svg as a block), and neither the letter case, nor the letter spacing, nor the line height, nor the horizontal padding that themes give to text buttons affects it. A theme in capitals, in monospace, or with wide spacing therefore cannot off-center or distort an icon. Text buttons (Utiliser, Personnaliser…) remain free to take the theme's style. Safeguard: tests/icon-button-geometry.spec.ts runs through all the shipped themes, at 1400×850 and 1000×700, and checks that every icon button on the Skins page is a square, that its icon is centered to ±0.5 px, that it does not overflow, that buttons in the same row have the same height, and that hover, keyboard focus, and press do not change the size.

Writing a fourth theme

1. Copy themes/slant/ to themes/<my-id>/ (or into <data>/themes).
2. Edit theme.json (id = folder name) and tokens.css.
3. In Skins → Reload (or restart), the theme's card appears; the preview is drawn with your tokens.

To change how screens are built, add --pv-layout-* keywords to tokens.css (see "Layout choices"); an omitted keyword keeps the current layout. The shipped themes serve as examples: macos (tab rail, window banner), hack (brackets, blinking focus, dense), ledger (rail, column profile, right-hand drawer). The --pv-tier-dark and --pv-rating-dark tokens are for a light theme (tier text darkened).

Nothing else: no code, no registration. The default theme (uiTheme setting missing or invalid) is cabinet; the theme with the identifier classic remains selectable and is reserved for the original menu structure (the components that predate the design system are attached to it through this identifier); any other identifier receives the design system's structure.

Fallback

The chosen theme is missing: the first available theme is used, with a notice. No theme exists: the application uses its built-in neutral tokens (theme/fallback.css), so that nothing is ever displayed unstyled.

The skin editor

The skin editor (Skins → Customize) lives in the overlay, a separate WebView page that has neither the theme list nor the settings: the host sends it overlayTheme (the chosen theme uiTheme, accentSource, accentCustom, and the themes already validated, the same data as interfaces, nothing more and nothing a script can reach). From this, the page derives, with the same code as the menus (theme/apply.ts, direction.ts, accent.ts), the CSS variables under [data-direction], the data-layout-* words, data-scheme, and the player's accent (a theme with accent: fixed keeps its own). On the page, PrismLegacy is declared as in the menus for the font stacks that name it.

The editor's panel, tabs, fields, switches, toolbar, and frames read only these tokens, through a layer of --ed-* variables (apps/web/src/overlay/editor/editor-theme.css): surfaces (--pv-plate, --pv-bg, --pv-plate-raised), lines (--pv-line), text (--pv-text, -2, -3), accent and ink (--pv-accent, --pv-ink), selection (--pv-accent-2, falling back to the accent), radii (--pv-radius-input, --pv-radius-panel), fonts (--pv-font-body, -display, -label, -num), --pv-switch and --pv-thumb with the word --pv-layout-controls: pill (pill-shaped switch, capsule tabs with a raised thumb). No color is hard-coded in the editor (a test verifies this): a theme added later restyles it with no changes. Only the scrim over the game, the shadows, and the color space of the color picker are neutral.