Skip to content

docs(design): Shop three chat surface designs on one page - #339

Merged
omesser merged 1 commit into
mainfrom
design/chat-surface-mockups
Sep 5, 2026
Merged

omesser merged 1 commit into
mainfrom
design/chat-surface-mockups

Conversation

@omesser

@omesser omesser commented Sep 4, 2026

Copy link
Copy Markdown
Owner

Why

#324 settled what the chat surface draws and how it behaves, and that design is approved
as workable. What it did not do is shop the alternatives. This page puts three visual
directions beside one another over the same conversation, so a direction can be picked on
sight rather than argued in prose.

It wires nothing. #324's design stays the reference until a direction is picked, and #17
stays open either way.

What changed

docs/design/chat-mockups.html — one self-contained page, vanilla JavaScript, no build
step. One conversation, one engine, three stylesheets scoped under a root class on the
stage: modern minimal, terminal log, pane of glass. The copy, the turn, the
timings, the sprite and the traces are #324's, unchanged, because a reviewer comparing
designs must not be comparing different words. Switching designs mid-stream keeps the turn
that is already streaming.

All three carry ADR-0010's four line kinds and no fifth, and all three carry the Character
Prompt tab — BMO's personality.txt frozen above, this Instance's own prompt editable and
empty below — whose ADR is #338. A backdrop switch puts every design over a plain desktop
and a bright, busy one, because a translucent panel proven over one wallpaper is not proven.

One line in docs/design/index.html and one cp in .github/workflows/pages.yml, plus
the class line ADR-0011 asks each index entry for.

Modern minimal, mid-stream, plain desktop:

Modern minimal

Terminal log, mid-stream, plain desktop:

Terminal log

Pane of glass, mid-stream, over the busy desktop:

Pane of glass

How to verify

open docs/design/chat-mockups.html. Drive all three designs across all three states, and
switch designs while the slow turn is streaming. Put the pane of glass over both backdrops.
A review link can name what to open: ?v=v-glass&bd=busy&tab=prompt.

— Claude Code, on @omesser's behalf.

One page, one conversation, three scoped stylesheets: modern minimal,
terminal log, pane of glass. Content, states and timings are #324's;
only the visual design differs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@omesser omesser mentioned this pull request Sep 4, 2026
@omesser

omesser commented Sep 4, 2026 •

Copy link
Copy Markdown
Owner Author

Decision - bots, capture this in an ADR:

  • V1 - implement modern minimal. Create the facilities for UX modularity
  • V2 - user gets a switcher to pick between the three proposed designs here. in the future we might add more optional designs.

@omesser

omesser commented Sep 5, 2026

Copy link
Copy Markdown
Owner Author

Decision recorded. ADR-0013 — docs/adr/0013-one-look-in-v1-switcher-in-v2.md,
in PR #347, with Look added to CONTEXT.md as the word for a swappable
visual design. Numbered 0013 because #338's branch claims 0012.

The Settings answer, since it is the part not yet seen: Settings keeps the
operating system's pixels and shares the words — colour and type never cross
into AppKit or GTK, and src-tauri/src/settings/form.rs, already the single
compiler-checked definition of the form's sections, labels and help text for
both toolkits, is what makes the two windows recognisably the same product.

The reasoning is on evidence rather than taste: the two settings_window.rs
files hold one hardcoded colour between them (#888888, twice, in Pango
markup) and take everything else from NSColor::secondaryLabelColor() and
NSFont::systemFontOfSize. Mirroring a palette into 2522 lines of native code
would create a drift surface where none exists and trade away dark mode and
contrast handling the toolkits give for free. Moving Settings to a webview is
refused by docs/SPEC.md and twice by #197. The reviewable bar the ADR sets: a
Look change that puts a hex colour or a pixel font size into either
settings_window.rs is wrong, and a Settings change that invents a label style
form.rs does not already use is wrong.

Also settled, each argued in the ADR: the v1 seam is one token file
(src/look.css) plus one root class and nothing else — not speculative
generality, because this page already runs three Looks off one engine by
swapping a class, which is the second and third implementation the seam needs;
the speech bubble is in scope, and Cues, the sprite, the tray and the
docs/design/ pages are out; the switcher is an application setting, not
per-Character (#119 closed that) and not per-Instance (#338 made it tempting,
but an Instance's identity is already its art).

This PR is now a v2 dependency. Terminal log and pane of glass exist only
on this branch, and a branch is not a review surface. Merging this as a Dated
page under ADR-0011 is what carries the two unshipped designs to the switcher.

Filed: #348 (the v2 switcher) and #349 (the Settings structure and wording
pass). v1's seam went to #17 as a comment rather than a new issue, since the
chat surface is what carries it.

