Requirements

The theme shall support small business informational websites as a primary use case.

The theme shall support multi-service business websites.

The theme shall support multi-location / multi-site business websites.

The theme shall support content-driven marketing or editorial websites.

Static Site Generation (SSG) shall be the default rendering strategy.

The theme shall support hybrid rendering patterns.

Hybrid rendering shall support dynamic behaviors including search, filtering, pagination, sorting, and forms requiring runtime logic.

Theme switching shall be supported at runtime.

Theme switching shall persist user preference across sessions.

A theme control component shall support Light, Dark, and System modes.

Dark mode selection shall resolve using persisted preference followed by system preference.

Search, filtering, sorting, and pagination behaviors shall be supported.

Dynamic views shall provide standardized empty-state behavior.

View transitions shall be supported for full page navigation.

Dark mode shall be supported at runtime.

The theme shall include foundational UI primitives.

The theme shall include a limited set of composite components.

A Breadcrumbs component shall be provided.

An Image Lightbox component shall be provided.

The SiteLogo component shall render an SVG logo (preferred), PNG logo (fallback), or site title text (final fallback) based on what is configured in src/config/site.ts, with no props required for default behavior.

Button components shall support defined visual variations.

Modal and overlay components shall define scroll locking behavior while active.

A Back to Top control shall be provided.

The Back to Top control shall be optionally enabled or disabled.

The Back to Top control shall support independent enablement for desktop and mobile contexts.

Markdown and/or MDX authoring shall be supported.

Draft content states shall be supported.

Estimated reading time shall be supported.

Table of contents generation shall be supported.

Modified time shall be supported.

Primary category taxonomy shall be supported.

Tags taxonomy shall be supported.

Category and tag listings shall support pagination by default.

Infinite loading shall be optionally supported.

Standardized empty-state UI patterns shall be defined.

Images shall be optimized automatically.

Art-directed image support shall be provided.

Responsive image components shall be provided.

Missing images shall degrade gracefully.

A skip-to-content link shall be provided.

Forms shall display visible validation and error messaging.

Canonical URLs shall be generated automatically.

Generated URLs shall be overridable.

Sitemap generation shall be supported.

Content shall be able to exclude itself from sitemap outputs.

Twitter Card metadata shall be supported.

Open Graph metadata shall be supported.

Robots.txt generation shall be supported.

Web Manifest support shall be provided.

Analytics and tracking scripts shall be blocked until consent.

A cookie consent mechanism shall be provided.

Consent states shall support Accept, Reject, and Required Only.

Compiled documentation shall be provided by default, disableable via site configuration.

A requirements index page shall be provided when the theme-docs system is enabled.

Per-requirement detail pages shall be system-generated when the theme-docs system is enabled.

Requirements discovery views shall support filtering with shareable URL state.

Local font loading shall be supported.

In production-aligned outputs (build/preview/deployed), requests for URLs missing the required trailing slash shall automatically redirect to the trailing-slash canonical URL.

Template V1 shall provide a configurable primary navigation system that supports nested menu nodes.

The SiteLogo component shall support a primary logo and an alternate logo variant; the alternate shall activate automatically based on the active color-scheme theme, and shall be overridable via an explicit prop that takes precedence over the theme-driven default.

The SiteLogo component shall use an explicit alt text value when configured; when not configured it shall fall back to the site title from src/config/site.ts.

The theme switcher shall be available in two variants: an icon-cycling button (ThemeIconSwitcher) and a text select dropdown (ThemeModeSwitcher). Both shall support Light, Dark, and System modes and share the same preference storage contract.

The active theme switcher variant shall be configurable via a single field in src/config/site.ts (themeSwitcher: 'icon' | 'select' | 'none') without requiring changes to header or layout components.

When themeSwitcher is set to 'none', no theme control shall be rendered and the site shall present in light mode only; no switcher markup shall appear in the desktop header or mobile dialog.

The icon theme switcher shall cycle through modes in the order system -> light -> dark -> system on each click, display the icon corresponding to the current preference, and update its aria-label and title to reflect the active mode.

The primary navigation shall include a search entry point (icon link) in both desktop and mobile contexts, implemented via Search.astro with a data-search-trigger attribute for future modal wiring.

The footer shall render social icon links driven by the site configuration surface; omitting or emptying the configured social links shall hide the social icons row entirely.

