Skip to main content

​
Sparki Web Platform UI/UX Specification

​
Executive Summary

The Sparki web platform delivers a developer-first, keyboard-centric, real-time collaborative interface that makes CI/CD management intuitive and delightful. This specification defines the complete UI/UX system for the browser-based dashboard, project management, pipeline orchestration, and real-time monitoring experiences. :::info design-philosophy Sparki’s Design Philosophy: “Keyboard-first, mouse-friendly, real-time, beautiful, and fast.” Every interface is designed for power users who live in terminals but want a beautiful dashboard. Every interaction prioritizes speed and clarity. Real-time updates are seamlessly integrated. Mobile-responsive without sacrificing desktop power-user features. :::

​
Part 1: Design System & Visual Language

​
Color Palette

Primary Colors: 
Sparki Brand Blue:    #2563EB (energetic, trustworthy)
Sparki Accent Orange: #F97316 (action, energy)
Success Green:        #10B981 (deployment success, health)
Warning Yellow:       #F59E0B (attention needed)
Error Red:            #EF4444 (failed builds, critical alerts)
Neutral Gray:         #6B7280 (secondary text, dividers)
Extended Palette: 
Success States:
├─ Light Success:     #D1FAE5 (success badge background)
├─ Success Text:      #065F46 (dark success text)
└─ Success Border:    #6EE7B7 (success element borders)

Error States:
├─ Light Error:       #FEE2E2 (error badge background)
├─ Error Text:        #7F1D1D (dark error text)
└─ Error Border:      #FCA5A5 (error element borders)

Neutral Background:
├─ White:             #FFFFFF (card backgrounds)
├─ Light Gray:        #F3F4F6 (section backgrounds)
├─ Medium Gray:       #E5E7EB (dividers, borders)
└─ Dark Gray:         #1F2937 (dark mode background)
Dark Mode Support:
  • All colors have dark mode variants
  • Default: Light mode (system preference override available)
  • Dark mode uses 15-20% lighter grays for eye comfort
  • High contrast mode available (WCAG AAA compliance)

​
Typography System

Font Stack: 
Headings (H1-H6): Inter, system-ui, sans-serif
Body Text: Inter, Segoe UI, sans-serif
Monospace/Code: "JetBrains Mono", "Fira Code", monospace
Terminal Output: "IBM Plex Mono", monospace (monospace, wider letterforms)
Scale: 
H1 (page titles):     32px, 700 weight, 40px line-height
H2 (section headers): 24px, 600 weight, 32px line-height
H3 (subsections):    18px, 600 weight, 24px line-height
H4 (card titles):    16px, 600 weight, 24px line-height
Body Large:          16px, 400 weight, 24px line-height
Body:                14px, 400 weight, 20px line-height
Body Small:          12px, 400 weight, 18px line-height
Label/Tag:           12px, 500 weight, 16px line-height
Caption:             11px, 400 weight, 16px line-height

​
Spacing System (8px base)

xs:    4px   (tight spacing within components)
sm:    8px   (default spacing)
md:   16px   (card padding, section margins)
lg:   24px   (major sections)
xl:   32px   (page-level spacing)
2xl:  48px   (top-level layout margins)
Component Padding: 
Button:           8px vertical, 16px horizontal (40px height)
Card:             16px padding
Modal:            24px padding
Sidebar:          16px vertical, 12px horizontal
Input/Select:     8px vertical, 12px horizontal (36px height)

​
Border Radius

Subtle (buttons, inputs):     4px
Standard (cards, modals):     8px
Large (prominent modals):    12px
Full (avatars, badges):     9999px

​
Shadow System

Subtle (hover states):        0 1px 2px rgba(0,0,0,0.05)
Card (default):              0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)
Elevated (dropdowns):        0 4px 6px rgba(0,0,0,0.1), 0 2px 4px rgba(0,0,0,0.06)
Modal (overlay):             0 20px 25px rgba(0,0,0,0.15), 0 10px 10px rgba(0,0,0,0.1)

​
Animation & Motion

Principles:
  • Under 200ms for micro-interactions (hover, focus, toggle)
  • 300-400ms for modal/drawer transitions
  • 500ms for page transitions
  • No animations on load (respect prefers-reduced-motion)
