Skip to content

DESIGN.md

Latest commit

 

History

History
289 lines (251 loc) · 13.4 KB

DESIGN.md

File metadata and controls

289 lines (251 loc) · 13.4 KB
Raw

Design System — CodeScout

Product Context

  • What this is: A free, open-source logging & network inspection dashboard for Flutter apps
  • Who it's for: Flutter developers who need visibility into their app's logs, network calls, and errors
  • Space/industry: Developer tools / observability (peers: Sentry, Datadog, Flipper, Flutter DevTools)
  • Project type: Data-heavy web dashboard — dark-first, self-hosted
  • Mascot: Pim — a blue penguin detective with a magnifying glass. Appears in empty states, onboarding, error pages, and the Flutter SDK overlay. Pim gives CodeScout warmth and personality that most dev tools lack.

Aesthetic Direction

  • Direction: Industrial/Utilitarian with character — function-first, data-dense, but softened by Pim and thoughtful empty states
  • Decoration level: Intentional — Pim appears in "human" moments (empty states, errors, onboarding). Data-dense views (log viewer, timeline) are clean and type-driven with no decoration.
  • Mood: Professional but approachable. A developer tool that feels like it was built by someone who cares, not generated by a template. Darker and warmer than GitHub's dark theme.
  • Anti-patterns: No purple gradients, no 3-column feature grids with icons in circles, no generic hero sections, no "clean modern UI" vagueness.

Typography

  • Display/Hero: Plus Jakarta Sans 800 — bold, geometric, confident. Used for page titles ("Projects"), logo wordmark.
  • Body: Plus Jakarta Sans 400/500 — clean readability at 13-15px. Labels use 500 weight.
  • UI/Labels: Plus Jakarta Sans 600 — buttons, nav links, tab labels.
  • Data/Tables: JetBrains Mono 400 — log timestamps, session IDs, project IDs, request IDs. Must support font-variant-numeric: tabular-nums for aligned columns.
  • Code: JetBrains Mono 400 — stack traces, metadata JSON, request/response bodies, search query syntax.
  • Loading: Google Fonts CDN
    • Plus Jakarta Sans:wght@400;500;600;700;800
    • JetBrains Mono:wght@400;500;600
  • Scale:
    • xs: 11px — timestamps, meta labels, badge text
    • sm: 13px — body text, table cells, input text, nav links
    • base: 15px — card titles, primary body
    • lg: 18px — section headings
    • xl: 20px — page headings ("Projects")
    • 2xl: 24px — major headings
    • display: 28px+ — hero/marketing only (not used in dashboard)

Color

Approach

Restrained — one blue accent, dark neutrals, color is used sparingly and meaningfully. Log level badges are the one place color is bold (intentional risk — makes the log viewer scannable at a glance).

Surfaces (dark mode — primary)

Token Hex Usage
chinese-black #111214 Page background (base)
cs-container #0D0D0F Nav bar, elevated containers
cs-card #17181C Card backgrounds, modals
eerie-black #1B1C1D Elevated surfaces, hover states
cs-input #151619 Input field backgrounds (border #2B2B2E)

Borders

Token Hex Usage
cs-border #21262D Default borders (cards, inputs, dividers)
border-muted #30363D Stronger borders (hover states)
border-focus #078DEE Focus rings, active input borders

Text

Token Hex Usage
fnt-platinum #E7E7E8 Primary text (headings, card titles)
text-primary #F0F0F0 Input text, body content
cs-muted #8B949E Secondary text (descriptions, labels, nav links)
text-placeholder #444444 Input placeholders
arsenic #414143 Disabled text, very muted

Brand / Accent

Token Hex Usage
cs-primary #078DEE Primary actions, active tabs, links, focus borders
primary-crayola #2667FF Alternative blue (logo, gradients)
blue-cola #078DEE Tertiary blue accent
primary-hover #2563EB Button hover state
primary-active #1D4ED8 Button active/pressed state

Log Level Colors (bold badges — intentional risk)

These are saturated and punchy. They only appear on the level badge itself, not the entire log row. This makes the log viewer scannable at a glance — you can spot errors instantly.

Level Hex Background (15% opacity)
Fatal #FF4D6A rgba(255,77,106,0.15)
Error #F85149 rgba(248,81,73,0.15)
Warning #D29922 rgba(210,153,34,0.15)
Info #0084FF rgba(0,132,255,0.15)
Debug #3FB950 rgba(63,185,80,0.15)
Verbose #8B949E rgba(139,148,158,0.12)
System #A371F7 rgba(163,113,247,0.15)

