diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..6251a15 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun run type-check && bun run lint && bun run format:check", + "timeout": 120 + } + ] + } + ] + } +} diff --git a/.cursor/rules/frontend/figma.md b/.cursor/rules/frontend/figma.md new file mode 100644 index 0000000..c2ba3c0 --- /dev/null +++ b/.cursor/rules/frontend/figma.md @@ -0,0 +1,29 @@ +## Figma MCP Integration Rules + +These rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change. + +### Required flow (do not skip) + +1. Run get_design_context first to fetch the structured representation for the exact node(s). +2. If the response is too large or truncated, run get_metadata to get the high‑level node map and then re‑fetch only the required node(s) with get_design_context. +3. Run get_screenshot for a visual reference of the node variant being implemented. +4. Only after you have both get_design_context and get_screenshot, download any assets needed and start implementation. +5. Translate the output (usually React + Tailwind) into this project’s conventions, styles and framework.  Reuse the project’s color tokens, components, and typography wherever possible. +6. Validate against Figma for 1:1 look and behavior before marking complete. + +### Implementation rules + +- Treat the Figma MCP output (React + Tailwind) as a representation of design and behavior, not as final code style. +- Replace Tailwind utility classes with the project’s preferred utilities/design‑system tokens when applicable. +- Reuse existing components (e.g., buttons, inputs, typography, icon wrappers) instead of duplicating functionality. +- Use the project’s color system, typography scale, and spacing tokens consistently. +- Respect existing routing, state management, and data‑fetch patterns already adopted in the repo. +- Strive for 1:1 visual parity with the Figma design. When conflicts arise, prefer design‑system tokens and adjust spacing or sizes minimally to match visuals. +- Validate the final UI against the Figma screenshot for both look and behavior. + +### Figma MCP server rules + +  - The Figma MCP server provides an assets endpoint which can serve image and SVG assets +  - IMPORTANT: If the Figma MCP server returns a localhost source for an image or an SVG, use that image or SVG source directly +  - IMPORTANT: DO NOT import/add new icon packages, all the assets should be in the Figma payload +  - IMPORTANT: do NOT use or create placeholders if a localhost source is provided diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 670fb82..d565407 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,3 +16,5 @@ jobs: run: bun run type-check - name: Lint check run: bun run lint + - name: Format check + run: bun run format:check diff --git a/.gitignore b/.gitignore index a547bf3..90208f8 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,10 @@ dist-ssr *.njsproj *.sln *.sw? + +# Visual-QA artefacts (generated by scripts/screenshot-home.mjs) +specs/iterations/*.png + +# Env +.env +.env.local diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..ff15c23 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,6 @@ +node_modules +dist +pnpm-lock.yaml +convex/_generated +apps/dashboard/test-results +apps/dashboard/playwright-report diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..6487723 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,8 @@ +{ + "semi": true, + "singleQuote": false, + "trailingComma": "all", + "printWidth": 80, + "tabWidth": 2, + "plugins": ["prettier-plugin-tailwindcss"] +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5afd662 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,75 @@ +# Cornell Loop — Agent Guide + +Loop is an event-discovery dashboard for Cornell student orgs. Students follow clubs, RSVP to events, and browse a feed of upcoming happenings. Convex backs auth + data; a browser extension surface is also planned. + +Keep this file concise — it loads every new session. + +## Repo layout + +- `apps/dashboard/` — Vite + React 19 + TypeScript SPA (the main web app). +- `shared/ui/` — design system (components, tokens, utils). Imported in the dashboard via the `@app/ui` alias (see `apps/dashboard/vite.config.ts`). +- `ai/`, `scripts/`, `specs/` — docs, codegen helpers, and visual-QA artefacts. + +No other apps today; workspace is set up to grow (e.g. extension). + +## Tech stack + +- **React 19** + **React Router v7** (see `apps/dashboard/src/App.tsx` for routes). +- **Convex** (`@convex-dev/auth`) for auth. `ProtectedRoute` has a **dev bypass** — protected routes render without login when `import.meta.env.DEV`. Great for iteration. **Always read `apps/dashboard/convex/_generated/ai/guidelines.md` first** before touching Convex code — its rules override training data. +- **Tailwind CSS v4** via `@tailwindcss/vite`. No config file; content scanning is via `@source` directives inside `apps/dashboard/src/index.css`. **Important:** `shared/ui/src` is explicitly `@source`'d so design-system classes land in the generated CSS. If a design-system class silently stops working, check that this `@source` is still present. +- **Design tokens** are plain CSS custom properties in `shared/ui/src/styles/tokens.css` (`--color-*`, `--space-*`, `--font-*`, `--radius-*`, `--shadow-*`, etc.). **Never hardcode colors/spacing/fonts.** Reference tokens with Tailwind arbitrary-value syntax, e.g. `bg-[var(--color-surface)]`, `gap-[var(--space-4)]`. +- **Fonts**: DM Sans (body), Inter (UI), Manrope (brand wordmark). Loaded in `apps/dashboard/index.html`. +- **SVG** via `vite-plugin-svgr` (`import Icon from './x.svg?react'`). + +## Package manager + +- This repo uses **bun** (not pnpm — ignore any older doc that says otherwise). +- Root scripts forward into the dashboard package: + - `bun run dev` — start Vite (default 5173, falls back to 5174 if busy). + - `bun run build` — `tsc -b && vite build`. + - `bun run type-check` — `tsc --noEmit`. + - `bun run lint` — ESLint. + - `bun run format` / `bun run format:check` — Prettier (with tailwind plugin). +- If bun is unavailable in a sandbox, `node scripts/*.mjs` still works for scripts. + +## Automated checks (Claude Stop hook) + +A `Stop` hook in `.claude/settings.json` runs `bun run type-check && bun run lint && bun run format:check` at the end of every turn. If it fails, address the errors before finishing — even pre-existing ones. + +## Visual QA workflow + +- **Screenshot the dashboard** with Playwright: + - `node scripts/screenshot-home.mjs