tessera/docs/design-system.md

Tessera Design System

The app follows a clean, minimal aesthetic — no heavy borders, no unnecessary shadows, flat hierarchy.

Principles

1. Flat, not boxed. Avoid bordered containers around every section. Use whitespace for separation.
2. Soft borders. Never full-opacity borders. Always /50 or /30.
3. No shadows. Cards and sections don't need shadows. The sidebar has the only subtle shadow.
4. Consistent typography. Three font sizes: labels (10px), content (12-13px), headings (14-24px).
5. Dimmed by default. Icons, borders, and secondary text start dimmed. They brighten on hover/focus.

Component Patterns

Section Wrapper

<section className="overflow-hidden rounded-lg border border-border/50">
  ...
</section>

Section Header / Title Bar

<div className="flex items-center justify-between border-b border-border/50 bg-muted/20 px-4 py-3">
  <h2 className="text-sm font-semibold">Title</h2>
  <Button size="sm">Action</Button>
</div>

List Item (clickable)

<button className={cn(
  "rounded-lg border p-3 text-left transition",
  "border-border/50 hover:border-primary/30 hover:bg-accent/30",
  isActive && "border-primary/50 bg-primary/5"
)}>
  <div className="text-sm font-semibold">Name</div>
  <div className="text-xs text-muted-foreground">Description</div>
</button>

Property Row (key-value)

<div className="flex items-baseline justify-between gap-2 text-sm">
  <span className="text-muted-foreground">Label</span>
  <span className="text-foreground">Value</span>
</div>

Sidebar Nav Item

<Link href={href} className={cn(
  "flex items-center px-2.5 py-1.5 rounded-md text-[13px] transition-colors",
  active
    ? "bg-sidebar-accent text-sidebar-foreground font-medium"
    : "text-sidebar-foreground/55 hover:text-sidebar-foreground hover:bg-sidebar-accent/50"
)}>
  <Icon className={cn("w-4 h-4", active ? "opacity-90" : "opacity-50 group-hover:opacity-70")} />
  <span className="truncate">{label}</span>
</Link>

Section Label (small caps)

<div className="text-[10px] font-medium uppercase tracking-wider text-muted-foreground/60">
  LABEL
</div>

Form Input

<input className="h-8 w-full rounded-md border border-input bg-transparent px-2.5 text-sm outline-none focus:border-ring" />

Form Select

<select className="h-8 w-full rounded-md border border-input bg-transparent px-2.5 text-sm outline-none focus:border-ring">
  <option>...</option>
</select>

Typography Scale

Size	Weight	Use
text-[10px]	font-medium	Section labels, form labels
text-[11px]	font-medium	Meta, timestamps, badges
text-[13px]	font-normal	Nav items, list items
text-sm	font-normal	Body, property values
text-sm	font-semibold	Card titles, list item names
text-base	font-semibold	Section headings
text-lg	font-semibold	Form titles
text-xl	font-semibold	Page headings

Color Tokens

Token	Use
border-border/50	Section borders, card borders
border-border/30	Subtle dividers, list separators
border-border/50	Sidebar border
bg-muted/20	Section header background
bg-muted/40	Tab bar background
bg-sidebar-accent	Active nav item
text-sidebar-foreground/55	Inactive nav item
text-muted-foreground/60	Section labels
text-foreground/90	Slightly muted body text

What to Avoid

• ❌ rounded-md — use rounded-lg for cards, rounded-md for small elements
• ❌ shadow-sm or shadow-md on any card or section
• ❌ bg-card/82 — use solid bg-card or bg-transparent
• ❌ border-border (full opacity) — always /50 or /30
• ❌ backdrop-blur on headers
• ❌ <dl>/<dt>/<dd> grids for property lists — use flex rows
• ❌ text-[11px] font-semibold uppercase — use the section label pattern
• ❌ Heavy icon usage in section headers — keep icons small (h-3 w-3)