Sync: add prd and ui system notes
This commit is contained in:
987
Project/fonrey/UI&UX/UI_SYSTEM.md
Normal file
987
Project/fonrey/UI&UX/UI_SYSTEM.md
Normal file
@@ -0,0 +1,987 @@
|
||||
> **For AI assistants**: Read this entire file before writing any frontend code or template. All decisions here are final. When in doubt about styling, spacing, color, or component behavior — the answer is in this document. Do not invent values.
|
||||
|
||||
---
|
||||
|
||||
## 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; do not 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 (use a spinner instead)
|
||||
- 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
|
||||
- Full-width buttons on desktop (max-width: 320px for standalone CTAs)
|
||||
- Mixing card and table layouts in the same list view
|
||||
- Auto-submitting forms on change without explicit confirmation
|
||||
- Generic error messages ("Something went wrong" is never acceptable)
|
||||
- `window.alert` — always use our Dialog/Toast components
|
||||
|
||||
---
|
||||
|
||||
## Design Tokens
|
||||
|
||||
All colors, spacing, radius, and shadow values must come from these tokens. **Never write raw hex values or arbitrary px values in components.**
|
||||
|
||||
### Color System
|
||||
|
||||
We use CSS custom properties (variables). Define these in `base.css` under `:root`.
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Backgrounds */
|
||||
--color-bg-base: #ffffff; /* page background */
|
||||
--color-bg-subtle: #f9fafb; /* card, sidebar, panel backgrounds */
|
||||
--color-bg-muted: #f3f4f6; /* disabled states, placeholders, table zebra */
|
||||
|
||||
/* Text */
|
||||
--color-text-primary: #111827; /* body text */
|
||||
--color-text-secondary:#6b7280; /* labels, captions, helper text */
|
||||
--color-text-disabled: #9ca3af; /* disabled text */
|
||||
--color-text-inverse: #ffffff; /* text on dark/colored backgrounds */
|
||||
|
||||
/* Borders */
|
||||
--color-border: #e5e7eb; /* default borders */
|
||||
--color-border-strong: #d1d5db; /* focused, emphasized borders */
|
||||
|
||||
/* Brand / Accent — orange as primary action color */
|
||||
--color-accent: #f97316; /* primary actions, links, active states */
|
||||
--color-accent-hover: #ea6c0a; /* hover state of accent */
|
||||
--color-accent-subtle: #fff7ed; /* light tint for accent backgrounds */
|
||||
|
||||
/* Semantic */
|
||||
--color-success: #16a34a; /* confirmations, completed states */
|
||||
--color-success-bg: #f0fdf4;
|
||||
--color-warning: #d97706; /* non-blocking alerts */
|
||||
--color-warning-bg: #fffbeb;
|
||||
--color-danger: #dc2626; /* destructive actions, errors */
|
||||
--color-danger-bg: #fef2f2;
|
||||
--color-info: #2563eb; /* informational, neutral alerts */
|
||||
--color-info-bg: #eff6ff;
|
||||
}
|
||||
```
|
||||
|
||||
**Mapping to Tailwind**: Configure `tailwind.config.js` to extend colors using these CSS variables so you can write `text-accent`, `bg-bg-subtle`, etc. If that is not yet configured, use the following Tailwind equivalents as a temporary fallback — but never use arbitrary hex:
|
||||
|
||||
| Token | Tailwind equivalent |
|
||||
|---|---|
|
||||
| `--color-accent` | `text-orange-500` / `bg-orange-500` |
|
||||
| `--color-accent-hover` | `hover:bg-orange-600` |
|
||||
| `--color-text-primary` | `text-gray-900` |
|
||||
| `--color-text-secondary` | `text-gray-500` |
|
||||
| `--color-text-disabled` | `text-gray-400` |
|
||||
| `--color-border` | `border-gray-200` |
|
||||
| `--color-border-strong` | `border-gray-300` |
|
||||
| `--color-bg-subtle` | `bg-gray-50` |
|
||||
| `--color-bg-muted` | `bg-gray-100` |
|
||||
| `--color-danger` | `text-red-600` / `bg-red-600` |
|
||||
| `--color-success` | `text-green-600` |
|
||||
|
||||
**Rule**: If you find yourself writing `text-gray-500`, stop. Ask: is this a label, a caption, or secondary content? Then use the semantic token. If you find yourself writing `text-gray-400`, that is disabled text.
|
||||
|
||||
---
|
||||
|
||||
### Spacing Scale
|
||||
|
||||
We use a **4px base grid**. Only these values are permitted:
|
||||
|
||||
| px | Tailwind |
|
||||
|---|---|
|
||||
| 4px | `p-1` / `m-1` / `gap-1` |
|
||||
| 8px | `p-2` / `m-2` / `gap-2` |
|
||||
| 12px | `p-3` / `m-3` / `gap-3` |
|
||||
| 16px | `p-4` / `m-4` / `gap-4` |
|
||||
| 24px | `p-6` / `m-6` / `gap-6` |
|
||||
| 32px | `p-8` / `m-8` / `gap-8` |
|
||||
| 48px | `p-12` / `m-12` / `gap-12` |
|
||||
| 64px | `p-16` / `m-16` / `gap-16` |
|
||||
| 96px | `p-24` / `m-24` / `gap-24` |
|
||||
|
||||
**Never use**: `p-5`, `p-7`, `p-9`, `p-10`, `p-11` — these break the grid.
|
||||
|
||||
---
|
||||
|
||||
### Border Radius
|
||||
|
||||
```
|
||||
--radius-sm: 4px → rounded-sm (inputs, badges, table cells)
|
||||
--radius-md: 8px → rounded (cards, buttons) ← default
|
||||
--radius-lg: 12px → rounded-xl (modals, drawers, panels)
|
||||
--radius-full: 9999px → rounded-full (avatars, pill badges, toggles)
|
||||
```
|
||||
|
||||
**Rule**: Never mix radius sizes within the same component. A card with `rounded` should not have children with `rounded-xl`.
|
||||
|
||||
---
|
||||
|
||||
### Elevation / Shadow
|
||||
|
||||
```
|
||||
--shadow-sm → shadow-sm (subtle card lift, focused inputs)
|
||||
--shadow-md → shadow-md (dropdowns, popovers, floating panels)
|
||||
--shadow-lg → shadow-xl (modals, drawers, dialogs)
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- Never use `drop-shadow` filter — use `box-shadow` (`shadow-*`) only
|
||||
- Never use `shadow-2xl` — `shadow-xl` is the maximum
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
**Font stack**:
|
||||
- UI: `Inter` (variable weight, loaded via `<link>` from self-hosted or CDN)
|
||||
- Code / monospace data: `JetBrains Mono` (used for code blocks and numeric data columns only)
|
||||
- Never import fonts via Google Fonts `@import` inside CSS — use `<link>` in `<head>`
|
||||
|
||||
**Type scale** — use only these sizes, no arbitrary values:
|
||||
|
||||
| Tailwind class | Size | Weight | Line-height | Usage |
|
||||
|---|---|---|---|---|
|
||||
| `text-xs` | 12px | 400 | 1.5 | Labels, badges, metadata, table captions |
|
||||
| `text-sm` | 14px | 400 | 1.5 | Body text, secondary content, form helpers |
|
||||
| `text-base` | 16px | 400 | 1.6 | Primary body text |
|
||||
| `text-lg` | 18px | 500 | 1.4 | Section headings, drawer titles |
|
||||
| `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 — never in app UI |
|
||||
|
||||
**Rules**:
|
||||
- Max 2 font sizes per component
|
||||
- `font-medium` (500) is the minimum weight for anything interactive (buttons, links, tab labels)
|
||||
- Never use `text-3xl` in application views — only marketing/landing pages
|
||||
- Body text line length: max 72 characters (`max-w-prose`)
|
||||
- Numbers in tables: use `font-mono` (JetBrains Mono) and `tabular-nums`
|
||||
|
||||
---
|
||||
|
||||
## Page Layout
|
||||
|
||||
### App Shell
|
||||
|
||||
The standard application layout is a **fixed sidebar + scrollable main content** pattern.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Top Nav Bar (h-14, fixed, z-30) │
|
||||
├──────────────┬──────────────────────────────────────┤
|
||||
│ │ Page Header (breadcrumb + actions) │
|
||||
│ Sidebar ├──────────────────────────────────────┤
|
||||
│ (w-56, │ │
|
||||
│ fixed, │ Main Content Area │
|
||||
│ z-20) │ (overflow-y-auto, flex-1) │
|
||||
│ │ │
|
||||
│ │ │
|
||||
└──────────────┴──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- **Top Nav**: `h-14`, `bg-white`, `border-b border-gray-200`, `fixed top-0 inset-x-0 z-30`
|
||||
- **Sidebar**: `w-56`, `bg-gray-50`, `border-r border-gray-200`, `fixed left-0 top-14 bottom-0 z-20`, `overflow-y-auto`
|
||||
- **Main**: `ml-56 mt-14`, `min-h-screen`, `bg-white`
|
||||
- **Page content padding**: `p-6` on all sides
|
||||
|
||||
### Page Header
|
||||
|
||||
Every page has a header section directly below the top nav, inside the main area:
|
||||
|
||||
```html
|
||||
<div class="px-6 pt-6 pb-4 border-b border-gray-200">
|
||||
<!-- Breadcrumb -->
|
||||
<nav class="text-sm text-gray-500 mb-1">
|
||||
<span>房源管理</span>
|
||||
<span class="mx-1">/</span>
|
||||
<span class="text-gray-900">住宅出售</span>
|
||||
</nav>
|
||||
<!-- Page title + primary actions -->
|
||||
<div class="flex items-center justify-between">
|
||||
<h1 class="text-2xl font-bold text-gray-900">住宅出售</h1>
|
||||
<div class="flex items-center gap-2">
|
||||
<!-- Primary action buttons here -->
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Sidebar Navigation
|
||||
|
||||
- Active item: `bg-orange-50 text-orange-600 font-medium border-r-2 border-orange-500`
|
||||
- Inactive item: `text-gray-600 hover:bg-gray-100`
|
||||
- Section label: `text-xs font-semibold text-gray-400 uppercase tracking-wide px-3 mt-4 mb-1`
|
||||
- Item height: `h-9` (`36px`)
|
||||
- Item padding: `px-3`
|
||||
- Icon size: `w-4 h-4`, `mr-2`
|
||||
- Second-level items: `pl-9`
|
||||
|
||||
---
|
||||
|
||||
## Core Component Specs
|
||||
|
||||
### Button
|
||||
|
||||
**Variants**:
|
||||
|
||||
| Variant | Tailwind classes | Use case | Never use for |
|
||||
|---|---|---|---|
|
||||
| `primary` | `bg-orange-500 hover:bg-orange-600 text-white font-medium rounded` | Single main CTA per view | Destructive actions |
|
||||
| `secondary` | `bg-white border border-gray-300 hover:bg-gray-50 text-gray-700 font-medium rounded` | Secondary actions | Main CTA |
|
||||
| `ghost` | `bg-transparent hover:bg-gray-100 text-gray-600 font-medium rounded` | Toolbar actions, low-priority | Standalone CTAs |
|
||||
| `danger` | `bg-red-600 hover:bg-red-700 text-white font-medium rounded` | Irreversible destructive actions only | Anything reversible |
|
||||
| `link` | `text-orange-500 hover:text-orange-600 underline-offset-2 hover:underline` | Inline navigation links only | Form submissions |
|
||||
|
||||
**Sizes**:
|
||||
|
||||
| Size | Height | Padding | Font |
|
||||
|---|---|---|---|
|
||||
| `sm` | `h-7` (28px) | `px-3` | `text-xs` |
|
||||
| `md` | `h-9` (36px) | `px-4` | `text-sm` — default |
|
||||
| `lg` | `h-11` (44px) | `px-6` | `text-base` |
|
||||
|
||||
**States** (all must be handled in every button):
|
||||
|
||||
- `default` — base styles above
|
||||
- `hover` — defined in variant above
|
||||
- `active` — `active:scale-95 active:opacity-90`
|
||||
- `focus-visible` — `focus-visible:outline-2 focus-visible:outline-orange-500 focus-visible:outline-offset-2`
|
||||
- `disabled` — `disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none`
|
||||
- `loading` — spinner icon replaces or precedes label; button is disabled
|
||||
|
||||
**Loading state rule**: Show spinner and disable button immediately on click. Never allow double-submission.
|
||||
|
||||
```html
|
||||
<!-- Correct: HTMX handles loading state automatically with hx-indicator -->
|
||||
<button hx-post="/api/save/"
|
||||
hx-disabled-elt="this"
|
||||
class="btn-primary"
|
||||
aria-label="保存">
|
||||
<span class="htmx-indicator">
|
||||
<svg class="animate-spin w-4 h-4 mr-2" ...></svg>
|
||||
</span>
|
||||
保存
|
||||
</button>
|
||||
|
||||
<!-- For Alpine.js-controlled loading -->
|
||||
<button @click="submit()"
|
||||
:disabled="loading"
|
||||
:class="loading ? 'opacity-50 cursor-not-allowed' : ''"
|
||||
class="btn-primary">
|
||||
<svg x-show="loading" class="animate-spin w-4 h-4 mr-2" ...></svg>
|
||||
<span x-text="loading ? '保存中...' : '保存'"></span>
|
||||
</button>
|
||||
```
|
||||
|
||||
**Icon buttons**: Always include `aria-label`. Never use icon-only buttons as the sole primary CTA.
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
**Base input class**:
|
||||
```
|
||||
block w-full rounded border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900
|
||||
placeholder:text-gray-400
|
||||
focus:outline-none focus:ring-2 focus:ring-orange-500 focus:border-orange-500
|
||||
disabled:bg-gray-100 disabled:text-gray-400 disabled:cursor-not-allowed
|
||||
```
|
||||
|
||||
**States**:
|
||||
|
||||
| State | Additional classes |
|
||||
|---|---|
|
||||
| `default` | `border-gray-300` |
|
||||
| `focus` | `ring-2 ring-orange-500 border-orange-500` |
|
||||
| `error` | `border-red-500 ring-2 ring-red-500 focus:ring-red-500` |
|
||||
| `disabled` | `bg-gray-100 text-gray-400 cursor-not-allowed` |
|
||||
| `readonly` | `bg-gray-50 text-gray-600 cursor-default` |
|
||||
|
||||
**Label**:
|
||||
```html
|
||||
<label for="field-id" class="block text-sm font-medium text-gray-700 mb-1">
|
||||
字段名称 <span class="text-red-500">*</span> <!-- required indicator -->
|
||||
</label>
|
||||
```
|
||||
|
||||
**Helper text**:
|
||||
```html
|
||||
<p class="mt-1 text-xs text-gray-500">格式说明文字</p>
|
||||
```
|
||||
|
||||
**Error message**:
|
||||
```html
|
||||
<p class="mt-1 text-xs text-red-600" id="field-id-error" role="alert">
|
||||
<svg class="inline w-3 h-3 mr-1" ...></svg>
|
||||
具体的错误原因，可操作的
|
||||
</p>
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- Label always above input, never to the side (exception: checkbox and radio)
|
||||
- Placeholder text is NOT a label — both must exist
|
||||
- Error messages: specific and actionable ("请输入有效的手机号", not "格式错误")
|
||||
- Required fields: mark with `*` next to label; explain at top of form ("* 为必填项")
|
||||
- Never disable a submit button to prevent submission — show errors inline instead
|
||||
- `aria-describedby` must link input to its error element when error is shown
|
||||
|
||||
**Select / Dropdown**:
|
||||
```
|
||||
block w-full rounded border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900
|
||||
focus:outline-none focus:ring-2 focus:ring-orange-500 focus:border-orange-500
|
||||
```
|
||||
|
||||
**Textarea**: same as input, add `resize-y min-h-[80px]`. Always include character counter when there is a max length.
|
||||
|
||||
---
|
||||
|
||||
### Data Table
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
[Toolbar: bulk actions + filter chips + column visibility + export]
|
||||
[Table: sticky header, checkbox col, data cols, actions col]
|
||||
[Pagination: count + page controls + per-page selector + jump-to]
|
||||
```
|
||||
|
||||
**Table base classes**:
|
||||
```html
|
||||
<div class="overflow-x-auto">
|
||||
<table class="min-w-full divide-y divide-gray-200 text-sm">
|
||||
<thead class="bg-gray-50 sticky top-0 z-10">
|
||||
<tr>
|
||||
<!-- Checkbox column — leftmost -->
|
||||
<th class="w-10 px-3 py-3">
|
||||
<input type="checkbox" class="rounded border-gray-300 text-orange-500 focus:ring-orange-500">
|
||||
</th>
|
||||
<!-- Sortable column -->
|
||||
<th class="px-4 py-3 text-left text-xs font-semibold text-gray-500 uppercase tracking-wide cursor-pointer select-none hover:bg-gray-100"
|
||||
hx-get="?sort=field&order=asc" hx-target="#table-body">
|
||||
列名 <svg class="inline w-3 h-3 ml-1">...</svg>
|
||||
</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody id="table-body" class="divide-y divide-gray-100 bg-white">
|
||||
<tr class="hover:bg-gray-50 transition-colors">
|
||||
<td class="px-3 py-3">...</td>
|
||||
<!-- Actions column — rightmost, visible on row hover only -->
|
||||
<td class="px-3 py-3 opacity-0 group-hover:opacity-100 transition-opacity text-right">
|
||||
...
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
```
|
||||
|
||||
Add `group` class to `<tr>` to enable `group-hover` on the actions column.
|
||||
|
||||
**Column rules**:
|
||||
- Numbers: `text-right font-mono tabular-nums`
|
||||
- Dates: relative time for < 7 days ("2小时前"), absolute date for older ("2025-10-15")
|
||||
- Status: always a colored badge — never plain text
|
||||
- Long text: `truncate max-w-[200px]` with `title` attribute showing full value
|
||||
|
||||
**Default page size**: 25 rows. Options: 10 / 25 / 50 / 100.
|
||||
|
||||
**Pagination display**: Always show total count — "共 3,629 条，第 1–25 条"
|
||||
|
||||
**Empty state** (never just "暂无数据"):
|
||||
```html
|
||||
<tr>
|
||||
<td colspan="[N]" class="py-16 text-center">
|
||||
<div class="flex flex-col items-center gap-3">
|
||||
<svg class="w-12 h-12 text-gray-300" ...></svg> <!-- relevant icon -->
|
||||
<p class="text-base font-medium text-gray-500">暂无房源</p>
|
||||
<p class="text-sm text-gray-400">符合条件的房源将出现在这里</p>
|
||||
<a href="/property/add/" class="btn-primary btn-sm mt-2">新增房源</a>
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Status Badge
|
||||
|
||||
Status must always be communicated with **color + icon + text** (never color alone).
|
||||
|
||||
```html
|
||||
<!-- Base badge structure -->
|
||||
<span class="inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-xs font-medium">
|
||||
<svg class="w-3 h-3" ...></svg>
|
||||
状态文字
|
||||
</span>
|
||||
```
|
||||
|
||||
**Variant classes** (add to base):
|
||||
|
||||
| Status | Class |
|
||||
|---|---|
|
||||
| Active / 在售 | `bg-green-100 text-green-700` |
|
||||
| Warning / 即将过期 | `bg-yellow-100 text-yellow-700` |
|
||||
| Danger / 已删除 | `bg-red-100 text-red-700` |
|
||||
| Neutral / 已下架 | `bg-gray-100 text-gray-600` |
|
||||
| Info / 跟进中 | `bg-blue-100 text-blue-700` |
|
||||
| Brand / 出售 | `bg-orange-100 text-orange-700` |
|
||||
|
||||
---
|
||||
|
||||
### Modal / Dialog
|
||||
|
||||
**Size variants**:
|
||||
|
||||
| Size | Max-width | Use case |
|
||||
|---|---|---|
|
||||
| `sm` | `max-w-sm` (400px) | Confirmation dialogs, simple alerts |
|
||||
| `md` | `max-w-lg` (560px) | Forms with ≤ 5 fields |
|
||||
| `lg` | `max-w-2xl` (720px) | Complex forms, detail previews |
|
||||
| `xl` | `max-w-4xl` (960px) | Multi-step flows, wide content |
|
||||
|
||||
**Base modal structure**:
|
||||
```html
|
||||
<div x-data="{ open: false }">
|
||||
<!-- Backdrop -->
|
||||
<div x-show="open"
|
||||
x-transition:enter="transition ease-out duration-200"
|
||||
x-transition:enter-start="opacity-0"
|
||||
x-transition:enter-end="opacity-100"
|
||||
x-transition:leave="transition ease-in duration-150"
|
||||
x-transition:leave-start="opacity-100"
|
||||
x-transition:leave-end="opacity-0"
|
||||
@click="open = false"
|
||||
class="fixed inset-0 bg-black/50 z-40"
|
||||
aria-hidden="true">
|
||||
</div>
|
||||
|
||||
<!-- Panel -->
|
||||
<div x-show="open"
|
||||
x-transition:enter="transition ease-out duration-200"
|
||||
x-transition:enter-start="opacity-0 scale-95"
|
||||
x-transition:enter-end="opacity-100 scale-100"
|
||||
x-transition:leave="transition ease-in duration-150"
|
||||
x-transition:leave-start="opacity-100 scale-100"
|
||||
x-transition:leave-end="opacity-0 scale-95"
|
||||
role="dialog"
|
||||
aria-modal="true"
|
||||
x-trap="open"
|
||||
class="fixed inset-0 z-50 flex items-center justify-center p-4">
|
||||
<div class="bg-white rounded-xl shadow-xl w-full max-w-lg flex flex-col max-h-[90vh]">
|
||||
|
||||
<!-- Header -->
|
||||
<div class="flex items-center justify-between px-6 py-4 border-b border-gray-200 shrink-0">
|
||||
<h2 class="text-lg font-semibold text-gray-900">弹窗标题</h2>
|
||||
<button @click="open = false" aria-label="关闭" class="text-gray-400 hover:text-gray-600">
|
||||
<svg class="w-5 h-5" ...></svg>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<!-- Scrollable body -->
|
||||
<div class="px-6 py-4 overflow-y-auto flex-1">
|
||||
<!-- content -->
|
||||
</div>
|
||||
|
||||
<!-- Footer -->
|
||||
<div class="flex items-center justify-end gap-2 px-6 py-4 border-t border-gray-200 shrink-0">
|
||||
<button @click="open = false" class="btn-secondary">取消</button>
|
||||
<button class="btn-primary">确定</button>
|
||||
<!-- Destructive: danger button on RIGHT, cancel on LEFT — as shown above -->
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- Always trap focus inside modal (`x-trap` from Alpine.js Focus plugin)
|
||||
- ESC key always closes (Alpine handles this automatically with `x-trap`)
|
||||
- Click outside backdrop closes — unless form has unsaved changes → show confirmation
|
||||
- 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 an async action — wait for user to dismiss
|
||||
|
||||
---
|
||||
|
||||
### Drawer / Slide-over Panel
|
||||
|
||||
Used for editing content with many fields where the main page should remain visible for reference.
|
||||
|
||||
**When to use Drawer vs Modal**:
|
||||
|
||||
| Scenario | Component |
|
||||
|---|---|
|
||||
| Many fields, needs scrolling | Drawer |
|
||||
| Few fields (≤ 5), simple confirm | Modal |
|
||||
| User needs to reference main page data while editing | Drawer |
|
||||
|
||||
**Standard drawer** (slides in from the right):
|
||||
```html
|
||||
<div x-data="{ open: false }">
|
||||
<!-- Backdrop -->
|
||||
<div x-show="open"
|
||||
x-transition:enter="transition ease-out duration-300"
|
||||
x-transition:enter-start="opacity-0"
|
||||
x-transition:enter-end="opacity-100"
|
||||
@click="open = false"
|
||||
class="fixed inset-0 bg-black/30 z-40">
|
||||
</div>
|
||||
|
||||
<!-- Drawer panel -->
|
||||
<div x-show="open"
|
||||
x-transition:enter="transition ease-out duration-300"
|
||||
x-transition:enter-start="translate-x-full"
|
||||
x-transition:enter-end="translate-x-0"
|
||||
x-transition:leave="transition ease-in duration-200"
|
||||
x-transition:leave-start="translate-x-0"
|
||||
x-transition:leave-end="translate-x-full"
|
||||
role="dialog"
|
||||
aria-modal="true"
|
||||
class="fixed right-0 top-0 h-full w-[480px] bg-white z-50 shadow-xl flex flex-col">
|
||||
|
||||
<!-- Fixed header -->
|
||||
<div class="px-6 py-4 border-b border-gray-200 flex items-center justify-between shrink-0">
|
||||
<h2 class="text-lg font-semibold text-gray-900">抽屉标题</h2>
|
||||
<button @click="open = false" aria-label="关闭" class="text-gray-400 hover:text-gray-600">
|
||||
<svg class="w-5 h-5" ...></svg>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<!-- Scrollable content -->
|
||||
<div class="flex-1 overflow-y-auto px-6 py-4">
|
||||
<!-- content -->
|
||||
</div>
|
||||
|
||||
<!-- Fixed footer -->
|
||||
<div class="px-6 py-4 border-t border-gray-200 flex justify-end gap-2 shrink-0">
|
||||
<button @click="open = false" class="btn-secondary">取消</button>
|
||||
<button class="btn-primary">确定</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Width**: `w-[480px]` default; `w-[640px]` for wide content (image management, multi-column settings).
|
||||
|
||||
---
|
||||
|
||||
### Tab Navigation
|
||||
|
||||
**Standard tabs** (underline style):
|
||||
```html
|
||||
<div x-data="{ activeTab: 'info' }">
|
||||
<!-- Tab bar -->
|
||||
<div class="flex border-b border-gray-200">
|
||||
<button @click="activeTab = 'info'"
|
||||
:class="activeTab === 'info'
|
||||
? 'border-b-2 border-orange-500 text-orange-600 font-medium'
|
||||
: 'text-gray-500 hover:text-gray-700'"
|
||||
class="px-4 py-3 text-sm -mb-px">
|
||||
基本信息
|
||||
</button>
|
||||
<!-- more tabs -->
|
||||
</div>
|
||||
|
||||
<!-- Tab panels — use HTMX for content that requires server data -->
|
||||
<div x-show="activeTab === 'info'" class="pt-4">
|
||||
...
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Tab + HTMX** (for server-rendered tab content):
|
||||
```html
|
||||
<button hx-get="/property/123/tab/followup/"
|
||||
hx-target="#tab-content"
|
||||
hx-swap="innerHTML"
|
||||
@click="activeTab = 'followup'"
|
||||
:class="activeTab === 'followup' ? 'border-b-2 border-orange-500 text-orange-600 font-medium' : 'text-gray-500 hover:text-gray-700'"
|
||||
class="px-4 py-3 text-sm -mb-px">
|
||||
跟进记录
|
||||
</button>
|
||||
<div id="tab-content" class="pt-4">...</div>
|
||||
```
|
||||
|
||||
**URL-syncing tabs**: Use `hx-push-url="true"` on HTMX tab requests to make tabs bookmarkable.
|
||||
|
||||
---
|
||||
|
||||
### Toggle Switch
|
||||
|
||||
```html
|
||||
<button @click="val = !val"
|
||||
:aria-checked="val.toString()"
|
||||
role="switch"
|
||||
:class="val ? 'bg-orange-500' : 'bg-gray-300'"
|
||||
:disabled="disabled"
|
||||
class="relative w-10 h-5 rounded-full transition-colors duration-200 focus-visible:outline-2 focus-visible:outline-orange-500 focus-visible:outline-offset-2 disabled:opacity-50 disabled:cursor-not-allowed">
|
||||
<span :class="val ? 'translate-x-5' : 'translate-x-0.5'"
|
||||
class="absolute top-0.5 left-0 w-4 h-4 bg-white rounded-full shadow transition-transform duration-200">
|
||||
</span>
|
||||
</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Collapsible / Accordion
|
||||
|
||||
```html
|
||||
<div x-data="{ open: false }">
|
||||
<!-- Header row — clickable -->
|
||||
<div @click="open = !open"
|
||||
class="flex items-center justify-between px-4 py-3 cursor-pointer hover:bg-gray-50 select-none">
|
||||
<span class="text-sm font-medium text-gray-700">分组标题</span>
|
||||
<svg :class="open ? 'rotate-180' : ''"
|
||||
class="w-4 h-4 text-gray-400 transition-transform duration-200" ...></svg>
|
||||
</div>
|
||||
|
||||
<!-- Collapsible body — use x-collapse plugin for smooth height animation -->
|
||||
<div x-show="open" x-collapse class="px-4 pb-4">
|
||||
<!-- content -->
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
Requires Alpine.js `@alpinejs/collapse` plugin (official, ~1KB).
|
||||
|
||||
---
|
||||
|
||||
### Tree Select
|
||||
|
||||
For hierarchical data selection (org unit, staff assignment):
|
||||
|
||||
- **Small datasets** (< 200 nodes): Alpine.js renders full JSON tree client-side
|
||||
- **Large datasets**: HTMX lazy-loads child nodes on expand
|
||||
|
||||
Alpine.js data structure:
|
||||
```javascript
|
||||
{
|
||||
open: false,
|
||||
query: '',
|
||||
selected: null,
|
||||
nodes: [/* tree JSON from Django */],
|
||||
|
||||
toggle(node) { node.expanded = !node.expanded },
|
||||
select(node) { this.selected = node; this.open = false },
|
||||
|
||||
filteredNodes() {
|
||||
if (!this.query) return this.nodes
|
||||
// Recursive filter — preserves ancestors of matching nodes
|
||||
return this.filterTree(this.nodes, this.query.toLowerCase())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Multi-select Tag Input
|
||||
|
||||
For multi-value fields (e.g., property status, amenities):
|
||||
|
||||
```html
|
||||
<div x-data="multiSelect(options)"
|
||||
@click.away="open = false"
|
||||
class="relative">
|
||||
|
||||
<!-- Tag container / trigger -->
|
||||
<div @click="open = true"
|
||||
:class="open ? 'ring-2 ring-orange-500 border-orange-500' : 'border-gray-300'"
|
||||
class="flex flex-wrap gap-1 min-h-[36px] border rounded px-2 py-1.5 cursor-text bg-white">
|
||||
<template x-for="item in selected" :key="item.value">
|
||||
<span class="inline-flex items-center gap-1 bg-gray-100 text-gray-700 text-xs px-2 py-0.5 rounded">
|
||||
<span x-text="item.label"></span>
|
||||
<button @click.stop="remove(item)" aria-label="移除" class="text-gray-400 hover:text-gray-600">×</button>
|
||||
</span>
|
||||
</template>
|
||||
<input x-model="query" class="outline-none text-sm flex-1 min-w-[60px] bg-transparent" placeholder="搜索或选择">
|
||||
</div>
|
||||
|
||||
<!-- Dropdown -->
|
||||
<div x-show="open" class="absolute z-20 mt-1 w-full bg-white border border-gray-200 rounded shadow-md max-h-48 overflow-y-auto">
|
||||
<template x-for="option in filteredOptions()" :key="option.value">
|
||||
<div @click="toggle(option)"
|
||||
class="flex items-center justify-between px-4 py-2 text-sm hover:bg-gray-50 cursor-pointer">
|
||||
<span x-text="option.label"></span>
|
||||
<svg x-show="isSelected(option)" class="w-4 h-4 text-orange-500" ...></svg>
|
||||
</div>
|
||||
</template>
|
||||
<div x-show="filteredOptions().length === 0" class="px-4 py-3 text-sm text-gray-400">暂无匹配选项</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Date Range Picker
|
||||
|
||||
Use **Flatpickr** (CDN, ~16KB, zero framework dependency):
|
||||
|
||||
```javascript
|
||||
flatpickr("#date-range-input", {
|
||||
mode: "range",
|
||||
showMonths: 2,
|
||||
dateFormat: "Y-m-d",
|
||||
locale: "zh",
|
||||
});
|
||||
```
|
||||
|
||||
Override Flatpickr default styles with Tailwind to match our design system. Never build a date picker from scratch.
|
||||
|
||||
---
|
||||
|
||||
### Photo Gallery / Image Management
|
||||
|
||||
- Upload: **Filepond** (~50KB, zero framework dependency) — drag-and-drop, preview, progress, multi-file queue
|
||||
- Drag-to-reorder: **SortableJS** (~3KB) — use `handle: '.drag-handle'`
|
||||
- Lightbox preview: **Viewer.js** (~5KB) — zoom, rotate, thumbnail strip
|
||||
|
||||
All three are framework-free pure JS libraries, fully compatible with HTMX + Alpine.js.
|
||||
|
||||
---
|
||||
|
||||
## State & Feedback Patterns
|
||||
|
||||
### Loading States
|
||||
|
||||
| Duration | Pattern |
|
||||
|---|---|
|
||||
| < 300ms | Nothing — avoid flash of spinner |
|
||||
| 300ms – 1s | Inline spinner (`animate-spin`) |
|
||||
| 1s – 3s | Spinner + "加载中..." text |
|
||||
| > 3s | Progress bar + estimated time |
|
||||
| Background Celery task | Subtle pulsing indicator in top nav |
|
||||
|
||||
HTMX automatically adds `htmx-request` class during requests — use it to show/hide indicators:
|
||||
```html
|
||||
<div class="htmx-indicator">
|
||||
<svg class="animate-spin w-4 h-4 text-orange-500" ...></svg>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Empty States
|
||||
|
||||
Every list, table, and data view must handle the empty state. Required elements:
|
||||
|
||||
1. Relevant icon (not a generic "no data" icon — use something contextually relevant)
|
||||
2. Friendly headline ("暂无房源")
|
||||
3. Explanation ("符合当前筛选条件的房源将出现在这里")
|
||||
4. CTA if the user can fix it ("新增第一条房源 →")
|
||||
|
||||
```html
|
||||
<div class="flex flex-col items-center justify-center py-16 text-center">
|
||||
<svg class="w-12 h-12 text-gray-300 mb-4" ...></svg>
|
||||
<p class="text-base font-medium text-gray-500 mb-1">暂无房源</p>
|
||||
<p class="text-sm text-gray-400 mb-4">符合当前筛选条件的房源将出现在这里</p>
|
||||
<a href="/property/add/" class="btn-primary btn-sm">新增房源</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Toast Notifications
|
||||
|
||||
| Type | When to use | Duration | Classes |
|
||||
|---|---|---|---|
|
||||
| `success` | Async action completed | 3s auto-dismiss | `bg-green-50 border-green-200 text-green-800` |
|
||||
| `error` | Action failed, user must retry | Persistent (manual dismiss) | `bg-red-50 border-red-200 text-red-800` |
|
||||
| `warning` | Completed with caveats | 5s | `bg-yellow-50 border-yellow-200 text-yellow-700` |
|
||||
| `info` | Background process started | 3s | `bg-blue-50 border-blue-200 text-blue-700` |
|
||||
|
||||
**Rules**:
|
||||
- Max 3 toasts visible at once (queue the rest)
|
||||
- Never show success toast for page navigations
|
||||
- Error toasts must include a retry action button when possible
|
||||
- Never use toast for validation errors — show inline instead
|
||||
- Position: `fixed bottom-4 right-4 z-50 flex flex-col gap-2`
|
||||
|
||||
Trigger via HTMX response header: `HX-Trigger: {"showToast": {"type": "success", "message": "保存成功"}}`
|
||||
|
||||
---
|
||||
|
||||
### Inline Edit (Read/Edit Mode Toggle)
|
||||
|
||||
For settings pages and detail views that support in-place editing:
|
||||
|
||||
```html
|
||||
<div x-data="{ editing: false, snapshot: null }"
|
||||
@keydown.escape="editing = false; restoreSnapshot()">
|
||||
|
||||
<button x-show="!editing" @click="editing = true; snapshot = JSON.parse(JSON.stringify(data))"
|
||||
class="btn-secondary btn-sm">编辑</button>
|
||||
<div x-show="editing" class="flex gap-2">
|
||||
<button @click="editing = false; restoreSnapshot()" class="btn-secondary btn-sm">取消</button>
|
||||
<button hx-post="/settings/save/" hx-vals="js:data" @click="editing = false" class="btn-primary btn-sm">保存</button>
|
||||
</div>
|
||||
|
||||
<!-- Each field toggles between read and edit mode -->
|
||||
<div class="flex justify-between py-3 border-b border-gray-100">
|
||||
<span class="text-sm text-gray-500">工龄计算方式</span>
|
||||
<span x-show="!editing" class="text-sm text-gray-900" x-text="data.tenureBasis"></span>
|
||||
<select x-show="editing" x-model="data.tenureBasis" class="input-sm">
|
||||
<option>从首次入职开始计算</option>
|
||||
</select>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Cancel rule**: Always snapshot data before entering edit mode. On cancel, restore from snapshot (3 lines). Never leave the user with unsaved partial edits on cancel.
|
||||
|
||||
---
|
||||
|
||||
## Responsive Breakpoints
|
||||
|
||||
**Strategy**: Desktop-first (target users are ≥ 85% desktop/Windows Electron client).
|
||||
|
||||
| Breakpoint | Tailwind prefix | Viewport | Target |
|
||||
|---|---|---|---|
|
||||
| Desktop | (base, no prefix) | > 1280px | Primary design target |
|
||||
| Laptop | `lg:` | ≥ 1024px | Minor layout adjustments |
|
||||
| Tablet | `md:` | ≥ 768px | Collapsed sidebar |
|
||||
| Mobile | `sm:` | ≥ 640px | Single column, no tables |
|
||||
|
||||
**Component-specific rules**:
|
||||
- Data tables → `overflow-x-auto` on `md` and below
|
||||
- Sidebar → collapses to icon-only or hidden on `md`; bottom nav on `sm`
|
||||
- Modals → full-screen (`inset-0 rounded-none`) on `sm`
|
||||
- Multi-column forms → single column on `md` and below (`md:grid-cols-1`)
|
||||
- Drawers → full-width on `sm` (`sm:w-full`)
|
||||
|
||||
**Never**:
|
||||
- Hide critical functionality on mobile — adapt it, do not remove it
|
||||
- Use fixed px widths for layout containers (use `max-w-*` instead)
|
||||
- Assume touch input on desktop
|
||||
|
||||
---
|
||||
|
||||
## Motion & Animation
|
||||
|
||||
**Principle**: Motion communicates state, it does not decorate.
|
||||
|
||||
**Duration scale**:
|
||||
|
||||
| Token | Duration | Use for |
|
||||
|---|---|---|
|
||||
| `duration-100` | 100ms | Micro-interactions (checkbox tick, toggle) |
|
||||
| `duration-200` | 200ms | Most transitions (hover, focus, fade) — default |
|
||||
| `duration-300` | 300ms | Larger elements (modal enter, drawer slide) |
|
||||
| `duration-500` | 500ms | Page-level transitions only |
|
||||
|
||||
**Easing**:
|
||||
- Default UI transitions: `ease-out` (enter) / `ease-in` (leave)
|
||||
- Playful/spring: avoid in this product — we are a business tool
|
||||
- Progress bars: `linear`
|
||||
|
||||
**What to animate**:
|
||||
- `opacity` — enter/exit fades
|
||||
- `transform: translateY / translateX` — panel slide-in
|
||||
- `max-height` with `x-collapse` — accordion expand
|
||||
|
||||
**Never animate**:
|
||||
- `width` or `height` directly — use `max-height` with `x-collapse` or `transform`
|
||||
- `top / left / right / bottom` — use `transform: translate` instead
|
||||
- `box-shadow` on hover — use opacity-layered pseudo-element trick instead
|
||||
- Anything if `prefers-reduced-motion: reduce` is set:
|
||||
|
||||
```css
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
*, *::before, *::after {
|
||||
animation-duration: 0.01ms !important;
|
||||
transition-duration: 0.01ms !important;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Accessibility (Non-negotiable)
|
||||
|
||||
**Every component must**:
|
||||
- Meet WCAG 2.1 AA contrast ratios (4.5:1 for body text, 3:1 for large text ≥ 18px)
|
||||
- Be fully keyboard navigable (Tab, Shift+Tab, Enter, Space, Escape)
|
||||
- Have visible focus indicators — never `outline: none` without a custom replacement using `focus-visible:`
|
||||
- Work with screen readers (proper ARIA roles and labels)
|
||||
|
||||
**Required patterns**:
|
||||
|
||||
| Element | Requirement |
|
||||
|---|---|
|
||||
| Icon-only buttons | `aria-label="操作名称"` always |
|
||||
| Form inputs | `id` attribute + `<label for="...">` pairing always |
|
||||
| Images | `alt` text always (empty `alt=""` for decorative images) |
|
||||
| Modals | `role="dialog"` + `aria-modal="true"` + focus trap (`x-trap`) |
|
||||
| Loading states | `aria-busy="true"` on the loading container |
|
||||
| Error messages | `aria-describedby` linking input `id` to error `id` |
|
||||
| Toggle switches | `role="switch"` + `aria-checked` |
|
||||
| Status indicators | color + icon + text (never color alone) |
|
||||
|
||||
**Color alone is never enough**:
|
||||
- Status badges: color background + icon + text label
|
||||
- Form errors: red border + error icon + text message below field
|
||||
- Charts: color + pattern or direct label
|
||||
|
||||
---
|
||||
|
||||
## UI Anti-patterns — Never Do These
|
||||
|
||||
**Layout**:
|
||||
- Body text wider than 72 characters without `max-w-prose`
|
||||
- Full-width buttons on desktop (use `max-w-xs` or `w-auto`)
|
||||
- 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 — always provide an alternative
|
||||
- Hover-only affordances (invisible until hovered)
|
||||
- Auto-submitting forms on field change without explicit "保存" action
|
||||
|
||||
**Feedback**:
|
||||
- Generic error messages: "出错了" or "Something went wrong" — always be specific
|
||||
- Success messages that do not tell the user what happened ("已保存" with no context)
|
||||
- Blocking the UI with a modal spinner for optimistic actions
|
||||
- Using `window.alert()`, `window.confirm()`, or `window.prompt()` — use our Dialog component
|
||||
|
||||
**Content**:
|
||||
- Lorem ipsum in any committed code or template
|
||||
- Hardcoded user names, emails, or phone numbers in components
|
||||
- Placeholder images — use the Avatar initials fallback component
|
||||
|
||||
**Spacing**:
|
||||
- `p-5`, `p-7`, `p-9`, `p-10`, `p-11` — off-grid values, never use
|
||||
- Arbitrary values like `p-[13px]` — always round to the nearest grid value
|
||||
|
||||
---
|
||||
|
||||
## Third-party Libraries Approved for Use
|
||||
|
||||
The following libraries are pre-approved. Do not introduce any library not on this list without updating this document.
|
||||
|
||||
| Library | Version | Purpose | CDN size |
|
||||
|---|---|---|---|
|
||||
| HTMX | 2.x | Partial DOM updates, server interactions | ~14KB |
|
||||
| Alpine.js | 3.x | Frontend state management | ~15KB |
|
||||
| Alpine `@alpinejs/collapse` | official | Smooth accordion height animation | ~1KB |
|
||||
| Alpine `@alpinejs/focus` | official | Focus trapping in modals | ~3KB |
|
||||
| Tailwind CSS | 3.x | Utility-first styling | (purged) |
|
||||
| Flatpickr | 4.x | Date range picker | ~16KB |
|
||||
| Filepond | 4.x | File upload with preview | ~50KB |
|
||||
| SortableJS | 1.x | Drag-to-reorder lists and grids | ~3KB |
|
||||
| Viewer.js | 1.x | Image lightbox preview | ~5KB |
|
||||
|
||||
**Never introduce**: React, Vue, Angular, jQuery, Lodash, Moment.js, Bootstrap, or any component library built for a JS framework.
|
||||
Reference in New Issue
Block a user