Frontend Design

Frontend Design Skill

Thiết kế frontend với chất lượng cao, có chủ đích. Không generic, không AI-slop.

Mode Detection

This skill operates in two modes based on context:

1. Design Thinking (Both Modes)

Before writing any CSS or markup, answer these questions:

Purpose

• What is this interface trying to accomplish?
• What action should the user take?
• What information hierarchy exists?

Tone

• Is this playful or serious? Dense or spacious?
• What emotions should the interface evoke?
• How does this fit the brand personality?

Constraints

• Screen size / responsive requirements?
• Performance budget? (animations, images, fonts)
• Accessibility requirements?

Differentiation

• What makes this NOT look like a generic template?
• What is the ONE detail that makes this memorable?
• Where can we add craft without adding complexity?

2. Internal Mode: Control UI (LitElement)

When building for the OpenClaw Control UI dashboard.

Quick Reference

Design system: See references/control-ui-design-system.md for complete CSS variables, component classes, and animation catalog.

Component patterns: See references/litelement-patterns.md for view functions, html templates, event binding, and state management.

Core Principles

1. Dark-first: Default theme is dark (#121212). Light theme supported via CSS vars
2. Compact density: Small fonts (10-14px), tight padding (4-8-12-16px grid)
3. Accent red: var(--accent) = #ff5c5c. Use sparingly for primary actions and active states
4. Secondary teal: var(--accent-2) = #14b8a6. For secondary highlights
5. Motion budget: 100-300ms with var(--ease-out-expo) for entrances
6. Border-first depth: Cards use border: 1px solid var(--border) over heavy shadows

Typography

--font-body: "Space Grotesk", -apple-system, sans-serif;
--mono: "JetBrains Mono", monospace;

• Body text: 12-13px Space Grotesk
• Labels/badges: 10-11px, font-weight 500
• Headings: 14-16px, font-weight 600
• Code: 12px JetBrains Mono

Color Usage

Component Patterns

Cards: Border + subtle shadow, hover lifts border-color

border: 1px solid var(--border);
background: var(--card);
border-radius: var(--radius-lg); /* 12px */

Buttons: Inline-flex, small (11px), transition on hover

.btn { border: 1px solid var(--border); background: var(--bg-elevated); }
.btn.primary { background: var(--accent); color: white; }

Status dots: 8px circles with statusPulse animation for online state

Pills/badges: border-radius: var(--radius-full), semantic colors

Empty states: Centered flex column, 64px icon container, accent CTA button

Animation Guidelines

Use animations from animations.css:

Staggering: Use animation-delay with calc(var(--i) * 30ms) for list items.

Reduced motion: Always respect @media (prefers-reduced-motion: reduce).

Layout

Grid-based shell layout:

┌────────────────────────────┐
│         topbar (52px)      │
├──────┬─────────────────────┤
│ nav  │     content          │
│200px │     padding: 16px    │
│      │     20px 32px        │
└──────┴─────────────────────┘

Nav collapses to 52px. Chat focus mode hides nav entirely.

3. External Mode: General Web

When building new web apps, landing pages, or non-LitElement projects.

Typography

Choose fonts with intention. Defaults that work:

• Display: Inter, Satoshi, or Space Grotesk
• Body: System stack or Inter
• Mono: JetBrains Mono or Fira Code

Scale: Use a modular scale (1.25 ratio). Don't use more than 4-5 distinct sizes.

Line height: 1.4-1.6 for body, 1.1-1.2 for headings, 1.7-1.8 for long-form.

Color

Build a palette with purpose:

• 1 primary action color — buttons, links, CTAs
• 1 neutral scale — text, backgrounds, borders (8-10 shades)
• Semantic colors — success (green), warning (amber), error (red), info (blue)
• 1-2 accent colors — sparingly, for differentiation

Dark mode: Don't just invert. Dark backgrounds need lighter borders, reduced shadow opacity, and slightly desaturated colors.

Spatial Composition

• 8px base grid — all spacing in multiples of 8 (4px for tight UI)
• Consistent gaps — pick 3-4 spacing values and reuse them
• Breathing room — generous padding on sections (64-128px vertical)
• Max-width — content rarely needs more than 1200px
• Alignment — everything should align to something

Motion

• Entrances: 150-300ms, ease-out
• Exits: 100-200ms, ease-in
• Hover: 100-150ms, ease
• Page transitions: 200-400ms

Rule: If you can't explain why something animates, remove the animation.

Backgrounds

Avoid flat solid colors. Options:

• Subtle gradients (2-3 stops, low contrast)
• Noise texture overlay (opacity 0.02-0.05)
• Dot/grid pattern (very subtle)
• Radial glow behind hero content

Never: Mesh gradients with 5+ colors, parallax on everything, video backgrounds without purpose.

Component Guidelines

Buttons: Max 2-3 variants (primary, secondary, ghost). Consistent padding ratio (1:2 vertical:horizontal).

Cards: Pick ONE depth method (shadow OR border, not both heavy). Consistent radius.

Forms: Visible labels (not just placeholders). Clear focus states. Inline validation.

Navigation: Maximum 7 top-level items. Active state must be obvious.

Responsive

• Mobile-first CSS
• Breakpoints: 640, 768, 1024, 1280px
• Don't hide content on mobile — restructure it
• Touch targets minimum 44x44px
• Test at 320px width minimum

4. Vibecode Integration

This skill complements the /build workflow:

Architect (Claude Chat) → Blueprint.json → Builder (Claude Code)
                              ↓
                    design.colors → CSS vars
                    design.fonts → font-family
                    design.spacing → gap/padding

When executing a Blueprint:

1. Map design.colors.primary → --accent or primary color variable
2. Map design.colors.background → --bg
3. Map design.fonts.heading → heading font-family
4. Apply design tokens consistently across ALL components
5. Use this skill's guidelines to fill gaps the Blueprint doesn't specify

5. Anti-Slop Rules

Never Do

• Generic hero sections with stock gradient backgrounds
• "Built with AI" aesthetic — rounded everything, pastel gradients, generic icons
• Placeholder content that says "Lorem ipsum" in production
• More than 2 fonts on a page
• Box shadows AND borders AND gradients on the same element
• Animations on every element
• "Glassmorphism" or "Neumorphism" without clear purpose
• Generic testimonial carousels
• Hamburger menus on desktop
• Infinite scroll without clear navigation

Always Do

• Test with real content (or realistic content)
• Check contrast ratios (WCAG AA minimum)
• Verify hover/focus/active states exist
• Ensure loading states are designed (not just spinners)
• Make empty states helpful (not just "No data")
• Use semantic HTML elements
• Include keyboard navigation
• Test at smallest supported viewport

Internal Mode Additions

• Use existing CSS variables — don't create new color values
• Follow the 4px spacing grid
• Match existing component density (compact, not spacious)
• Animations from animations.css — don't add new @keyframes unless necessary
• Dark theme first — light theme vars handle the flip automatically