puter/zopu-code
1
0
Fork 0
Code Issues 3 Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
52510d1107ee0a8c20a45fc23a60cf21b822af69
zopu-code/docs/DESIGN.md
-Puter 52510d1107 chore: establish signals feature baseline
2026-07-23 14:29:57 +05:30

30 KiB
Raw Blame History

Zopo Work OS — Product Design

Status: working interaction and interface specification
Audience: product design, frontend, product engineering, and agent experience teams
Scope: information architecture, screens, cards, interaction patterns, states, actions, and design principles
Excludes: backend implementation and low-level infrastructure details

1. Design objective

Design one calm, persistent interface in which users can supervise many active units of work across multiple organizations, products, projects, teams, and contexts without managing chat threads, model settings, or agent sessions.

The interface should make a complex autonomous system feel understandable and controllable.

The primary design challenge is not displaying everything the system knows. It is showing the smallest amount of information required for the user to understand:

  1. What matters.
  2. What is happening.
  3. What is blocked.
  4. What requires human action.
  5. What will happen next.
  6. Why the system believes what it believes.

The central interaction principle is:

The conversation is the command surface. The work unit is the persistent product object.

2. Experience principles

2.1 One continuous workspace

Do not organize the product around chat history, sessions, or thread lists.

The user should experience one persistent workspace with a composer that can operate globally or inside a selected work unit.

2.2 Work first, machinery second

The user should see outcomes, blockers, decisions, artifacts, and results.

Agent names, model choices, runtime state, and infrastructure details should remain hidden unless they help explain progress or debug a failure.

2.3 Progressive disclosure

Collapsed cards should be scannable. Expanded cards should become rich working surfaces. Deep evidence, raw events, and technical details should be available on demand.

2.4 Calm density

The product should support dense operational information without feeling like a traditional enterprise dashboard.

Use hierarchy, spacing, typography, and grouping rather than excessive borders, colors, or permanent panels.

2.5 Human attention is a scarce resource

The interface should centralize requests for human involvement. Users should not search through cards to discover approvals, blockers, or unanswered questions.

2.6 Context must always be visible

The user should always know:

  • Which organization they are viewing.
  • Which project or portfolio scope is active.
  • Whether the composer is global or work-specific.
  • Which work unit is selected.
  • Whether an action affects external or production systems.

2.7 Provenance should be nearby

Important claims, decisions, and recommendations should have accessible source indicators. Evidence should be one interaction away, not buried in a separate audit application.

3. Product language

Use consistent language across the interface.

Organization

A company, client, or hard context boundary.

Project

A product, application, repository-backed system, or durable operating context.

Goal

A measurable business or product objective.

Signal

A new piece of information that may matter.

Candidate

A proposed unit of work awaiting confirmation.

Work unit

A persistent outcome the system is responsible for progressing.

Run

One execution attempt inside a work unit.

Artifact

A produced or collected output such as a pull request, preview, report, design, or document.

Attention item

A decision, approval, question, blocker, review, or risk that requires human action.

Avoid exposing terms such as:

  • Agent thread.
  • Model context window.
  • Harness session.
  • VM.
  • Sandbox lifecycle.
  • Actor wake state.

These may appear only in technical details or debugging views.

4. Global information architecture

The primary desktop layout uses three regions.

┌─────────────────────────────────────────────────────────────────────┐
│ Header                                                              │
├───────────────┬───────────────────────────────────┬─────────────────┤
│ Work index    │ Primary workspace                 │ Context panel   │
│               │                                   │                 │
│               │ Cards / expanded work / chat      │ Evidence,       │
│               │                                   │ artifacts,      │
│               │                                   │ preview, tools  │
├───────────────┴───────────────────────────────────┴─────────────────┤
│ Persistent composer                                                 │
└─────────────────────────────────────────────────────────────────────┘

The layout should collapse gracefully on smaller screens.

4.1 Header

The header provides global orientation and lightweight controls.

Recommended contents:

  • Current organization switcher.
  • Current project or portfolio scope.
  • Search or command trigger.
  • Attention count.
  • Activity indicator.
  • User menu.

