# THE BRAJ — Design Token Reference (Phase 1)

**Source of truth:** `resources/css/tokens.css` (imported first by `resources/css/frontend.css`)
**Date:** 2026-10-18 · **Baseline:** `93e70f8`

This is the mapping table and usage rulebook for the shared public design system.
Page-level rewrites (Phase 3+) must replace raw colour literals with these tokens.

---

## 1. The two token families (rule)

| Family | Prefix | Theme behaviour | Where to use it |
|---|---|---|---|
| **Raw brand constants** | `--braj-*` | **Never changes** between dark/light | Always-dark chrome only: header, top bar, footer, hero overlays, print-style constants |
| **Semantic tokens** | `--bg-*`, `--text-*`, `--gold*`, `--border-*`, `--shadow-*`, `--search-*`, `--mega-*` | Re-defined per theme (`[data-theme="light"]`) | All page content, so day/night mode keeps working |

> Using `--braj-gold` inside page content is wrong — it will not follow the light theme.
> Using `--gold` inside the footer is also acceptable only because the footer is always dark
> *and* both themes happen to be checked; prefer `--braj-*` there for safety.

---

## 2. Colour mapping — literal → token

### 2.1 Raw brand (theme-independent)

| Literal | Token | Used by |
|---|---|---|
| `#000000` | `--braj-black` | header / footer / body (dark) |
| `#0B0A08` | `--braj-ink` | top bar, cards (dark) |
| `#12110E` | `--braj-ink-soft` | card hover, inputs (dark) |
| `#F5F2EA` | `--braj-cream` | headings, cream text |
| `#FFFFFF` | `--braj-white` | white text/surfaces |
| `#555555` | `--braj-grey` | dim separators |
| `#F2B622` | `--braj-gold` | brand gold |
| `#FFC94D` | `--braj-gold-light` | gold highlight |
| `#AC6106` | `--braj-gold-dark` | deep gold |
| `#6B4508` | `--braj-gold-deep` | darkest gold |
| `#A8A39A` | `--braj-muted` | muted text on dark |
| `#6D6A63` | `--braj-muted-soft` | muted text on light |
| `#E7DED0` / `#D4C9B8` / `#FFFDF8` | `--braj-cream-line` / `-line-strong` / `-input` | light-theme surfaces |
| `rgba(242,182,34,.05 … .40)` | `--braj-gold-05 / -08 / -10 / -15 / -20 / -25 / -30 / -40` | gold tints |
| `rgba(0,0,0,.5)` / `.6` | `--braj-overlay-50` / `--braj-overlay-60` | scrims |
| `#B52A2A`, `#FF7A7A`, `#E25555` | `--braj-danger`, `--braj-danger-text`, `--braj-danger-text-light` | emergency/alerts |
| `#25D366` | `--braj-success` | WhatsApp / success |
| `#3D8D14`, `#14858A`, `#0554B4`, `#0AAAC0` | `--peacock-green/teal/blue/cyan` | brand accents |

### 2.2 Semantic (theme-aware)

| Token | Dark | Light |
|---|---|---|
| `--bg-body` | `#000000` | `#F5F2EA` |
| `--bg-card` / `--bg-card-hover` | `#0B0A08` / `#12110E` | `#FFFFFF` / `#FFFDF8` |
| `--bg-header` / `--bg-header-top` | `#000000` / `#0B0A08` | `#FFFFFF` / `#F5F2EA` |
| `--bg-footer` | `#000000` | `#000000` (footer stays dark) |
| `--bg-input` | `#12110E` | `#FFFDF8` |
| `--text-primary` | `#F5F2EA` | `#1A1816` |
| `--text-secondary` | `#A8A39A` | `#6D6A63` |
| `--text-heading` | `#F2B622` | `#AC6106` |
| `--gold` / `--gold-bright` / `--gold-dark` | `#F2B622` / `#FFC94D` / `#AC6106` | `#AC6106` / `#F2B622` / `#6B4508` |
| `--gold-bg` | `rgba(242,182,34,.08)` | `rgba(172,97,6,.06)` |
| `--border-color` / `--border-strong` | `rgba(242,182,34,.2)` / `.35` | `#E7DED0` / `#D4C9B8` |
| `--shadow-card` / `--shadow-card-hover` | gold-tinted | neutral black |
| `--search-bg` / `--search-border` | `#0B0A08` / `rgba(242,182,34,.3)` | `#FFFFFF` / `#D4C9B8` |
| `--mega-bg` / `--mega-border` | `#0B0A08` / `rgba(242,182,34,.2)` | `#FFFFFF` / `#E7DED0` |
| `--bg-skeleton-start/-mid` | `#1a1814` / `#2a2520` | `#E7DED0` / `#F5F2EA` |

