fishies-ui/handbook/README.md

# The Fishies Handbook

How Fishies looks, reads, sounds and what its world holds, generated from the game's own sources. The living version, with every component drawn, is at https://fishies.lol/ui.

## Brand

### Brand

The five colours every store page, capsule, banner, the site and the Reef Journal sit on.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-ground` | `#071a24` | The night-water ground behind the site, the Reef Journal and every brand picture. |
| `--fx-ground-ink` | `#edf5ed` | Words on the ground: headings and links on the site. |
| `--fx-gold` | `#ffc46b` | The one warm accent: the thing to press, the coin, the playhead, a focus ring. |
| `--fx-sea` | `#83cfbd` | Sea-green for links and quiet highlights on the ground. |
| `--fx-muted` | `#adc3c7` | Body copy on the ground, a step quieter than the headings. |

### Gold

The toy gold of the HUD: a face, a rim and a darker foot that makes a button sit up.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-gold-light` | `#ffe2a6` | Gold words on glass: window titles, the clock, numbers that matter. |
| `--fx-gold-face` | `#ffe4a8` | The lit top of a gold button. |
| `--fx-gold-deep` | `#e59a3e` | The far end of a gold fill: a progress bar, the played part of a video. |
| `--fx-gold-foot` | `#c88a3d` | The solid edge under a gold button, its toy thickness. |
| `--fx-gold-warm` | `#ff9a6b` | Gold leaning to coral, where a fill runs warm (sunrise, a streak). |
| `--fx-amber` | `#f4c656` | The landing’s amber: the wordmark’s gleam and the reel’s titles. |

### Type

Baloo 2 for the game’s voice (numbers, labels, buttons, titles), Nunito for sentences; nothing under 12px.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-font-display` | `var(--font-display), "Baloo 2", ui-rounded, sans-serif` | Titles, numbers, buttons, labels. |
| `--fx-font-ui` | `var(--font-ui), Nunito, ui-rounded, sans-serif` | Sentences and anything read as text. |
| `--fx-t-xs` | `12px` | The floor: units, captions, a badge’s count. |
| `--fx-t-sm` | `13px` | Chips, list details, helper lines. |
| `--fx-t-md` | `15px` | Buttons, list titles, body copy in the game. |
| `--fx-t-lg` | `19px` | A panel’s title. |
| `--fx-t-xl` | `24px` | A stat’s value, a window’s hero number. |
| `--fx-t-2xl` | `31px` | A page heading. |
| `--fx-t-3xl` | `40px` | A moment’s headline (level up, a new fish). |
| `--fx-track-tight` | `-.015em` | Display type at size. |
| `--fx-track-label` | `.14em` | Upper-case eyebrows above a group. |

## UI

### Water

The deep blues under the glass; each one is the water a few metres further down.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-abyss` | `#04101b` | The deepest water: behind full-screen moments and the video frame. |
| `--fx-deep` | `#08202f` | A sunken well inside a panel: inputs, tracks, empty slots. |
| `--fx-deep-2` | `#0d2c3f` | A raised well: a hovered row, a chosen tab’s ground. |
| `--fx-deep-3` | `#14435c` | The lightest deep: dividers that need to show on glass. |
| `--fx-navy` | `#173d63` | The body of a round toy button (window controls, the player’s buttons). |

### Ink

Words on glass, in three weights; the quietest still reads at 6.7:1 on a panel.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-ink` | `#eef6ff` | Everything a player reads on glass: titles, values, labels. |
| `--fx-ink-2` | `rgb(238 246 255 / 80%)` | Sentences under a title. |
| `--fx-ink-3` | `rgb(238 246 255 / 62%)` | Captions, units and hints; never anything a player must act on. |
| `--fx-ink-blue` | `#a9c9ea` | Labels that name a value beside it (Level, Coins, Fish). |
| `--fx-ink-on-gold` | `#12304a` | Words on a gold button or a gold chip. |

### Tones

