# Design System Master File

> **LOGIC:** When building a specific page, first check `design-system/智念助手/pages/[page-name].md`.
> If that file exists, its rules **override** this Master file.
> If not, strictly follow the rules below.

---

**Project:** 智念助手
**Generated:** 2026-04-26 16:21:54
**Category:** Micro SaaS

---

## Global Rules

### Color Palette

| Role | Hex | CSS Variable |
|------|-----|--------------|
| Primary | `#1E3A8A` | `--color-primary` |
| Secondary | `#3B82F6` | `--color-secondary` |
| CTA/Accent | `#CA8A04` | `--color-cta` |
| Background | `#F8FAFC` | `--color-background` |
| Text | `#1E40AF` | `--color-text` |

**Color Notes:** Luxury navy + gold service

### Typography

- **Preferred Implementation:** System font stack first for desktop reliability and China-network/offline friendliness.
- **Heading Font:** `-apple-system`, `BlinkMacSystemFont`, `PingFang SC`, `Microsoft YaHei`, `Segoe UI`, sans-serif
- **Body Font:** `-apple-system`, `BlinkMacSystemFont`, `PingFang SC`, `Microsoft YaHei`, `Segoe UI`, sans-serif
- **Reference Pairing:** Rubik + Nunito Sans can inform proportions, but should not be required at runtime.
- **Mood:** mature B-end operations, precise desktop tooling, calm AI assistant

**Optional Reference Import:**
```css
@import url('https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Rubik:wght@300;400;500;600;700&display=swap');
```

### Spacing Variables

| Token | Value | Usage |
|-------|-------|-------|
| `--space-xs` | `4px` / `0.25rem` | Tight gaps |
| `--space-sm` | `8px` / `0.5rem` | Icon gaps, inline spacing |
| `--space-md` | `16px` / `1rem` | Standard padding |
| `--space-lg` | `24px` / `1.5rem` | Section padding |
| `--space-xl` | `32px` / `2rem` | Large gaps |
| `--space-2xl` | `48px` / `3rem` | Section margins |
| `--space-3xl` | `64px` / `4rem` | Hero padding |

### Shadow Depths

| Level | Value | Usage |
|-------|-------|-------|
| `--shadow-sm` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle lift |
| `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | Cards, buttons |
| `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modals, dropdowns |
| `--shadow-xl` | `0 20px 25px rgba(0,0,0,0.15)` | Hero images, featured cards |

---

## Component Specs

### Buttons

```css
/* Primary Button */
.btn-primary {
  background: #CA8A04;
  color: white;
  padding: 12px 24px;
  border-radius: 8px;
  font-weight: 600;
  transition: all 200ms ease;
  cursor: pointer;
}

.btn-primary:hover {
  opacity: 0.9;
  transform: translateY(-1px);
}

/* Secondary Button */
.btn-secondary {
  background: transparent;
  color: #1E3A8A;
  border: 2px solid #1E3A8A;
  padding: 12px 24px;
  border-radius: 8px;
  font-weight: 600;
  transition: all 200ms ease;
  cursor: pointer;
}
```

### Cards

```css
.card {
  background: #F8FAFC;
  border-radius: 12px;
  padding: 24px;
  box-shadow: var(--shadow-md);
  transition: all 200ms ease;
  cursor: pointer;
}

.card:hover {
  box-shadow: var(--shadow-lg);
  transform: translateY(-2px);
}
```

### Inputs

```css
.input {
  padding: 12px 16px;
  border: 1px solid #E2E8F0;
  border-radius: 8px;
  font-size: 16px;
  transition: border-color 200ms ease;
}

.input:focus {
  border-color: #1E3A8A;
  outline: none;
  box-shadow: 0 0 0 3px #1E3A8A20;
}
```

### Modals

```css
.modal-overlay {
  background: rgba(0, 0, 0, 0.5);
  backdrop-filter: blur(4px);
}

.modal {
  background: white;
  border-radius: 16px;
  padding: 32px;
  box-shadow: var(--shadow-xl);
  max-width: 500px;
  width: 90%;
}
```

---

## Style Guidelines

**Style:** Flat Design

**Keywords:** 2D, minimalist, bold colors, no shadows, clean lines, simple shapes, typography-focused, modern, icon-heavy

**Best For:** Web apps, mobile apps, cross-platform, startup MVPs, user-friendly, SaaS, dashboards, corporate

**Key Effects:** No gradients/shadows, simple hover (color/opacity shift), fast loading, clean transitions (150-200ms ease), minimal icons

### Product Identity

- **Product Name:** 智念助手
- **Desktop App ID:** `app.zhinian.assistant`
- **Primary Mark:** Rounded navy app tile with a blue conversation panel, white intelligence loop, and restrained gold service line.
- **Brand Assets:**
  - App icon source: `resources/icons/icon.svg`
  - Plain app mark: `resources/icons/icon-plain.svg`
  - Tray template source: `resources/icons/tray-icon-template.svg`
  - Renderer wordmark: `src/assets/logo.svg`
- **Generated Desktop Assets:**
  - `resources/icons/icon.png`
  - `resources/icons/icon.icns`
  - `resources/icons/icon.ico`
  - `resources/icons/16x16.png` through `512x512.png`
  - `resources/icons/tray-icon-Template.png`

### Product Shell Rules

