Terminal design system

My terminal design system supplies shared tokens and atomic compositions across native interfaces. Application code stays grouped by capability. The built-in Nord preset establishes the first baseline before a personal green preset is designed.

Jump to theme roles, presentation tokens, Git status components, the atomic catalog, or integration boundaries.

How the system fits together

The source chain is palette → semantic roles → component roles → native mappings. Preset selection chooses the input; --theme overrides it for an experiment. Runtime filenames, theme identifiers and adapter mappings stay independent of that choice. The status broker supplies state names; the generated tmux adapter resolves their presentation locally, ignoring producer-supplied colors. Shared tokens own reusable aliases, blend recipes and typed presentation defaults. Presets assign palette values; component definitions describe presentation roles. Adapters translate those definitions into each host’s native vocabulary.

The theme distinguishes selected rows, active tabs, warnings, errors, success, attention and unknown observations. Status retains a label or glyph. Syntax grammars can differ across hosts; matching semantic roles does not promise identical token classification.

Kitty opacity remains 0.97; Neovim’s main background remains inherited. The theme defines solid surfaces for popups, selections and other native components. Transparent compositing depends on the terminal and desktop behind it; preset captures show the solid theme backing.

Foundation contracts

Charmed’s foundations inform this system’s separation of meaning, emphasis, glyphs and terminal geometry. Atomic levels describe composition depth; native adapters stay organized by capability. The catalog leads with resolved component examples and links each component to its tokens and native consumers.

Foundation	Contract here
Meaning	Git file state, unstaged hunks, staged hunks and branch comparison keep separate identities. A renderer displays state supplied by its application.
Tone	Semantic color roles own meaning; glyph tokens carry no color. Focus, selection and status retain separate roles.
Emphasis	Bold changes weight; dim selects an explicit semantic shade. Neither changes the glyph or adds padding.
Glyphs	Every managed symbol declares a printable ASCII fallback of at most one cell. An empty glyph explicitly means count-only or no separator.
Geometry	Dimensions declare horizontal cells or vertical rows. Native adapters decide where padding is supported; website pixels are independent.
Evidence	Saved native examples belong to their preset. Browser color chips are references; actual terminal fixtures verify native translation.

Charmed’s contrast floors, one-cell Unicode geometry, lifecycle state catalog and chart-series palette belong to its native components. Existing dotfile adapters do not establish those guarantees. In particular, inherited backgrounds and Nord’s subdued gutter colors need separate contrast evaluation. Color remains accompanied by a state name, a glyph, or native Git context; the prompt deliberately keeps compact counts.

Presentation variants

Presets can override presentation without changing native adapters. Boolean emphasis, single-line symbol strings, and nonnegative integer spacing are typed. Spacing declares cell or row units; an adapter must explicitly support the unit. Current inline padding consumers use cells. These terminal units are separate from the website’s CSS pixels.

{
  "presentation": {
    "emphasis.heading": false,
    "space.inline": 2,
    "symbol.git.file.modified": "M"
  }
}

Add this optional object to a preset. Override values retain the shared declaration’s type and unit; aliases use { "token": "another.declared.token" }. Component/native references use the same explicit token object. A cell dimension becomes native text padding only through { "token": "space.inline", "as": "spaces" }. Missing references, cycles, incompatible types or units, and unsupported native syntax fail before generated files are written.

Heading emphasis reaches Neovim and Glow; Glow’s sixth-level heading stays subdued. Inline padding reaches Glow code spans and tmux’s session label. Powerline separators reach tmux and lualine. Git file status icons feed Starship’s native modules, preserving counts and ahead/behind composition. Unstaged, staged and branch-comparison gutter signs have separate token names and preserve their existing defaults. Empty symbol strings are allowed, including Starship’s count-only staged indicator. Each managed symbol also declares an ascii fallback in the shared token source. Nerd Font availability and native glyph widths remain host constraints; Neovim rejects gutter symbols wider than two display cells.

