# UI Development React

> UI design system and visual identity tokens for Alauda Container Platform. Provides design tokens (TypeScript, CSS, JSON), dark mode support, and implementation guidelines for React and other frameworks.

- Skill: `alauda/ui-development-react` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add alauda/ui-development-react`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alauda/ui-development-react/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: alauda (https://skillmd.com/u/alauda)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alauda/ui-development-react

---


# 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

```javascript
// 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:
   ```bash
   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.