---
name: 知习 AI Design System
version: 2.0
description: >
  知习 AI — AI 驱动的知识学习平台。设计语言融合 Notion 的温润极简、Linear 的精准克制
  与 Apple 的质感表达，定位为"温润而聪慧"。全 Token 机器可读，AI 代理可直接引用。
platforms: iOS 18+ / iPadOS 18+ (优先), Web / Android 后续对齐
---

# 知习 AI 设计系统 v2.0

## Overview

知习 AI 是一款 AI 驱动的知识学习平台，覆盖**知识导入 → AI 分析 → 主动回忆 → 间隔复习**全链路。
设计系统以机器可读的 Token 为核心，每个组件通过 `{section.token}` 交叉引用，
AI 编程代理无需"理解文意"即可精确还原 UI。

**设计基因**：

| 参考 | 采纳点 | 刻意不采纳 |
|------|--------|-----------|
| Notion | 暖白底色、中性色分层、卡片圆角、非胶囊按钮 | 深海军蓝 Hero（学习场景忌压抑） |
| Linear | 单主色克制、极致留白、精准字间距 | 纯黑底色（学习需要明亮感） |
| Apple (HIG) | SF Pro 全系、SF Symbols、Dynamic Type、Haptics | 灰度按钮（学习场景需要明确的 CTA 色） |

---

## Colors

colors:
  # ── 品牌主色 ──
  primary: "#5B5FED"
  primary-pressed: "#4A4ECC"
  primary-deep: "#3B3EA8"
  primary-soft: "#EEEDFC"
  on-primary: "#FFFFFF"
  primary-gradient-start: "#5B5FED"
  primary-gradient-end: "#7B6FF0"

  # ── 功能色 ──
  accent-amber: "#F59E0B"
  accent-amber-soft: "#FEF3C7"
  accent-amber-deep: "#92400E"
  accent-coral: "#F87171"
  accent-coral-soft: "#FEE2E2"
  accent-coral-deep: "#991B1B"
  accent-mint: "#34D399"
  accent-mint-soft: "#D1FAE5"
  accent-mint-deep: "#065F46"
  accent-sky: "#60A5FA"
  accent-sky-soft: "#DBEAFE"
  accent-sky-deep: "#1E40AF"

  # ── 中性色（暖灰体系） ──
  canvas: "#FAFAF8"
  canvas-dark: "#1C1C1E"
  surface: "#F3F2F0"
  surface-dark: "#2C2C2E"
  surface-soft: "#FAFAF9"
  surface-soft-dark: "#242426"
  surface-elevated: "#FFFFFF"
  surface-elevated-dark: "#3A3A3C"
  hairline: "#E8E6E1"
  hairline-dark: "#38383A"
  hairline-soft: "#F0EEE9"
  hairline-soft-dark: "#303032"
  hairline-strong: "#D4D1CB"
  hairline-strong-dark: "#48484A"
  ink-primary: "#1E1B18"
  ink-primary-dark: "#FFFFFF"
  ink-secondary: "#6B6560"
  ink-secondary-dark: "#A1A1A6"
  ink-tertiary: "#9F9993"
  ink-tertiary-dark: "#636366"
  ink-inverse: "#FFFFFF"
  ink-inverse-dark: "#1E1B18"
  on-dark: "#FFFFFF"
  on-dark-muted: "#8E8E93"

  # ── 知识库分类色（参考 Notion 数据库属性色） ──
  kb-blue-bg: "#E8F0FE"
  kb-blue-fg: "#1967D2"
  kb-green-bg: "#E6F4EA"
  kb-green-fg: "#137333"
  kb-purple-bg: "#F1E8FD"
  kb-purple-fg: "#7627BF"
  kb-amber-bg: "#FEF7E0"
  kb-amber-fg: "#B06000"
  kb-rose-bg: "#FDE8EC"
  kb-rose-fg: "#B81C3C"

---

## Typography