Starship’s complete configuration is generated from a native template; its existing configuration path remains stable. Other prompt-module symbols stay application specific. The catalog lists direct consumers and exceptions. Generated tokens.json records defaults, overrides and resolved values; existing colors.json consumers retain their color interface. Neovim and Python exports also expose resolved presentation values.

ASCII representation

Glyph representation is independent of the palette preset. Select it in design-system/config.json with { "theme": "nord", "symbols": "ascii" }, or generate an isolated variant:

python3 scripts/theme.py --theme nord --symbols ascii --output-dir /tmp/my-theme-ascii

The default is unicode. ASCII mode selects each managed symbol’s declared fallback, including Git status, gutter signs and separators. It takes precedence over a preset’s Unicode symbol override; edit the token’s ascii declaration to change that fallback. Color, emphasis and spacing retain their selected values. Other Starship modules, application-owned icons, border characters and document content keep their native behavior; this is a managed-glyph presentation, not an ASCII-only terminal or monochrome mode. Generation and native reload remain separate steps.

Symbols and color

A symbol token supplies a character; a semantic component pairs it with a foreground role and supported emphasis. For example, git.file.modified combines symbol.git.file.modified, the git.file.modified color role, and its bold/dim tokens. The Starship adapter formats that component together with its native count. A preset can change the glyph, color, or emphasis independently without editing the adapter.

{
  "roles": { "git.file.modified": "@status.info" },
  "presentation": {
    "symbol.git.file.modified": "M",
    "emphasis.git.file.modified.bold": true
  }
}

Shared Git foreground defaults reference ANSI slots, preserving the existing prompt palette while giving each state its own semantic role. The component always refers to that role. Unstaged, staged and branch-comparison components pair their sign tokens with separate diff foregrounds; the native editor adapter turns those components into sign text and highlight groups. Dim file status selects its dim_fg role before native output is generated; Starship receives the resulting RGB without a faint attribute. Staged/branch colors retain their separate muted diff roles. Shared recipes blend each semantic hue toward the preset surface; presets can supply a different shade through role overrides. Other symbols, such as separators, inherit the style of their enclosing component.

Generate, configure and reload

make theme-generate  # compile committed native artifacts
make theme-check    # validate sources and detect stale artifacts without writes
make shell kitty tmux-config vim-config zellij
make theme-cache    # refresh bat's cache, also consumed by delta

For the initial Zellij migration, build the changed status plugin with make zellij-status zellij. Subsequent palette changes use native KDL theme styles; the status renderer no longer embeds the theme RGB values. Runtime installation remains explicit and separate from theme generation.

Use Kitty’s existing Cmd+Shift+R binding, :colorscheme dotfiles in Neovim, and tmux source-file ~/.config/tmux/tmux.conf. Reopen pickers and pagers; restart bottom. Start a new Zellij session if its native watcher does not reload a theme-file edit. The main tmux config reload refreshes existing agent segment colors without resetting their state age. There is no coordinated live-switch guarantee.

For an isolated theme experiment, run python3 scripts/theme.py --theme nord --output-dir /tmp/my-theme. DOTFILES_THEME_DIR selects alternate generated artifacts for the native fixture runner and owned Python/Neovim/fzf consumers; it does not select a theme globally across running applications. Generated files carry native formats and require no generator during normal startup.

Presets

The built-in Nord preset owns its palette reference, native examples and initial regression baseline. New presets use the same token contract and native adapters; preset-specific captures stay with their preset.

Git status components

A Git-state component combines a symbol, semantic foreground and supported emphasis. File status and gutter signs retain distinct meanings. Previews use the selected preset’s surface and resolved color, including explicit dim shades.

File status · Starship



`git.file.conflicted`

@git.file.conflicted · #BF616A

Bold · Full intensity

Consumer: starship



`git.file.stashed`

@git.file.stashed.dim · #A5AAB2

