step 002 complete

openspec/changes/archive/2026-04-10-step-001-project-scaffold/design.md

@@ -0,0 +1,77 @@
+## 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.