typography:
  # ── 字体族 ──
  font-display: "SF Pro Display, -apple-system, system-ui, sans-serif"
  font-text: "SF Pro Text, -apple-system, system-ui, sans-serif"
  font-mono: "SF Mono, Menlo, monospace"

  # ── 字号层级 ──
  hero:
    fontFamily: "{typography.font-display}"
    fontSize: 34pt
    fontWeight: 700
    lineHeight: 1.12
    letterSpacing: -0.5pt
    dynamicTypeStyle: largeTitle
    use: 页面大标题（如"我的知识库"）

  title-1:
    fontFamily: "{typography.font-display}"
    fontSize: 28pt
    fontWeight: 700
    lineHeight: 1.18
    letterSpacing: -0.3pt
    dynamicTypeStyle: title1
    use: 页面标题

  title-2:
    fontFamily: "{typography.font-display}"
    fontSize: 22pt
    fontWeight: 600
    lineHeight: 1.22
    letterSpacing: -0.2pt
    dynamicTypeStyle: title2
    use: 区块标题、卡片标题

  title-3:
    fontFamily: "{typography.font-display}"
    fontSize: 20pt
    fontWeight: 600
    lineHeight: 1.25
    letterSpacing: -0.1pt
    dynamicTypeStyle: title3
    use: 列表项标题、KB 卡片名称

  headline:
    fontFamily: "{typography.font-text}"
    fontSize: 17pt
    fontWeight: 600
    lineHeight: 1.29
    letterSpacing: 0
    dynamicTypeStyle: headline
    use: 段落小标题、Sheet 标题

  body:
    fontFamily: "{typography.font-text}"
    fontSize: 17pt
    fontWeight: 400
    lineHeight: 1.47
    letterSpacing: 0
    dynamicTypeStyle: body
    use: 正文、知识点内容、AI 回复正文

  body-medium:
    fontFamily: "{typography.font-text}"
    fontSize: 17pt
    fontWeight: 500
    lineHeight: 1.47
    letterSpacing: 0
    dynamicTypeStyle: body
    use: 列表行主标题（需要比 body 更突出）

  body-sm:
    fontFamily: "{typography.font-text}"
    fontSize: 15pt
    fontWeight: 400
    lineHeight: 1.47
    letterSpacing: 0
    dynamicTypeStyle: subheadline
    use: 辅助说明、卡片描述、副标题

  body-sm-medium:
    fontFamily: "{typography.font-text}"
    fontSize: 15pt
    fontWeight: 500
    lineHeight: 1.47
    letterSpacing: 0
    dynamicTypeStyle: subheadline
    use: Section Header 右侧"查看全部"

  callout:
    fontFamily: "{typography.font-text}"
    fontSize: 14pt
    fontWeight: 500
    lineHeight: 1.43
    letterSpacing: 0
    dynamicTypeStyle: callout
    use: 按钮文字、Tab 标签、Pill 标签

  caption:
    fontFamily: "{typography.font-text}"
    fontSize: 13pt
    fontWeight: 400
    lineHeight: 1.38
    letterSpacing: 0
    dynamicTypeStyle: caption1
    use: 时间戳、元信息、输入框辅助文字

  caption-bold:
    fontFamily: "{typography.font-text}"
    fontSize: 13pt
    fontWeight: 600
    lineHeight: 1.38
    letterSpacing: 0
    dynamicTypeStyle: caption1
    use: 徽章文字、强调标签

  caption-2:
    fontFamily: "{typography.font-text}"
    fontSize: 11pt
    fontWeight: 500
    lineHeight: 1.36
    letterSpacing: 0.5pt
    dynamicTypeStyle: caption2
    use: Tab Bar 文字、微小标签、角标数字

  micro-caps:
    fontFamily: "{typography.font-text}"
    fontSize: 10pt
    fontWeight: 600
    lineHeight: 1.30
    letterSpacing: 1.2pt
    dynamicTypeStyle: caption2
    use: 全大写标签（如"NEW""PRO"）

  nav-title:
    fontFamily: "{typography.font-text}"
    fontSize: 17pt
    fontWeight: 600
    lineHeight: 1.29
    letterSpacing: 0
    dynamicTypeStyle: headline
    use: 导航栏居中标题

---

## Rounded

rounded:
  none: 0pt
  xs: 4pt
  sm: 6pt
  md: 10pt
  lg: 14pt
  xl: 20pt
  xxl: 24pt
  full: 9999pt

### Border Radius Usage

| Token | Value | Use |
|-------|-------|-----|
| `{rounded.xs}` | 4pt | Tag chips, small inline badges |
| `{rounded.sm}` | 6pt | Badge backgrounds, color swatches |
| `{rounded.md}` | 10pt | Buttons (NOT pills), inputs, list thumbnails |
| `{rounded.lg}` | 14pt | Cards, panels, sheets |
| `{rounded.xl}` | 20pt | KB cover cards, modals |
| `{rounded.xxl}` | 24pt | Large feature cards |
| `{rounded.full}` | 9999pt | Avatars, progress rings, pill-shaped filter chips |

---

## Spacing

spacing:
  xxs: 4pt
  xs: 8pt
  sm: 12pt
  md: 16pt
  lg: 20pt
  xl: 24pt
  xxl: 32pt
  xxxl: 40pt
  section: 48pt
  section-lg: 64pt
  hero: 80pt

### Page Margin

| Context | Horizontal | Vertical |
|---------|-----------|----------|
| pageMargin-h: 20pt | Main content area | — |
| pageMargin-card: 16pt | Inside cards | 16pt |
| pageMargin-sheet: 24pt | Sheet / modal | 20pt |
| pageMargin-listLeading: 20pt | List row without icon | — |
| pageMargin-listLeadingWithIcon: 68pt | List row with 40pt icon | — |
| pageMargin-listTrailing: 16pt | List row right edge | — |

### Grid

- **iPhone**: Single column, 640pt max content width
- **iPad portrait**: Single column, 640pt max
- **iPad landscape**: KB grid 3 columns, 12pt gutter; lists max 720pt
- **Column gap** (KB grid): `{spacing.sm}` (12pt)

---

## Depth & Elevation

