KQED Prototype Boilerplate

A minimal starting point for building prototypes with Vite + React + TypeScript, set up to pair well with AI coding tools (Claude Code and Cursor). Fork this repo for each new prototype instead of starting from scratch.

Getting started

1. Fork or duplicate this repository for your prototype.

2. Clone it to your computer.

3. Install Node.js (LTS version) if you don't already have it.

4. Install dependencies:

   npm install

5. Start the dev server:

   npm run dev

6. Open the URL it prints (usually http://localhost:3000) in your browser. The page updates automatically as you (or your AI assistant) edit files.

Project structure

index.html          The HTML page that loads the app
src/main.tsx         App entry point — you shouldn't need to touch this often
src/App.tsx          The main page — start editing here
src/App.css          Styles for App.tsx
src/index.css        Global styles

As your prototype grows, it's fine to add more files under src/ (for example src/components/) — just ask your AI assistant to help organize things as needed.

Useful commands

Command	What it does
npm run dev	Start the local dev server
npm run build	Build an optimized production version
npm run preview	Preview the production build locally
npm run lint	Check the code for common issues
npm run format	Auto-format all files

Using this with AI tools

This repo includes ground rules so Claude and Cursor behave consistently and keep changes easy to follow:

• Claude Code: reads CLAUDE.md automatically.
• Cursor: reads the rules in .cursor/rules/project.mdc automatically.

You generally don't need to open or edit these yourself — they're there so the AI knows the conventions of this project (don't add dependencies without asking, keep changes small and previewable, run lint/format before finishing, etc.). If you want the AI to behave differently for your specific prototype, you can ask it to update these files.

Tips for non-technical builders

• Describe what you want in plain language — "add a button that shows a random fact when clicked" is a great prompt.
• Ask the AI to explain what it changed if you're not sure.
• Keep the dev server (npm run dev) running in a terminal and check the browser after each change.
• If something breaks, tell the AI what you see (an error message, a blank page, etc.) — it can usually diagnose it from there.