The footer shall render SiteLogo to maintain brand consistency between header and footer without duplicating logo configuration.

Any external link that opens in a new tab (target='_blank') shall include rel='noopener noreferrer'. External links in prose content shall not open in a new tab by default; only links where the author explicitly intends a new-tab experience (e.g. social icons, certain CTAs) shall use target='_blank'.

External links in prose content shall render a visually distinct icon (e.g. external-link glyph) adjacent to the link text. Links that open in a new tab shall additionally include a visually hidden announcement (e.g. '(opens in new tab)') so screen reader users are informed of the context change.

Static `.astro` pages and markdown content entries shall support an optional `heroTitle` field that, when present, overrides `title` as the rendered page H1 heading while `title` continues to drive the browser tab title and SEO `<title>` tag.

Static `.astro` pages and markdown content entries shall support an optional `shortTitle` field for use in condensed-space surfaces such as navigation labels, breadcrumbs, and card titles.

The system shall support a provider-agnostic redirects manifest that defines redirect rules in source control. Redirect execution uses Astro's native routing with middleware status code correction. The manifest format is designed for future provider-specific output generation (e.g., Netlify, Vercel, Cloudflare) without making any provider mandatory.

Redirects shall be definable at the content level via frontmatter in addition to the global redirects manifest.

The navigation system shall define a Primary Menu and a Utility Menu by default. The Primary Menu drives main site navigation; the Utility Menu is intended for footer and legal/system pages.

The mobile navigation experience shall include a panel/drawer-style interaction model. Relying solely on layout reflow of the main menu is not sufficient.

Mobile navigation shall inherit menu items from the Primary Menu by default and shall support override via a dedicated mobile menu configuration when a distinct item set is required.

Category listing pages shall be indexable by default. Tag listing pages shall be configurable, defaulting to not indexed. Tag pages shall exist regardless of indexability and shall emit noindex directives rather than returning 404.

The content system shall support media embeds, with first-class support for YouTube embeds.

The system shall provide Similar/Related Items content blocks for content pages.

The system shall generate RSS and/or Atom feeds. Content shall be able to exclude itself from generated feeds.

The theme shall provide a PostShare component that uses the Web Share API for native sharing with clipboard copy as the fallback for unsupported browsers.

Button components shall support Primary, Outline, Secondary, Secondary Outline, Tertiary, Tertiary Outline, Neutral, Inverted, On Primary, On Secondary, and On Tertiary visual variations. Outline variations represent hollow/ghost treatments reusing their matching action token family. Contextual on-* variants are designed for use on matching brand-colored surfaces. A documented semantic-token override escape hatch allows rare one-off treatments using semantic token references. Per-instance border-radius is controlled via Tailwind utility classes on class, not a dedicated prop.

The footer copyright notice shall automatically reflect the current year.

The theme shall provide a configurable social icon system. Each social icon entry shall define an icon name and destination URL. The system shall be reusable across components and layouts beyond the footer.

Content shall support narrow, default, wide, and full alignment modes. Components shall respect these alignment rules.

The theme shall provide first-class structured data support for Organization, WebPage, Article, FAQPage, BreadcrumbList, and LocalBusiness schema types.

Open Graph images shall be generated using content-driven inputs (e.g., page title, description, or configured template) with content-level overrides available.

The search entry point (REQ-00163) shall be upgraded to a functional search modal dialog that allows users to search site content without navigating away from the current page.

Trailing slash enforcement behavior shall be controllable from a single configuration value such that enabling or disabling it does not require manual edits in multiple files.

The theme shall provide a complete SEO <head> system with site-level defaults from site.ts and per-page frontmatter override support, covering: <title>, <meta name="description">, <meta name="author">, Open Graph tags (og:title, og:description, og:image, og:url), and Twitter Card tags, wired into BaseLayout.astro or a dedicated SEOHead.astro component.

The canonical site URL shall be defined once in site.ts and used as the default for all URL-dependent outputs (sitemap, canonical tags, Open Graph metadata), with environment variables serving only as override mechanisms.

The system shall support reusable markdown content fragments via a unified fragments collection that supersedes the original page-fragments collection, with core/site shadow support.

The system shall provide a preview route that renders any content entry (including drafts) in full page context, accessible only in development or via an authenticated surface, and excluded from sitemap and robots outputs.

