A modern, design-system-driven static site built with Astro, featuring a complete AI-powered development feedback loop.
Built following Vignelli's design principles:
- Semantic approach - Content separated from presentation
- Discipline - Consistent design system with 140+ tokens
- Timelessness - ITCSS architecture for maintainable CSS
- Responsibility - Accessibility-first, performance-focused
# Install dependencies
npm install
# Start development server with HMR
npm run dev
# Run tests
npm run test
# Full CI pipeline
npm run cimicrohams/
├── content/ # 📝 Content Collections (markdown)
│ ├── articles/ # Blog posts and technical guides
│ ├── docs/ # Reference documentation
│ ├── projects/ # Project documentation
│ ├── pages/ # General site pages
│ └── config.ts # Content schemas (TypeScript)
├── src/
│ ├── layouts/ # Astro layouts
│ ├── pages/ # Route files (index, [slug])
│ ├── lib/ # Error boundary, utilities
│ ├── styles/ # ITCSS CSS architecture
│ └── test/ # Vitest setup
├── playwright/ # E2E and visual regression tests
├── scripts/ # AI validation, watch feedback
├── .docker/ # CI container (Ubuntu 22.04)
├── docs/ # Project documentation
└── public/ # Static assets
Content at Root Level: The content/ directory is at the project root (not in src/) to clearly separate:
- Content (markdown, schemas) - Managed by writers/editors
- Code (components, logic) - Managed by developers
Astro automatically discovers content via a symlink at src/content → ../content. This approach enables:
- Easier content contribution (no need to navigate src/)
- Potential for content as separate git submodule
- Clear separation between content and code
See CONTENT_REORGANIZATION.md for details.
src/styles/
├── 00-settings/ # Design tokens (colors, spacing, typography)
├── 01-tools/ # Custom properties setup
├── 02-generic/ # CSS resets
├── 03-elements/ # Base HTML elements
├── 04-layouts/ # Layout primitives (Stack, Cluster, Grid, etc.)
├── 05-components/ # UI components (Card, Button, Badge, etc.)
└── 06-utilities/ # Utility classes
- OKLCH color space for perceptual uniformity
- Perfect Fourth typographic scale (1.333 ratio)
- Powers-of-2 spacing (4px base unit)
- Logical properties for i18n
- Data attributes for state (HMR-friendly)
npm run test # Watch mode
npm run test:unit # Run once
npm run test:ui # Visual UInpm run test:e2e # Run E2E tests
npm run test:visual # Visual regression only
npm run test:e2e:ui # Interactive UI modenpm run ci # lint → type-check → test → buildLocal CI that mirrors GitHub Actions:
# Build container
npm run docker:build
# Run full CI in Docker
npm run docker:test
# Or use docker-compose
docker-compose -f .docker/docker-compose.yml up cicat > content/articles/my-article.md << 'EOF'
---
title: "My Article Title"
description: "Brief description"
author: "Your Name"
date: 2025-10-21
tags: ["ham-radio", "tutorial"]
featured: true
---
Your content here...
EOFcat > content/docs/my-doc.md << 'EOF'
---
title: "Documentation Title"
description: "What this documents"
order: 10
section: "Getting Started"
---
Documentation content...
EOFcat > content/projects/my-project.md << 'EOF'
---
title: "Project Name"
description: "What it does"
status: "active"
technologies: ["Python", "Raspberry Pi"]
repository: "https://github.com/..."
---
Project details...
EOF# Manual validation
node scripts/ai-validate.js
# Validates:
# - Design system consistency (no magic numbers)
# - Accessibility (alt text, ARIA labels)
# - Performance (bundle size)
# - Code quality (type checking)# Terminal 1: Dev server
npm run dev
# Terminal 2: Watch mode with auto-validation
node scripts/watch-feedback.js# Check all packages are at October 2025 versions
npm run verify| Command | Description |
|---|---|
npm run dev |
Start dev server (localhost:4321) |
npm run build |
Build static site to dist/ |
npm run preview |
Preview production build |
npm test |
Run Vitest in watch mode |
npm run test:e2e |
Run Playwright E2E tests |
npm run test:visual |
Visual regression tests only |
npm run lint |
Check ESLint errors |
npm run lint:fix |
Auto-fix ESLint issues |
npm run type-check |
TypeScript type checking |
npm run verify |
Verify package versions |
npm run ci |
Full CI pipeline |
npm run docker:build |
Build Docker CI image |
npm run docker:test |
Run CI in Docker |
Development includes a sophisticated error boundary that:
- Catches runtime errors in browser
- Reports to Vite dev server over WebSocket
- Shows detailed overlay with source maps
- Includes component stack traces
Access via browser console:
window.__errorBoundary.getErrors() // View captured errors
window.__errorBoundary.clearErrors() // Clear error log- START_HERE.md - Getting started guide
- PROJECT_SUMMARY.md - Architecture overview
- FEEDBACK_LOOP.md - AI-powered development workflow
- VERSION_AUDIT.md - Package versions (October 2025)
- CONTRIBUTING.md - Content contribution guide
Push to main branch triggers GitHub Actions:
Build → Deploy to gh-pagesSite available at: https://microhams.net
npm run build
# Upload dist/ to your hosting providerOctober 2025 Compatible ✅
| Technology | Version | Purpose |
|---|---|---|
| Astro | 5.14.8 | Static site generator |
| Vite | 7.1.11 | Build tool & HMR |
| Vitest | 3.2.4 | Unit testing |
| Playwright | 1.56.1 | E2E & visual testing |
| TypeScript | 5.9.3 | Type safety |
| ESLint | 9.38.0 | Code linting |
| Prettier | 3.6.2 | Code formatting |
| Docker | Ubuntu 22.04 + Node 20 | Local CI |
- Fork the repository
- Create a feature branch
- Add content or fix bugs
- Run full CI:
npm run ci - Submit pull request
See CONTRIBUTING.md for detailed guidelines.
[Specify your license here]
Built with ❤️ using Vignelli's design principles
Last updated: October 21, 2025