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

```text
------------------------------------------------
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.