Phase 3 - Essential Tooling & Quality Gates

Status: Done

Overview

• Track: Both (MVP & Showcase)
• Duration: 1 day
• Dependencies: Phase 0-2 completed
• Deliverables: Linting setup, formatting config, CI pipeline, quality gates

Entry Criteria

• TypeScript configured
• Design system initialized
• Git repository set up
• Package manager chosen

Implementation Steps

Step	Task	MVP	Showcase	Notes
3.01	Install Biome	✅	✅	Replaces ESLint + Prettier
3.02	Configure Biome rules	✅	✅	Astro-friendly settings
3.03	Set up format command	✅	✅	Format on save
3.04	Configure lint command	✅	✅	Type-aware linting
3.05	Set up pre-commit hook	✅	✅	Husky + lint-staged
3.06	Set up commit-msg hook	✅	✅	Husky + commitlint
3.07	Create CI workflow	✅	✅	GitHub Actions
3.08	Add type checking	✅	✅	tsc + astro check
3.09	Configure build checks	✅	✅	Token validation (script to check all semantic color token pairs for WCAG AA contrast)
3.10	Set up branch protection	✅	✅	Require CI pass
3.11	Add dependency audit	✅	✅	Security scanning
3.12	Set up unit testing for utilities	✅	✅	Vitest for core helpers/utils
3.13	Create quality reports (e.g., coverage)	❌	✅	Broader test coverage, complexity reports
3.14	Document standards	✅	✅	Contributing guide

Why Biome over ESLint + Prettier?

This project uses Biome as its primary tool for code formatting and linting, replacing the more traditional combination of ESLint and Prettier. Here’s why:

• Performance: Biome is written in Rust and is designed to be extremely fast—often over 20x faster than ESLint. This keeps the development feedback loop quick, especially in large codebases.
• Simplicity: By combining formatting and linting into a single tool, Biome reduces configuration overhead. There’s only one configuration file (biome.json) and one dependency to manage.
• All-in-One Solution: Biome handles formatting, linting, and import sorting out of the box, eliminating the need for separate plugins and tools to make them work together.
• First-Class TypeScript Support: It’s built with TypeScript in mind, providing robust and accurate type-aware linting.

Code Quality Standards

Before Committing

Our pre-commit hook runs lint-staged, which automatically:

• Runs biome check --write on staged code files (format, lint, import sorting)
• Runs markdownlint-cli2 --fix on staged Markdown files

Type checking is not part of the pre-commit hook — tsc and astro check run via pnpm run quality locally and quality:ci in CI.

Manual Checks

Run all quality checks:

pnpm run quality

The canonical gate — the same command CI runs, and the one a change must pass before it can be called complete — is:

pnpm run quality:ci

Note: As the project grows, the full pnpm run quality suite (including tests, extensive linting, etc.) might become slower. For faster local iteration, a mechanism such as setting an environment variable (e.g., CI=0 or FAST_LINT=true) might be implemented to run a quicker, focused subset of these checks. However, the complete quality suite will always be enforced by the CI pipeline (the git hooks run a faster subset: lint-staged pre-commit, unit tests pre-push) to ensure no regressions.

Individual checks:

• pnpm run lint - Check for code issues
• pnpm run format:check - Verify formatting
• pnpm run check - Type checking

quality:ci chains these plus markdown linting, unit tests, and the repo’s consistency gates — treat it as the single source of truth for “is this change done”.

Code Style

• Use TypeScript strict mode
• Prefer const over let
• Use optional chaining (?.)
• Sort imports alphabetically
• Keep files under 300 lines

Component Guidelines

• One component per file
• Props interface exported
• JSDoc comments for public APIs
• Accessibility considered

Git Workflow

1. Create feature branch

2. Make changes

3. Commit with conventional format:

   • feat: New features
   • fix: Bug fixes
   • docs: Documentation
   • style: Formatting
   • refactor: Code restructuring
   • perf: Performance
   • test: Testing
   • chore: Maintenance

4. Push and create PR

5. Ensure CI passes

Performance Budget

Respect our performance budgets:

• JS Bundle: < 160KB
• CSS Bundle: < 50KB
• Images: < 200KB each

Accessibility

• WCAG AA compliance minimum
• Test with keyboard navigation
• Verify with screen readers
• Check color contrast

Common Pitfalls

1. Conflicting Formatters: Having Prettier and Biome both active

   • Solution: Disable Prettier, use only Biome

2. Slow CI: Running unnecessary checks

   • Solution: Parallelize jobs, cache dependencies

3. Token Drift: Forgetting to commit built tokens

   • Solution: CI validates token builds

4. Type Errors Hidden: Not running strict checks

   • Solution: Both tsc and astro check in CI

Exit Criteria

• Biome installed and configured
• Format/lint commands working
• Pre-commit hooks functional
• CI pipeline passing
• Type checking enabled
• Token validation in CI
• Branch protection enabled
• Security scanning active
• Contributing guide written

Rollback Strategy

If tooling causes issues:

1. Biome Problems:

      # Revert to the last known-good Biome config — Biome is the only
      # formatter/linter in this stack; do not fall back to Prettier or ESLint
      git checkout HEAD~1 -- biome.json

2. CI Failures:

     - Check for flaky tests
     - Increase timeouts if needed
     - Review recent dependency updates

3. Hook Issues:

   Do not bypass hooks with --no-verify — the gates are halt-on-violation by design. Fix the underlying failure (or revert the change that introduced it) so the hook passes, then commit.

AI Assistant Notes

Key Files to Reference

• biome.json - Linting and formatting rules
• .github/workflows/ci.yml - CI pipeline
• package.json - Scripts and hooks (lint-staged config lives here)
• .husky/ - Pre-commit and commit-msg hooks

Common Prompts for This Phase

• “Set up Biome for Astro project”
• “Create GitHub Actions CI for quality checks”
• “Configure pre-commit hooks with Husky”
• “Add security scanning to CI”

Context Requirements

• Team size and experience
• CI/CD platform (GitHub Actions, etc.)
• Performance requirements
• Security compliance needs