# The Free Companies — Design System

This file is the authoritative design-system reference for all mockups under `design/mockups/`. The `/discuss-design` skill reads it at the start of every session and updates it after design-system discovery runs.

---

## Typography

### Google Fonts CDN (use in mockup HTML)

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=IM+Fell+English:ital@0;1&family=IM+Fell+English+SC&family=Cormorant+Garamond:wght@400;500;600&display=swap" rel="stylesheet">
```

### Font roles

| Role | Family | Weight | When to use |
|---|---|---|---|
| Panel headings | IM Fell English | 400 | Modal titles, popup headers |
| Decorative headings | IM Fell English SC | 400 (small-caps) | Section labels, column headers |
| Body text | Cormorant Garamond | 400 | Paragraph text, descriptions |
| Sub-headings | Cormorant Garamond | 500–600 | Card labels, field names |
| Inline fallback | Georgia, serif | — | When custom fonts fail |

---

## Color Palette

| Token | Hex / RGBA | Usage |
|---|---|---|
| `bg-primary` | `#0a0a0a` | Page and panel backgrounds |
| `bg-panel` | `rgba(12,10,8,0.98)` | Popup / modal panel surface |
| `accent-gold` | `#c8a84b` | Headings, active state borders, CTA text |
| `accent-gold-muted` | `#9d7e35` | Subtitles, secondary labels |
| `accent-gold-border` | `rgba(184,134,11,0.4)` | Default panel borders |
| `accent-gold-border-active` | `rgba(184,134,11,0.5)` | Focused / hovered panel borders |
| `success` | `#5a9a5a` | Ready state, collect buttons, met requirements |
| `success-bright` | `#7aba7a` | Success text on dark background |
| `danger` | `#c87060` | Unmet requirements, cancel buttons, error state |
| `danger-muted` | `#c07060` | Secondary danger text |
| `text-primary` | `#e0d8c8` | Body text, card content |
| `text-default` | `#e0e0e0` | Default paragraph text |
| `text-secondary` | `#9d9080` | Labels, meta information |
| `text-muted` | `#a89880` | Dimmed / inactive text |
| `overlay` | `rgba(0,0,0,0.55)` | Modal backdrop |

### Color semantics (never break without documented rationale)

- **Gold** → currency, active / pending state
- **Green** → friendly, success, ready-to-collect, met condition
- **Red / coral** → hostile, danger, unmet condition, cancel
- **Gray** → inactive, disabled, dimmed

---

## Spacing

Spacing is compact. This is a strategy game — information density is a feature.

| Scale | Value | Use |
|---|---|---|
| xs | 4px | Icon-to-label gap, tight list items |
| sm | 6–8px | Card internal padding (vertical) |
| md | 10–12px | Card internal padding (horizontal), field gaps |
| lg | 16–18px | Panel internal padding, section gaps |
| xl | 24px | Between major sections |

---

## Border & Radius

- **All borders**: `1px solid` with gold at varying opacity
  - Default: `rgba(184,134,11,0.2)` (faint, inactive cards)
  - Active: `rgba(184,134,11,0.5)` (focused / hovered)
  - Panel frame: `rgba(184,134,11,0.4)` (popup outer border)
- **Border radius**:
  - Cards / panels: 4–8px
  - Buttons: 3–4px
  - Icons: 2–4px

---

## Buttons

| Variant | Border | Text | Hover bg |
|---|---|---|---|
| Accept / primary | `1px solid accent-gold` | `accent-gold` | `rgba(200,168,75,0.1)` |
| Collect / success | `1px solid success` | `success-bright` | `rgba(90,154,90,0.1)` |
| Cancel / danger | `1px solid danger` | `danger` | `rgba(200,112,96,0.1)` |

Padding: 5–6px vertical, 12–18px horizontal. Radius: 3–4px. Font: Cormorant Garamond 500.

---

## Component Grammar

The live client uses these surface types. Mockups should respect the same taxonomy:

| Type | File suffix | Description |
|---|---|---|
| `*Screen` | full viewport | Primary game screens (map, company, loading) |
| `*Popup` | overlaid panel | Context-specific overlays (contract board, dialogue) |
| `*Panel` | side panel | Persistent side surfaces (settings, reckoning) |
| `*Modal` | blocking overlay | Destructive / critical confirmations |
| `GameHUD` | always-on | Persistent top-bar gold/troops/location display |

---

## How to update

When `/discuss-design` completes design-system discovery and finds tokens that differ from or extend this file, it writes the updated content here. Keep this file as the single source of truth — do not maintain separate token definitions in mockup files.

---

## Theme Library

Four visual themes have been explored and live in `design/themes/`. The skill selects one theme per mockup session (or "all four" for the multi-theme canvas).

| ID | File | Name | Palette summary |
|---|---|---|---|
| `iron-parchment` | `design/themes/iron-parchment.jsx` | Iron & Parchment | Aged cream (`#e9dcc0`) · ink black · wax red |
| `black-sellsword` | `design/themes/black-sellsword.jsx` | Black Sellsword | Near-black bg · ember gold · cinematic shadows |
| `cartographers-quarter` | `design/themes/cartographers-quarter.jsx` | Cartographer's Quarter | Vellum · map-blue ink · marginalia accents |
| `banner-blade` | `design/themes/banner-blade.jsx` | Banner & Blade | Flat heraldic color · bold sigils · strategy-game chrome |

**Selected theme for new mockups:** `iron-parchment` (default; override by asking the user at intake).

The tokens defined above in this file (dark `#0a0a0a` base + gold accent) apply to surfaces that aren't tied to a specific theme — e.g. loading screens, system overlays, onboarding. For game-play surfaces use the theme JSX palette directly.

**To update selected theme:** change the "Selected theme" line above. The skill reads this on every session start.