Files

Xin Wang 75a25be339 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

3.2 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

@AGENTS.md

Commands

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.

3.2 KiB Raw Permalink Blame History