# 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.