elevation:
  level-0:
    shadow: none
    use: 列表、正文区、无边框卡片
  level-1:
    shadow: "0 1px 3px rgba(0,0,0,0.06)"
    use: 标准卡片、Section 面板
  level-2:
    shadow: "0 4px 12px rgba(0,0,0,0.08)"
    use: 长按浮起、下拉菜单、Context Menu
  level-3:
    shadow: "0 -4px 20px rgba(0,0,0,0.10)"
    use: Sheet/弹窗、Modal

### Dark Mode Elevation

In dark mode, shadows are invisible. Use **brightness steps** instead:
- `level-1`: surface raised 1 step above canvas
- `level-2`: surface raised 2 steps
- `level-3`: surface raised 3 steps + 0.5pt `{colors.hairline-dark}` border

---

## Components

### 7.1 Button

button-primary:
  backgroundColor: "{colors.primary}"
  textColor: "{colors.on-primary}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  height: 50pt
  paddingH: 24pt
  minimumAccessibleSize: 44x44pt

button-primary-pressed:
  backgroundColor: "{colors.primary-pressed}"
  textColor: "{colors.on-primary}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  transform: scale(0.97)

button-primary-disabled:
  backgroundColor: "{colors.hairline}"
  textColor: "{colors.ink-tertiary}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  height: 50pt

button-secondary:
  backgroundColor: transparent
  textColor: "{colors.ink-primary}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  height: 50pt
  paddingH: 24pt
  border: "1.5pt solid {colors.hairline-strong}"

button-secondary-pressed:
  backgroundColor: "{colors.surface}"
  textColor: "{colors.ink-primary}"
  border: "1.5pt solid {colors.hairline-strong}"
  transform: scale(0.97)

button-tertiary:
  backgroundColor: transparent
  textColor: "{colors.primary}"
  typography: "{typography.callout}"
  height: 44pt
  paddingH: 0
  border: none

button-tertiary-pressed:
  textColor: "{colors.primary-pressed}"

button-icon:
  backgroundColor: transparent
  tintColor: "{colors.ink-secondary}"
  size: 44x44pt
  symbolConfig: "pointSize:22, weight:regular"

button-icon-pressed:
  tintColor: "{colors.primary}"
  transform: scale(0.92)

button-pill:
  backgroundColor: "{colors.surface}"
  textColor: "{colors.ink-secondary}"
  typography: "{typography.callout}"
  rounded: "{rounded.full}"
  height: 34pt
  paddingH: 16pt

button-pill-selected:
  backgroundColor: "{colors.primary-soft}"
  textColor: "{colors.primary}"
  typography: "{typography.callout}"

button-destructive:
  backgroundColor: "{colors.accent-coral}"
  textColor: "{colors.on-primary}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  height: 50pt

### 7.2 Input

text-input:
  backgroundColor: "{colors.surface-elevated}"
  textColor: "{colors.ink-primary}"
  placeholderColor: "{colors.ink-tertiary}"
  typography: "{typography.body}"
  rounded: "{rounded.md}"
  height: 50pt
  paddingH: "{spacing.md}"
  border: "1pt solid {colors.hairline-strong}"

text-input-focused:
  backgroundColor: "{colors.surface-elevated}"
  border: "2pt solid {colors.primary}"
  outerGlow: "0 0 0 3pt {colors.primary-soft}"

text-input-error:
  border: "2pt solid {colors.accent-coral}"
  outerGlow: "0 0 0 3pt {colors.accent-coral-soft}"

text-input-disabled:
  backgroundColor: "{colors.surface}"
  textColor: "{colors.ink-tertiary}"
  border: "1pt solid {colors.hairline}"

search-bar:
  backgroundColor: "{colors.surface}"
  textColor: "{colors.ink-primary}"
  placeholderColor: "{colors.ink-tertiary}"
  typography: "{typography.body}"
  rounded: "{rounded.md}"
  height: 40pt
  paddingH: "{spacing.sm}"
  icon: "magnifyingglass"
  iconColor: "{colors.ink-tertiary}"

### 7.3 Card

card-base:
  backgroundColor: "{colors.surface-elevated}"
  rounded: "{rounded.lg}"
  padding: "{spacing.md}"
  border: "0.5pt solid {colors.hairline}"
  elevation: "{elevation.level-1}"

card-kb-cover:
  width: flexible (grid column)
  rounded: "{rounded.xl}"
  topColorArea:
    height: 120pt
    backgroundColor: one of "{colors.kb-*-bg}"
  infoArea:
    height: 56pt
    backgroundColor: "{colors.surface-elevated}"
    padding: "{spacing.sm} {spacing.md}"
  icon:
    sfSymbol: "books.vertical.fill"
    size: 64pt
    color: matching "{colors.kb-*-fg}"
    position: centered in topColorArea
  title:
    typography: "{typography.title-3}"
    textColor: "{colors.ink-primary}"
  subtitle:
    typography: "{typography.caption}"
    textColor: "{colors.ink-tertiary}"

