Skills

ui-development-react

Installation
SKILL.md

UI Development Skill: ACP Design System

Overview

The UI Development Skill provides a comprehensive design system for Alauda Container Platform (ACP). It encodes the complete visual identity, design tokens, and implementation guidelines that ensure consistency across all ACP user interfaces.

This skill is designed to be used company-wide by:

  • Frontend developers building new UI features
  • Product designers maintaining visual consistency
  • Full-stack engineers integrating design tokens into applications
  • Teams adopting ACP design standards

Visual Identity

Color Philosophy

ACP uses a professional, cool-toned palette emphasizing clarity and information hierarchy:

  • Primary Blues: Professional, trustworthy feeling (backgrounds, panels, info states)
  • Success Greens: Positive, completion states (confirmations, successful operations)
  • Process Teals: Active workflow states (investigations, pending operations)
  • Neutral Grays: Hierarchy and separation (borders, dividers, subtle elements)

Color Palette

Light Mode (Default)

Category Color Hex Usage
Backgrounds Main #ffffff Primary content areas
Primary BG #f4f6f8 Top chrome, secondary panels
Panel BG #eef4ff Left sidebars, guidance areas
Accents Info BG #e3f2fd Alert boxes, key information
Info Border #90caf9 Info element borders
Success Success BG #d7f5e9 Success states, completion
Success Border #4caf50 Success indicators
Process Process BG #e8f2ff Processing steps, workflows
Process Border #2196f3 Process state indicators
Teal Teal BG #e0f2f1 Hypothesis/investigation states
Teal Border #4db6ac Teal state indicators
Borders Primary #cbd7e0 Panel borders, main dividers
Secondary #cbd5e1 Card separators, subtle lines

Dark Mode

Dark mode variants maintain WCAG AA contrast ratios while preserving visual hierarchy:

Category Color Hex Usage
Backgrounds Main #1a1a1a Primary content areas
Primary BG #2d3748 Top chrome, secondary panels
Panel BG #1e3a5f Left sidebars, guidance areas
Accents Info BG #1e3a8a Alert boxes
Info Border #60a5fa Info element borders
Success Success BG #064e3b Success states
Success Border #10b981 Success indicators
Process Process BG #1e40af Processing steps
Process Border #3b82f6 Process indicators
Teal Teal BG #134e4a Hypothesis states
Teal Border #14b8a6 Teal indicators
Borders Primary #4b5563 Panel borders
Secondary #555d6f Card separators

Spacing System

ACP uses a 10px base unit grid system:

4px   (1 unit)
8px   (2 units)
12px  (3 units)
16px  (4 units) - Standard padding/margin
20px  (5 units)
24px  (6 units) - Large spacing
32px  (8 units) - Section spacing
48px  (12 units)
64px  (16 units) - Major section gaps

Typography

Font Stack (System Fonts)

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
             "Helvetica Neue", Arial, sans-serif;

Font Sizes

  • Body: 14px / 1.5 line-height
  • Small: 12px / 1.4 line-height
  • Large: 16px / 1.6 line-height
  • Heading 4: 18px / 1.4 line-height, 500 weight
  • Heading 3: 20px / 1.3 line-height, 600 weight
  • Heading 2: 24px / 1.2 line-height, 600 weight
  • Heading 1: 32px / 1.1 line-height, 700 weight

Font Weights

  • 300: Light
  • 400: Regular (default)
  • 500: Medium (interactive, accents)
  • 600: Semi-bold (subheadings)
  • 700: Bold (main headings)

Effects & Interactions

Border Radius

  • Subtle: 4px (form inputs, small elements)
  • Standard: 8px (cards, buttons)
  • Large: 12px (panels, containers)
  • Extra Large: 16px (major sections)

Shadows

  • Subtle: 0 1px 2px rgba(0, 0, 0, 0.05)
  • Medium: 0 4px 6px rgba(0, 0, 0, 0.1)
  • Strong: 0 10px 15px rgba(0, 0, 0, 0.15)

Transitions

  • Fast: 200ms (micro-interactions, hovers)
  • Standard: 300ms (modal opens, page transitions)
  • Slow: 500ms (complex animations)

Design Patterns

Card Pattern

