cutThink_lite/docs/UI-FRAMEWORK.md

# CutThink Lite - UI 框架文档

## 概述

CutThink Lite 的 UI 框架提供了一套完整的 CSS 变量系统和可复用的 JavaScript 组件。

## CSS 变量系统

### 颜色变量

```css
/* 品牌色 */
--primary: #8B6914;
--primary-hover: #A67C00;
--primary-light: #F5E6C8;
--primary-dark: #6B520F;

/* 功能色 */
--danger: #EF4444;
--success: #10B981;
--warning: #F59E0B;
--info: #3B82F6;

/* 背景色 */
--bg-primary: #FFFFFF;
--bg-secondary: #F8F9FA;
--bg-tertiary: #E5E7EB;
--bg-sidebar: #FFFFFF;

/* 文本色 */
--text-primary: #1F2937;
--text-secondary: #6B7280;
--text-muted: #9CA3AF;
```

### 间距系统

```css
--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 12px;
--spacing-lg: 16px;
--spacing-xl: 20px;
--spacing-2xl: 24px;
--spacing-3xl: 32px;
--spacing-4xl: 40px;
```

### 圆角

```css
--radius-xs: 4px;
--radius-sm: 6px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-xl: 16px;
--radius-full: 9999px;
```

### 阴影

```css
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
```

## JavaScript 组件

### 1. Layout 布局组件

```javascript
import { Layout } from '@/components/shared/Layout.js'

const layout = new Layout({
  header: true,
  sidebar: true,
  headerOptions: {
    title: 'CutThink Lite',
    version: 'v0.1.0',
    searchable: true,
    actions: [
      { icon: '⚙️', title: '设置', onClick: () => {} }
    ]
  },
  sidebarOptions: {
    sections: [
      {
        title: '主要功能',
        items: [
          { id: 'screenshot', icon: '📷', label: '截图', active: true },
          { id: 'gallery', icon: '🖼️', label: '图库' }
        ]
      }
    ]
  }
})

document.getElementById('app').appendChild(layout.render())
```

### 2. Button 按钮组件

```javascript
import { Button } from '@/components/shared/Button.js'

const button = new Button({
  text: '点击我',
  icon: '✓',
  variant: 'primary', // primary, secondary, danger, success, ghost
  size: 'md',         // sm, md, lg
  onClick: () => console.log('Clicked!')
})

document.body.appendChild(button.render())
```

### 3. Input 输入框组件

```javascript
import { Input } from '@/components/shared/Input.js'

const input = new Input({
  label: '用户名',
  placeholder: '请输入用户名',
  required: true,
  hint: '用户名长度为 4-20 个字符',
  onChange: (value) => console.log(value)
})

document.body.appendChild(input.render())
```

### 4. Card 卡片组件

```javascript
import { Card } from '@/components/shared/Card.js'

const card = new Card({
  title: '卡片标题',
  icon: '📝',
  content: '<p>这是卡片内容</p>',
  actions: [
    { text: '编辑', onClick: () => {} },
    { text: '删除', onClick: () => {} }
  ]
})

document.body.appendChild(card.render())
```

### 5. Toast 通知组件

```javascript
import { Toast } from '@/components/shared/Toast.js'

// 显示不同类型的通知
Toast.success('成功', '操作已完成！')
Toast.danger('错误', '操作失败，请重试。')
Toast.warning('警告', '请注意检查输入。')
Toast.info('信息', '这是一条通知。')

// 自定义配置
Toast.show({
  type: 'success',
  title: '自定义标题',
  message: '自定义消息',
  duration: 5000
})
```

### 6. Modal 模态框组件

```javascript
import { Modal } from '@/components/shared/Modal.js'

// 创建模态框
const modal = new Modal({
  title: '确认操作',
  content: '<p>确定要执行此操作吗？</p>',
  onConfirm: () => console.log('Confirmed'),
  onCancel: () => console.log('Cancelled')
})

// 静态方法
Modal.confirm({
  title: '删除确认',
  content: '确定要删除这条记录吗？'
}).then(result => {
  if (result) {
    // 用户点击了确定
  }
})
```

## CSS 类名

### 布局类

```html
<div class="app-container">
  <header class="header">...</header>
  <div class="main-container">
    <aside class="sidebar">...</aside>
    <main class="content-area">...</main>
  </div>
</div>
```

### 按钮类

```html
<button class="btn btn-primary">主要按钮</button>
<button class="btn btn-secondary">次要按钮</button>
<button class="btn btn-danger">危险按钮</button>
<button class="btn btn-sm">小按钮</button>
<button class="btn btn-lg">大按钮</button>
<button class="btn btn-icon">✓</button>
```

### 表单类

```html
<div class="form-group">
  <label class="form-label">标签</label>
  <input type="text" class="input" placeholder="请输入...">
  <div class="form-hint">提示信息</div>
  <div class="form-error">错误信息</div>
</div>
```

### 卡片类

```html
<div class="card">
  <div class="card-header">
    <div class="card-title">标题</div>
  </div>
  <div class="card-body">
    内容...
  </div>
  <div class="card-footer">
    底部...
  </div>
</div>
```

### 工具类

```html
<!-- 间距 -->
<div class="mt-sm mb-md p-lg">间距工具类</div>

<!-- 文本 -->
<span class="text-sm text-muted">小号灰色文本</span>
<span class="font-semibold">半粗体</span>

<!-- Flex -->
<div class="flex items-center justify-between gap-md">
  <span>左边</span>
  <span>右边</span>
</div>

<!-- Grid -->
<div class="grid grid-cols-2">
  <div>列 1</div>
  <div>列 2</div>
</div>
```

## 响应式设计

框架包含完整的响应式支持：

- **桌面端**: 完整布局，侧边栏宽度 240px
- **平板端** (≤1024px): 侧边栏宽度 200px
- **移动端** (≤768px): 侧边栏变为底部导航栏

## 主题切换

```javascript
// 浅色主题
document.body.classList.add('theme-light')

// 深色主题
document.body.classList.add('theme-dark')

// 跟随系统（默认）
document.body.classList.remove('theme-light', 'theme-dark')
```

## 浏览器兼容性

- Chrome/Edge: 最新 2 个版本
- Firefox: 最新 2 个版本
- Safari: 最新 2 个版本
- 支持 CSS 变量

## 文件结构

```
src/components/shared/
├── Layout.js      # 布局组件
├── Header.js      # 头部组件
├── Sidebar.js     # 侧边栏组件
├── Button.js      # 按钮组件
├── Input.js       # 输入框组件
├── Card.js        # 卡片组件
├── Toast.js       # 通知组件
├── Modal.js       # 模态框组件
├── Loading.js     # 加载组件
├── Notification.js # 通知组件
└── index.js       # 入口文件

style.css          # 全局样式（包含所有 CSS 变量和组件样式）
```

## 最佳实践

1. **使用 CSS 变量**: 所有颜色、间距、阴影都应使用 CSS 变量，方便主题切换
2. **组件复用**: 优先使用 JavaScript 组件而不是手动创建 DOM
3. **响应式优先**: 设计时要考虑移动端体验
4. **无障碍**: 使用语义化标签，添加适当的 aria 属性
5. **性能**: 避免频繁的 DOM 操作，使用事件委托

## 更新日志

### v0.1.0 (2025-02-12)
- 初始版本
- 实现 CSS 变量系统
- 创建基础布局组件
- 创建共享 UI 组件
- 实现响应式设计