qumo-website/openspec/specs/brand-tokens/spec.md

Spec: Brand Tokens

Purpose

Defines the Qumo brand design tokens (colors, typography, fonts) exposed as Tailwind CSS utilities and loaded globally across all pages. Covers color token configuration, Archia font-face declarations, global CSS import strategy, sitemap integration, and the initial brand smoke test page.

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