feat(tui): add accessibility controls

Author: XiaoConstantine

README.md

@@ -87,6 +87,7 @@ Maestro is an AI code review and repository analysis assistant built on top of `
 - **Coding-Agent Workflow**: Natural-language prompts can inspect and edit the authoritative workspace you launched Maestro from while typed run/turn/tool events update progress; shell verification is explicit opt-in.
 - **Slash-Command Workflow**: `/ask`, `/review`, session, and subagent commands remain explicit specialist paths. `/review` invokes the specialized review pipeline through a dspy-go `agents.Agent` adapter, and coding sessions can delegate explicit PR-review requests through the same `review_pull_request` subagent tool.
 - **Unified Review Component**: inline `/review` results and standalone `RunReviewTUI` share file grouping, flattened selection, severity filters, list/detail rendering, and colorblind-safe severity shapes. Standalone posting confirmation remains available when its host supplies a posting callback; host-specific quit/status semantics stay at the wrapper boundary.
+- **Accessible Presentation**: `--high-contrast` or `MAESTRO_THEME=high-contrast` increases text and border contrast; `--reduce-motion` or `MAESTRO_REDUCE_MOTION=1` replaces animated status frames with a static label. Standard `NO_COLOR` disables color without enabling reduced motion.
 - **Responsive Agent Context**: the header identifies the authoritative workspace and active model. At 80+ columns, active run/review context can move into an adaptive rail; narrow panes retain a single chronological transcript. Ctrl+\\ toggles the rail without discarding its state.
 - **Adaptive Composer**: multiline prompts grow the editor to at most 30% of the terminal or 10 rows and show line/character counts while preserving a usable conversation region.
 - **Readable Responses**: assistant output renders Markdown, links, inline code, and fenced code blocks with Maestro's dark/coral syntax palette and width-aware reflow.

dev-notes/tui-accessibility.md

@@ -0,0 +1,16 @@
+# TUI accessibility controls
+
+Phase 6 adds explicit presentation controls without changing Maestro's dark/coral default identity.
+
+- `--high-contrast` and `MAESTRO_THEME=high-contrast` select stronger muted-text and border colors.
+- `--reduce-motion` and `MAESTRO_REDUCE_MOTION=1` replace the animated spinner with a static `[working]` label while retaining periodic elapsed-time updates.
+- `NO_COLOR` selects a color-free theme and leaves reduced motion independent. Structure, text emphasis, review severity shapes, and status labels remain available without hue.
+
+These settings are resolved when the canonical `MaestroModel` is constructed, so embedders receive the same environment behavior as the CLI. Tests cover color-free Markdown, environment theme selection, and stable reduced-motion frames.
+
+Run:
+
+```sh
+GOWORK=off go test ./terminal
+GOWORK=off go test -race ./terminal
+```

docs/coding_session.md

@@ -61,6 +61,8 @@ Inspect the failing tests, implement the smallest fix, and run the focused tests
 
 In interactive mode, the workspace is the current working directory you launched Maestro from. The responsive header labels that workspace and the active provider/model; coding tools and any file-tree view should all refer to the same root.
 
+For accessible presentation, use `--high-contrast` (or `MAESTRO_THEME=high-contrast`) for stronger text and border contrast, and `--reduce-motion` (or `MAESTRO_REDUCE_MOTION=1`) for static progress indicators. `NO_COLOR` independently removes colors while preserving labels, severity shapes, emphasis, and layout; it does not imply reduced motion.
+
 Prompt controls:
 
 - **Enter** runs the current task.

main.go

@@ -112,6 +112,8 @@ type config struct {
 	verbose                bool
 	verifyOnly             bool
 	allowCodingBash        bool
+	highContrast           bool
+	reduceMotion           bool
 	modelProvider          string
 	modelName              string
 	modelConfig            string // For additional model-specific configuration
@@ -219,6 +221,12 @@ Available slash commands in interactive mode:
   /ask <QUESTION>         - Ask a question about the repository
   /exit or /quit          - Exit the application`,
 		RunE: func(cmd *cobra.Command, args []string) error {
+			if cfg.highContrast {
+				_ = os.Setenv("MAESTRO_THEME", "high-contrast")
+			}
+			if cfg.reduceMotion {
+				_ = os.Setenv("MAESTRO_REDUCE_MOTION", "1")
+			}
 			if cmd.Flags().Changed("model") {
 				modelStr, _ := cmd.Flags().GetString("model")
 				provider, name, modelCfg := util.ParseModelString(modelStr)
@@ -253,6 +261,8 @@ Available slash commands in interactive mode:
 	rootCmd.PersistentFlags().BoolVar(&cfg.verbose, "verbose", false, "Enable verbose logging")
 	rootCmd.PersistentFlags().BoolVar(&cfg.verifyOnly, "verify-only", false, "Only verify token permissions")
 	rootCmd.PersistentFlags().BoolVar(&cfg.allowCodingBash, "allow-coding-bash", false, "Allow the coding agent to run unrestricted shell commands in the workspace")
+	rootCmd.PersistentFlags().BoolVar(&cfg.highContrast, "high-contrast", false, "Use the high-contrast TUI theme")
+	rootCmd.PersistentFlags().BoolVar(&cfg.reduceMotion, "reduce-motion", false, "Replace TUI animation with static status indicators")
 
 	rootCmd.PersistentFlags().BoolP("interactive", "i", false, "Run in interactive mode")
 
@@ -957,6 +967,8 @@ func runModernUI(cfg *config) error {
 		Verbose:       cfg.verbose,
 		IndexWorkers:  cfg.indexWorkers,
 		ReviewWorkers: cfg.reviewWorkers,
+		HighContrast:  cfg.highContrast,
+		ReduceMotion:  cfg.reduceMotion,
 	}
 
 	// Create service adapter for TUI

terminal/accessibility_test.go

@@ -0,0 +1,51 @@
+package terminal
+
+import (
+	"strings"
+	"testing"
+
+	"charm.land/lipgloss/v2"
+)
+
+func TestNoColorThemeAndMarkdownContainNoANSI(t *testing.T) {
+	t.Setenv("NO_COLOR", "1")
+	model := NewMaestroModel(&MaestroConfig{}, NewNoOpBackend("owner", "repo"))
+	if _, ok := model.theme.Accent.(lipgloss.NoColor); !ok {
+		t.Fatalf("accent color type = %T, want lipgloss.NoColor", model.theme.Accent)
+	}
+	message := Message{Role: "assistant", Content: "# Heading\n\n`code` and **bold**"}
+	rendered := model.renderAssistantMessage(&message, 60)
+	if strings.Contains(rendered, "\x1b[") {
+		t.Fatalf("NO_COLOR markdown contains ANSI escapes: %q", rendered)
+	}
+	if !strings.Contains(rendered, "**bold**") {
+		t.Fatalf("NO_COLOR markdown lost textual emphasis: %q", rendered)
+	}
+}
+
+func TestHighContrastThemeCanBeSelectedFromEnvironment(t *testing.T) {
+	t.Setenv("NO_COLOR", "")
+	t.Setenv("MAESTRO_THEME", "high-contrast")
+	model := NewMaestroModel(&MaestroConfig{}, NewNoOpBackend("owner", "repo"))
+	if model.theme.TextMuted == ClaudeCodeTheme().TextMuted || model.theme.Comment != model.theme.TextMuted {
+		t.Fatal("high-contrast theme retained a default low-contrast semantic color")
+	}
+	styles := maestroMarkdownStyles(model.theme)
+	if styles.CodeBlock.Chroma == nil || styles.CodeBlock.Chroma.Comment.Color == nil ||
+		*styles.CodeBlock.Chroma.Comment.Color != *markdownColor(model.theme.Comment) {
+		t.Fatal("Markdown code comments do not use the selected theme")
+	}
+}
+
+func TestReducedMotionUsesStaticProgressIndicator(t *testing.T) {
+	progress := NewProgressModel(ClaudeCodeTheme())
+	progress.SetReducedMotion(true)
+	progress.message = "Testing"
+	progress.state = ProgressWorking
+	first := progress.renderWorking()
+	progress.frame = 7
+	second := progress.renderWorking()
+	if first != second || !strings.Contains(first, "[working]") {
+		t.Fatalf("reduced-motion progress changed frames: %q != %q", first, second)
+	}
+}

terminal/backend.go

@@ -82,6 +82,8 @@ type MaestroConfig struct {
 	Verbose       bool
 	IndexWorkers  int
 	ReviewWorkers int
+	HighContrast  bool
+	ReduceMotion  bool
 }
 
 // NoOpBackend is a placeholder backend for testing.

terminal/commands.go

@@ -234,7 +234,7 @@ func (cp *CommandPaletteModel) renderCommandItem(cmd Command, selected bool) str
 
 	if selected {
 		style = lipgloss.NewStyle().
-			Background(lipgloss.Color("#3A3C55")).
+			Background(cp.theme.Surface).
 			Foreground(cp.theme.Accent).
 			Bold(true)
 	} else {

terminal/maestro_model.go

@@ -119,7 +119,7 @@ type SessionMutationMsg struct {
 
 // NewMaestroModel creates a new root TUI model.
 func NewMaestroModel(cfg *MaestroConfig, backend MaestroBackend) *MaestroModel {
-	theme := ClaudeCodeTheme()
+	theme := ResolveTheme(cfg != nil && cfg.HighContrast)
 	styles := theme.CreateStyles()
 
 	vp := viewport.New()
@@ -150,6 +150,11 @@ func NewMaestroModel(cfg *MaestroConfig, backend MaestroBackend) *MaestroModel {
 
 	// Create input model and hide optional capabilities the backend does not expose.
 	m.inputModel = NewInputModel(theme, m.handleCommand, m.handleQuestion)
+	reduceMotion := cfg != nil && cfg.ReduceMotion
+	if value := strings.TrimSpace(os.Getenv("MAESTRO_REDUCE_MOTION")); value != "" && value != "0" {
+		reduceMotion = true
+	}
+	m.progressModel.SetReducedMotion(reduceMotion)
 	if _, ok := backend.(modelSelectionProvider); !ok {
 		m.inputModel.removeCommand("model")
 		m.commandPalette.removeCommand("model")
@@ -1495,11 +1500,11 @@ func (m *MaestroModel) renderMessages() {
 		case "system":
 			// System messages: warning style
 			icon := lipgloss.NewStyle().
-				Foreground(lipgloss.Color("#FF6B6B")).
+				Foreground(m.theme.LogoPrimary).
 				Bold(true).
 				Render("⚠ ")
 			content := lipgloss.NewStyle().
-				Foreground(lipgloss.Color("#FF6B6B")).
+				Foreground(m.theme.LogoPrimary).
 				Render(msg.Content)
 			sb.WriteString(icon + content)
 		}

terminal/markdown.go

@@ -1,11 +1,14 @@
 package terminal
 
 import (
+	"fmt"
+	"image/color"
 	"strings"
 
 	"charm.land/glamour/v2"
 	glamouransi "charm.land/glamour/v2/ansi"
 	glamourstyles "charm.land/glamour/v2/styles"
+	"charm.land/lipgloss/v2"
 )
 
 func messageWidthBucket(width int) int {
@@ -23,7 +26,7 @@ func (m *MaestroModel) renderAssistantMessage(message *Message, width int) strin
 	}
 
 	message.renderCount++
-	styles := maestroMarkdownStyles()
+	styles := maestroMarkdownStyles(m.theme)
 	renderer, err := glamour.NewTermRenderer(
 		glamour.WithStyles(styles),
 		glamour.WithWordWrap(bucket),
@@ -44,12 +47,18 @@ func (m *MaestroModel) renderAssistantMessage(message *Message, width int) strin
 	return message.Rendered
 }
 
-func maestroMarkdownStyles() glamouransi.StyleConfig {
-	styles := glamourstyles.DarkStyleConfig
+func maestroMarkdownStyles(theme *Theme) glamouransi.StyleConfig {
 	zero := uint(0)
+	if _, noColor := theme.TextPrimary.(lipgloss.NoColor); noColor {
+		styles := glamourstyles.NoTTYStyleConfig
+		styles.Document.Margin = &zero
+		styles.CodeBlock.Margin = &zero
+		return styles
+	}
+	styles := glamourstyles.DarkStyleConfig
 	styles.Document.Margin = &zero
-	styles.Document.Color = stringPointer("#E8E9F3")
-	styles.Heading.Color = stringPointer("#E8985A")
+	styles.Document.Color = markdownColor(theme.TextPrimary)
+	styles.Heading.Color = markdownColor(theme.LogoPrimary)
 	for _, heading := range []*glamouransi.StyleBlock{
 		&styles.H1,
 		&styles.H2,
@@ -58,28 +67,30 @@ func maestroMarkdownStyles() glamouransi.StyleConfig {
 		&styles.H5,
 		&styles.H6,
 	} {
-		heading.Color = stringPointer("#E8985A")
+		heading.Color = markdownColor(theme.LogoPrimary)
 		heading.BackgroundColor = nil
 	}
-	styles.Link.Color = stringPointer("#00D9FF")
-	styles.LinkText.Color = stringPointer("#00D9FF")
-	styles.Code.Color = stringPointer("#D4D4E5")
-	styles.Code.BackgroundColor = stringPointer("#2B2D42")
+	styles.Link.Color = markdownColor(theme.Accent)
+	styles.LinkText.Color = markdownColor(theme.Accent)
+	styles.Code.Color = markdownColor(theme.Code)
+	styles.Code.BackgroundColor = markdownColor(theme.Surface)
 	styles.CodeBlock.Margin = &zero
-	styles.CodeBlock.Color = stringPointer("#D4D4E5")
+	styles.CodeBlock.Color = markdownColor(theme.Code)
 	if styles.CodeBlock.Chroma != nil {
 		chroma := *styles.CodeBlock.Chroma
 		styles.CodeBlock.Chroma = &chroma
-		styles.CodeBlock.Chroma.Text.Color = stringPointer("#D4D4E5")
-		styles.CodeBlock.Chroma.Comment.Color = stringPointer("#6B6B7E")
-		styles.CodeBlock.Chroma.Keyword.Color = stringPointer("#B185F7")
-		styles.CodeBlock.Chroma.KeywordReserved.Color = stringPointer("#B185F7")
-		styles.CodeBlock.Chroma.KeywordType.Color = stringPointer("#B185F7")
-		styles.CodeBlock.Chroma.LiteralString.Color = stringPointer("#7FE9DE")
+		styles.CodeBlock.Chroma.Text.Color = markdownColor(theme.Code)
+		styles.CodeBlock.Chroma.Comment.Color = markdownColor(theme.Comment)
+		styles.CodeBlock.Chroma.Keyword.Color = markdownColor(theme.Keyword)
+		styles.CodeBlock.Chroma.KeywordReserved.Color = markdownColor(theme.Keyword)
+		styles.CodeBlock.Chroma.KeywordType.Color = markdownColor(theme.Keyword)
+		styles.CodeBlock.Chroma.LiteralString.Color = markdownColor(theme.String)
 	}
 	return styles
 }
 
-func stringPointer(value string) *string {
-	return &value
+func markdownColor(value color.Color) *string {
+	r, g, b, _ := value.RGBA()
+	hex := fmt.Sprintf("#%02X%02X%02X", uint8(r>>8), uint8(g>>8), uint8(b>>8))
+	return &hex
 }

terminal/markdown_test.go

@@ -9,6 +9,9 @@ import (
 )
 
 func TestRenderAssistantMessageRendersMarkdown(t *testing.T) {
+	t.Setenv("NO_COLOR", "")
+	t.Setenv("MAESTRO_THEME", "")
+	t.Setenv("MAESTRO_REDUCE_MOTION", "")
 	model := NewMaestroModel(&MaestroConfig{}, NewNoOpBackend("owner", "repo"))
 	message := Message{Content: "# Result\n\nUse **care** and `go test`."}