78 lines
4.2 KiB
Markdown
78 lines
4.2 KiB
Markdown
## 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.
|