Gemini CLI — TUI Design System

Google’s AI assistant in the terminal. Based on Gemini CLI — colorful, polished, with Google brand gradients and a comprehensive theme system.

1. Theme Overview

• Mood: Colorful, polished, branded
• Density: Balanced — clean conversation with bordered tool blocks
• Target: AI agents, branded CLI tools, interactive assistants, developer tools
• Terminal: TrueColor recommended for gradient effects, 256-color minimum

2. Color Palette

Semantic Roles

Google Brand Gradient

#4796E4 → #847ACE → #C3677F
  blue      purple     rose

Used for banners, spinner, and decorative brand elements. Applied as gradient text via tinygradient library where TrueColor is available.

Built-in Theme System (15+ Themes)

Gemini CLI ships with a comprehensive theme system — users can switch between built-in themes or create custom ones:

Custom themes can be defined via JSON with a semantic color token architecture (e.g., ui.active, status.warning, border.default).

Built with React Ink (not ratatui like Codex).

Tool Call Border Colors (Semantic)

3. Typography & ASCII Art

• Header font: Block character icon (▝▜▄ pattern) + “Gemini” text
• Body text: plain terminal font
• Emphasis: bold + Primary, italic for status text
• Code/values: Accent (cyan)

Text Hierarchy

4. Borders & Box Drawing

Primary Border

╭──────────────╮
│   content    │
╰──────────────╯

Rounded borders throughout. Color changes by semantic state.

Parts Table

Border States

• Running (shell): Primary blue border
• Pending (non-shell): Warning yellow border
• Focused: Success green border
• Completed: Muted gray border

5. Components

Gradient Spinner (Signature Feature)

  ⠋ Thinking... (3.2s)  (esc to cancel)

• Braille dots spinner (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏)
• Spinner color cycles through 6-color Google brand gradient at 33fps: purple → blue → cyan → green → yellow → red
• Italic status text with elapsed timer
• (esc to cancel) hint in Muted

Brand Banner

  ▝▜
  ▗▟▄  Gemini CLI

• Block character icon (▝▜▄ quadrant pattern) — represents the Gemini sparkle
• “Gemini CLI” text in gradient (blue → purple → rose)
• Displayed at startup/header
• The icon uses Unicode quadrant block characters for a compact logo that works in any terminal

AI Response

  Here's how to fix the import issue:

  The problem is that `utils` isn't exported from the
  package root. You need to import it directly:

  `import { helper } from '@pkg/utils/helper'`

• Plain Foreground text
• Inline code in Accent (cyan)
• Markdown rendered (bold, code blocks, lists)

Tool Call Block

  ╭─ Shell: npm test ───────────────────╮
  │                                      │
  │  PASS  src/app.test.ts               │
  │    ✓ handles input (12ms)            │
  │    ✓ rejects invalid (3ms)           │
  │                                      │
  │  ✓ 2 passed                          │
  ╰──────────────────────────────────────╯

• Border color by state (blue=running, yellow=pending, gray=done)
• Tool name in border header
• Status icons inside:
  • ✓ success (green)
  • x error (red)
  • ⊷ executing (blue)
  • ? confirming (yellow)
  • o pending (muted)
  • - canceled (muted)

Permission Prompt

  ╭─ Run shell command? ────────────────╮
  │                                      │
  │  $ npm test                          │
  │                                      │
  │  [Y]es  [N]o  [A]lways              │
  ╰──────────────────────────────────────╯

• Warning (yellow) border for permission prompts
• Command preview in bold
• Options with highlighted keys

Status Text

  ⠹ Thinking... (3.2s)  (esc to cancel)

• Italic status text (Gemini uses italic for all loading text)
• Elapsed timer in parentheses, auto-updating
• (esc to cancel) hint in Muted — always visible during operations
• Gradient-colored spinner prefix

Semantic Color Token System

Gemini CLI’s theme system uses semantic tokens (not raw colors). This allows themes to be swapped while maintaining meaning:

ui.active     → running tool border
ui.focus      → focused tool border
status.ok     → success states
status.warning → pending/caution
status.error  → error states
border.default → completed/inactive
text.primary  → main text
text.secondary → dimmed text

Custom themes map these tokens to actual colors. This is why Gemini supports 15+ themes out of the box.

6. Layout & Spacing

• Min terminal width: 80
• Ideal terminal width: 120
• Padding inside blocks: 1 line top/bottom, 1 char left/right
• Gap between messages: 1 empty line
• Indent level: 2 spaces

Alignment Principles

• Left-aligned conversation flow
• Tool call blocks are full-width with rounded borders
• Brand banner centered at startup
• Status text left-aligned with timer right of text

7. Icons & Indicators

8. Animation & Motion

Gradient Spinner (33fps)

• Uses dots spinner type from cli-spinners library: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
• Spinner color cycles through a 6-color Google brand gradient at 33fps (~30ms/frame): purple → blue → cyan → green → yellow → red → purple → ...
• Implemented with tinygradient library for smooth color interpolation
• In basic terminals: falls back to static colored dots

Transitions

• No animated transitions between views
• Streaming text appears as received
• Tool call borders change color by state (blue → gray when done)

Progress

• Elapsed timer in status text: (3.2s)
• No progress bar — timer-based feedback
• Spinner for all async operations

9. Agent Prompt Guide

Quick Reference

Background: #1a1a2e  (dark blue-black)
Foreground: #e0e0e0  (light gray)
Blue:       #87afff  (primary, running tools)
Purple:     #d7afff  (secondary, brand)
Cyan:       #87d7d7  (info, code)
Green:      #d7ffd7  (success)
Yellow:     #ffffaf  (warning, pending)
Red/Pink:   #ff87af  (errors)
Gradient:   #4796E4 → #847ACE → #C3677F  (brand)
Border:     ╭─╮│╰─╯  (rounded, color by state)
Style:      colorful branded, gradient spinner, semantic border colors, polished

Example Prompts

• “Build an AI assistant CLI: Gemini style, rounded borders that change color by state (blue=running, yellow=pending, green=focused, gray=done), gradient brand spinner, polished and colorful”
• “Create a branded CLI tool: Gemini aesthetic, gradient text banner, braille dots spinner cycling through brand colors, rounded tool call blocks, ✓/x/⊷ status icons”
• “Design a conversational agent: Gemini-inspired, colorful but structured, semantic border colors, italic status text with elapsed timer, (esc to cancel) hints”

Do’s and Don’ts

Do

• Use semantic border colors — the state of a tool call should be visible from its border color
• Use the brand gradient for spinner and banner — it’s the Google signature
• Use rounded borders for all framed content
• Show elapsed time during async operations
• Use a rich set of status icons (✓ x ⊷ ? o -)

Don’t

• Don’t use the gradient everywhere — save it for brand elements and spinner
• Don’t use plain monochrome — Gemini is intentionally colorful
• Don’t use straight/heavy borders — rounded is the standard
• Don’t hide cancel hints — always show (esc to cancel) during operations
• Don’t skip the elapsed timer — users need feedback on long operations