Semantic

Token Hex Usage
Success #3FB950 Sync complete, connection established
Warning #D29922 Retry attempts, degraded state
Error #F85149 Connection lost, sync failed
Info #58A6FF Informational banners, tips

Light Mode

Strategy: invert surfaces (white base, light gray cards), reduce color saturation by 10-20%, keep the same accent blue. Dark mode is the primary experience; light mode is secondary.

Dark Token Light Override
chinese-black #FFFFFF
cs-card #F6F8FA
cs-border #D0D7DE
text-primary #1F2328
cs-muted #656D76
cs-primary #0069CC (slightly darker for contrast)

Spacing

  • Base unit: 4px
  • Density: Comfortable — generous padding on cards and sections, tighter in data-dense views (log rows)
  • Scale:
Token px Usage
2xs 2 Hairline gaps
xs 4 Inline spacing, icon gaps
sm 8 Input padding, button gaps, card internal gaps
gap 6 Label-to-input gap (specific to forms — from your login screen)
md 16 Card padding, section gaps
lg 24 Section spacing, toolbar padding
xl 32 Major section gaps
2xl 48 Page-level spacing
3xl 64 Hero/empty state spacing

Layout

  • Approach: Grid-disciplined — strict columns, predictable alignment
  • Grid: 3 columns on desktop (lg), 2 on tablet (md), 1 on mobile (sm) — for project cards
  • Max content width: 1280px (max-w-[1280px])
  • Page padding: 24px horizontal (px-6)
  • Nav height: 64px
  • Border radius:
Token px Usage
sm 4 Badges, small tags
md 8 Buttons, inputs, pagination squares
lg 12 Project cards, alert boxes
xl 16 Modals, major cards
2xl 20 Login card (from your screen — slightly more rounded)
full 9999 Pills, avatar circles, tab buttons

Components

