Files

T

2026-05-31 09:36:23 +08:00

19 KiB

Raw Blame History

Pika 设计规范

AI-Native 组件库：专为大模型代码生成优化的 AntV 类可视化 + UI 组件库。核心目标：让 AI 第一次生成的代码就能跑、就能看、就能用。 设计原则：以 Apple Human Interface Guidelines 为准，融合 Ant Design 成熟实践。

一、核心理念

1.1 设计价值观

Pika 基于 Apple Human Interface Guidelines 的三大核心原则构建，同时融合 Ant Design 的成熟实践经验：

层级 (Hierarchy)

建立清晰的视觉层级，使控件和界面元素突出内容、区分层次。

核心要点：

内容和控件应该明确区分
重要的信息应该占据主要位置
使用视觉层次帮助用户快速理解界面

和谐 (Harmony)

与硬件和软件的同心设计保持一致，在界面元素、系统体验和设备之间创造和谐。

核心要点：

界面元素与硬件设计协调
保持跨平台的一致性
尊重平台特有的交互方式

一致性 (Consistency)

采用平台约定，保持一致的设计，在不同窗口大小和显示器间持续适应。

核心要点：

遵循各平台的交互惯例
用户在切换设备时感到熟悉
保持操作的一致性预期

意义感 (Meaningful)

每个设计决策都应该服务于用户目标和业务价值。设计不仅仅是美观，更是解决问题的工具。

核心要点：

设计服务于功能，而非装饰
关注用户任务和目标
创造有价值的用户体验

生长性 (Growing)

设计系统应该具有自我进化和适应能力，随着用户需求和技术发展不断迭代完善。

核心要点：

支持组件的扩展和定制
适应不同场景和需求
持续迭代和优化

1.2 AI 优先 (AI-First)

Pika 面向 AI 代码生成进行优化，同时遵循 Apple HIG 的设计原则：

原则	说明	反例	正例
零歧义	每个 prop 名称自解释，无简称、无隐式行为	`allowClear`	`showClear`
零默认假设	所有视觉行为显式声明，不靠"常识"	`status` 默认 `undefined`	`status: 'default' \| 'error' \| 'warning' \| 'success'`
一致性	相同概念用相同 prop 名，跨组件统一	`dataSource` / `options` / `treeData`	统一 `data`
扁平化	最多一层嵌套，禁止深层 renderProps	`columns[].render()`	`column.renderCell`
确定性	相同输入始终产生相同输出，无随机行为	默认不带 `key` 警告	强制 `key` 或无状态

1.3 可视化 + UI 一体化

Pika 融合 AntV 的数据可视化能力与 Apple HIG / Ant Design 的 UI 能力，共享同一套设计 Token、交互模式、主题系统。

二、设计原则（以 Apple HIG 为准）

2.1 色彩系统

设计原则（以 Apple 为准）：

避免使用相同颜色表示不同含义
- 在整个界面中一致地使用颜色
- 如果用品牌色表示交互式按钮可点击，不要用相同颜色来样式化非交互文本
确保应用的所有颜色在浅色、深色和高对比度环境下都正常工作
- 系统颜色会根据外观设置细微调整
- 开启"增强对比度"设置时，颜色差异会更加明显
在各种光照条件下测试应用的配色方案
考虑作品和半透明性如何影响附近颜色

语义化颜色（以 Apple 为准）：

/* Apple 语义化颜色 */
--apple-label: rgba(0, 0, 0, 0.88);
--apple-secondary-label: rgba(0, 0, 0, 0.6);
--apple-tertiary-label: rgba(0, 0, 0, 0.3);
--apple-separator: rgba(0, 0, 0, 0.12);

/* Pika 品牌色（融合） */
--nv-color-primary: #6C5CE7;
--nv-color-primary-hover: #A29BFE;
--nv-color-primary-active: #4A3DBF;

功能色：

/* 成功色 */
--nv-color-success: #00B894;
--nv-color-success-hover: #33c9a5;
--nv-color-success-active: #009975;

/* 警告色 */
--nv-color-warning: #FDCB6E;
--nv-color-warning-hover: #fdd97d;
--nv-color-warning-active: #e6b800;

/* 错误色 */
--nv-color-error: #FF7675;
--nv-color-error-hover: #ff9493;
--nv-color-error-active: #e0504f;

/* 信息色 */
--nv-color-info: #74B9FF;
--nv-color-info-hover: #96ccff;
--nv-color-info-active: #4da3ff;

