git:20260413.7bd7e4c to git:20260501.dfc0d54

# ClawHub Design System

This document outlines the design rules, patterns, and guidelines for the ClawHub platform to ensure consistency, accessibility, and maintainability across all components.

---

## Color System

### Brand Palette (OpenClaw)

ClawHub uses a strict **3-5 color palette** based on the OpenClaw brand:

### Rules

1. **Never exceed 5 colors** without explicit design approval

2. **Never use purple/violet prominently** unless explicitly requested

3. **Always override text color** when changing background color to ensure contrast

4. **Use semantic tokens** (`--accent`, `--ink`, `--surface`) instead of raw colors

---

## Typography

### Font Stack

```css

```

### Scale

### Rules

1. **Maximum 2 font families** per page

2. **Line height 1.4-1.6** for body text (use `leading-relaxed`)

3. **Never use decorative fonts** for body text

4. **Minimum font size: 14px** for readability

5. Use `text-balance` or `text-pretty` for titles

---

## Layout

### Method Priority

Use this hierarchy for layout decisions:

1. **Flexbox** - Default for most layouts

2. **CSS Grid** - Only for complex 2D layouts (cards, galleries)

3. **Never use floats** or absolute positioning unless absolutely necessary

### Spacing Scale

```css

```

### Grid Patterns

#### Auto-fit Grid (Recommended for Cards)

```css

grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));

```

- Automatically adjusts columns based on container width

- Prevents orphan items on partial rows

- Maintains consistent card widths

#### Fixed Grid (When exact columns needed)

```css

/* 3-column at desktop, 2 at tablet, 1 at mobile */

grid-template-columns: repeat(3, minmax(0, 1fr));

@media (max-width: 860px) {

grid-template-columns: repeat(2, minmax(0, 1fr));

}

@media (max-width: 520px) {

grid-template-columns: 1fr;

}

```

### Container Widths

---

## Components

### Cards

```css

.card {

padding: var(--space-4);

border: 1px solid var(--line);

border-radius: var(--r-md);

background: var(--surface);

}

```

**Rules:**

- Always use `display: flex; flex-direction: column;` for consistent height

- Add `flex: 1` to content area for equal-height cards in grids

- Include hover state with `border-color` and subtle `box-shadow`

### Buttons

**Rules:**

- Always include visible focus state

- Minimum touch target: 44x44px on mobile

- Include `aria-label` when icon-only

### Form Controls

- Labels above inputs (not inline)

- Error states use `--status-error-fg`

- Focus rings use `--accent` with 0.2 opacity

- Minimum input height: 40px

---

## Responsive Breakpoints

```css

/* Mobile first - base styles for mobile */

@media (min-width: 520px) {

/* Small tablets, large phones */

}

@media (min-width: 640px) {

/* Tablets */

}

@media (min-width: 860px) {

/* Small desktops, landscape tablets */

}

@media (min-width: 1024px) {

/* Desktops */

}

@media (min-width: 1280px) {

/* Large desktops */

}

```

### Rules

1. **Mobile-first approach** - Base styles target mobile

2. **Progressive enhancement** - Add complexity as viewport increases

3. **Test intermediate breakpoints** - Avoid jarring layout jumps

4. **Never hide critical content** on mobile

---

## Accessibility

### Color Contrast

- Normal text: Minimum 4.5:1 ratio

- Large text (18px+): Minimum 3:1 ratio

- Interactive elements: Minimum 3:1 ratio

### Focus States

```css

:focus-visible {

outline: 2px solid var(--accent);

outline-offset: 2px;

border-radius: 2px;

}

```

### Screen Readers

- Use `sr-only` class for visually hidden but accessible text

- Always include `alt` text for images (empty `alt=""` for decorative)

- Use semantic HTML elements (`main`, `nav`, `article`, `section`)

- Proper heading hierarchy (h1 > h2 > h3, no skipping)

### Motion

```css

/* Respect user preference */

@media (prefers-reduced-motion: reduce) {

* {

animation-duration: 0.01ms !important;

transition-duration: 0.01ms !important;

}

}

```

---

## Animation

### Timing

```css

--transition-fast: 150ms;

--transition-base: 200ms;

--transition-slow: 300ms;

```

### Easing

- Use `ease` or `ease-out` for most transitions

- Use `ease-in-out` for enter/exit animations

- Never use `linear` except for continuous animations

### Rules

1. **Subtle by default** - Avoid flashy animations

2. **Purpose-driven** - Animation should provide feedback

3. **Respect preferences** - Support `prefers-reduced-motion`

4. **Performance** - Use `transform` and `opacity` only

---

## Icons

### Usage

- Use Lucide icons consistently

- Standard sizes: 14px, 16px, 20px, 24px

- Include `aria-hidden="true"` for decorative icons

- Never use emojis as icons

### Placement

- Left of labels in buttons and navigation

- Right of labels for external links or dropdowns

- Centered when used alone with `aria-label`

---

## Dark Mode

### Implementation

```css

[data-theme="dark"] {

/* Dark mode overrides */

}

```

### Rules

1. Never use pure white (`#ffffff`) on dark backgrounds

2. Reduce shadow intensity in dark mode

3. Adjust image brightness if needed

4. Test contrast ratios in both modes

---

## Performance

### CSS

1. Use CSS custom properties for theming

2. Avoid deeply nested selectors (max 3 levels)

3. Use `will-change` sparingly

4. Prefer `transform` over `top/left` for animations

### Images

1. Always specify `width` and `height` attributes

2. Use `loading="lazy"` for below-fold images

3. Use appropriate formats (WebP with fallbacks)

4. Include placeholder or skeleton states

---

## Code Style

### CSS Class Naming

```css

/* Component */

/* Component modifier */

/* Component child */

/* State */

```

### File Organization

```

src/

components/

ui/ # Primitive components (Button, Input, Card)

layout/ # Layout components (Container, Header)

styles.css # Global styles and design tokens

lib/

theme.ts # Theme utilities

preferences.ts # User preference management

```

---

## Checklist

Before shipping any UI changes, verify:

- [ ] Color contrast meets WCAG AA standards

- [ ] Focus states are visible

- [ ] Layout works at all breakpoints

- [ ] Animations respect `prefers-reduced-motion`

- [ ] Text is readable at default browser zoom

- [ ] Interactive elements have 44px minimum touch target

- [ ] Semantic HTML is used appropriately

- [ ] Dark mode has been tested