Six hues that tell kinds apart (an app tile, a chip, a chart line) and two that mean good and bad.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-tone-sky` | `#6cc8ff` | Sky blue: water, visits, anything about other keepers. |
| `--fx-tone-coral` | `#ff8f87` | Coral: reports, a count that wants you, the close button. |
| `--fx-tone-kelp` | `#7fdc8f` | Kelp green: live, online, growing. |
| `--fx-tone-violet` | `#b8a2ff` | Violet: rare things and night. |
| `--fx-tone-lagoon` | `#5cd8c6` | Lagoon: the landing’s shallow water. |
| `--fx-tone-mute` | `#8fa7b5` | Grey-blue: off, empty, not yet. |
| `--fx-good` | `#6fe3b0` | Done, fed, clean, saved. |
| `--fx-alarm` | `#ff8478` | Hungry, dirty, failed: what needs a hand now. |
| `--fx-pearl` | `#fff4d6` | Pearl: the warm white of a badge rim and the landing’s cream. |
| `--fx-cream` | `#f3dfb2` | Cream: the shaded side of a pearl knob, warm sand. |
| `--fx-plum` | `#36203f` | Plum: the landing’s deep warm shadow under cream. |

### Glass

The one material everything floats on: tinted water glass with a sheen across its top.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-glass-top` | `rgb(22 58 120 / 70%)` | The upper tint of glass. |
| `--fx-glass-bottom` | `rgb(8 26 66 / 88%)` | The lower tint of glass, darker so words sit on it. |
| `--fx-glass-quiet-top` | `rgb(22 58 120 / 62%)` | Glass over the live tank, a little thinner so the fish show through. |
| `--fx-glass-quiet-bottom` | `rgb(8 26 66 / 82%)` | The lower tint of quiet glass. |
| `--fx-glass-sheen` | `rgb(255 255 255 / 16%)` | The light across the top half of a pane. |
| `--fx-glass` | `linear-gradient(180deg, var(--fx-glass-sheen), transparent 46%), linear-gradient(180deg, var(--fx-glass-top), var(--fx-glass-bottom))` | A pane: windows, panels, menus, the dock. |
| `--fx-glass-quiet` | `linear-gradient(180deg, var(--fx-glass-sheen), transparent 46%), linear-gradient(180deg, var(--fx-glass-quiet-top), var(--fx-glass-quiet-bottom))` | A pane over the tank: HUD capsules, the fish card. |
| `--fx-glass-well` | `rgb(4 16 30 / 55%)` | The darker water inside a window, under its title bar. |
| `--fx-glass-blur` | `blur(14px) saturate(1.2)` | What glass does to the reef behind it (backdrop-filter). |

### Rims

A hairline of light round every pane; gold marks the panes that are yours to use.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-rim` | `rgb(140 200 255 / 34%)` | The blue hairline round glass. |
| `--fx-rim-bright` | `rgb(140 200 255 / 55%)` | The hairline on hover. |
| `--fx-gold-rim` | `rgb(255 196 107 / 58%)` | The gold hairline round windows, the dock, tiles and the chosen tab. |
| `--fx-gold-rim-quiet` | `rgb(255 196 107 / 26%)` | Gold dividers: under a title bar, between dock groups. |
| `--fx-rim-light` | `inset 0 1px rgb(255 240 210 / 30%)` | The lit inner top edge of a gold-rimmed pane. |
| `--fx-ground-rim` | `#9ebfbe26` | Hairlines on the ground: card edges and rules between sections of the site. |

### Depth

Soft lifts for panes over water, and the solid foot that makes a toy control look pressable.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-lift-1` | `0 2px 10px rgb(2 10 18 / 34%)` | A chip or a small button just off the water. |
| `--fx-lift-2` | `0 10px 30px rgb(2 8 20 / 45%)` | A panel, the dock, a menu. |
| `--fx-lift-3` | `0 24px 60px rgb(2 8 20 / 60%)` | A window or a moment that takes the screen. |
| `--fx-foot` | `0 4px 0 rgb(4 18 34 / 55%)` | The toy foot under a glass button or tile; pressing sinks into it. |
| `--fx-foot-deep` | `0 6px 0 rgb(4 18 34 / 55%)` | The foot under a desktop tile, which stands taller. |
| `--fx-plump` | `inset 0 2px rgb(255 255 255 / 40%), inset 0 -6px 12px rgb(0 0 0 / 28%)` | The lit top and shaded belly that make a tile round. |
| `--fx-on-water` | `0 1px 2px #020c1a, 0 4px 16px rgb(2 12 26 / 80%)` | The shadow under words that sit straight on the water. |