Avoid filling the header with model controls, agent selectors, or environment settings.

4.2 Left work index

The left region is not chat history.

It contains operational navigation such as:

  • Now.
  • Attention.
  • Discovery.
  • Active work.
  • Waiting.
  • Review.
  • Monitoring.
  • Recently completed.
  • Goals.
  • Projects.
  • Knowledge.
  • Activity.

The index should show compact counts and status indicators.

A project section may show:

  • Project name.
  • Health.
  • Number of active units.
  • Number requiring attention.
  • Current goal or release.

4.3 Primary workspace

The center is where work appears and expands.

It can show:

  • Portfolio overview.
  • Project overview.
  • Work-card feed.
  • Expanded work unit.
  • Global conversation moments.
  • Candidate review.
  • Attention workflow.
  • Results and learning.

4.4 Context panel

The right panel changes with the selected object.

Possible contents:

  • Evidence.
  • Sources.
  • Files.
  • Pull request.
  • Code changes.
  • Preview.
  • Test results.
  • Research.
  • Agent activity.
  • Decisions.
  • Dependencies.
  • Analytics.
  • Customer feedback.
  • Version history.

The panel should be hidden or collapsed when there is no relevant content.

4.5 Persistent composer

The composer remains available across the product.

It has two scopes:

Global workspace

or:

Working in: Fix Safari OAuth callback failures

The active scope should be visually obvious but not heavy.

The composer can accept:

  • Text.
  • Files.
  • Images.
  • Voice.
  • Links.
  • Source mentions.
  • Work-unit references.
  • Project references.
  • Commands through natural language.

The user should not have to select a model, agent, or thinking mode.

5. Primary screens

5.1 Command Center

The Command Center is the default high-level screen.

Purpose:

  • Give the user an immediate understanding of the portfolio.
  • Show what progressed autonomously.
  • Surface only meaningful changes and required actions.

Recommended sections:

Today

  • Highest-value active work.
  • Upcoming deadlines.
  • Work likely to become blocked.
  • Work recently unblocked.

Needs attention

  • Approvals.
  • Decisions.
  • Questions.
  • Reviews.
  • Risks.

Autonomous progress

  • Work advanced since the last visit.
  • Newly produced artifacts.
  • Verification completed.
  • Follow-up candidates.

Project health

For each relevant project:

  • Current goal.
  • Active work count.
  • Blocker count.
  • Recent result.
  • Risk or health signal.

Recent outcomes

  • Completed work.
  • Measured effects.
  • Newly captured learnings.

The Command Center should not become a wall of metrics. It should be an operational briefing.

5.2 Discovery Inbox

The Discovery Inbox contains signals and candidate work.

Each item should clearly distinguish raw information from proposed interpretation.

Views:

  • New signals.
  • Candidate work.
  • Possible duplicates.
  • Suggested links to existing work.
  • Low-confidence observations.

Primary actions:

  • Accept.
  • Edit.
  • Attach to existing work.
  • Merge.
  • Defer.
  • Dismiss.
  • Save as knowledge.
  • Ask why.

Batch actions may be useful for obvious duplicates or low-value signals, but important candidate creation should remain inspectable.

5.3 Project Overview

The Project Overview presents one product or application context.

Sections:

  • Project identity and health.
  • Current goals.
  • Active work.
  • Waiting and blocked work.
  • Recent releases or outcomes.
  • Connected sources.
  • Important context documents.
  • Team members and responsibility.
  • Autonomous activity.

The screen should answer:

  • What is this project trying to achieve?
  • What is moving?
  • What is blocked?
  • What changed recently?
  • What requires the user?

5.4 Work Unit Workspace

The Work Unit Workspace is the expanded state of a selected card.

Recommended structure:

Work header

  • Outcome-oriented title.
  • Organization and project.
  • Work type.
  • Phase.
  • Status.
  • Priority.
  • Owner or responsible party.
  • Last meaningful change.
  • Autonomy state.