Normal weight · Dimmed

Consumer: starship



`git.file.deleted`

@git.file.deleted · #BF616A

Normal weight · Full intensity

Consumer: starship



`git.file.renamed`

@git.file.renamed · #88C0D0

Normal weight · Full intensity

Consumer: starship



`git.file.modified`

@git.file.modified · #EBCB8B

Normal weight · Full intensity

Consumer: starship

`git.file.staged`

@git.file.staged · #A3BE8C

Normal weight · Full intensity · Count only

Consumer: starship



`git.file.untracked`

@git.file.untracked · #81A1C1

Normal weight · Full intensity

Consumer: starship



`git.file.typechanged`

@git.file.typechanged · #B48EAD

Normal weight · Full intensity

Consumer: starship



`git.file.ahead`

@git.file.ahead · #A3BE8C

Normal weight · Full intensity

Consumer: starship



`git.file.behind`

@git.file.behind · #EBCB8B

Normal weight · Full intensity

Consumer: starship



`git.file.branch`

@git.file.branch · #81A1C1

Normal weight · Full intensity

Consumer: starship

Unstaged hunks · Neovim

┃

`git.hunk.add`

@diff.add · #A3BE8C

Normal weight · Full intensity

Consumer: neovim

┃

`git.hunk.change`

@diff.change · #EBCB8B

Normal weight · Full intensity

Consumer: neovim

▁

`git.hunk.delete`

@diff.delete · #BF616A

Normal weight · Full intensity

Consumer: neovim

`git.hunk.topdelete`

@diff.delete · #BF616A

Normal weight · Full intensity

Consumer: neovim

`git.hunk.changedelete`

@diff.change · #EBCB8B

Normal weight · Full intensity

Consumer: neovim

┆

`git.hunk.untracked`

@diff.add · #A3BE8C

Normal weight · Full intensity

Consumer: neovim

Staged hunks · Neovim

┃

`git.staged_hunk.add`

@diff.add.dim · #6E806A

Normal weight · Full intensity

Consumer: neovim

┃

`git.staged_hunk.change`

@diff.change.dim · #968769

Normal weight · Full intensity

Consumer: neovim

▁

`git.staged_hunk.delete`

@diff.delete.dim · #7E4D57

Normal weight · Full intensity

Consumer: neovim

▔

`git.staged_hunk.topdelete`

@diff.delete.dim · #7E4D57

Normal weight · Full intensity

Consumer: neovim

`git.staged_hunk.changedelete`

@diff.change.dim · #968769

Normal weight · Full intensity

Consumer: neovim

Branch comparison · Neovim

│

`git.branch_hunk.add`

@diff.add.dim · #6E806A

Normal weight · Full intensity

Consumer: neovim

│

`git.branch_hunk.change`

@diff.change.dim · #968769

Normal weight · Full intensity

Consumer: neovim

`git.branch_hunk.delete`

@diff.delete.dim · #7E4D57

Normal weight · Full intensity

Consumer: neovim

`git.branch_hunk.topdelete`

@diff.delete.dim · #7E4D57

Normal weight · Full intensity

Consumer: neovim

Resolved theme roles

Resolved from the currently generated preset: nord. Preset references own their palettes and native examples.

surface#2E3440

surface.raised#3B4252

surface.selected#434C5E

border#4C566A

text#D8DEE9

text.strong#ECEFF4

text.muted#81A1C1

text.inverse#2E3440

accent#88C0D0

accent.secondary#8FBCBB

focus#B48EAD

status.success#A3BE8C

status.warning#EBCB8B

status.error#BF616A

status.info#88C0D0

status.attention#D08770

status.idle#81A1C1

status.off#4C566A

syntax.comment#4C566A

syntax.keyword#81A1C1

syntax.function#88C0D0

syntax.string#A3BE8C

syntax.type#8FBCBB

syntax.number#B48EAD

