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
```tsx
<section className="overflow-hidden rounded-lg border border-border/50">
  ...
</section>
```

### Section Header / Title Bar
```tsx
<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)
```tsx
<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)
```tsx
<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
```tsx
<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)
```tsx
<div className="text-[10px] font-medium uppercase tracking-wider text-muted-foreground/60">
  LABEL
</div>
```

### Form Input
```tsx
<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
```tsx
<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`)