The theme shall provide a sitewide search system that indexes published content and returns relevant results to power the search modal experience (REQ-00199).

The system shall provide the C5 section baseline set (`Hero`, `CallToAction`, `InfoCards`, `FeatureGrid`, `Testimonials`) as reusable section components composed from shared primitives.

The theme documentation system (collection, routes, sidebar, requirements browser) shall be disableable via site configuration, with all related routes, navigation links, and build output suppressed when disabled.

The theme shall provide a shared Docs Kit (schema factory, generic sidebar navigation, parameterized related-docs resolution) that child sites can use to create custom documentation collections without duplicating theme-docs internals.

The theme shall rewrite file-relative markdown links targeting .md/.mdx files to their canonical route URLs at build time, so authors can use natural inter-document linking across routed content collections.

YouTube embeds shall use a click-to-load facade pattern with build-time cached thumbnail images to prevent third-party data transfer before user interaction.

Media embed components shall degrade gracefully without JavaScript, providing direct links to the embedded content as fallback.

The image resilience system shall substitute a site-configurable fallback image for broken image elements at runtime, with an opt-out mechanism (data-no-fallback attribute) for images that should not receive fallback treatment and infinite-loop prevention for fallback image failures.

Redirect execution shall preserve query parameters from the original request URL, passing them through to the target URL by default.

Infinite loading shall announce newly loaded content via ARIA live regions so assistive technology users are informed of additions without losing reading context.

The lightbox shall integrate with markdown content via a build-time rehype plugin that wraps eligible images in lightbox-enabled links, enabling lightbox behavior without manual markup in content files.

The lightbox shall support gallery grouping via data attributes, keyboard navigation (arrow keys for gallery traversal, Escape to close), and touch swipe gestures for mobile navigation.

The site header shall support configurable scroll behavior modes — static (default), CSS sticky, and scroll-up (hides on scroll down, reveals on scroll up) — selectable via site configuration (HeaderConfig).

The theme mode switcher shall support three presentation variants — icon toggle (cycling light/dark/system), select dropdown (explicit mode selection), and disabled (no UI) — selectable via site configuration.

Client-side filtering and pagination on listing pages shall synchronize state with URL query parameters, enabling shareable and bookmarkable filtered views with browser back/forward navigation support.

The search modal shall be activatable via Cmd/Ctrl+K keyboard shortcut, with the shortcut suppressed when focus is in form inputs, textareas, or contenteditable elements.

A standalone search page (/search/) shall be provided as a full-page search interface with URL state via query parameter (?q=), scoped to pages and articles collections, and marked noindex to prevent search engine indexing of search result pages.

Search interactions shall emit a defined event taxonomy (search_opened, search_submitted, search_results_viewed, search_result_clicked, search_no_results) routed through the analytics trackEvent system, with privacy-safe payloads (no raw query text; use queryLength, resultCount, resultIndex).

All forms collecting personal data shall include a required GDPR consent checkbox linking to the site's privacy policy URL, preventing submission without explicit consent.

Forms shall render as valid, accessible HTML without JavaScript. A noscript message shall inform users that JavaScript is required for submission. Native HTML constraints (required, type, minlength) shall provide first-line validation before client-side vanilla JS enhancement.

An Accordion component shall be provided with single-expand behavior, configurable default-open item (for CLS prevention), heading level control, reduced-motion support, and an FAQ variant that emits FAQPage structured data via the FAQSchema component.

A Tabs component shall be provided with horizontal and vertical orientation support, WAI-ARIA tabs pattern compliance via vanilla JS, and keyboard navigation (arrow keys for tab selection, Home/End for first/last).

A Tooltip component shall be provided with hover and focus triggers, role="tooltip" semantics, aria-describedby association between trigger and tooltip, Escape key to dismiss, and reduced-motion support for show/hide transitions.

A CopyButton component shall be provided for one-click clipboard copying with visual success feedback (icon swap with auto-revert after timeout), keyboard accessibility, and screen reader announcement of the copied state.

A consent revocation mechanism (ConsentReset) shall be provided that clears consent state from localStorage, removes known analytics cookies (configurable prefix list), disables event tracking for the remainder of the session, and triggers a page reload to ensure a clean runtime state.