Objective

  • Desired outcome.
  • Why now.
  • Linked goal.
  • Success criteria.
  • Scope and non-goals.

Current understanding

A concise system-generated summary separated into:

  • Known.
  • Inferred.
  • Uncertain.
  • Conflicting.

Plan

  • Current approach.
  • Steps.
  • Completed actions.
  • Next action.
  • Alternative path when relevant.

Blockers and dependencies

Each blocker shows:

  • What is blocked.
  • Why.
  • Who or what can resolve it.
  • Impact of waiting.
  • Requested human action.

Activity

A chronological but compressed history of:

  • User instructions.
  • Agent progress.
  • State changes.
  • Decisions.
  • Artifacts.
  • External actions.
  • Verification.

Artifacts

A collection of previews and links for:

  • Pull requests.
  • Commits.
  • Documents.
  • Screenshots.
  • Previews.
  • Test reports.
  • Designs.
  • Research.

Results

Visible after publication or completion:

  • Expected result.
  • Actual result.
  • Measurement window.
  • Evidence.
  • Unexpected effects.
  • Follow-up recommendation.

Contextual composer

The composer remains fixed at the bottom and clearly scoped to the selected work unit.

5.5 Attention Queue

The Attention Queue is the central human-in-the-loop surface.

Categories:

  • Decisions.
  • Approvals.
  • Questions.
  • Blockers.
  • Reviews.
  • Access requests.
  • Risk alerts.

Each item must answer:

  • What is needed?
  • Why is it needed?
  • What does the system recommend?
  • What evidence supports that recommendation?
  • What happens after approval?
  • What happens if the user does nothing?
  • How urgent is it?
  • Is the action reversible?

The queue should support quick review without forcing the user into the full work-unit workspace unless deeper context is needed.

5.6 Activity Stream

The Activity Stream shows what the autonomous system did.

It should include meaningful events such as:

  • Work discovered.
  • Work updated.
  • Run started.
  • Plan prepared.
  • Code changed.
  • Verification completed.
  • Artifact created.
  • Blocker detected.
  • Approval requested.
  • Work completed.
  • Result measured.

Avoid filling the stream with every low-level tool call.

Users can expand an event to inspect technical detail and provenance.

5.7 Results and Learning

This screen shows completed work as a feedback system rather than an archive.

Views:

  • Recently completed.
  • Monitoring.
  • Successful outcomes.
  • Unexpected regressions.
  • Follow-up opportunities.
  • Reusable learnings.

Each result should connect to the original objective and evidence.

5.8 Knowledge

The Knowledge screen exposes durable organization and project understanding.

Categories:

  • Product.
  • Business.
  • Customers.
  • Design.
  • Technical context.
  • Decisions.
  • Known constraints.
  • Reusable learnings.

The user should be able to see whether knowledge is:

  • Canonical.
  • Inferred.
  • Pending review.
  • Outdated.
  • Conflicting.

6. Card system

The card is a visual projection of a durable product object.

The same underlying work unit may appear as:

  • Compact card.
  • Expanded card.
  • Attention item.
  • Embedded conversation object.
  • Timeline event.
  • Result card.

Do not create separate task systems for each surface.

6.1 Signal card

Purpose: show newly detected information.

Collapsed content:

  • Source icon and source name.
  • Observation.
  • Project or organization.
  • Time.
  • Suggested relationship.
  • Confidence.

Actions:

  • Create work.
  • Attach to existing work.
  • Save as knowledge.
  • Dismiss.

Example:

Support · Acme Corp · 18m ago

Three users could not finish OAuth setup in Safari.

Possible match: Fix Safari callback failures
Confidence: High

[Attach] [Create separate work] [Dismiss]

6.2 Candidate card

Purpose: propose a durable work unit.

Collapsed content:

  • Proposed outcome.
  • Why it matters.
  • Project.
  • Linked goal.
  • Supporting source count.
  • Confidence.
  • Duplicate warning if relevant.

Actions:

  • Accept.
  • Edit.
  • Merge.
  • Defer.
  • Dismiss.
  • Ask why.

