Improve desktop first-run UX and empty-state discoverability

[Fullstop000]

Summary

Design critique of the current Chorus desktop shell found a strong, distinctive visual system, but the first-run/empty experience does not yet guide users toward the core workflow of creating agents, sending the first message, and turning work into tasks.

Scope note: mobile/responsive behavior is intentionally out of scope for this issue. Treat this as a desktop web refinement/onboarding pass.

Evidence inspected

Ran the app locally at http://localhost:5173 against a temporary clean data directory because the default ~/.chorus database uses an old identity schema.

Screens reviewed locally:

• Desktop empty channel: #all chat, no messages
• Desktop Tasks tab
• Desktop Create Agent modal

No browser console errors were observed during inspection.

Anti-pattern verdict

The interface does not look like generic 2024-2025 AI-generated SaaS. It avoids the usual tells: no gradient text, glowing dark dashboard, rounded glass cards, hero metric grid, or decorative blobs.

The design language is clear and memorable: sharp zero-radius surfaces, cream paper tones, mono labels, sparse industrial structure, and a Slack-like operator console layout.

Caveats:

• Sidebar.css includes a menu box-shadow, contrary to docs/DESIGN.md (No box-shadow, anywhere).
• The modal backdrop blur is visually pleasant but slightly softer/glassier than the rest of the flat industrial system.

Priority problems

1. First-run empty states do not guide action

The default chat says: No messages yet. Be the first to say something! But a new user likely needs to understand how to create agents, message #all, and use tasks.

The Agents section is empty except for a tiny + control.

Why this matters: the app looks like a strong shell, but not like an onboarding path. Users must infer the core workflow.

Suggested fix:

• Add a stronger empty-state panel in #all with explicit next actions, e.g.:
  • Create your first agent
  • Send a message to #all
  • Turn this message into a task
• Keep the industrial/mono style, but use grouping, border weight, and hierarchy to create a clear focal point.
• In the empty Agents section, show an inline Create agent row, not only an icon.

2. Important controls are too cryptic

Several controls are icon-only or symbolic:

• Channel +
• Team/member icon next to Channels
• Agent +
• Member count button
• SYS badge
• Footer settings button

Some icon buttons rely on title rather than visible copy or aria-label.

Why this matters: the aesthetic is coherent, but new users have to guess too much.

Suggested fix:

• Add aria-label everywhere an icon-only button appears.
• Use visible labels in empty/first-run contexts, then collapse to icon-only once the section has content.
• Explain SYS with accessible help text/tooltip or less cryptic copy.

3. Empty desktop screens are too flat

The desktop channel view has strong chrome but a very quiet center. The eye lands on #all, then a huge blank canvas. The primary path is present but under-directed.

Suggested fix:

• Give the empty center a designed focal object: compact instructions, suggested first prompt, and a Create agent CTA.
• Preserve the monochrome industrial language; rely on scale, grouping, and border contrast rather than color/glow.

4. Tasks board feels unfinished when empty

The Tasks tab renders four thin columns across the top and a large unused plane. Only to do has an input; the other columns are just counters.

Suggested fix:

• Make each lane read as a real column/drop zone, even when empty.
• Explain whether tasks are created manually, from chat via Also create as a task, or by agents.
• Visually connect the chat checkbox with the Tasks board behavior.

5. Design-system consistency cleanup

The current design depends on restraint. Small deviations dilute the signature.

Suggested fix:

• Replace shadows with border weight, nested borders, or flat contrast.
• Reconsider/reduce modal blur if it conflicts with the no-glass, no-elevation direction in docs/DESIGN.md.

Acceptance criteria

• Empty #all state provides clear first-run guidance and at least one obvious next action.
• Empty Agents section makes agent creation discoverable without relying only on an icon.
• Icon-only controls have accessible labels.
• Tasks empty board explains or implies how tasks enter/move through the board.
• The chat composer and Also create as a task affordance are visually/verbally connected to the Tasks board.
• No new shadows, gradients, rounded corners, or glass-style treatments are introduced outside the documented design language.

Notes

The core visual direction is working. This should be treated as a desktop first-run refinement, not a redesign.

[Fullstop000]

Added marked desktop screenshots for the scoped first-run UX work. Mobile/responsive behavior is intentionally out of scope for this issue.

1. Empty #all channel

Markers:

1. Empty state says there are no messages, but does not explain the first useful workflow.
2. Empty Agents section relies on a tiny + as the only create-agent cue.
3. Icon-only controls need visible first-run labels or accessible help.
4. Composer and Also create as a task should connect conceptually to the Tasks board.

2. Tasks board

Markers:

1. Only to do has an action; it reads disconnected from chat task creation.
2. Other lanes collapse to counters rather than reading as drop zones or workflow stages.
3. The large empty plane should teach how tasks arrive and move, not feel unfinished.

3. Create Agent modal

Markers:

1. Section syntax is strong; preserve this visual language for first-run guidance.
2. Status unavailable needs an actionable next step, not only diagnostic copy.
3. Disabled create action is expected, but first-run flow should point back to required fields.
4. Keep the modal/backdrop treatment aligned with the flat/no-elevation design language.

Raw image source gist: https://gist.github.com/Fullstop000/e8249c59f7f2499cac46fc2fa7825766