From d57673ca880478e2188aca1b863917a3292b8a73 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 19 May 2026 15:54:43 +0000 Subject: [PATCH 01/28] feat: add project design plan and task list for blueprint template Create `plan.md` and `tasks.md` in `.vibe/specs/0-create-template/` as requested. These files outline the architecture, tech stack, and implementation steps for the production-ready Next.js 16 template. --- .vibe/specs/0-create-template/plan.md | 49 ++++++++++++++++++++++ .vibe/specs/0-create-template/tasks.md | 57 ++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 .vibe/specs/0-create-template/plan.md create mode 100644 .vibe/specs/0-create-template/tasks.md diff --git a/.vibe/specs/0-create-template/plan.md b/.vibe/specs/0-create-template/plan.md new file mode 100644 index 0000000..a6d52b6 --- /dev/null +++ b/.vibe/specs/0-create-template/plan.md @@ -0,0 +1,49 @@ +# Design and Plan: Blueprint Template + +## Overview +Blueprint is a production-ready Next.js 16 starter template designed for high performance, accessibility, and developer productivity. It leverages the latest web technologies and strictly enforces TypeScript for type safety. + +## Tech Stack +- **Next.js 16.2.6**: App Router, TypeScript strict mode, Turbopack. +- **React 19**: Peer dependency of Next.js 16. +- **Tailwind CSS v4**: CSS-first configuration via `@theme` in `globals.css`. +- **HeroUI v3.0.5**: Core UI component library. +- **Framer Motion**: For complex animations and page transitions. +- **Lucide React**: Icon library. +- **cmdk**: Keyboard-driven command palette. +- **next-themes**: Dark mode management. +- **Zod**: Environment variable validation. +- **Vitest 4.1**: Unit and component testing. +- **Playwright 1.59.1**: E2E and accessibility testing. +- **Supabase**: Data layer (stubbed integration). +- **Vercel Blob**: File storage (stubbed integration). + +## Architectural Design +### 1. Component Strategy +- **Server Components by default**: Optimization for performance and SEO. +- **Client Components at leaf nodes**: Minimal use of `"use client"` for interactivity. +- **Barrel Exports**: Every component folder includes an `index.ts` for clean imports. +- **TSDoc**: Mandatory documentation for all public components and utilities. + +### 2. Styling +- **Tailwind v4 CSS-first**: Theme configuration is handled directly in CSS, avoiding a separate JS/TS config file. +- **Responsive Design**: Mobile-first approach, tested at 375px and 1280px. +- **Dark Mode**: Seamless light/dark mode support with system preference detection. + +### 3. Data & State Management +- **Type-safe Environment**: Environment variables validated at runtime using Zod. +- **Data Access Layer**: Abstracted data fetching through `src/lib/data/` returning typed interfaces. +- **URL-synced State**: Data table filters and search state synchronized with URL search params. + +### 4. Testing & Quality +- **Co-located Unit Tests**: Tests sit next to their components. +- **Comprehensive E2E**: Covering navigation, keyboard interactions, and accessibility. +- **CI/CD Integration**: Automated workflows for type-checking, linting, and testing on every PR. + +## Implementation Strategy +The project will be built in phases: +1. **Infrastructure**: Toolchain setup (mise, pnpm), core configurations (Next.js, TS, Tailwind). +2. **Core Components**: Navigation, layout providers, and theme toggling. +3. **Data Layer**: Mock data structures and Supabase/Blob stubs. +4. **Feature Pages**: Landing, Dashboard (complex data table), About, and Error pages. +5. **Testing & Docs**: Implementing the test suites and the Nextra documentation site. diff --git a/.vibe/specs/0-create-template/tasks.md b/.vibe/specs/0-create-template/tasks.md new file mode 100644 index 0000000..40978be --- /dev/null +++ b/.vibe/specs/0-create-template/tasks.md @@ -0,0 +1,57 @@ +# Tasks: Blueprint Template Implementation + +## Phase 1: Environment & Initialization +- [ ] Initialize `.mise.toml` with Node 24 and pnpm 11. +- [ ] Create `package.json` with exact versions for Next.js 16, HeroUI v3, etc. +- [ ] Configure `tsconfig.json` with strict mode and required path aliases. +- [ ] Install dependencies. +- [ ] Set up `.env.example` and `src/lib/env.ts` (Zod validation). + +## Phase 2: Core Infrastructure +- [ ] Configure `next.config.ts` with security headers and CSP. +- [ ] Implement `src/app/globals.css` with Tailwind v4 `@theme`. +- [ ] Create `src/components/Providers/index.tsx` (HeroUI, ThemeProvider). +- [ ] Set up root `layout.tsx` with providers and skip-to-content link. + +## Phase 3: Shared Components +- [ ] Implement `` with SVG logo, nav links, and theme toggle. +- [ ] Implement `