Easing Curves: 
Standard:      cubic-bezier(0.4, 0, 0.2, 1)
Ease-in:       cubic-bezier(0.4, 0, 1, 1)
Ease-out:      cubic-bezier(0, 0, 0.2, 1)
Bounce (spring): cubic-bezier(0.34, 1.56, 0.64, 1)
Loading States:
  • Skeleton screens for content loading (not spinners—feels faster)
  • Progress bars for long operations (under 2 seconds)
  • Pulse animation for real-time indicators (subtle, non-distracting)

​
Part 2: Core Pages & Navigation

Sidebar Navigation (always visible on desktop, collapsible)
├─ Sparki Logo + Org Selector
│
├─ MAIN NAVIGATION
│  ├─ Overview (dashboard, key metrics)
│  ├─ Projects (project list, search, filters)
│  ├─ Pipelines (pipeline editor, templates)
│  ├─ Builds (all builds, history, status)
│  ├─ Deployments (deployment history, approvals)
│  ├─ Analytics (metrics, trends, cost analysis)
│  └─ Settings (org, team, billing)
│
├─ WORKSPACE SWITCHER
│  └─ "Create workspace" option
│
└─ ACCOUNT MENU
   ├─ Profile
   ├─ Preferences
   ├─ API Keys
   ├─ Notifications
   └─ Sign Out
Responsive Behavior:
  • Desktop (1024px+): Sidebar always visible
  • Tablet (768-1023px): Sidebar collapses on scroll
  • Mobile (under 768px): Bottom tab navigation + hamburger menu

​
Page: Dashboard / Overview

Purpose: High-level summary of organization’s CI/CD health Layout: 
┌─ Sparki Dashboard ─────────────────────────────────────────────┐
│                                                                  │
│  [Org Selector] [Search Projects] [Alerts] [User Menu]        │
│                                                                  │
│  ┌─ Key Metrics (4-column grid) ──────────────────────────────┐
│  │                                                              │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  │ Build    │  │ Deployment
│  │  │ Success  │  │ Frequency│  │ System   │  │ Team     │   │
│  │  │ Rate     │  │ (per day)│  │ Health   │  │ Members  │   │
│  │  │ 98.2%    │  │ 4.2x     │  │ 99.95%   │  │ 8        │   │
│  │  │ ↑ 2.1%   │  │ ↑ 15%    │  │ ↓ 0.02%  │  │          │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Recent Builds (Last 24h) ─────────────────────────────────┐
│  │                                                              │
│  │  Status │ Project │ Branch │ Commit │ Duration │ Time      │
│  │  ✓      │ api    │ main   │ abc123 │ 2m 34s   │ 5 min ago │
│  │  ✓      │ web    │ main   │ def456 │ 1m 12s   │ 15 min ago│
│  │  ✗      │ api    │ dev    │ ghi789 │ 45s      │ 32 min ago│
│  │  ⏳ (waiting)                                               │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Deployments (Last 7 days) ────────────────────────────────┐
│  │                                                              │
│  │  Target │ Project │ Status │ Health │ Commits │ Triggered │
│  │  Prod   │ api    │ ✓      │ ✓      │ 3       │ 2h ago   │
│  │  Staging│ web    │ ✓      │ ⚠      │ 1       │ 30m ago  │
│  │  Prod   │ worker │ ✓      │ ✓      │ 5       │ 6h ago   │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Activity Feed ────────────────────────────────────────────┐
│  │ [User] merged PR #234 in api                     5 min ago │
│  │ [User] manually triggered build in web           12 min ago│
│  │ Deployment to prod completed                      2h ago   │
│  └──────────────────────────────────────────────────────────┘
│
└──────────────────────────────────────────────────────────────────┘
REQ-WEB-DASHBOARD-001: Key Metrics Cards
  • Build Success Rate: Percentage + trend indicator (color-coded)
  • Deployment Frequency: Builds/day + trend
  • System Health: Uptime % or error rate
  • Team Members: Count + “Manage” CTA
REQ-WEB-DASHBOARD-002: Recent Builds Table
  • Status indicator (✓ pass, ✗ fail, ⏳ running/queued, ⚠ warning)
  • Project name + link to project
  • Branch name (with git icon)
  • Commit short hash (clickable → git provider)
  • Duration in human-readable format (2m 34s)
  • Time since completion (5 min ago)
  • Clicking row expands to show: logs, artifacts, failures, deployment status
