# ReefRide Figma kit

This bundle gives a designer everything needed to build a Figma library that
matches what ships in the live ReefRide product UI: colors, type scale,
spacing, radii, shadows, and the full icon set.

It is **not** a pre-built `.fig` file. Figma's binary file format is not a
durable distribution channel (it changes between major versions and can't be
versioned in git), so the kit instead ships the upstream sources and a setup
recipe. Following the recipe takes about 15 minutes and produces a Figma
library that stays in sync with the codebase.

---

## What's in the bundle

| File | Purpose |
| --- | --- |
| `tokens.json` | Design tokens in W3C DTCG format. Imports straight into Tokens Studio for Figma. Also consumable by Style Dictionary, Tailwind, and any token pipeline. |
| `figma-kit-readme.md` | This document. |
| `../icons/reefride-icon-set.zip` | 50 brand-curated icons as flat SVGs. Drop straight into Figma. |
| `../colors.json` | Legacy color manifest (still ships for back-compat with older brand kits). Tokens.json supersedes it. |
| `../voice.md` | Tone, vocabulary, house rules — applies to copy in Figma mockups too. |

---

## Recipe — set up the Figma library

### 1. Create the file
Open Figma. Create a new file called **ReefRide Library**. Publish it to
your team library when steps 2–4 are done.

### 2. Import the design tokens
1. Install the **Tokens Studio for Figma** plugin (free; the standard for
   token import).
2. Run plugin → **Settings → Add new** → **JSON file** → upload
   `tokens.json`.
3. Tokens Studio will parse the DTCG payload and create:
   - **Color styles** under `color/brand/*`, `color/text/*`,
     `color/surface/*`, `color/status/*`
   - **Typography styles** under `typography/scale/*`
   - **Effect styles** for the two shadows
   - **Variables** for spacing, border-radius, and icon sizes
4. Click **Push to Figma** → **Create styles** so the tokens become real
   Figma styles you can apply with one click.

### 3. Drop in the icon set
1. Unzip `reefride-icon-set.zip` to a folder on disk.
2. In your Figma library file, create a page called **Icons**.
3. **File → Place image** → select all 50 SVGs at once. Figma imports each
   as an independent SVG node.
4. Select all icons → **Right-click → Create component / Create components**
   (with an `s` — Figma will auto-name each component after the SVG file).
5. Group components into frames by category, matching `icons.json`:
   - Vehicles & travel
   - Status & verification
   - Time & schedule
   - Actions
   - People
   - Money
   - Communication
   - Brand & extras
6. (Optional but recommended) Bind the icon's stroke to the
   `color/text/primary` token so flipping themes flips the icons too.

### 4. Build the core component set
With tokens + icons in place, build these components in the same library
file. Source-of-truth for every prop is the production code under
`src/components/ui/` — match those before improvising.

| Component | Variants / sizes | Notes |
| --- | --- | --- |
| **Button** | `primary` / `secondary` / `tertiary`, sizes `sm` / `md` / `lg` | Reef-blue primary; soft-gray secondary; ghost tertiary. Use `borderRadius.md` (8px). |
| **Pill / TabBar** | `inactive` / `active` | Capsule shape (`borderRadius.pill`); active = ride-black background, white text. Matches `AdminSubNav`. |
| **Card** | `flat` / `bordered` / `elevated` | All three use `borderRadius.lg` (12px). Elevated uses `shadow.card`. |
| **KPI tile** | single variant | White surface, 12px radius, `shadow.card`. Uppercase tracked label + bold value. Matches `Pro/PropertyHost` earnings tiles. |
| **Status pill** | `ok` / `warn` / `crit` / `muted` | 10% alpha surface tint of the `color/status/*` token; the dot uses the full token color. |
| **Input** | `default` / `focus` / `error` | 1px border, 8px radius, 14px body type. |
| **Notification banner** | `info` / `warning` / `negative` | Reuses Base UI's Notification. |

### 5. Publish
- Each new component → **Right-click → Publish** so other Figma files in
  the team can pull instances.
- Tag the publish version in the Figma description: `v1.0 — synced from
  reefride@<short SHA>`.

---

## Updating the kit

The icon set and tokens are generated from code:

```bash
# regenerate icons (lucide-react path data → flat SVGs + zip + manifest)
npx tsx scripts/build-brand-icon-set.ts

# tokens.json is curated by hand — edit
#   public/brand-assets/figma/tokens.json
# and re-run Tokens Studio → Refresh.
```

After regenerating, re-upload `tokens.json` in Tokens Studio and re-import
new SVGs. Existing component instances pick up token changes automatically;
icon updates require re-creating the affected icon component (Figma can't
hot-replace SVG geometry).

---

## A Figma Community URL?

A public Figma Community link will be added below once the library is
published. Until then, this README + the bundled assets are the primary
delivery channel.

> **Figma Community URL:** _coming soon_

If you need direct file access in the meantime, email
[press@reefride.co](mailto:press@reefride.co) with a Figma org ID and we'll
share the source file with view + duplicate access.