6.3 Active work card

Purpose: communicate current operational state.

The collapsed card should answer five questions:

  1. What is this?
  2. Why does it matter?
  3. What state is it in?
  4. Is anything blocked?
  5. What happens next?

Recommended anatomy:

[Type] [Organization / Project]                       [Status]

Fix Safari OAuth callback failures

Supports: Improve onboarding reliability

42% complete
Blocked: Need production Safari logs

Latest: Agent reproduced the issue · 18m ago
Next: Approve temporary logging deployment

3 artifacts · 5 sources · 2 runs

6.4 Waiting or blocked card

Waiting should be visually distinct without becoming alarmist.

Show:

  • Exact blocker.
  • Responsible party.
  • Time waiting.
  • Impact.
  • Next resolution action.

Example:

Waiting · Approval required

Fix Safari OAuth callback failures

Need: Approve 30-minute diagnostic logging
Impact: Investigation cannot continue without production evidence

[Review request]

6.5 Approval card

Purpose: let the user make a bounded decision safely.

Required content:

  • Exact action.
  • Why it is requested.
  • Recommendation.
  • Alternatives.
  • Risk.
  • Impact.
  • Evidence.
  • Reversibility.

Actions:

  • Approve.
  • Modify.
  • Reject.
  • Ask for more evidence.
  • Delegate.

Example:

Approval required

Merge PR #184

Why:
All automated verification passed. No blocking review issues remain.

Impact:
Changes OAuth callback validation. No database migration.

Evidence:
• 14 unit tests passed
• 6 browser tests passed
• Preview reviewed
• Automated code review attached

[Review changes] [Request changes] [Merge]

6.6 Review card

Purpose: evaluate an artifact or completed run.

Show:

  • What changed.
  • Acceptance criteria.
  • Verification summary.
  • Open concerns.
  • Preview or diff access.
  • Recommended decision.

Actions:

  • Accept.
  • Request changes.
  • Continue discussion.
  • Compare alternative.
  • Stop work.

6.7 Result card

Purpose: connect completed work to actual outcomes.

Show:

  • Intended outcome.
  • What shipped.
  • Expected impact.
  • Actual result.
  • Measurement period.
  • Unexpected effects.
  • Suggested follow-up.

Actions:

  • Accept result.
  • Continue monitoring.
  • Create follow-up.
  • Reopen.
  • Roll back where applicable.

6.8 Parent initiative card

Purpose: summarize a larger outcome composed of several child work units.

Show:

  • Initiative outcome.
  • Progress across children.
  • Critical path.
  • Current blockers.
  • Next milestone.
  • Number of active and completed children.

The parent card should not duplicate every child detail.

7. Card expansion behavior

Selecting a work card expands it in place in the primary workspace.

Recommended behavior:

  • Only one primary card is expanded at a time on desktop.
  • Other cards remain visible in the surrounding feed where practical.
  • The right panel updates to the selected section or artifact.
  • The composer scope changes to the selected work unit.
  • The selected card retains its position when collapsed.
  • Deep links can open directly to a work unit.

Expanded work should feel like entering a workspace, not navigating to a disconnected detail page.

On mobile, the expanded card may use a full-screen sheet or route while preserving the same conceptual model.

8. Global and contextual chat

8.1 Global mode

Global mode can create and coordinate work across the active organization or portfolio.

Example prompts:

  • What needs my attention today?
  • Create work for the repeated OAuth complaints.
  • Compare onboarding issues across my projects.
  • What is blocked for the release?
  • Move the pricing experiment behind the reliability work.
  • Summarize what progressed overnight.

Global responses may include embedded work cards and attention items.

8.2 Context mode

Context mode focuses on one work unit.

Example prompts:

  • Add Safari 17 to the acceptance criteria.
  • Explain the current hypothesis.
  • Show me the failing test.
  • Try a solution without changing the data model.
  • Prepare a smaller pull request.
  • Ask the customer for the missing information.

The composer header should show the active scope and provide an easy way to return to global mode.

8.3 Creating work from chat