REQ-WEB-DASHBOARD-003: Real-Time Updates
  • Builds update in real-time (WebSocket from Sparki API)
  • Pulse animation when new build added to list
  • Counts update smoothly (98.2% → 98.3%)
  • No jarring page reloads

​
Page: Projects List & Project Details

Projects List: 
┌─ Projects ─────────────────────────────────────────────────────┐
│                                                                  │
│  [Search] [Filter by status] [Sort ▼] [+ New Project]         │
│                                                                  │
│  ┌─ Project Grid (3-column on desktop) ──────────────────────┐
│  │                                                              │
│  │  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│  │  │ api            │  │ web            │  │ worker         │
│  │  │ Main branch    │  │ Main branch    │  │ Main branch    │
│  │  │                │  │                │  │                │
│  │  │ Builds: 234    │  │ Builds: 156    │  │ Builds: 89     │
│  │  │ Success: 98.2% │  │ Success: 99.1% │  │ Success: 97.5% │
│  │  │                │  │                │  │                │
│  │  │ Last build:    │  │ Last build:    │  │ Last build:    │
│  │  │ ✓ 5 min ago    │  │ ⏳ in progress │  │ ✗ 2 hours ago  │
│  │  │                │  │                │  │                │
│  │  │ [• •• •]       │  │ [• •• •]       │  │ [• •• •]       │
│  │  └────────────────┘  └────────────────┘  └────────────────┘
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
└──────────────────────────────────────────────────────────────────┘
Project Details View: 
┌─ Project: api ─────────────────────────────────────────────────┐
│                                                                  │
│  [← Back] [Settings] [Transfer] [Delete]  Status: ✓ Healthy   │
│                                                                  │
│  ┌─ Tabs ─────────────────────────────────────────────────────┐
│  │ Overview | Pipelines | Builds | Deployments | Settings    │
│  └────────────────────────────────────────────────────────────┘
│
│  ┌─ Overview ─────────────────────────────────────────────────┐
│  │                                                              │
│  │  Repository: github.com/sparki/api                         │
│  │  Language: Go | Framework: Fiber                           │
│  │  Protected branches: main, staging                         │
│  │  Last sync: 2 minutes ago                                  │
│  │                                                              │
│  │  Build Configuration: Auto-detected ✓                      │
│  │  Pipeline: Default (using go.mod for dependencies)         │
│  │  Deployments: 3 targets (staging, prod, canary)            │
│  │                                                              │
│  │  ┌─ Recent Activity ──────────────────────────────────────┐
│  │  │ [User] pushed to main branch                    1h ago │
│  │  │ Build triggered automatically                   1h ago │
│  │  │ Deployment to staging completed                 1h ago │
│  │  └────────────────────────────────────────────────────────┘
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
└──────────────────────────────────────────────────────────────────┘

​
Page: Pipelines Editor

Purpose: Create, edit, visualize, and debug CI/CD pipelines Layout: 
┌─ Pipeline Editor: build-test-deploy ───────────────────────────┐
│                                                                  │
│  [Project: api] [← Back] [Save] [Delete] [Run] [Conditions ▼] │
│                                                                  │
│  ┌─ Pipeline Visualization (DAG) ─────────────────────────────┐
│  │                                                              │
│  │     ┌──────────┐                                            │
│  │     │  Checkout│                                            │
│  │     │  commit  │                                            │
│  │     └─────┬────┘                                            │
│  │           │                                                  │
│  │     ┌─────▼──────┐                                          │
│  │     │ Build (Go) │                                          │
│  │     │ 2m 30s     │                                          │
│  │     └─────┬──────┘                                          │
│  │           │                                                  │
│  │     ┌─────▼──────┬────────────┐                             │
│  │     │   Tests    │  Lint      │  (parallel)                 │
│  │     │   45s      │  30s       │                             │
│  │     └─────┬──────┴─────┬──────┘                             │
│  │           │            │                                     │
│  │     ┌─────▼────────────▼──────┐                             │
│  │     │  Publish Docker Image   │                             │
│  │     │  1m 15s                 │                             │
│  │     └─────┬───────────────────┘                             │
│  │           │                                                  │
│  │     ┌─────▼────────────┐                                    │
│  │     │ Deploy to Staging│                                    │
│  │     │ (with approval)  │                                    │
│  │     └──────────────────┘                                    │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Pipeline Configuration ───────────────────────────────────┐
│  │                                                              │
│  │ [YAML Editor]                                              │
│  │                                                              │
│  │ name: build-test-deploy                                    │
│  │ on:                                                        │
│  │   push:                                                    │
│  │     branches: [main, staging]                             │
│  │                                                              │
│  │ jobs:                                                      │
│  │   build:                                                   │
│  │     runs-on: ubuntu-latest                                │
│  │     steps:                                                 │
│  │       - uses: checkout@v3                                 │
│  │       - run: go build ./cmd/api                           │
│  │                                                              │
│  │ [✓] Syntax valid                                           │
│  │ [AI Suggestions] [Save as template]                        │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
└──────────────────────────────────────────────────────────────────┘
REQ-WEB-PIPELINE-001: Visual Pipeline DAG
  • Directed acyclic graph showing job dependencies
  • Color coding: ✓ successful, ✗ failed, ⏳ running, ⚠ manual approval
  • Hover shows: Job name, duration, status
  • Click to inspect logs, failures, artifacts
  • Drag to rearrange (saves as new template)
