feat: redesign for 4th ed (#21)

Author: lmammino

.claude/commands/plan.md

@@ -0,0 +1,36 @@
+Plan how to implement the specified feature.
+
+This is the second step in the Spec-Driven Development lifecycle.
+
+Given the implementation details provided as an argument, do this:
+
+1. Run `scripts/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+2. Read and analyze the feature specification to understand:
+   - The feature requirements and user stories
+   - Functional and non-functional requirements
+   - Success criteria and acceptance criteria
+   - Any technical constraints or dependencies mentioned
+
+3. Read the constitution at `/memory/constitution.md` to understand constitutional requirements.
+
+4. Execute the implementation plan template:
+   - Load `/templates/implementation-plan-template.md` (already copied to IMPL_PLAN path)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-10
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     - Phase 0 generates research.md
+     - Phase 1 generates data-model.md, contracts/, quickstart.md
+     - Phase 2 generates tasks.md
+   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.

.claude/commands/specify.md

@@ -0,0 +1,12 @@
+Start a new feature by creating a specification and feature branch.
+
+This is the first step in the Spec-Driven Development lifecycle.
+
+Given the feature description provided as an argument, do this:
+
+1. Run the script `scripts/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+2. Load `templates/spec-template.md` to understand required sections.
+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the next phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.

.claude/commands/tasks.md

@@ -0,0 +1,58 @@
+Break down the plan into executable tasks.
+
+This is the third step in the Spec-Driven Development lifecycle.
+
+Given the context provided as an argument, do this:
+
+1. Run `scripts/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents:
+   - Always read plan.md for tech stack and libraries
+   - IF EXISTS: Read data-model.md for entities
+   - IF EXISTS: Read contracts/ for API endpoints
+   - IF EXISTS: Read research.md for technical decisions
+   - IF EXISTS: Read quickstart.md for test scenarios
+
+   Note: Not all projects have all documents. For example:
+   - CLI tools might not have contracts/
+   - Simple libraries might not need data-model.md
+   - Generate tasks based on what's available
+
+3. Generate tasks following the template:
+   - Use `/templates/tasks-template.md` as the base
+   - Replace example tasks with actual tasks based on:
+     - **Setup tasks**: Project init, dependencies, linting
+     - **Test tasks [P]**: One per contract, one per integration scenario
+     - **Core tasks**: One per entity, service, CLI command, endpoint
+     - **Integration tasks**: DB connections, middleware, logging
+     - **Polish tasks [P]**: Unit tests, performance, docs
+
+4. Task generation rules:
+   - Each contract file → contract test task marked [P]
+   - Each entity in data-model → model creation task marked [P]
+   - Each endpoint → implementation task (not parallel if shared files)
+   - Each user story → integration test marked [P]
+   - Different files = can be parallel [P]
+   - Same file = sequential (no [P])
+
+5. Order tasks by dependencies:
+   - Setup before everything
+   - Tests before implementation (TDD)
+   - Models before services
+   - Services before endpoints
+   - Core before integration
+   - Everything before polish
+
+6. Include parallel execution examples:
+   - Group [P] tasks that can run together
+   - Show actual Task agent commands
+
+7. Create FEATURE_DIR/tasks.md with:
+   - Correct feature name from implementation plan
+   - Numbered tasks (T001, T002, etc.)
+   - Clear file paths for each task
+   - Dependency notes
+   - Parallel execution guidance
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

.claude/constitution.md

@@ -0,0 +1,56 @@
+# Node.js Design Patterns Website Constitution
+
+## Core Principles
+
+### Minimal Static Site
+
+This project represents a minimal static site built with Astro. The core principle is to keep the site lean and fast for the users. So everything that can be pre-built should be pre-built. Images should be optimized and served in modern formats (e.g., WebP) to reduce load times. Whenever we implement a new feature we should aim for the smallest possible footprint and, if possible, the simplest and least intrusive solution.
+
+This means for example favoring Astro components and minimal vanilla JavaScript snippets, rather than React.
+React is also available for more advanced use cases, though. But it should be used sparingly.
+
+### Modern tooling
+
+This website assumes we use modern tooling such as recent versions of Node.js and pnpm and Tailwind CSS for styling.
+
+### Data-driven approach
+
+Where it makes sense we separate data from actual templates, components and other rendering logic. We have data files organized in the `src/content` subdivided in specific types, for example `authors`, `blog`, `chapters`, `quotes`, `faq`, and `reviews`. Each piece of content can be in markdown or JSON format and it should be strongly typed using Astro collections which are defined in `src/content.config.ts`.
+
+### Responsive mobile-first design
+
+The website must be designed to follow a responsive mobile-first approach. This is generally achieved using specific Tailwind CSS utilities that prioritize mobile layouts and progressively enhance them for larger screens (e.g., using `sm:`, `md:`, and `lg:` prefixes).
+
+### Accessibility
+
+The website must follow accessibility best practices to ensure it is usable by everyone, including users with disabilities. This includes:
+
+- Using semantic HTML elements (e.g., `<main>`, `<nav>`, `<section>`, `<article>`, `<header>`, `<footer>`)
+- Providing meaningful alt text for all images and decorative images marked with empty alt attributes
+- Ensuring proper heading hierarchy (h1, h2, h3, etc.) without skipping levels
+- Maintaining sufficient color contrast ratios (WCAG AA standard: 4.5:1 for normal text, 3:1 for large text)
+- Making all interactive elements keyboard accessible with visible focus indicators
+- Using ARIA labels and attributes when semantic HTML is insufficient
+- Ensuring forms have properly associated labels and error messages
+- Testing with screen readers and keyboard navigation
+- Providing skip links for main content navigation
+
+### Coding standards
+
+We adhere to a set of coding standards to ensure code quality and maintainability. This includes using consistent naming conventions, writing clear and concise comments (which must provide business context and describe why we do certain things and not how, the code should be clear enough not to require code-specific comments), and following best practices for each technology used in the project.
+
+The repository uses well-defined formatting rules through [Prettier](https://prettier.io/) and linting through [ESLint](https://eslint.org/).
+
+## Deployment
+
+The website is automatically deployed to GitHub Pages through a GitHub Actions workflow. The deployment process is triggered on every push to the `main` branch. The workflow builds the static site and publishes it to GitHub Pages, making it accessible to users. Contributors do not need to manually handle deployment - focus on code quality and the automated pipeline will handle the rest.
+
+## Governance
+
+- Everyone is welcome to contribute as long as they follow the established guidelines and best practices.
+- Every PR should be reviewed and approved by at least one other contributor before being merged.
+- Every PR must pass basic formatting and linting checks before being merged.
+- PRs should be squashed before merging to maintain a clean commit history.
+- Articles and other textual changes should be proofread for clarity and coherence (AI usage is allowed and encouraged).
+
+**Version**: 1.0.0 | **Ratified**: 2025-09-04 | **Last Amended**: 2025-09-04

.claude/instructions.md

@@ -0,0 +1,14 @@
+# Project Instructions
+
+When working on this project, always follow the guidelines in the project constitution located at `.claude/constitution.md`.
+
+Key principles to remember:
+
+- Keep the site minimal, lean and fast (Astro-first, React sparingly)
+- Follow mobile-first responsive design with Tailwind CSS
+- Maintain accessibility standards (semantic HTML, ARIA, keyboard navigation)
+- Use data-driven approach with strongly typed content collections
+- Follow established coding standards with ESLint and Prettier
+- All changes are automatically deployed via GitHub Actions to GitHub Pages
+
+Always read the constitution file when starting work to ensure alignment with project principles.

.eleventy.js

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: ['*']
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        name: Install pnpm
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Astro sync
+        run: pnpm astro sync
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Check formatting
+        run: pnpm format:check
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Build
+        run: pnpm build

.eslintignore

@@ -0,0 +1,59 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.14.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build with Astro
+        run: pnpm build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4