无障碍色彩：

原则	说明
避免仅依靠颜色区分对象	使用文本标签或符号形状标识对象或状态
确保足够对比度	最小 4.5:1，推荐 7:1
考虑文化差异	颜色含义因文化而异

2.2 字体系统

字体规范：

/* 字体族 */
--nv-font-family: "SF Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
--nv-font-family-mono: "SF Mono", "JetBrains Mono", monospace;

/* 字体大小（三个级别） */
--nv-font-size-small: 12px;
--nv-font-size-middle: 14px;
--nv-font-size-large: 16px;

/* 字重 */
--nv-font-weight-regular: 400;
--nv-font-weight-medium: 500;
--nv-font-weight-semibold: 600;
--nv-font-weight-bold: 700;

字号层级：

级别	字号	字重	用途
标题	20px	600	页面标题
正文大	16px	500	卡片标题
正文	14px	400	正文内容
辅助	12px	400	辅助说明

最小触摸目标：

最小触摸目标：44 × 44 px

2.3 间距系统

基础间距（三个级别）：

--nv-spacing-small: 8px;
--nv-spacing-middle: 16px;
--nv-spacing-large: 24px;

安全区域：

平台	安全区域处理
iOS	尊重 Dynamic Island 和传感器外壳
iPadOS	尊重摄像头外壳
macOS	避免在窗口底部放置控件

2.4 圆角系统

圆角（三个级别）：

--nv-radius-small: 4px;
--nv-radius-middle: 8px;
--nv-radius-large: 12px;
--nv-radius-full: 9999px;

元素类型	圆角值
按钮	8px
卡片	8px
输入框	8px
标签	4px
头像	50% (圆形)

2.5 阴影系统

阴影（三个级别）：

--nv-shadow-small: 0 1px 2px rgba(0, 0, 0, 0.05);
--nv-shadow-middle: 0 4px 8px rgba(0, 0, 0, 0.08);
--nv-shadow-large: 0 8px 16px rgba(0, 0, 0, 0.12);
--nv-shadow-focus: 0 0 0 3px rgba(108, 92, 231, 0.2);

2.6 动效系统

动效原则：

有目的地添加动效 - 支持体验而非喧宾夺主
让动效成为可选的 - 使用替代方案如触觉和音频
追求与用户手势一致的逼真反馈
让用户可以取消动效

动效时长（三个级别）：

类型	时长
快速	0.15s
正常	0.25s
缓慢	0.4s

动效曲线：

--nv-ease-default: cubic-bezier(0.4, 0, 0.2, 1);
--nv-ease-in: cubic-bezier(0.4, 0, 1, 1);
--nv-ease-out: cubic-bezier(0, 0, 0.2, 1);
--nv-ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);

三、深色模式

3.1 核心原则

避免提供应用特定的外观设置 - 让用户使用系统设置
确保应用在两种外观下都看起来良好
使用语义化颜色自动适应

3.2 颜色适配

背景颜色：

类型	浅色模式	深色模式
背景	#FFFFFF	#1C1C1E
浮层	#F5F5F5	#2C2C2E

文本颜色：

类型	浅色模式	深色模式
主要	#1a1a2e	#FFFFFF
次要	#666666	rgba(255,255,255,0.65)
禁用	#999999	rgba(255,255,255,0.35)

3.3 对比度要求

最小对比度：4.5:1
推荐对比度：7:1

四、AI 友好的组件设计

4.1 核心理念

Pika 是专为 AI 代码生成优化的组件库。设计时始终考虑 AI 的理解能力和生成习惯。

4.2 统一数据模型

所有列表/表格/图表组件使用统一的数据 prop 名称：

// ✅ Pika 方式 — AI 容易理解和记忆
<Table data={items} />
<List data={items} />
<Chart data={items} />
<Timeline data={items} />

// ❌ 不统一 — AI 容易混淆
<Table dataSource={items} />     // 为什么不是 data？
<Select options={items} />        // 为什么叫 options？
<Tree treeData={items} />         // 为什么叫 treeData？

4.3 统一尺寸体系

所有组件使用统一的 size prop，值从三个级别中选择：

// ✅ 所有组件共用 size，无例外
size: 'small' | 'middle' | 'large'

<Button size="small" />
<Input size="middle" />
<Select size="large" />

尺寸定义：

