Theming & Accessibility
Relevant source files
The following files were used as context for generating this wiki page:
M31 Autonomous (M31A) utilizes a centralized design system and accessibility framework to provide a premium, terminal-native user experience. The system is built on a "Seven-phase workflow" and emphasizes clarity, professional aesthetics, and inclusive navigation. Theming is handled through a tiered token system, while accessibility is addressed through responsive layout adjustments, reduced motion modes, and keyboard-first navigation.
Sources: README.md:16-24, internal/ui/tui/theme/tokens.go:3-10
Theming System Architecture
The M31A design system follows a hierarchical structure where base color tokens are mapped to semantic styles. This architecture ensures that components express functional intent rather than hardcoded visual properties.
Tier 1: Base Design Tokens
Base tokens define the core color palette. The palette is inspired by professional, calm aesthetics, using desaturated tones to ensure comfort during long sessions. It utilizes a "soft white" hierarchy for text and "graphite" levels for backgrounds.
| Token Category | Description | Key Values |
|---|---|---|
| Backgrounds | Deep graphite hierarchy for depth. | BgBase (#0F1117), BgSurface (#161822) |
| Text | Soft white tones for high contrast without glare. | TextPrimary (#E2E4E9), TextMuted (#5C5F73) |
| Accents | Primary interactive and brand colors. | AccentPrimary (#4A6CF7) |
| Semantic | Functional colors for state communication. | Success (#5CB88A), Error (#E05C5C), Warning (#D4A053) |
Sources: internal/ui/tui/theme/tokens.go:12-70
Tier 2: Semantic Styles
The SemanticStyles library maps design tokens to specific UI components. This layer abstracts the visual implementation, allowing the design system to control the look of buttons, cards, and headers globally.
The design system enforces zero per-frame allocations for style creation by pre-computing these styles into a SemanticStyles struct.
Sources: internal/ui/tui/theme/tokens_semantic.go:5-25, internal/ui/tui/theme/tokens_semantic.go:210-250
Component Styling
Components such as the Implementation Plan use semantic coloring to communicate task priority and wave depth.
Task Wave Coloring
In the PlanModel, tasks are grouped into "Waves" (Foundation, Core Features, etc.), each receiving distinct semantic colors:
- Wave 1 (Foundation): Uses
Brandcolor. - Wave 2 (Core Features): Uses
Infocolor. - Subsequent Waves: Use
TextMuted.
Sources: internal/ui/tui/plan_model.go:265-280, internal/ui/tui/plan_model.go:312-320
Diagnostic Feedback
The system uses "Soft" variants of semantic colors for background tints in cards and panels, such as SuccessSoft or ErrorSoft, to provide contextual feedback without aggressive saturation.
Sources: internal/ui/tui/theme/tokens.go:65-85
Accessibility and Responsive Layout
M31A incorporates several accessibility features designed for diverse terminal environments and user needs.
Responsive Breakpoints
The layout engine uses dynamic breakpoints to adjust the UI based on terminal width. This ensures readability and prevents information density issues on small screens.
| Breakpoint | Width (Cols) | Behavior |
|---|---|---|
| UltraNarrow | < 40 | Minimal chrome, no breadcrumbs or hints. |
| Compact | 40 - 79 | Limited metadata, no sidebar. |
| Full | 80 - 119 | Standard view with sidebar and breadcrumbs. |
| UltraWide | >= 120 | Extended layout for large monitors. |
Sources: internal/tests/tui/layout/m1_regression_test.go:160-200
User Experience Enhancements
The project includes specific accessibility and UX toggles in its configuration:
- Reduced Motion Mode: Disables or simplifies animations for users sensitive to motion.
- Opacity Controls: Allows adjustment of UI transparency.
- Keyboard-First Navigation: Support for Vim-style navigation (
j/k) and leader key shortcuts (Ctrl+X).
Sources: README.md:155-165, internal/ui/tui/plan_model.go:180-195
Information Density Management
To maintain accessibility, M31A simplifies the "Chrome" (Headers and Footers) at smaller widths. For example, the header removes the Provider badge and Context meter in compact modes to prevent clutter.
Implementation Details
Style Computation
Semantic styles are generated through the BuildSemanticStyles function, which accepts a Theme and returns a populated SemanticStyles struct.
func BuildSemanticStyles(t Theme) SemanticStyles {
s := SemanticStyles{}
s.PageTitle = lipgloss.NewStyle().Foreground(t.TextPrimary).Bold(true)
s.ErrorText = lipgloss.NewStyle().Foreground(t.Error)
// ... further mappings
return s
}
Sources: internal/ui/tui/theme/tokens_semantic.go:210-230
Visual Consistency Rules
The design system mandates specific rules for maintainers:
- Intent over Appearance: Components must describe what they are, not how they look.
- No Pure Colors: Avoid pure white (#FFFFFF) or pure black (#000000) to reduce eye strain.
- Soft Contrast: Use desaturated semantic colors (e.g., desaturated red for errors).
Sources: internal/ui/tui/theme/tokens.go:3-10, internal/ui/tui/theme/tokens_semantic.go:10-20
M31A's theming and accessibility framework provides a consistent, high-contrast, and responsive environment. By decoupling design tokens from semantic intent and implementing responsive layout breakpoints, the system ensures that the terminal-native agent remains usable across varying hardware configurations and user preferences.