# FM.video skins: how to make one FM.video turns radio stations into non-stop music-video channels. A skin changes how it looks: the colours, the corners, the type and the texture. Anyone can make one. You need a text editor and about ten minutes. This guide is for people outside the project. If you work on the app itself, the last two sections are for you. - Try skins and import your own: `/skins` - JSON Schema for editors: `/skins/skin.schema.json` - Example files: `/skins/examples/green-screen.json`, `/skins/examples/bubblegum.json` ## What a skin is A skin is one small JSON file. It holds a name, a set of colours, and a few choices from fixed lists: square or round corners, a texture, a shadow style, and a typeface for headings, body and labels. This is a complete skin: ```json { "id": "bubblegum", "name": "Bubblegum", "author": "You", "version": 1, "mode": "dark", "tokens": { "canvas": "#1b1030", "ink": "#fff4fb", "accent": "#ff8ad8" }, "shape": "round" } ``` Three colours and a shape. FM.video works out the other colours from those three (see "Leaving colours out"). ## What a skin is not A skin is data, not code. It cannot contain CSS, images, links, fonts from the web, or script. That is deliberate: - **It is safe to load a skin from a stranger.** The worst a skin can do is look bad. It cannot track anyone, load anything or change what a button does. - **It cannot break the layout.** Sizes, spacing and where things sit are not in a skin's hands, so every skin works on a phone, a laptop and a TV. - **It keeps working.** When FM.video adds a screen, every existing skin already covers it, because the screen uses the same colours by name. Some things are the same in every skin, on purpose: | Not skinnable | Why | |---|---| | The FM.video logo and wordmark | It is how people know where they are. It keeps its own colours and typeface. | | The red LIVE marker | Red means "this is a live broadcast" and nothing else. If skins could move it, it would stop meaning that. | | The layout | Where the player, the stations and the tabs sit. A skin restyles the room. It does not move the furniture. | | The video and what is drawn over it | Controls and lyrics over a moving picture are always white on a dark veil, so they can be read on any video. Textures never cover the video. | | Station logos and artwork | They belong to the stations and the artists. They are never recoloured. | | The product name | It is FM.video in every skin. | ## Quick start 1. Open `/skins` and tap the skin closest to what you want. 2. Press **Export**. You get a `.json` file with every setting filled in. (A built-in skin is exported under a new id, such as `pixel-remix`, so you can import your version straight back.) 3. Open the file in any text editor. Change the colours. 4. Back on `/skins`, paste the file into **Import a skin**, or choose the file. If something is wrong, it tells you what and how to fix it. 5. Happy with it? Send the file to anyone. They import it the same way. ## The file | Field | Required | What it is | |---|---|---| | `id` | yes | A unique kebab-case name: lower-case letters, digits and single hyphens, 40 characters at most. For example `night-drive`. The built-in ids are taken. | | `name` | yes | What people see on the skin's card. Plain text, 40 characters at most. | | `author` | yes | You. Plain text, 40 characters at most. | | `version` | yes | Always the number `1`. It is the version of this file format, not of your skin. | | `description` | no | One line about the skin. Plain text, 200 characters at most. | | `mode` | yes | `"dark"` when the canvas is darker than the text, `"light"` when it is lighter. Light skins work, with a few limits (see "Known limits"). | | `tokens` | yes | The colours. See below. May be empty. | | `shape` | no | Corners. Default `brand`. | | `texture` | no | A faint pattern on the page. Default `none`. | | `shadow` | no | Default `soft`. | | `fonts` | no | A typeface for `display`, `body` and `mono`. | A whole file is 8,192 characters at most. A real one is under 1,000. Names, authors and descriptions are plain text: no links and no markup. ## Colours (tokens) Every colour is a hex value: `#rgb` or `#rrggbb`. Colour names, `rgb()`, transparency and gradients are not accepted. FM.video makes the see-through versions itself. | Token | What it colours | FM.video's own value | |---|---|---| | `canvas` | The page background, behind everything. | `#08070c` | | `surface` | Cards, rows, tiles and sheets. | `#14101c` | | `elevated` | Menus, the player bar and anything that floats over the page. | `#1c1626` | | `line` | Hairlines and borders. | `#241830` | | `ink` | Main text and icons. Also the fill of the selected filter chip. | `#ffffff` | | `inkDim` | Secondary text: artist names, descriptions, idle icons. | `#9e93a8` | | `inkMute` | Captions, counts and small labels. | `#7a6e86` | | `accent` | Highlights: the playing song, the active tab, links, the focus ring, the equaliser bars. | `#ff2e9a` | | `action` | The fill of the main button (play) and of progress bars. Follows accent unless you set it. | same as `accent` | | `onAccent` | Text and icons sitting on an accent or action fill. | `#08070c` | | `scrim` | The veil over artwork that makes text on it readable, and the dim behind dialogs. | `#000000` | | `success` | Good news: saved, added, climbing. | `#35d07f` | | `warn` | Warnings and things that need a look. | `#ffb020` | | `info` | Neutral notices. | `#4da8ff` | | `spectrumWarm` | First colour of decorative gradients. | `#ff6a1a` | | `spectrumMid` | Middle colour of decorative gradients. | `#ce34c6` | | `spectrumCool` | Last colour of decorative gradients, and casting. | `#9b4dff` | Some notes that save time: - **`ink` is used two ways.** It is the text colour, and it is the fill of a selected chip (with `canvas` as the text on it). If ink reads well on canvas, both work. - **`accent` and `action` are usually the same.** Set `action` only when you want quiet highlights and a loud play button. The built-in Midnight does this: its accent is white and its action is pink, so the play button is the only colour on the page. Studio uses it another way: its button is the FM.video pink itself, and its pink text is a shade deeper so it reads on white. - **A skin can use more than one colour.** The grounds, the line and the two quieter inks take any hue, not only greys. Teletext has blue cards, cyan artist names and green captions. Sunset has purple grounds and peach and orange text. Sorbet has a mint page and lavender cards. The accent stays the one colour that means "this is playing" and "press here". - **`scrim` sits under text on artwork**, so `ink` has to be readable on it. In a dark skin it is black or near it. In a light skin it is white or near it. - **Keep `accent` away from pure red.** Red is for LIVE. You get a warning if your accent is close to it. ### Leaving colours out You do not have to set all seventeen. - Set **nothing** and you get FM.video's own colours. - Set **only `accent`** and you get FM.video's grounds with your accent. - Set **`canvas` or `ink`** (or make a light skin) and the colours you leave out are mixed from your own canvas and ink: `surface`, `elevated` and `line` are your canvas nudged towards your ink, `inkDim` and `inkMute` are your ink faded towards your canvas. - `onAccent` becomes near-black or white, whichever reads better on your button colour. - `scrim` becomes black in a dark skin and white in a light one. - `success`, `warn`, `info` and the three gradient colours fall back to FM.video's. Export always writes all seventeen, so you can see what was worked out and adjust it. ## Shape, texture, shadow | `shape` | What you get | |---|---| | `brand` | FM.video's corners: 12px tiles, 16px sheets, pill buttons. | | `square` | No curves anywhere. Pills, circles, avatars and the play button are square too. Made for pixel art. | | `soft` | Small, even corners (2 to 12px). Pills and circles stay round. | | `round` | Big corners (up to 44px). Pills and circles stay round. | | `texture` | What you get | |---|---| | `none` | A flat canvas. | | `scanlines` | Fine horizontal lines, like an old tube screen. | | `grid` | A 24px graph-paper grid. | | `dots` | A 12px dot matrix. | | `noise` | Film grain. | Textures are faint, they are drawn in your `ink` colour on the page canvas only, behind all content, and never over the video. | `shadow` | What you get | |---|---| | `soft` | Blurred shadows under menus, sheets and the floating video. | | `hard` | Solid offset shadows with no blur, and one under the main button. Black in a dark skin, your ink in a light one. | | `none` | Flat. The floating video gets a hairline so it still has an edge. | ## Fonts A skin picks from a fixed list. Every face is bundled with FM.video and only downloaded when a skin uses it. A skin cannot load a font of its own. ``` "fonts": { "display": "pixel", "body": "pixel-sans", "mono": "space-mono" } ``` `display` is headings, `body` is everything you read, `mono` is numbers, times and small labels. Leave a role out to keep FM.video's. | Font | Typeface | Good for | |---|---|---| | `big-shoulders` | Big Shoulders | The brand display face. Tall, condensed, loud. | | `space-grotesk` | Space Grotesk | The brand body face. | | `space-mono` | Space Mono | The brand mono face, for numbers and small labels. | | `pixel` | Jersey 15 | A chunky, condensed pixel face. Best for headings. | | `pixel-sans` | Pixelify Sans | A pixel face that stays readable at body sizes. | | `terminal` | VT323 | A green-screen terminal face. Runs small: best for headings and labels. | | `matrix` | Doto | A dot-matrix display face, like a hi-fi readout. Headings only. | | `system` | System sans | Whatever the device uses for its own interface. | | `serif` | System serif | The device's serif. Editorial and calm. | | `mono` | System mono | The device's monospace. | Headings are set large, bold and in capitals. Wide faces (`matrix`, `terminal`, `mono`) make long headings wrap onto a second line. That is fine, but check your favourite pages. `pixel` and `terminal` have one weight, so headings in them are not bold. ## The rules A skin is checked when it is imported. It is refused, with a message, if it breaks one of these. ### Contrast Text has to be readable. These are WCAG contrast ratios (1:1 is invisible, 21:1 is black on white). Any contrast checker on the web will measure them. | This | on this | at least | because | |---|---|---|---| | `ink` | `canvas` | 4.5:1 | main text on the page | | `ink` | `surface` | 4.5:1 | main text on cards | | `ink` | `elevated` | 4.5:1 | main text in menus and the player bar | | `ink` | `scrim` | 4.5:1 | titles over artwork | | `inkDim` | `canvas` | 3:1 | secondary text on the page | | `inkDim` | `surface` | 3:1 | secondary text on cards | | `accent` | `canvas` | 3:1 | the playing song and the active tab | | `onAccent` | `accent` | 4.5:1 | labels on accent fills | | `onAccent` | `action` | 4.5:1 | the icon on the play button | You also get a warning (not a refusal) when `inkMute` on `canvas` is under 3:1, and when your accent is close to the LIVE red. A message looks like this, and says which way to move: ``` Contrast too low for main text on the page: ink (#56607a) on canvas (#0a1022) is 3.0:1 and needs at least 4.5:1. Make ink lighter or canvas darker. ``` ### Everything else - Only the fields in "The file" are allowed. An unknown field is refused, and so is an unknown token. `tokens.background` gets you "Did you mean canvas?". - `mode` must match the colours: in a dark skin the canvas is darker than the ink. - `shape`, `texture`, `shadow` and each font must be one of the values listed above. - No links and no markup in `name`, `author` or `description`. ## A worked example Say you want the feel of driving through a city at night: deep blue, warm white, the orange of sodium street lights. **1. Start from the idea, not from seventeen colours.** Pick the canvas, the ink and the accent. ``` "canvas": "#0a1022" deep blue, nearly black "ink": "#fdf6e9" warm white "accent": "#ff9f43" sodium orange ``` Warm white on that blue is 17.6:1 and the orange is 9.3:1. Plenty. **2. Build the grounds.** Cards a step lighter than the canvas, menus a step lighter again, lines lighter again. Keep the blue. ``` "surface": "#121a33" "elevated": "#1a2545" "line": "#28365f" ``` **3. Quieter inks.** Fade the ink towards the blue instead of towards grey, so secondary text feels like part of the scene. ``` "inkDim": "#9fabc9" "inkMute": "#7480a3" ``` **4. Text on the button.** The orange is light, so the label on it is dark. ``` "onAccent": "#1a0d00" ``` **5. Style.** Round corners suit it, a faint grid reads as a city map, and the brand's condensed headings already look like road signs. The finished skin, ready to copy: ```json { "id": "night-drive", "name": "Night Drive", "author": "Aroha", "version": 1, "description": "City lights from the motorway: deep blue, warm white, sodium orange.", "mode": "dark", "tokens": { "canvas": "#0a1022", "surface": "#121a33", "elevated": "#1a2545", "line": "#28365f", "ink": "#fdf6e9", "inkDim": "#9fabc9", "inkMute": "#7480a3", "accent": "#ff9f43", "onAccent": "#1a0d00" }, "shape": "round", "texture": "grid", "shadow": "soft", "fonts": { "display": "big-shoulders", "body": "system", "mono": "space-mono" } } ``` It leaves out `scrim`, `action`, the three status colours and the gradient colours, so those are FM.video's. ## Test it 1. Go to `/skins`. 2. Paste the JSON into **Import a skin** and press **Import and apply**, or choose the `.json` file. 3. If it is refused, each problem is listed with the fix. Change the file and import it again. Importing a skin with the same `id` replaces the old one. 4. Now use the app. At least look at: - Home, with something playing (the mini player and the playing song) - the now-playing view (open the player) - a chart or a playlist (long lists, the playing row) - Search (chips, the selected chip) - a menu (the three dots on any song) and the sign-in sheet - a phone-sized window and a wide one 5. Press **Reset to FM.video** at any time to go back. An imported skin stays in that browser only. It is not uploaded anywhere. ## Share it Send the `.json` file, or paste the JSON into a message. The other person imports it on `/skins`. That is the whole process for now. Built-in skins can be linked: add `?skin=` and an id from the table below to any FM.video address, for example `?skin=pixel` or `?skin=studio`. Links only work for built-in skins, so a link can never switch someone to a skin they have not chosen to import. If you make one you are proud of, send it to us. The best ones can become built-in. ## The built-in skins Fourteen ship with FM.video: nine dark and five light. On `/skins` they are grouped as Dark and Light, and each card is drawn in that skin's own colours, corners and type, so you can see what you are getting before you tap. | Skin | id | Mode | What it shows off | |---|---|---|---| | Transmission | `transmission` | dark | The brand. Applying it is the same as having no skin. | | Pixel | `pixel` | dark | `square` shape, `hard` shadows, `dots`, pixel type, yellow on navy. | | Hi-Fi | `hifi` | dark | Graphite greys (the one dark skin that is not near-black), `scanlines`, dot-matrix headings, mono body, amber accent. | | Midnight | `midnight` | dark | The simple one. Black and white, no texture, no shadows, pink only on the play button (`action`). | | Sunday Paper | `sunday-paper` | dark | `round` shape, `noise`, serif headings, brass on ink blue. | | Sunset | `sunset` | dark | Coloured grounds and coloured quiet text: deep purple, peach and orange, with the brand pink. `round`, `noise`. | | Lagoon | `lagoon` | dark | Deep teal with aqua text and the brand pink. `soft` shape, `grid`. | | Teletext | `teletext` | dark | Black screen, blue cards, cyan and green text, terminal headings. `square`, `scanlines`, no shadows. | | High Contrast | `high-contrast` | dark | For easier reading. White text and bright borders on black, a lighter pink, system type. Every pair in the contrast table is 7:1 or better. | | Daylight | `daylight` | light | The first light skin: the brand in daytime. Warm paper, a deeper pink. | | Studio | `studio` | light | Pure white, black type and black outlines. `square`, `hard` shadows. The brand pink on the button, a deeper pink for text. | | Airmail | `airmail` | light | Pale blue paper, navy ink, serif for headings and body, `scanlines` as ruled lines, no shadows. | | Sorbet | `sorbet` | light | Pastel. A mint page with lavender cards, `round`, `dots`. | | Cassette | `cassette` | light | Cream, brown and burnt orange. `noise`, `hard` shadows in brown ink, typewriter headings. | | Pop Art | `pop-art` | light | A comic panel: cream paper, flat yellow cards, black keylines, primary blue. `dots`, `hard` shadows, square. | | Memphis | `memphis` | light | Eighties Memphis: mint page, white and pastel pink, black lines, purple secondary text. `grid`, `hard` shadows, round. | | Carnival | `carnival` | dark | A fairground at night: deep purple, gold lines, mint small print. `dots`, `hard` shadows, round. | | Hideous | `hideous` | light | Made on purpose: screaming yellow, acid lime, cyan, red lines, a serif body and pixel headings. `dots`, `hard` shadows. Passes the contrast rules all the same. | The FM.video pink stays in every skin added since the first six: it is the accent and the main button. On a light ground it is a shade deeper (and in High Contrast a shade lighter) so that it still reads. Pixel, Hi-Fi and Sunday Paper are older and use their own accent. The logo is pink in all of them. ## Known limits **Light skins have limits.** FM.video was designed dark. There are five light skins now, and some parts of the app have not caught up: - The video, its controls and station logo tiles stay dark in every skin. That is by design, not a bug. - The start-up splash is always FM.video's dark one, so a light skin begins with a dark flash. - Some colours in the sign-in sheet and the VJ chat (error red, link blue, notice amber, a few white icons) were picked for a dark background and are weaker on a light one. - Text over artwork sits on a light veil instead of a dark one. Busy artwork can look washed out under it. - Older pages that have not been rebuilt for the new interface (reels, the build log, updates, legal pages) follow the tokens but have not been checked in light. **Old browsers keep the brand look.** Skins rely on a browser feature from 2023 (`color-mix`). Chrome 111, Safari 16.2 and Firefox 113 or newer are fine. Older ones, including some smart TVs, show FM.video as designed and say so on `/skins`. **Skins do not apply to embeds, the TV app, the remote or the admin.** Those are separate surfaces with their own design. ## How it works (for people working on the app) Everything is in `web/v2/skins/`. | File | What | |---|---| | `types.ts` | The format. | | `tokens.ts` | The one table: token to CSS variable, the font list, limits. | | `colour.ts` | Hex parsing, WCAG contrast, mixing. Pure. | | `validate.ts` | `validateSkin`, `parseSkinJson`, `normalise`, the contrast rules. Pure. | | `resolve.ts` | A skin to `{ vars, attrs }` for ``. Pure. | | `builtin.ts` | The built-in skins, in the public format. | | `apply.ts` | `applySkin`, `clearSkin`: the only DOM writes. | | `boot.ts` | Storage keys and the inline script that prevents a flash on load. | | `store.ts`, `useSkin.ts` | State, persistence, the `useSkin()` hook. | | `SkinBoot.tsx` | Mounted in `V2Root`. Applies the saved skin after hydration. | | `SkinPicker.tsx`, `SkinsPage.tsx` | The switcher and the `/skins` page. A card in the switcher is painted inline from its own skin's tokens, never with colour utilities, so it does not change with the skin that is on. | | `fonts.ts` | The extra bundled faces (`next/font`, not preloaded). | | `skins.css` | What `data-shape`, `data-texture`, `data-shadow` and `data-mode` do. | The idea in one paragraph: every colour in the app is a Tailwind v4 theme variable (`app/globals.css`). `bg-void` compiles to `background-color: var(--color-void)`, `text-white` to `color: var(--color-white)`, `bg-black/60` to a `color-mix()` over `var(--color-black)`, `rounded-xl` to `var(--radius-xl)`, `font-display` to `var(--font-display)`. A skin sets those variables on `` and everything that uses a utility follows. Three things are not variables and are handled in `skins.css`: `rounded-full` and `rounded-[..]` (literals), the size of a shadow (only its colour is a variable, so `--tw-shadow` is replaced), and anything written as a literal colour. Storage (`localStorage`): `fmv.skin` is the chosen id, `fmv.skin.custom` is the imported skins, `fmv.skin.vars` is the chosen skin already resolved, which the inline script in `app/layout.tsx` replays before first paint. Imported skins are validated again every time they are read. ### Keeping new UI skinnable - Use the token utilities: `bg-void`, `bg-surface`, `bg-elevated`, `border-line`, `text-white`, `text-ink-dim`, `text-ink-mute`, `bg-pink` with `text-on-accent`. Never a hex, never `bg-[#...]`, never a Tailwind palette colour such as `text-red-400`. - `bg-black/NN` and `from-black/NN` mean "scrim under text on artwork". `text-white` on top of them is correct and flips together in a light skin. - `shadow-black/NN` means "a shadow" and is fine. - For a colour with alpha in plain CSS or an inline style, use the channel variables with the brand value as the fallback: `rgb(var(--skin-accent-rgb, 255 46 154) / 0.35)`. There are five: `--skin-accent-rgb`, `--skin-ink-rgb`, `--skin-canvas-rgb`, `--skin-scrim-rgb` and `--skin-elevated-rgb`. - Something that must stay brand-coloured in every skin goes inside an element with the class `v2-brand`. - The LIVE dot is `bg-onair`. It is not a token and never will be. - Run `npm run test:skins` in `web/`. It checks the built-ins, the validator, the schema, the examples and the examples in this guide. ### Adding a token, a font or a built-in - A token: add it to `TOKENS` in `tokens.ts` and to `TokenKey` in `types.ts`, give it a fallback in `normalise`, add it to the schema and to the table above. The test fails until all four agree. - A font: add it in `fonts.ts`, then `FontId`, `FONTS`, the schema and the table above. - A built-in skin: add it to `builtin.ts`, to the reserved ids in the schema and to the table of built-in skins above. It must pass with no warnings. The test holds a built-in skin to more than an imported one: - Every token, the shape, the texture, the shadow and all three fonts are written out. - `inkDim` reaches 4.5:1 on canvas, surface and elevated. `inkMute`, `accent` and the three status colours reach 3:1 on cards as well as on the page. - The main button (`action`) is the FM.video pink, and in a new skin the `accent` is too. Deeper on a light ground is fine. Another hue is not. - It has a style of its own: no other built-in has the same mode, shape, texture, shadow, display face and body face, or the same grounds and inks. ## Roadmap What exists now is the foundation: the format, the checks, a switcher, fourteen skins and this guide. What comes next, roughly in order: 1. **A public gallery.** Submit a skin, browse and try other people's, one tap to apply. Needs moderation of names and descriptions, and a "report" link. Skins will be linkable by id once they live on the server. 2. **Skins on your account.** Your chosen skin and your imported skins follow you to every device you sign in on. Today they stay in one browser. 3. **Per-station accents.** A skin could let the accent take the colour of the station that is playing, within the contrast rules. 4. **Icon packs.** A second icon set (pixel icons for Pixel, for example), chosen from a list the same way fonts are. 5. **Sound packs.** Short interface sounds: the tune-in, a button press. Off by default, never over the music. 6. **Layout variants.** A small set of arrangements we design and test, such as a compact mode or a player-first mode. A skin chooses one. It still does not write layout. 7. **A skin editor.** Colour pickers and a live preview on `/skins`, with the contrast rules shown as you go, so nobody has to open a text editor. 8. **More light-skin work.** Until the limits above are gone. 9. **A second colour.** The interface uses one accent everywhere, so a skin cannot yet give small labels, chips or hover states a colour of their own. That needs the app's components to ask for a second colour by name first. Then it becomes one more optional token. ### Why data-only skins first Classic media-player skins were images and scripts, and they were wonderful and fragile: a skin could hide the buttons, break on the next release, or do things its user never agreed to. FM.video runs in a browser, where "arbitrary CSS from a stranger" also means "can read the page and send it somewhere". Starting with data gets most of the fun for none of that risk: - **Safe by construction.** There is nothing in a skin to sanitise, because nothing in it is executable or fetchable. Colours are hex, everything else is a choice from a list. - **Readable by rule.** A machine can check a data skin for contrast. It cannot check arbitrary CSS. - **It survives redesigns.** Skins name roles ("the page", "main text"), not elements. When the layout changes, skins carry on working. - **Anyone can make one.** No build tools, no CSS knowledge. Three colours is a skin. - **It is the right base for everything above.** A gallery, account sync, an editor and per-station accents are all easy when a skin is a 600-byte JSON object, and all hard when it is a stylesheet. Each later step (icons, sounds, layouts) follows the same rule: the skin chooses from things we have built and tested. It never brings its own code.