# Havoc

Havoc is a competitive gaming and esports platform with a loud, electric, cyberpunk identity — built for players who want to win.

> ⚠️ AI-generated — review and refine before shipping. The marks are extracted to SVG/PNG by an AI pipeline, so small imperfections (a stray tone, a slightly-off path, an occasional mis-cropped detail) are possible. Anything off is editable, or just ask the agent to re-generate it.

**Voice:** High-voltage competitive · Cyberpunk sharp · Victory-obsessed · Confident, never toxic · Command-line clear
**Industry:** competitive gaming & esports platform

## Logo usage

- **Clear space:** keep at least 25% of the mark's height clear on every side.
- **Minimum size:** Primary, secondary & wordmark — 24px; Letter-mark, app icon & favicon — 16px.
- **Formats:** Prefer **SVG** (crisp at any size); fall back to **PNG** (transparent) for raster contexts. Avoid JPG for marks — it's lossy and has no transparency.
- **Light / dark:** On light backgrounds use the full-color or black mark; on dark backgrounds use the white knockout (`logos/<mark>-white.svg` / `.png`) where one ships, or recolor the `.svg` fill to white. The social cards present the logo + wordmark on the brand's surface color.

## Color palette

| Hex | Name | Role |
|---|---|---|
| `#060D10` | Deep Charcoal | surface |
| `#FFD900` | Havoc Yellow | primary |
| `#FFA300` | Ember Gold | accent |
| `#FF4A0A` | Blaze Orange | muted |
| `#F20F32` | Combat Red | neutral |
| `#DDE2E6` | Light Interface Text | text |

CSS variables for these are in `tokens/globals.css` (`--color-*`).
Machine-readable tokens are in `tokens/tokens.json`.

### Contrast (WCAG 2.1)

| Pairing | Colors | Ratio | Result |
|---|---|---|---|
| text on surface | `#DDE2E6` on `#060D10` | 15.00:1 | ✅ AAA |
| text on neutral | `#DDE2E6` on `#F20F32` | 3.29:1 | AA large only |
| black on primary | `#000000` on `#FFD900` | 15.18:1 | ✅ AAA |
| white on primary | `#FFFFFF` on `#FFD900` | 1.38:1 | ❌ fails AA |

> ⚠️ 1 text pairing below WCAG 2.1 AA (4.5:1). For text on neutral, try `#000000` (4.89:1).

_Standard: **WCAG 2.1 AA** is the floor (4.5:1 normal, 3:1 large; AAA noted where met). APCA / WCAG 3 are not yet adopted — that model is still a draft._

#### Dark theme contrast

The kit derives a dark-mode palette (`color.dark.*` in `tokens.json`, `@media (prefers-color-scheme: dark)` in `globals.css`). Its key pairings:

| Pairing | Colors | Ratio | Result |
|---|---|---|---|
| text on surface | `#DDE2E6` on `#060D10` | 15.00:1 | ✅ AAA |
| text on neutral | `#DDE2E6` on `#1a2023` | 12.63:1 | ✅ AAA |
| black on primary | `#000000` on `#FFD900` | 15.18:1 | ✅ AAA |
| white on primary | `#FFFFFF` on `#FFD900` | 1.38:1 | ❌ fails AA |


## Typography

- **Heading:** PP Neue Machina (custom — license required; self-host via `@font-face`)
- **Body:** Geist (Google Fonts — auto-imported in `tokens/globals.css`)

### Type scale

A 1.25 modular scale. CSS variables (`--font-size-*`, `--line-height-*`, `--font-weight-*`) are in `tokens/globals.css`; structured tokens under `typography` in `tokens.json`.

| Role | Size | Weight | Line-height | Use |
|---|---|---|---|---|
| `display` | 2.441rem | 700 | 1.1 | hero / marketing headline |
| `h1` | 1.953rem | 700 | 1.15 | page title |
| `h2` | 1.563rem | 600 | 1.2 | section heading |
| `h3` | 1.25rem | 600 | 1.3 | subsection heading |
| `body` | 1rem | 400 | 1.5 | body copy / UI |
| `caption` | 0.8rem | 400 | 1.45 | captions / meta |