syntax.constant#D8DEE9

syntax.operator#81A1C1

syntax.special#EBCB8B

syntax.variable#D8DEE9

diff.add#A3BE8C

diff.change#EBCB8B

diff.delete#BF616A

diff.add.bg#414A4C

diff.change.bg#4C4C4C

diff.delete.bg#453B47

diff.add.dim#6E806A

diff.change.dim#968769

diff.delete.dim#7E4D57

selection.bg#434C5E

selection.fg#ECEFF4

match#A3BE8C

tab.active.bg#B48EAD

tab.active.fg#2E3440

tab.inactive.bg#2E3440

tab.inactive.fg#81A1C1

frame.inactive.fg#979DA9

keyhint#88C0D0

heading#88C0D0

link#88C0D0

prompt#88C0D0

diff.add.emph.bg#515D57

diff.delete.emph.bg#5A424D

git.file.conflicted#BF616A

git.file.stashed#E5E9F0

git.file.deleted#BF616A

git.file.renamed#88C0D0

git.file.modified#EBCB8B

git.file.staged#A3BE8C

git.file.untracked#81A1C1

git.file.typechanged#B48EAD

git.file.ahead#A3BE8C

git.file.behind#EBCB8B

git.file.branch#81A1C1

git.file.conflicted.dim#8C515B

git.file.stashed.dim#A5AAB2

git.file.deleted.dim#8C515B

git.file.renamed.dim#688F9E

git.file.modified.dim#A99671

git.file.staged.dim#7A8E71

git.file.untracked.dim#647B94

git.file.typechanged.dim#856E87

git.file.ahead.dim#7A8E71

git.file.behind.dim#A99671

git.file.branch.dim#647B94

file.directory#81A1C1

file.executable#A3BE8C

file.special#B48EAD

file.archive#D08770

file.project#EBCB8B

Presentation tokens

Inspect defaults, selected preset overrides and direct consumers. File status icons and gutter signs retain their own meanings. Native adapters own units and supported mappings.

Selected glyph representation: unicode. Git counts and ahead/behind composition stay in Starship’s native adapter. The bundled font previews default symbols; Unicode values identify variants requiring other glyphs.

Heading emphasis

`emphasis.heading`

Type: boolean
Default: true
Override: None
Resolved: true

Consumers: components, glow, neovim

Glow h6 remains subdued; other heading consumers use this emphasis.

Git file emphasis

`emphasis.git.file.conflicted.bold`

Type: boolean
Default: true
Override: None
Resolved: true

Terminal design system

How the system fits together

Foundation contracts

Presentation variants

ASCII representation

Symbols and color

Generate, configure and reload

Presets

Git status components

git.file.conflicted

git.file.stashed

git.file.deleted

git.file.renamed

git.file.modified

git.file.staged

git.file.untracked

git.file.typechanged

git.file.ahead

git.file.behind

git.file.branch

git.hunk.add

git.hunk.change

git.hunk.delete

git.hunk.topdelete

git.hunk.changedelete

git.hunk.untracked

git.staged_hunk.add

git.staged_hunk.change

git.staged_hunk.delete

git.staged_hunk.topdelete

git.staged_hunk.changedelete

git.branch_hunk.add

git.branch_hunk.change

git.branch_hunk.delete

git.branch_hunk.topdelete

Resolved theme roles

Presentation tokens

emphasis.heading

emphasis.git.file.conflicted.bold

emphasis.git.file.conflicted.dim

emphasis.git.file.stashed.bold

emphasis.git.file.stashed.dim

emphasis.git.file.deleted.bold

emphasis.git.file.deleted.dim

emphasis.git.file.renamed.bold

emphasis.git.file.renamed.dim

emphasis.git.file.modified.bold

emphasis.git.file.modified.dim

emphasis.git.file.staged.bold

emphasis.git.file.staged.dim

emphasis.git.file.untracked.bold

