# dot+ Base v1.1 — Handoff Package

For **Claude Code** (or any developer/designer agent) building the Figma file and SwiftUI implementation.

---

## What's in this folder

| File | Purpose | Authority |
|---|---|---|
| `HANDOFF.md` | **This file.** Read first. | — |
| `spec.md` | Full written design system spec, v1.1 | Source of truth for prose & rationale |
| `tokens.json` | Machine-readable tokens (W3C Design Tokens / Tokens Studio format) | **Source of truth for values** |
| `style-guide.html` | Living visual style guide with Light/Dark toggle | Source of truth for visuals |
| `original-v1.0.html` | Original v1.0 style guide (reference only) | Historical — do not use values from this |

> **If `tokens.json` and `spec.md` ever disagree on a value, `tokens.json` wins.** The spec is the story; the tokens are the law.

---

## What changed from v1.0 → v1.1

1. **Two-layer token architecture** — primitive (`mono.*`, `accent.*`) + semantic (`surface.*`, `content.*`, `border.*`, `state.*`). Components reference only semantic.
2. **Light theme added** as a first-class mode. Both ship from day one.
3. **Inter** replaces Manrope; **JetBrains Mono** replaces DM Mono.
4. **Accents recalibrated** to Base-aligned hexes (`#05944F`, `#BB7A00`, `#E11900`, `#276EF1`).
5. **Buttons rebuilt** — 4 sizes (mini 28 / small 36 / default 48 / large 56), 4 shapes (default / pill / square / circle), tinted secondary (no border).
6. **9pt "Micro" tier removed**. Floor is 11pt caption.
7. **Base vs dot+ boundary marked.** Every component in `tokens.json` has a `$class` of either `"Base"` or `"dot+ extension"`.

---

## How to build the Figma file (for Claude Code with Figma MCP)

Build in this exact order to avoid rework:

### Step 1 — Fonts
Install **Inter** and **JetBrains Mono** (both free, Google Fonts). Add to the Figma file via *Assets → Fonts*.

### Step 2 — Variables: Primitive collection
1. Create a Variables collection named **`Primitive`** with **1 mode** (no theming).
2. Color group `mono`: 12 variables (`mono/0` → `mono/1000`) using the hex values from `tokens.json` → `primitive.mono`.
3. Color group `accent`: 4 variables (`positive`, `warning`, `negative`, `info`) from `tokens.json` → `primitive.accent`.

### Step 3 — Variables: Semantic collection
1. Create a Variables collection named **`Semantic`** with **2 modes**: `Dark`, `Light`.
2. For each semantic token in `tokens.json` → `semantic.dark` and `semantic.light`:
   - Create a variable (e.g., `surface/primary`)
   - Set its value to **reference** the corresponding primitive in the Primitive collection (different reference per mode)
3. Critical: variables hold **references**, not raw hexes. This is what enables one-click theme switching.

### Step 4 — Variables: Number & String collections
- `Number`: 8 spacing variables (`space/1` … `space/8`), 4 radius variables (`radius/xs` … `radius/lg`).
- `String` (optional): font family + weight aliases.

### Step 5 — Text styles
Create 7 Text Styles from `tokens.json` → `typography`. Bind each to the appropriate font, weight, size, and line height.

### Step 6 — Effect styles
Create `shadow/1`, `shadow/2`, `shadow/3` for Light mode (Dark mode has no shadow — use surface lift).

### Step 7 — Components — build in this order
For each component in `tokens.json` → `components`, build the Figma component **using only Semantic variables, never raw hexes or Primitive variables**.

1. **Button** — One master component with properties: `variant` (4) × `size` (4) × `shape` (4) × `state` (default/pressed/disabled). Use Figma component properties — don't make 192 separate frames.
2. **Tag** — 5 variants (default + positive/warning/negative/info).
3. **Input** — 3 states (default / focused / error).
4. **Toggle** — 2 states (on / off).
5. **Card** — base shell + slot.
6. **NavBar** — back / title / trailing slots.
7. **TabBar** (dot+ extension) — 4-tab default; tag the component description with `"dot+ extension"`.

### Step 8 — File pages
- Page 0 — Cover
- Page 1 — Tokens / Primitive
- Page 2 — Tokens / Semantic (Dark + Light side-by-side)
- Page 3 — Components / Core
- Page 4 — Components / dot+ Extensions
- Page 5 — Icons
- Pages 6–14 — Screens
- Page 15 — User flows
- Page 16 — iPad variants

### Step 9 — iPhone frame template
393×852 (iPhone 14/15 Pro). Status bar inset 47pt, home indicator 34pt. Save as a Figma component.

---

## How to build the SwiftUI implementation

### Path A — Manual
Translate `tokens.json` by hand into `DesignTokens.swift`:

```swift
extension Color {
    // Primitive — never use directly in views
    static let mono900 = Color(hex: 0x0F0F14)
    // ...
    static let accPositive = Color(hex: 0x05944F)
    // ...
}

extension Color {
    // Semantic — use these in views
    static var surfacePrimary: Color { Color("surfacePrimary") }   // backed by Assets.xcassets
    static var surfaceSecondary: Color { Color("surfaceSecondary") }
    // ...
}
```

In `Assets.xcassets`, create a Color Set for each semantic token with Any/Dark Appearance values from `tokens.json`.

### Path B — Generated (recommended)
Use **Style Dictionary** or the **Tokens Studio CLI** to generate `DesignTokens.swift` directly from `tokens.json`. This keeps Figma and SwiftUI in lockstep.

```bash
npm install -g token-transformer style-dictionary
token-transformer tokens.json tokens.transformed.json
style-dictionary build --config sd.config.js
```

---

## Component contracts — quick reference

These are the rules every component must follow. Full details in `tokens.json` → `components` and `spec.md` § 5.

| Component | Class | Key contract |
|---|---|---|
| `DotButton` | Base | 4 sizes × 4 shapes × 4 variants. Min hit target 44×44 always. |
| `DotTag` | Base | 24pt height. 5 variants. No border. |
| `DotCard` | Base | Fill-only on Dark, 1pt subtle border on Light. |
| `DotInput` | Base | 48pt height. Tinted fill. Focus = info border, error = negative border. |
| `DotToggle` | Base | 42×24 track, 20×20 knob. Knob inverts to maintain contrast. |
| `DotNavBar` | Base | 52pt height. Solid surface, no blur. |
| `DotTabBar` | dot+ ext | 80pt. Solid surface, no blur. iOS pattern, not Base. |

---

## Non-negotiables

- **Never reference primitive tokens directly in components.** Always go through semantic.
- **Never invent new colors.** If you need a color that isn't in `tokens.json`, the system needs to evolve — add a token, don't bypass.
- **Never use radius > 16pt.**
- **Never use spring animations.**
- **Never use shadows in Dark mode.** Use surface tonal lift instead.
- **Every interactive element ≥ 44×44pt hit target.**
- **Every text contrast ≥ 4.5:1** (3:1 for ≥18pt or ≥14pt bold).

---

## What to ask the user for, if anything's unclear

- The **Cap Cana Figma project** — exports of key screens for visual benchmarking (not yet provided).
- **Custom icon set** — if SF Symbols doesn't cover a concept, get original SVGs before drawing.
- **Real product copy** — placeholder strings in the style guide are dummy data.

---

## Version

- **v1.1** — May 2026
- Owner: Rodrigo Arvizu (rarvizu@xhinola.io) · Xhinola
- Confidential