## Design tokens

### Spacing, radius & elevation

- **Spacing** (`--space-*`, 16px base): `xs` 4px · `sm` 8px · `md` 16px · `lg` 24px · `xl` 32px · `2xl` 48px · `3xl` 64px
- **Radius** (`--radius-*`): `sm` 4px · `md` 8px · `lg` 16px · `full` 9999px
- **Shadow** (`--shadow-*`): `sm` · `md` · `lg`

Full values are in `tokens.json` (`spacing`, `radius`, `shadow`, and component aliases when present) and `globals.css`.


## Favicons

Copy `favicons/` to your site root and add to `<head>`:

```html
<link rel="icon" href="/favicons/favicon.ico" sizes="any">
<link rel="icon" href="/favicons/favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/favicons/apple-touch-icon.png">
<link rel="manifest" href="/favicons/site.webmanifest">
```

## Voice

The full Voice Guide — personality, traits, tone, lexicon, mechanics, messaging, and a say/don't-say example matrix — is in `voice/voice-guidelines.md`. A machine-readable `voice/brand-voice.json` (few-shot good/bad examples) is ready to drop into your own LLM prompts.

## Files in this kit

```
brief/  — the locked brief — source of truth for vibe
  brief.png
logos/  — logo marks
  app-icon.png
  app-icon.svg
  favicon.png
  letter-mark-black.png
  letter-mark-black.svg
  letter-mark-white.png
  letter-mark-white.svg
  letter-mark.png
  letter-mark.svg
  primary-black.png
  primary-black.svg
  primary-white.png
  primary-white.svg
  primary.png
  primary.svg
  secondary-black.png
  secondary-black.svg
  secondary-white.png
  secondary-white.svg
  secondary.png
  secondary.svg
  wordmark-black.png
  wordmark-black.svg
  wordmark-white.png
  wordmark-white.svg
  wordmark.png
  wordmark.svg
favicons/  — multi-size favicon set
  apple-touch-icon.png
  favicon-16x16.png
  favicon-32x32.png
  favicon-48x48.png
  favicon.ico
  favicon.svg
  icon-192.png
  icon-512.png
  icon-maskable-512.png
  site.webmanifest
social/  — Open Graph / social share image
  og-image.dark.png
  og-image.png
  square.dark.png
  square.png
  story.dark.png
  story.png
  twitter-card.dark.png
  twitter-card.png
tokens/  — design tokens
  globals.css
  tokens.json
voice/  — Voice Guide
  brand-voice.json
  voice-guidelines.md
AGENTS.md
README.md
manifest.json
```

## Notes

- The wordmark is regenerated text-to-image from the canonical spec, not
  cropped from the source brief — this avoids inheriting any text typos
  the brief image may carry.
- Logo SVGs are produced via vectorizer.ai. Mascot illustrations stay as
  PNG only — full-color art doesn't vectorize well.
- Marks that reduce cleanly to one color ship true-black and true-white variants
  (`logos/<mark>-black.{svg,png}`, `-white.{svg,png}`): use the black on light
  surfaces, the white on dark ones. For a mark without them (detailed/illustrative
  marks), recolor the `.svg`'s flat `fill` yourself.
- Drop `tokens/globals.css` into your project's global stylesheet; the
  CSS custom properties are framework-agnostic. It ships a **dark theme**:
  the semantic `--color-role-*` variables flip automatically under
  `@media (prefers-color-scheme: dark)`, or force it with
  `<html data-theme="dark">`.
- `social/` holds ready-to-post share cards: `social/og-image.png` (1200×630 —
  the universal Open Graph card for Facebook/LinkedIn/Slack/iMessage),
  `social/twitter-card.png` (1200×675), `social/square.png` (1080² for
  Instagram/profile), and `social/story.png` (1080×1920 for stories/reels). Each
  also ships a DARK variant (`*.dark.png`) on the derived dark surface — swap to it
  for a dark-theme site with `content="…/og-image.dark.png"`. Reference the OG card
  with `<meta property="og:image" content="https://yoursite.com/og-image.png">`.
