@fishies/ui 0.8.3

package/handbook/README.md

@@ -0,0 +1,236 @@
+# 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.
+- [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.
+
+### 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.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@fishies/ui",
+  "version": "0.8.3",
+  "description": "The Fishies UI kit: reef-toy components, design tokens and the painted system icon set from the social aquarium game Fishies.",
+  "keywords": [
+    "fishies",
+    "ui-kit",
+    "design-tokens",
+    "react",
+    "components",
+    "icons",
+    "game-ui"
+  ],
+  "homepage": "https://fishies.lol/ui",
+  "repository": {
+    "type": "git",
+    "url": "https://git.crt.fyi/PlayFishies/fishies-ui.git"
+  },
+  "bugs": {
+    "url": "https://fishies.lol/community"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Fishies <hi@crt.fyi>",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tokens": {
+      "types": "./dist/tokens.d.ts",
+      "import": "./dist/tokens.js"
+    },
+    "./icons": {
+      "types": "./dist/icons.d.ts",
+      "import": "./dist/icons.js"
+    },
+    "./tokens.css": "./dist/tokens.generated.css",
+    "./kit.css": "./dist/kit.css",
+    "./loader.css": "./dist/loader.css",
+    "./select.css": "./dist/select.css",
+    "./icons/*": "./icons/*",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "icons",
+    "handbook",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/FishiesImg.tsx

@@ -0,0 +1,58 @@
+'use client'
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type ImgHTMLAttributes, type Ref } from 'react'
+import { reveal } from './fx-image'
+import './loader.css'
+
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect
+
+export default function FishiesImg({ ref, decoding, ...props }: ImgHTMLAttributes<HTMLImageElement> & { ref?: Ref<HTMLImageElement> }) {
+  const own = useRef<HTMLImageElement | null>(null)
+  const mounted = useRef(false)
+  const setRef = useCallback((node: HTMLImageElement | null) => {
+    own.current = node
+    if (typeof ref === 'function') ref(node)
+    else if (ref) ref.current = node
+  }, [ref])
+  useIsomorphicLayoutEffect(() => {
+    const img = own.current
+    if (!img) return
+
+    if (mounted.current) img.setAttribute('data-fx', 'wait')
+    const first = !mounted.current
+    mounted.current = true
+    reveal(img, first && img.complete)
+    const settle = () => reveal(img)
+    img.addEventListener('load', settle)
+    img.addEventListener('error', settle)
+    return () => { img.removeEventListener('load', settle); img.removeEventListener('error', settle) }
+  }, [props.src, props.srcSet])
+  return <img {...props} ref={setRef} decoding={decoding ?? 'async'} data-fx="wait" suppressHydrationWarning/>
+}
+
+export function useFxPoster(video: { current: HTMLVideoElement | null }, poster: string | null | undefined) {
+  const decoded = useDecodedUrl(poster)
+  useIsomorphicLayoutEffect(() => {
+    const element = video.current
+    if (!element || !poster) return
+    const show = () => { if (element.getAttribute('data-fx') === 'wait') element.setAttribute('data-fx', 'fade') }
+    if (decoded || element.readyState >= 2) { show(); return }
+    element.addEventListener('loadeddata', show)
+    return () => element.removeEventListener('loadeddata', show)
+  }, [video, poster, decoded])
+}
+
+export function useDecodedUrl(url: string | null | undefined): string | null {
+  const [ready, setReady] = useState<string | null>(null)
+  useEffect(() => {
+    if (!url) return
+    let live = true
+    const probe = new Image()
+    probe.decoding = 'async'
+    probe.src = url
+    const done = () => { if (live) setReady(url) }
+    ;(typeof probe.decode === 'function' ? probe.decode() : new Promise(resolve => { probe.onload = resolve })).then(done, done)
+    return () => { live = false }
+  }, [url])
+  return url && ready === url ? url : null
+}