### Radii

Round, never sharp: the smaller the thing, the rounder it reads.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-r-sm` | `10px` | Rows, inputs, keys. |
| `--fx-r-md` | `14px` | Cards, menus, tooltips. |
| `--fx-r-lg` | `20px` | Panels and windows. |
| `--fx-r-xl` | `28px` | Desktop tiles and the dock. |
| `--fx-r-full` | `999px` | Buttons, chips, tabs, badges, tracks. |

### Spacing

A 4px grid: every gap, padding and margin is one of these.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-s-1` | `4px` | Inside a chip, between a value and its unit. |
| `--fx-s-2` | `8px` | Between an icon and its label, between chips. |
| `--fx-s-3` | `12px` | Inside a button, between rows. |
| `--fx-s-4` | `16px` | A card’s inset. |
| `--fx-s-5` | `24px` | A panel’s inset, between groups. |
| `--fx-s-6` | `32px` | Between sections of a page. |
| `--fx-s-7` | `48px` | Around a page’s hero. |

### Layers

Named heights, so a toast never slides under a window and a tooltip never under a toast.

| Token | Value | Use |
| --- | --- | --- |
| `--fx-z-raised` | `10` | A card lifted above its siblings (a dragged tile). |
| `--fx-z-sticky` | `100` | Headers and rails that stay as the page scrolls. |
| `--fx-z-dock` | `900` | The menu bar and the dock. |
| `--fx-z-modal` | `1000` | A window or sheet that holds the screen, with its backdrop. |
| `--fx-z-toast` | `1100` | Toasts, above any window. |
| `--fx-z-tooltip` | `1200` | Tooltips and open menus, above everything. |

### Motion

Named slots the motion system fills (apps/web/app/motion/motion.css, where each one is described): arrivals overshoot a little and settle, presses squash, exits get out of the way.

| Token | Value | Use |
| --- | --- | --- |
| `--m-quick` | `120ms` | A press, a hover, a check. |
| `--m-base` | `180ms` | A fade, a chip changing. |
| `--m-move` | `260ms` | Something travelling: a panel arriving, a row sliding. |
| `--m-show` | `400ms` | A moment: a window unfolding, a reward landing. |
| `--m-ease-out` | `cubic-bezier(.2, .8, .2, 1)` | Answers the hand: decelerates hard. |
| `--m-ease-spring` | `cubic-bezier(.34, 1.5, .64, 1)` | The reef-toy arrival: overshoots a little and settles. |
| `--m-ease-calm` | `cubic-bezier(.45, 0, .25, 1)` | Calm, symmetric: crossfades, drift. |
| `--m-ease-in` | `cubic-bezier(.4, 0, 1, 1)` | Leaving: accelerates away. |
| `--m-stagger` | `40ms` | Stagger step for lists. |

### Components

