buildpulse/docs/UI_SPEC.md

BuildPulse UI Specification

Design Goal

BuildPulse should feel like a calm cockpit, not an enterprise task manager. The user should quickly understand:

• What is active now
• What comes next
• What has been parked
• What happened recently
• How to export context for AI work

Main Navigation

v0.1 has four main views:

1. Feature Plan
2. Parking Lot
3. Pulse Log
4. Export

Optional small project summary area can appear in the header or dashboard area.

Global Layout

Suggested layout:

------------------------------------------------
BuildPulse Active Project: BuildPulse
------------------------------------------------
Feature Plan | Parking Lot | Pulse Log | Export
------------------------------------------------
Main content
------------------------------------------------

Mobile:

• Navigation collapses into bottom tabs or simple top tabs.
• Cards should stack vertically.
• Editing can happen in modal, drawer, or full-screen panel.

View 1: Feature Plan

Purpose: Show all feature cards grouped by current placement.

Columns:

• Now
• Next
• Later
• Done

Each card displays:

• Title
• Short description
• Priority
• Acceptance criteria count
• Recent pulse indicator, optional

Actions:

• Add feature
• Edit feature
• Delete feature
• Move feature to another column
• Add acceptance criteria
• Add pulse for this feature

Feature detail panel fields:

• Title
• Description
• Column
• Priority
• Status
• Acceptance criteria
• Scope notes

Empty state: No features yet. Add the first feature to define what you are building.

View 2: Parking Lot

Purpose: Capture distracting ideas safely.

Each item displays:

• Title
• Description
• Reason parked
• Possible future placement
• Risk level

Actions:

• Add parked idea
• Edit parked idea
• Delete parked idea
• Convert to feature
• Add pulse event: PARKED_IDEA

Empty state: No parked ideas yet. This is where useful distractions go so they do not hijack the current build.

View 3: Pulse Log

Purpose: Show what has happened over time.

Display:

• Chronological event list, newest first by default
• Filters:
  • Pulse type
  • Feature
  • Source/agent

Each pulse displays:

• Timestamp
• Pulse type
• Feature title, if linked
• Source/agent
• Message
• Confidence score
• Evidence refs

Actions:

• Add Pulse event
• Edit Pulse event, optional
• Delete Pulse event, optional for v0.1
• Filter by feature
• Filter by type

Add Pulse form fields:

• Pulse type
• Feature link, optional
• Source/agent
• Message
• Confidence score
• Evidence refs
• Trace ID, optional

Empty state: No Pulse events yet. Add an INTENT or DECISION to start the project log.

View 4: Export

Purpose: Create useful handoff context for AI coding agents.

Export options:

1. Full JSON export
2. Pulse JSONL export
3. Markdown package export

Markdown package includes:

• PROJECT_SUMMARY.md
• FEATURE_PLAN.md
• PARKING_LOT.md
• PULSE_LOG.md
• CLAUDE_CONTEXT.md

Actions:

• Copy Markdown to clipboard
• Download Markdown files, if practical
• Download JSON
• Download JSONL
• Import JSON

Import behavior:

• Validate schema
• Show preview/confirmation, if practical
• Handle invalid JSON gracefully
• Avoid data loss where possible

Project Summary Area

Project summary can be a compact editable panel.

Fields:

• Project name
• One-line pitch
• Description
• Current goal
• Notes

This should not become a full project management screen in v0.1.

Visual Style

Use:

• Simple typography
• Plenty of whitespace
• Calm colors
• Clear hierarchy
• Rounded cards if desired
• Low visual noise

Avoid:

• Dense tables everywhere
• Enterprise dashboards
• Too many badges
• Too many settings
• Gamification
• Overly flashy UI

UX Priority

Most important UX actions:

1. Add feature quickly.
2. Park idea quickly.
3. Add pulse quickly.
4. Export context quickly.

The app should support quick capture without forcing perfect data entry.