ccch1mneyyy/dsh-TUI / guide/dsh-tui-guide
dsh-tui-guide
UnverifiedUse when the user asks about dsh-tui itself (usage, shortcuts, config, themes, migration, VS Code). Load before answering; skip for normal coding tasks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
| claude-backend.en.md | markdown | 14.5 KB |
| claude-backend.md | markdown | 13.2 KB |
| cli.en.md | markdown | 9.0 KB |
| cli.md | markdown | 8.4 KB |
| codex-backend.en.md | markdown | 23.3 KB |
| codex-backend.md | markdown | 20.7 KB |
| configuration.en.md | markdown | 43.0 KB |
| configuration.md | markdown | 39.4 KB |
| getting-started.en.md | markdown | 30.9 KB |
| getting-started.md | markdown | 28.9 KB |
| interaction.en.md | markdown | 75.1 KB |
| interaction.md | markdown | 68.8 KB |
| migrate.en.md | markdown | 10.5 KB |
| migrate.md | markdown | 9.5 KB |
| plugins.en.md | markdown | 16.8 KB |
| plugins.md | markdown | 14.5 KB |
| themes.en.md | markdown | 10.3 KB |
| themes.md | markdown | 10.0 KB |
| user-guide.en.md | markdown | 80.9 KB |
| user-guide.md | markdown | 75.0 KB |
| vscode.en.md | markdown | 13.8 KB |
| vscode.md | markdown | 12.6 KB |
themes.en.md
View on GitHub# Themes
[Documentation index](README.md) · [简体中文](themes.md)
## Built-in themes
dsh-TUI ships two palette families (six themes) plus an `auto` pseudo-theme:
| Name | Family | Purpose |
| --- | --- | --- |
| `auto` | — | Pseudo-theme: follows the system/terminal background, resolving to `light` or `dark` |
| `light` | Mist Blue | White panels, ink body text, and mist-blue interaction color |
| `dark` | Mist Blue | Dark-terminal adaptation with warm-gray text and soft blue accents |
| `dark-ansi` | Mist Blue | 16-color ANSI fallback (except the ignition pair) |
| `pink-day` | Sakura Pink | Light terminals: blush panels and sakura-pink interaction color |
| `pink-night` | Sakura Pink | Dark terminals: warm surfaces and sakura-pink interaction color |
| `pink-ansi` | Sakura Pink | 16-color ANSI fallback (except the ignition pair) |
Both families keep the same role split (light / dark / ANSI fallback). `auto`
resolves within the Mist Blue family only; the Sakura Pink family is selected
explicitly.
Without an explicit choice, the TUI queries the terminal background with OSC
11 and selects `light` or `dark`. It falls back to `dark` when the terminal
does not answer.
Light-theme panels and tool cards take their own family's surface colors (`light`
uses white `#FFFFFF`; `pink-day` uses blush `#F9ECF1`), and their input fills are
the warm `#F6F3ED` / `#FBF3F0`; image previews always use neutral borders. Dark
palettes and accent colors are unchanged. This does not modify the terminal's own
background or wallpaper.
`auto` turns that one-shot startup detection into a standing choice:
- A valid value for `/theme`, `DSH_TUI_THEME`, and `~/.dsh-tui/theme.json`.
- Selecting `auto` applies the last detected base immediately and re-queries
OSC 11 in the background.
- On terminals that follow the system theme, picking `auto` again (or
restarting) catches up after a system light/dark switch.
- `/theme status` shows which palette `auto` currently resolves to.
- `getTheme('auto')` serves that palette to every consumer.
- A user theme named `auto` is shadowed by the built-in pseudo-theme (not
listed in the picker).
Selection precedence is:
```text
DSH_TUI_THEME
> persisted choice in ~/.dsh-tui/theme.json
> OSC 11 background detection
> dark fallback
```
## Switching themes
- `/theme` opens the picker, with `auto` and the built-ins before static JSON
and plugin themes. On terminals at least 76 columns wide a live preview sits
beside the list: the **focused row's** palette renders a code block, a
code-operation tool card and a diff, so moving the cursor compares syntax,
diff and tool-card colors before Enter applies anything. Narrower terminals
stack the preview under the list, and it yields entirely when the height
budget is short — the list and its focused row always stay visible.
- `/theme <name>` switches directly to a built-in, static JSON, or runtime plugin theme.
- `/theme status` shows the current theme and persistence location.
Confirming a choice hot-switches immediately and writes it to
`~/.dsh-tui/theme.json`. `DSH_TUI_THEME`, when set, still wins on the next
launch.
## Custom themes
Place JSON files under `~/.dsh-tui/themes/`. Each file starts from one
built-in palette and overrides a subset of its colors:
```json
{
"name": "sakura",
"displayName": "Sakura",
"base": "dark",
"colors": {
"accent": "#FF9EC7",
"accentShimmer": "#FFC0D5",
"activity": "#7DA1DE",
"activityShimmer": "#ABC2EC",
"mascotBody": "#D98A63",
"inputBackground": "#000000",
"permission": "#FFB3CC",
"promptBorder": "#B08B99",
"text": "#E8E6E0",
"inactive": "#A99BA0",
"subtle": "#8A7A80",
"selectionBg": "#5C3A44",
"success": "#9CC7A8",
"error": "#E08591",
"warning": "#E0C08A"
}
}
```
Fields:
| Field | Required | Meaning |
| --- | --- | --- |
| `base` | Yes | `light`, `dark`, or `dark-ansi`; source for every non-overridden color |
| `colors` | Yes | Partial override of Theme color keys |
| `name` | No | Theme ID; defaults to the filename |
| `displayName` | No | Picker label; defaults to `name` |
Available color keys by purpose:
- Brand/focus/activity: `accent`, `accentShimmer`, `activity`, `activityShimmer`, `suggestion`, `remember`
- Panels/borders: `permission`, `permissionShimmer`, `promptBorder`, `promptBorderShimmer`, `bashBorder`, `planMode`, `ide`, `background`
- Body text: `text`, `inverseText`, `inactive`, `inactiveShimmer`, `subtle`
- Tool names & status dots: `toolNameMutate`, `toolNameExec`, `toolDotExec`, `toolDotRead`, `toolDotWrite`, `toolDotWeb`, `toolDotTask`
- Tool card surfaces: `toolCardBackground`, `toolCardBackgroundDim`, `presentCardWarm`, `presentCardTint`
- Status: `autoAccept`, `success`, `error`, `warning`, `warningShimmer`, `merged`
- Diff: `diffAdded`, `diffRemoved`, `diffAddedDimmed`, `diffRemovedDimmed`, `diffAddedWord`, `diffRemovedWord`
- Diff syntax highlighting: `syntaxKeyword`, `syntaxString`, `syntaxComment`, `syntaxNumber`, `syntaxFunction`, `syntaxType`
- Diff syntax highlighting (cont.): `syntaxVariable`, `syntaxOperator`, `syntaxPunctuation`, `syntaxConstant`
- Badges/accents: `mascotBody`, `inputBackground`, `professionalBlue`, `chromeYellow`
- Animated chrome & caret: `contextBarSystem`, `contextBarPrompt`, `contextBarAssistant`
- Animated chrome & caret (cont.): `contextBarThinking`, `contextBarTools`, `ignition`, `ignitionDim`, `cursor`
- Messages & input: `userMessageBackground`, `userMessageBackgroundHover`, `messageActionsBackground`, `selectionBg`, `bashMessageBackgroundColor`
- Messages & input (cont.): `memoryBackgroundColor`, `rate_limit_fill`, `rate_limit_empty`, `fastMode`, `fastModeShimmer`, `userPromptLabel`
- Subagent messages: `subagentBullet`, `subagentDescription`, `subagentModel`, `subagentElapsed`, `subagentToolName`, `subagentStatusRunning`
- Subagent messages (cont.): `subagentStatusCompleted`, `subagentStatusFailed`
When the file declares `name`, its filename remains a loading alias. See the
`Theme` type in [`src/theme.ts`](../src/theme.ts) for every color key.
A few keys carry behavior worth knowing:
- `contextBarSystem` … `contextBarTools`: the context progress bar's five segment fills, in bar
order (system → prompt → assistant → thinking → tools). Static JSON and plugin themes inherit
all five from the `base` they pick; only a legacy resolver's key-less palette keeps the old ramp.
- `ignition` / `ignitionDim`: the top reasoning tier's ignition colors — the sweep waveform, the
`❯` prefix and the tier badge all read the same pair, and `ignitionDim` is the substrate the
wave fades into. The wave emits per-column truecolor SGR, so these two want a form with fixed
channels (`#rgb`, `#rrggbb`, `#rrggbbaa` with the alpha ignored, or `rgb(r,g,b)`); `ansi:*` /
`ansi256(n)` — or a missing key — falls back **per key** to the built-in pair selected by the
palette's lightness, so the other key is unaffected.
- `cursor`: the painted caret fill in the main prompt, launchpad input and picker search boxes
during static rendering without a native cursor, plus image-token focus in the main prompt.
Ordinary TTY text editing uses the native cursor; shape, color, blinking and animation follow terminal settings.
The glyph on it is whichever of `text` / `inverseText`
contrasts better with that fill (a 16-color `ansi:*` fill, or a palette whose `text`/`inverseText`
has no parseable channels, cannot be measured and keeps `inverseText`), so a light caret can still
carry dark ink. The built-ins leave it empty, giving the painted fallback an inverse-video block.
A custom fill affects these painted highlights only.
- Transcript link text follows `accent`; an empty or unparseable accent keeps the old fixed blue.
## npm plugin themes
An npm plugin registers a runtime theme through the `tuiThemes` service,
without writing to `~/.dsh-tui/themes/`. Minimal example:
```ts
import type { Context } from '@deepseek-ai/cordis'
export function apply(ctx: Context): void {
ctx.get('tuiThemes', false)?.register({
name: 'my-plugin:night',
base: 'dark',
colors: { accent: '#88AAFF' },
}, ctx)
}
```
- Use a lowercase safe ID such as `plugin-id:theme-id`.
- `auto`, built-in names, and `status` are reserved.
- Registrations are removed with the plugin activation; the returned disposer
can remove one early.
- Plugin themes appear in the `/theme` picker and completion; their names use
the existing `~/.dsh-tui/theme.json` persistence.
- Priority: built-ins > static JSON > same-name plugin theme.
- On an older profile without `tuiThemes`, the plugin degrades silently and
static themes remain unaffected.
See the [Plugin Admission and Development Guide](../tui-profile/docs/plugin-admission-and-development.md)
for the full key list, legacy-key mapping, and registration contract.
## Color formats
Accepted forms:
- `#rgb`
- `#rrggbb`
- `#rrggbbaa`
- `rgb(r,g,b)`
- `ansi256(n)`
- 16-color names such as `ansi:black` and `ansi:redBright`
Colors must be concrete values. CSS variables, gradients, and arbitrary CSS
color names are not accepted.
## Validation and failure behavior
- Unknown Theme key: skip that key with a warning and keep the rest.
- Invalid color: skip that value with a warning.
- Invalid `base`, malformed JSON, or non-object `colors`: skip the whole file.
- Missing theme referenced by the environment or preference file: warn and
continue with background detection.
- One bad theme never blocks TUI startup or other themes.
Theme names are user input. The loader verifies that the resolved path
remains inside `~/.dsh-tui/themes/`, preventing names from escaping the theme
directory. Preserve that containment check when changing the implementation.
## Design guidance
- Use color keys instead of changing only `text` and `background`. Check at
least body, inactive, focus, selection, success, warning, error, and diff
colors.
- Test light themes in a real light terminal and dark themes in a dark one.
- Check 16-color, 256-color, and truecolor fallback behavior.
- Verify narrow layouts, tool diffs, questionnaires, multiline input, and
selection contrast.
- Theme files should contain display metadata and color only, never credentials
or other user data.
When developing the theme subsystem, run:
```sh
node --import tsx/esm scripts/verify-themes.mjs
```
See [Architecture and limitations](architecture.en.md) for terminal capability
and renderer details.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |