diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 2af0d7d..57d40f2 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -102,11 +102,11 @@ CI clones `rtk/main` at `./rtk-repo`. Once `feat-refac-doc` is merged into main, | Page type | Nav component | |-----------|--------------| -| Landing (`/`) | `src/components/landing/Nav.astro` | -| Product pages (`/vox/`, `/icm/`) | `src/components/landing/ProductNav.astro` | +| Landing (`/`) | `src/components/global/SiteHeader.astro` (variant="landing") | +| Product pages (`/vox/`, `/icm/`) | `src/components/global/SiteHeader.astro` (variant="product") | | Docs (`/guide/**`) | `src/components/global/Header.astro` (via Starlight override) | -Anchor links in Nav.astro use absolute paths (`/#problem`, `/#install`) so they work from any page. +Anchor links in SiteHeader.astro use absolute paths (`/#problem`, `/#install`) so they work from any page. ## Workflow before push to main diff --git a/.claude/commands/review.md b/.claude/commands/review.md new file mode 100644 index 0000000..a1fa974 --- /dev/null +++ b/.claude/commands/review.md @@ -0,0 +1,125 @@ +--- +name: review +description: Code review for rtk-ldp — Astro components, CSS token compliance, design system rules, generated file integrity, and build correctness. +--- + +Run a thorough code review of the current changes against the RTK Landing standards. + +## Step 1 — Diff scope + +```bash +git diff --name-only HEAD +git diff HEAD --stat +``` + +If no staged/unstaged changes, review the last commit: `git diff HEAD~1 HEAD --name-only`. + +## Step 2 — Read changed files + +Read every changed `.astro`, `.css`, `.ts`, `.mjs`, `.md` file in full before issuing findings. + +## Step 3 — Checklist + +### 3a. CSS Token Compliance (BLOCKER) + +Check every changed `.astro` and `.css` file: + +- No inline `color:`, `background:`, `border-color:`, `fill:` using raw hex values that match a design token +- Tokens to enforce (source: `src/styles/global.css`): + - `--bg: #060b18`, `--bg-alt: #0c1225`, `--bg-card: #0f1629` + - `--text: #e2e8f0`, `--text-muted: #8294ab`, `--text-dim: #64748b` + - `--accent: #00e599`, `--cyan: #38bdf8`, `--violet: #a78bfa`, `--border: #1a2344` +- No duplicate token declarations in `src/styles/landing.css` (tokens defined in `global.css` must not be redefined) +- New color values must be added to `global.css` as tokens, not hardcoded + +### 3b. Generated Files Integrity + +These files must NEVER be manually edited: + +| File | Generator | +| --------------------------------- | -------------------------------- | +| `src/content/docs/guide/**` | `scripts/prepare-docs.mjs` | +| `src/data/docs-search-entries.ts` | `scripts/build-search-index.mjs` | +| `src/data/docs-anchor-map.json` | `scripts/prepare-docs.mjs` | + +Flag any manual edits to these files. + +### 3c. Source of Truth Compliance + +| Data | Must be in | Never in | +| ---------------- | ------------------------------------------------------------------ | ------------------------- | +| RSS entries | `src/data/rss-entries.ts` | `src/pages/rss.xml.ts` | +| Nav anchor links | `Nav.astro` / `ProductNav.astro` with absolute paths (`/#section`) | Inline in pages | +| Docs content | `rtk/docs/guide/` (external repo) | `src/content/docs/guide/` | + +### 3d. Astro Component Quality + +- No inline styles for anything covered by a design token +- Component props typed with TypeScript interfaces +- No `,import './Card.css',Low, +15,Styling,Use scoped styles by default,Astro scopes styles to component automatically, (scoped),,,Medium, +17,Styling,Integrate Tailwind properly,Use @astrojs/tailwind integration,Official Tailwind integration,Manual Tailwind setup,npx astro add tailwind,Manual PostCSS config,Low,https://docs.astro.build/en/guides/integrations-guide/tailwind/ +18,Styling,Use CSS variables for theming,Define tokens in :root,CSS custom properties for themes,Hardcoded colors everywhere,:root { --primary: #3b82f6; },color: #3b82f6; everywhere,Medium, +19,Data,Fetch in frontmatter,Data fetching in component frontmatter,Top-level await in frontmatter,useEffect for initial data,const data = await fetch(url),client-side fetch on mount,High,https://docs.astro.build/en/guides/data-fetching/ +20,Data,Use Astro.glob for local files,Import multiple local files,Astro.glob for markdown/data files,Manual imports for each file,const posts = await Astro.glob('./posts/*.md'),"import post1; import post2;",Medium, +21,Data,Prefer content collections over glob,Type-safe collections for structured content,getCollection() for blog/docs,Astro.glob for structured content,await getCollection('blog'),await Astro.glob('./blog/*.md'),High, +22,Data,Use environment variables correctly,Import.meta.env for env vars,PUBLIC_ prefix for client vars,Expose secrets to client,import.meta.env.PUBLIC_API_URL,import.meta.env.SECRET in client,High,https://docs.astro.build/en/guides/environment-variables/ +23,Performance,Preload critical assets,Use link preload for important resources,Preload fonts above-fold images,No preload hints,"",No preload for critical assets,Medium, +24,Performance,Optimize images with astro:assets,Built-in image optimization, component for optimization, for local images,"import { Image } from 'astro:assets';","",High,https://docs.astro.build/en/guides/images/ +25,Performance,Use picture for responsive images,Multiple formats and sizes, for art direction,Single image size for all screens, with multiple sources, with single size,Medium, +26,Performance,Lazy load below-fold content,Defer loading non-critical content,loading=lazy for images client:visible for components,Load everything immediately,"",No lazy loading,Medium, +27,Performance,Minimize client directives,Each directive adds JS bundle,Audit client: usage regularly,Sprinkle client:load everywhere,Only interactive components hydrated,Every component with client:load,High, +28,ViewTransitions,Enable View Transitions,Smooth page transitions, in head,Full page reloads,"import { ViewTransitions } from 'astro:transitions';",No transition API,Medium,https://docs.astro.build/en/guides/view-transitions/ +29,ViewTransitions,Use transition:name,Named elements for morphing,transition:name for persistent elements,Unnamed transitions,"
",
without name,Low, +30,ViewTransitions,Handle transition:persist,Keep state across navigations,transition:persist for media players,Re-initialize on every navigation,"