432 lines
14 KiB
Markdown
432 lines
14 KiB
Markdown
`UI_SYSTEM.md` 的核心目标是：**让 AI 生成的每一个组件，都像是同一个设计师写的，而不是从五个不同的 UI 库里随机拼凑的。**
|
||
|
||
---
|
||
|
||
## 必须包含的内容
|
||
|
||
### 1. 设计哲学（Design Philosophy）
|
||
|
||
在写任何具体规则之前，先定义"感觉"。AI 在模糊情况下会回到这里做判断。
|
||
|
||
```md
|
||
## Design Philosophy
|
||
|
||
**Core aesthetic**: Clean, functional, low-friction.
|
||
We build tools, not experiences. Every UI element must earn its place.
|
||
|
||
**Principles** (in priority order):
|
||
1. **Clarity over cleverness** — if you have to explain the UI, it failed
|
||
2. **Density over whitespace** — our users are power users, don't waste screen space
|
||
3. **Consistency over novelty** — use existing patterns before inventing new ones
|
||
4. **Motion is functional** — animate only to communicate state change, never for decoration
|
||
|
||
**Anti-patterns we actively avoid**:
|
||
- Skeleton loaders for data that loads in < 300ms (just show a spinner)
|
||
- Modal dialogs for destructive actions that are easily reversible
|
||
- Infinite scroll (we use pagination, users need to share URLs to specific pages)
|
||
- Tooltips on mobile
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 设计 Token（Design Tokens）
|
||
|
||
这是整个系统的基础。所有颜色、间距、字体都必须来自这里，AI 不能自己发明数值。
|
||
|
||
````md
|
||
## Design Tokens
|
||
|
||
### Color System
|
||
We use CSS variables. NEVER use raw hex values in components.
|
||
|
||
**Semantic colors** (use these, not primitives):
|
||
```css
|
||
--color-bg-base /* page background */
|
||
--color-bg-subtle /* card, sidebar backgrounds */
|
||
--color-bg-muted /* disabled states, placeholders */
|
||
|
||
--color-text-primary /* body text */
|
||
--color-text-secondary /* labels, captions */
|
||
--color-text-disabled /* disabled text */
|
||
--color-text-inverse /* text on dark backgrounds */
|
||
|
||
--color-border /* default borders */
|
||
--color-border-strong /* focused, emphasized borders */
|
||
|
||
--color-accent /* primary actions, links */
|
||
--color-accent-hover /* hover state of accent */
|
||
|
||
--color-success /* confirmations, completed states */
|
||
--color-warning /* non-blocking alerts */
|
||
--color-danger /* destructive actions, errors */
|
||
--color-info /* informational, neutral alerts */
|
||
````
|
||
|
||
**Rule**: If you find yourself writing `text-gray-500`, stop. Map it to a semantic token.
|
||
|
||
### Spacing Scale
|
||
|
||
We use an 4px base grid. Only use these values: `4px / 8px / 12px / 16px / 24px / 32px / 48px / 64px / 96px`
|
||
|
||
In Tailwind: `p-1 / p-2 / p-3 / p-4 / p-6 / p-8 / p-12 / p-16 / p-24`
|
||
|
||
Never: `p-5`, `p-7`, `p-9`, `p-10`, `p-11` — these break the grid.
|
||
|
||
### Border Radius
|
||
|
||
```
|
||
--radius-sm: 4px → rounded-sm (inputs, badges)
|
||
--radius-md: 8px → rounded (cards, buttons) ← default
|
||
--radius-lg: 12px → rounded-xl (modals, panels)
|
||
--radius-full: 9999px → rounded-full (avatars, pills)
|
||
```
|
||
|
||
Never mix radius sizes within the same component.
|
||
|
||
### Elevation / Shadow
|
||
|
||
```
|
||
--shadow-sm → subtle card lift
|
||
--shadow-md → dropdowns, popovers
|
||
--shadow-lg → modals, dialogs
|
||
```
|
||
|
||
Never use `drop-shadow` filter — use `box-shadow` only.
|
||
|
||
````
|
||
|
||
---
|
||
|
||
### 3. 字体系统（Typography System）
|
||
|
||
```md
|
||
## Typography
|
||
|
||
**Font stack**:
|
||
- UI: `Inter` (loaded via next/font, variable weight)
|
||
- Code: `JetBrains Mono` (code blocks, inline code only)
|
||
- Never import fonts from Google Fonts directly
|
||
|
||
**Type scale** (use only these, no arbitrary sizes):
|
||
|
||
| Token | Size | Weight | Line-height | Usage |
|
||
|----------------|-------|--------|-------------|--------------------------|
|
||
| `text-xs` | 12px | 400 | 1.5 | Labels, badges, metadata |
|
||
| `text-sm` | 14px | 400 | 1.5 | Body, secondary content |
|
||
| `text-base` | 16px | 400 | 1.6 | Primary body text |
|
||
| `text-lg` | 18px | 500 | 1.4 | Section headings |
|
||
| `text-xl` | 20px | 600 | 1.3 | Page sub-headings |
|
||
| `text-2xl` | 24px | 700 | 1.2 | Page titles |
|
||
| `text-3xl` | 30px | 700 | 1.1 | Hero headings only |
|
||
|
||
**Rules**:
|
||
- Max 2 font sizes per component
|
||
- `font-weight: 500` is the minimum for anything interactive (buttons, links)
|
||
- Never use `text-3xl` outside of marketing pages
|
||
- Line length: max 72 characters for body text (`max-w-prose`)
|
||
````
|
||
|
||
---
|
||
|
||
### 4. 核心组件规范（Core Component Specs）
|
||
|
||
为每个高频组件定义变体、状态和使用规则。这是 AI 最需要的部分。
|
||
|
||
````md
|
||
## Core Component Specs
|
||
|
||
### Button
|
||
|
||
**Variants**:
|
||
| Variant | Use case | Never use for |
|
||
|-------------|---------------------------------------|----------------------------|
|
||
| `primary` | Single main CTA per view | Destructive actions |
|
||
| `secondary` | Secondary actions | Main CTA |
|
||
| `ghost` | Toolbar actions, low-priority | Standalone CTAs |
|
||
| `danger` | Irreversible destructive actions only | Anything reversible |
|
||
| `link` | Navigation only | Form submissions |
|
||
|
||
**Sizes**: `sm` (28px h) / `md` (36px h, default) / `lg` (44px h)
|
||
|
||
**States** (all must be handled):
|
||
- `default` / `hover` / `active` / `focus-visible` / `disabled` / `loading`
|
||
|
||
**Loading state rule**:
|
||
Show spinner + disable button immediately on click.
|
||
Never let the button be clicked twice.
|
||
```tsx
|
||
// Correct
|
||
<Button onClick={handleSubmit} loading={isSubmitting}>
|
||
Save Changes
|
||
</Button>
|
||
|
||
// Wrong — no loading state
|
||
<Button onClick={handleSubmit} disabled={isSubmitting}>
|
||
{isSubmitting ? 'Saving...' : 'Save Changes'}
|
||
</Button>
|
||
````
|
||
|
||
**Icon buttons**: Always include `aria-label`. Never use icon-only buttons for primary actions.
|
||
|
||
---
|
||
|
||
### Form Inputs
|
||
|
||
**Anatomy** (always in this order, no exceptions):
|
||
|
||
```
|
||
[Label] ← always visible, never placeholder-only
|
||
[Input field]
|
||
[Helper text] ← optional, describes expected format
|
||
[Error message] ← replaces helper text on error
|
||
```
|
||
|
||
**States**: `default` / `focus` / `error` / `disabled` / `readonly`
|
||
|
||
**Rules**:
|
||
|
||
- Label always above input, never to the side (except checkbox/radio)
|
||
- Placeholder text is NOT a label — both must exist
|
||
- Error messages: specific and actionable ("Enter a valid email" not "Invalid input")
|
||
- Required fields: mark with asterisk (*) next to label, explain at top of form
|
||
- Never disable a submit button to prevent submission — show errors inline instead
|
||
|
||
---
|
||
|
||
### Data Table
|
||
|
||
```md
|
||
### Table
|
||
|
||
**Default behavior**:
|
||
- Sticky header on scroll
|
||
- Row hover highlight
|
||
- Checkbox column for bulk actions (leftmost)
|
||
- Actions column (rightmost, visible on row hover only)
|
||
- Empty state: illustration + message + CTA (never just "No data")
|
||
|
||
**Pagination**:
|
||
- Default page size: 25 rows
|
||
- Options: 10 / 25 / 50 / 100
|
||
- Always show total count ("Showing 1–25 of 143 results")
|
||
- Preserve page position on filter change
|
||
|
||
**Column rules**:
|
||
- Numbers: right-aligned, monospace font
|
||
- Dates: relative time for < 7 days ("2 hours ago"), absolute for older
|
||
- Status: always a colored badge, never plain text
|
||
- Long text: truncate with tooltip showing full value
|
||
```
|
||
|
||
---
|
||
|
||
### Modal / Dialog
|
||
|
||
```md
|
||
### Modal
|
||
|
||
**Size variants**:
|
||
| Size | Max-width | Use case |
|
||
|-------|-----------|---------------------------|
|
||
| `sm` | 400px | Confirmation dialogs |
|
||
| `md` | 560px | Forms with < 5 fields |
|
||
| `lg` | 720px | Complex forms, previews |
|
||
| `xl` | 960px | Multi-step flows |
|
||
|
||
**Rules**:
|
||
- Always trap focus inside modal
|
||
- ESC key always closes (unless unsaved changes → show confirmation)
|
||
- Click outside closes (unless form with unsaved changes)
|
||
- Never nest modals — use a multi-step flow instead
|
||
- Destructive confirm dialogs: danger button on RIGHT, cancel on LEFT
|
||
- Never auto-close a modal after async action — wait for user to dismiss
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 状态与反馈模式（State & Feedback Patterns）
|
||
|
||
````md
|
||
## State & Feedback Patterns
|
||
|
||
### Loading States
|
||
| Duration | Pattern |
|
||
|---------------|--------------------------------|
|
||
| < 300ms | Nothing (avoid flash of spinner)|
|
||
| 300ms – 1s | Inline spinner |
|
||
| 1s – 3s | Spinner + "Loading..." |
|
||
| > 3s | Progress bar + estimated time |
|
||
| Background | Subtle pulsing indicator in nav|
|
||
|
||
### Empty States
|
||
Every list/table must handle empty state:
|
||
```tsx
|
||
// Required elements:
|
||
// 1. Relevant icon (not a generic "no data" icon)
|
||
// 2. Friendly headline ("No tasks yet")
|
||
// 3. Explanation of why ("Projects with tasks will appear here")
|
||
// 4. CTA if user can fix it ("Create your first task →")
|
||
````
|
||
|
||
### Toast Notifications
|
||
|
||
|Type|When to use|Duration|
|
||
|---|---|---|
|
||
|`success`|Async action completed|3s|
|
||
|`error`|Action failed, user must retry|persistent|
|
||
|`warning`|Completed with caveats|5s|
|
||
|`info`|Background process started|3s|
|
||
|
||
**Rules**:
|
||
|
||
- Max 3 toasts visible at once (queue the rest)
|
||
- Never show success toast for page navigations
|
||
- Error toasts must include a retry action when possible
|
||
- Never use toast for validation errors — show inline instead
|
||
|
||
### Skeleton vs Spinner
|
||
|
||
- Skeleton: only for content with known layout (profile cards, feed items)
|
||
- Spinner: for unknown-shape content, buttons, inline actions
|
||
- Never both at the same time in the same view
|
||
|
||
````
|
||
|
||
---
|
||
|
||
### 6. 响应式断点（Responsive Breakpoints）
|
||
|
||
```md
|
||
## Responsive Breakpoints
|
||
|
||
**Strategy**: Desktop-first (our users are 85% desktop)
|
||
|
||
| Breakpoint | Token | Value | Target |
|
||
|------------|--------|--------|--------------------------|
|
||
| Desktop | (base) | > 1280px | Primary design target |
|
||
| Laptop | `lg` | 1024px | Minor adjustments |
|
||
| Tablet | `md` | 768px | Collapsed sidebar |
|
||
| Mobile | `sm` | 640px | Single column, no tables |
|
||
|
||
**Component-specific rules**:
|
||
- Data tables → horizontal scroll on `md` and below
|
||
- Sidebar → collapses to bottom nav on `sm`
|
||
- Modals → full-screen on `sm`
|
||
- Multi-column forms → single column on `md` and below
|
||
|
||
**Never**:
|
||
- Hide critical functionality on mobile (adapt it, don't remove it)
|
||
- Use fixed px widths for layout containers
|
||
- Assume touch input on desktop or mouse on mobile
|
||
````
|
||
|
||
---
|
||
|
||
### 7. 动效规范（Motion & Animation）
|
||
|
||
```md
|
||
## Motion & Animation
|
||
|
||
**Principle**: Motion communicates state, it doesn't decorate.
|
||
|
||
**Duration scale**:
|
||
```
|
||
|
||
--duration-fast: 100ms → micro-interactions (checkbox, toggle) --duration-normal: 200ms → most transitions (hover, focus) --duration-slow: 350ms → larger elements (modal, drawer enter) --duration-crawl: 500ms → only for page-level transitions
|
||
|
||
```
|
||
|
||
**Easing**:
|
||
```
|
||
|
||
--ease-default: cubic-bezier(0.2, 0, 0, 1) → most UI transitions --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1) → playful elements only --ease-linear: linear → progress bars only
|
||
|
||
```
|
||
|
||
**What to animate**:
|
||
- ✅ Opacity (enter/exit)
|
||
- ✅ Transform: translateY (panel slide-in)
|
||
- ✅ Max-height (accordion expand)
|
||
|
||
**Never animate**:
|
||
- ❌ `width` or `height` directly (use `max-height` or `transform`)
|
||
- ❌ `top/left/right/bottom` (use `transform: translate`)
|
||
- ❌ `box-shadow` on hover (use opacity trick instead)
|
||
- ❌ Anything if `prefers-reduced-motion: reduce`
|
||
```
|
||
|
||
---
|
||
|
||
### 8. 可访问性基线（Accessibility Baseline）
|
||
|
||
```md
|
||
## Accessibility (Non-negotiable)
|
||
|
||
**Every component must**:
|
||
- Meet WCAG 2.1 AA contrast ratios (4.5:1 body, 3:1 large text)
|
||
- Be fully keyboard navigable
|
||
- Have visible focus indicators (never `outline: none` without replacement)
|
||
- Work with screen readers (proper ARIA roles and labels)
|
||
|
||
**Required patterns**:
|
||
- Icon-only buttons: always `aria-label`
|
||
- Form inputs: always `htmlFor` ↔ `id` pairing
|
||
- Images: `alt` text always (empty string `""` for decorative images)
|
||
- Modals: `role="dialog"`, `aria-modal="true"`, focus trap
|
||
- Loading states: `aria-busy="true"` on the loading container
|
||
- Error messages: `aria-describedby` linking input to error text
|
||
|
||
**Color alone is never enough**:
|
||
- Status badges: color + icon + text
|
||
- Form errors: color + icon + message below field
|
||
- Graphs: color + pattern or label
|
||
```
|
||
|
||
---
|
||
|
||
### 9. 禁止模式（Anti-patterns）
|
||
|
||
```md
|
||
## UI Anti-patterns — Never Do These
|
||
|
||
**Layout**:
|
||
- ❌ Centering body text wider than 72 characters
|
||
- ❌ Full-width buttons on desktop (max-width: 320px)
|
||
- ❌ Mixing card and table layouts in the same list view
|
||
|
||
**Interaction**:
|
||
- ❌ Double-click to perform actions (single click only)
|
||
- ❌ Drag-and-drop as the *only* way to reorder
|
||
- ❌ Hover-only affordances (invisible until you hover)
|
||
- ❌ Auto-submitting forms on change without explicit confirmation
|
||
|
||
**Feedback**:
|
||
- ❌ Generic error messages ("Something went wrong")
|
||
- ❌ Success messages that don't tell the user what happened
|
||
- ❌ Blocking UI with a spinner for optimistic actions
|
||
- ❌ Alert dialogs (window.alert) — use our Dialog component
|
||
|
||
**Content**:
|
||
- ❌ Lorem ipsum in any committed code
|
||
- ❌ Hardcoded user names or emails in components
|
||
- ❌ Placeholder images (use our Avatar initials fallback)
|
||
```
|
||
|
||
---
|
||
|
||
## 优先级总结
|
||
|
||
|优先级|内容|为什么关键|
|
||
|---|---|---|
|
||
|🔴 必须|设计 Token（颜色、间距、圆角）|AI 最容易乱用原始数值|
|
||
|🔴 必须|核心组件规范（Button、Input、Table）|高频生成，最容易出现不一致|
|
||
|🔴 必须|状态与反馈模式|最能体现产品质感的细节|
|
||
|🟡 重要|字体系统|防止 AI 混用字号和字重|
|
||
|🟡 重要|可访问性基线|事后补救成本极高|
|
||
|🟡 重要|禁止模式|比"应该做什么"更有效|
|
||
|🟢 加分|动效规范|统一产品"手感"|
|
||
|🟢 加分|响应式断点|避免断点不一致的多设备问题|
|
||
|
||
---
|
||
|
||
**核心原则**：`UI_SYSTEM.md` 不是设计文档，是给 AI 的**决策树**。当 AI 面对"这里用什么颜色？""这个按钮多大？""错误怎么展示？"时，答案必须在这里找到，不能靠猜。 |