When a user describes work, the system may:

  • Update an existing unit.
  • Create a candidate.
  • Create accepted work when intent is explicit and policy permits.
  • Ask a clarifying question.
  • Save the information as knowledge.

The interface should briefly communicate what happened:

Created candidate work: Improve OAuth diagnostics
Linked to: Restore OAuth reliability
Sources attached: 3

8.4 Mentioning work

Users should be able to reference:

  • A work unit.
  • A project.
  • A goal.
  • An artifact.
  • A source.
  • A person.

Mentions should insert structured references without requiring the user to copy IDs or links.

9. Status design

Use a small set of user-facing statuses.

Proposed

The system suggests work but has not started it.

Primary actions:

  • Accept.
  • Edit.
  • Merge.
  • Dismiss.

Clarifying

The outcome or requirements are incomplete.

Primary actions:

  • Answer question.
  • Add context.
  • Accept assumption.

Ready

The work is sufficiently defined and can begin.

Primary actions:

  • Start.
  • Review plan.
  • Change priority.

Active

The work is progressing.

Primary actions:

  • Inspect.
  • Steer.
  • Pause.
  • Add context.

Waiting

Progress depends on a person, dependency, approval, or external event.

Primary actions:

  • Resolve blocker.
  • Grant access.
  • Make decision.
  • Continue waiting.

Review

An artifact or result needs evaluation.

Primary actions:

  • Approve.
  • Request changes.
  • Continue discussion.

Monitoring

The work has shipped and the system is watching the outcome.

Primary actions:

  • Inspect result.
  • Extend monitoring.
  • Create follow-up.
  • Roll back.

Done

The work has reached a completed or intentionally stopped outcome.

Primary actions:

  • View result.
  • Reopen.
  • Create follow-up.
  • Archive.

Modifiers:

  • Blocked.
  • Approval required.
  • Waiting on user.
  • Waiting on dependency.
  • Running autonomously.
  • Scheduled.
  • At risk.

Use text and iconography in addition to color.

10. Activity design

Activity should show meaningful product events, not raw agent noise.

Primary activity language

Good:

  • Investigated authentication flow.
  • Identified likely state-validation bug.
  • Added regression tests.
  • Verification passed.
  • Pull request created.
  • Waiting for merge approval.

Avoid as primary UI:

  • Called grep.
  • Ran shell command.
  • Read 34 files.
  • Model generated 2,600 tokens.
  • Actor woke.

Low-level events should remain accessible in a technical details drawer.

Activity grouping

Group related events into meaningful sessions:

Implementation run · 24 minutes

• Inspected callback handler
• Added state validation
• Added regression tests
• 14 tests passed
• Created PR #184

11. Provenance design

Provenance has four levels.

Level 1: Source chips

Visible directly on cards:

  • Git.
  • Support.
  • Analytics.
  • Conversation.
  • System inference.
  • Human decision.

Level 2: Evidence panel

Shows sources supporting the current understanding or recommendation.

Level 3: Raw source

Allows the user to inspect the original message, issue, log, file, or event.

Level 4: Derivation detail

For high-impact claims, show:

  • Conclusion.
  • Evidence used.
  • Assumptions.
  • Confidence.
  • Conflicting evidence.
  • Last updated time.
  • Producing agent or process.

Use labels such as:

  • Verified.
  • Reported.
  • Inferred.
  • Assumed.
  • Conflicting.
  • Outdated.

Do not force the user to read derivation detail during normal operation.

12. Project and organization switching

Users may manage several organizations and projects.

Requirements:

  • The active organization must always be visible.
  • Switching organizations changes the full product scope.
  • The system must not show blended private context across organizations.
  • Portfolio views may aggregate counts and summaries with explicit labels.
  • The composer should show whether it is operating at portfolio, organization, project, or work-unit scope.

A hierarchy may look like:

Portfolio
├── Company A
│   ├── Product Alpha
│   └── Internal Platform
└── Client B
    └── Customer Portal

The interface should not require users to navigate a deep tree for every action. Search, recent projects, and scope-aware commands should provide fast movement.

