Context
Hypha's interface today is mouse-led and menu-driven — you arrive and have to already know
where to click. #2478 (AI-assistance
layer architecture) surfaced a delivery-surface / UI-UX redesign thread: the human-machine
chat interface is where Hypha should lead, and both Joachim and Vlad agree a large UI/UX rethink
is needed. This ticket is the concrete, buildable spike for that thread — a working prototype the
team can see and try, not a doc.
The idea: replace the entry point with a talk-first experience. Like walking into a store and
being met by someone who greets you, offers the actions you're likely to want (more so if we
already know you), and otherwise lets you say what you need — the system then acts on the request
and the ongoing conversation rather than making you navigate to it. It is not a wholly original
concept, but doing it well, wired to Hypha's own signals / agreements / governance data, is where
the value is.
What this involves
On a hypha-web feature branch, reusing existing components wherever possible. This is
version 0 / version 1, not a throwaway — simplicity over a spotless solution, but on correct
foundations: the design definitions and abstractions must be right so it can be iterated on top of
(v0 → a good solution) without a rewrite. Three stacked regions:
- Persistent interaction bar (top) — always present, so the user feels a fluent, constant
conversation with the system. Rendered as a moving sound-wave to signal "this is something you
talk to".
- Next-actions strip (below the bar) — suggested next steps we think the user is likely to
want; adapts to what they've asked and to what we already know about them.
- Contextual canvas (main area) — a widget/component surface that reacts to the conversation.
Mostly contextual information (e.g. signals filtered to a task/objective, related
agreements, etc.), though widgets stay interactive like any other UI. Every widget must be
parameterizable so it can be filtered/adapted to what the user asked for.
Plus:
- Mode toggle (in or beside the bar) — switch between talk-first mode and the classic
mouse-led UI, for backward compatibility and users who prefer it.
- Interaction model: user opens a conversation → assistant presents the likely options → user
says what they need → the actions strip and the canvas widgets update to match. All real
interaction flows through talking to the system; clicking widgets is secondary.
Design intent / longevity (informs architecture decisions now, not scope now)
Build it so the reusable core could later be extracted as a library — a way to present an
existing UI conversationally, applicable to other pages / other apps, with guidance for a
consumer on how to adapt their components and what to wire up. Not built in this POC, but the
decisions now must not foreclose it: a clear seam between the generic conversational shell
(bar, actions strip, canvas orchestration, conversation → widget-state mapping) and the
Hypha-specific wiring (components, data, personas); widgets integrated via a defined
parameter/filter contract, not ad-hoc props; config-driven registration of widgets and
actions. Take the time to make the right design/architectural calls here.
Depends on / relates to
Approach / status
- Discovery + full spec are deliberately deferred to a dedicated, scoped session — not done
in the session that opened this ticket. That session covers: component inventory for reusable
parameterizable widgets; whether the current AI SDK setup supports a persistent streaming bar +
tool-driven canvas updates without a redesign; prior art for conversational-canvas UIs; the
interaction-model spec; and demo acceptance criteria.
- This issue exists to capture the objective and framing now so the work is on the board.
- Ticket workspace (full technical context):
progress/members/gerroza/tickets/<id>-ai-conversational-entrypoint-ux-poc/ in the context repo.
Open questions (for the scoped session)
Context
Hypha's interface today is mouse-led and menu-driven — you arrive and have to already know
where to click. #2478 (AI-assistance
layer architecture) surfaced a delivery-surface / UI-UX redesign thread: the human-machine
chat interface is where Hypha should lead, and both Joachim and Vlad agree a large UI/UX rethink
is needed. This ticket is the concrete, buildable spike for that thread — a working prototype the
team can see and try, not a doc.
The idea: replace the entry point with a talk-first experience. Like walking into a store and
being met by someone who greets you, offers the actions you're likely to want (more so if we
already know you), and otherwise lets you say what you need — the system then acts on the request
and the ongoing conversation rather than making you navigate to it. It is not a wholly original
concept, but doing it well, wired to Hypha's own signals / agreements / governance data, is where
the value is.
What this involves
On a
hypha-webfeature branch, reusing existing components wherever possible. This isversion 0 / version 1, not a throwaway — simplicity over a spotless solution, but on correct
foundations: the design definitions and abstractions must be right so it can be iterated on top of
(v0 → a good solution) without a rewrite. Three stacked regions:
conversation with the system. Rendered as a moving sound-wave to signal "this is something you
talk to".
want; adapts to what they've asked and to what we already know about them.
Mostly contextual information (e.g. signals filtered to a task/objective, related
agreements, etc.), though widgets stay interactive like any other UI. Every widget must be
parameterizable so it can be filtered/adapted to what the user asked for.
Plus:
mouse-led UI, for backward compatibility and users who prefer it.
says what they need → the actions strip and the canvas widgets update to match. All real
interaction flows through talking to the system; clicking widgets is secondary.
Design intent / longevity (informs architecture decisions now, not scope now)
Build it so the reusable core could later be extracted as a library — a way to present an
existing UI conversationally, applicable to other pages / other apps, with guidance for a
consumer on how to adapt their components and what to wire up. Not built in this POC, but the
decisions now must not foreclose it: a clear seam between the generic conversational shell
(bar, actions strip, canvas orchestration, conversation → widget-state mapping) and the
Hypha-specific wiring (components, data, personas); widgets integrated via a defined
parameter/filter contract, not ad-hoc props; config-driven registration of widgets and
actions. Take the time to make the right design/architectural calls here.
Depends on / relates to
UX-direction spike.
participant is reachable now).
hypha-webAI path (OpenRouter + Vercel AI SDK) and existing epic components(signals, agreements, treasury, governance, profile) as reuse targets.
Approach / status
in the session that opened this ticket. That session covers: component inventory for reusable
parameterizable widgets; whether the current AI SDK setup supports a persistent streaming bar +
tool-driven canvas updates without a redesign; prior art for conversational-canvas UIs; the
interaction-model spec; and demo acceptance criteria.
progress/members/gerroza/tickets/<id>-ai-conversational-entrypoint-ux-poc/in the context repo.Open questions (for the scoped session)
wiring, and what the widget contract looks like (so a future library extraction stays open).
which need a thin filter wrapper.
calls that mutate the canvas) without a redesign.
for the demo.
coherencethe right home for this, or does it need its own app-shell track.