awoooi/docs/design/COMPONENT_LIBRARY.md

AWOOOI 原子組件庫規格

版本: v1.0 建立日期: 2026-03-20 負責人: CPO 設計系統: Nothing.tech 純白工業風

---

概述

本文件定義 AWOOOI 前端組件庫的設計規格，採用 Atomic Design 原則，確保視覺一致性與開發效率。

---

設計 Token

色彩系統

// packages/lewooogo-ui/src/tokens/colors.ts

export const colors = {
  // 基底色 (Pure White Base)
  white: '#FFFFFF',
  snow: '#FAFAFA',      // 主背景
  cloud: '#F5F5F5',     // 次背景/卡片
  mist: '#E5E5E5',      // 邊框/分隔線

  // 文字色 (High Contrast)
  ink: '#0A0A0A',       // 主文字
  gray: {
    600: '#6B7280',     // 次文字
    400: '#9CA3AF',     // 輔助文字
    200: '#E5E7EB',     // 禁用文字
  },

  // 功能色
  status: {
    success: '#10B981',
    warning: '#F59E0B',
    error: '#EF4444',
    info: '#3B82F6',
    thinking: '#8B5CF6',  // AI 思考中
  },

  // 品牌色
  brand: {
    primary: '#FF6B35',   // AWOOOI 橘
    nothingRed: '#D71921', // Nothing 品牌紅
  },
} as const;

間距系統

// packages/lewooogo-ui/src/tokens/spacing.ts

export const spacing = {
  0: '0',
  1: '4px',
  2: '8px',
  3: '12px',
  4: '16px',
  5: '20px',
  6: '24px',
  8: '32px',
  10: '40px',
  12: '48px',
  16: '64px',
} as const;

字體系統

// packages/lewooogo-ui/src/tokens/typography.ts

export const typography = {
  fontFamily: {
    display: '"NDot", monospace',     // AI 介面/數字
    body: '"Inter", system-ui',       // 一般文字
    mono: '"JetBrains Mono", monospace', // 程式碼
  },

  fontSize: {
    xs: '12px',
    sm: '14px',
    base: '16px',
    lg: '18px',
    xl: '20px',
    '2xl': '24px',
    '3xl': '30px',
    '4xl': '36px',
  },

  fontWeight: {
    normal: 400,
    medium: 500,
    semibold: 600,
    bold: 700,
  },

  lineHeight: {
    tight: 1.25,
    normal: 1.5,
    relaxed: 1.75,
  },
} as const;

效果系統

// packages/lewooogo-ui/src/tokens/effects.ts

export const effects = {
  // 白玻璃效果 (White Glassmorphism)
  glass: {
    background: 'rgba(255, 255, 255, 0.7)',
    blur: 'blur(20px)',
    border: 'rgba(0, 0, 0, 0.05)',
  },

  // 點陣紋理 (Dot Matrix)
  dotMatrix: {
    pattern: 'radial-gradient(circle, rgba(0, 0, 0, 0.03) 1px, transparent 1px)',
    size: '16px 16px',
  },

  // 陰影
  shadow: {
    sm: '0 1px 2px rgba(0, 0, 0, 0.05)',
    md: '0 4px 6px rgba(0, 0, 0, 0.05)',
    lg: '0 10px 15px rgba(0, 0, 0, 0.05)',
    glow: '0 0 20px rgba(255, 107, 53, 0.2)', // 品牌光暈
  },

  // 圓角
  radius: {
    sm: '4px',
    md: '8px',
    lg: '12px',
    xl: '16px',
    full: '9999px',
  },

  // 過渡
  transition: {
    fast: '150ms ease',
    normal: '250ms ease',
    slow: '350ms ease',
  },
} as const;

---

Atoms (原子組件)

StatusOrb - 狀態呼吸燈

// packages/lewooogo-ui/src/atoms/StatusOrb.tsx

interface StatusOrbProps {
  status: 'healthy' | 'warning' | 'critical' | 'unknown' | 'thinking';
  size?: 'sm' | 'md' | 'lg';
  pulse?: boolean;
  label?: string;
}

/**
 * 狀態呼吸燈
 * - 即時反映系統/主機狀態
 * - 支援脈衝動畫 (告警/思考中)
 *
 * @example
 * <StatusOrb status="healthy" size="md" />
 * <StatusOrb status="thinking" pulse label="AI 處理中" />
 */

視覺規格:

Size	直徑	光暈半徑
sm	8px	12px
md	12px	18px
lg	16px	24px

狀態色彩:

Status	色彩	脈衝
healthy	#10B981	無
warning	#F59E0B	慢 (2s)
critical	#EF4444	快 (0.5s)
unknown	#9CA3AF	無
thinking	#8B5CF6	中 (1s)

---

MetricValue - 數值顯示

// packages/lewooogo-ui/src/atoms/MetricValue.tsx

interface MetricValueProps {
  value: number | string;
  unit?: string;
  trend?: 'up' | 'down' | 'stable';
  trendValue?: string;
  size?: 'sm' | 'md' | 'lg' | 'xl';
  format?: 'number' | 'percent' | 'bytes' | 'duration';
}

