step 002 complete
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-04-10
|
||||
@@ -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.
|
||||
@@ -0,0 +1,33 @@
|
||||
## Why
|
||||
|
||||
The Astro project scaffold exists but has no Tailwind CSS integration or brand tokens configured. Before any UI work can begin, the design system foundation must be in place: brand colors, the Archia typeface, and the gradient — all wired into Tailwind so every subsequent step can use utility classes directly.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Install `tailwindcss` and `@tailwindcss/vite` (Tailwind v4) and `@astrojs/sitemap`
|
||||
- Configure `astro.config.mjs` with the Vite Tailwind plugin and sitemap integration
|
||||
- Create `src/styles/global.css` with:
|
||||
- `@import "tailwindcss"`
|
||||
- `@theme` block defining brand color tokens and `font-archia`
|
||||
- `@font-face` declarations for all 6 Archia weights (Thin, Light, Regular, Medium, SemiBold, Bold)
|
||||
- Replace the default `src/pages/index.astro` with a brand smoke test page showing color swatches, font weight samples, and a gradient bar
|
||||
- No `tailwind.config.mjs` — configuration is CSS-based (Tailwind v4 pattern)
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `brand-tokens`: Qumo design system tokens available as Tailwind utilities — brand colors (`midnight`, `snow`, `brand-blue`, `brand-red`), `font-archia`, and the gradient definition
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
_(none)_
|
||||
|
||||
## Impact
|
||||
|
||||
- `website/package.json` — new dependencies: `tailwindcss`, `@tailwindcss/vite`, `@astrojs/sitemap`
|
||||
- `website/astro.config.mjs` — adds Vite plugin and sitemap integration
|
||||
- `website/src/styles/global.css` — new file, imported globally
|
||||
- `website/src/pages/index.astro` — replaced with temporary smoke test (will be replaced again in a later step when the homepage is built)
|
||||
- No SEO impact — smoke test page is a dev-only visual check
|
||||
- No content strings needed — smoke test has no user-visible text to localize
|
||||
@@ -0,0 +1,81 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Brand color tokens available as Tailwind utilities
|
||||
The build system SHALL expose Qumo brand colors as Tailwind utility classes via the `@theme` block in `global.css`. The following tokens SHALL be defined:
|
||||
- `--color-midnight: #102022` → `bg-midnight`, `text-midnight`, `border-midnight`
|
||||
- `--color-snow: #F3F3F3` → `bg-snow`, `text-snow`, `border-snow`
|
||||
- `--color-brand-blue: #5257E4` → `bg-brand-blue`, `text-brand-blue`
|
||||
- `--color-brand-red: #F71E3E` → `bg-brand-red`, `text-brand-red`
|
||||
|
||||
#### Scenario: Color utilities compile correctly
|
||||
- **WHEN** a component uses `bg-midnight text-snow`
|
||||
- **THEN** the compiled CSS contains the exact hex values `#102022` and `#F3F3F3`
|
||||
|
||||
#### Scenario: Gradient is available as a CSS variable
|
||||
- **WHEN** a component applies `style="background: var(--gradient-brand)"`
|
||||
- **THEN** the element renders a linear gradient from `#5257E4` to `#F71E3E`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Archia font available as a Tailwind utility
|
||||
The build system SHALL expose `font-archia` as a Tailwind font-family utility via `--font-archia` in the `@theme` block. The font stack SHALL be `"Archia", ui-sans-serif, system-ui, sans-serif`.
|
||||
|
||||
#### Scenario: Font utility applies correct stack
|
||||
- **WHEN** a component uses `font-archia`
|
||||
- **THEN** the compiled CSS sets `font-family: "Archia", ui-sans-serif, system-ui, sans-serif`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: All 6 Archia weights loaded via @font-face
|
||||
`global.css` SHALL declare `@font-face` rules for all 6 Archia weights using the woff2 files in `src/assets/fonts/archia/`. Each declaration SHALL use `font-display: swap`.
|
||||
|
||||
| Weight name | CSS font-weight | File |
|
||||
|-------------|-----------------|-------------------------------|
|
||||
| Thin | 100 | archia-thin-webfont.woff2 |
|
||||
| Light | 300 | archia-light-webfont.woff2 |
|
||||
| Regular | 400 | archia-regular-webfont.woff2 |
|
||||
| Medium | 500 | archia-medium-webfont.woff2 |
|
||||
| SemiBold | 600 | archia-semibold-webfont.woff2 |
|
||||
| Bold | 700 | archia-bold-webfont.woff2 |
|
||||
|
||||
#### Scenario: Font renders with correct weight
|
||||
- **WHEN** a component uses `font-archia font-bold`
|
||||
- **THEN** the browser loads `archia-bold-webfont.woff2` and renders text at weight 700
|
||||
|
||||
#### Scenario: Fallback renders while font loads
|
||||
- **WHEN** the woff2 file has not yet loaded
|
||||
- **THEN** the browser renders text using the system fallback font (`ui-sans-serif`) due to `font-display: swap`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: global.css imported globally by Astro
|
||||
`src/styles/global.css` SHALL be imported in `astro.config.mjs` or in the root layout so that brand tokens and font-face declarations apply to every page.
|
||||
|
||||
#### Scenario: Tokens available without per-page import
|
||||
- **WHEN** any `.astro` page component uses `bg-midnight`
|
||||
- **THEN** the class applies without that page importing `global.css` directly
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Sitemap integration configured
|
||||
`astro.config.mjs` SHALL include `@astrojs/sitemap` with `site: 'https://qumo.io'` so that `sitemap-index.xml` is generated on every build.
|
||||
|
||||
#### Scenario: Sitemap generated on build
|
||||
- **WHEN** `npm run build` is executed
|
||||
- **THEN** `dist/sitemap-index.xml` and `dist/sitemap-0.xml` are present in the output
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Brand smoke test page
|
||||
`src/pages/index.astro` SHALL be a temporary visual smoke test page (not production content) that allows a developer to verify all brand tokens render correctly. It SHALL show:
|
||||
- A color swatch for each brand color token (Midnight, Snow, Brand Blue, Brand Red)
|
||||
- A gradient bar using `--gradient-brand`
|
||||
- A font weight sample row for each of the 6 Archia weights (showing uppercase and sentence-case text)
|
||||
|
||||
#### Scenario: Smoke test builds without errors
|
||||
- **WHEN** `npm run build` is run after setup
|
||||
- **THEN** the build succeeds with zero errors
|
||||
|
||||
#### Scenario: All font weights visible in dev
|
||||
- **WHEN** `npm run dev` is run and the index page is opened
|
||||
- **THEN** 6 distinct font weights are visible and the gradient bar shows the blue-to-red gradient
|
||||
@@ -0,0 +1,30 @@
|
||||
## 1. Install dependencies
|
||||
|
||||
- [x] 1.1 Install `tailwindcss` and `@tailwindcss/vite` in `website/`
|
||||
- [x] 1.2 Install `@astrojs/sitemap` in `website/`
|
||||
|
||||
## 2. Configure Astro
|
||||
|
||||
- [x] 2.1 Update `astro.config.mjs` to add `@tailwindcss/vite` as a Vite plugin and `@astrojs/sitemap` as an integration with `site: 'https://qumo.io'`
|
||||
|
||||
## 3. Create global.css
|
||||
|
||||
- [x] 3.1 Create `src/styles/global.css` with `@import "tailwindcss"`
|
||||
- [x] 3.2 Add `@theme` block with brand color tokens: `--color-midnight`, `--color-snow`, `--color-brand-blue`, `--color-brand-red`
|
||||
- [x] 3.3 Add `--font-archia` to the `@theme` block with system fallback stack
|
||||
- [x] 3.4 Add `:root` block with `--gradient-brand: linear-gradient(135deg, #5257E4, #F71E3E)`
|
||||
- [x] 3.5 Add `@font-face` declarations for all 6 Archia weights (Thin/100, Light/300, Regular/400, Medium/500, SemiBold/600, Bold/700) pointing to `../assets/fonts/archia/` woff2 files, each with `font-display: swap`
|
||||
|
||||
## 4. Wire global.css into Astro
|
||||
|
||||
- [x] 4.1 Import `../styles/global.css` in `src/pages/index.astro` (will move to BaseLayout in step 002)
|
||||
|
||||
## 5. Brand smoke test page
|
||||
|
||||
- [x] 5.1 Replace the default `src/pages/index.astro` content with a smoke test page: a color swatch grid (Midnight, Snow, Brand Blue, Brand Red, + gradient bar) and a font weight table (Thin through Bold, each row showing uppercase + sentence-case sample text)
|
||||
|
||||
## 6. Verify
|
||||
|
||||
- [x] 6.1 Run `npm run build` inside `website/` — must succeed with zero errors
|
||||
- [x] 6.2 Run `npm run dev` and open the index page — verify all 4 color swatches, the gradient bar, and all 6 font weights render correctly
|
||||
- [x] 6.3 Confirm `dist/sitemap-index.xml` is present in the build output
|
||||
Reference in New Issue
Block a user