13. Project onboarding design

Project onboarding should feel like preparing a capable working environment, not filling a long settings form.

13.1 Entry choices

  • Start from template.
  • Connect existing repository.
  • Import repository.
  • Create an empty project.

13.2 Template selection

Initial templates may include:

  • React.
  • Hono.
  • Express.
  • Full-stack web application.
  • API service.
  • Expo application.
  • Monorepo.

Each template card should explain:

  • What it includes.
  • What it is suited for.
  • Expected setup time.
  • Included verification.

13.3 Context setup

Guide the user through concise sections for:

  • Product.
  • Business.
  • Design.
  • Technical conventions.
  • Agent instructions.

The system may draft these from repository content or conversation. The user reviews and confirms.

Avoid forcing users to write complete documents before starting. Allow progressive completion while clearly marking missing context.

13.4 Readiness state

Show project setup progress:

  • Repository ready.
  • Dependencies prepared.
  • Context confirmed.
  • Verification passed.
  • Preview available.
  • Agent ready.

Infrastructure details should appear as plain operational language rather than raw logs.

14. Artifact experience

Artifacts should feel first-class within the work unit.

Supported artifact presentations:

  • Pull request summary.
  • Code diff.
  • Preview frame.
  • Test report.
  • Screenshot gallery.
  • Research document.
  • Design proposal.
  • Generated file.
  • Release note.

Each artifact should show:

  • Name.
  • Type.
  • Producer.
  • Time.
  • Related run.
  • Verification state.
  • Review state.
  • Source or destination.

Artifacts should open in the right panel or a focused viewer without breaking the work-unit context.

15. Human-in-the-loop actions

The product should support explicit actions rather than vague “continue” buttons.

Examples:

  • Approve plan.
  • Answer question.
  • Grant temporary access.
  • Review preview.
  • Review changes.
  • Request revision.
  • Approve branch push.
  • Approve pull request.
  • Approve merge.
  • Approve deployment.
  • Send message.
  • Pause autonomous work.
  • Cancel run.
  • Reopen work.

Every sensitive action should show scope and consequence.

Example:

Deploy preview

Project: Zopo Web
Branch: work/W-103/team-invitations
Environment: Temporary preview
External impact: None
Expected duration: 20 minutes

[Deploy preview]

16. Autonomy controls

Do not expose a complex agent-control panel by default.

Use simple autonomy states:

  • Manual.
  • Ask before actions.
  • Autonomous within policy.
  • Paused.

Project or organization policy can define defaults.

A work unit may show:

Autonomous within policy
No action required

or:

Paused after repeated verification failure
Review required

Advanced settings may expose policy detail, but everyday product use should remain simple.

17. Empty, loading, and failure states

17.1 Empty workspace

Do not show a blank dashboard.

Offer focused starting points:

  • Create project.
  • Connect repository.
  • Describe what you are working on.
  • Import existing issues.
  • Start from a template.

17.2 No active work

Show recent outcomes and suggested candidates rather than inventing busywork.

17.3 Run provisioning

Show simple language:

  • Preparing workspace.
  • Loading project context.
  • Starting implementation.

Avoid exposing infrastructure terms unless the process is delayed or fails.

17.4 Failure state

A failure should explain:

  • What failed.
  • Whether any work was preserved.
  • Whether retry is safe.
  • What the system recommends.
  • Whether human action is required.

Example:

Verification failed

The implementation is saved, but 2 browser tests are failing.
The system recommends another repair attempt.

[Review failures] [Retry repair] [Stop work]

17.5 Conflicting evidence

Show conflict explicitly rather than silently choosing one source.

Conflicting evidence

Support reports OAuth failures increased.
Analytics currently shows no significant change.

[Inspect sources] [Continue monitoring] [Start investigation]

18. Responsive behavior

Desktop

  • Three-column layout.
  • One expanded work unit.
  • Right contextual panel.
  • Persistent bottom composer.

Tablet

  • Collapsible left index.
  • Primary workspace.
  • Right panel as overlay or resizable drawer.

