step 002 complete

2026-04-10 18:41:58 +02:00
parent e9aa6f452b
commit 089dbaa606
26 changed files with 2732 additions and 15 deletions
--- a/openspec/changes/archive/2026-04-10-step-002-base-layout/specs/base-layout/spec.md
+++ b/openspec/changes/archive/2026-04-10-step-002-base-layout/specs/base-layout/spec.md
@@ -0,0 +1,76 @@
+## ADDED Requirements
+
+### Requirement: BaseLayout provides complete HTML document shell
+`src/layouts/BaseLayout.astro` SHALL render a complete HTML document (`<!DOCTYPE html>`, `<html>`, `<head>`, `<body>`) that every page can wrap its content in. It SHALL accept the following props:
+- `title: string` — page-specific `<title>` and OG title
+- `description: string` — page-specific meta description and OG description
+- `locale?: string` — BCP 47 language tag, default `"en"`
+- `canonicalUrl: string` — absolute canonical URL for this page
+- `alternateUrl: string` — absolute URL of the alternate-locale version of this page
+- `ogImage?: string` — absolute URL for `og:image`; tag is omitted when falsy
+- `jsonLd?: Record<string, unknown>` — structured data object to serialize as JSON-LD
+
+#### Scenario: Page renders with all head meta tags
+- **WHEN** a page wraps its content in `<BaseLayout>` with all props provided
+- **THEN** the rendered HTML `<head>` SHALL contain: `<meta charset="utf-8">`, `<meta name="viewport">`, `<link rel="icon">` for both SVG and ICO favicons, `<link rel="canonical">`, `<link rel="alternate" hreflang>` for both locales, `<meta property="og:*">` tags, `<meta name="twitter:*">` tags, and `<title>`
+
+#### Scenario: OG image tag omitted when ogImage is falsy
+- **WHEN** `ogImage` prop is an empty string or not provided
+- **THEN** no `<meta property="og:image">` tag SHALL appear in the rendered HTML
+
+#### Scenario: Body has brand defaults
+- **WHEN** any page uses BaseLayout
+- **THEN** the `<body>` element SHALL have Tailwind classes `bg-midnight text-snow font-archia` applied
+
+### Requirement: BaseLayout preloads critical Archia font weights
+The `<head>` SHALL contain `<link rel="preload" as="font" type="font/woff2" crossorigin>` for Archia Regular (400), SemiBold (600), and Bold (700) woff2 files. Thin (100) and Light (300) SHALL NOT be preloaded.
+
+#### Scenario: Correct preload tags rendered
+- **WHEN** the page HTML is rendered
+- **THEN** exactly three font preload links SHALL appear in `<head>`: one each for `archia-regular-webfont.woff2`, `archia-semibold-webfont.woff2`, and `archia-bold-webfont.woff2`
+
+### Requirement: BaseLayout renders hreflang alternates
+The `<head>` SHALL contain `<link rel="alternate" hreflang>` tags for both `en` and `nl` locales, plus an `x-default` pointing to the EN URL.
+
+#### Scenario: EN page hreflang output
+- **WHEN** a page passes `locale="en"`, `canonicalUrl="https://qumo.io/about"`, `alternateUrl="https://qumo.io/nl/about"`
+- **THEN** the head SHALL contain:
+  - `<link rel="alternate" hreflang="en" href="https://qumo.io/about">`
+  - `<link rel="alternate" hreflang="nl" href="https://qumo.io/nl/about">`
+  - `<link rel="alternate" hreflang="x-default" href="https://qumo.io/about">`
+
+#### Scenario: NL page hreflang output
+- **WHEN** a page passes `locale="nl"`, `canonicalUrl="https://qumo.io/nl/about"`, `alternateUrl="https://qumo.io/about"`
+- **THEN** the head SHALL contain the same three hreflang tags with EN/NL values swapped appropriately, and `x-default` SHALL always point to the EN URL (the `alternateUrl` on NL pages)
+
+### Requirement: BaseLayout supports JSON-LD injection via prop
+When the `jsonLd` prop is provided, BaseLayout SHALL render a `<script type="application/ld+json">` tag in `<head>` containing the JSON-serialized value.
+
+#### Scenario: JSON-LD rendered from prop
+- **WHEN** `jsonLd={{ "@context": "https://schema.org", "@type": "WebPage", "name": "About" }}` is passed
+- **THEN** the head SHALL contain `<script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","name":"About"}</script>`
+
+#### Scenario: No JSON-LD script when prop omitted
+- **WHEN** `jsonLd` prop is not provided
+- **THEN** no `<script type="application/ld+json">` tag SHALL appear in the rendered head (beyond any injected via the named slot)
+
+### Requirement: BaseLayout supports additional JSON-LD via named slot
+A `<slot name="jsonld" />` SHALL be provided inside `<head>` for pages that need additional or multiple structured data blocks beyond the `jsonLd` prop.
+
+#### Scenario: Named slot accepts additional script
+- **WHEN** a page passes `<script slot="jsonld" type="application/ld+json">{"@type":"BreadcrumbList"}</script>`
+- **THEN** that script tag SHALL appear in the rendered `<head>`
+
+### Requirement: BaseLayout includes Nav and Footer stub components
+`BaseLayout.astro` SHALL import `src/components/Nav.astro` and `src/components/Footer.astro` and render them at the top and bottom of `<body>` respectively. Both components are stubs that render nothing in this step.
+
+#### Scenario: Nav and Footer positions in body
+- **WHEN** any page uses BaseLayout
+- **THEN** the `<body>` structure SHALL be: Nav stub output → `<slot />` (page content) → Footer stub output
+
+### Requirement: BaseLayout content slot renders page content
+A default `<slot />` SHALL be provided between Nav and Footer for page-specific content.
+
+#### Scenario: Page content appears in slot
+- **WHEN** a page places markup inside `<BaseLayout>...</BaseLayout>`
+- **THEN** that markup SHALL appear in the rendered body between Nav and Footer
--- a/openspec/changes/archive/2026-04-10-step-002-base-layout/specs/content-i18n/spec.md
+++ b/openspec/changes/archive/2026-04-10-step-002-base-layout/specs/content-i18n/spec.md
@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Locale content JSON files contain global meta fields
+`src/content/en.json` and `src/content/nl.json` SHALL each contain a top-level `"meta"` key with the following fields:
+- `siteName: string` — the site name (e.g., `"Qumo"`)
+- `defaultTitle: string` — default page title (used as fallback)
+- `defaultDescription: string` — default meta description (used as fallback)
+- `defaultOgImage: string` — default OG image path; may be empty string initially
+
+#### Scenario: en.json has correct meta structure
+- **WHEN** `src/content/en.json` is parsed as JSON
+- **THEN** it SHALL have a `meta` object with string values for `siteName`, `defaultTitle`, `defaultDescription`, and `defaultOgImage`
+
+#### Scenario: nl.json has correct meta structure
+- **WHEN** `src/content/nl.json` is parsed as JSON
+- **THEN** it SHALL have the same `meta` object shape as `en.json`, with Dutch-language values for `defaultTitle` and `defaultDescription`
+
+### Requirement: i18n helper returns correct content for locale
+`src/content/i18n.ts` SHALL export a function `getContent(locale: string)` that returns the parsed content object for the given locale. It SHALL return the EN content object for any unrecognized locale string.
+
+#### Scenario: Returns EN content for "en" locale
+- **WHEN** `getContent("en")` is called
+- **THEN** the function SHALL return the parsed contents of `src/content/en.json`
+
+#### Scenario: Returns NL content for "nl" locale
+- **WHEN** `getContent("nl")` is called
+- **THEN** the function SHALL return the parsed contents of `src/content/nl.json`
+
+#### Scenario: Falls back to EN for unknown locale
+- **WHEN** `getContent("fr")` or any unrecognized locale string is called
+- **THEN** the function SHALL return the parsed contents of `src/content/en.json`
+
+### Requirement: Content files use static imports (no runtime fetch)
+The `i18n.ts` helper SHALL use static ES module imports (`import enContent from './en.json'`) rather than dynamic `fetch` or `fs.readFile`. This ensures type safety and tree-shaking at build time.
+
+#### Scenario: Build succeeds with static imports
+- **WHEN** `npm run build` is executed in the `website/` directory
+- **THEN** the build SHALL complete without errors, with locale content bundled statically