feat: add --theme CLI option for custom color schemes by esumerfd · Pull Request #217 · subsy/ralph-tui

esumerfd · 2026-01-24T22:00:34Z

Add support for loading custom color themes from JSON files at runtime.

Changes:

Add --theme CLI flag to argument parsing
Create theme file loader with JSON parsing and hex color validation
Implement deep merge for partial theme overrides (fallback to defaults)
Make colors object runtime-configurable while maintaining type safety
Wire theme initialization into TUI startup (before components render)
Add comprehensive unit tests for loader, validator, and merge functions
Include bundled themes: bright-theme.json, high-contrast-theme.json
Document --theme option in README with example screenshot

Usage:
ralph-tui run --theme ./assets/themes/high-contrast-theme.json

Screenshots

Custom Theme Example:

ralph-tui run --theme ./assets/themes/high-contrast-theme.json

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Custom colour theme support via a new CLI --theme option to load JSON theme files.
- Two bundled colour themes added: Bright and High-Contrast.
Documentation
- New “Themes” docs and README sections with usage examples, theme schema, bundled theme descriptions and guidance on creating/using partial custom themes.
Tests
- Expanded tests for theme loading, validation, merging, initialization and reset.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add support for loading custom color themes from JSON files at runtime. Changes: - Add --theme <filename> CLI flag to argument parsing - Create theme file loader with JSON parsing and hex color validation - Implement deep merge for partial theme overrides (fallback to defaults) - Make colors object runtime-configurable while maintaining type safety - Wire theme initialization into TUI startup (before components render) - Add comprehensive unit tests for loader, validator, and merge functions - Include bundled themes: bright-theme.json, high-contrast-theme.json - Document --theme option in README with example screenshot Usage: ralph-tui run --theme ./assets/themes/high-contrast-theme.json 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

vercel · 2026-01-24T22:00:39Z

@esumerfield is attempting to deploy a commit to the plgeek Team on Vercel.

A member of the Team first needs to authorize it.

coderabbitai · 2026-01-24T22:00:52Z

Walkthrough

Adds JSON-driven theming: new theme assets, a runtime theming core with load/validate/merge/apply functions and a Proxy-backed active colors object, CLI --theme support and config field, expanded tests, and documentation and navigation entries for theme usage. No public API removals.

Changes

Cohort / File(s)	Summary
Theme System Implementation `src/tui/theme.ts`	New theming core: `ThemeColors`/`PartialThemeColors` types, `defaultThemeColors`/`defaultColors`, Proxy-backed `colors`, deep merge (`mergeTheme`), hex validation, `loadThemeFile`, `initializeTheme`, `resetTheme` and helpers.
CLI & Runtime Types `src/commands/run.tsx`, `src/config/types.ts`	Adds `--theme` CLI option and early `initializeTheme` usage; `RuntimeOptions` gains optional `themePath?: string`.
Theme Assets `assets/themes/bright-theme.json`, `assets/themes/high-contrast-theme.json`	Adds two JSON theme files with hierarchical color tokens (`bg`, `fg`, `status`, `task`, `accent`, `border`) using hex colour codes.
Documentation & Site `README.md`, `website/content/docs/configuration/themes.mdx`, `website/lib/navigation.ts`	Adds Custom Themes docs, CLI examples, theme schema/validation notes, and registers a Themes page in site navigation.
Tests `tests/tui/theme.test.ts`	Large test additions covering `mergeTheme`, `loadThemeFile`, `initializeTheme`, `isValidHexColor`, `resetTheme`, error cases and integration with the colours API.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as Command Line<br/>(src/commands/run.tsx)
    participant ThemeSys as Theme System<br/>(src/tui/theme.ts)
    participant FS as File System
    participant TUI as TUI Components

    User->>CLI: ralph run --theme ./path/theme.json
    CLI->>CLI: parse args, extract themePath
    CLI->>ThemeSys: initializeTheme(themePath)
    ThemeSys->>FS: read theme JSON file
    FS-->>ThemeSys: return JSON
    ThemeSys->>ThemeSys: parse, validate hex colours
    ThemeSys->>ThemeSys: merge partial theme with defaults
    ThemeSys->>ThemeSys: update activeColors (Proxy)
    ThemeSys-->>CLI: initialization success
    CLI->>TUI: start/render UI
    TUI->>ThemeSys: access colors proxy
    ThemeSys-->>TUI: provide active colours
    TUI-->>User: render themed interface

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐇 I hopped through hex and midnight skies,
I stitched bright tones where darkness lies.
A Tokyo dusk, a contrast beam,
Now UIs sparkle where I dream—
Tiny paws, big colour dreams. 🎨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding a --theme CLI option for custom color schemes, which aligns with the primary objective of the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