Site configuration shall support custom analytics snippet injection (script URL or inline code, head or body-end location, unique id for deduplication) with the same consent-gating rules as built-in GTM/GA4 providers.

In development mode (import.meta.env.DEV), analytics scripts shall not be injected into the page and trackEvent calls shall log to console.debug instead of dispatching to the dataLayer, preventing dev activity from polluting production analytics.

A Drawer primitive shall be provided as a reusable slide-in overlay with configurable position (left, right, full-width), focus trapping, scroll locking, ESC and backdrop-click close, and reduced-motion support, serving as the shared foundation for mobile menu, search modal, and other overlay patterns.

Article listing pages shall display entries as structured cards showing title, publication date, category link, tag badges, and description excerpt, composed into a responsive grid layout.

Article detail pages shall provide previous/next navigation links to adjacent articles in the collection, ordered by publication date.

Content detail pages shall support a RelatedContent section displaying links to related pages or articles, driven by frontmatter configuration (relatedDocs field).

Form submission UX shall implement hybrid status feedback: replace the entire form with a success message on successful submission; display field-level error messages inline on validation failure, keeping the form visible for correction.

Content collections shall support an optional linkedRoute frontmatter field that associates a metadata-only content entry with a static .astro page route, enabling programmatic discovery of static pages via getCollection() without requiring those pages to use file-based content routing.

The theme shall provide a scroll-reveal animation utility that animates elements as they enter the viewport, with named presets for common entrance patterns (fade, slide, scale variants) and support for custom keyframes.

The theme shall set a .dark class on the document element alongside data-theme so that Tailwind ecosystem libraries (Starwind, Flowbite, shadcn/ui, DaisyUI) can detect dark mode without adapter code.

The theme shall provide an optional git-based CMS (Sveltia CMS) for browser-based editing of pages, articles, and fragments. The CMS shall be disabled by default with zero build cost when off.

The theme shall provide layout and content components covering standard content block patterns (separator, button group, columns, media-text, pullquote, reading time, table, gallery, masonry gallery, cover, timeline).

Client-side JavaScript usage shall be minimized while preserving functional richness.

Theme tokens shall maintain WCAG 2.2 AA contrast conformance.

Motion behavior shall respect reduced motion preferences.

Modal/lightbox components shall implement focus trapping and restoration.

Transient interactive UI shall restore focus upon dismissal.

The Back to Top control shall be accessible via keyboard and assistive technologies.

Content rendering failures shall degrade gracefully.

The theme shall conform to WCAG 2.2 Level AA.

Reduced motion preferences shall be respected.

Interactive targets shall meet minimum size guidelines.

Interactive documentation and requirements catalog interfaces shall provide accessible interaction patterns, including keyboard navigation and assistive technology support for filtering and control elements.

GDPR compliance mechanisms shall be supported.

CCPA compliance mechanisms shall be supported.

Component and token changes shall be verified across theme modes.

The theme shall support modern browser versions.

Lighthouse targets shall be soft goals with 90+ preferred.

Font loading strategies shall minimize layout shift.

Primary navigation and submenu controls shall be keyboard-operable with deterministic focus management and correct ARIA state announcements.

Authors shall be shielded from direct Tailwind utility class usage where reasonable. Content authoring surfaces shall not require knowledge of the underlying styling framework.

The system shall include automated tests covering critical user journeys.

The Pagefind search library shall be lazy-loaded on first search interaction (modal open), not at page load, to avoid impacting initial page weight and loading performance.

Form endpoints shall enforce rate limiting per client IP address, with configurable thresholds (default: 5 submissions per 15 minutes) and adapter-aware IP resolution supporting reverse proxy and CDN headers (X-Forwarded-For, CF-Connecting-IP, X-Real-IP).

Authenticated/member-only sections may be supported where needed; highly app-like authenticated product experiences remain out of scope for the v1 baseline.

Internationalization shall not be required for the initial release but shall not be structurally precluded.

Hybrid rendering activation shall be explicit and deterministic (config or frontmatter driven), not inferred implicitly.

Theme switching shall be implemented via document-level class or attribute changes.

Persisted theme preference storage shall be implementation-agnostic and replaceable without affecting component contracts.

All data-driven views shall define deterministic empty and error states.

Infinite loading shall be a progressive enhancement layered on canonical paginated URLs.

The theme shall use a semantic design token system.

The theme shall implement a CSS variable-driven token system.

