AstroDeck — Windsurf Rules

# AstroDeck — Windsurf Rules

## Priority Order
1. PROJECT.md — project-specific overrides (highest priority)
2. AGENTS.md  — AstroDeck defaults and patterns
3. README.md  — human-readable docs (installation, deployment)

---

## Tech Stack
- Astro v6.x — island architecture, file-based routing, zero-JS by default
- Tailwind CSS v4 — configured via @tailwindcss/vite (Vite plugin)
- shadcn/ui + Radix UI — React components for interactive elements
- TypeScript — strict mode, no `any`

---

## Tailwind v4 — Critical Configuration
- Integration: @tailwindcss/vite in vite.plugins (NOT @astrojs/tailwind)
- Theme: @theme directive in src/styles/globals.css (NOT tailwind.config.js)
- Colors: OKLCH format only (NOT HSL, NOT hex in @theme)
- NEVER create tailwind.config.js or tailwind.config.mjs

Correct @theme example:
@theme {
  --color-background: oklch(100% 0 0);
  --color-foreground: oklch(9.8% 0.0016 286.75);
  --color-primary: oklch(11.2% 0.0079 286.75);
  --color-primary-foreground: oklch(98% 0.0011 286.75);
  --color-muted: oklch(96.1% 0.0011 286.75);
  --color-muted-foreground: oklch(55.6% 0.0117 286.75);
}

.dark {
  --color-background: oklch(1.5% 0 0);
  --color-foreground: oklch(98% 0 0);
}

---

## Import Alias
Always use @/ for imports from src/. Relative paths are forbidden.

CORRECT: import Hero from "@/components/sections/Hero.astro"
WRONG:   import Hero from "../components/sections/Hero.astro"

---

## Styling
CORRECT: class="bg-background text-foreground"
CORRECT: class="bg-primary text-primary-foreground"
WRONG:   class="bg-white text-gray-900"
WRONG:   class="bg-blue-500"
WRONG:   style="padding: 80px"

Use semantic CSS variable classes that work in both light and dark mode.
Never hardcode colors. Never use inline styles.
All global styles go in src/styles/globals.css only.

---

## Responsive Design — Mobile-First
CORRECT: text-3xl md:text-5xl lg:text-6xl
WRONG:   text-6xl sm:text-3xl

Verify at: 375px (mobile), 768px (tablet), 1024px (laptop), 1280px (desktop)
Requirements: no horizontal overflow, touch targets min 44px, grids stack on mobile

---

## File Types
.astro — use for everything static: sections, pages, layouts, UI (default choice)
.tsx   — use ONLY when client-side state is needed (forms, modals, dropdowns)

---

## File Naming
Components:    PascalCase  — Hero.astro, PricingTable.astro, ThemeToggle.astro
Pages:         kebab-case  — index.astro, about-us.astro, privacy-policy.astro
UI components: kebab-case  — button.tsx, card.tsx, dialog.tsx
Utilities:     camelCase   — utils.ts

---

## Project Structure
src/
  components/
    sections/     Pre-built page sections (Hero, CTA, Pricing, FAQ, Features, etc.)
    ui/           shadcn/ui React components (Button, Card, Dialog, etc.)
  layouts/        BaseLayout, FullWidthLayout, MinimalLayout, AuthLayout, ArticleLayout
  pages/          File-based routing — index.astro = /
  content/        Astro Content Collections — blog posts
  styles/
    globals.css   Design tokens + Tailwind @theme — edit colors here
  lib/
    utils.ts      cn() helper and utilities
public/           Static assets (fonts, favicon, images)
astro.config.mjs  Astro + Vite configuration

---

## TypeScript Props — Always Required
Every component needs a typed Props interface:

interface Props {
  title: string;
  description?: string;
  variant?: 'default' | 'centered' | 'wide';
}
const { title, description, variant = 'default' } = Astro.props;

---

## Layout Selection
BaseLayout      → content pages, blog posts (boxed, max-w-5xl)
FullWidthLayout → showcase, gallery, portfolio (full viewport)
MinimalLayout   → 404, maintenance, standalone landing pages (no nav)
AuthLayout      → login, signup, password reset (split screen with branding)
ArticleLayout   → blog articles (reading-optimized typography)