> **Known pre-existing quirk:** `resources/css/app.css` force-overrides
> `[data-theme="light"] body { background:#f3f4f6 !important }`, so the *body*
> in light mode renders `#f3f4f6` (grey-100) instead of `--bg-body` (`#F5F2EA`).
> Unchanged in Phase 1 — decide in Phase 5 whether to honour `--bg-body`.

---

## 3. Non-colour tokens

| Group | Tokens |
|---|---|
| Typography | `--font-body` (Inter) · `--font-display` (Cormorant Garamond) · `--font-alt` (Cinzel) · `--font-hindi` (Noto Sans Devanagari → Inter fallback) · `--font-mono` |
| Type scale | `--text-2xs … --text-6xl` (10 → 64px) · `--leading-tight/snug/normal/relaxed` · `--tracking-tight/wide/caps` |
| Spacing | `--space-1 … --space-24` (4 → 96px) |
| Radius | `--radius-sm/md/lg/xl/2xl/pill/full` |
| Shadow | `--shadow-sm/md/lg/xl` (+ theme-specific `--shadow-card*`) |
| Z-index | `--z-base/dropdown/sticky/float/header/drawer/overlay/preloader` |
| Motion | `--dur-fast/base/slow` · `--ease-default/out/in-out` |
| Breakpoints | `--bp-sm 480px` · `--bp-md 767px` · `--bp-lg 1199px` · `--bp-xl 1440px` — **copy literally into `@media`, CSS variables do not work there** |

---

## 4. Shared primitives (in `resources/css/frontend.css`)

| Group | Classes |
|---|---|
| Typography | `.t-display` `.t-h1` `.t-h2` `.t-h3` `.t-h4` `.t-lead` `.t-body` `.t-body-sm` `.t-caption` `.t-eyebrow` `.t-gold` `.t-heading` `.t-muted` `.t-center` · `.font-devanagari` (auto-applied to `[lang="hi"]`) |
| Buttons | existing `.btn-primary` `.btn-secondary` `.btn-emergency` `.btn-outline-custom` + new `.btn-outline` `.btn-ghost` `.btn-lg` `.btn-block` |
| Forms | `.form-group` `.form-label` `.form-input` `.form-textarea` `.form-select` `.form-help` `.form-error` `.is-invalid` |
| Badges | `.badge` + `.badge--gold` `--solid` `--outline` `--muted` `--success` `--danger` |
| Panels | `.panel` `.panel__header` `.panel__body` `.panel__footer` |
| Layout | `.stack` `.row` `.grid-auto` `.grid-auto--sm` `.full-bleed` `.divider` |
| A11y | `.sr-only` `.skip-link` (wired to `<main id="main">`) · global `:focus-visible` ring · `::selection` · `prefers-reduced-motion` kill-switch |

---

## 5. What Phase 1 changed (files)

| File | Change |
|---|---|
| `resources/css/tokens.css` | **NEW** — single source of truth for all tokens |
| `resources/css/frontend.css` | `@import './tokens.css'` (first line) + shared primitives section |
| `resources/views/frontend/layouts/app.blade.php` | removed duplicated `:root`/`[data-theme]` variable block (now commented); added Noto Sans Devanagari to the Google Fonts request; added skip-link + `<main id="main" tabindex="-1">` |
| `resources/views/frontend/partials/header.blade.php` | **51/51** colour literals inside `<style>` → tokens |
| `resources/views/frontend/partials/footer.blade.php` | **17/17** colour literals inside `<style>` → tokens |
| `docs/design-tokens.md` | this document |

**Not changed:** any route, controller, model, migration, admin view, `app.css`, page-level blades.
**Verification:** `npm run build` green · 10 public routes HTTP 200 · token values read back from live DOM (dark + light) · before/after screenshots of `/` identical · 0 console errors.

---

## 6. Rules for Phase 3 page rewrites

1. Replace a hex **only** when a token with the *identical* value exists (table above).
2. Never batch-replace across files — one page at a time, screenshot before/after.
3. Page content uses semantic tokens; header/footer/hero-chrome may use `--braj-*`.
4. Put page-specific CSS in the page's `<style>` block but token-driven; shared rules move to `frontend.css`.
5. Hindi strings must carry `lang="hi"` (the font stack applies automatically).
6. No new statistics, hours, contacts, coordinates or claims may be introduced by a rewrite.
