4.2 KiB
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-archiaavailable as a Tailwind font utility- All 6 Archia weights loaded via
@font-facewithfont-display: swap @astrojs/sitemapconfigured withsite: '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.
@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.
: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/typographycompatibility → Already in devDeps; v4-compatible version should be installed. Mitigation: verify it installs without peer dep errors afternpm 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.