Lammel Design System

Authoritative guide for all UI development in projects using this design system. Every agent MUST read this before writing UI code.

Token source of truth: design-tokens.css Tailwind v4 mapping: globals.css Design philosophy: White floating islands on a warm Anthropic cream canvas. Intercom-inspired structural geometry: sharp 4px buttons, scale interactions, editorial negative letter-spacing. Primary accent: #cc785c (Claude coral) Secondary accent: #d4a27f (warm beige)

---

1. Design Concept — "Claude-Native"

A warm, editorial system that signals Claude lineage without being cute about it:

• Canvas — the background behind all UI cards. Warm Anthropic cream (#f5f4ed).
• Floating islands — white (#ffffff) rounded cards that sit on top of the canvas. Pure white feels professional and readable against the warm canvas.
• Coral as the signal color — used sparingly for interactive elements (CTAs, links, focus rings). Never as a surface fill.
• Beige as warmth — for AI content highlights, accent badges, secondary CTAs.

---

2. Quick Reference — Decision Trees

"What background color do I use?"

Page canvas / app shell  → bg-surface-dim (#f5f4ed)
Floating card / island   → bg-surface (#ffffff — pure white)
Sidebar island           → bg-surface-container-low (#f9f8f2)
Muted area / header      → bg-surface-container (#f0eee5)
Popover / dropdown       → bg-surface (#ffffff)
Dialog                   → bg-surface + border + shadow-lg

"What text color do I use?"

Primary text     → text-foreground (#181818 — near-black)
Secondary text   → text-muted-foreground (#6b6b6b — warm neutral)
Nav items        → text-foreground (full black — NOT muted)
Link text        → text-primary (Claude coral)
Error text       → text-error / text-destructive

"What button variant do I use?"

Primary CTA (default) → variant="default"  (black bg, white text)
Brand/coral CTA       → variant="accent"   (Claude coral bg, white text)
Secondary action      → variant="outline"  (border, no fill)
Tertiary action       → variant="ghost"    (transparent, hover gray)
Destructive           → variant="destructive" (red text, light red bg)

"What badge variant do I use?"

Neutral / default     → variant="default"  (gray fill)
Brand accent          → variant="accent"   (coral fill)
AI content / warm     → bg-tertiary-container text-on-tertiary-container (beige)
Destructive           → variant="destructive" (red)
Outline               → variant="outline"  (border only)

"What do I use for status colors?"

Error / destructive  → text-error, bg-error-container
Warning              → text-warning, bg-warning-container
Success              → text-success, bg-success-container
Info / primary       → text-primary, bg-primary-container
AI / warm highlight  → text-tertiary, bg-tertiary-container (beige)

---

3. Color System

Philosophy

White islands floating on a warm cream canvas. Two accents:

• Claude coral (primary) — for all interactive elements: CTAs, links, active states, checkboxes, focus rings
• Warm beige (tertiary) — for AI-generated content, warmth accents, special highlights

Never use coral on surfaces. Never use beige as a primary CTA.

Palette

Token	Light	Dark	Source
--surface	#ffffff	#141312	Floating islands
--surface-dim	#f5f4ed	#0f0e0d	Canvas / app shell
--surface-container-low	#f9f8f2	#1a1714	Sidebar island
--surface-container	#f0eee5	#211e1a	Muted areas
--on-surface	#181818	#ede9e4	Near-black
--on-surface-variant	#6b6b6b	#a39a8f	Warm neutral
--primary	#cc785c	#e8a48a	Claude coral
--primary-container	#f5dcd0	#6e2e18	Coral tint
--tertiary	#d4a27f	#e8c4a4	Warm beige
--tertiary-container	#f4e8db	#5c3e22	Beige tint
--outline-variant	#e8e4d8	#2f2b26	Warm parchment borders
--ai-border	#cc785c	#e8a48a	Coral — AI content left border

Surface Levels

Canvas (app shell)       → bg-surface-dim
Sidebar island           → bg-surface-container-low
Main content card        → bg-surface (#ffffff)
Muted areas / headers    → bg-surface-container
Hover states             → bg-surface-variant
Active nav item          → bg-black/8 (works on any bg)

Borders

• border-outline-variant — Default: #e8e4d8 warm parchment
• Borders > shadows. Use borders for structure, shadows only for floating elements.

---

4. Typography

Font: Inter (Google Fonts), system sans-serif fallback.

Weights: 400 body · 500 labels/buttons · 600 headlines

Letter-spacing: Negative on headlines (-0.01em to -0.03em) for more character. Default on body.

Type Scale

Class	Size	Weight	Use
text-headline-medium	28px	600	Page titles
text-headline-small	24px	600	Section headings
text-title-large	22px	400	Large card titles
text-title-medium	16px	500	Card titles, subheadings
text-title-small	14px	500	Table headers
text-body-large	16px	400	Primary body text
text-body-medium	14px	400	Default body text
text-body-small	12px	400	Captions, timestamps
text-label-large	14px	500	Buttons, active labels
text-label-medium	12px	500	Filter labels, badges
text-label-small	11px	500	Counters

---

5. Layout

Spacing Scale (8px base)

Use	Value	Class
Inline gap	4px	gap-1
Icon-to-text	6px	gap-1.5
Component internal	8px	gap-2 / p-2
Card padding	16-24px	p-4 to p-6
Section gap	16-24px	gap-4 to gap-6
Page sections	32px	gap-8

Radius

--radius: 0.5rem (8px). Islands use rounded-xl (12px). Buttons use rounded-[4px] (sharp, Intercom-style industrial geometry — NOT rounded-lg).

---

6. Component Patterns

Buttons

<Button>Primary action</Button>                    {/* Black (default) */}
<Button variant="accent">Brand CTA</Button>        {/* Claude coral */}
<Button variant="outline">Secondary</Button>
<Button variant="ghost">Tertiary</Button>
<Button variant="destructive">Delete</Button>

Rule: ONE primary action per view.

Interaction model (Intercom-style): Buttons use hover:scale-[1.05] active:scale-[0.95] — a physical "growing" feel on hover, snap back on press. transition-all is already in the base class. Never use translate-y press effects on buttons.

Cards / Islands

<Card>  {/* border border-outline-variant, no shadow, bg-surface */}
  <CardHeader>...</CardHeader>
  <CardContent>...</CardContent>
  <CardFooter className="bg-muted/50 border-t">...</CardFooter>
</Card>

AI Content

Left border in coral:

<div className="border-l-2 border-tertiary pl-3">
  {/* AI-generated text */}
</div>

Or use --ai-border token directly.

Tables

• Header: text-muted-foreground + bg-surface-container
• Row hover: hover:bg-muted/50
• Borders: bottom only, minimal

Inputs

• Focus ring: border-ring ring-3 ring-ring/50 (coral focus)

---

7. Anti-Patterns

// ❌ Hardcoded colors
<span className="text-emerald-500">✓</span>
// ✅ Semantic tokens
<span className="text-success">✓</span>

// ❌ Coral on surfaces (overwhelming, breaks the calm canvas)
<div className="bg-primary/5">...</div>
// ✅ Neutral surfaces
<div className="bg-surface-container">...</div>

// ❌ Muted nav text (washes out)
className="text-muted-foreground"
// ✅ Full foreground in nav
className="text-foreground"

// ❌ ring-1 ring-foreground/10 for card borders
<Card className="ring-1 ring-foreground/10">
// ✅ Semantic border
<Card className="border border-outline-variant">

// ❌ rounded-lg or rounded-md on buttons (too soft — not Intercom)
<Button className="rounded-md">
// ✅ Buttons are always 4px — built into buttonVariants base
<Button>

// ❌ translate-y press effect on buttons
active:translate-y-px
// ✅ Scale interactions
hover:scale-[1.05] active:scale-[0.95]

---

8. Design References

Reference	What to study
Anthropic (anthropic.com, claude.ai)	Coral accent on warm cream, restrained typography, editorial spacing
Intercom (intercom.com)	Sharp 4px buttons, scale interactions, editorial negative tracking, warm oat borders

---

9. Files in this repo

File	What
design-tokens.css	All CSS custom properties (light + dark theme) — token source of truth
globals.css	Tailwind v4 @theme inline mapping + base styles + typography utilities. Drop-in for Next.js + Tailwind v4 + shadcn/ui.
README.md	This document — agent instructions

---

10. How to use in a new project

1. Copy design-tokens.css and globals.css into your project (e.g., src/styles/).
2. Adjust the import path in globals.css so ./design-tokens.css resolves correctly.
3. Import globals.css from your root layout / app entry.
4. Add Inter font via next/font or <link> from Google Fonts.
5. Set up shadcn/ui — the legacy aliases in globals.css keep its components working.
6. Hand this README to your AI assistant as the design rulebook.