Skip to content

Custom CSS

Overview

Mutsumi’s TUI is built with Textual, which uses a CSS-like styling system. You can inject custom CSS to override any visual aspect of the interface.

Configuration

Set the custom_css_path in config.toml:

custom_css_path = "~/.config/mutsumi/custom.tcss"

Create the file at that path. Mutsumi loads it on startup and applies it on top of the default styles.

Textual CSS Basics

Textual CSS looks like web CSS but targets terminal widgets:

/* Target by widget class name */
TaskRow {
  background: #1e1e2e;
  color: #cdd6f4;
}

/* Target by ID */
#header-bar {
  background: #181825;
}

/* Target by CSS class */
.priority-high {
  color: #f38ba8;
}

/* Pseudo-classes */
TaskRow:hover {
  background: #313244;
}

TaskRow:focus {
  background: #45475a;
}

These are the main widget classes you can target:

Widget	Description
`MutsumiApp`	Root application
`HeaderBar`	Top bar with tabs and branding
`TaskList`	Main scrollable task container
`TaskRow`	Individual task row
`PriorityGroup`	Priority section header (HIGH/NORMAL/LOW)
`DetailPanel`	Expanded task detail view
`FooterBar`	Bottom status bar
`ConfirmBar`	Inline delete confirmation
`ConfirmDialog`	Modal delete confirmation
`SearchBar`	Search input bar
`SortOverlay`	Sort field picker
`HelpScreen`	Keybinding help overlay
`TaskForm`	New/edit task dialog

CSS Classes

Class	Applied to
`.priority-high`	Task rows with high priority
`.priority-normal`	Task rows with normal priority
`.priority-low`	Task rows with low priority
`.task-done`	Completed task rows
`.task-pending`	Pending task rows
`.tab-active`	Currently active scope tab
`.search-match`	Tasks matching search query
`.search-dim`	Tasks not matching search query

Example: Wider Task List

TaskList {
  width: 100%;
  max-width: 120;
}

Example: Custom Priority Colors

.priority-high {
  color: #ff6b6b;
}

.priority-normal {
  color: #ffd93d;
}

.priority-low {
  color: #6bcb77;
}

Example: Strikethrough for Done Tasks

.task-done {
  text-style: strike;
  color: #666666;
}

FooterBar {
  display: none;
}

Example: Custom Header Background

HeaderBar {
  background: #181825;
  border-bottom: solid #313244;
}

Example: Rounded Detail Panel

DetailPanel {
  border: round #45475a;
  padding: 1 2;
  margin: 1;
}

Tips

Restart Mutsumi after editing the CSS file for changes to take effect.
Use mutsumi config --path to confirm where your config file is located.
Textual CSS supports !important for overriding specificity.
Colors can be specified as hex (#ff5555), named (red), or RGB (rgb(255, 85, 85)).
text-style accepts: bold, italic, underline, strike, reverse, dim.