Add CLAUDE.md for project guidance and architecture overview

Introduced CLAUDE.md to provide comprehensive guidance for the Claude Code repository. The document includes commands for development, an overview of the architecture, component layers, design system specifications, theming implementation details, and shadcn/Radix configuration. This addition aims to enhance understanding and streamline collaboration within the project.
2026-06-05 15:47:21 +08:00
parent b62c8a20ec
commit 75a25be339
1 changed files with 48 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
@AGENTS.md
+
+## Commands
+
+```bash
+npm run dev      # start dev server at localhost:3000
+npm run build    # production build
+npm run lint     # ESLint (no test suite exists yet)
+```
+
+## Architecture
+
+This is a single-page admin console for managing AI video assistants. It is a Next.js 16 app using the App Router, React 19, Tailwind CSS v4, and shadcn components backed by Radix UI primitives.
+
+**Navigation model** — the app has no Next.js routes beyond `/`. All "pages" are React components in `src/components/pages/` that are conditionally rendered by `AppShell` based on a `NavKey` state value. `AppShell` owns the active page and sidebar-collapsed state and threads them down as props.
+
+**Component layers:**
+- `src/app/` — Next.js entry: `layout.tsx` (fonts, theme-flash script, metadata) and `page.tsx` (renders `<AppShell />`)
+- `src/components/layout/` — `AppShell` (page-switching shell), `Sidebar` (collapsible nav, 252 → 76px), `Topbar` (theme toggle, notifications), `ThemeToggle`
+- `src/components/pages/` — one component per nav section; `PlaceholderPage` is a shared editorial header for unimplemented pages
+- `src/components/ui/` — shadcn primitives (button, card, badge, dialog, etc.)
+- `src/hooks/` — `use-mobile.ts`
+- `src/lib/utils.ts` — `cn()` (clsx + tailwind-merge)
+- `src/data/mock.ts` — static mock data (no API layer yet)
+
+**Path alias** — `@/` maps to `src/`.
+
+## Design System
+
+`DESIGN.md` is the authoritative spec. `src/app/globals.css` is the implementation — it sets the CSS custom properties consumed by all Tailwind utilities. Key rules:
+
+- **Two themes from one navy palette.** Dark navy is the default (applied via `<html className="dark">` and a no-flash `localStorage` script in `layout.tsx`). Light is cool off-white. Toggle is a `ThemeToggle` component in `Topbar`.
+- **Never hardcode hex values.** Drive color from semantic tokens: `bg-background`, `text-foreground`, `bg-card`, `text-ink`, `border-hairline`, `bg-surface-strong`, `text-muted-foreground`, etc.
+- **Display typography** uses Cormorant Garamond (`--font-display`, `font-weight: 300`). Apply via the `.font-display` class or `.display-{mega|xl|lg|md|sm}` size helpers. **Never bold display copy.**
+- **Body typography** uses Inter (`--font-sans`, `font-weight: 400/500`).
+- **All CTAs and nav items are pill-shaped** (`rounded-full`). Cards use `rounded-2xl`; hero bands use `rounded-3xl`.
+- **Gradient orbs** (mint, peach, lavender, sky, rose) are atmosphere-only — they appear as blurred `radial-gradient` backgrounds on hero panels and brand/avatar icons, never as button fills or text colors.
+
+## Theming Implementation
+
+`globals.css` defines `:root` (light) and `.dark` variable blocks. All shadcn variables (`--background`, `--card`, `--primary`, `--border`, …) plus editorial extras (`--ink`, `--canvas-soft`, `--surface-strong`, `--hairline*`, `--gradient-*`, `--body-text`) are declared there. The `@theme inline` block wires them into Tailwind utilities.
+
+## shadcn / Radix
+
+`components.json` configures shadcn with style `radix-luma`. Add new primitives via `npx shadcn add <component>` — they land in `src/components/ui/`. Icon library is Lucide React.