/**
 * 數值顯示組件
 * - NDot 字體呈現數字
 * - 支援趨勢箭頭與變化值
 *
 * @example
 * <MetricValue value={99.9} unit="%" trend="up" trendValue="+0.1%" />
 * <MetricValue value={1024} format="bytes" /> // 顯示 "1 KB"
 */

視覺規格:

Size	字體大小	權重
sm	18px	500
md	24px	600
lg	36px	700
xl	48px	700

---

IconButton - 圖示按鈕

// packages/lewooogo-ui/src/atoms/IconButton.tsx

interface IconButtonProps {
  icon: ReactNode;
  variant?: 'ghost' | 'outline' | 'solid';
  size?: 'sm' | 'md' | 'lg';
  color?: 'default' | 'primary' | 'danger';
  disabled?: boolean;
  loading?: boolean;
  tooltip?: string;
  onClick?: () => void;
}

/**
 * 圖示按鈕
 * - 用於工具列、操作區
 * - 必須有 tooltip 說明
 */

---

Badge - 標籤徽章

// packages/lewooogo-ui/src/atoms/Badge.tsx

interface BadgeProps {
  children: ReactNode;
  variant?: 'solid' | 'outline' | 'subtle';
  color?: 'gray' | 'green' | 'yellow' | 'red' | 'blue' | 'purple' | 'orange';
  size?: 'sm' | 'md';
  dot?: boolean;
}

/**
 * 標籤徽章
 * - 用於狀態標示、分類
 *
 * @example
 * <Badge color="green">Active</Badge>
 * <Badge color="red" dot>3 Alerts</Badge>
 */

---

Molecules (分子組件)

GlassCard - 玻璃卡片

// packages/lewooogo-ui/src/molecules/GlassCard.tsx

interface GlassCardProps {
  children: ReactNode;
  variant?: 'default' | 'elevated' | 'bordered';
  padding?: 'sm' | 'md' | 'lg';
  interactive?: boolean;
  selected?: boolean;
  onClick?: () => void;
}

/**
 * 白玻璃卡片
 * - Nothing.tech 核心視覺元素
 * - 支援點擊交互與選中狀態
 *
 * CSS:
 * - background: rgba(255, 255, 255, 0.7)
 * - backdrop-filter: blur(20px)
 * - border: 1px solid rgba(0, 0, 0, 0.05)
 */

視覺規格:

Variant	背景	邊框	陰影
default	glass	subtle	sm
elevated	glass	subtle	lg
bordered	white	solid	none

---

HostCard - 主機卡片

// packages/lewooogo-ui/src/molecules/HostCard.tsx

interface HostCardProps {
  host: {
    id: string;
    name: string;
    ip: string;
    role: string;
    status: 'healthy' | 'warning' | 'critical' | 'unknown';
    metrics?: {
      cpu: number;
      memory: number;
      disk: number;
    };
    lastSeen?: string;
  };
  variant?: 'compact' | 'detailed';
  showMetrics?: boolean;
  onClick?: () => void;
}

/**
 * 主機狀態卡片
 * - 戰情室核心組件
 * - 整合 StatusOrb + MetricValue
 *
 * @example
 * <HostCard host={hostData} variant="detailed" showMetrics />
 */

佈局:

┌──────────────────────────────────────┐
│ ● web-server-01          [healthy]   │
│   192.168.0.188 · AI+Web 中心        │
├──────────────────────────────────────┤
│  CPU     Memory    Disk              │
│  45%     72%       58%               │
│  ████░   ███████░  █████░            │
└──────────────────────────────────────┘

---

AlertPanel - 告警面板

// packages/lewooogo-ui/src/molecules/AlertPanel.tsx

interface AlertPanelProps {
  alerts: Alert[];
  maxVisible?: number;
  showTimestamp?: boolean;
  onAlertClick?: (alert: Alert) => void;
  onAcknowledge?: (alertId: string) => void;
}

interface Alert {
  id: string;
  severity: 'info' | 'warning' | 'critical';
  title: string;
  message: string;
  source: string;
  timestamp: string;
  acknowledged?: boolean;
}

/**
 * 告警列表面板
 * - 即時更新 (SSE)
 * - 支援確認操作
 */

---

ApprovalCard - HITL 審批卡片

// packages/lewooogo-ui/src/molecules/ApprovalCard.tsx

interface ApprovalCardProps {
  approval: {
    id: string;
    type: 'deploy' | 'rollback' | 'config' | 'security';
    title: string;
    description: string;
    requester: string;
    blastRadius: 'low' | 'medium' | 'high' | 'critical';
    signaturesRequired: number;
    signaturesCollected: Signature[];
    expiresAt: string;
    aiSummary?: string;
    aiConfidence?: number;
  };
  currentUser: string;
  onApprove?: () => void;
  onReject?: () => void;
  onRequestInfo?: () => void;
}

/**
 * Human-In-The-Loop 審批卡片
 * - 顯示 Blast Radius 風險等級
 * - 支援 Multi-Sig 簽核進度
 * - AI 摘要與信心度
 */

佈局:

