agent/design.md

森林AI UI Design Guide

Purpose

This file defines the shared visual direction for 森林AI. 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

森林AI 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.