Catppuccin — TUI Design System
Soothing pastel theme for the high-spirited. Based on Catppuccin Mocha, the community-driven pastel palette loved for its gentle aesthetics.
1. Theme Overview
- Mood: Warm, pastel, soothing
- Density: Balanced — comfortable with gentle contrast
- Target: Personal tools, editors, music players, chat apps, any cozy CLI
- Terminal: TrueColor recommended, 256-color acceptable
2. Color Palette
Semantic Roles (Mocha flavor)
| Role | Hex | ANSI 256 | ANSI 16 | Usage |
|---|---|---|---|---|
| Background | #1e1e2e |
234 |
black |
Base |
| Foreground | #cdd6f4 |
189 |
white |
Text |
| Primary | #cba6f7 |
183 |
bright magenta |
Mauve — primary accent |
| Secondary | #89b4fa |
111 |
bright blue |
Blue — secondary |
| Accent | #f5c2e7 |
218 |
magenta |
Pink — highlights |
| Success | #a6e3a1 |
151 |
green |
Green |
| Warning | #f9e2af |
223 |
yellow |
Yellow |
| Error | #f38ba8 |
211 |
red |
Red |
| Muted | #585b70 |
240 |
bright black |
Surface2 — dim text |
| Surface | #313244 |
236 |
black |
Surface0 — raised |
Extended Catppuccin Mocha
| Name | Hex | ANSI 256 | Usage |
|---|---|---|---|
| Rosewater | #f5e0dc |
224 |
Links, special text |
| Flamingo | #f2cdcd |
224 |
IDs, highlights |
| Peach | #fab387 |
216 |
Numbers, constants |
| Teal | #94e2d5 |
152 |
Paths, URLs |
| Sky | #89dceb |
117 |
Operators |
| Lavender | #b4befe |
147 |
Active indicators |
| Overlay0 | #6c7086 |
243 |
Comments, subtle |
| Mantle | #181825 |
233 |
Deeper background |
| Crust | #11111b |
232 |
Deepest background |
3. Typography & ASCII Art
- Header font:
small(figlet) — gentle, not aggressive - Body text: plain terminal font
- Emphasis:
bold+ Mauve or Pink - Code/values: Teal or Peach
Text Hierarchy
| Level | Style | Example Usage |
|---|---|---|
| H1 | figlet small + Mauve |
App title |
| H2 | BOLD + Mauve | Section headers |
| H3 | BOLD + Blue | Subsections |
| Body | Text (foreground) | Content |
| Caption | Overlay0 | Help, metadata |
| Data | Teal | Paths, URLs |
| Numbers | Peach | Numeric values |
4. Borders & Box Drawing
Primary Border
╭──────────────╮
│ content │
╰──────────────╯
Rounded corners in Surface2 (Muted). Soft and inviting.
Parts Table
| Part | Character | Usage |
|---|---|---|
| top_left | ╭ |
Panel corners |
| top_right | ╮ |
|
| bottom_left | ╰ |
|
| bottom_right | ╯ |
|
| horizontal | ─ |
|
| vertical | │ |
|
| cross | ┼ |
Table intersections |
| tee_down | ┬ |
|
| tee_up | ┴ |
|
| tee_right | ├ |
|
| tee_left | ┤ |
Dividers
- Horizontal:
──────────────────(Muted) - Section break:
── 🌸 ──or── ◦ ──
5. Components
Buttons / Actions
▸ Save Cancel Help
↑ ↑ ↑
focused normal muted
- Focused:
▸prefix + reverse (Mauve bg) + BOLD - Normal: Foreground
- Disabled: Muted + dim
Input Fields
Title: ╭────────────────────────╮
│ My cozy project_ │
╰────────────────────────╯
- Active: Mauve border
- Inactive: Muted border
- Error: Red border
Tables
Name Type Status
──────────────────────────────────────────
sunrise.mp3 Audio ▸ Playing
moonlight.flac Audio ○ Queued
stars.mp3 Audio ○ Queued
Borderless. Muted divider. Gentle presentation.
Lists / Menus
Library
▸ Now Playing
Playlists
Settings
- Selected:
▸+ BOLD + Mauve - Normal: Foreground
- Disabled: Muted + dim
Panels / Cards
╭── Now Playing ─────────────────╮
│ │
│ ♪ Moonlight Sonata │
│ ── ◦ ──────────────── ◦ ── │
│ ▕████████████░░░░░░░░▏ 3:24 │
│ │
╰─────────────────────────────────╯
Title in Mauve. Song name in Foreground. Progress in Lavender.
Status Bar
♪ Playing · Moonlight Sonata · 3:24 / 5:12 ♥ Favorites
Lavender active indicator. Muted separators. Pink for favorites.
6. Layout & Spacing
- Min terminal width:
80 - Ideal terminal width:
100 - Padding inside panels: 1 line top/bottom, 1 char left/right
- Gap between components: 1 empty line
- Indent level: 2 spaces
Alignment Principles
- Left-align content
- Right-align secondary status bar info
- Generous spacing — cozy, not cramped
7. Icons & Indicators
| Purpose | Icon | Fallback (ASCII) |
|---|---|---|
| Success | ✓ |
+ |
| Error | ✗ |
x |
| Warning | ! |
! |
| Info | ● |
* |
| Pending | ○ |
o |
| Running | ▸ |
> |
| Spinner | ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ |
|/- |
| Arrow | → |
-> |
| Bullet | ◦ |
o |
| Selected | ▸ |
> |
| Music | ♪ |
# |
| Heart | ♥ |
<3 |
8. Animation & Motion
Spinners
- Default:
⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏at 80ms in Mauve - Gentle:
◜ ◠ ◝ ◞ ◡ ◟at 150ms in Lavender
Transitions
- No harsh transitions — instant but gentle state changes
- Spinners for async operations
Progress
▕████████████░░░░░░░░▏ 58%
- Filled:
█in Mauve, Empty:░in Muted - Caps:
▕▏ - Shifts to Green on completion
9. Agent Prompt Guide
Quick Reference
Background: #1e1e2e (Base — deep purple-black)
Foreground: #cdd6f4 (Text — soft blue-white)
Mauve: #cba6f7 (primary accent)
Blue: #89b4fa (secondary)
Pink: #f5c2e7 (highlights)
Green: #a6e3a1 (success)
Yellow: #f9e2af (warning)
Red: #f38ba8 (error)
Peach: #fab387 (numbers)
Teal: #94e2d5 (paths/URLs)
Muted: #585b70 (borders, dim text)
Border: ╭─╮│╰─╯ (rounded, muted)
Style: warm pastels, rounded borders, cozy spacing, mauve primary
Example Prompts
- “Build a music player TUI: Catppuccin Mocha palette, rounded borders in muted gray, mauve accents, ♪ music icons, gentle layout with breathing room”
- “Create a task manager: pastel Catppuccin theme, mauve for active items, peach for deadlines, teal for tags, borderless tables”
- “Design a chat interface: Catppuccin dark base, pink for mentions, blue for links, rounded message bubbles (bordered panels), lavender for timestamps”
Do’s and Don’ts
Do
- Use Mauve as the signature color — it’s the Catppuccin identity
- Use the extended palette (Peach, Teal, Lavender) for semantic color coding
- Use rounded corners — soft and inviting
- Keep the overall feeling warm and cozy
- Use pastel colors at full intensity — they’re already soft by nature
Don’t
- Don’t use harsh, saturated neon colors — pastels only
- Don’t use heavy or double-line borders — too aggressive
- Don’t use ALL CAPS headers — too loud
- Don’t overcrowd — this theme values breathing room
- Don’t use emoji as functional icons — keep ♪ and ♥ as special decorative touches only