card-stat:
  width: ~148pt (flexible)
  backgroundColor: "{colors.surface-elevated}"
  rounded: "{rounded.lg}"
  padding: "{spacing.md}"
  elevation: "{elevation.level-1}"
  value:
    typography: "{typography.title-1}"
    textColor: "{colors.primary}"
  label:
    typography: "{typography.caption}"
    textColor: "{colors.ink-tertiary}"

card-chat-bubble-user:
  backgroundColor: "{colors.primary}"
  textColor: "{colors.on-primary}"
  typography: "{typography.body}"
  rounded: "{rounded.lg}"
  padding: "{spacing.sm} {spacing.md}"
  maxWidth: 75% of container
  alignment: trailing

card-chat-bubble-ai:
  backgroundColor: "{colors.surface}"
  textColor: "{colors.ink-primary}"
  typography: "{typography.body}"
  rounded: "{rounded.lg}"
  padding: "{spacing.sm} {spacing.md}"
  maxWidth: 85% of container
  alignment: leading

card-review-face:
  backgroundColor: "{colors.surface-elevated}"
  rounded: "{rounded.lg}"
  padding: "{spacing.xl}"
  elevation: "{elevation.level-1}"
  frontText:
    typography: "{typography.body}"
    textColor: "{colors.ink-primary}"
  backText:
    typography: "{typography.body}"
    textColor: "{colors.ink-secondary}"

### 7.4 Navigation

tab-bar:
  backgroundColor: "{colors.surface-elevated}"
  topBorder: "0.5pt solid {colors.hairline}"
  height: 49pt + safeAreaBottom
  items: 5 (学习 / 知识库 / AI / 分析 / 我的)

tab-bar-item-selected:
  icon: fill variant
  iconColor: "{colors.primary}"
  textColor: "{colors.primary}"
  typography: "{typography.caption-2}"
  animation: spring(damping=0.7, duration=250ms)

tab-bar-item-unselected:
  icon: outline variant
  iconColor: "{colors.ink-tertiary}"
  textColor: "{colors.ink-tertiary}"
  typography: "{typography.caption-2}"

tab-bar-badge:
  backgroundColor: "{colors.accent-coral}"
  textColor: "{colors.on-primary}"
  typography: "{typography.caption-2}"
  size: 18pt diameter
  position: top-right of icon

navigation-bar-large:
  titleTypography: "{typography.hero}"
  titleColor: "{colors.ink-primary}"
  titleAlignment: leading
  collapseBehavior: "scrolls up into standard nav-bar"

navigation-bar-standard:
  backgroundColor: "{colors.canvas} @ 0.85 opacity + blur"
  titleTypography: "{typography.nav-title}"
  titleColor: "{colors.ink-primary}"
  titleAlignment: center
  backButton: system default chevron (DO NOT customize text or icon)
  trailingButtons:
    tintColor: "{colors.primary}"
    symbolConfig: "pointSize:22, weight:regular"

section-header:
  leadingText:
    typography: "{typography.body-sm-medium}"
    textColor: "{colors.ink-secondary}"
  trailingLink:
    typography: "{typography.body-sm-medium}"
    textColor: "{colors.primary}"
    text: "查看全部"
  padding: "{spacing.lg} {pageMargin-h} {spacing.sm}"

segmented-control:
  backgroundColor: "{colors.surface}"
  rounded: "{rounded.md}"
  height: 36pt

segmented-control-selected:
  backgroundColor: "{colors.surface-elevated}"
  textColor: "{colors.ink-primary}"
  typography: "{typography.callout}"
  elevation: "{elevation.level-1}"

segmented-control-unselected:
  backgroundColor: transparent
  textColor: "{colors.ink-tertiary}"
  typography: "{typography.callout}"

### 7.5 List Row

list-row-standard:
  height: 52pt
  backgroundColor: "{colors.surface-elevated}"
  separatorColor: "{colors.hairline}"
  separatorInset: "{pageMargin-h}"

list-row-with-thumbnail:
  height: 64pt
  thumbnail:
    size: 40x40pt
    rounded: "{rounded.sm}"
    position: leading, centered vertically
  separatorInset: "{pageMargin-listLeadingWithIcon}"

list-row-title:
  typography: "{typography.body-medium}"
  textColor: "{colors.ink-primary}"
  maxLines: 1

list-row-subtitle:
  typography: "{typography.body-sm}"
  textColor: "{colors.ink-secondary}"
  maxLines: 1

list-row-trailing:
  typography: "{typography.caption}"
  textColor: "{colors.ink-tertiary}"
  accessory: chevron.right SF Symbol, 14pt

### 7.6 Badge & Tag

badge-review:
  backgroundColor: "{colors.accent-amber-soft}"
  textColor: "{colors.accent-amber-deep}"
  typography: "{typography.caption-bold}"
  rounded: "{rounded.xs}"
  padding: "3pt 8pt"
  text: "需复习"

badge-mastered:
  backgroundColor: "{colors.accent-mint-soft}"
  textColor: "{colors.accent-mint-deep}"
  typography: "{typography.caption-bold}"
  rounded: "{rounded.xs}"
  padding: "3pt 8pt"
  text: "已掌握"

