Designer-Led ACA Development Template

A production-ready Next.js template designed for designers working with AI Coding Assistants (ACAs) like Cursor, Claude, Copilot, and Cody.

Features

• Next.js 14+ with App Router and TypeScript strict mode
• Convex for real-time database and backend functions
• NextAuth.js for authentication
• shadcn/ui component system with Tailwind CSS
• React Hook Form + Zod for type-safe forms
• Learning paths integrated into the codebase
• ACA-optimized patterns and documentation

Quick Start

Prerequisites

• Node.js 20+
• A Convex account (sign up free)

Installation

1. Clone this repository

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env.local

   Fill in your Convex URL and NextAuth secret.

4. Start Convex dev server:

   npm run convex:dev

5. In another terminal, start Next.js:

   npm run dev

6. Visit http://localhost:3000

Documentation

• Introduction for Designers - Start here!
• Core Learning Path - Step-by-step tutorials
• ACA Tooling Guide - Using Cursor, Claude, Copilot, Cody
• Stack Reference - Architecture and patterns
• Design System Guide - shadcn/ui and styling
• Governance - Safe zones and protected zones

Learning Paths

Core Path

1. Setup and Tour
2. Build Your First Screen
3. Connect to Convex
4. Forms and Validation
5. UI Refactoring and Bugfixing
6. End-to-End Feature

Optional Tracks

• AI Assistant Track
• Data and Backend Track
• Venture Studio Track
• Advanced Frontend Track

Project Structure

├─ app/              # Next.js App Router pages
├─ components/       # Reusable React components
├─ features/         # Domain-specific features
├─ convex/          # Convex backend (schema, queries, mutations)
├─ core/            # Core infrastructure (protected)
├─ lib/             # Shared utilities
├─ docs/            # Documentation
├─ learning/        # Learning materials
└─ playgrounds/     # Experimental code

Key Commands

# Development
npm run dev              # Start Next.js dev server
npm run convex:dev      # Start Convex dev server

# Code Quality
npm run lint            # Run ESLint
npm run type-check      # TypeScript type checking
npm run format          # Format with Prettier

# Testing
npm test                # Run unit tests
npm run test:e2e        # Run E2E tests

# Features
npm run create-feature  # Scaffold a new feature
npm run seed            # Seed database with sample data

Safe Zones vs Protected Zones

Safe Zones (Designers Can Modify)

• features/ - All feature code
• components/ - UI components
• learning/ - Learning materials
• playgrounds/ - Experimental code

Protected Zones (Require Approval)

• core/ - Core infrastructure
• convex/system.ts - System functions
• app/api/auth/ - Authentication
• core/config/env.ts - Environment config

See Governance for details.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Support

• Check the documentation
• Review learning materials
• Open an issue for bugs or questions