MVP Track Guide

MVP Track - Implementation Path

Fast-track to production with essential features only

Overview

This track focuses on content presentation with zero JavaScript, manual testing, and essential features only.

Track Philosophy

Ship Fast: Get to production quickly
Stay Simple: Avoid premature optimization
Focus on Content: Let your work speak
Embrace Constraints: Zero JS = Zero JS problems

Best For

Personal portfolios
Small business websites
Blogs and content sites
Proof of concepts
Learning projects
Fast launches

Success Metrics

Metric	Target	Why It Matters
Time to Launch	As fast as possible	Fast feedback loop
Lighthouse Score	95+	Performance = UX
Page Weight	< 200KB	Fast on slow connections
JavaScript Size	0KB	No bundle = no problems
Complexity	Minimal	Easy to maintain

Phase Implementation Guide

Phase 0: Foundation

💡 Starter Template: All foundation decisions are pre-configured in this template

MVP Decisions:

Framework: Astro (latest stable)
Styling: Tailwind CSS
JavaScript: None (HTML + CSS only)
Package Manager: pnpm
Deployment: GitHub Pages (ships with the starter's deploy.yml)
Repository: GitHub

📖 See Also: ADR-000: Starter Decisions for detailed rationale

Skip These:

Complex build tools
State management
API integrations
Advanced TypeScript configs

Phase 1: Content Architecture

MVP Approach:

// Minimal content structure
blog/
  - title, date, description, content
projects/
  - title, description, image, link
pages/
  - about, contact

Skip These:

Complex taxonomies
Multiple author support
Advanced content relationships
External data sources

Phase 2: Design System (1 day)

MVP Tokens:

/* Keep it simple — these variables are compiled from tokens/base.json
   and tokens/semantic.json (pnpm run tokens:build); never hardcode
   hex or spacing values in components. Color tokens are HSL channel
   triplets, so consume them via hsl(var(--token)) */
:root {
  /* 3-4 semantic colors max, aliased to base tokens */
  --color-text: var(--color-slate-900);
  --color-background: var(--color-slate-50);
  --color-primary: var(--color-primary-600);
  --color-muted: var(--color-slate-500);

  /* 3-4 spacing steps */
  --space-sm: var(--spacing-2);
  --space-md: var(--spacing-4);
  --space-lg: var(--spacing-8);
  --space-xl: var(--spacing-16);

  /* System fonts */
  --font-sans: system-ui, sans-serif;
  --font-mono: monospace;
}

Skip These:

Complex color schemes
Multiple font families
Elaborate animations
Advanced theming

Phase 3: Tooling (4 hours)

MVP Setup:

# Simple setup script
pnpm install
pnpm run build

Skip These:

Complex CI/CD pipelines
Extensive linting rules
Code coverage
Advanced Git hooks

Phase 4: Skeleton (2 days)

MVP Layout:

Don’t hand-roll a <head> — the starter ships src/layouts/BaseLayout.astro with SEO tags, Header, Footer, and skip link already wired up. Wrap every page in it:

---
import BaseLayout from '@/layouts/BaseLayout.astro';
---

<BaseLayout title="About" description="Who I am and what I do">
  <h1>About</h1>
  <p>Your content here.</p>
</BaseLayout>

Navigation lives in src/content/navigation/header.json; footer links live in src/config.ts.

Phase 5: Components (1 day)

💡 Starter Template: Essential components are pre-built in src/components/ (organized as atoms/, molecules/, and structural/)

MVP Component List:

Button.astro → Available at /src/components/atoms/Button.astro

---
const { href, variant = 'primary' } = Astro.props;
// Token-backed utility classes — never hardcode colors like bg-blue-600
const classes = {
  primary: 'bg-primary-600 text-primary-foreground hover:bg-primary-700',
  secondary: 'bg-surface text-foreground border border-border-emphasis hover:bg-background'
};
---

<a href={href} class={`px-4 py-2 rounded ${classes[variant]}`}>
  <slot />
</a>

Card.astro → Available at /src/components/molecules/Card.astro

Props are { class?: string; animated?: boolean } — content goes in the slot (the card ships without padding, so add it via class):

---
import Card from '@/components/molecules/Card.astro';
---

<Card class="p-6" animated>
  <h3 class="text-xl font-bold mb-2">Project One</h3>
  <p class="text-muted-foreground mb-4">What it is and why it matters.</p>
  <a href="/projects/one/" class="text-primary-600 hover:underline">Learn more →</a>
</Card>

Section.astro → Available at /src/components/structural/Section.astro

Props are { class?, id?, fullHeight?, ariaLabel?, ariaLabelledBy? } with a fixed vertical rhythm (py-16 sm:py-24 lg:py-32) — there is no size prop, and width constraints are yours to add inside the slot:
```
---
import Section from '@/components/structural/Section.astro';
---

<Section ariaLabel="Projects">
  <div class="max-w-4xl mx-auto px-4">
    <h2 class="text-3xl font-bold mb-8">Projects</h2>
    
  </div>
</Section>
```

Skip These Components:

Modals
Tabs
Accordions
Carousels
Complex forms
Interactive widgets

Phase 6: Sections (1 day)

MVP Sections:

Hero Section

<Section ariaLabel="Intro">
  <div class="max-w-4xl mx-auto px-4">
    <h1 class="text-5xl font-bold">Your Name</h1>
    <p class="text-xl text-muted-foreground mt-4">Developer, Writer, Creator</p>
  </div>
</Section>

Project List

<Section ariaLabel="Projects">
  <div class="max-w-4xl mx-auto px-4">
    <h2 class="text-3xl font-bold mb-8">Projects</h2>
    <div class="grid md:grid-cols-2 gap-8">
      <Card class="p-6">
        <h3 class="text-xl font-bold mb-2">Project One</h3>
        <p class="text-muted-foreground mb-4">...</p>
      </Card>
      <Card class="p-6">
        <h3 class="text-xl font-bold mb-2">Project Two</h3>
        <p class="text-muted-foreground mb-4">...</p>
      </Card>
    </div>
  </div>
</Section>

Phase 7: Content (3 days)

MVP SEO:

<meta name="description" content={description}>
<meta property="og:title" content={title}>
<meta property="og:description" content={description}>

Phase 8: QA

MVP Testing Checklist:

## Manual Testing Checklist

### Functionality
- [ ] All links work
- [ ] Forms submit (if any)
- [ ] Images load
- [ ] No console errors

### Responsive
- [ ] Mobile (320px)
- [ ] Tablet (768px)
- [ ] Desktop (1200px)

### Browsers
- [ ] Chrome
- [ ] Firefox
- [ ] Safari

### Accessibility
- [ ] Keyboard navigation works
- [ ] Alt text for all images
- [ ] Sufficient color contrast

Phase 9: Performance (4 hours)

MVP Performance Checklist:

Optimize Images (use TinyPNG)
Minify CSS (Astro does this)
Check Lighthouse (aim for 95+)

Phase 10: Deployment (2 hours)

MVP Deployment:

Push to GitHub
Enable GitHub Pages (Settings → Pages → Source: GitHub Actions)
Configure domain
Auto-deploy is already wired — the shipped .github/workflows/deploy.yml deploys every push to master

# That's it!
git push origin master
# The shipped deploy.yml handles the rest

Phase 11: Documentation (2 hours)

MVP Documentation:

# Project Name

## Overview
What this site is about.

## Development
```bash
pnpm install
pnpm dev

Deployment

Pushes to master auto-deploy to GitHub Pages (.github/workflows/deploy.yml).

Content Management

Edit markdown files in src/content/.

Phase 12: Post-Launch (2 hours)

MVP Monitoring:

Set up Cloudflare Analytics
Create Google Search Console
Weekly manual check
Monthly content update

What NOT to Build

Avoid These Patterns

No Client-Side Routing
- Use regular links
- Let the browser handle it
No State Management
- No stores
- No context
- No props drilling
No Build Complexity
- No custom webpack
- No complex plugins
- No build optimization
No Interactive Components
- Use CSS hover states
- Form submissions are fine
- Details/summary for accordions

CSS-Only Solutions

/* Dropdown with pure CSS */
.dropdown:hover .dropdown-content {
  display: block;
}

/* Mobile menu with checkbox hack */
#menu-toggle:checked ~ .mobile-menu {
  display: block;
}

/* Smooth scroll */
html {
  scroll-behavior: smooth;
}

/* Print styles */
@media print {
  nav, footer { display: none; }
}

Time Allocation

Week 1: Foundation

Day 1: Setup & Architecture
Day 2: Design System & Tooling
Day 3-4: Layout & Components
Day 5: Sections & Pages

Week 2: Content & Launch

Day 6-8: Content Creation
Day 9: QA & Performance
Day 10: Deployment & Launch

Week 3: Polish (Optional)

Refine content
Add more pages
Optimize images
Gather feedback

Cost Analysis

Item	Cost	Notes
Domain	$12/year	Use Cloudflare
Hosting	$0	GitHub Pages (shipped workflow)
Email	$0	Use mailto:
Analytics	$0	Cloudflare Analytics
Total	$12/year	Just the domain

MVP to Showcase Migration

When ready to upgrade:

Keep the Same Structure
- Don’t rewrite
- Enhance incrementally
Add Features Gradually
- One component at a time
- Test each addition
Introduce JavaScript Carefully
- Start with View Transitions
- Add islands where needed
Enhance Testing
- Add Playwright
- Implement visual regression

Success Stories

Case Study 1: Developer Portfolio

Timeline: 10 days
Pages: 5
Lighthouse: 100/100
Result: 3 job interviews

Case Study 2: Local Business

Timeline: 2 weeks
Pages: 8
Cost: $12 (domain only)
Result: 40% more inquiries

Case Study 3: Personal Blog

Timeline: 1 week
Posts: 10 migrated
Performance: 200ms load time
Result: 2x reader engagement

Common Pitfalls

1. Scope Creep

Problem: “Just one more feature” Solution: Write features down for v2

2. Perfection Paralysis

Problem: Endless tweaking Solution: Ship at 80% perfect

3. Framework FOMO

Problem: “Should I use React?” Solution: No. Ship first.

4. Design Paralysis

Problem: Endless design iterations Solution: Use system fonts and move on

MVP Mantras

“Done is better than perfect”
“Ship early, iterate often”
“Content over chrome”
“Zero JavaScript, zero problems”
“If it works, ship it”

Ready to Start?

# Your MVP journey begins now
pnpm create astro@latest my-mvp-site --template clownware/astro-performance-starter
cd my-mvp-site
pnpm install
pnpm dev
# You're already 1% done!

Remember: The goal is to launch, not to build the perfect site. Every day you don’t ship is a day you’re not learning from real users. Ship it! 🚀