REQ-WEB-PIPELINE-002: YAML Editor with Intelligence
  • Syntax highlighting (keywords, strings, numbers)
  • Auto-complete for common fields (uses, runs-on, steps)
  • Real-time validation (syntax errors highlighted)
  • Diff view against last saved version
  • AI suggestions: “Did you mean to…?” for common mistakes
REQ-WEB-PIPELINE-003: One-Click Pipeline Running
  • [Run] button immediately queues pipeline
  • Shows live progress (which jobs are running, queued, completed)
  • Real-time log streaming for current job
  • Can manually trigger, skip steps, or re-run on failure

​
Page: Builds & Build Details

Builds List: 
┌─ All Builds ───────────────────────────────────────────────────┐
│                                                                  │
│  [Project filter] [Status filter] [Date range] [Sort ▼]        │
│                                                                  │
│  Status │ Project │ Branch │ Duration │ When     │ Trigger     │
│  ────────────────────────────────────────────────────────────  │
│  ✓ pass  │ api     │ main   │ 2m 34s   │ 5 min ago│ auto (push)│
│  ✓ pass  │ web     │ main   │ 1m 12s   │ 15 min ago│ auto (push)│
│  ✗ fail  │ api     │ dev    │ 45s      │ 32 min ago│ manual    │
│  ⏳ running │ worker  │ main  │ 1m 20s   │ in progress│ auto (push)│
│                                                                  │
│  [Load more] [Showing 1-50 of 1,234]                           │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
Build Details View: 
┌─ Build #1234: api / main / abc123 ─────────────────────────────┐
│                                                                  │
│  Status: ✓ PASSED (completed 5 min ago)                        │
│  Duration: 2m 34s | Started: 10:23 AM | Ended: 10:25 AM       │
│                                                                  │
│  ┌─ Tabs ─────────────────────────────────────────────────────┐
│  │ Summary | Logs | Artifacts | Deployment | Timeline         │
│  └────────────────────────────────────────────────────────────┘
│
│  ┌─ Summary ──────────────────────────────────────────────────┐
│  │                                                              │
│  │  Triggered by: [User] | Commit: abc123                     │
│  │  Branch: main | Repository: github.com/sparki/api          │
│  │                                                              │
│  │  ┌─ Pipeline Execution ──────────────────────────────────┐
│  │  │                                                        │
│  │  │  ✓ Checkout (30s)                                     │
│  │  │  ✓ Build (2m 10s) [details]                          │
│  │  │  ✓ Test (22s) [show failures]                        │
│  │  │  ✓ Lint (12s) [warnings: 2]                          │
│  │  │  ✓ Publish (10s) [docker hash: xxx...]               │
│  │  │  ✓ Deploy to staging (20s)                           │
│  │  │                                                        │
│  │  └────────────────────────────────────────────────────────┘
│  │                                                              │
│  │  [View Commit] [View PR] [Retry Build] [Deploy to Prod]    │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Logs ─────────────────────────────────────────────────────┐
│  │                                                              │
│  │  [Build ▼] $ go build ./cmd/api                            │
│  │            $ go build ./cmd/api                            │
│  │            go build ./cmd/api                              │
│  │            go: downloading github.com/valyala/fasthttp...  │
│  │            go: downloading github.com/gofiber/fiber/v2... │
│  │            ✓ Build complete                                │
│  │                                                              │
│  │  [Search logs] [Download logs]                             │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
└──────────────────────────────────────────────────────────────────┘
REQ-WEB-BUILD-001: Build Status Progression
  • Visual timeline showing each job with color-coded status
  • Click any job to expand and see detailed logs
  • Real-time log streaming while job running
  • Syntax highlighting for common log patterns (errors, warnings, success)
