/*
  Design tokens — single source of truth for color, typography, spacing,
  radius/shadow, container widths, and breakpoints.

  Load this file FIRST, before base.css and any file in components/, on
  every page. Everything downstream references these custom properties
  instead of hard-coded literals — that's the whole point of the system.
  See README.md for the philosophy and a step-by-step customization guide.

  This is a TEMPLATE extracted from a real project's token system. Values
  marked #REPLACE_ME are this business's brand colors and must not be
  reused as-is — pick your own palette, then verify contrast (README
  section "Customizing for a new project") before shipping. Everything
  else (spacing, type scale ratios, radius/shadow, breakpoints) is a
  tested default — keep it unless you have a specific reason to change it.
*/

:root {
  /* ============================================================
     COLOR
     ------------------------------------------------------------
     Keep these ROLE names even when you change the literal values —
     every component file below is written against roles (text-primary,
     surface-alt, brand-primary...) not against raw hex codes. That's
     what makes swapping a whole palette a one-file edit instead of a
     site-wide find-and-replace.
     ============================================================ */

  /* Brand — PLACEHOLDER PALETTE, not final. Pending derivation from the
     locked hero/office images via design-discovery-prompt once picked
     (see Mega_Canadian_Image_Generation_Brief_V1.md). Chosen now to be
     roughly consistent with the approved logo (wood brown) and the
     established photography palette (warm wood, cream, charcoal,
     muted navy) so wireframes don't look jarring, not because these
     hex values are locked. */
  --color-brand-primary: #6B4423;         /* wood-brown, matches logo */
  --color-brand-primary-onDark: #C89B5C;  /* lighter warm tan for dark surfaces */
  --color-brand-dark: #1C1A17;            /* near-black warm charcoal for headers/footers/dark bands */

  /* Text */
  --color-text-primary: #2B2620;    /* dark warm charcoal-brown */
  --color-text-secondary: #6B655C;  /* warm gray */
  --color-text-inverse: #FFFFFF;        /* text on dark/brand-dark surfaces */
  --color-text-on-brand: #FFFFFF;   /* white on wood-brown passes contrast */

  /* Surfaces */
  --color-surface-default: #FFFFFF;  /* page background, card background */
  --color-surface-alt: #F5F1EA;  /* warm cream, matches "cream walls" in photography */
  --color-surface-dark: #1C1A17; /* header/footer/hero/CTA-band background */

  /* Structural */
  --color-border: #E3DCD0; /* light warm neutral */
  --color-focus: #B8863B;  /* warm gold, visible against both light and dark surfaces */

  /* Status (usable defaults — not brand-dependent, but re-verify contrast
     if you change them; these are pre-checked at >=4.5:1 on white) */
  --color-success: #1A7F4B;
  --color-error: #B3261E;

  /* ============================================================
     TYPOGRAPHY
     ------------------------------------------------------------
     Font FAMILIES below are placeholders — swap for your project's
     type choice (the source project used Merriweather/Inter; that's
     just an example, not a requirement). The SIZE SCALE is a tested
     ratio; keep it unless you have a specific reason to change it —
     see README "Why a fixed heading scale" for the reasoning.
     ============================================================ */
  --font-family-heading: Georgia, 'Times New Roman', serif; /* placeholder — no web font loaded yet, system serif keeps this dependency-free until a final pairing is chosen */
  --font-family-body: -apple-system, 'Segoe UI', Roboto, Arial, sans-serif; /* placeholder — system sans, same reasoning */

  --font-h1: 3rem;         /* 48px */
  --font-h2: 2rem;         /* 32px */
  --font-h3: 1.5rem;       /* 24px */
  --font-base: 1rem;       /* 16px — body text; never go below this on mobile, iOS Safari auto-zooms on inputs under 16px */
  --font-small: 0.875rem;  /* 14px — captions/meta/labels only, not paragraph copy */
  --line-height-body: 1.5;
  --line-height-heading: 1.1;

  /* Deliberately NOT fluid clamp() values for the heading scale. See
     README lessons-learned checklist: fluid clamp() headings can wrap
     mid-word at in-between viewport widths nobody checked while
     designing. Fixed sizes per breakpoint (see base.css) are slightly
     more code but fully predictable and easy to QA. If you do want
     fluid type for a specific element, use the clamp()-with-fallback
     pattern documented in base.css's .container rule and in the
     README's Safari-fallback checklist item. */

  /* ============================================================
     SPACING — 8px-based scale
     ------------------------------------------------------------
     Use these for every margin/padding/gap in the system. Reaching
     for an arbitrary value like "1.35rem" or "0.65rem" instead of the
     nearest scale step is exactly the ad hoc drift this scale exists
     to prevent — see README lessons-learned checklist.
     ============================================================ */
  --space-1: 0.25rem;  /* 4px  */
  --space-2: 0.5rem;   /* 8px  */
  --space-3: 0.75rem;  /* 12px */
  --space-4: 1rem;     /* 16px */
  --space-5: 1.5rem;   /* 24px */
  --space-6: 2rem;     /* 32px */
  --space-7: 3rem;     /* 48px */
  --space-8: 4rem;     /* 64px */

  /* ============================================================
     RADIUS / SHADOW
     ============================================================ */
  --radius-sm: 2px;  /* form inputs */
  --radius-md: 4px;  /* cards, buttons */
  --radius-lg: 8px;  /* modals, large media panels */

  --shadow-sm: 0 2px 6px rgba(0, 0, 0, 0.08);
  --shadow-md: 0 18px 38px rgba(0, 0, 0, 0.09);
  --shadow-lg: 0 22px 44px rgba(0, 0, 0, 0.12);

  /* ============================================================
     CONTAINERS
     ============================================================ */
  --container-max: 1200px;      /* full-width sections, headers/footers */
  --container-standard: 960px;  /* default body/content width */
  --container-narrow: 720px;    /* long-form text, legal pages, forms */

  /* ============================================================
     BREAKPOINTS
     ------------------------------------------------------------
     CSS custom properties cannot be referenced inside @media query
     conditions (that's a CSS spec limitation, not a bug here) — these
     exist purely as the documented source of truth for the literal
     px values used directly in @media declarations throughout
     base.css and components/*.css. If a project moves to Sass/PostCSS,
     these become real variables/custom media queries; keep them in
     sync with the values below either way.
     ============================================================ */
  --breakpoint-xs: 480px;
  --breakpoint-sm: 640px;
  --breakpoint-md: 900px;
  --breakpoint-lg: 1200px;
}