Color definitions shall use OKLCH where practical.

The token system shall support Primary, Secondary, and Tertiary brand color roles.

The Tertiary brand color shall be restricted to decorative/emphasis usage.

The theme shall define an allowed semantic color palette.

Brand color roles shall include variants for emphasis and subtle states.

The theme shall define radii presets.

The theme shall define shadow presets.

Components shall use presets rather than ad-hoc values.

Styling decisions shall resolve from tokens or presets.

Utility class usage shall not bypass semantic token constraints.

Interactive states shall resolve from semantic tokens.

Components shall resolve styling from semantic design tokens rather than raw color values.

Dark mode behavior shall be driven by semantic token value swapping rather than component-level per-mode styling overrides.

Dark mode and all mode differences shall be expressed through semantic token value swapping; component-level per-mode styling overrides shall be exceptional and explicitly documented.

Components shall encapsulate styling and behavior.

Framework-free components are preferred.

Components shall expose stable public APIs.

Markdown heading levels shall be programmatically adjusted for semantic correctness.

Modified time shall resolve from a deterministic source hierarchy.

Figures and captions shall follow consistent semantic patterns.

Form validation shall implement correct ARIA relationships and semantics.

Accessibility requirements apply equally to theme UI, content UI, and documentation/requirements UI.

Required scripts shall execute regardless of consent state.

The theme shall function as a Parent Theme equivalent.

Theme overrides shall survive upgrades.

Theme overrides shall survive upgrades and updates shall flow downstream without breaking customizations; upgrade compatibility is a mutual contract between upstream and downstream.

Themes shall be distributable across repositories.

The system shall define a canonical requirements data model.

Requirements definitions shall be normative over explanatory documentation.

External content sources shall not alter requirement semantics.

The system shall define deterministic enforcement boundaries separating hard failures from warnings.

Overrides shall not break token completeness, accessibility invariants, or routing/metadata invariants.

Provider-specific infrastructure shall not be required.

CDN-backed deployments shall be supported.

Third-party font CDNs shall not be assumed.

Documentation routes shall use slug-based canonical URLs (for example, `/theme-docs/<slug>/`). Immutable `docId` values (format `DOC-00001`) shall remain required for internal cross-reference and traceability.

Override resolution shall follow deterministic precedence (`defaults -> theme override -> project override -> page/content`) with validation failures for same-tier key collisions.

Navigation implementation shall separate menu data contract, resolver logic, and render/layout integration responsibilities.

Menu behavior bindings shall use stable `data-*` hooks rather than style-class selectors.

Menu customization APIs shall preserve structural and behavior-critical classes/attributes, limiting overrides to documented slots or token-driven surfaces.

Tailwind utility token mappings shall resolve through documented semantic design-token aliases (for example via `@theme` / `@theme inline`) rather than raw palette literals in component/layout code.

Tailwind prose/typography plugin styling shall resolve through documented semantic prose token aliases rather than raw plugin defaults or hardcoded values in component/layout code.

Tailwind utility token mappings shall include documented semantic aliases for link, status, form, and icon roles so component/layout code does not rely on raw palette literals.

Long-form content surfaces shall use a shared token-driven prose baseline that defines heading/paragraph spacing, list marker presentation, and block-level element rhythm.

Shiki shall be the canonical code-block renderer for long-form content and preview surfaces; non-markdown sample code blocks shall use the same Shiki rendering path rather than bespoke raw `<pre><code>` styling.

Site identity constants (title, home URL, logo paths, and logo alt text) shall be defined in a single canonical configuration file (src/config/site.ts) and imported by components; values shall not be hard-coded inline.

External link detection and announcement injection shall be applied automatically to all prose content rendered through the long-form content pipeline (articles, docs, page-content layouts), without requiring authors to manually annotate individual links.

The configuration override hierarchy shall follow a deterministic four-layer precedence: Parent defaults -> Child theme overrides -> Content frontmatter overrides -> Runtime user preferences. Runtime preferences are limited to theme mode and consent state.

The system shall support environment-aware configuration so that behavior can differ between development and production builds.

The spacing scale shall be finite and token-driven. Components and layouts shall avoid hard-coded spacing values outside the defined scale.

Semantic z-index tokens shall be defined for layered UI contexts including dropdown, sticky, overlay, modal, and toast layers. Components shall resolve stacking from these tokens rather than ad-hoc z-index values.