badge-ai:
  backgroundColor: "{colors.primary-soft}"
  textColor: "{colors.primary}"
  typography: "{typography.caption-bold}"
  rounded: "{rounded.xs}"
  padding: "3pt 8pt"
  text: "AI 推荐"

badge-new:
  backgroundColor: "{colors.accent-coral-soft}"
  textColor: "{colors.accent-coral-deep}"
  typography: "{typography.micro-caps}"
  rounded: "{rounded.xs}"
  padding: "2pt 6pt"
  text: "NEW"

### 7.7 Progress

progress-bar:
  trackColor: "{colors.hairline}"
  trackHeight: 6pt
  trackRounded: 3pt
  fillColor: "{colors.primary}"
  fillRounded: 3pt
  animation: 600ms ease-out on width change

progress-bar-amber:
  fillColor: "{colors.accent-amber}"

progress-bar-mint:
  fillColor: "{colors.accent-mint}"

progress-ring:
  size: 80pt diameter
  trackColor: "{colors.hairline}"
  trackWidth: 6pt
  fillColor: "{colors.primary}"
  fillWidth: 6pt
  centerText:
    typography: "{typography.title-2}"
    textColor: "{colors.ink-primary}"
  animation: 800ms ease-out on strokeEnd

### 7.8 Toggle / Switch

toggle-on:
  trackColor: "{colors.primary}"
  thumbColor: "{colors.on-primary}"

toggle-off:
  trackColor: "{colors.hairline-strong}"
  thumbColor: "{colors.surface-elevated}"

### 7.9 Action Sheet

action-sheet:
  backgroundColor: "{colors.surface-elevated}"
  rounded: "{rounded.lg}"
  titleTypography: "{typography.headline}"
  destructiveButton:
    textColor: "{colors.accent-coral}"
  cancelButton:
    textColor: "{colors.ink-primary}"
    fontWeight: 600

### 7.10 Toast / Banner

toast:
  backgroundColor: "{colors.ink-primary}"
  textColor: "{colors.on-dark}"
  typography: "{typography.body-sm}"
  rounded: "{rounded.md}"
  padding: "{spacing.sm} {spacing.md}"
  position: bottom of safe area + 16pt
  animation: slide up 300ms spring, auto-dismiss 3s
  icon: optional leading SF Symbol 16pt

### 7.11 Skeleton

skeleton:
  backgroundColor: "{colors.hairline}"
  rounded: "{rounded.md}"
  animation: pulse 1.5s ease-in-out infinite
  brightnessRange: 0.6 — 1.0

### 7.12 Rating Button Group (复习评分)

rating-group:
  layout: horizontal, equal width
  spacing: "{spacing.sm}"
  paddingH: "{pageMargin-h}"

rating-button-again:
  backgroundColor: "{colors.accent-coral-soft}"
  textColor: "{colors.accent-coral-deep}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  height: 48pt
  icon: "arrow.counterclockwise"
  label: "再来一次"

rating-button-hard:
  backgroundColor: "{colors.accent-amber-soft}"
  textColor: "{colors.accent-amber-deep}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  height: 48pt
  icon: "hand.thumbsup"
  label: "有些难"

rating-button-good:
  backgroundColor: "{colors.accent-mint-soft}"
  textColor: "{colors.accent-mint-deep}"
  typography: "{typography.callout}"
  rounded: "{rounded.md}"
  height: 48pt
  icon: "hand.thumbsup.fill"
  label: "记住了"

### 7.13 Empty State

empty-state:
  layout: centered vertically & horizontally
  icon:
    sfSymbol: "tray" (or "sparkles" for AI, "chart.bar" for Analysis)
    size: 48pt
    color: "{colors.ink-tertiary}"
  title:
    typography: "{typography.body}"
    textColor: "{colors.ink-secondary}"
  description:
    typography: "{typography.body-sm}"
    textColor: "{colors.ink-tertiary}"
    maxLines: 2
  action:
    component: "{components.button-secondary}"
    marginTop: "{spacing.md}"

### 7.14 Error State

error-state:
  extends: "{components.empty-state}"
  icon:
    sfSymbol: "wifi.slash"
  action:
    text: "重试"
    component: "{components.button-tertiary}"

---

## Animation

