Design philosophy: restraint, not addition. The best details are invisible — felt, not seen. Inspired by Linear, Vercel, and Resend.

• Monochrome-first. Color only for semantic meaning (error, success, brand accent). Not decoration.
• Derived tokens. Every surface, text, and border is derived from 3 foundation vars via opacity. Never hardcoded hex.
• Information density. Dense content, sparse chrome. The frame recedes; content advances.
• Motion as feedback. Every transition is meaningful. Nothing animates for its own sake.
• Progressive disclosure. Resting state is minimal. Complexity surfaces on interaction.

All tokens are CSS custom properties in HSL format. Consume via hsl(var(--token)).

Rule: Violet appears only on: active/selected states, brand badges, the primary CTA on the landing page, and AI-related features. Never on chrome elements.

Four levels, each a subtle opacity shift — no heavy shadows.

Level 0  background     hsl(var(--background))     #0e0e12  App canvas
Level 1  card/raised    hsl(var(--card))            #161618  Cards, panels, table rows
Level 2  popover        hsl(var(--popover))         #18181c  Dropdowns, tooltips, sheets
Level 3  dialog         hsl(var(--popover)) + ring  #18181c  Modals (add ring border)

Rule: In dark mode, elevation is communicated by subtle background shift + semi-transparent borders. Never box-shadow in dark mode — use border border-border/50 instead.

Font stack: "Inter", system-ui, sans-serif Mono stack: "JetBrains Mono", "Fira Code", monospace

font-feature-settings: "cv11", "ss01";  /* Inter optical sizing + stylistic alternates */
-webkit-font-smoothing: antialiased;

• One dominant heading per view. No competing font-semibold blocks.
• tabular-nums on all numbers in tables and metrics.
• font-mono-xs for IDs, API keys, branch names, version strings.
• Never break-all. All strings are bounded with truncate or line-clamp-{n}.

Base unit: 4px (Tailwind default scale)

Rule: No arbitrary values (e.g. mt-[13px]). All values from the 4px scale.

• transition-colors duration-150 is the floor for all interactive elements.
• Never add artificial delays. Motion is instant-but-smooth.
• Exit animations: duration-100 (shorter exit than entrance).
• Spring easing only for elements entering from above (dialogs, dropdowns).

Dark mode uses borders for elevation, not shadows.

/* Use instead of box-shadow in dark mode: */
border border-border/50

/* Floating: */
shadow-xl shadow-black/40

/* Glow (brand accent): */
shadow-[0_0_20px_rgba(139,92,246,0.3)]

/* Glow (white/primary): */
shadow-[0_0_20px_rgba(255,255,255,0.15)]

/* Standard divider */
border-border

/* Subtle: inside surfaces */
border-border/60

/* Very subtle: between list items */
border-border/40  or  border-white/[0.06]

/* Semi-transparent (landing/marketing pages) */
border-white/[0.08]

Rules:

• One primary button per view.
• All clickable: cursor-pointer.
• All transitions: transition-colors duration-150.
• Icon-only: must have <Tooltip>.

Normal:   border-border       bg-input          focus: ring-ring/30
Error:    border-destructive  bg-destructive/5  text-destructive below
Disabled: opacity-50          cursor-not-allowed

/* Standard card */
rounded-lg border border-border bg-card p-5

/* Interactive card */
rounded-lg border border-border bg-card p-5
transition-colors duration-150
hover:border-border/80 hover:bg-card/80

/* Feature card (landing) */
rounded-xl border border-white/[0.07] bg-card
transition-all duration-200
hover:border-white/[0.13]

/* Success */
bg-emerald-500/15 text-emerald-400

/* Error */
bg-destructive/15 text-destructive

/* Warning */
bg-amber-500/15 text-amber-400

/* Neutral */
bg-muted text-muted-foreground

/* Brand */
bg-violet-500/15 text-violet-400

• font-variant-numeric: tabular-nums on all number cells
• Full row hover: hover:bg-muted/40 transition-colors duration-100
• Row actions: opacity-0 group-hover:opacity-100 transition-opacity duration-150
• Column headers: text-[11px] uppercase tracking-wider text-muted-foreground
• Numbers: right-aligned; text: left-aligned

/* Use .shimmer class — animated gradient sweep */
<div className="h-4 w-24 rounded shimmer" />

/* Match the exact shape of real content — never generic rectangles */

• Library: Lucide React only.
• Sizes: h-3 w-3 (dense), h-3.5 w-3.5 (compact), h-4 w-4 (standard), h-5 w-5 (prominent).
• Color: Default currentColor. Use text-muted-foreground for decorative/inactive icons.
• No emojis in UI. No sparkle/wand/AI-cliché icons.
• Icon-only buttons must have a <Tooltip> — no exceptions.

No z-[9999]. Always use the defined scale.

The marketing landing page is always dark. It uses the same CSS vars but adds:

/* Landing-specific background (slightly deeper than app bg for drama) */
--landing-bg: #0a0a0f         /* body */
--landing-surface: --card     /* hsl(var(--card)) */

/* Landing ambient glow */
Violet top:  bg-violet-600/8 blur-[100px]
Cyan right:  bg-cyan-600/5   blur-[80px]

/* Dot grid texture */
radial-gradient(circle, rgba(255,255,255,0.9) 1px, transparent 1px)
background-size: 28px 28px
opacity: 0.025

• Focus ring: 1.5px solid hsl(var(--ring)) at 2px offset — always visible.
• Color is never the sole carrier of meaning (always paired with icon or text).
• Disabled state: opacity-50 cursor-not-allowed — element stays in DOM.
• All interactive elements have ARIA labels where visual context is absent.
• Selection highlight: hsl(var(--violet) / 0.22).

All Tailwind color classes map to CSS variables via tailwind.config.ts:

bg-background     → hsl(var(--background))
bg-card           → hsl(var(--card))
bg-popover        → hsl(var(--popover))
bg-muted          → hsl(var(--muted))
bg-primary        → hsl(var(--primary))
bg-secondary      → hsl(var(--secondary))
bg-accent         → hsl(var(--accent))
bg-destructive    → hsl(var(--destructive))
text-foreground   → hsl(var(--foreground))
text-muted-foreground → hsl(var(--muted-foreground))
border-border     → hsl(var(--border))
ring-ring         → hsl(var(--ring))
bg-sidebar        → hsl(var(--sidebar))

Use Tailwind classes everywhere. Raw hsl(var(--token)) only in CSS files or when Tailwind can't express the value.

web/src/
├── globals.css          ← All CSS custom properties + keyframes + base utilities
├── tailwind.config.ts   ← Token-to-Tailwind mapping
├── components/
│   ├── ui/              ← shadcn/ui components (never re-implement these)
│   └── app-sidebar.tsx  ← Sidebar with LogoMark, nav, workspace switcher, user row
└── routes/
    ├── index.tsx        ← Landing page (always dark, marketing)
    ├── login.tsx        ← Auth pages
    └── _app/            ← App shell + all dashboard routes