Design System
AgentHub Home follows the shared TokenDance design contract while preserving the product-specific Desktop workbench feel. This page documents the public-site design rules so that the homepage, docs, mock UI, icons, and motion stay aligned.
Design source
The cross-repository design contract is owned by the TokenDance workspace docs. This page is the AgentHub public-site implementation guide: it translates those rules into website and docs decisions.
Visual Direction
AgentHub should feel like a calm engineering tool, not a marketing poster. The surface should be dense enough for repeated work, yet still readable on first visit.
| Principle | Rule |
|---|---|
| Light first | Default to light surfaces, soft shadows, and readable contrast |
| TokenDance Blue | Use rgb(0, 113, 188) / #0071BC as the primary brand anchor |
| No old purple drift | Do not reintroduce purple gradients, rainbow bars, or unrelated accent strips |
| Compact by default | Keep nav, pills, cards, and docs controls tight and aligned |
| Desktop fidelity | The homepage mock should resemble AgentHub Desktop behavior and state |
| Honest status | Visual polish must not imply that unfinished features are generally available |
Color Tokens
| Token intent | Value | Usage |
|---|---|---|
| Brand | #0071BC | Primary CTA, active state, focus affordance |
| Brand bright | #29ABE2 | Logo secondary blue, small highlights |
| Canvas | #F5F5F7 | Page background |
| Surface | #FFFFFF | Cards, docs body, mock panels |
| Surface muted | #F8FAFC | Nested tool panels and sidebars |
| Ink | #13111C | Primary text |
| Ink muted | #6B6575 | Secondary text |
| Hairline | rgba(19, 17, 28, 0.08) | Borders and separators |
Token Usage Rules
Public-site components should use semantic tokens before hardcoded colors. Before adding a color, identify its intent:
| Intent | Preferred variables | Use |
|---|---|---|
| Brand action | --brand, --brand-hover, --brand-soft | CTA, active item, link hover, focus affordance |
| Page surface | --canvas, --surface-1, --surface-2, --surface-3 | Page background, docs body, mock panels, nested tool areas |
| Text | --ink, --ink-muted, --ink-subtle | Body copy, helper copy, metadata |
| Boundaries | --hairline, --hairline-strong | Cards, tables, sidebars, mock-window separators |
| State | --state-success, --state-warning, --state-danger, --state-offline | Run state, errors, health checks, offline targets |
| Docs | --docs-active-bg, --inline-code-bg, --cta-band-bg | Docs active item, inline code, bottom CTA |
If a component needs a new color, name the product intent first, then map it to TokenDance Blue, moss, or neutral surfaces. Do not put purple, rainbow, hard black, or one-off rgba(...) values directly into components.
Components
| Component | Design rule |
|---|---|
| Navigation | Keep login at the far right, GitHub as an icon link, and language control compact |
| Buttons | Use clear labels for commands; use icons for recognizable actions like GitHub |
| Pills | Light border, low-contrast shadow, no heavy outline |
| Docs sidebar | Stable width, readable nested groups, active item uses TokenDance Blue |
| Tables | Render as real tables with horizontal overflow handling on mobile |
| Code blocks | Provide copy affordance, preserve line-wrapping constraints, and avoid page overflow |
| Footer | Use white/light surface, not hard black |
Desktop Mock
The homepage demo is not decoration. It should preview how AgentHub Desktop behaves:
- theme and language follow the website theme/language;
- conversation state can advance automatically without layout jumps;
- file, diff, preview, and terminal panels look like a real workbench;
- hover states are subtle and should not show browser focus rectangles inside the mock;
- runtime logos should use canonical brand icons, including Claude Code and Codex where available;
- scale should be applied without a first-frame flash at full size.
Motion
Motion should aid comprehension, not compete with content.
| Pattern | Rule |
|---|---|
| Page entrance | Short opacity/translate motion; no large bouncing or jumping text |
| Mock playback | Smooth state transitions between chat, files, diff, and preview |
| Hover | Slight lift or color change; avoid heavy shadows |
| Theme switch | Site and mock theme update together |
| Reduced motion | Respect prefers-reduced-motion and keep content readable without animation |
Interaction States
Interaction states should be complete without being loud:
| State | Rule |
|---|---|
| Hover | Use subtle background, border, or shadow changes; do not show blue DOM focus boxes inside the mock |
| Active/selected | Use low-saturation TokenDance Blue backgrounds and fine borders instead of large solid fills |
| Focus-visible | Keep accessible focus on real forms, links, and buttons; suppress browser-default outlines in pure demo mock surfaces |
| Loading | Keep container dimensions stable and avoid hydration flashes from full size to scaled size |
| Error | Use a clear state color and explanatory copy, not just a red dot or generic toast |
| Disabled | Lower contrast while preserving layout size, avoiding button-width changes |
Docs, the homepage mock, and future login/register entries should share this state language. Hovering a mock control or a real button should feel like one product system, not a temporary demo.
Icon Rules
- Use
lucide-reactfor generic UI commands where a matching icon exists. - Use
@lobehub/iconsfor AI/LLM/runtime brand marks when available. - Use the GitHub mark for the GitHub nav link instead of a text-only item.
- Do not draw custom brand-like icons when canonical assets exist.
- Keep icons optically aligned with pill/button height.
Documentation Page Rules
Docs are product manuals, not a generic blog template:
- Every status page should explain what can be done, what is not promised, and what evidence is needed to promote status.
- Every integration page should identify the owner, event entry, failure state, secret boundary, and public/private evidence boundary.
- Every configuration page should explain variable ownership without revealing real keys, hosts, SSH aliases, or rollback paths.
- English and Chinese pages stay structurally aligned: heading hierarchy, status words, table semantics, and security boundaries match.
- Examples use placeholder hosts/tokens/paths and prefer the smallest copyable request.
Visual QA
Before publishing visible changes, capture:
/zhand/endesktop first viewport;/zhmobile first viewport;- at least one docs page on desktop and mobile;
- theme switch state, language switch state, and mock playback state.
Check for old purple, hard black surfaces, text wrapping in nav/buttons, table overflow, mock focus rectangles, stale language in the mock, and wrong runtime logos.