级别	字体大小	组件高度	间距
small	12px	32px	8px
middle	14px	40px	16px
large	16px	48px	24px

4.4 统一事件命名

// ✅ on + 动词 + 名词 — AI 容易理解意图
onClick      // 点击事件
onChange     // 值变化事件
onSelect     // 选择事件
onClose      // 关闭事件

// ❌ on + 名词 + 动词 — 增加 AI 推理负担
onMenuClick      // ❌ → onClick 即可
onPanelChange    // ❌ → onChange

4.5 统一布尔 prop 命名

// ✅ 动词/形容词 + 肯定形式 — 语义清晰
disabled: boolean      // 禁用
loading: boolean       // 加载中
readOnly: boolean      // 只读
showSearch: boolean    // 显示搜索
showClear: boolean     // 显示清除

// ❌ 不一致 — AI 容易混淆
// allowClear / showSearch / bordered / dropdownMatchSelectWidth

4.6 自包含组件 + 确定导入路径

// ✅ 每个组件独立导入，路径即名字 — AI 不会选错路径
import { Button } from '@Pika/ui/button'
import { Modal } from '@Pika/ui/modal'
import { LineChart } from '@Pika/ui/line-chart'

// ❌ 统一入口 — AI 可能 tree-shake 失败
import { Button } from '@Pika/ui'

4.7 类型优先原则

所有 prop 使用联合类型字面量，AI 能看到所有可选值：

// ✅ 明确枚举 — AI 不会遗漏任何可能性
type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'text' | 'link'
type ButtonSize = 'small' | 'middle' | 'large'
type Status = 'default' | 'success' | 'warning' | 'error' | 'info'

// ❌ boolean 类型 — 隐藏了其他可能性
<Button ghost />           // 为什么不是 outline？
<Button primary />         // primary 和 type="primary" 是什么关系？

4.8 远离魔法字符串

// ✅ 枚举/常量 — AI 不会拼错值
<Table scrollBar={{ placement: 'overlay' }} />
Toast.show({ type: 'success' })

// ❌ 魔法字符串 — AI 可能拼错
Toast.show({ type: 'sueecss' })  // 拼写错误难以发现

4.9 组件原子化

一个组件只做一件事，避免"大而全"的上帝组件：

// ✅ 拆分 — AI 容易选择和组合
<Table />           // 纯表格
<TableFilter />      // 表格筛选
<TableSort />        // 表格排序

// ❌ 不拆分 — 30+ props，AI 难以理解
<Table filter sort pagination editable onRowClick ... />

4.10 使用 data-* 属性进行样式绑定

// ✅ data-* 属性 — AI 删除/修改时不易出错
<button
  data-variant="solid"
  data-size="middle"
  data-status="success"
  data-loading={isLoading}
/>

// ❌ classnames 拼接 — AI 难以追踪所有组合
<button className={cn('btn', `btn-${variant}`, `btn-${size}`, { 'btn-loading': loading })} />

4.11 Props 声明规范

// ✅ 正确做法 — 完整类型定义
interface ButtonProps {
  /** 按钮风格变体 */
  variant?: 'solid' | 'outline' | 'ghost' | 'text' | 'link'
  /** 按钮尺寸 */
  size?: 'small' | 'middle' | 'large'
  /** 按钮状态 */
  status?: 'default' | 'success' | 'warning' | 'error' | 'info'
  /** 是否禁用 */
  disabled?: boolean
}

// ❌ 禁止做法 — 类型不明确
interface BadProps {
  type?: string          // ❌ string 类型，AI 不知道可选值
  mode?: any            // ❌ any 类型，无类型提示
  [key: string]: any    // ❌ 透传，AI 无法推理
}

4.12 状态映射规范

使用对象映射替代 switch-case：

// ✅ 对象映射 — AI 容易理解和修改
const STATUS_STYLES = {
  default: { bg: '#f5f5f5', color: '#333' },
  success: { bg: '#e8fdf5', color: '#00B894' },
  warning: { bg: '#fffbeb', color: '#e6b800' },
  error: { bg: '#fff5f5', color: '#FF7675' },
} as const

// ❌ switch-case — 层层嵌套，AI 难以维护
switch (status) {
  case 'success': return { bg: '#e8fdf5', color: '#00B894' }
  case 'warning': return { bg: '#fffbeb', color: '#e6b800' }
  // ... 更多 case
}

五、组件规范