---

## New Section Template
---
// src/components/sections/NewSection.astro
interface Props { title?: string; subtitle?: string; }
const { title = "Default Title", subtitle } = Astro.props;
---
<section class="py-20 px-6">
  <div class="max-w-7xl mx-auto">
    <div class="text-center mb-12">
      <h2 class="text-4xl font-bold mb-4">{title}</h2>
      {subtitle && <p class="text-lg text-muted-foreground">{subtitle}</p>}
    </div>
    <slot />
  </div>
</section>

---

## New Page Template
---
import BaseLayout from "@/layouts/BaseLayout.astro";
const title = "Page Title - AstroDeck";
const description = "SEO description (150-160 characters ideal)";
---
<BaseLayout title={title} description={description}>
  <!-- sections here -->
</BaseLayout>

---

## Astro 6 — Breaking Changes to Watch For
ViewTransitions  → ClientRouter from astro:transitions
z from astro:content → z from astro/zod
z from astro:schema  → z from astro/zod
Node.js requirement: 22+ (not 18, not 20)

---

## Performance
- Astro ships zero JS by default — maintain this
- client:load only when JS is truly essential
- Prefer client:idle (after page load) or client:visible (on scroll into view)
- Use <Image /> from astro:assets for all images
- Lazy load below-the-fold content

---

## Accessibility
- Semantic HTML: <section>, <article>, <nav>, <main>, <header>, <footer>
- All images: descriptive alt text (alt="" for decorative)
- One <h1> per page, then h2, h3 in order — no skipping levels
- Keyboard navigation must work for all interactive elements
- Color contrast: 4.5:1 minimum for body text
- ARIA labels on interactive elements without visible text

---

## SEO Component
<SEO
  title="Page Title"
  description="150-160 character description"
  image="/cover.png"
  type="website"
  noindex={false}
/>

Set noindex={true} on auth pages (login, signup).

---

## Common Tailwind Patterns
Container:        class="max-w-7xl mx-auto px-6"
Responsive grid:  class="grid md:grid-cols-2 lg:grid-cols-3 gap-6"
Full screen flex: class="flex items-center justify-center min-h-screen"
Card:             class="rounded-lg border bg-card p-6 hover:shadow-lg transition-shadow"
Button row:       class="flex flex-col sm:flex-row gap-4"

---

## Commands
npm run dev          Start dev server at http://localhost:4321
npm run build        Production build to dist/
npm run preview      Preview production build locally
npm run lint:fix     ESLint auto-fix
npm run format       Prettier formatting

---

## Git
- Commits: fine to do when work is complete
- Push: requires explicit user request — never push automatically

---

## Design Knowledge Base
Central design decisions live in `system/globals/`. Read the relevant file BEFORE making design decisions:
- Colors → system/globals/colors.md
- Typography → system/globals/typography.md
- Spacing → system/globals/spacing.md
- Interaction → system/globals/interaction.md
- Accessibility → system/globals/accessibility.md
- Effects → system/globals/effects.md
- Responsiveness → system/globals/responsiveness.md
- Imagery → system/globals/imagery.md

## Self-Audit Prompts
Portable quality checks in `system/prompts/`. Can be used in any tool via copy-paste.

## Never Do
- Relative imports (use @/ alias)
- Hardcoded colors (use CSS variable classes)
- Inline styles (use Tailwind classes)
- tailwind.config.js or tailwind.config.mjs
- @astrojs/tailwind integration
- HSL or hex colors in @theme (use OKLCH)
- import { z } from 'astro:content' (use astro/zod)
- <ViewTransitions /> (use <ClientRouter />)
- .tsx files for static content (use .astro)
- TypeScript any type
- Skipping responsive design
- Styles outside src/styles/globals.css

---

## MCP Servers (Optional — Enhances AI Assistance)
Astro Docs: https://mcp.docs.astro.build/mcp
shadcn/ui:  https://www.shadcn.io/api/mcp

## Resources
Astro Docs:      https://docs.astro.build
Tailwind v4:     https://tailwindcss.com/docs
shadcn/ui:       https://ui.shadcn.com