The theme shall define standardized layout width constraints. At minimum a content width, a wide width, and a prose/reading width shall be defined as canonical layout tokens.

The theme shall define standardized vertical spacing rules between content blocks and around headings, lists, and tables within long-form content.

The theme shall follow Semantic Versioning (SemVer). Minor versions shall be backwards-compatible. Major versions may contain breaking changes, which shall be documented with migration notes.

Collection-driven routing shall be required for entries under `src/content/pages/`; this requirement does not prohibit additional public route families backed by the `articles` collection, `docs` collection, or static `.astro` pages.

Page, article-detail, and docs-detail routes shall render heading-band content in the `PageGridLayout` `subheader` slot using `Hero`; without actions or image, `Hero` renders as a compact page-title band.

A generic Embed component shall apply restrictive iframe defaults (sandbox with allow-scripts and allow-same-origin only, no allow attributes by default, no allowfullscreen by default, referrerpolicy of strict-origin-when-cross-origin or stricter) with explicit opt-in escape hatches for permissions.

Content validation shall use a pluggable static rules framework that supports rule registration via configuration, per-rule severity levels, and extensibility for new rules without modifying the framework core.

Static rule violations shall support a dual exception model: inline source comments for localized suppressions and a centralized TypeScript manifest for cross-cutting exceptions. Both mechanisms shall require a documented reason for traceability.

Infinite loading integration shall use stable data-attribute DOM contracts (data-article-grid, data-docs-grid) as the interface between server-rendered HTML and client-side progressive enhancement logic, avoiding brittle structural selectors.

Lightbox enablement shall resolve through a three-level configuration hierarchy: content frontmatter override, collection default, system default (false), allowing per-page, per-collection, and system-wide control.

Form submissions shall pass through a layered server-side validation pipeline in this order: honeypot check, rate limiting, CAPTCHA verification, field validation, provider dispatch. Each layer shall return a typed JSON response with appropriate HTTP status code (200 success, 422 validation error, 429 rate limit, 403 authorization failure, 500 provider error).

Server-side form handling shall use pluggable provider adapter interfaces for email delivery (EmailProvider) and newsletter subscription (NewsletterProvider), enabling backend substitution without form component changes. In development, providers shall fall back to console logging when credentials are absent; in production, missing credentials shall cause requests to fail closed.

The analytics system shall define a shared event taxonomy (page_view, cta_click, form_submit, search_submitted, search_result_clicked) dispatched via a centralized trackEvent function that routes to the dataLayer in GTM format. Event payloads shall follow privacy-safe conventions (no PII, no raw search query text).

Alpine.js shall be loaded via a custom deferred integration that initializes Alpine only after DOM ready, avoiding the bundle overhead and eager initialization of the official @astrojs/alpinejs integration.

Critical CSS delivery shall use a preload/swap pattern (link rel="preload" as="style" with onload swap) rather than build-time CSS inlining tools, avoiding complex build-time CSS parsing dependencies while maintaining above-the-fold rendering performance.

Typography shall use a fluid type scale based on CSS clamp() functions, generated from a declarative token configuration file, ensuring smooth scaling between defined viewport breakpoints without requiring media query breakpoints.

Cross-component communication shall use named custom DOM events dispatched on the window object (e.g., theme-changed, search:open, listbox-change) rather than direct component coupling. Event names and payload shapes shall be treated as public API contracts.

External link indicators (icon and screen-reader announcement) shall be automatically applied only to links rendered through the markdown/MDX content pipeline. Component-rendered and navigation links shall use the ExternalLink component for explicit opt-in.

In multi-column page layouts, DOM order shall reflect logical reading and tab order (e.g., sidebar/TOC before main content). CSS Grid shall be used to decouple visual layout from DOM order. Article metadata shall be placed in the page layout's main-header slot.

Configuration values consumed by build-time plugins (rehype, remark) in astro.config.mjs shall be defined independently of site.ts, because Vite path aliases are not available during Astro config parsing. Site overrides affecting plugin behavior shall be synchronized in both astro.config.mjs and site.ts.

Motion Mini (motion/mini) shall be the approved animation engine for WAAPI-based animations, providing a reduced-motion-aware animate() wrapper.