- **SystemIcon** · A painted icon from the system set, by name, at one of the set's sizes.
- **Button** · A plump toy button: glass for everyday actions, gold for the one thing to press, ghost for a quiet third choice, danger for what cannot be undone.
- **ButtonLink** · The same button as a link, for an action that goes somewhere.
- **RoundButton** · A round toy button for window controls, the video player and close; `label` is what it says to a screen reader.
- **Chip** · A small reading or choice: a dot of colour for a kind, an icon, or gold when chosen.
- **Badge** · A coral count bubble that sits on a tile, a dock item or a bell; a dot when the number does not matter.
- **Tag** · A gold-rimmed capsule for a small upper-case word beside a name (Beta, New, Admin).
- **Card** · A glass card: an optional eyebrow, a title and a few lines.
- **Panel** · A gold-rimmed glass panel with a title row (icon, title, actions) and a body.
- **Window** · A Keeper OS window frame: a title bar with round minimise and close buttons over a darker well.
- **Tabs** · A row of pill tabs in a sunken track; the chosen one is gold.
- **List** · A list of rows; each row has an icon, a title, a detail line and a value at its end.
- **ListRow** · One row of a list; a button when it does something, a link when it goes somewhere.
- **Field** · A labelled text field in a sunken pill, with an optional hint under it.
- **Toggle** · An on and off switch with a pearl knob; gold when on.
- **Tooltip** · A designed tooltip, never plain text: an icon and title, a line, and labelled values; it opens on hover and on keyboard focus.
- **Toast** · A notice that slides in at the edge: an icon in a coloured bubble, a title, a line and a close.
- **Stat** · A number a keeper reads at a glance: an icon, the value in gold with its unit, and what it counts.
- **DockTile** · A desktop tile: a plump glass square in its own hue holding an icon, a title under it, a badge and an open mark.
- **Dock** · A dock: a gold-rimmed glass shelf of icons; the app in front wears a gold bar, open ones a dot.
- **DockItem** · One icon on a dock.
- **Spinner** · The Fishies spinner for anything on its way: a glass porthole with a gold arc going round and bubbles rising.
- **Progress** · A progress bar: a glass channel filling with gold, a bubble riding its leading edge; with no value the gold sweeps.
- **Select** · A dropdown that opens a dark panel with a gold check, driven from the keyboard like a native one and never clipped by its panel.
- **Image** · The one way Fishies puts a picture on screen: a drop-in `<img>` that shows the Fishies spinner on a glass placeholder in its own box until the file is fully downloaded and decoded, then fades it in.

## World

### Reef Journal

- [Open Water](https://fishies.lol/wiki/mechanics/open-water) · Swim out as one of your fish and meet other keepers.
- [Expeditions](https://fishies.lol/wiki/mechanics/expeditions) · Send a team of your grown fish to the Trench or the Vents and wait for what they bring home.
- [Swimming in a friend's aquarium](https://fishies.lol/wiki/mechanics/swim-visits) · Join another keeper's aquarium as one of your own fish.

### Places

- [Kelp Garden](https://fishies.lol/open-water/kelp-garden) · A coral garden that runs into a kelp forest. Room to roam.
- [Shipwreck](https://fishies.lol/open-water/shipwreck) · An old ship asleep on the sand, lanterns still lit. Swim through its ribs.
- [Market](https://fishies.lol/open-water/market) · A wanted board in the sunny shallows. Bring the fish the Market is asking for this week.
- [Lagoon](https://fishies.lol/open-water/lagoon) · Warm, bright shallows of seagrass and white sand. Play Pearl Catch at the oyster bed.
- [Arena](https://fishies.lol/open-water/arena) · An open stadium of coral stands round a start gate. Race the week's course for a place on the board.
- [Ice Shelf](https://fishies.lol/open-water/ice-shelf) · Pale water under an ice roof, frost ferns and ice spires. The seasonal parties are thrown here.
- [Ruins](https://fishies.lol/open-water/ruins) · A sunken temple among fallen columns, its door sealed. Six lost tablets are hidden across Open Water.
- [Trench](https://fishies.lol/open-water/trench) · The dark deep at the reef's edge. Send a fish on an expedition into it from the diving bell.
- [Vents](https://fishies.lol/open-water/vents) · Warm volcanic chimneys glowing in the dark. Send a fish on an expedition from the outpost.
- [Pineapple House](https://fishies.lol/open-water/pineapple-house) · A house made from a pineapple, deep in the kelp. It is the reading room: tap it to open the Reef Journal.
- [Gallery](https://fishies.lol/open-water/gallery) · Keepers' aquariums, framed on the wall. Swim close to look inside.
- [The Temple](https://fishies.lol/open-water/ruins-temple) · Inside the sunken temple, where the first light is kept.
- [Cove](https://fishies.lol/open-water/cove) · Your school's own bay, with its banner and notice board.

### Catalogues

- [Species catalogue](https://fishies.lol/wiki/species) (102) · Every fish in the game with its growth time, unlock level, egg price and sale value.
- [Decorations catalogue](https://fishies.lol/wiki/decorations) (74) · Every plant and ornament, what it costs and how long it keeps algae away.
- [Equipment catalogue](https://fishies.lol/wiki/equipment) (9) · Every filter, auto-feeder and heater with its price, unlock level and what it does.