subsy · 2026-01-26T16:03:51Z

@esumerfd mind adding a couple of screenshots to the PR?

codecov · 2026-01-26T16:38:06Z

Codecov Report

❌ Patch coverage is 70.68966% with 34 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.04%. Comparing base (c64bd43) to head (60f771f).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/commands/run.tsx	10.52%	17 Missing ⚠️
src/tui/theme.ts	82.47%	17 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #217      +/-   ##
==========================================
+ Coverage   44.93%   45.04%   +0.10%     
==========================================
  Files          84       84              
  Lines       24486    24596     +110     
==========================================
+ Hits        11004    11079      +75     
- Misses      13482    13517      +35

Files with missing lines	Coverage Δ
src/config/types.ts	`100.00% <ø> (ø)`
src/commands/run.tsx	`8.23% <10.52%> (-0.04%)`	⬇️
src/tui/theme.ts	`92.40% <82.47%> (-6.92%)`	⬇️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

vercel · 2026-01-26T16:44:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
ralph-tui	Ignored	Preview	Jan 26, 2026 9:26pm

subsy · 2026-01-26T16:47:33Z

@esumerfd Thanks - looks good - but before i merge can you please

remove/trim down the README.md content
update the actual website/docs content with usage guidance

Thanks!

feat: add --theme CLI option for custom color schemes

subsy mentioned this pull request Jan 26, 2026

How do you change the contrast or style of the TUI? #154

Closed

Shrink up the readme a little, and add themes to the website docs.

0a4e906

vercel bot deployed to Preview January 26, 2026 19:49 View deployment

Merge branch 'main' into main

60f771f

subsy merged commit 4bebef6 into subsy:main Jan 26, 2026
8 checks passed

coderabbitai bot mentioned this pull request Jan 27, 2026

feat: simplify theme usage with bundled theme names #231

Merged

5 tasks

sakaman pushed a commit to sakaman/ralph-tui that referenced this pull request Feb 15, 2026

Merge pull request subsy#217 from esumerfd/main

99b62bb

feat: add --theme CLI option for custom color schemes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add --theme CLI option for custom color schemes#217

feat: add --theme CLI option for custom color schemes#217
subsy merged 3 commits intosubsy:mainfrom
esumerfd:main

esumerfd commented Jan 24, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Jan 24, 2026

Uh oh!

coderabbitai bot commented Jan 24, 2026 •

edited

Loading

Uh oh!

subsy commented Jan 26, 2026

Uh oh!

codecov bot commented Jan 26, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 26, 2026 •

edited

Loading

Uh oh!

subsy commented Jan 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

esumerfd commented Jan 24, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Screenshots

Summary by CodeRabbit

Uh oh!

vercel bot commented Jan 24, 2026

Uh oh!

coderabbitai bot commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

Uh oh!

subsy commented Jan 26, 2026

Uh oh!

codecov bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

vercel bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

subsy commented Jan 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

esumerfd commented Jan 24, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 24, 2026 •

edited

Loading

codecov bot commented Jan 26, 2026 •

edited

Loading

vercel bot commented Jan 26, 2026 •

edited

Loading