animation:
  # 默认过渡
  default-duration: 200ms
  default-curve: ease-out

  # 页面导航
  push-duration: 300ms
  push-curve: ease-out
  pop-duration: 250ms
  pop-curve: ease-in

  # Sheet
  sheet-present-duration: 350ms
  sheet-present-curve: "spring(damping=0.85, response=0.35)"
  sheet-dismiss-duration: 250ms
  sheet-dismiss-curve: ease-in

  # 按压反馈
  press-scale: 0.97
  press-duration: 150ms
  press-curve: ease-out

  # Tab 图标
  tab-select-duration: 250ms
  tab-select-curve: "spring(damping=0.7, response=0.3)"

  # AI 内容生成
  ai-reveal-duration: 400ms
  ai-reveal-curve: ease-out
  ai-reveal-effect: "opacity 0→1 + translateY 8pt→0"

  # AI 思考指示器
  ai-thinking-dot-size: 6pt
  ai-thinking-dot-spacing: 6pt
  ai-thinking-dot-color: "{colors.primary}"
  ai-thinking-scale-sequence: "1.0 → 1.4 → 1.0"
  ai-thinking-interval: 200ms
  ai-thinking-label: "AI 正在思考…"
  ai-thinking-label-typography: "{typography.body-sm}"
  ai-thinking-label-color: "{colors.ink-tertiary}"

  # 消息气泡
  chat-bubble-ai-duration: 400ms
  chat-bubble-ai-effect: "opacity + translateY 8pt"
  chat-bubble-user-duration: 200ms
  chat-bubble-user-effect: "opacity + translateY 4pt"

  # 列表入场
  list-stagger-duration: 300ms
  list-stagger-delay: 50ms
  list-stagger-effect: "opacity + translateY 20pt→0"

  # 进度
  progress-fill-duration: 600ms
  progress-ring-fill-duration: 800ms

  # 复习卡片翻转
  card-flip-duration: 400ms
  card-flip-curve: ease-in-out
  card-flip-effect: "3D perspective rotateY(180deg)"

  # 禁止的动画
  forbidden:
    - "打字机逐字动画（AI 回复用整段渐现）"
    - "无限弹跳循环"
    - "旋转加载指示器（使用系统 UIActivityIndicator）"
    - "百叶窗/翻页切换"
    - "自动轮播 onboarding"

---

## Haptics

haptics:
  light:
    iOS: "UIImpactFeedbackGenerator(style: .light)"
    use: 按钮点击、Tab 切换、列表选择
  medium:
    iOS: "UIImpactFeedbackGenerator(style: .medium)"
    use: 刷新完成、AI 回答到达、Sheet 弹出
  heavy:
    iOS: "UIImpactFeedbackGenerator(style: .heavy)"
    use: 学习成就达成、连续打卡里程碑、卡片翻面
  selection:
    iOS: "UISelectionFeedbackGenerator()"
    use: Picker 滚动、滑块拖动
  notification-error:
    iOS: "UINotificationFeedbackGenerator(.error)"
    use: 操作失败、网络错误
  notification-success:
    iOS: "UINotificationFeedbackGenerator(.success)"
    use: 导入完成、知识点已掌握

---

## Icons

icons:
  source: "SF Symbols 6.0+ (iOS 18 minimum)"
  rendering: "hierarchical (outline default, fill on selected)"
  sizes:
    tabBar: 25pt
    navigationBar: 22pt
    listRow: 20pt
    kb-cover: 64pt
    emptyState: 48pt
    toast: 16pt
    badge: 12pt

  # 语义映射
  symbol-knowledgeBase: "books.vertical"
  symbol-ai: "sparkles"
  symbol-study: "brain.head.profile"
  symbol-analysis: "chart.bar"
  symbol-profile: "person.crop.circle"
  symbol-search: "magnifyingglass"
  symbol-add: "plus"
  symbol-close: "xmark"
  symbol-chevron: "chevron.right"
  symbol-check: "checkmark.circle.fill"
  symbol-warning: "exclamationmark.triangle"
  symbol-error: "wifi.slash"
  symbol-empty: "tray"
  symbol-review: "arrow.triangle.2.circlepath"
  symbol-notification: "bell"
  symbol-settings: "gearshape"
  symbol-feedback: "pencil.and.scribble"
  symbol-goal: "target"
  symbol-time: "clock"
  symbol-streak: "flame"
  symbol-mastery: "star.circle.fill"

---

## Layout Patterns

### 5-Tab Structure

```
┌──────────┬──────────┬──────────┬──────────┬──────────┐
│  学习     │  知识库    │   AI     │  分析     │   我的    │
└──────────┴──────────┴──────────┴──────────┴──────────┘
```

### StudyHome (学习) Layout

```
┌──────────────────────────────────┐
│  NavBar large: "学习"             │
│  ┌──────────────────────────────┐│
│  │ card-stat-group              ││ ← 今日进度环 + 数据（掌握 12 · 待复习 4）
│  └──────────────────────────────┘│
│  ┌──────────────────────────────┐│
│  │ list-row: "继续学习" →       ││ ← 上次会话快捷入口
│  └──────────────────────────────┘│
│  section-header: "今日推荐" →    │
│  [card][card][card] 水平滚动     │ ← 推荐知识点
│  section-header: "复习队列"       │
│  list-row × N (含 badge-review) │
└──────────────────────────────────┘
```

### LibraryHome (知识库) Layout

```
┌──────────────────────────────────┐
│  NavBar large: "知识库"           │
│  search-bar                      │
│  ┌──────────┐ ┌──────────┐      │
│  │ card-kb  │ │ card-kb  │      │ ← 2 列网格
│  └──────────┘ └──────────┘      │
│  ┌──────────┐ ┌──────────┐      │
│  │ card-kb  │ │ + 新建立   │      │
│  └──────────┘ └──────────┘      │
└──────────────────────────────────┘
```