REQ-WEB-BUILD-002: Artifact Management
  • List all artifacts produced by this build (binaries, docker images, test reports)
  • Direct download links (with access control)
  • Size + build date metadata
  • Retention policy display (this artifact kept for X days)
REQ-WEB-BUILD-003: Build Insights
  • Trend: This build was 15% faster than average
  • Failures: Tests 3 times slower than normal (regression detection)
  • AI-powered suggestions: “This step is 5x slower than repo average, suspect slow query”

​
Page: Deployments & Deployment History

Deployments Dashboard: 
┌─ Deployments ──────────────────────────────────────────────────┐
│                                                                  │
│  ┌─ Active Deployments ───────────────────────────────────────┐
│  │                                                              │
│  │  Target: PROD | Project: api                               │
│  │  ├─ Current: v1.2.3 (deployed 6h ago)                      │
│  │  ├─ Pending:  v1.2.4 (in approval queue, 2 approvals)     │
│  │  ├─ Health: ✓ Green (99.98% uptime)                        │
│  │  ├─ Error rate: 0.02%                                      │
│  │  └─ [Rollback to v1.2.2] [View logs] [Deployment details]  │
│  │                                                              │
│  │  Target: STAGING | Project: api                            │
│  │  ├─ Current: v1.2.4-rc1 (deployed 45 min ago)             │
│  │  ├─ Health: ⚠ Yellow (HTTP 500 errors: 0.5%)              │
│  │  └─ [View error logs] [Investigate]                        │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Deployment History ──────────────────────────────────────┐
│  │                                                              │
│  │  Version │ Target  │ Status │ Health │ Duration │ When    │
│  │  v1.2.3  │ prod    │ ✓      │ ✓      │ 1m 30s   │ 6h ago  │
│  │  v1.2.2  │ staging │ ✓      │ ⚠      │ 45s      │ 1d ago  │
│  │  v1.2.1  │ prod    │ ✓      │ ✓      │ 1m 20s   │ 2d ago  │
│  │  v1.2.0  │ canary  │ ✗ rbk  │ -      │ 2m 10s   │ 3d ago  │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
└──────────────────────────────────────────────────────────────────┘
Deployment Details: 
┌─ Deployment: v1.2.3 → prod ────────────────────────────────────┐
│                                                                  │
│  Status: ✓ HEALTHY | Deployed: 6 hours ago                    │
│  Rollout: 100% complete | Health check: ✓ Green               │
│                                                                  │
│  ┌─ Deployment Timeline ──────────────────────────────────────┐
│  │                                                              │
│  │  10:00 ├─ Pre-deployment health check ✓                    │
│  │  10:01 ├─ Backup current version ✓                         │
│  │  10:02 ├─ Deploy new version (blue-green) ✓               │
│  │  10:03 ├─ Smoke tests ✓                                    │
│  │  10:04 ├─ Traffic: 10% → new version ✓                    │
│  │  10:07 ├─ Traffic: 50% → new version ✓                    │
│  │  10:15 ├─ Traffic: 100% → new version ✓                   │
│  │  10:20 ├─ Cleanup old version ✓                            │
│  │  10:21 └─ Deployment complete ✓                            │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Health Metrics ───────────────────────────────────────────┐
│  │                                                              │
│  │  Error rate:     0.02% (target: less than 0.1%)           │
│  │  Response time:  120ms p95 (target: 150ms)                │
│  │  CPU usage:      45% (healthy)                            │
│  │  Memory:         2.3GB / 4GB (healthy)                     │
│  │  Uptime:         99.98%                                    │
│  │                                                              │
│  │  [View full monitoring dashboard]                          │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  [Rollback] [Deployment logs] [Incident investigation]         │
│
└──────────────────────────────────────────────────────────────────┘
REQ-WEB-DEPLOY-001: Deployment Approval Workflow
  • Visual representation of approval gate
  • Show who can approve, who has approved, who still needs to approve
  • One-click approve/reject with optional comments
  • Automatic notifications to pending approvers
