secrets/apps/desktop/design/DESIGN.md

Secrets Design System

1. Visual Theme & Atmosphere

• Primary inspiration: Raycast desktop UI.
• Secondary influence: Linear information density and list discipline.
• Product personality: secure, local-first, developer-facing, restrained, trustworthy.
• Default mood: dark utility app, not a marketing site and not a glossy consumer app.
• The interface should feel like a native desktop control surface for secrets and MCP integrations.
• Use calm contrast, clean edges, compact spacing, and intentional empty space.
• Prefer precision over decoration. Visual polish should come from alignment, spacing, and hierarchy.

2. Color Palette & Roles

Core Surfaces

• bg.app: #0A0A0B - app background, deepest canvas.
• bg.panel: #111113 - main panel and modal background.
• bg.panelElevated: #17171A - cards, selected rows, input shells.
• bg.panelHover: #1D1D22 - hover state for rows and controls.
• bg.input: #141418 - text inputs, code blocks, secret fields.
• border.subtle: #26262C - default panel borders.
• border.strong: #34343D - active borders and high-emphasis outlines.

Text

• text.primary: #F5F5F7 - primary labels and values.
• text.secondary: #B3B3BD - supporting metadata.
• text.tertiary: #7C7C88 - placeholders and low-emphasis copy.
• text.inverse: #0B0B0D - text on bright accents.

Accents

• accent.blue: #3B82F6 - login CTA, toggles, focus ring, trust signals.
• accent.blueHover: #4C8DFF - hover state for primary interactions.
• accent.purple: #8B5CF6 - secondary accent for selected count pills or light emphasis.
• accent.amber: #D97706 - local warnings or pending states.
• accent.red: #EF4444 - destructive actions.
• accent.green: #22C55E - success or enabled state when stronger signal is required.

Semantic Use

• Blue is the main action color. Keep it rare and meaningful.
• Purple can appear in subtle badges or selected-count chips, never as a second primary CTA.
• Red is reserved for delete, revoke, sign-out danger, and destructive confirmations.
• Avoid bright gradients as a dominant surface treatment.

3. Typography Rules

• Font stack: Inter, SF Pro Text, SF Pro Display, Segoe UI, system sans-serif.
• Use system-friendly text rendering. This is a desktop tool, not a display-heavy website.
• Chinese UI copy is allowed and should feel natural beside English identifiers like host, token, MCP.
• Keep tracking neutral. Avoid wide uppercase spacing except tiny overline labels.

Type Scale

• App title / page title: 30-34px, weight 700.
• Section title: 18-22px, weight 650-700.
• Card title / row title: 15-17px, weight 600.
• Body text: 13-14px, weight 400-500.
• Caption / metadata label: 11-12px, weight 500, uppercase allowed with modest tracking.
• Monospace values: SF Mono, JetBrains Mono, Menlo, monospace; 12-13px.

4. Component Stylings

App Shell

• Use a three-pane desktop layout for the main screen: left navigation, middle list, right detail pane.
• Pane separation should rely on subtle borders, not strong shadows.
• Sidebar should feel slightly darker than the center list pane.
• The detail pane can be the most open surface, with larger top padding and calmer spacing.

Login Card

• Centered card on a dark canvas.
• Width: compact, roughly 420-520px.
• Rounded corners: 24-28px.
• Include one lock/trust mark, one clear product title, one short support sentence, one primary Google login button.
• Login should feel calm and premium, never busy.

Buttons

• Primary button: dark app shell with blue fill, white text, medium radius.
• Secondary button: dark raised surface with subtle border.
• Destructive button: same structure as secondary, with red text or red-emphasis border only when needed.
• Button height should feel desktop-like, not mobile oversized.
• Avoid flashy gradients and oversized glows.

Inputs

• Inputs use dark filled surfaces, subtle inset feel, 12-14px radius.
• Border should be nearly invisible at rest and stronger on hover/focus.
• Placeholders should be quiet and low-contrast.
• Search and filter inputs should visually align and share the same height.

Lists and Rows

