// ✅ Correct - use CSS variables
<h1 className="font-sans">Spline Sans (default)</h1>
<blockquote className="font-serif">Piazzolla for accents</blockquote>
<code className="font-mono">Spline Sans Mono</code>

// ❌ Wrong - hardcoded fonts
<h1 style={{ fontFamily: 'Inter' }}>Never do this</h1>

// ✅ Good
<h1 className="title-1">Page Title</h1>
<p className="body">Content goes here</p>

// ❌ Bad - recreating what exists
<h1 className="text-2xl font-normal tracking-tight leading-7">Page Title</h1>

// Primitive utilities (use sparingly, prefer semantics)
<div className="bg-brand-fern-050">Primary brand surface</div>
<div className="border-neutral-090">High-contrast border</div>

// ❌ These tokens DO NOT EXIST - don't invent them
bg-background-secondary    // Use: bg-secondary
bg-background-muted        // Use: bg-muted
text-primary               // Use: text-foreground or text-primary-foreground
bg-surface                 // Use: bg-card or bg-background
text-subtle                // Use: text-muted-foreground
border-muted               // Use: border-border
bg-hover                   // Use: hover:bg-accent

// ✅ Semantic (preferred)
<Button className="bg-primary text-primary-foreground">Save</Button>
<div className="border border-border rounded-lg">Card</div>
<span className="text-muted-foreground">Optional hint</span>

// ❌ Avoid raw values
<Button className="bg-[#2d6a4f]">Save</Button>
<div style={{ borderColor: '#e5e5e5' }}>Card</div>

className="focus-visible:ring-ring/50 focus-visible:ring-[3px]"

// ✅ Use design system
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Dialog, DialogContent } from "@/components/ui/dialog";
import { Card, CardHeader, CardContent } from "@/components/ui/card";

// ❌ Never recreate
const MyButton = () => <button className="px-4 py-2 bg-blue-500">...</button>;

// ✅ Good - compose from Button
export function SubmitButton({ children, ...props }) {
  return (
    <Button variant="default" size="lg" {...props}>
      <CheckIcon className="mr-2 h-4 w-4" />
      {children}
    </Button>
  );
}

// ❌ Bad - duplicate Button internals
export function SubmitButton({ children }) {
  return (
    <button className="inline-flex items-center justify-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground">
      <CheckIcon className="mr-2 h-4 w-4" />
      {children}
    </button>
  );
}

// NEVER use these fonts
fontFamily: 'Inter'           // Generic AI default
fontFamily: 'Roboto'          // Google generic
fontFamily: 'Arial'           // System fallback
fontFamily: 'system-ui'       // Platform default
className="font-['Inter']"    // Hardcoded font

// NEVER use these patterns
className="bg-gradient-to-r from-purple-500 to-pink-500"  // Purple gradient slop
className="bg-indigo-600"      // Arbitrary Tailwind color
style={{ backgroundColor: '#6366f1' }}  // Hardcoded hex
className="bg-blue-500"        // Generic blue

// NEVER nest cards in cards
<Card>
  <Card>  {/* Card inception = bad */}
    <CardContent>...</CardContent>
  </Card>
</Card>

// Use flat hierarchy with spacing instead
<Card>
  <CardContent className="space-y-4">
    <section>...</section>
    <section>...</section>
  </CardContent>
</Card>

// NEVER recreate existing components
const MyModal = ({ children }) => (
  <div className="fixed inset-0 bg-black/50 flex items-center justify-center">
    <div className="bg-white rounded-lg p-6">{children}</div>
  </div>
);
// Use: import { Dialog, DialogContent } from "@/components/ui/dialog";

// NEVER hardcode shadows
className="shadow-[0_4px_6px_rgba(0,0,0,0.1)]"
// Use: className="shadow-sm" or "shadow-md"

// Preferred - Custom Brief icons (when available)
import { BriefIcon } from "@/components/icons/react";

// Fallback - Lucide (still installed)
import { Check, X, ChevronDown } from "lucide-react";

// Icon sizing follows Button conventions
<Button size="icon">
  <Check className="h-4 w-4" />
</Button>

// ✅ Good
<div className="flex flex-col gap-4">
  <Item />
  <Item />
</div>

// ❌ Avoid
<div className="flex flex-col">
  <Item className="mb-4" />
  <Item />
</div>

className="rounded-md"   // 6px - default for inputs/buttons
className="rounded-lg"   // 8px - cards, dialogs
className="rounded-xl"   // 12px - large containers