Mobile

  • Bottom navigation for Now, Attention, Work, and Projects.
  • Work cards in a vertical feed.
  • Expanded work as a full-screen route or sheet.
  • Composer fixed above navigation.
  • Context panel content displayed as tabs or sheets.

The mobile product should prioritize supervision, review, and approval rather than full code inspection.

19. Visual language

The visual direction should feel:

  • Calm.
  • Precise.
  • Premium.
  • Spacious.
  • Highly legible.
  • Modern without looking experimental.

Recommended characteristics:

  • Warm white or restrained dark backgrounds.
  • Soft neutral surfaces.
  • Thin separators.
  • Large rounded corners.
  • Subtle depth.
  • Strong typography hierarchy.
  • Restrained accent color.
  • Selective pastel states for work categories or phases.
  • Smooth expansion and scope transitions.

Avoid:

  • Dense enterprise dashboards.
  • Excessive gradients.
  • Permanent card borders around every item.
  • Bright status colors everywhere.
  • Model and agent control clutter.
  • Chat bubbles dominating the product.
  • Kanban as the default mental model.
  • Gamification.

The product should feel like a focused operating environment, not a collection of AI widgets.

20. Motion and transitions

Motion should reinforce state and continuity.

Use motion for:

  • A card expanding into a workspace.
  • Composer scope changing.
  • A candidate becoming accepted work.
  • An approval resolving and work resuming.
  • A new artifact appearing.
  • A blocker clearing.

Avoid decorative motion that distracts from operational information.

The system should feel alive because work changes meaningfully, not because the interface constantly animates.

21. Accessibility

Requirements:

  • Full keyboard navigation.
  • Clear focus states.
  • Screen-reader labels for status and actions.
  • Status not communicated by color alone.
  • Sufficient contrast in light and dark modes.
  • Reduced-motion support.
  • Predictable card expansion.
  • Action confirmations for destructive or external effects.
  • Human-readable timestamps and relative times with exact-time access.

22. MVP screen set

Build the first product around four primary screens:

  1. Active Work

    • Work-card feed.
    • Filters by project and status.
    • Expanded work unit.

  2. Discovery Inbox

    • Signals.
    • Candidate work.
    • Merge and attach actions.

  3. Attention Queue

    • Decisions.
    • Approvals.
    • Questions.
    • Reviews.

  4. Project Overview

    • Goals.
    • Active work.
    • Project context.
    • Artifacts and recent outcomes.

Persistent across all four:

  • Header.
  • Work index.
  • Global or contextual composer.
  • Realtime activity.

23. MVP card set

Initial card types:

  • Signal card.
  • Candidate card.
  • Active work card.
  • Waiting or blocker card.
  • Approval card.
  • Review card.
  • Result card.

Avoid designing a separate card type for every technical event. Use sections and modifiers inside the core card system.

24. Design success criteria

The product experience is successful when a user can answer these questions within seconds:

  • What should I focus on?
  • What progressed without me?
  • What is blocked?
  • What requires my decision?
  • Why is this work happening?
  • What evidence supports the current understanding?
  • What will happen next?
  • What changed in the project?
  • What result did completed work produce?

The product should also let the user start, steer, review, or stop work without understanding the internal agent or infrastructure architecture.

25. Design principles checklist

Before shipping a screen or feature, verify:

  • Is the primary object a work unit rather than a chat session?
  • Is organization and project scope clear?
  • Is the next human action obvious?
  • Are machine actions separated from human decisions?
  • Is provenance available?
  • Is uncertainty represented honestly?
  • Can detail be progressively disclosed?
  • Are technical internals hidden unless useful?
  • Does the composer preserve continuity?
  • Does the experience reduce coordination rather than create more?

26. Core experience statement

Zopo should feel like supervising a capable operating system rather than operating a collection of agents.

The user opens one workspace, sees the state of meaningful work, resolves the few things requiring judgment, and continues the conversation where needed. The system handles context, execution, progress tracking, and knowledge retention beneath a calm surface organized around persistent outcomes.