• Entry rows should be compact, crisp, and easy to scan.
• Selected row: slightly brighter dark card, subtle border, no heavy glow.
• Support a two-line rhythm: primary name and smaller type/folder metadata.
• Counts in the sidebar should use muted rounded chips.

Detail Pane

• Use strong top title hierarchy with restrained action buttons on the right.
• Metadata should be presented in structured blocks or columns, not loose paragraphs.
• Secret values should live inside dedicated protected field cards.
• Secret field rows should include icon, masked value, reveal action, and copy action.
• Sensitive content must look controlled and deliberate, not playful.

Modals

• Modal cards should feel like elevated control panels.
• MCP integration modal should support stacked integration rows with trailing toggles.
• Embedded JSON/config blocks should use a darker, code-oriented surface with monospace text.
• Large modal width is acceptable for configuration-heavy content.

Toggles

• Use blue enabled state by default.
• Toggle track should be compact and clean, avoiding iOS-like softness.
• Align toggles flush right in integration lists.

Badges and Status Pills

• Use small rounded pills for folder counts, archived state, or recent-delete state.
• Prefer muted purple, gray, or amber fills over saturated color blocks.

5. Layout Principles

• Use an 8px spacing system.
• Typical paddings:
• Sidebars: 16-20px.
• List and toolbar: 12-18px.
• Detail pane: 24-32px.
• Modals: 20-28px.
• Favor even vertical rhythm over decorative separators.
• Keep left edges aligned aggressively across sections.
• Avoid oversized hero spacing inside application surfaces.
• The main app should feel dense enough for productivity but never cramped.

6. Depth & Elevation

• Most separation should come from tone shifts and borders.
• Base panels: no shadow or extremely soft shadow.
• Elevated cards and modals: subtle shadow only, with low blur and low opacity.
• Do not use neon bloom, oversized backdrop blur, or glassmorphism.
• Focus states should use border color and a faint blue outer ring.

7. Do's and Don'ts

Do

• Keep the UI dark, crisp, and desktop-native.
• Preserve strong information hierarchy in the detail pane.
• Make security-sensitive actions feel explicit and carefully gated.
• Use compact controls and disciplined spacing.
• Let alignment and typography carry most of the visual quality.
• Keep MCP integration screens structured like settings panels.

Don't

• Do not turn the app into a landing page aesthetic.
• Do not use giant gradients, colorful illustrations, or soft SaaS cards.
• Do not over-round every surface.
• Do not mix many accent colors in one screen.
• Do not make secret fields look like casual form inputs.
• Do not use bright white backgrounds in the desktop app.

8. Responsive Behavior

• Primary target is desktop widths from 1280px upward.
• The three-pane shell should remain stable on desktop.
• At narrower widths, collapse from three panes to two panes before using stacked mobile behavior.
• The MCP modal can reduce width but should keep readable row spacing and code block legibility.
• Buttons and toggles should remain mouse-first, with minimum 32px touch-friendly height where practical.

9. Screen-Specific Guidance

Login Screen

• Centered trust card.
• One focal icon or emblem above the title.
• Keep copy short.
• The Google login button should be the visual anchor.

Main Secrets Screen

• Left sidebar: user card, folder navigation, utility actions near the bottom.
• Middle pane: search, type filter, result list.
• Right pane: selected entry title, metadata grid, secret cards, edit actions.
• The selected item should be immediately obvious but understated.

MCP Integration Screen

• Treat as a settings modal.
• Integration rows should read like desktop preferences, not marketing feature cards.
• JSON config block should feel developer-native and copy-friendly.

10. Agent Prompt Guide

• Keywords: dark desktop utility, Raycast-inspired, Linear-density, secure control panel, developer tool, restrained premium, MCP settings modal.
• When generating screens, preserve: dark surfaces, subtle borders, compact controls, right-aligned actions, clean typography, muted status pills.
• If unsure, bias toward less decoration and tighter structure.

11. Quick Summary for Agents

Build Secrets like a polished desktop utility: mostly Raycast in atmosphere, a little Linear in density, with dark layered panels, precise typography, subtle borders, blue-only primary actions, and security-sensitive detail cards that feel calm, serious, and highly usable.