- Desktop shell must say `智念助手` in customer-facing places.
- Product language should describe the selected tenant as a `工作空间` or `业务对象`, not as a hotel.
- Keep `ClawX` and `OpenClaw` only in technical contexts, developer documentation, compatibility tests, or advanced implementation surfaces.
- Login, Sidebar, Windows title bar, tray menu, installer metadata, and desktop shortcuts should all use the 智念助手 brand.
- The design should feel like a mature operations product, not a marketing landing page.

### Implemented UI Primitives

The renderer design kit lives in `src/components/yinian/ui.tsx`.

- `YinianPageShell`
- `YinianPageHeader`
- `YinianHeaderActions`
- `YinianKicker`
- `YinianPanel`
- `YinianSectionPanel`
- `YinianMetricCard`
- `YinianListItem`
- `YinianInfoRow`
- `YinianNotice`
- `YinianEmptyState`
- `YinianStatusDot`

Use these before adding page-local card/list/notice styling. New primitives should stay thin and composable over existing React/Tailwind/shadcn foundations.

### Implemented Page Direction

- **Login:** enterprise desktop entry with brand narrative, reliability cues, and a focused organization account form.
- **Today:** operations cockpit using section panels, metric cards, task queue rows, and clear skill state labels.
- **Skills Manager:** capability management surface with clear entitlement/local registry/version state separation.
- **Sidebar Service Context:** one account maps to one B-end service for now; show the current service, region, role, and user inside the left sidebar instead of a top switcher. The service card is also the Dashboard/Today entry.
- **Sidebar:** production navigation is intentionally narrow: `快速使用` for Skills/定时任务/知识库, `对话` for New Chat/History, and a footer Settings entry. Do not expose Models, Agents, Channels, or Dev Console in normal customer navigation.
- **Chat History:** history should not be a permanently expanded side list. Use a compact `历史会话` row that opens a hover popover on pointer devices and clicks through to the latest session.
- **Knowledge Base:** knowledge upload is a first-class quick-use tool. The v0 UI may be local-only, but it should present as a service-scoped document library that will later connect to indexing and permissions.
- **Settings:** account actions, service config sync, logout, local preferences, and the "configuration is service-managed" explanation belong in Settings.
- **Service-Managed Configuration:** model/provider strategy, Agent orchestration, notification channels, and low-level scheduling policy are issued by the service side for the current account/service. Local editing controls for these areas should stay disabled or hidden unless an explicit admin/developer mode is added.
- **Inherited Chinese Surfaces:** customer-visible Chinese strings in Chat, Settings, and Setup should say 智念助手; keep ClawX/OpenClaw only where the user is explicitly in technical or compatibility context.
- **Inherited Page Typography:** inherited dashboard pages should not use oversized serif page titles. Use system-font, semibold headings with compact desktop-dashboard scale.
- **Customer-Visible Chinese Copy:** zh locale should avoid ClawX unless describing a technical compatibility or upstream/open-source context.

### Visual QA Baselines

The production 智念 flow has a repeatable screenshot smoke test in `tests/e2e/yinian-visual-smoke.spec.ts`.

- Login baseline: `test-results/yinian-visual/01-login.png`
- Today baseline: `test-results/yinian-visual/02-today.png`
- Skills baseline: `test-results/yinian-visual/03-skills.png`
- Knowledge baseline: `test-results/yinian-visual/04-knowledge.png`
- Settings baseline: `test-results/yinian-visual/05-settings.png`

Run `pnpm run build:vite` before `pnpm exec playwright test tests/e2e/yinian-visual-smoke.spec.ts` so Electron loads the latest built renderer.

### Page Pattern

**Pattern Name:** Product Demo + Features

- **Conversion Strategy:** Embedded product demo increases engagement. Use interactive mockup if possible. Auto-play video muted.
- **CTA Placement:** Video center + CTA right/bottom
- **Section Order:** 1. Hero, 2. Product video/mockup (center), 3. Feature breakdown per section, 4. Comparison (optional), 5. CTA

---

## Anti-Patterns (Do NOT Use)

- ❌ Complex onboarding flow
- ❌ Cluttered layout

### Additional Forbidden Patterns

- ❌ **Emojis as icons** — Use SVG icons (Heroicons, Lucide, Simple Icons)
- ❌ **Missing cursor:pointer** — All clickable elements must have cursor:pointer
- ❌ **Layout-shifting hovers** — Avoid scale transforms that shift layout
- ❌ **Low contrast text** — Maintain 4.5:1 minimum contrast ratio
- ❌ **Instant state changes** — Always use transitions (150-300ms)
- ❌ **Invisible focus states** — Focus states must be visible for a11y

---

## Pre-Delivery Checklist

Before delivering any UI code, verify:

- [ ] No emojis used as icons (use SVG instead)
- [ ] All icons from consistent icon set (Heroicons/Lucide)
- [ ] `cursor-pointer` on all clickable elements
- [ ] Hover states with smooth transitions (150-300ms)
- [ ] Light mode: text contrast 4.5:1 minimum
- [ ] Focus states visible for keyboard navigation
- [ ] `prefers-reduced-motion` respected
- [ ] Responsive: 375px, 768px, 1024px, 1440px
- [ ] No content hidden behind fixed navbars
- [ ] No horizontal scroll on mobile