FM.video
Skins

Skins

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:

{
  "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 skinnableWhy
The FM.video logo and wordmarkIt is how people know where they are. It keeps its own colours and typeface.
The red LIVE markerRed means "this is a live broadcast" and nothing else. If skins could move it, it would stop meaning that.
The layoutWhere 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 itControls 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 artworkThey belong to the stations and the artists. They are never recoloured.
The product nameIt 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

FieldRequiredWhat it is
idyesA 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.
nameyesWhat people see on the skin's card. Plain text, 40 characters at most.
authoryesYou. Plain text, 40 characters at most.
versionyesAlways the number 1. It is the version of this file format, not of your skin.
descriptionnoOne line about the skin. Plain text, 200 characters at most.
modeyes"dark" when the canvas is darker than the text, "light" when it is lighter. Light skins work, with a few limits (see "Known limits").
tokensyesThe colours. See below. May be empty.
shapenoCorners. Default brand.
texturenoA faint pattern on the page. Default none.
shadownoDefault soft.
fontsnoA 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.

TokenWhat it coloursFM.video's own value
canvasThe page background, behind everything.#08070c
surfaceCards, rows, tiles and sheets.#14101c
elevatedMenus, the player bar and anything that floats over the page.#1c1626
lineHairlines and borders.#241830
inkMain text and icons. Also the fill of the selected filter chip.#ffffff
inkDimSecondary text: artist names, descriptions, idle icons.#9e93a8
inkMuteCaptions, counts and small labels.#7a6e86
accentHighlights: the playing song, the active tab, links, the focus ring, the equaliser bars.#ff2e9a
actionThe fill of the main button (play) and of progress bars. Follows accent unless you set it.same as accent
onAccentText and icons sitting on an accent or action fill.#08070c
scrimThe veil over artwork that makes text on it readable, and the dim behind dialogs.#000000
successGood news: saved, added, climbing.#35d07f
warnWarnings and things that need a look.#ffb020
infoNeutral notices.#4da8ff
spectrumWarmFirst colour of decorative gradients.#ff6a1a
spectrumMidMiddle colour of decorative gradients.#ce34c6
spectrumCoolLast 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

shapeWhat you get
brandFM.video's corners: 12px tiles, 16px sheets, pill buttons.
squareNo curves anywhere. Pills, circles, avatars and the play button are square too. Made for pixel art.
softSmall, even corners (2 to 12px). Pills and circles stay round.
roundBig corners (up to 44px). Pills and circles stay round.
textureWhat you get
noneA flat canvas.
scanlinesFine horizontal lines, like an old tube screen.
gridA 24px graph-paper grid.
dotsA 12px dot matrix.
noiseFilm grain.

Textures are faint, they are drawn in your ink colour on the page canvas only, behind all content, and never over the video.

shadowWhat you get
softBlurred shadows under menus, sheets and the floating video.
hardSolid offset shadows with no blur, and one under the main button. Black in a dark skin, your ink in a light one.
noneFlat. 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.

FontTypefaceGood for
big-shouldersBig ShouldersThe brand display face. Tall, condensed, loud.
space-groteskSpace GroteskThe brand body face.
space-monoSpace MonoThe brand mono face, for numbers and small labels.
pixelJersey 15A chunky, condensed pixel face. Best for headings.
pixel-sansPixelify SansA pixel face that stays readable at body sizes.
terminalVT323A green-screen terminal face. Runs small: best for headings and labels.
matrixDotoA dot-matrix display face, like a hi-fi readout. Headings only.
systemSystem sansWhatever the device uses for its own interface.
serifSystem serifThe device's serif. Editorial and calm.
monoSystem monoThe 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.

Thison thisat leastbecause
inkcanvas4.5:1main text on the page
inksurface4.5:1main text on cards
inkelevated4.5:1main text in menus and the player bar
inkscrim4.5:1titles over artwork
inkDimcanvas3:1secondary text on the page
inkDimsurface3:1secondary text on cards
accentcanvas3:1the playing song and the active tab
onAccentaccent4.5:1labels on accent fills
onAccentaction4.5:1the 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:

{
  "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:
  5. Home, with something playing (the mini player and the playing song)
  6. the now-playing view (open the player)
  7. a chart or a playlist (long lists, the playing row)
  8. Search (chips, the selected chip)
  9. a menu (the three dots on any song) and the sign-in sheet
  10. a phone-sized window and a wide one
  11. 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.

SkinidModeWhat it shows off
TransmissiontransmissiondarkThe brand. Applying it is the same as having no skin.
Pixelpixeldarksquare shape, hard shadows, dots, pixel type, yellow on navy.
Hi-FihifidarkGraphite greys (the one dark skin that is not near-black), scanlines, dot-matrix headings, mono body, amber accent.
MidnightmidnightdarkThe simple one. Black and white, no texture, no shadows, pink only on the play button (action).
Sunday Papersunday-paperdarkround shape, noise, serif headings, brass on ink blue.
SunsetsunsetdarkColoured grounds and coloured quiet text: deep purple, peach and orange, with the brand pink. round, noise.
LagoonlagoondarkDeep teal with aqua text and the brand pink. soft shape, grid.
TeletextteletextdarkBlack screen, blue cards, cyan and green text, terminal headings. square, scanlines, no shadows.
High Contrasthigh-contrastdarkFor 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.
DaylightdaylightlightThe first light skin: the brand in daytime. Warm paper, a deeper pink.
StudiostudiolightPure white, black type and black outlines. square, hard shadows. The brand pink on the button, a deeper pink for text.
AirmailairmaillightPale blue paper, navy ink, serif for headings and body, scanlines as ruled lines, no shadows.
SorbetsorbetlightPastel. A mint page with lavender cards, round, dots.
CassettecassettelightCream, brown and burnt orange. noise, hard shadows in brown ink, typewriter headings.
Pop Artpop-artlightA comic panel: cream paper, flat yellow cards, black keylines, primary blue. dots, hard shadows, square.
MemphismemphislightEighties Memphis: mint page, white and pastel pink, black lines, purple secondary text. grid, hard shadows, round.
CarnivalcarnivaldarkA fairground at night: deep purple, gold lines, mint small print. dots, hard shadows, round.
HideoushideouslightMade 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/.

FileWhat
types.tsThe format.
tokens.tsThe one table: token to CSS variable, the font list, limits.
colour.tsHex parsing, WCAG contrast, mixing. Pure.
validate.tsvalidateSkin, parseSkinJson, normalise, the contrast rules. Pure.
resolve.tsA skin to { vars, attrs } for <html>. Pure.
builtin.tsThe built-in skins, in the public format.
apply.tsapplySkin, clearSkin: the only DOM writes.
boot.tsStorage keys and the inline script that prevents a flash on load.
store.ts, useSkin.tsState, persistence, the useSkin() hook.
SkinBoot.tsxMounted in V2Root. Applies the saved skin after hydration.
SkinPicker.tsx, SkinsPage.tsxThe 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.tsThe extra bundled faces (next/font, not preloaded).
skins.cssWhat 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 <html> 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.

This guide as plain text, for a text editor or an AI assistant: /skins/guide.md