## Context

The Astro project was scaffolded with `astro@6.1.5` and directory structure in place, but `astro.config.mjs` is empty and no Tailwind integration exists. The Archia woff2 font files are already present at `src/assets/fonts/archia/`. The migration steps doc was written expecting Tailwind v3 patterns (`tailwind.config.mjs`); we are using Tailwind v4 instead.

## Goals / Non-Goals

**Goals:**
- Tailwind v4 fully wired into the Astro 6 build pipeline
- All Qumo brand color tokens available as Tailwind utility classes (`bg-midnight`, `text-snow`, etc.)
- `font-archia` available as a Tailwind font utility
- All 6 Archia weights loaded via `@font-face` with `font-display: swap`
- `@astrojs/sitemap` configured with `site: 'https://qumo.io'`
- A smoke test page that confirms every token and weight renders correctly

**Non-Goals:**
- No real page content, layout, or navigation (those are steps 002–004)
- No NL locale routing yet
- No SEO meta tags or structured data yet
- No production optimisation of font loading (preloads come in step 002 with BaseLayout)

## Decisions

### Tailwind v4 over v3

**Decision:** Use `@tailwindcss/vite` (Tailwind v4) rather than `tailwindcss@3` + `@astrojs/tailwind`.

**Rationale:** Tailwind v4 is the current major version and integrates natively with Vite via a single Vite plugin — no Astro integration adapter needed. Configuration is CSS-based (`@theme` block), which keeps brand tokens co-located with the font-face declarations in one file. Astro 6 ships with Vite 6, which is fully supported.

**Alternative considered:** Tailwind v3 (`tailwind.config.mjs`). Rejected because it requires an additional `@astrojs/tailwind` adapter with limited Astro 6 testing, and the JS config file adds complexity for what is simply a set of color + font token definitions.

### CSS-based token definition

**Decision:** Brand tokens defined in `src/styles/global.css` using the `@theme` block, not in a JS config.

```css
@import "tailwindcss";

@theme {
  --color-midnight: #102022;
  --color-snow: #F3F3F3;
  --color-brand-blue: #5257E4;
  --color-brand-red: #F71E3E;
  --font-archia: "Archia", ui-sans-serif, system-ui, sans-serif;
}
```

**Rationale:** Tailwind v4 CSS variables in `@theme` are automatically exposed as utilities (`bg-midnight`, `text-snow`, `font-archia`, etc.) with no additional config. This is the idiomatic v4 pattern.

### Gradient as CSS custom property, not a Tailwind utility

**Decision:** Define the brand gradient as a CSS custom property in `global.css` rather than a Tailwind background utility.

```css
:root {
  --gradient-brand: linear-gradient(135deg, #5257E4, #F71E3E);
}
```

**Rationale:** The gradient is used in specific, controlled contexts (hero accent, CTA sections) — never as a flat background. A raw CSS variable is easier to apply precisely than a generated utility class, and avoids accidentally using the gradient colors as standalone flat colors.

### Font loading strategy

**Decision:** `@font-face` declarations in `global.css` with `font-display: swap`. Load Regular, SemiBold, and Bold in the initial stylesheet; defer Thin, Light, and Medium.

**Rationale:** Archia Regular/SemiBold/Bold covers all visible text in the design. Thin/Light/Medium are used sparingly if at all. Font preloads (`<link rel="preload">`) will be added to BaseLayout in step 002 for the three primary weights.

### Smoke test in index.astro

**Decision:** Replace the default `index.astro` with a dev-only smoke test. It is not a real page — it will be fully replaced in the homepage step.

**Structure:** Color swatch grid (4 swatches + gradient bar) + font weight table (Thin → Bold, each showing uppercase and sentence-case samples) + a note that this is a dev artifact.

## Risks / Trade-offs

- **Tailwind v4 is newer** → Less community Q&A available. Mitigation: Astro Docs MCP server has current documentation; the API surface for what we need (colors, fonts) is stable.
- **`@tailwindcss/typography` compatibility** → Already in devDeps; v4-compatible version should be installed. Mitigation: verify it installs without peer dep errors after `npm install`.
- **Smoke test left in place too long** → If step 002 is delayed, the index route shows a dev page. Acceptable: this is a dev-only environment until deployment.