# OpenHands Design System A portable design system extracted from the OpenHands UI. Drop it into any React + Tailwind project to get a consistent dark-first interface with semantic color tokens, pre-built components, and a comprehensive style guide. ## What's Included ``` OpenHands-Design/ DESIGN.md # Full design system specification README.md # This file tailwind.config.js # Tailwind theme (colors, radii, fonts, animations) src/ globals.css # CSS custom properties (design tokens) + base resets lib/ utils.ts # cn() helper (clsx + tailwind-merge) components/ui/ button.tsx # Button with 8 variants (default, destructive, outline, light, secondary, muted, ghost, link) input.tsx # Text input with unified focus style search-input.tsx # Search input with icon, clear button, and 3 sizes native-select.tsx # Native
); } ``` ## Using with AI Agents (Cursor, Copilot, etc.) The `DESIGN.md` file is structured as an AI-readable specification. Two ways to use it: ### Option A: Cursor Rule (recommended) Create `.cursor/rules/design-system.md` in your project: ```markdown When building UI components, follow the design system in /DESIGN.md. Key rules: - Use semantic color tokens (bg-card, text-foreground, border-border) — never raw palette classes - Use the Button, Input, SearchInput, and NativeSelect components — never raw HTML with inline styles - Hover on dark surfaces: hover:bg-muted/60 - Hover on white/primary buttons: hover:bg-primary/85 - Focus rings: focus-visible:ring-1 (keyboard-only, 1px) - Default text: text-sm font-normal text-foreground - Secondary text: text-sm text-muted-foreground - Standard gap: gap-2 (8px) - Standard card: bg-card border border-border rounded-lg p-4 ``` Every Cursor conversation will now follow your design system automatically. ### Option B: Direct prompt Paste this at the start of a conversation: > Build this feature following the design system in DESIGN.md. Use semantic tokens for all colors, the Button component for actions, and the Input component for form fields. ## Token Architecture All colors are HSL triplets stored as CSS custom properties. Tailwind maps them via `hsl(var(--token))`. ``` Background scale (darkest → lightest): --background 5% #0d0d0d Page background --card 7% #121212 Cards, elevated surfaces --secondary 8% #141414 Secondary surfaces --muted 12% #1f1f1f Hover fills, badges, tooltips --border 14% #242424 Borders, dividers --muted-hover 18% #2e2e2e Hover on muted surfaces Text scale: --foreground 98% #fafafa Primary text --muted-foreground 55% #8c8c8c Secondary text, placeholders --primary 100% #ffffff Maximum emphasis, button bg --primary-foreground 0% #000000 Text on white buttons Semantic colors: --success hsl(142 71% 45%) Green — success states --warning hsl(38 92% 50%) Amber — warnings, in-progress --info hsl(217 91% 60%) Blue — links, informational --destructive hsl(0 72% 51%) Red — errors, danger ``` ## Button Variants | Variant | Look | Use | |---------|------|-----| | `default` | White bg, black text | Primary CTA | | `destructive` | Red bg, white text | Delete, danger | | `outline` | Transparent, border | Secondary actions | | `light` | White bg, border | High-contrast primary | | `secondary` | Dark bg | Tertiary actions | | `muted` | Muted bg, grey text | Subdued actions | | `ghost` | Transparent, no border | Minimal chrome | | `link` | Underline on hover | Inline links | ## Customization ### Changing the color scheme Edit the HSL values in `globals.css`. Every UI element updates automatically: ```css :root { --background: 220 20% 5%; /* Add a blue tint */ --card: 220 15% 8%; --border: 220 10% 16%; } ``` ### Adding a light theme Create a new class block in `globals.css` with inverted values: ```css .light { --background: 0 0% 100%; --foreground: 0 0% 5%; --card: 0 0% 97%; --border: 0 0% 88%; /* ... */ } ``` Then toggle `class="light"` on the `` element. ## Reference See [DESIGN.md](./DESIGN.md) for the complete specification including: 1. Visual theme and atmosphere 2. Full color palette with hex values 3. Typography rules and type scale 4. Component styling recipes 5. Layout principles and spacing system 6. Depth and elevation system 7. Do's and Don'ts 8. Responsive behavior 9. Interaction and motion patterns 10. AI agent prompt guide 11. Normalization backlog ## License MIT