REQ-WEB-DEPLOY-002: Real-Time Health Monitoring
  • Live health metrics during deployment (error rate, response time, CPU)
  • Automated rollback trigger if metrics exceed thresholds
  • Visual health status (green/yellow/red) with context
  • Ability to manually rollback at any point
REQ-WEB-DEPLOY-003: Deployment Strategies Visualization
  • Blue-green: Show both environments, traffic routing diagram
  • Canary: Percentage distribution chart (10% → 50% → 100%)
  • Rolling: Progressive rollout with instance count visualization

​
Page: Team & Settings

Team Management: 
┌─ Team Management ──────────────────────────────────────────────┐
│                                                                  │
│  [Add member] [Roles & Permissions] [Invitations pending]      │
│                                                                  │
│  ┌─ Active Members ───────────────────────────────────────────┐
│  │                                                              │
│  │  Name          │ Email              │ Role    │ Status │   │
│  │  ───────────────────────────────────────────────────────   │
│  │  [A] Admin     │ admin@sparki.dev   │ Owner   │ Active │   │
│  │  [J] John      │ john@sparki.dev    │ Admin   │ Active │   │
│  │  [S] Sarah     │ sarah@sparki.dev   │ Dev     │ Active │   │
│  │  [M] Mike      │ mike@sparki.dev    │ Viewer  │ Active │   │
│  │                                                              │
│  │  [Action ▼] for each member:                               │
│  │  - Change role                                             │
│  │  - Revoke access                                           │
│  │  - View activity                                           │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
│  ┌─ Roles & Permissions ──────────────────────────────────────┐
│  │                                                              │
│  │  Owner: Full access, can delete organization              │
│  │  Admin: Can manage team, create projects, view billing     │
│  │  Developer: Can create/edit projects, trigger builds       │
│  │  Viewer: Read-only access to builds and deployments        │
│  │                                                              │
│  │  [Create custom role]                                      │
│  │                                                              │
│  └──────────────────────────────────────────────────────────┘
│
└──────────────────────────────────────────────────────────────────┘

​
Part 3: Interactive Patterns & Micro-Interactions

​
REQ-WEB-PATTERN-001: Search & Filter

Search Behavior:
  • Type to search (no button click required)
  • Debounce search input (300ms) to avoid excessive API calls
  • Show results dropdown below search box (max 8 results)
  • Results include: Project name, last build status, team
  • Keyboard navigation: Arrow keys to select, Enter to open
  • Esc key to close dropdown
Filter UI:
  • Horizontal pill-based filters above list
  • Multiple selection (e.g., “show passing AND manual triggers”)
  • Persisted in URL query parameters
  • “Clear all” button visible when filters active
  • Smooth animation when applying filters

​
REQ-WEB-PATTERN-002: Real-Time Status Updates

WebSocket Integration:
  • Connect on page load, disconnect on page unload
  • Automatic reconnection with exponential backoff (1s → 2s → 4s → 8s → 30s)
  • Show connection status indicator (dot: green = connected, red = disconnected)
  • Graceful fallback to polling (30s interval) if WebSocket fails
Update Animations:
  • Incoming new build: Pulse animation on list (1 pulse, 1 second)
  • Status change: Color transition (red → green) with brief hold
  • Metric update: Number tweens smoothly to new value (1 second)
  • No jarring jumps—everything feels intentional and smooth

​
REQ-WEB-PATTERN-003: Long-Running Operations

Build Execution UX:
  • Show estimated time based on historical data
  • Live progress: Which jobs are running, queued, done
  • Log streaming: Auto-scroll to bottom, option to pause
  • Ability to cancel job if still queued
  • Sound notification when build completes (optional, muted by default)
Deployment Execution UX:
  • Show deployment strategy with visual progress (blue-green, canary, rolling)
  • Real-time health checks (✓ or ✗)
  • Current traffic distribution for canary/rolling
  • Automatic rollback if thresholds exceeded (with manual override)

