docs: add ui design guide

design.md

@@ -0,0 +1,227 @@
+# SenlinAI UI Design Guide
+
+## Purpose
+
+This file defines the shared visual direction for SenlinAI Workbench. It keeps future UI work consistent across the login page, project shell, channel pages, object inspector, and desktop wrapper.
+
+The visual reference is shadcn/ui: quiet, structured, component-driven, and practical. This is a visual reference only. The web app must remain Svelte and TypeScript, and must not add React or shadcn/ui as runtime dependencies.
+
+## Product Feel
+
+SenlinAI is a private project workbench for focused knowledge work. The UI should feel calm, precise, and durable rather than decorative. It should support long sessions, dense information, fast scanning, and frequent switching between projects and channels.
+
+Use a restrained desktop-app tone:
+
+- Clear hierarchy.
+- Compact but breathable spacing.
+- Low-noise borders and surfaces.
+- Strong focus states.
+- Predictable controls.
+- Minimal decoration.
+
+Avoid:
+
+- Marketing-style hero sections inside the app.
+- Large decorative gradients.
+- Floating page sections styled as cards.
+- Nested cards.
+- One-color themes dominated by a single hue.
+- Purely visual icon buttons without labels for assistive technology.
+
+## Layout Principles
+
+The main workbench uses a Discord-like project model:
+
+- Project rail: narrow, persistent, dynamic project list.
+- Channel sidebar: current project navigation and recent sessions.
+- Main content: channel-specific page.
+- Object inspector: discussion, properties, and more actions.
+- Topbar: search and global navigation.
+
+Desktop is the primary layout. Mobile should remain usable by collapsing the project rail, channel sidebar, and inspector into drawers or full-screen panels.
+
+Use stable dimensions for fixed UI elements:
+
+- Project icons: fixed square or circle size.
+- Channel rows: fixed minimum height.
+- Icon buttons: fixed square hit area.
+- Task cards: stable padding and content rhythm.
+- Inspector tabs: consistent height.
+
+## Color
+
+Use neutral surfaces first:
+
+- App background: soft gray.
+- Panels and toolbars: white or near-white.
+- Borders: light neutral gray.
+- Primary text: near-black neutral.
+- Secondary text: muted gray.
+
+Use one clear brand/action blue for:
+
+- Primary buttons.
+- Active channel indicator.
+- Selected tabs.
+- Focus-visible outlines when appropriate.
+
+Use semantic colors sparingly:
+
+- Success: completed tasks and successful sync states.
+- Warning: delayed tasks or partial states.
+- Danger: destructive actions and errors.
+
+Do not use color as the only state indicator. Pair color with text, icon shape, or position.
+
+## Typography
+
+Use the existing system font stack unless a design-system font is explicitly added later.
+
+Typography should be compact and readable:
+
+- Page title: clear but not oversized.
+- Panel title: medium weight.
+- Row/card title: strong enough for scanning.
+- Metadata: smaller and muted.
+- Button text: short and action-oriented.
+
+Do not scale font size with viewport width. Letter spacing should stay at `0`.
+
+## Spacing
+
+Use a small spacing scale:
+
+- 4px for tight internal gaps.
+- 8px for standard control gaps.
+- 12px for row and card content spacing.
+- 16px for panel padding.
+- 24px for major page spacing.
+
+Dense work surfaces can use tighter spacing, but text and controls must not feel cramped.
+
+## Radius And Borders
+
+Use shadcn-like restrained shapes:
+
+- Inputs, buttons, tabs, cards, menus: 6px to 8px radius.
+- Project avatars can be circular when matching the Discord-like rail.
+- Avoid large pill shapes except for count badges or compact status labels.
+
+Use borders to define structure before shadows. Shadows should be subtle and reserved for menus, dialogs, popovers, and floating inspectors.
+
+## Components
+
+Buttons:
+
+- Primary button for the main action on a surface.
+- Secondary/outline button for supporting actions.
+- Ghost button for toolbar and icon actions.
+- Destructive button only for irreversible actions.
+
+Inputs:
+
+- Labels must be explicit.
+- Errors must appear near the field.
+- Focus state must be visible.
+
+Tabs:
+
+- Use tabs for Discussion, Properties, and More in the inspector.
+- Active tab must be visually clear and keyboard accessible.
+
+Cards:
+
+- Use cards for tasks, repeated records, and object summaries.
+- Do not place cards inside cards.
+- Keep task cards compact, with complete/incomplete state visible.
+
+Badges:
+
+- Use badges for counts, status, tags, and source type.
+- Count badges in the channel sidebar should be compact and aligned.
+
+Menus:
+
+- Use menus for secondary actions.
+- Destructive actions should be separated or clearly styled.
+
+## Channel Templates
+
+Each system channel has its own page template.
+
+Message Flow:
+
+- Similar to email.
+- Use a list of messages with sender/source, subject, summary, timestamp, status, and tags.
+- Selected message opens details in the inspector.
+
+Work Plan:
+
+- Similar to Todo software.
+- Use task cards with complete/incomplete controls.
+- Show owner, due date, tags, and status.
+
+AI Sessions:
+
+- Use a session list plus selected conversation detail.
+- Show context references and save/convert actions clearly.
+
+Notes And Sources:
+
+- Similar to file and attachment management.
+- Support list and metadata-heavy rows.
+- Show file type, note/source type, updated time, tags, and source.
+
+Cron Plans:
+
+- Similar to scheduled task management.
+- Show enabled state, schedule, next run, last result, and owner.
+- Keep this as plan/reminder management unless a later spec expands backend execution.
+
+Custom Channel:
+
+- Use title, icon, and URL.
+- Show open and copy actions.
+- Do not make it a separate content system in MVP.
+
+## Login Page
+
+The login page should feel like a private deployment entry point:
+
+- Server address first.
+- Email or username.
+- Password.
+- Clear login button.
+- Connection and error state.
+- Remembered server address.
+
+Avoid a marketing landing page. The first screen should let the user log in.
+
+## Accessibility
+
+Every icon button needs an accessible name.
+
+Keyboard users must be able to:
+
+- Move through project rail items.
+- Move through channel rows.
+- Search.
+- Switch inspector tabs.
+- Toggle task completion.
+- Open menus.
+- Submit login.
+
+Focus-visible states must be clear. Error states must use text and not color alone.
+
+## Implementation Notes
+
+Use Svelte components and local CSS. A future design token file may be introduced, but until then, keep colors, spacing, radius, and typography consistent with this document.
+
+Before finishing UI work, check:
+
+- Text does not overflow buttons, cards, sidebars, or tabs.
+- Mobile layout remains usable.
+- Active project and active channel are obvious.
+- Counts and statuses are readable.
+- Empty states explain what the user can do next.
+- The UI does not depend on placeholder boxes or decorative fake assets.

docs/superpowers/specs/2026-07-19-discord-style-project-workbench-design.md

@@ -241,6 +241,18 @@ MVP 限制：
 - 状态徽标不能只依赖颜色表达。
 - 表单错误需要文本说明，并通过 `aria-live` 或等价方式通知。
 
+## 视觉风格
+
+UI 视觉风格参考 shadcn/ui 的克制、清晰、组件化表达，但前端仍只使用 Svelte，不引入 React 或 shadcn/ui 依赖。视觉统一规则以仓库根目录 `design.md` 为准。
+
+后续页面和组件应遵循：
+
+- 中性色为主，少量品牌色用于选中态、主按钮和关键状态。
+- 卡片、输入框、列表、tabs、菜单、弹窗等控件保持一致的边框、圆角、间距和焦点状态。
+- 工作台页面优先信息密度和可扫描性，避免营销页式大 hero、装饰性渐变和过度卡片化。
+- 图标优先使用语义明确的按钮图标，文字仅用于清晰命令或需要解释的动作。
+- 每个频道页面可以有不同布局，但基础控件和状态表达必须一致。
+
 ## 技术落点
 
 前端仍使用 Svelte 和 TypeScript，不引入 React。