5.1 按钮 (Button)

按钮变体：

<Button variant="solid">实心按钮</Button>
<Button variant="outline">轮廓按钮</Button>
<Button variant="ghost">毛玻璃按钮</Button>
<Button variant="text">文字按钮</Button>
<Button variant="link">链接按钮</Button>

按钮尺寸：

<Button size="small">小按钮</Button>
<Button size="middle">中按钮（默认）</Button>
<Button size="large">大按钮</Button>

按钮形状（以 Apple 为准）：

<Button shape="default">默认</Button>
<Button shape="round">圆角</Button>
<Button shape="circle">圆形</Button>
<Button shape="pill">胶囊形</Button>  // Apple 风格

按钮状态：

<Button status="default">默认</Button>
<Button status="success">成功</Button>
<Button status="warning">警告</Button>
<Button status="error">错误</Button>

按钮属性：

export type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'text' | 'link'
export type ButtonSize = 'large' | 'middle' | 'small'
export type ButtonShape = 'default' | 'circle' | 'round' | 'pill'
export type ButtonStatus = 'default' | 'success' | 'warning' | 'error' | 'info'

export interface ButtonProps {
  variant?: ButtonVariant
  size?: ButtonSize
  shape?: ButtonShape
  status?: ButtonStatus
  disabled?: boolean
  loading?: boolean
  fullWidth?: boolean
  icon?: ReactNode
  iconPosition?: 'left' | 'right'
  onClick?: React.MouseEventHandler<HTMLButtonElement>
}

5.2 输入框 (Input)

输入框尺寸：

单行文本字段：40 px
多行文本字段：最小 80 px

<Input size="small" />
<Input size="middle" />
<Input size="large" />

输入框状态：

<Input status="default" />
<Input status="success" />
<Input status="warning" />
<Input status="error" />

5.3 导航组件

导航栏（以 Apple 为准）：

平台	高度
iOS 普通	44 pt
iOS 大标题	64 pt
iPadOS	44 pt

标签栏（以 Apple 为准）：

平台	高度
iOS	49 pt
iOS (含 Home Indicator)	83 pt
最多标签数	5 个

侧边栏（以 Apple 为准）：

平台	宽度
iPadOS	280 pt
macOS	320 pt

5.4 列表与表格

列表行高度：

类型	高度
紧凑	32px
标准	40px
大	56px

5.5 模态与弹窗（以 Apple 为准）

操作表 (Action Sheets)：

从底部滑出的卡片
圆角：14 pt

提醒 (Alerts)：

中央弹出
圆角：14 pt
避免过度使用

浮层 (Popovers)：

箭头指向锚点
圆角：10 pt

六、平台特定规范

6.1 触摸目标

最小触摸目标：44 × 44 px

6.2 响应式布局

支持不同屏幕尺寸
支持横屏和竖屏
支持暗色模式

6.3 手势支持

支持点击、滑动、拖拽
避免与系统手势冲突

七、结合 AntV 的可视化组件规范

7.1 图表组件统一接口

interface ChartBaseProps<T> {
  data: T[]
  xField: keyof T
  yField: keyof T
  seriesField?: keyof T
  color?: string | string[] | ((d: T) => string)
  tooltip?: boolean | TooltipConfig
  legend?: boolean | LegendConfig
  animation?: boolean | AnimationConfig
}

7.2 支持的图表类型

<LineChart data={data} xField="date" yField="value" />
<BarChart data={data} xField="category" yField="count" />
<PieChart data={data} angleField="value" colorField="name" />
<AreaChart data={data} xField="date" yField="value" />
<ScatterChart data={data} xField="age" yField="income" />
<DualAxesChart data={data} left={{ yField: 'revenue' }} right={{ yField: 'rate' }} />

八、可落地的 Token 体系