Nav Bar

  • Background: cs-container (#0D0D0F) with bottom border cs-border
  • Height: 64px, max-width 1280px centered
  • Left: Pim logo + "CodeScout" wordmark (Plus Jakarta Sans 700)
  • Center/Right: Nav links ("GitHub" in cs-primary blue, others in cs-muted)
  • Far right: User avatar (circular, 36px, gradient fallback if no photo)

Cards (Project)

  • Background: cs-card (#17181C)
  • Border: 1px cs-border, hover → cs-muted/40% opacity
  • Border radius: lg (12px)
  • Padding: 20px
  • Content: Project name (white, 600 weight), Project ID (muted, mono), favorite star

Buttons

  • Primary: cs-primary bg, white text, 600 weight, md radius (8px), hover → #2563EB
  • Secondary: cs-card bg, border cs-border, muted text, hover → lighter border
  • Ghost: Transparent, muted text, hover → white text
  • Danger: error bg at 12% opacity, error text color

Inputs

  • Background: cs-input (#151619)
  • Border: 1px cs-input-border (#2B2B2E), focus → cs-primary
  • Border radius: md (8px)
  • Text: 13px, #F0F0F0
  • Placeholder: #444444
  • Login inputs have a subtle blue left border accent

Tabs (Filter Pills)

  • Active: cs-primary bg, white text, md radius
  • Inactive: transparent, cs-muted text, border cs-border, hover → white text

Pagination

  • Square buttons: 32x32px, md radius (8px)
  • Active page: cs-primary bg, white text
  • Inactive: cs-card bg, border cs-border, muted text
  • Disabled: 50% opacity, cursor-not-allowed
  • Ellipsis: ··· in muted text

Log Level Badges

  • Pill shape (full radius)
  • 11px, uppercase, 700 weight, letter-spacing 0.04em
  • Colored text on 15% opacity background of the same color (see Log Level Colors above)
  • Clickable — click to filter by that level

Empty States

  • Centered, generous vertical padding (3xl / 64px+)
  • Pim illustration (SVG, ~150px height)
  • Title: 16px, 600 weight, white
  • Description: 13px, cs-muted
  • Primary action button below

Tabs (Network Detail)

  • Background: cs-card container
  • Tab bar: bottom border cs-border, tabs sit on it
  • Active tab: cs-primary text + 2px bottom border cs-primary
  • Inactive tab: cs-muted text, no bottom border, hover → white text
  • Tab padding: 12px horizontal, 8px vertical
  • Font: 13px, 600 weight
  • Content area: padding 20px, font-mono for headers/body data

Timeline (Session View)

  • Vertical line: 2px wide, cs-border color, left-aligned
  • Event nodes: 8px circles on the line
    • Regular log: filled circle in cs-border color
    • Network call: diamond shape (rotated square) in cs-primary
    • Error: filled circle in level-error
  • Event content: right of the line, 12px gap
    • Timestamp: font-mono, 11px, text-muted
    • Level badge: standard log level badge
    • Message: 13px, text-secondary
  • Spacing between events: md (16px)
  • Expandable: click event → inline expand (same pattern as log viewer)

Log Row (Log Viewer)

  • Grid layout: TIME (80px) | LEVEL (70px) | MESSAGE (1fr) | TAGS (auto)
  • Row padding: 8px vertical, 20px horizontal
  • Bottom border: 1px cs-border
  • Hover: eerie-black background
  • Cursor: pointer
  • Expanded state: border-left 2px in level color, additional padding, shows error/stack/metadata/links
  • Expansion transition: 150ms ease-out height animation

Breadcrumb

  • "← Back to Projects" or "← Back to Logs"
  • Font: 13px, cs-muted, hover → white
  • Arrow: left-pointing, same color as text
  • Position: top of content area, below nav, above page title

Live Indicator (SSE)

  • Pill shape (full radius)
  • Background: rgba(63,185,80,0.1) (success at 10%)
  • Text: semantic-success, 12px, 600 weight
  • Dot: 6px circle, semantic-success, pulsing animation (2s infinite)
  • States: "Live" (green pulse), "Connecting..." (gray pulse), "Reconnecting" (yellow pulse)

Alerts / Banners

  • Border radius: md (8px)
  • 1px border at 20% opacity of the semantic color
  • Background: 10% opacity of the semantic color
  • Text: semantic color, 13px, 500 weight

Motion

  • Approach: Minimal-functional — transitions aid comprehension, nothing decorative
  • Easing: ease-out for enter, ease-in for exit, ease-in-out for movement
  • Duration:
    • Micro: 50-100ms (hover color changes)
    • Short: 150ms (border transitions, opacity)
    • Medium: 250ms (HTMX swaps — default)
  • Rules:
    • No entrance animations on page load
    • No scroll-driven animations
    • HTMX swaps are instant (no transition)
    • SSE log rows: fade-in from top, 150ms
    • Pim: no animation (static illustration)

Pim Usage Guidelines

  • Where Pim appears: Empty states, error pages (5xx), first-run onboarding, loading states (optional), 404 page
  • Where Pim does NOT appear: Log viewer, data tables, nav bar icon only (no full illustration), settings
  • Variants: Pim with magnifying glass (default/logo), Pim with bag (empty state — "No projects yet!"), Pim in Flutter overlay (red floating button)
  • Tone: Helpful, curious, slightly mischievous. Never sad or frustrated — even error states should feel like "Pim is investigating the problem"

Keyboard Shortcuts (new — for log viewer)

  • j / k — navigate up/down in log list
  • / — focus search input
  • Esc — clear search / close modal
  • Enter — open selected log detail
  • d — toggle dark/light mode
  • Visual hint: show shortcut keys on hover (muted text in bottom-right of buttons)

Accessibility

  • All interactive elements: minimum 44px touch target
  • Focus visible: 2px cs-primary outline with 2px offset
  • Color contrast: all text meets WCAG AA on dark backgrounds
  • Keyboard navigable: all actions reachable via Tab + Enter
  • Screen reader: ARIA labels on icon-only buttons (star, pagination arrows, theme toggle)
  • Log level badges: never rely on color alone — always include text label

Decisions Log

Date Decision Rationale
2026-03-19 Initial design system created Codified from existing Figma screens + implemented code by /design-consultation
2026-03-19 Plus Jakarta Sans + JetBrains Mono PJS already in use; JBM adds code readability for log viewer
2026-03-19 Bold log level badges Saturated colors on badges only — makes log viewer scannable at a glance
2026-03-19 Pim in empty states only Personality without clutter — Pim in "human" moments, clean in data views
2026-03-19 Dark mode primary, light mode secondary Developer tool convention — dark is the expected experience
2026-03-19 4px spacing base, comfortable density Matches existing 6px gaps and 8px/16px padding in implemented screens
2026-07-30 UI tokens re-sampled from Figma final section (326:1081) cs-primary #078DEE, cs-card #17181C, cs-container #0D0D0F, inputs #151619/#2B2B2E — neutral dark palette replaces GitHub-dark values; log-level badge colors unchanged