### AiHome (AI) Layout

```
┌──────────────────────────────────┐
│  NavBar large: "AI" + sparkles   │
│  ┌──────────────────────────────┐│
│  │     ✨ 大图标                  ││
│  │   今天想学什么？               ││
│  │   我可以帮你解释、出题、分析…  ││
│  └──────────────────────────────┘│
│  section-header: "建议"           │
│  card × 3 (建议问题，点击即对话)  │
│  ── fixed bottom ──              │
│  text-input + mic icon           │
└──────────────────────────────────┘
```

### AnalysisHome (分析) Layout

```
┌──────────────────────────────────┐
│  NavBar large: "学习分析"         │
│  ┌──────────────────────────────┐│
│  │ 本周学习时长 · 柱状图          ││
│  └──────────────────────────────┘│
│  card-stat                card-stat
│  ┌──────┐  ┌──────┐             │
│  │ 78%  │  │ 5天  │             │
│  │掌握率 │  │连续  │             │
│  └──────┘  └──────┘             │
│  section-header: "AI 学习建议"    │
│  card: AI 分析建议文             │
└──────────────────────────────────┘
```

### Profile (我的) Layout

```
┌──────────────────────────────────┐
│  ┌──────────────────────────────┐│
│  │ ● 头像 64pt                   ││
│  │ 昵称 · 学习方向               ││
│  └──────────────────────────────┘│
│  list-row: 学习偏好 →           │
│  list-row: 目标设定 →           │
│  list-row: 通知管理 →           │
│  list-row: 意见反馈 →           │
│  list-row: 设置 →               │
└──────────────────────────────────┘
```

---

## Interaction

### Gestures

| Gesture | Context | Feedback |
|---------|---------|----------|
| Swipe left | List row: delete / archive | Red action button reveals |
| Long press | KB card: context menu | `{haptics.medium}` + card elevated to `{elevation.level-2}` |
| Pull down | List / home: refresh | System spinner + data reload |
| Edge swipe right | Any pushed page: back | System default edge gesture |
| Double tap | Review card: flip | `{animation.card-flip}` + `{haptics.heavy}` |

### Keyboard (iPad)

- **Focus ring**: `{colors.primary}` 2pt outline with `{colors.primary-soft}` outer glow
- **Tab order**: logical reading order (top→bottom, left→right)
- **⌘K**: Global search / command palette (if implemented)

---

## Page ↔ Component Mapping

| iOS Page | Layout Pattern | Key Components |
|----------|---------------|----------------|
| AIHomeView | Hero + suggestion list | `card-base`, `section-header`, `text-input` |
| AIChatPage | Message stream | `card-chat-bubble-user`, `card-chat-bubble-ai`, `ai-thinking` |
| ActiveRecallView | Q&A card | `card-review-face`, `text-input`, `progress-bar` |
| RecallTestPage | Full-screen test | `progress-bar`, `button-primary`, timer (monospaced) |
| DailyThinkingPage | Dated list | `list-row-standard` with date grouping |
| WeakPointsPage | Item list | `list-row-standard`, `badge-review` / `badge-ai` |
| AIFeedbackPageView | Analysis cards | `card-base`, `badge-ai` |
| LibraryHomeView | 2-col grid + search | `card-kb-cover`, `search-bar` |
| LibrarySubpages | List / detail | `list-row-with-thumbnail`, `card-base` |
| StudyHomeView | Hero + horizontal scroll | `progress-ring`, `card-stat`, `card-base` |
| LearningSessionView | Immersive learning | `card-review-face`, `progress-bar` |
| ReviewCardView | Flashcard flip | `card-review-face`, `rating-group` |
| AnalysisHomeView | Charts + stats | `progress-ring`, `card-stat`, `card-base` |
| ProfileView | Static list | `list-row-standard`, avatar |
| EditProfilePage | Form | `text-input`, avatar, `button-primary` |
| SettingsView | List with toggles | `list-row-standard`, `toggle` |
| NotificationListView | Dated list | `list-row-standard`, `badge-new` |
| GoalSettingDetailView | Form + list | `text-input`, `card-stat`, `progress-bar` |
| MethodPreferenceView | Multi-select list | `list-row-standard` with checkmark |
| FeedbackFormView | Form | `text-input` (multiline), `button-primary` |

---

## Dark Mode

dark-mode:
  strategy: "system follows user preference (automatic)"
  mapping:
    canvas: "{colors.canvas-dark}"
    surface: "{colors.surface-dark}"
    surface-soft: "{colors.surface-soft-dark}"
    surface-elevated: "{colors.surface-elevated-dark}"
    hairline: "{colors.hairline-dark}"
    hairline-soft: "{colors.hairline-soft-dark}"
    hairline-strong: "{colors.hairline-strong-dark}"
    ink-primary: "{colors.ink-primary-dark}"
    ink-secondary: "{colors.ink-secondary-dark}"
    ink-tertiary: "{colors.ink-tertiary-dark}"
  elevation:
    # Shadows invisible in dark mode; use brightness steps
    level-1: surface raised 1 step above canvas
    level-2: surface raised 2 steps
    level-3: surface raised 3 steps + 0.5pt border hairline-dark
  accentBehavior:
    # Functional colors keep same hue, slightly desaturated for dark
    primary: unchanged (has enough contrast on dark surfaces)
    kb-colors: use bg variants at 50% opacity