​
REQ-WEB-PATTERN-004: Error Handling & Recovery

Error Display:
  • Toast notifications for non-blocking errors (e.g., “Failed to load metrics”)
  • Modal dialogs for blocking errors (e.g., “Deploy failed, rollback initiated”)
  • Error messages are specific and actionable (not “Error occurred”)
  • Example: “Deployment failed: Health check timeout after 5 minutes. System rolled back to v1.2.2.”
Retry Logic:
  • Automatic retry for transient errors (network timeouts, 5xx errors)
  • Show retry attempt count and next retry time
  • Manual “Retry now” button
  • After 3 retries, escalate to user action (e.g., “Contact support”)

​
Part 4: Accessibility & Responsive Design

​
REQ-WEB-ACCESSIBILITY-001: WCAG 2.1 AA Compliance

Color Contrast:
  • All text meets 4.5:1 contrast ratio (large text: 3:1)
  • Color never sole indicator (use icons, text, patterns)
  • High contrast mode: 7:1+ ratio, thicker borders, larger text
Keyboard Navigation:
  • All interactive elements reachable via Tab key
  • Focus indicators visible and distinguishable
  • Tab order logical (left→right, top→bottom)
  • Escape key closes modals and dropdowns
Screen Reader Support:
  • All images have alt text (functional descriptions, not “image123”)
  • Form labels properly associated with inputs
  • Semantic HTML (using <button>, <nav>, <main>, etc.)
  • Live regions for real-time updates (aria-live=“polite”)
Motion & Animation:
  • Respects prefers-reduced-motion preference
  • No auto-playing video
  • No more than 3 flashes per second (seizure safety)

​
REQ-WEB-RESPONSIVE-001: Responsive Breakpoints

Desktop (1440px+):     Full featured, all panels visible
Large (1024-1439px):   Sidebar visible, full columns
Tablet (768-1023px):   Sidebar collapses on scroll, 2-column layout
Small (480-767px):     Single column, bottom navigation
Phone (under 480px):   Single column, optimized touch targets
Touch Optimization:
  • Minimum touch target: 44px × 44px
  • Spacing between targets: minimum 8px
  • Swipe gestures for navigation (left/right) on mobile
  • Long-press for context menus instead of right-click

​
Part 5: Component Library

​
Buttons

Variants: 
Primary:   Blue background, white text, hover: darker blue
Secondary: Light gray background, dark text, hover: darker gray
Danger:    Red background, white text, hover: darker red
Ghost:     No background, blue text, hover: light blue background
States:
  • Default: Normal appearance
  • Hover: Slight color shift + subtle shadow
  • Active/Pressed: Darker color + inset shadow
  • Disabled: Gray, 50% opacity, cursor not-allowed
  • Loading: Show spinner, disable click
Sizes:
  • Large (48px): Primary CTAs
  • Default (40px): Most buttons
  • Small (32px): Secondary actions, filters
  • Compact (28px): Inline actions

​
Forms & Inputs

Input States:
  • Default: Gray border, placeholder text
  • Focus: Blue border (2px), blue shadow ring
  • Error: Red border, error message below
  • Success: Green checkmark, light green background (optional)
  • Disabled: Gray background, no interaction
Validation:
  • Real-time validation (shows error immediately)
  • Error message under field in red text
  • Visual feedback (red border + icon)
  • Success state optional (not always necessary)

​
Cards

Structure: 
┌─ [Title] [Status indicator]     [Menu ▼]────────────────┐
│                                                            │
│  Subtitle or metadata text                               │
│                                                            │
│  Main content area                                       │
│                                                            │
│  Footer with actions or metadata                         │
│                                                            │
└────────────────────────────────────────────────────────────┘
Variants:
  • Elevated: Shadow, white background
  • Outlined: Border, light background
  • Flat: No shadow, light background
  • Interactive: Hover state with shadow/color shift

​
Modals & Dialogs

Structure: 
┌─ Title                                           [×]────┐
│                                                          │
│  Descriptive text about the action               │
│                                                          │
│  [Content/Form]                                 │
│                                                          │
│  ─────────────────────────────────────────────  │
│  [Cancel button]  [Primary action button]               │
│                                                          │
└──────────────────────────────────────────────────────────┘
Behavior:
  • Click outside or Esc key to cancel
  • Backdrop: Darkened, non-interactive
  • Focus trap: Tab cycles through form elements
  • No body scroll while modal open

