OpenHands-Design/DESIGN.md

OpenHands UI Design System

1. Visual Theme & Atmosphere

OpenHands is a dark-first AI agent platform built on a near-black monochrome canvas. The entire experience lives on a 0 0% 5% HSL background — effectively #0d0d0d — with 0 0% 98% foreground text that reads as warm off-white. Every surface is a shade of neutral grey scaled in 2–5% lightness increments, creating depth through tonal variation rather than color. The only chromatic moments are semantic: green for success, red-orange for danger, amber for warnings, and blue for informational states.

Typography is carried by Inter (sans-serif) for all UI text and JetBrains Mono for code, terminals, and technical labels. The type system is weight-restrained — font-medium (500) is the workhorse, font-semibold (600) for headings and emphasis, and font-normal (400) for body. Bold (700) is rare and reserved for maximum emphasis.

The UI framework is React + Tailwind CSS + Radix primitives (shadcn/ui pattern). All colors flow through CSS custom properties declared in :root and consumed via hsl(var(--token)) in the Tailwind config. This means every color in the system is overridable by changing a single HSL triplet.

Key characteristics:

• Near-black monochrome canvas (#0d0d0d background, #fafafa foreground)
• Neutral grey surface scale in 2–5% lightness increments (5% → 7% → 8% → 12% → 14% → 18%)
• Inter + JetBrains Mono dual-font system
• HSL-based CSS custom property architecture for full theme overridability
• Tailwind utility-first styling with Radix UI headless primitives
• transition-colors as the dominant transition (958 uses) — UI feels responsive but not animated
• Dark-only primary mode; light and sepia modes exist as secondary via class-map theming

---

2. Color Palette & Roles

All colors are declared as HSL triplets (without the hsl() wrapper) in CSS custom properties. Tailwind maps them as hsl(var(--token)).

Core Surfaces

Token	HSL	Hex	Role
--background	0 0% 5%	#0d0d0d	Page background, app shell
--card	0 0% 7%	#121212	Card surfaces, elevated containers
--secondary	0 0% 8%	#141414	Secondary surfaces, sidebar accent
--popover	0 0% 7%	#121212	Dropdown menus, popovers
--muted	0 0% 12%	#1f1f1f	Muted backgrounds, hover fills, badges, tooltip surfaces
--border / --input	0 0% 14%	#242424	Borders, input borders, dividers
--muted-hover	0 0% 18%	#2e2e2e	Hover state for muted surfaces
--modal-background	Inherits --background	#0d0d0d	Dialogs, sheets, modals (can diverge)

Core Text

Token	HSL	Hex	Role
--foreground	0 0% 98%	#fafafa	Primary text, headings
--muted-foreground	0 0% 55%	#8c8c8c	Secondary text, labels, placeholders, icons
--primary	0 0% 100%	#ffffff	Maximum emphasis text, primary buttons
--primary-foreground	0 0% 0%	#000000	Text on primary (white) surfaces
--accent	0 0% 100%	#ffffff	Accent elements (matches primary in dark)

Sidebar (inherits core but isolated for overridability)

Token	HSL	Role
--sidebar-background	0 0% 5%	Sidebar background
--sidebar-foreground	0 0% 98%	Sidebar text
--sidebar-accent	0 0% 8%	Sidebar hover/active background
--sidebar-border	0 0% 14%	Sidebar dividers
--sidebar-ring	0 0% 50%	Sidebar focus ring

Semantic / Status

Token	HSL	Hex	Role
--success	142 71% 45%	#22c55e	Success states, running indicators
--success-foreground	142 71% 76%	#86efac	Success text on dark surfaces
--warning	38 92% 50%	#f59e0b	Warning states, caution badges
--info	217 91% 60%	#3b82f6	Informational states, links
--destructive	0 72% 51%	#dc2626	Error states, danger actions, delete
--destructive-foreground	0 0% 98%	#fafafa	Text on destructive surfaces
--ring	0 0% 80%	#cccccc	Focus rings (1px, keyboard-only via focus-visible:)

Gradients & Decorative

Token	Value	Role
--gradient-card-hover	linear-gradient(180deg, hsl(0 0% 9%) 0%, hsl(0 0% 7%) 100%)	Subtle card hover gradient
--shadow-card	0 1px 2px 0 hsl(0 0% 0% / 0.3)	Default card shadow

Hover Backgrounds

Surface	Hover Token	Use
Dark surfaces (cards, nav items, menus, rows)	hover:bg-muted/60	Standard hover — the single canonical dark-surface hover
White/primary buttons	hover:bg-primary/85	Light grey hover on white buttons (85% opacity white)

Canonical dark-surface hover: hover:bg-muted/60 — used consistently across the codebase. Do not mix /40, /50, /70 variants. Canonical primary-button hover: hover:bg-primary/85 — never use hover:bg-muted/60 on a bg-primary/bg-white button (causes dark flash).

---

3. Typography Rules

Font Families

Role	Family	CSS Variable	Tailwind Class	Fallbacks
UI / Body	Inter	--font-sans	font-sans	system-ui, sans-serif
Code / Technical	JetBrains Mono	--font-mono	font-mono	monospace

Fonts are loaded via Google Fonts @import in index.css.

Type Scale

The app uses Tailwind's default type scale. These are the canonical sizes ordered by frequency of use:

Tailwind Class	Size	Uses	Role
text-sm	14px / 0.875rem	711	Primary body text, labels, button text, descriptions
text-xs	12px / 0.75rem	427	Secondary text, metadata, badges, menu items, captions
text-base	16px / 1rem	52	Larger body text, input text, chat messages
text-lg	18px / 1.125rem	67	Section sub-headings, dialog titles
text-xl	20px / 1.25rem	28	Page sub-headings
text-2xl	24px / 1.5rem	31	Page headings, modal titles
text-3xl	30px / 1.875rem	12	Hero headings, landing sections

Arbitrary Font Sizes (to normalize)

These arbitrary sizes appear frequently and should be migrated to the standard scale or formalized as tokens:

Arbitrary	Count	Recommended Replacement
text-[11px]	46	text-xs (12px) — or formalize as --text-2xs if 11px is intentional
text-[10px]	20	text-xs (12px) — or formalize as --text-2xs
text-[12px]	8	text-xs (already 12px — use the utility)
text-[40px]	5	text-4xl (36px) or formalize as hero display size
text-[28px]	3	text-3xl (30px) or formalize
text-[32px]	1	text-3xl (30px) or text-4xl (36px)
text-[8px]	1	Likely a micro label — evaluate if needed

Font Weight Scale

Tailwind Class	Weight	Uses	Role
font-medium	500	304	Labels, nav items, badges (note: buttons use font-normal)
font-semibold	600	229	Headings, section titles, strong emphasis
font-normal	400	106	Body text, descriptions, long-form content
font-bold	700	29	Maximum emphasis (use sparingly)
font-light	300	13	De-emphasized text (use sparingly)

Line Height

Tailwind Class	Uses	Role
leading-4	38	Tight — compact UI, badges
leading-6	34	Standard — body text
leading-relaxed	33	Comfortable — long-form, descriptions
leading-5	28	Medium — labels, short text
leading-tight	27	Condensed — headings
leading-snug	17	Slightly condensed
leading-none	16	No leading — single-line elements

Letter Spacing

Tailwind Class	Uses	Role
tracking-wide	28	Uppercase labels, section headers
tracking-wider	20	Small-caps metadata
tracking-tight	19	Display headings

Canonical Patterns

Body text: text-sm font-normal text-foreground Label: text-sm font-medium text-foreground Secondary text: text-sm text-muted-foreground Metadata/caption: text-xs text-muted-foreground Uppercase category: text-[11px] font-medium uppercase tracking-wide text-muted-foreground Heading (page): text-2xl font-semibold text-foreground Heading (section): text-lg font-semibold text-foreground Code/mono: text-sm font-mono

---

4. Component Stylings

Buttons (Button component — src/components/ui/button.tsx)

Base classes (all variants): inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-normal ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 active:scale-[0.97] [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0

Variant	Background	Text	Border	Hover	Use
default	bg-primary	text-primary-foreground	—	hover:bg-primary/85	Primary CTA (white button, black text)
destructive	bg-destructive	text-destructive-foreground	—	hover:bg-destructive/85	Delete, danger actions
outline	bg-background	—	border border-input	hover:bg-muted hover:text-foreground	Secondary actions (most used — 53 instances)
light	bg-primary	text-primary-foreground	border border-input	hover:bg-primary/85	High-contrast primary on dark bg (token-based, no raw bg-white)
secondary	bg-secondary	text-secondary-foreground	—	hover:bg-muted-hover	Tertiary actions
muted	bg-muted	text-muted-foreground	—	hover:bg-muted-hover hover:text-foreground	Subdued actions
ghost	transparent	—	—	hover:bg-muted hover:text-foreground	Minimal chrome actions
link	transparent	text-primary underline-offset-4	—	hover:underline	Inline links

Primary button convention: All white/primary buttons use bg-primary text-primary-foreground hover:bg-primary/85. Never use bg-white text-black hover:bg-muted/60 inline — the dark hover on a white button is incorrect. Use the Button component or match its tokens.

Size	Height	Padding	Font
default	h-10	px-4 py-2	text-sm
sm	h-10	px-3	text-sm
xs	h-10	px-3	text-xs
lg	h-11	px-8	text-sm
icon	h-10 w-10	—	—

Cards & Containers

There is no dedicated Card primitive — cards are composed with utilities.

Standard card recipe:

bg-card border border-border rounded-lg p-4

Elevated card:

bg-card border border-border rounded-xl p-6 shadow-lg

Interactive card:

bg-card border border-border rounded-lg p-4 transition-colors hover:border-white/30

Glass / backdrop card:

bg-card/70 border border-border/60 rounded-lg p-6 shadow-lg backdrop-blur-xl supports-[backdrop-filter]:bg-card/50

Inputs (Input component — src/components/ui/input.tsx)

Standard input:

h-10 w-full rounded-md border border-border bg-muted/40 px-3 py-2 text-base md:text-sm
ring-offset-background focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring
focus-visible:ring-offset-2 focus-visible:bg-muted/60 hover:bg-muted/60
placeholder:text-muted-foreground
disabled:cursor-not-allowed disabled:opacity-50 disabled:bg-muted/30

Canonical focus style (all inputs, textareas, selects must match):

ring-offset-background focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:bg-muted/60

Key rules:

• Always use focus-visible: (keyboard-only), never focus: (fires on click too)
• Always include ring-offset-background and focus-visible:ring-offset-2
• Always include focus-visible:bg-muted/60 for the subtle fill on focus
• Search inputs (type="search") have appearance: none in global CSS to strip browser default focus chrome

Size variants (via SearchInput wrapper):

• sm: h-9 + pl-8 pr-8 (icon padding)
• default: h-10 + pl-9 pr-9
• lg: h-11 + pl-10 pr-10

Dropdown Menus (DropdownMenu — Radix-based)

Menu content:

z-[100] min-w-[8rem] overflow-y-auto rounded-md border bg-popover p-1 text-popover-foreground shadow-md

Menu item:

group relative flex cursor-default select-none items-center rounded-md px-2 py-1.5 text-sm
transition-colors focus:bg-muted/60 data-[highlighted]:bg-muted/60

Icon treatment in menu items:

• Default: [&_svg]:text-muted-foreground (grey)
• Hover/highlight: group-hover:[&_svg]:!text-foreground (white)

Popover

Content:

z-50 max-h-[min(24rem,calc(100dvh-2rem))] shadow-md rounded-[12px] border border-border
bg-sidebar p-6 text-sidebar-foreground overflow-y-auto

Navigation (LeftNav sidebar)

• Collapsed: 56px wide icon rail
• Expanded: 240px+ with text labels
• Items: flex items-center gap-2 rounded-md px-3 py-1.5 text-xs transition-colors
• Icons: w-4 h-4 text-muted-foreground group-hover:text-white
• Active: bg-muted/60 text-foreground
• Hover: hover:bg-muted/60 hover:text-white

Scrollbar Variants

Class	Width	Behavior	Use
.dropdown-scroll	6px thin	Always visible	Menus, popovers
.custom-scrollbar	8px thin	Always visible	Chat, main content
.scrollbar-on-hover	8px thin	Visible on hover only	Chat threads
.hide-scrollbar	hidden	Hidden	Horizontal scroll areas

All scrollbar thumbs: hsl(var(--muted-foreground) / 0.5) with hover at 0.7.

Tooltips

All tooltips use bg-muted for a lighter surface that visually separates from the dark page background.

Standard tooltip (rounded-md):

whitespace-nowrap rounded-md bg-muted px-2 py-1 text-xs text-foreground shadow-md

Pill tooltip (rounded-full):

bg-muted text-foreground text-xs rounded-full shadow-lg px-3 py-1

Dialog Close Button

The dialog close "×" button has no focus ring (focus ring removed to avoid visual noise on click):

absolute right-4 top-4 inline-flex h-7 w-7 items-center justify-center rounded-md opacity-70
ring-offset-background transition-colors hover:opacity-100 hover:bg-muted/60 focus:outline-none

---

5. Layout Principles

Spacing System

The app uses Tailwind's default 4px-based spacing scale. These are the most common values by usage:

Gaps (flex/grid):

Class	Px	Uses	Context
gap-2	8px	414	Standard gap — between items in rows, icon + label
gap-3	12px	144	Comfortable gap — form groups, card content
gap-4	16px	110	Generous gap — section spacing, grid layouts
gap-1	4px	86	Tight gap — inline badges, compact lists
gap-1.5	6px	59	Between tight and standard
gap-6	24px	50	Large gap — major sections

Padding:

Class	Px	Uses	Context
px-4	16px	216	Standard horizontal padding — buttons, cards
px-3	12px	212	Compact horizontal padding — menu items, inputs
py-2	8px	200	Standard vertical padding — buttons, rows
px-2	8px	198	Tight horizontal padding — badges, pills
py-1	4px	138	Compact vertical padding
py-1.5	6px	76	Slightly more than compact
p-4	16px	89	Uniform card/container padding
p-6	24px	26	Generous container/dialog padding

Grid & Container

• Max container width: 1400px (via Tailwind container config with 2rem padding)
• Primary layout: sidebar (56–240px) + main content area
• Settings layout: custom CSS vars for independent nav/main vertical inset
  • --settings-nav-padding-top/bottom: 2rem
  • --settings-main-padding-top/bottom: 2rem

Whitespace Philosophy

• Dense but breathable: The app uses text-sm (14px) as the default with gap-2 (8px) standard spacing — dense enough for a productivity tool, but never cramped.
• Consistent rhythm: Sections are separated by border-t border-border dividers with my-3 (12px) vertical margin. No heavy horizontal rules.
• Surface differentiation over spacing: Rather than using large whitespace to separate areas, the app uses background color shifts (bg-background → bg-card → bg-muted) to create visual sections.

Border Radius Scale

Defined via CSS custom properties and Tailwind mapping:

Token	Value	Tailwind	Uses	Role
--radius	0.375rem (6px)	rounded-lg	112	Standard container radius — cards, panels
calc(--radius - 2px)	0.25rem (4px)	rounded-md	501	Default element radius — buttons, inputs, menu items
calc(--radius - 4px)	0.125rem (2px)	rounded-sm	12	Subtle radius — small inline elements
--radius-modal	0.75rem (12px)	rounded-modal	—	Modal/dialog/popover radius
—	—	rounded-xl	90	Larger cards, featured containers
—	—	rounded-2xl	23	Hero elements, large cards
—	—	rounded-full	185	Avatars, pills, circular buttons, badges

Arbitrary radii to normalize:

Arbitrary	Count	Recommended
rounded-[6px]	20	rounded-lg (already 6px via --radius)
rounded-[100px]	15	rounded-full (same visual effect)
rounded-[12px]	8	rounded-modal or rounded-xl (12px)
rounded-[4px]	4	rounded-md (already 4px)

---

6. Depth & Elevation

Shadow Scale

Tailwind	Uses	Role
shadow-sm	21	Subtle elevation — small cards, badges
shadow	22	Default — standalone cards
shadow-md	31	Medium — dropdown menus, popovers
shadow-lg	49	Most used — modals, dialogs, elevated panels
shadow-xl	14	High emphasis — floating panels
shadow-2xl	5	Maximum — overlay dialogs
shadow-inner	8	Inset — pressed buttons, input focus
shadow-none	19	Reset — flat elements

Custom Shadows

Token	Value	Role
--shadow-card	0 1px 2px 0 hsl(0 0% 0% / 0.3)	Card resting shadow

Elevation Levels

Level	Treatment	Use
0 — Flat	No shadow, bg-background	Page background
1 — Surface	bg-card + border border-border	Cards, content panels
2 — Raised	shadow-md + border	Dropdown menus, popovers
3 — Floating	shadow-lg + border	Modals, dialogs, sheets
4 — Overlay	shadow-xl or shadow-2xl	Full-screen overlays, drawers

Border System

• Standard border: border border-border (1px solid hsl(0 0% 14%))
• Subtle border: border border-border/60 (reduced opacity)
• Interactive hover: hover:border-white/30 or hover:border-muted-foreground/30
• Section divider: border-t border-border (horizontal rule) or border-t border-sidebar-border (in sidebar)
• Focus ring: ring-1 ring-ring ring-offset-2 ring-offset-background (1px, focus-visible: only)

---

7. Do's and Don'ts

Colors

Do	Don't
Use text-foreground for primary text	Use text-white for primary text (278 instances to migrate)
Use text-muted-foreground for secondary text	Use text-stone-400 or text-gray-400 (raw palette)
Use bg-background for page surfaces	Use bg-black or hardcoded bg-[#0d0d0d]
Use bg-card for elevated surfaces	Use bg-stone-800 or bg-neutral-900
Use bg-muted for subtle backgrounds	Use bg-stone-700 or bg-gray-800
Use border-border for all borders	Use border-stone-700 or border-gray-700
Use text-success-foreground for success text	Use text-emerald-400 or text-green-400
Use text-destructive for error text	Use text-red-500 or text-rose-500
Use hover:text-foreground for hover text brightening	Use hover:text-white except in sidebar context

Semantic status colors: Use text-success / bg-success, text-warning / bg-warning, text-info / bg-info, text-destructive / bg-destructive — never raw chromatic palette classes like text-green-500, bg-amber-400, text-blue-500, etc.

Current debt: themeAppClassMap.ts and NewUserExperienceFlowchart.tsx still use raw stone-* / rgb() values (theme definition maps — intentionally deferred; requires per-theme CSS variable architecture). ChatThread.tsx messageTypeColors has 4 remaining raw palette colors (orange-500, indigo-500, purple-500, pink-500) for categorical distinctness — no semantic tokens defined for these yet.

Typography

Do	Don't
Use text-sm (14px) as default body size	Use text-[14px] or arbitrary pixel values
Use text-xs (12px) for small/meta text	Use arbitrary pixel sizes for general text
Use Tailwind scale (text-lg, text-xl, text-2xl)	Use arbitrary sizes like text-[28px], text-[40px]
Use font-medium as default weight	Use font-bold for general emphasis
Keep heading hierarchy: 2xl → xl → lg → base	Skip levels or invert the scale

Border Radius

Do	Don't
Use rounded-md (4px) for buttons, inputs, menu items	Use rounded-[4px] (same value, less maintainable)
Use rounded-lg (6px) for cards, containers	Use rounded-[6px] (use the token)
Use rounded-xl or rounded-modal for dialogs	Use rounded-[12px] (use the token)
Use rounded-full for pills and avatars	Use rounded-[100px] (use rounded-full)

Spacing

Do	Don't
Use gap-2 (8px) as standard item gap	Use arbitrary gap values
Use px-3/px-4 for horizontal padding	Mix px-2.5 and px-3.5 without reason
Use p-4 for card padding, p-6 for dialogs	Use p-[24px] (same as p-6)
Use my-3 for section divider spacing	Use inconsistent vertical margins around dividers

Hover & Interaction

Do	Don't
Use hover:bg-muted/60 as standard hover bg on dark surfaces	Mix /40, /50, /60, /70 without hierarchy
Use hover:bg-primary/85 for white/primary buttons	Use hover:bg-muted/60 on white buttons (creates dark hover)
Use transition-colors for color-only changes	Use transition-all when only color changes
Use duration-200 as standard transition speed	Mix duration-150, duration-200, duration-300 randomly
Use group + group-hover: for parent-child hover	Apply hover to each child independently
Use active:scale-[0.97] for button press feedback	Use active:scale-95 (inconsistent with Button component)

Icons

Do	Don't
Use w-4 h-4 as standard icon size in menus/buttons	Use w-3 h-3 or w-5 h-5 without size hierarchy reason
Set icon color to text-muted-foreground by default	Leave icons inheriting parent text color (appears too bright)
Brighten on hover: group-hover:text-foreground or group-hover:text-white	Omit icon hover transitions
Use shrink-0 on icons in flex layouts	Let icons squish when text wraps

---

8. Responsive Behavior

Breakpoints (Tailwind defaults)

Prefix	Min Width	Key Changes
(none)	0px	Mobile-first base styles
sm	640px	Wider cards, more padding
md	768px	Multi-column layouts begin, md:text-sm on inputs
lg	1024px	Full sidebar visible, expanded grid
xl	1280px	Maximum content width, full feature layout
2xl	1400px	Container max-width ceiling

Touch Targets

• Minimum interactive height: h-10 (40px) for buttons and inputs
• Small variant: h-9 (36px) for compact contexts
• Icon buttons: h-10 w-10 (40×40px)
• Menu items: py-1.5 (6px) vertical padding at text-sm yields ~32px touch target

Collapsing Strategy

• Sidebar: collapses from expanded (labels) to icon-only rail on narrow viewports
• Navigation menus: horizontal → hamburger on mobile
• Grid layouts: multi-column → single-column stacked
• Container padding: reduces from p-6 → p-4 → p-3 at smaller breakpoints

---

9. Interaction & Motion

Transitions

Pattern	Uses	When
transition-colors	958	Default — use for any color/bg/border change
transition-opacity	96	Fade in/out
transition-all	96	Multiple properties changing simultaneously
transition-transform	59	Scale/translate animations

Duration

Duration	Uses	When
duration-200	~48	Standard — local, small feedback: toggles, chevron rotation, sidebar width, card/row hovers, opacity on hover, dialogs
duration-300	~34	Layout motion — panel/drawer resize, sheet exit, canvas split, login/marketing card hover, grid row animations

Easing

Easing	Uses	When
ease-in-out	111	Default — smooth symmetrical transitions
ease-out	52	Enter animations — elements arriving

Framer Motion Patterns (23 files)

• AnimatePresence for mount/unmount transitions
• Standard enter: initial={{ opacity: 0 }} → animate={{ opacity: 1 }}
• Standard exit: exit={{ opacity: 0 }}
• Duration: typically 0.2s–0.3s
• Used for: panel reveals, notification toasts, drawer slides, loading states

Interactive Feedback

• Button press: active:scale-[0.97] (slight shrink on click)
• Card hover: hover:scale-[1.02] (subtle grow, 12 uses)
• Focus: focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-2 (1px ring, keyboard-only)

---

10. Agent Prompt Guide

Quick Color Reference

• Page background: bg-background → hsl(0 0% 5%) → #0d0d0d
• Primary text: text-foreground → hsl(0 0% 98%) → #fafafa
• Secondary text: text-muted-foreground → hsl(0 0% 55%) → #8c8c8c
• Card surface: bg-card → hsl(0 0% 7%) → #121212
• Border: border-border → hsl(0 0% 14%) → #242424
• Hover background: bg-muted/60 → hsl(0 0% 12% / 0.6)
• Success: text-success-foreground → hsl(142 71% 76%) → #86efac
• Error: text-destructive → hsl(0 72% 51%) → #dc2626

Example Component Prompts

• "Create a settings card": bg-card border border-border rounded-lg p-4. Title at text-lg font-semibold text-foreground. Description at text-sm text-muted-foreground. Action button: <Button variant="outline">.
• "Create a sidebar menu item": group flex items-center gap-2 rounded-md px-3 py-1.5 text-xs text-sidebar-foreground hover:text-white hover:bg-muted/60 transition-colors. Icon: w-4 h-4 shrink-0 text-muted-foreground transition-colors group-hover:text-white.
• "Create a dropdown menu": Use DropdownMenu + DropdownMenuTrigger + DropdownMenuContent + DropdownMenuItem from src/components/ui/dropdown-menu.tsx. Icons auto-styled grey → white on hover via the component's built-in [&_svg] selectors.
• "Create a form field": Label at text-sm font-medium text-foreground mb-1.5. Use <Input> component (never inline raw <input> with custom focus styles). Help text at text-xs text-muted-foreground mt-1.
• "Create a tooltip": bg-muted text-foreground text-xs rounded-md px-2 py-1 shadow-md. For pill-style: use rounded-full instead of rounded-md.
• "Create a status badge": inline-flex items-center rounded-full px-2 py-0.5 text-[11px] font-medium. Success: bg-success/10 text-success-foreground. Error: bg-destructive/10 text-destructive.

Iteration Guide

1. Always use semantic color tokens — never raw palette colors (stone-*, gray-*, slate-*). Every color should trace back to a --css-variable.
2. text-sm is the default — don't reach for text-base unless the context genuinely needs larger text (e.g., chat messages, hero content).
3. rounded-md for elements, rounded-lg for containers — this is the consistent radius hierarchy. Dialogs get rounded-xl or rounded-modal.
4. gap-2 is the standard — 8px between items in any flex/grid layout. Use gap-4 for major sections.
5. Icons are always text-muted-foreground by default and brighten to text-foreground or text-white on hover via group + group-hover:.
6. transition-colors duration-200 is the standard animation. Don't add transition-all unless multiple property types are actually changing.
7. hover:bg-muted/60 is the canonical hover background. Use it consistently across menus, nav items, and interactive rows.
8. The Button component handles its own variants — don't rebuild button styles from scratch. Use variant="outline" for most secondary actions.