Brief Design Skill

Use this skill when creating or modifying UI components. Brief has a complete design system—always use it instead of inventing new patterns.

Quick Reference

font-sans

font-serif

font-mono

bg-primary

ring-ring

@/components/ui/*

Typography

Font Families

Brief uses three font families configured in

web/lib/fonts.ts

// ✅ 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>

Semantic Typography Classes

Use these predefined classes from

globals.css

.large-title

.large-title-heavy

.title-1

.title-2

.title-3

.body

.callout

.subhead

.caption-1

Add

-heavy

.title-1-heavy

// ✅ 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>

Color System

Layer 1: OKLCH Primitives

All colors are OKLCH-based. Key ramps defined in

globals.css

• brand-fern

  — Primary brand green (050–095 stops)

• neutral

  — Grays for backgrounds/borders

• sky-blue

  — Focus states and interactive chrome

// 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>

Layer 2: Semantic Tokens

Always prefer semantic tokens over primitives.

⚠️ CRITICAL: Only use tokens that exist. Do NOT invent tokens by pattern-matching (e.g., don't create

bg-background-secondary

because

bg-background

exists).

Complete Token Allowlist

These are the only semantic tokens available. If it's not listed, it doesn't exist:

background

foreground

card

card-foreground

popover

popover-foreground

primary

primary-foreground

secondary

secondary-foreground

muted

muted-foreground

accent

accent-foreground

destructive

destructive-foreground

border

input

ring

sidebar

sidebar-foreground

sidebar-primary

sidebar-primary-foreground

sidebar-accent

sidebar-accent-foreground

sidebar-border

sidebar-ring

chart-1

chart-5

Common Invented Tokens (DON'T USE)

// ❌ 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>

Focus Rings

All interactive elements use consistent focus rings:

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

Component Reuse

CRITICAL: Search Before Creating

Before writing any component:

1. Check

   @/components/ui/*

   (TailStack components)
2. Search codebase:

   grep -r "ComponentName" components/

3. Check

   packages/chat-ui/src/

   for shared components

TailStack Components

Always use existing primitives from

/components/ui/

// ✅ 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>;

Composition Over Duplication

Extend existing components via composition:

// ✅ 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>
  );
}

Anti-Patterns (AI Slop Prevention)

❌ Typography Anti-Patterns

// 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

❌ Color Anti-Patterns

// 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

❌ Layout Anti-Patterns

// 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>

❌ Component Anti-Patterns

// 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"

Icons

Brief is transitioning from Lucide to custom icons:

// 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>

Spacing & Layout

Use

gap

Over Margin

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

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

Standard Spacing Scale

gap-1

gap-2

gap-4

gap-6

gap-8

Border Radius

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

Verification

After creating/modifying a component:

1. Check Storybook — Run

   pnpm run storybook

   in

   packages/ui-storybook

2. Verify tokens — Inspect computed styles, confirm OKLCH/semantic usage
3. Test focus states — Tab through, verify ring color is sky-blue
4. No hardcoded values — Search for hex codes, arbitrary colors

Resources

• Design System Docs:

  docs/design/system.md

• Storybook:

  packages/ui-storybook

  (run with

  pnpm run storybook

  )
• UI Components:

  web/components/ui/

• Color Tokens:

  web/app/globals.css

  (

  :root

  and

  @theme inline

  sections)
• Font Config:

  web/lib/fonts.ts

Deep-Dive Reference Docs

For detailed context beyond this quick reference, see the

reference/

reference/typography.md

reference/color.md

reference/motion.md

Use these for edge cases, advanced patterns, or when you need to explain why a pattern exists.