astro-performance-starter/
│ │ ├── ci.yml # CI — quality gates (lint, types, tests)
│ │ ├── deploy.yml # Deploy to GitHub Pages (shipped deployment)
│ │ ├── lighthouse.yml # Lighthouse CI (desktop + mobile floors)
│ │ ├── link-check.yml # Markdown link check
│ │ ├── mutation.yml # Stryker mutation testing
│ │ ├── release.yml # Release automation
│ │ └── versions-sync.yml # Keeps versions.json in sync (ADR-061)
│ │ └── feature-request.md
│ ├── PULL_REQUEST_TEMPLATE.md
├── .claude/ # Layered AI constitution (ADR-036)
│ ├── agents/ # Agent definitions
│ ├── roles/ # Role playbooks (ADR-038)
│ ├── skills/ # Project skills
│ ├── engineering.md, stack.md, workflow.md
│ ├── launch.json # Dev-server launch config
│ ├── pre-commit # lint-staged
│ ├── commit-msg # commitlint
│ └── enforcement.config.json # Halt-on-violation checks (ADR-064)
│ ├── README.md # Docs overview & roadmap status
│ ├── personalization-guide.md
│ ├── 2026-06_design_system/ # Design-system brief (brand, motion, tokens, wiring)
│ ├── adr/ # Architecture Decision Records
│ │ ├── 000-starter-decisions.md
│ │ ├── 001-preact-island-usage-policy.md
│ │ └── ... # Numbered ADRs (three-digit prefix), some reserved
│ ├── ai-context/ # AI entry point (INDEX.md) + prompt libraries
│ ├── development/ # Contributor docs
│ ├── getting-started/ # Onboarding & quick-start guides
│ ├── implementation-guides/ # Phase guides
│ │ ├── README.md # Implementation roadmap (tiers)
│ │ ├── completed/ # Foundation phases (0-4) + code examples
│ │ ├── active-phases/ # Build + Polish phases (5-12)
│ │ ├── code-examples/ # Examples for phases 5-12
│ │ ├── guides/ # Topic guides (a11y, components, content model, images, responsive, rollback, testing)
│ │ └── reference/ # tech-stack, directory-structure, budgets-guardrails, optional-analytics, portfolio-checklist, table-format-guide
│ ├── patterns/ # Reusable code patterns (islands, components, performance, content, MDX)
│ └── snippets/ # Reusable code snippet includes
├── e2e/ # Playwright end-to-end specs (a11y-axe, header, theme, pages)
│ ├── _headers # Security headers (CSP — ADR-051)
│ ├── favicon.svg, favicon.ico, apple-touch-icon.png
│ ├── og-default.png/.svg, og-about.png/.svg, og-blog.png/.svg
│ ├── og-manifest.json # OG image manifest (og:build / og:check)
│ ├── tsconfig.json # Scripts TypeScript config
│ └── src/ # TypeScript utility scripts (run with tsx):
│ ├── build-tokens.ts # Token builder (tokens:build)
│ ├── validate-env.ts # SITE_URL guard (env:validate)
│ ├── validate-contrast.ts # Contrast validator (design:validate)
│ ├── analyze-bundle.ts # Bundle analysis (bundle:analyze)
│ ├── build-agents-md.ts # AGENTS.md generator (agents:build / agents:check)
│ ├── run-enforcement.ts # Enforcement runner (enforce)
│ ├── remark-*.mjs # Remark plugins (link validation, snippet includes)
│ ├── ... # Budgets, OG images, image/font gates, roadmap sync
│ └── __tests__/ # Unit tests + fixtures for scripts
│ │ ├── brand/ # Brand marks (SVG)
│ │ ├── fonts/ # Vendored woff2 (Astro Fonts API)
│ │ ├── CLAUDE.md # Component-layer constitution
│ │ ├── ThemeSetup.astro # Inline dark-first theme script (ADR-032)
│ │ ├── atoms/ # Badge, Button, Icon, Image,
│ │ │ └── ... # ThemeToggle, Tooltip, ...
│ │ ├── molecules/ # Card, ContactForm, Dialog,
│ │ │ └── ... # Head, PostCard, Tabs, ...
│ │ ├── structural/ # Container, Footer, Grid,
│ │ │ └── ... # Header, Section, ParallaxSection
│ │ ├── islands/ # Preact islands (.tsx)
│ │ ├── mdx/ # Components for MDX content
│ ├── content/ # Content collections (data)
│ │ ├── navigation/ # header.json — drives Header nav
│ ├── content.config.ts # Content Layer schemas (src root)
│ ├── config.ts # Site metadata & links
│ │ ├── BaseLayout.astro # Complete base layout
│ │ └── ProjectLayout.astro
│ │ ├── index.astro # Homepage
│ │ ├── how-it-works.astro
│ │ ├── showcase.astro # Living style guide (ADR-049)
│ │ ├── adr/ # Rendered ADR pages (index + [slug])
│ │ ├── blog/ # index, [slug], tag/[tag]
│ │ └── projects/ # index, [slug]
│ ├── scripts/ # Client-side helpers (featureCardSync.ts)
│ │ └── global.css # With token integration
│ │ ├── astro-content.d.ts # Generated types
│ │ ├── content.ts # Homepage data types
│ │ ├── icons.ts # Icon name registry
│ │ └── navigation.ts # Navigation types
│ ├── utils/ # blog, formatDate, resolveImageFormat,
│ │ └── ... # socialShare, url-utils, validateOgImage
│ ├── __mocks__/ # astro:content mock for unit tests
│ └── __tests__/ # Design-token & contrast tests
│ └── fixtures/ # Shared test fixtures (posts, tokens)
│ ├── base.json # Complete token set
│ └── dist/ # Git-ignored build output
├── .audit-allowlist.json # pnpm audit allowlist (audit:ci)
├── .commitlintrc.cjs # Commit message linting
├── .editorconfig # Editor settings
├── .env.example # Environment template
├── .gitignore # Comprehensive ignore
├── .gitleaks.toml # Secret scanning config (ADR-046)
├── .lintstagedignore # Lint staged ignore
├── .markdown-link-check.json # Link-check config
├── .markdownlint-cli2.jsonc # Markdown lint config (lint:md)
├── .nvmrc # Node version
├── AGENTS.md # Generated agent instructions
├── CHANGELOG.md # Release notes
├── CLAUDE.md # AI constitution
├── CONTRIBUTING.md # Contribution guide
├── README.md # Project overview
├── SECURITY.md # Security policy
├── LICENSE.txt # MIT license
├── astro.config.mjs # Astro config (site/base from env, fonts, astro:env, integrations)
├── ec.config.mjs # Expressive Code options
├── biome.json # Complete config
├── budget-overrides.json # Example overrides
├── budgets.json # Performance budgets
├── lighthouserc.json # Lighthouse CI config (desktop)
├── lighthouserc.mobile.json # Lighthouse CI config (mobile)
├── package.json # All deps, no fluff
├── playwright.config.ts # E2E test config
├── pnpm-lock.yaml # Lockfile
├── stryker.conf.json # Mutation testing config
├── tsconfig.json # Strict mode
├── versions.json # Public stack-version contract (ADR-061)
└── vitest.config.ts # Testing config
