Frontend Design System

Frontend Design System

This project uses a developer-grade design aesthetic inspired by Vercel, Linear, and shadcn/​ui.

Core Principles

1. Black & White Dominant - Color only for semantic status (success/​error/​warning)
2. High Information Density - Clean but compact
3. Border-Based Hierarchy - Avoid heavy shadows
4. Monospace for Data - IDs, dates, timestamps, code always in font-mono

Tech Stack

• React + Vite for apps
• Tailwind CSS v3.4+ for styling
• CSS Variables with semantic classes (bg-background not bg-white)
• Dark Mode First - Class-based via .dark on <html>

Semantic Color Tokens

NEVER use hardcoded colors. Use semantic tokens:

Typography

• UI Text: font-sans (Inter)
• Data/​Code: font-mono (JetBrains Mono) - MANDATORY for:
  • IDs, UUIDs, hashes
  • Dates and timestamps
  • Status codes
  • Logs/​console output
  • Metric values

Component Patterns

Buttons

// Primary
<button className="h-9 px-4 rounded-md bg-primary text-primary-foreground text-sm font-medium hover:bg-primary/​90">
  Action
</​button>

// Secondary
<button className="h-9 px-4 rounded-md bg-secondary text-secondary-foreground text-sm font-medium hover:bg-secondary/​80">
  Cancel
</​button>

// Ghost (for icons/​menus)
<button className="h-9 px-3 rounded-md hover:bg-accent hover:text-accent-foreground">
  <Icon />
</​button>

Cards

<div className="rounded-xl border border-border bg-card text-card-foreground shadow-sm">
  <div className="p-6 pb-2">
    <h3 className="font-semibold text-foreground">Title</​h3>
    <span className="font-mono text-xs text-muted-foreground">ID: abc123</​span>
  </​div>
  <div className="p-6 pt-0">{/​* Content */​}</​div>
</​div>

Inputs

<input
  className="h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm focus-visible:ring-1 focus-visible:ring-ring"
  placeholder="Enter value..."
/>

Tables

<div className="rounded-md border border-border">
  <table className="w-full">
    <thead>
      <tr className="border-b border-border bg-muted/​50">
        <th className="p-4 text-left text-xs uppercase font-medium text-muted-foreground">
          Column
        </​th>
      </​tr>
    </​thead>
    <tbody>
      <tr className="border-b border-border hover:bg-muted/​50">
        <td className="p-4 align-middle font-mono text-sm">value</​td>
      </​tr>
    </​tbody>
  </​table>
</​div>

Quick Reference

Do's and Don'ts

DO:

• Use border-border for all dividing lines
• Use text-muted-foreground for metadata/​labels
• Use font-mono for any data values
• Ensure sufficient contrast

DON'T:

• Use shadows to define hierarchy (use borders)
• Use rounded-full for buttons (except icon-only)
• Mix serif fonts
• Use hardcoded colors like bg-white or bg-gray-100

Reference Files

For detailed information:

• Full design system: See references/​design-system.md
• Component examples: See references/​components.md