Contrast conformance shall be validated via automated accessibility audits against rendered showcase pages.

Frontmatter validation shall be enforced.

Draft content shall be excluded from sitemap and indexing outputs.

Draft content shall imply noindex/nofollow directives.

Pages with missing titles shall fail builds.

Missing alternative text shall generate warnings.

Potential color contrast violations shall generate warnings.

Metadata requirements shall apply to all pages.

Build processes shall fail for violations that produce structurally invalid outputs, invalid schemas, or broken routing/metadata invariants.

Validation processes shall generate warnings for non-critical quality issues without blocking builds.

Build processes shall fail for violations that would ship inaccessible interactive UI when deterministically detectable.

Missing alt text findings shall generate warnings rather than hard failures, with a documented exception path.

Content entries in `pages`, `articles`, and `docs` collections shall require a non-empty `description` field.

Fragment references used by routed content shall resolve to existing fragment IDs at build/validation time.

Broken internal links shall generate warnings by default; CI pipelines on production-targeted branches may be configured to treat them as hard failures.

Broken link detection shall validate both route existence and fragment anchors against a pre-build route inventory that does not depend on astro:content availability, using slug generation compatible with Astro's github-slugger behavior.

When both the global redirects manifest and content-level redirectFrom define redirects for overlapping source paths, the system shall detect conflicts and surface them as build-time errors for manifest-level collisions or warnings when frontmatter overrides manifest entries.

Token override declarations in site style files shall be validated by a dedicated lint tool that distinguishes structural violations (wrong-location declarations, same-tier key collisions) as hard failures from advisory findings (unknown token references, incomplete mode coverage) as warnings.

Fluid design tokens (typography, spacing) shall be generated from a declarative token configuration file via a build script (generate:tokens), with drift detection (generate:tokens:check) integrated into the validate pipeline to ensure generated CSS output stays synchronized with configuration source.

File ownership markers (// CORE-OWNED, // SITE-OWNED) in governed directories shall be validated by a lint step in the validate pipeline, ensuring all core-owned source files declare their ownership zone and site-owned directory files do not carry incorrect markers.

File ownership marker validation shall apply context-specific defaults for unmarked files: src/site/ and src/components/ are SITE-OWNED by directory (markers recommended but not required); src/pages/ with no marker defaults to SITE-OWNED (fail-safe for site customization files); src/content/ defaults to SITE-OWNED by directory convention. Core-owned directories (src/core/, src/lib/, scripts/) shall require explicit markers.

Documentation shall include user-facing, implementor, and developer layers.

Requirements displays shall follow defined grouping rules.

Documentation pages shall be canonical-first with respect to requirements.

Documentation pages containing non-normative guidance shall use Notes sections.

Documentation markup shall use semantic HTML.

Documentation updates shall be part of completion criteria.

A deployment runbook shall be maintained in the theme-docs collection covering the steps, configuration requirements, and verification checklist for deploying to a production hosting target.

Components sourced from external pattern libraries shall follow the tier-1 curated source hierarchy defined in §13 and shall document their source origin and any modifications applied, enabling traceability from component to source pattern.

Recommendation records shall capture provenance fields including promoted requirement IDs, decision date, and decision owner.

Canonical requirement lifecycle statuses shall be actively maintained to reflect current decision and implementation state.

Canonical requirements should define `dependsOn` and `appliesTo` metadata when material dependencies or documentation applicability exist.

Canonical requirements should include V1 scope tags when the requirement is explicitly in scope or deferred by the approved V1 scope definition.

Significant architectural, technology, and process decisions shall be documented as Architecture Decision Records (ADRs) and tracked in the project decisions log.

All shipped changes that affect public behavior, configuration surfaces, or component APIs shall be documented in CHANGELOG.md following the project's changelog format, with entries created as part of the merge or release process.

Multi-step implementation work shall follow the planning standard (.docs/standards/PLANNING.md), with plans stored in .docs/plans/ and archived to .docs/archive/ upon completion. Plans shall cite relevant charter sections using §N notation.

Theme-docs frontmatter order fields shall follow a banded convention: topic-indexes at 1, entry-point guides at 2–10, regular docs starting at 11 with incremental assignment, and showcases/layout-recipes starting at 800.

The contact form shall submit validated data to the Postmark HTTP API for transactional email delivery; API credentials shall not be exposed to the client.