Tint transcript turns in speaker colors for visual distinction (#241)

## Summary

Redesigned the visual rendering of conversation transcripts so that
entire speaker turns (both label and body text) are tinted in the
speaker's color, rather than just the label prefix. This makes "you:"
and "agent:" lines visually distinct at a glance, even on terminals with
limited color support.

## Key Changes

- **Theme colors**: Introduced a new `AGENT` color (`#14B8A6`, teal) to
replace the previous secondary accent (Cobolt 300) for agent labels. The
teal was chosen specifically to downgrade to ANSI cyan on 16-color
terminals, staying clearly distinct from the brand purple used for "you"
lines. Previously, both speakers used near-identical cobolt purples that
collapsed to the same hue after downsampling.

- **Rendering**: Modified `_labeled()` in `aai_cli/agent/render.py` to
apply the style to the entire line (label + body) rather than just the
label prefix. This ensures the whole turn reads as a cohesive colored
block.

- **Tests**: Added `test_human_whole_turn_is_tinted_in_speaker_color()`
to verify that both the label and body text are wrapped in the speaker's
color SGR codes, and that the two speakers render in contrasting hues.
Added `test_you_and_agent_stay_distinct_after_downsampling()` to ensure
the colors remain visually distinct even after downsampling to 16-color
ANSI palettes.

## Implementation Details

- The `AGENT` teal (`#14B8A6`) was chosen outside the cobolt purple
family on purpose: it downsamples to ANSI cyan, which is clearly
distinct from the purple/blue that "you" downsamples to, ensuring
readability across all terminal capabilities.
- The `aai.you` style retains the brand purple and remains reserved
(never reused for diarized speakers).
- Updated theme documentation to clarify that the entire transcript turn
is now tinted, not just the prefix.

https://claude.ai/code/session_01AFrwHX8EdECmkNsU8LqJNf

Co-authored-by: Claude <noreply@anthropic.com>

Author: alexkroman

aai_cli/agent/render.py

@@ -9,8 +9,13 @@
 
 
 def _labeled(label: str, body: str, *, style: str = "aai.label") -> Text:
-    """A line whose `label` prefix is accented in `style` and whose body is default."""
-    return Text.assemble((label, style), body)
+    """A transcript line tinted entirely in `style` — both the `label` prefix and the body.
+
+    Coloring the whole turn (not just the prefix) is what makes a "you:" line and an
+    "agent:" line read as different colors top to bottom; the two styles resolve to
+    contrasting hues (see ``theme.aai.you`` / ``theme.aai.agent``).
+    """
+    return Text(f"{label}{body}", style=style)
 
 
 class AgentRenderer(BaseRenderer):

aai_cli/ui/theme.py

@@ -17,10 +17,18 @@
 
 # Brand accent. Defined once so the whole CLI can be re-tinted here.
 BRAND = COBOLT_400
-# Secondary accent — the lighter Cobolt 300 used where a second hue is needed (agent
-# label, links), so it stays in the brand family yet reads distinct from BRAND.
+# Secondary accent — the lighter Cobolt 300 used where a second hue is needed (links),
+# so it stays in the brand family yet reads distinct from BRAND.
 ACCENT = COBOLT_300
 
+# The agent's voice in a live conversation. A cool teal chosen *outside* the cobolt
+# purple family on purpose: "you" keeps the brand purple, and the two were previously
+# both purples (Cobolt 400 vs 300) that collapsed to the same hue once a terminal
+# downsampled truecolor to its 16-color palette — so "you:" and "agent:" lines looked
+# identically colored. Teal downsamples to ANSI cyan, staying clearly distinct from the
+# purple/blue "you" on any terminal.
+AGENT = "#14B8A6"
+
 # Semantic error red, matching the design system's --color-error. Rich downsamples it
 # to plain red on terminals without truecolor.
 ERROR = "#F04438"
@@ -55,11 +63,13 @@
         "aai.brand": f"bold {BRAND}",
         "aai.heading": f"bold {BRAND}",
         "aai.label": BRAND,
-        # Conversation labels: the human keeps the brand accent (reserved — never reused
-        # for a diarized speaker, see SPEAKER_STYLES), the agent gets a distinct hue so
-        # "you:" and "agent:" are easy to tell apart at a glance.
+        # Conversation colors: a whole transcript turn is tinted in its speaker's hue
+        # (not just the "you:"/"agent:" prefix), so the two read as different colors top
+        # to bottom. The human keeps the brand purple (reserved — never reused for a
+        # diarized speaker, see SPEAKER_STYLES); the agent gets a contrasting teal so the
+        # two are unmistakable at a glance, even after downsampling (see AGENT).
         "aai.you": BRAND,
-        "aai.agent": ACCENT,
+        "aai.agent": AGENT,
         # Links/URLs in the lighter Cobolt secondary accent so a clickable target stands
         # out from prose without shouting (Vercel/Supabase use a cool accent for the same).
         "aai.url": ACCENT,

tests/test_agent_render.py

@@ -192,3 +192,26 @@ def test_human_you_label_is_colored():
     assert "you: " in out
     assert "what is the time" in out
     assert "\x1b[" in out
+
+
+def _truecolor_sgr(style_name: str) -> str:
+    """The foreground SGR a truecolor console emits for a named theme style."""
+    color = theme.make_console(color_system="truecolor").get_style(style_name).color
+    assert color is not None
+    t = color.get_truecolor()
+    return f"\x1b[38;2;{t.red};{t.green};{t.blue}m"
+
+
+def test_human_whole_turn_is_tinted_in_speaker_color():
+    # The whole line — label *and* body — is wrapped in the speaker's color, and the two
+    # speakers render in different colors, so a glance separates "you" from "agent".
+    r, buf = _human(color_system="truecolor")
+    r.user_final("hello")
+    r.agent_transcript("hi there", interrupted=False)
+    r.close()
+    out = buf.getvalue()
+    you_sgr, agent_sgr = _truecolor_sgr("aai.you"), _truecolor_sgr("aai.agent")
+    assert you_sgr != agent_sgr  # contrasting hues, not two shades of the same color
+    # The body text rides inside the colored span (it follows the SGR, before any reset).
+    assert f"{you_sgr}you: hello" in out
+    assert f"{agent_sgr}agent: hi there" in out

tests/test_theme.py

@@ -55,6 +55,20 @@ def test_you_color_reserved_outside_speaker_palette():
     assert you_color not in speaker_colors
 
 
+def test_you_and_agent_stay_distinct_after_downsampling():
+    # "you" and "agent" used to be two near-identical cobolt purples that downsampled to
+    # the *same* 16-color ANSI slot, so a transcript looked single-colored on a basic
+    # terminal. Assert they're different hues and stay different once downgraded.
+    from rich.color import ColorSystem
+
+    console = theme.make_console()
+    you = console.get_style("aai.you").color
+    agent = console.get_style("aai.agent").color
+    assert you is not None and agent is not None
+    assert you != agent
+    assert you.downgrade(ColorSystem.STANDARD) != agent.downgrade(ColorSystem.STANDARD)
+
+
 def test_output_console_is_themed_and_error_is_styled(monkeypatch):
     from aai_cli.core.errors import CLIError
     from aai_cli.ui import output, theme