export const tokens = {
  color: {
    primary: '#6C5CE7',
    primaryHover: '#A29BFE',
    primaryActive: '#4A3DBF',
    success: '#00B894',
    warning: '#FDCB6E',
    error: '#FF7675',
    info: '#74B9FF',
  },
  radius: {
    small: '4px',
    middle: '8px',
    large: '12px',
    full: '9999px',
  },
  space: {
    small: '8px',
    middle: '16px',
    large: '24px',
  },
  font: {
    family: '"SF Pro", -apple-system, BlinkMacSystemFont, sans-serif',
    familyMono: '"SF Mono", "JetBrains Mono", monospace',
    size: { small: 12, middle: 14, large: 16 },
    weight: { regular: 400, medium: 500, semibold: 600, bold: 700 },
  },
  shadow: {
    small: '0 1px 2px rgba(0,0,0,0.05)',
    middle: '0 4px 8px rgba(0,0,0,0.08)',
    large: '0 8px 16px rgba(0,0,0,0.12)',
    focus: '0 0 0 3px rgba(108, 92, 231, 0.2)',
  },
  motion: {
    fast: '0.15s',
    normal: '0.25s',
    slow: '0.4s',
    easeDefault: 'cubic-bezier(0.4, 0, 0.2, 1)',
    easeSpring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
  },
} as const

九、无障碍设计

9.1 视觉无障碍

支持文字缩放 - 允许用户调整文本大小
支持屏幕阅读器 - 所有元素可访问
足够的颜色对比度 - 最小 4.5:1

9.2 运动无障碍

尊重"减少运动"设置
可选的运动效果

十、AI 友好的代码约束

10.1 Props 声明规范

interface ButtonProps {
  variant?: 'solid' | 'outline' | 'ghost' | 'text' | 'link'
  size?: 'large' | 'middle' | 'small'
  status?: 'default' | 'success' | 'warning' | 'error' | 'info'
}

10.2 状态映射

const STATUS_STYLES = {
  default: { bg: '#f5f5f5', color: '#333' },
  success: { bg: '#e8fdf5', color: '#00B894' },
  warning: { bg: '#fffbeb', color: '#e6b800' },
  error: { bg: '#fff5f5', color: '#FF7675' },
} as const

10.3 样式绑定

// data-* 属性 + CSS 属性选择器
<button data-variant="solid" data-size="md" data-status="success" />

十一、项目结构

Pikaui/
├── packages/
│   ├── core/
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Typography/
│   │   └── ...
│   ├── charts/
│   ├── icons/
│   ├── theme/
│   └── utils/
├── apps/
│   └── docs/

十二、总结：Pika 给 AI 的"提示工程"

1. 导入路径 = @Pika/ui/组件名
2. 数据 prop 始终叫 data
3. 尺寸 prop 始终叫 size，值从 large/middle/small 选
4. 布尔 prop 用动词开头
5. 所有 prop 类型用联合类型字面量定义
6. 状态样式用 data-* 属性
7. 回调命名 = on + 动词 + 名词
8. 每个组件独立文件
9. 可视化组件统一 xField / yField / data
10. 状态类型统一：default | success | warning | error | info

Pika 的核心竞争力：简洁统一的设计规范，专为 AI 代码生成优化。

19 KiB Raw Blame History Unescape Escape

Pika 设计规范

一、核心理念

1.1 设计价值观

层级 (Hierarchy)

和谐 (Harmony)

一致性 (Consistency)

意义感 (Meaningful)

生长性 (Growing)

1.2 AI 优先 (AI-First)

1.3 可视化 + UI 一体化

二、设计原则（以 Apple HIG 为准）

2.1 色彩系统

2.2 字体系统

2.3 间距系统

2.4 圆角系统

2.5 阴影系统

2.6 动效系统

三、深色模式

3.1 核心原则

3.2 颜色适配

3.3 对比度要求

四、AI 友好的组件设计

4.1 核心理念

4.2 统一数据模型

4.3 统一尺寸体系

4.4 统一事件命名

4.5 统一布尔 prop 命名

4.6 自包含组件 + 确定导入路径

4.7 类型优先原则

4.8 远离魔法字符串

4.9 组件原子化

4.10 使用 data-* 属性进行样式绑定

4.11 Props 声明规范

4.12 状态映射规范

五、组件规范

5.1 按钮 (Button)

5.2 输入框 (Input)

5.3 导航组件

5.4 列表与表格

5.5 模态与弹窗（以 Apple 为准）

六、平台特定规范

6.1 触摸目标

6.2 响应式布局

6.3 手势支持

七、结合 AntV 的可视化组件规范

7.1 图表组件统一接口

7.2 支持的图表类型

八、可落地的 Token 体系

九、无障碍设计

9.1 视觉无障碍

9.2 运动无障碍

十、AI 友好的代码约束

10.1 Props 声明规范

10.2 状态映射

10.3 样式绑定

十一、项目结构

十二、总结：Pika 给 AI 的"提示工程"

19 KiB

Raw Blame History