:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Code Commits Issues Pull requests Wiki Builds Discussions Projects Insights Search Files 21717 branches · 5227 tags posthog / .interface-design / system.md 8.6 KB
Code Raw Blame Permalink PostHog Design System
Extracted from codebase. Source of truth for UI consistency.
Spacing
Base unit : 4px (0.25rem)
Scale : 4, 8, 12, 16, 24, 32
Default gap : 8px (gap-2) — used in 55% of layouts
Default padding : 8px (p-2) or 16px (p-4)
Scene padding : var(--scene-padding)
Border Radius
Token
Value
Usage
--radius-sm
4px (0.25rem)
Small elements, tags
--radius
6px (0.375rem)
Default — buttons, inputs, cards
--radius-lg
10px (0.625rem)
Popovers, menus, larger containers
full
9999px
Avatars, pills, circular elements
Prefer rounded (default) for most elements. Use rounded-lg for popovers and elevated containers.
Depth Strategy
Borders-first. Shadows are rare and intentional.
Primary border : var(--color-border-primary) — posthog-3000 warm gray
Secondary border : var(--color-border-secondary) — darker variant
Semantic borders : --color-border-info, --color-border-warning, --color-border-error, --color-border-success
Default shadow : var(--shadow-elevation-3000) = 0 3px 0 <border-color> — only for elevated cards and toasts
Modal shadow : var(--modal-shadow-elevation) = 0px 16px 16px -16px rgb(0 0 0 / 35%)
Do not add shadows for general UI. Reserve for modals, dropdowns, and hover-elevated cards.
Colors
Accent
Token
Light
Dark
--color-accent
HSL(19, 100%, 48%) orange
HSL(43, 94%, 57%) yellow
--color-accent-hover
+10% lightness
+10% lightness
--color-accent-active
+15% lightness
+15% lightness
--color-accent-inverted
Yellow
Orange
Backgrounds
Token
Light
Dark
bg-primary
posthog-3000-50
neutral-cool-950
bg-surface-primary
white
neutral-cool-850
bg-surface-secondary
posthog-3000-100
neutral-cool-900
bg-surface-tertiary
posthog-3000-150
neutral-cool-950
bg-fill-primary
white
neutral-cool-900
bg-fill-secondary
posthog-3000-25
neutral-cool-850
bg-fill-tertiary
posthog-3000-50
neutral-cool-800
Highlight fills (opacity-based)
Use bg-fill-highlight-{50,100,150,200} for subtle black overlays (light mode) or white overlays (dark mode). These use color-mix() for transparency.
Text
Token
Light
Dark
text-primary
neutral-950
neutral-100
text-secondary
neutral-750
neutral-350
text-tertiary
neutral-600
neutral-400
text-success
green-600
green-400
text-warning
yellow-700
yellow-400
text-error
red-600
red-400
Semantic
Token
Value
danger
#db3707
warning
#f7a501
success
#388600
Data colors
15 series colors (--data-color-1 through --data-color-15) for charts. Some override in dark mode. Always use hex for Chart.js compatibility.
Brand
Token
Value
--brand-blue
#1d4aff
--brand-red
#f54e00
--brand-yellow
#f9bd2b
--brand-key
#000 (light) / #fff (dark)
Typography
Property
Value
Base size
14px
Line height
1.5715
Font sans
RoundHog, -apple-system, Inter, ...
Font title
RoundHog, -apple-system, Inter, ...
Font mono
ui-monospace, SFMono-Regular, SF Mono, Menlo, ...
Font medium
500
Font semibold
600
Headings
Level
Size
Weight
Font
h1
1.75rem
500
font-title
h2
1.3125rem
500
font-title
h3
1rem
500
font-title
h5
0.6875rem
600
font-title, uppercase, letter-spacing 0.075em
Component Patterns
Button (LemonButton)
Size
Height
H-Padding
V-Padding
Font Size
xxsmall
20px
4px
2px
0.6875rem
xsmall
26px
6px
4px
0.75rem
small
33px
8px
8px
inherit
medium
37px
12px
4px
0.875rem
large
49px
12px
12px
1rem
Border radius: var(--radius) (6px)
Default size: medium
Input (LemonInput)
Size
Height
H-Padding
V-Padding
xsmall
24px
4px
2px
small
32px
4px
2px
medium
37px
8px
4px
large
48px
—
—
Border: 1px solid var(--color-border-primary)
Border radius: var(--radius) (6px)
Focus ring: box-shadow: 0 0 0 3px var(--color-bg-fill-highlight-75)
Card (LemonCard)
Border: 1px solid (default border color)
Padding: 24px (p-6)
Border radius: var(--radius) (6px)
Background: bg-surface-primary
Hover (when hoverEffect): box-shadow: var(--shadow-elevation-3000) + scale(1.01)
Modal (LemonModal)
Border: 1px solid var(--border-bold)
Border radius: var(--radius) (6px)
Shadow: var(--modal-shadow-elevation)
Header/Content/Footer padding: 16px (1rem)
Backdrop: rgb(0 0 0 / 20%), blur 5px
Transition: 200ms
Popover / Menu
Background: bg-surface-primary
Border: 1px solid var(--color-border-primary)
Border radius: var(--radius-lg) (10px)
Shadow: var(--shadow-elevation-3000)
Min width: 8rem
Max width: 200px
Toast
Padding: 12px (0.75rem)
Border: 1px solid var(--secondary-3000-button-border)
Border radius: var(--radius) (6px)
Shadow: var(--shadow-elevation-3000)
Font: 0.875rem, weight 500
Layout
Token
Value
--project-navbar-width
215px
--project-navbar-width-collapsed
45px
--project-panel-width
245px
--side-panel-bar-width
40px
Breakpoints
Token
Value
sm
576px
md
768px
lg
992px
xl
1200px
2xl
1600px
Dark Mode
Selector: [theme="dark"] on body
Tailwind: darkMode: ['selector', '[theme="dark"]']
Accent swaps: orange (light) / yellow (dark)
Surfaces swap to neutral-cool 800-950 range
Borders swap to neutral-cool 600-800
Z-Index Scale
Token
Value
--z-top
9999
--z-bottom-notice
1450
--z-tooltip
1300
--z-popover
1200
--z-modal
1100
--z-hedgehog-buddy
1050
--z-drawer
900
--z-main-nav
750
--z-lemon-sidebar
700
--z-top-navigation
550
--z-content-overlay
500
--z-raised
5
Animations
Focus ring transition: box-shadow 0.1s ease-in-out
Modal transition: 200ms
Fade in: 0.4s ease-out
Overlay fade: 0.2s ease-out
Disabled opacity: 0.65 (--opacity-disabled)
Component Library
Three-tier architecture:
Primitives (frontend/src/lib/ui/) — Low-level React primitives (Button, Combobox, DropdownMenu, etc.)
Lemon UI (frontend/src/lib/lemon-ui/) — 50+ published components (LemonButton, LemonInput, LemonModal, LemonTable, etc.)
Composed components (frontend/src/lib/components/) — Feature-specific composed components built on Lemon UI
Always prefer Lemon UI components over custom implementations.