Skip to content

DESIGN.md

Latest commit

 

History

History
362 lines (258 loc) · 8.5 KB

DESIGN.md

File metadata and controls

362 lines (258 loc) · 8.5 KB

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:

Token Light Mode Dark Mode Usage
--accent #dc2626 #dc2626 Primary actions, interactive elements, emphasis
--accent-deep #b91c1c #ef4444 Hover states, secondary emphasis
--ink #0a0a0a #fafafa Primary text
--ink-soft #525252 #a1a1a1 Secondary text, descriptions
--surface #ffffff #121212 Card backgrounds, elevated surfaces
--bg #fafafa #0a0a0a Page background

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

--font-sans: "Geist", system-ui, sans-serif;
--font-mono: "Geist Mono", monospace;
--font-display: "Geist", system-ui, sans-serif;

Scale

Token Size Usage
--fs-xs 0.75rem (12px) Labels, badges, metadata
--fs-sm 0.875rem (14px) Body text, descriptions
--fs-base 1rem (16px) Default body text
--fs-md 1.125rem (18px) Subheadings
--fs-lg 1.25rem (20px) Section titles
--fs-xl 1.5rem (24px) Page headings

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

--space-1: 0.25rem /* 4px */ --space-2: 0.5rem /* 8px */ --space-3: 0.75rem /* 12px */
  --space-4: 1rem /* 16px */ --space-5: 1.5rem /* 24px */ --space-6: 2rem /* 32px */;

Grid Patterns

Auto-fit Grid (Recommended for Cards)

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)

/* 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

Size Max Width Usage
Default --page-max (1200px) Standard pages
Narrow --page-narrow (720px) Reading content, forms
Wide Full width Dashboards, data tables

Components

Cards

.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

Variant Usage
primary Main actions (Submit, Save, Download)
secondary Alternative actions
ghost Tertiary actions, navigation
destructive Delete, remove, dangerous actions

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

/* 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

: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

/* Respect user preference */
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Animation

Timing

--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

[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

/* Component */
.component-name {
}

/* Component modifier */
.component-name.variant {
}

/* Component child */
.component-name-child {
}

/* State */
.component-name.is-active {
}
.component-name[data-state="open"] {
}

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