┌──────────────────────────────────────────────────┐
│ 🚀 部署請求: web-api v2.3.1                      │
│ ════════════════════════════════════════════════ │
│                                                  │
│ 📊 Blast Radius: ████████░░ HIGH                 │
│    影響: 3 服務 · 12 Pods · ~5000 用戶           │
│                                                  │
│ 🤖 AI 摘要: 此更新包含 API 破壞性變更，建議      │
│    先通知下游服務團隊。信心度: 87%               │
│                                                  │
│ ✍️ 簽核進度: 1/2                                 │
│    ✅ CTO (2026-03-20 10:30)                     │
│    ⏳ CISO                                       │
│                                                  │
│ [詢問更多] [拒絕] [批准]                         │
└──────────────────────────────────────────────────┘

---

Organisms (組織組件)

CommandPalette - 快捷命令面板

// packages/lewooogo-ui/src/organisms/CommandPalette.tsx

interface CommandPaletteProps {
  isOpen: boolean;
  onClose: () => void;
  commands: Command[];
  recentCommands?: string[];
  onCommandSelect: (command: Command) => void;
}

interface Command {
  id: string;
  label: string;
  description?: string;
  icon?: ReactNode;
  shortcut?: string;
  category: 'navigation' | 'action' | 'ai' | 'settings';
  action: () => void;
}

/**
 * Cmd+K 快捷命令面板
 * - 全站快速導航與操作
 * - 支援模糊搜尋
 * - 顯示快捷鍵提示
 */

快捷鍵:

快捷鍵	功能
Cmd+K	開啟面板
Esc	關閉面板
↑/↓	選擇項目
Enter	執行命令

---

ThinkingTerminal - AI 思考終端

// packages/lewooogo-ui/src/organisms/ThinkingTerminal.tsx

interface ThinkingTerminalProps {
  isOpen: boolean;
  stream: ThinkingStream | null;
  position?: 'bottom' | 'right';
  collapsible?: boolean;
}

interface ThinkingStream {
  status: 'idle' | 'thinking' | 'completed' | 'error';
  steps: ThinkingStep[];
  result?: string;
  error?: string;
}

interface ThinkingStep {
  id: string;
  type: 'input' | 'process' | 'output' | 'tool_call';
  content: string;
  timestamp: string;
  duration?: number;
}

/**
 * AI 思考過程終端
 * - SSE 即時串流
 * - 打字機效果
 * - 支援摺疊
 */

---

DataPincer - 數據鉗視覺化

// packages/lewooogo-ui/src/organisms/DataPincer.tsx

interface DataPincerProps {
  data: {
    hosts: HostData[];
    connections: Connection[];
    flows: DataFlow[];
  };
  viewMode?: '2d' | '3d';
  interactive?: boolean;
  highlightHost?: string;
  onHostClick?: (hostId: string) => void;
}

/**
 * 數據鉗視覺化組件
 * - AWOOOI 品牌視覺符號
 * - 四主機架構拓撲圖
 * - 即時資料流動畫
 */

---

Templates (模板)

DashboardLayout - 儀表板佈局

// packages/lewooogo-ui/src/templates/DashboardLayout.tsx

interface DashboardLayoutProps {
  children: ReactNode;
  sidebar?: ReactNode;
  header?: ReactNode;
  background?: 'default' | 'dotMatrix';
}

/**
 * 儀表板頁面佈局
 * - 支援側邊欄
 * - 點陣背景紋理
 * - 響應式設計
 */

斷點:

斷點	寬度	佈局
mobile	< 768px	單欄 + 抽屜選單
tablet	768-1024px	摺疊側欄
desktop	1024-1440px	展開側欄
wide	> 1440px	展開側欄 + 更多欄位

---

無障礙規範 (WCAG 2.1 AA)

對比度要求

元素	最小對比度	實際值
正文文字	4.5:1	17.3:1 (ink/snow)
大標題	3:1	17.3:1
非文字元素	3:1	符合
狀態色 (綠)	3:1	4.5:1 (success/snow)

互動元素

• 所有可點擊元素必須有 focus-visible 樣式
• 鍵盤可操作 (Tab 導航)
• 適當的 aria-label
• 螢幕閱讀器支援

Focus 樣式

.focus-visible {
  outline: 2px solid var(--brand-primary);
  outline-offset: 2px;
}

---

組件狀態

組件	狀態	負責人
StatusOrb	⏳ 待開發	CPO
MetricValue	⏳ 待開發	CPO
IconButton	⏳ 待開發	CPO
Badge	⏳ 待開發	CPO
GlassCard	⏳ 待開發	CPO
HostCard	⏳ 待開發	CPO
AlertPanel	⏳ 待開發	CPO
ApprovalCard	⏳ 待開發	CPO
CommandPalette	⏳ 待開發	CPO
ThinkingTerminal	⏳ 待開發	CPO
DataPincer	⏳ 待開發	CPO
DashboardLayout	⏳ 待開發	CPO

---

變更記錄

日期	版本	變更	作者
2026-03-20	v1.0	初版建立	CPO

---

此文件由 CPO 維護，前端開發者必須遵守此規格。