Template Documentation

Comprehensive guide to the Template site architecture, philosophy, and components.

Overview

This is a multi-site Astro monorepo with shared component library. The Template site serves as the master component library that brand sites (like SmartDebtCoach.com) consume.

The architecture prioritizes component reusability, brand flexibility, and developer experience. All components are built in the Template site first, then imported by brand sites as needed. This ensures consistency across sites while allowing brand-specific customization through design tokens.

Project Structure

The monorepo is organized into three main areas:

Sites

  • Template - Master component library and showcase (this site)
  • sdc.com - SmartDebtCoach.com production site

Packages

  • design-tokens - Shared design system with color generation and typography utilities
  • components - Reusable component packages

Brand Assets

  • src/brand/sd - SmartDebt brand assets (logos, favicons)
  • src/brand/ts - TalbotStevens brand assets

This structure allows multiple brand sites to share components while maintaining distinct visual identities through brand-specific design tokens and assets.

Technology Stack

Carefully selected technologies for maximum value with minimal complexity.

Frontend

  • Astro 5 - Static site generation with zero JS by default
  • Alpine.JS - Lightweight interactivity for dropdowns, modals, and tabs
  • Tailwind CSS 3.4 - Utility-first CSS framework
  • TypeScript - Type safety and better developer experience

Testing

  • Playwright - E2E testing across 7 projects (3 desktop + 4 mobile)
  • Vitest - Unit testing for design tokens and utilities
  • axe-core - Automated accessibility testing (WCAG AA compliance)

Development

  • pnpm - Fast, efficient package manager with workspace support
  • ESLint + Prettier - Code quality and formatting
  • Husky + lint-staged - Pre-commit hooks for quality gates

Deployment

  • Cloudflare Pages - Fast global CDN with edge functions
  • Wrangler - Cloudflare deployment CLI

Design System

The design system uses a token-based approach for consistency and brand flexibility. All design decisions are encoded as CSS custom properties that can be overridden per brand.

Color System

Colors use the OKLCH color space for perceptually uniform brightness and saturation. Each brand defines anchor colors in RGB, which are automatically converted to 10-step OKLCH palettes with proper lightness curves for both light and dark modes.

Typography

Uses Inter Variable font with fluid scaling via CSS clamp(). Font sizes adapt smoothly between viewport sizes without breakpoints. Weights: 800 (headings), 600 (subheadings), 400 (body).

Spacing

Fluid spacing system with 8px base unit. All spacing uses CSS custom properties that scale with viewport size for responsive layouts without media queries.

Component Library

50+ production-ready components organized by category. All components are built with Astro for zero JavaScript overhead by default, with Alpine.JS added only when interactivity is required.

Component Categories

  • Hero Blocks - 5 variants for homepages, landing pages, and about pages
  • CTA Blocks - 4 conversion-focused variants including newsletter signup
  • Forms - Contact, newsletter, multi-step, calculator, and lead magnet forms
  • UI Primitives - Buttons, badges, cards, modals, dropdowns, tabs, accordions
  • Brand Components - Logos, favicons, testimonials, stats, reviews
  • Layout - Container, section, grid, header, footer, navigation

For full documentation and live examples, see the Component Showcase page.

Testing Strategy

Comprehensive testing ensures components work across devices, browsers, and accessibility requirements. All tests run locally with no CI/CD service required.

Test Projects (7 total)

Desktop: Chromium, Firefox, Webkit (1280x720)

Mobile: iPad Pro, iPad Air, iPhone 14 Pro, Samsung Galaxy S21

Test Layers

  • Unit Tests - Design token generation and utilities (Vitest)
  • E2E Tests - Component behavior and responsive layouts (Playwright)
  • Accessibility - WCAG AA compliance via axe-core
  • Visual Regression - Screenshot comparisons for UI consistency
  • Dark Mode - Theme switching and color token verification

Quality Gates

Pre-commit hooks run ESLint and Prettier on changed files. Pre-push hooks run unit tests, TypeScript checks, and Chromium E2E tests. Full test suite (all 7 projects) runs on demand.

Development Workflow

All development commands run from the site directory (e.g., sites/Template/).

Common Commands

  • pnpm dev - Start development server on localhost:4321
  • pnpm build - Build for production
  • pnpm test - TypeScript check (astro check)
  • pnpm test:e2e - Run Playwright E2E tests

Design System Commands

Run from site directory:

  • pnpm colors:sd - Generate SmartDebt color tokens
  • pnpm colors:ts - Generate TalbotStevens color tokens

Run from monorepo root:

  • pnpm favicon:sd - Generate SmartDebt favicon
  • pnpm favicon:ts - Generate TalbotStevens favicon

Resources