Template Documentation

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

Overview

The Template site is a modern, sustainable web presence built on proven technologies prioritizing simplicity, performance, and maintainability. It serves as a foundational framework for web projects aligned with FOSS principles and best practices.

Key Objectives

  • Provide a beautiful, accessible web presence
  • Demonstrate sustainable architecture patterns
  • Offer a foundation for future growth
  • Maintain simplicity and clarity in design
  • Ensure optimal performance and SEO

Philosophy

The Template site is built on a philosophy of pragmatism and restraint: use the simplest appropriate tools for each job, not the fanciest.

Core Principles

  • Performance First: Fast load times, small bundles, efficient rendering
  • Accessibility Always: WCAG AA compliant, keyboard navigable, screen reader compatible
  • Simplicity Over Complexity: Minimize dependencies, maximize clarity
  • Standards-Based: Use web standards (HTML, CSS, JavaScript), not proprietary solutions
  • Maintainability: Code is for people; make it easy to understand and modify
  • FOSS-Friendly: Free, open-source software throughout the stack

Structure

The Template site follows a proven file organization pattern that scales well and makes it easy to find what you need.

File Organization

src/
├── pages/           # Route pages (auto-routed by Astro)
│   ├── index.astro
│   ├── docs.astro
│   ├── components.astro
│   ├── blocks/
│   └── pages/
├── components/      # Reusable Astro components
│   ├── layout/
│   ├── ui/
│   ├── alpine/
│   └── blocks/
├── layouts/         # Page layouts (BaseLayout, etc.)
├── styles/          # Global styles and design tokens
└── config/          # Configuration files

Technology Stack

Carefully selected technologies that provide maximum value with minimal complexity.

Frontend Framework

  • Astro 5: Static site generation with optional interactivity
  • Alpine.JS: Lightweight (15KB) for simple interactive features
  • Tailwind CSS 3: Utility-first CSS framework

Design System

  • Fluid Design Tokens: Responsive typography and spacing using CSS variables
  • Brand Colors: Blue, Hunter Green, Gold for customization
  • Component Library: 16+ production-ready components
  • Dynamic Favicon: Automatically generated in the theme's primary color, with animated transition between "SD" and "$D" every 4 seconds

Build & Deployment

  • Build Tool: Vite (via Astro)
  • Package Manager: pnpm
  • Deployment: Cloudflare Pages or similar static host

Getting Started

Development

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Preview production build
pnpm preview

Creating Pages

Create a new file in src/pages/ with a .astro extension. Astro automatically routes files to URLs.

Using Components

---
import Button from '../components/ui/Button.astro';
import Container from '../components/layout/Container.astro';
---

<Container>
  <Button variant="primary">Click Me</Button>
</Container>

Component Categories

Layout Components

  • Container - Width constraint and centering
  • Section - Vertical spacing container
  • Grid - Responsive grid system
  • Header - Site header with navigation
  • Footer - Site footer

UI Components

  • Button - Multiple variants and sizes
  • Card - Content container
  • Badge - Labels and tags
  • Alert - Notifications
  • Label - Form labels
  • Separator - Visual divider

Form Components

  • Input - Text input with multiple types
  • Textarea - Multi-line text input
  • Form - Form container

Alpine-Enhanced Components

  • ThemeSwitcherEnhanced - Theme/color dropdown

Brand Components

  • SmartDebt - Animated branded text component (Web Component)
  • More brand components coming soon (logo, etc.)

For full component documentation with props and usage examples, see /components page.

Best Practices

Building Components

  • Start with Astro: Default to Astro components for all components
  • Add Alpine if needed: Only for simple user interactions
  • Use CSS Variables: All theme colors and spacing via CSS vars
  • Include ARIA Labels: Accessibility first, always
  • Test Responsiveness: Mobile (320px), tablet (768px), desktop (1024px+)

Performance

  • Keep components focused and single-purpose
  • Minimize JavaScript; prefer CSS when possible
  • Use lazy loading for images
  • Optimize images before adding to project

Support & Resources