Spaces:
Running
Running
| # 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 <select> with consistent styling | |
| ``` | |
| ## Quick Start | |
| ### Install with npx | |
| From your project root: | |
| ```bash | |
| npx openhands-design | |
| ``` | |
| This adds `./OpenHands-Design/` (including `DESIGN.md`, tokens, and UI components). Then ask your AI assistant to use **`DESIGN.md`** for UI work. If the folder already exists, run `npx openhands-design --force` to replace it. | |
| ### 1. Install dependencies | |
| ```bash | |
| npm install clsx tailwind-merge class-variance-authority @radix-ui/react-slot lucide-react tailwindcss-animate | |
| ``` | |
| ### 2. Copy files into your project | |
| ```bash | |
| # Copy the design tokens and global CSS | |
| cp OpenHands-Design/src/globals.css your-project/src/globals.css | |
| # Copy the Tailwind config (or merge into your existing one) | |
| cp OpenHands-Design/tailwind.config.js your-project/tailwind.config.js | |
| # Copy the utility helper | |
| cp OpenHands-Design/src/lib/utils.ts your-project/src/lib/utils.ts | |
| # Copy the UI components | |
| cp -r OpenHands-Design/src/components/ui/ your-project/src/components/ui/ | |
| ``` | |
| ### 3. Import globals.css | |
| In your app entry point (e.g., `main.tsx` or `App.tsx`): | |
| ```tsx | |
| import './globals.css'; | |
| ``` | |
| ### 4. Add the dark class | |
| The system is dark-first. Add the `dark` class to your `<html>` tag: | |
| ```html | |
| <html lang="en" class="dark"> | |
| ``` | |
| ### 5. Start using components | |
| ```tsx | |
| import { Button } from './components/ui/button'; | |
| import { Input } from './components/ui/input'; | |
| import { SearchInput } from './components/ui/search-input'; | |
| import { NativeSelect } from './components/ui/native-select'; | |
| function Example() { | |
| return ( | |
| <div className="flex flex-col gap-4 bg-background p-6 text-foreground"> | |
| <h1 className="text-2xl font-semibold">Settings</h1> | |
| <p className="text-sm text-muted-foreground">Manage your account.</p> | |
| <Input placeholder="Your name" /> | |
| <NativeSelect> | |
| <option>Option A</option> | |
| <option>Option B</option> | |
| </NativeSelect> | |
| <div className="flex gap-2"> | |
| <Button>Save</Button> | |
| <Button variant="outline">Cancel</Button> | |
| <Button variant="destructive">Delete</Button> | |
| </div> | |
| </div> | |
| ); | |
| } | |
| ``` | |
| ## 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 `<html>` 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 | |