emphasis.git.file.untracked.dim

emphasis.git.file.typechanged.bold

emphasis.git.file.typechanged.dim

emphasis.git.file.ahead.bold

emphasis.git.file.ahead.dim

emphasis.git.file.behind.bold

emphasis.git.file.behind.dim

emphasis.git.file.branch.bold

emphasis.git.file.branch.dim

space.inline

symbol.separator.section.left

symbol.separator.section.right

symbol.separator.component.left

symbol.separator.component.right

symbol.git.file.conflicted

symbol.git.file.stashed

symbol.git.file.deleted

symbol.git.file.renamed

symbol.git.file.modified

symbol.git.file.staged

symbol.git.file.untracked

symbol.git.file.typechanged

symbol.git.file.ahead

symbol.git.file.behind

symbol.git.file.branch

symbol.git.hunk.add

symbol.git.hunk.change

symbol.git.hunk.delete

symbol.git.hunk.topdelete

`git.file.conflicted`

`git.file.stashed`

`git.file.deleted`

`git.file.renamed`

`git.file.modified`

`git.file.staged`

`git.file.untracked`

`git.file.typechanged`

`git.file.ahead`

`git.file.behind`

`git.file.branch`

`git.hunk.add`

`git.hunk.change`

`git.hunk.delete`

`git.hunk.topdelete`

`git.hunk.changedelete`

`git.hunk.untracked`

`git.staged_hunk.add`

`git.staged_hunk.change`

`git.staged_hunk.delete`

`git.staged_hunk.topdelete`

`git.staged_hunk.changedelete`

`git.branch_hunk.add`

`git.branch_hunk.change`

`git.branch_hunk.delete`

`git.branch_hunk.topdelete`

`emphasis.heading`

`emphasis.git.file.conflicted.bold`

`emphasis.git.file.conflicted.dim`

`emphasis.git.file.stashed.bold`

`emphasis.git.file.stashed.dim`

`emphasis.git.file.deleted.bold`

`emphasis.git.file.deleted.dim`

`emphasis.git.file.renamed.bold`

`emphasis.git.file.renamed.dim`

`emphasis.git.file.modified.bold`

`emphasis.git.file.modified.dim`

`emphasis.git.file.staged.bold`

`emphasis.git.file.staged.dim`

`emphasis.git.file.untracked.bold`

`emphasis.git.file.untracked.dim`

`emphasis.git.file.typechanged.bold`

`emphasis.git.file.typechanged.dim`

`emphasis.git.file.ahead.bold`

`emphasis.git.file.ahead.dim`

`emphasis.git.file.behind.bold`

`emphasis.git.file.behind.dim`

`emphasis.git.file.branch.bold`

`emphasis.git.file.branch.dim`

`space.inline`

`symbol.separator.section.left`

`symbol.separator.section.right`

`symbol.separator.component.left`

`symbol.separator.component.right`

`symbol.git.file.conflicted`

`symbol.git.file.stashed`

`symbol.git.file.deleted`

`symbol.git.file.renamed`

`symbol.git.file.modified`

`symbol.git.file.staged`

`symbol.git.file.untracked`

`symbol.git.file.typechanged`

`symbol.git.file.ahead`

`symbol.git.file.behind`

`symbol.git.file.branch`

`symbol.git.hunk.add`

`symbol.git.hunk.change`

`symbol.git.hunk.delete`

`symbol.git.hunk.topdelete`

`symbol.git.hunk.changedelete`

`symbol.git.hunk.untracked`

`symbol.git.staged_hunk.add`

`symbol.git.staged_hunk.change`

`symbol.git.staged_hunk.delete`

`symbol.git.staged_hunk.topdelete`

`symbol.git.staged_hunk.changedelete`

`symbol.git.branch_hunk.add`

`symbol.git.branch_hunk.change`

`symbol.git.branch_hunk.delete`

`symbol.git.branch_hunk.topdelete`