​
Badges & Status Indicators

Status Colors:
  • ✓ Success (green): Passing build, healthy deployment
  • ✗ Error (red): Failed build, unhealthy deployment
  • ⚠ Warning (orange): Tests skipped, manual approval needed
  • ⏳ In Progress (blue): Build running, deployment in progress
  • ◯ Neutral (gray): Pending, not started, queued
Badge Variants:
  • Solid: Colored background + white text (high emphasis)
  • Outline: Colored border + colored text (medium emphasis)
  • Subtle: Light colored background + dark colored text (low emphasis)

​
Part 6: Performance & Technical Considerations

​
REQ-WEB-PERFORMANCE-001: Load Time Targets

  • Initial page load: under 2 seconds (first paint)
  • Interactive: under 3.5 seconds (time to interactive)
  • Dashboard data fetch: under 500ms
  • Build logs fetch: under 300ms (initial 100 lines)
  • Real-time WebSocket connection: under 1 second
Optimization Strategies:
  • Code splitting by route (lazy load page components)
  • Image optimization (WebP with fallbacks, responsive images)
  • Caching: Service worker for offline support
  • CDN: Static assets served from edge locations
  • Database: GraphQL queries optimized, no N+1 queries

​
REQ-WEB-PERFORMANCE-002: Data Management

State Management:
  • Use modern state library (Redux/Jotai/Zustand)
  • Normalized state shape (prevent duplication)
  • Selectors to derive computed state
  • Middleware for side effects (API calls, logging)
API Request Strategy:
  • GraphQL for flexible data fetching (only request needed fields)
  • Batch requests where possible (reduce waterfall)
  • Polling fallback: 30-second intervals if WebSocket unavailable
  • Request deduplication: Don’t re-request same data within 30 seconds

​
REQ-WEB-TECHNOLOGY-STACK

Frontend Framework: React 18+ (hooks, concurrent rendering) State Management: Jotai or Zustand (lightweight, no boilerplate) Routing: React Router v6 UI Component Library: Headless UI + custom Sparki design system Styling: Tailwind CSS + CSS modules for component scoping Real-time: Socket.io or native WebSocket for live updates Build Tool: Vite (fast dev server, optimized builds) Testing: Vitest + React Testing Library + Playwright E2E Monitoring: Sentry for error tracking, Hotjar for user behavior Type Safety: TypeScript strict mode

​
Part 7: Dark Mode & Theming

​
Color Mode Support

Default: System preference (respects OS dark mode setting) Toggle: User can override in settings Storage: Preference saved to localStorage Dark Mode Adjustments:
  • Reduce brightness on white (#FFFFFF → #F3F4F6)
  • Increase contrast on text
  • Use darker background (#1F2937 for main, #111827 for sections)
  • All colors have vetted dark mode variants
  • No pure black (use #1F2937, easier on eyes)

​
Conclusion

The Sparki web platform delivers a developer-first, real-time, delightful interface that makes complex CI/CD workflows feel intuitive and fast. Every design decision prioritizes:
  • Speed: Fast interactions, lazy loading, optimized rendering
  • Clarity: Clear information hierarchy, unambiguous status indicators
  • Power: Keyboard-centric, advanced features for power users
  • Accessibility: WCAG AA compliance, inclusive design
  • Beauty: Refined colors, smooth animations, delightful details
Document Statistics:
MetricValue
Pages Specified8+ (Dashboard, Projects, Pipelines, Builds, Deployments, Team, etc.)
Components Defined10+ (Buttons, Forms, Cards, Modals, Badges, etc.)
Interaction Patterns4+ (Search, Real-time, Long-running ops, Error handling)
Responsive Breakpoints5 (Phone, Small, Tablet, Large, Desktop)
WCAG Compliance2.1 AA
Accessibility Features8+ (Keyboard nav, Screen reader, Color contrast, Motion preferences)
Total Words~10,000
StatusCOMPLETE
Document History:
VersionDateAuthorChanges
1.02025-12-03Sparki DesignComplete web UI/UX specification