Cards are the fundamental building block of ACP interfaces:

  • White background (#ffffff light, #2d3748 dark)
  • Subtle border: 1px solid (#cbd7e0 light, #4b5563 dark)
  • Border radius: 8px
  • Padding: 16px (4 units)
  • Standard shadow

Variants:

  • Alert Card: Blue background (#e3f2fd light) for informational content
  • Success Card: Green background (#d7f5e9 light) for completion states
  • Process Card: Teal background (#e0f2f1 light) for workflow states

Color Usage Guidelines

Info States (Blue)

  • Use for informational alerts, monitor updates, guidance
  • Blue encourages reading and attention without alarm

Success States (Green)

  • Use for completion, confirmations, successful operations
  • Green = "action completed successfully"

Process States (Teal)

  • Use for investigation steps, workflow states, pending operations
  • Teal indicates "something is being processed or analyzed"

Warning States (Orange/Amber)

  • Reserved for warnings and cautions (not fully implemented yet)
  • Use sparingly to indicate issues requiring attention

Error States (Red)

  • Reserved for critical errors (not in current palette)
  • Use for failures and critical alerts

Layout Patterns

Standard Layout

  1. Header/Chrome - Navigation and title bar (24px height typically)
  2. Left Sidebar - Guidance, prompts, navigation (280-320px wide)
  3. Content Area - Main content (flexible width)
  4. Right Panel (optional) - Details, sidebar (240-280px wide)

Responsive Behavior

  • Mobile (< 768px): Stack vertically, hide sidebars or use drawer
  • Tablet (768px - 1024px): Collapse sidebar to icons
  • Desktop (> 1024px): Full layout

Component Patterns

Interactive States

Buttons/Controls

  • Default: Base color with standard shadow
  • Hover: 1 shade darker, medium shadow
  • Active: 2 shades darker, strong shadow
  • Disabled: Gray (#cbd7e0 light), no shadow, 50% opacity text

Form Inputs

  • Default: White bg, subtle border
  • Focus: Info border color, medium shadow
  • Disabled: Gray bg, border, reduced opacity
  • Error: Red border, error background tint

Data Display

Tables

  • Header row: Primary background color
  • Alternating rows: White and #f4f6f8
  • Hover row: #eef4ff highlight
  • Borders: Secondary color between rows

Status Indicators

  • Success badge: Green background + white text
  • Warning badge: Orange background + white text
  • Error badge: Red background + white text
  • Info badge: Blue background + white text

Localization

ACP interfaces support English and Simplified Chinese.

Guidelines:

  • All text strings should use tokens for dynamic language switching
  • Chinese text requires adjusted line heights (1.6-1.8) due to character complexity
  • Consider text expansion in layouts (Chinese is more compact than English)
  • Use font stacks that support Chinese characters properly

Accessibility (WCAG AA Compliance)

Color Contrast

All color combinations meet WCAG AA minimum 4.5:1 contrast ratio for text:

  • Body text (14px): 4.5:1 minimum
  • Large text (18px+): 3:1 minimum
  • UI components: 3:1 minimum

Keyboard Navigation

  • All interactive elements must be keyboard accessible
  • Focus indicators must be visible (use info border color)
  • Tab order should follow logical reading order
  • Proper semantic HTML (<button>, <a>, form elements)

Screen Readers

  • Use semantic HTML structure
  • Provide alt text for meaningful images
  • Use ARIA labels for complex interactions
  • Proper heading hierarchy (<h1> to <h6>)

Dark Mode Implementation

Usage Detection

// CSS Media Query (preferred)
@media (prefers-color-scheme: dark) {
  /* dark mode styles */
}

// Or with CSS class (for manual toggle)
.dark { /* dark mode styles */ }

// Or in JavaScript
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

Token Adaptation

When implementing dark mode:

  1. Use CSS custom properties for color swaps
  2. Maintain all contrast ratios
  3. Keep accent colors consistent with brand
  4. Test all color combinations for readability
  5. Ensure dark backgrounds don't cause eye strain

Integration Guides

With Next.js + Tailwind CSS

  1. Use tailwind.config.js from /tokens/
  2. Extend with Tailwind's theme configuration
  3. Access colors via Tailwind classes: bg-acp-blue-50, text-acp-green-600
  4. Dark mode via dark: prefix: dark:bg-acp-blue-900

With CSS Variables

  1. Import design-tokens.css in your main stylesheet
  2. Use variables: background: var(--color-primary-bg)
  3. Override for dark mode in media query
  4. Variables are namespaced: --color-*, --space-*, --font-*

With TypeScript

  1. Import from design-tokens.ts: import { designTokens } from '@acp/tokens'
  2. Use in styled-components or CSS-in-JS: color: designTokens.colors.primary.blue
  3. Type-safe token access with IntelliSense
  4. Easy refactoring across codebase

Common Usage Patterns

Semantic Color Names

Prefer semantic names over raw hex values:

  • ✅ background-color: var(--color-success-bg);
  • ❌ background-color: #d7f5e9;

Spacing Scales

Always use spacing tokens:

  • ✅ padding: var(--space-4); (16px)
  • ❌ padding: 16px;

Typography Pairs

Follow established typography hierarchy:

  • ✅ <h2>Heading</h2> with Heading 2 style + <p>Body</p> with Body style
  • ❌ Mixing font sizes randomly

Dark Mode Testing

Always test designs in both modes:

  • Compare light mode to dark mode side-by-side
  • Check all color contrasts in dark mode
  • Verify text readability on dark backgrounds
  • Test interactive states in both modes

File Structure

This skill provides several token export formats:

  • TypeScript (design-tokens.ts) - For Next.js/React projects
  • CSS (design-tokens.css) - For any CSS project
  • JSON (design-tokens.json) - For design tools and automation
  • Tailwind Config (tailwind.config.js) - For Tailwind CSS projects
  • CSS Module (colors.module.css) - For CSS Modules projects

Reference Documentation

Detailed documentation is available in the /references/ directory:

  • design-tokens.md - Complete token specifications
  • design-patterns.md - Visual pattern examples
  • guidelines.md - Design do's and don'ts
  • accessibility.md - WCAG compliance details
  • dark-mode.md - Dark mode implementation guide

Documentation & Guides

Quick guides available in the /docs/ directory:

  • quick-start.md - Getting started with tokens
  • token-usage.md - How to use different token formats
  • best-practices.md - Implementation best practices
  • visual-identity.md - ACP brand identity overview
  • faq.md - Common questions and answers

Getting Started

  1. Choose your integration method:

    • Next.js/React: Use design-tokens.ts + Tailwind
    • CSS/SCSS: Use design-tokens.css + CSS variables
    • Design Tools: Use design-tokens.json

  2. Import or reference tokens in your project

  3. Apply tokens consistently throughout your UI

  4. Test in both light and dark modes

  5. Run design validator to check for consistency:

    python3 scripts/design-validator.py audit --path=src --mode=dark

Support & Maintenance

For questions or to report design system issues, refer to the FAQ or contact the design systems team.

Design tokens are versioned - check design-tokens.json for the current version.

Related skills

More from alauda/agent-skills

Installs
1
Repository
alauda/agent-skills
First Seen
Mar 18, 2026