---

## Responsive Behavior

responsive:
  breakpoints:
    iPhone: "320—430pt width (compact)"
    iPad-portrait: "744—820pt width (regular, single column max 640pt)"
    iPad-landscape: "1024—1366pt width (regular, KB grid → 3 columns, lists max 720pt)"

  touch-targets:
    minimum: 44×44pt (HIG)
    ideal: 48×48pt for primary actions

  collapsing-navigation:
    large-title: visible at scroll top
    scroll-past: collapses to standard nav-bar with centered title
    threshold: 20pt scroll offset

  text-scaling:
    all typography tokens mapped to dynamicTypeStyle
    supported sizes: xSmall, small, medium, large, xLarge, xxLarge, xxxLarge
    layout adjustments: grids may drop to single column at accessibility sizes

---

## Do's & Don'ts

do:
  - "Use {colors.canvas} for page background"
  - "Use {colors.surface-elevated} for cards and sheets"
  - "Use {colors.primary} only on interactive elements (buttons, links, selected states)"
  - "Maximum one primary button per screen"
  - "AI-generated content: use {animation.ai-reveal} (fade + slide)"
  - "All spacing must be from the {spacing} scale"
  - "Use SF Symbols exclusively — no third-party icon libraries"
  - "Minimum touch target 44×44pt for all interactive elements"
  - "Cards: {rounded.lg}; Buttons: {rounded.md}; Tags: {rounded.xs}"

dont:
  - "NEVER use #000000 for text — use {colors.ink-primary}"
  - "NEVER use pure #FFFFFF for backgrounds — use {colors.canvas} or {colors.surface-elevated}"
  - "NEVER use {rounded.full} on buttons — pills are for filter chips and tags only"
  - "NEVER stack heavy shadows (level-2 or higher) on more than one element per screen"
  - "NEVER auto-play video"
  - "NEVER nest modals inside modals"
  - "NEVER customize navigation bar back button text or icon"
  - "NEVER use neon/fluorescent colors (#00FF00, #FF00FF, etc.)"
  - "NEVER use horizontal-scroll onboarding carousels"
  - "NEVER use typewriter animation for AI responses — use whole-block {animation.ai-reveal}"

---

## Agent Prompt Quick Reference

```
Build this page using the 知习 AI Design System:

COLORS:
  primary CTA:       {colors.primary}        #5B5FED
  page background:   {colors.canvas}         #FAFAF8
  card background:   {colors.surface-elevated} #FFFFFF
  body text:         {colors.ink-primary}    #1E1B18
  secondary text:    {colors.ink-secondary}  #6B6560
  divider:           {colors.hairline}       #E8E6E1
  success:           {colors.accent-mint}    #34D399 / bg {colors.accent-mint-soft}
  warning:           {colors.accent-amber}   #F59E0B / bg {colors.accent-amber-soft}
  error:             {colors.accent-coral}   #F87171 / bg {colors.accent-coral-soft}

TYPOGRAPHY:
  page title: 34pt / 700 / -0.5pt tracking
  card title: 22pt / 600 / -0.2pt tracking
  body text:  17pt / 400 / 1.47 line-height
  button:     14pt / 500
  caption:    13pt / 400

RADIUS:
  buttons: 10pt | cards: 14pt | tags: 6pt

SPACING: 4pt grid — page margins 20pt, card padding 16pt

ANIMATION: 200ms ease-out default; AI content 400ms fade+slide(8pt)

FORBIDDEN: pure black text, pure white bg, pill buttons, heavy shadows,
           neon colors, typewriter animation, carousel onboarding
```

---

## Known Gaps

- **Animation timing functions** documented as CSS keywords (`ease-out`, `spring`); iOS-native equivalents (`CAMediaTimingFunction`, `UISpringTimingParameters`) need per-platform mapping
- **Chart/Data Visualization** section is minimal — AnalysisHomeView bar chart needs full spec (axis labels, grid lines, bar width, gap, legend)
- **Markdown rendering** inside AI responses (code blocks, inline code, bold, lists) is not yet specified
- **Audio playback** (voice input for AI) has no UI spec — waveform, recording state, playback controls
- **Offline mode** visual indicators (sync status icons, stale data banners) not designed
- **Accessibility beyond Dynamic Type** — VoiceOver labels, Magic Tap, accessibility actions not enumerated per component
- **Sign-in / Onboarding flow** — Apple Sign In button, email verification, onboarding questions UI not specified
- **Notification content** — push notification card design (iOS notification extension) not covered
- The `kb-*-bg` / `kb-*-fg` color tokens work for 5 categories; a 6th+ category needs either rotation or user-custom color