One interpretation to confirm or correct: "the complete's chat bubble
(unless it's axes)" was read as the Completer's speech bubble, unless the
bubble is being axed
. Nothing suggests it is — #119 shipped and CONTEXT.md
records its timing rules — so the ADR records the bubble as in scope.

— Claude Code, on @omesser's behalf.

omesser added a commit that referenced this pull request Sep 5, 2026
Records @omesser's decision on #339. Settings is out of scope.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omesser

omesser commented Sep 5, 2026

Copy link
Copy Markdown
Owner Author

Correction to my comment above — the Settings paragraph is withdrawn.
Leaving the original in place so the record reads, but its one-sentence
Settings answer is no longer what the ADR says, at @omesser's direction.

ADR-0013 (PR #347) now decides nothing about the Settings window. It covers the
webview surfaces src/look.css can actually reach, and records Settings in one
line as deliberately not addressed and still undecided. Nothing in it argues
for or against a webview there. #349 is withdrawn and closed — its findings
were left on the issue for whoever picks Settings up.

Two other things in my earlier comment need re-attributing, now that the third
bullet is gone from the decision above. The surface scoping — speech bubble in;
sprite, Cues, tray and menus, and docs/design/ pages out — is the ADR's own
recommendation, marked as such and arguable
, not a decision handed down. In
particular the ADR no longer reads a parenthetical about the chat bubble, and
argues the bubble's inclusion on its own grounds instead: it is drawn by the
same webview from the same stylesheet as the chat surface. The alternative,
that the bubble keeps the palette #119 shipped, is written down beside it.

What the ADR records as decided is unchanged and is the two bullets above: one
Look in v1 with the seam that makes a Look swappable (src/look.css plus a
root class, no switcher machinery), and the switcher in v2 (#348), as an
application setting rather than per-Character or per-Instance.

This PR is still a v2 dependency. Terminal log and pane of glass exist only
on this branch, and a branch is not a review surface; merging this as a Dated
page under ADR-0011 is what carries them to the switcher.

Separately, and not this PR's business: #322 adds
docs/adr/0011-one-cancellable-slot-per-instance.md while
0011-generated-or-dated-site-pages.md is already on main — two ADR-0011s.
Left alone, flagged because it is yours to resolve.

— Claude Code, on @omesser's behalf.

omesser added a commit that referenced this pull request Sep 5, 2026
Records @omesser's decision on #339, narrowed to the chat surface at his
review of #347. Settings is out of scope.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omesser

omesser commented Sep 5, 2026

Copy link
Copy Markdown
Owner Author

Second correction to my "Decision recorded" comment above — the rename and a
scope fix.
@omesser reviewed #347 and asked for the word chat UI instead
of "Look", since "Look" could be read as the Character's art. He also asked
whether the scope was just the chat windows, and checking that turned up a real
error in what I recorded here.

Two claims in that comment are now wrong:

  • "The v1 seam is one token file (src/look.css) plus one root class" —
    right in shape, wrong in name and place. It is src/chat-ui.css plus
    class="chat-ui-minimal", and the class goes on the chat window's own
    document, which Chat surface #17 creates. I had it on src/index.html, which is the
    overlay — the only webview the app builds today, one per display, drawing
    sprites and speech bubbles. The chat surface is a second webview window
    (ADR-0010) that does not exist yet.
  • "The speech bubble is in scope" — now the opposite. The bubble is drawn
    in the overlay, above the sprite and beside the Character's art, from
    src/bubble.js; it is the Character's expression rather than the chat
    surface's chrome, and it keeps the palette Speech bubbles: dialogue over the sprite, and a thinking ellipsis while a turn is in flight #119 shipped. The argument I gave
    for including it — one window's two text surfaces disagreeing while sharing a
    stylesheet — was built on the belief that they share a window. They do not.

Unchanged: v1 implements modern minimal and creates the facilities for
modularity, v2 gives the user the switcher; the switcher is an application
setting; Cues, the sprite, the tray and the docs/design/ pages are out; the
Settings paragraph stays withdrawn per my correction above.

This PR is still v2's dependency, and for the same reason: terminal log and
pane of glass exist only on this branch, and merging it as a Dated page under
ADR-0011 is what carries them to the switcher. The three designs on
chat-mockups.html are also still the ADR's evidence that the seam is not
speculative — one skeleton, three designs, one class swap.

The ADR is docs/adr/0013-one-chat-ui-in-v1-switcher-in-v2.md; CONTEXT.md
gains Chat UI beside Chat surface. Issues: #355 (v1) and #348 (v2),
both updated.

— Claude Code, on @omesser's behalf.

@omesser
omesser merged commit fc5854c into main Sep 5, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant