Theming & Customization
Relevant source files
The following files were used as context for generating this wiki page:
Theming and customization in the Oh My Pi project encompass a multi-layered approach to visual presentation across Terminal User Interfaces (TUI), web exports, and agent-driven design. The system is built on a "token-first" philosophy, prioritizing reusable design tokens like colors, spacing, and typography over hardcoded values to ensure consistency across different output formats.
Sources: designer.md:18-24, template.css:6-14
TUI Theming Architecture
The TUI components utilize a structured MarkdownTheme and DefaultTextStyle to control the rendering of text and structural elements in the terminal. This system allows for granular control over how markdown tokens are translated into ANSI-styled strings.
Theme Data Structures
The core of the TUI customization is defined by interfaces that map markdown elements to styling functions.
| Interface | Purpose | Key Members |
|---|---|---|
DefaultTextStyle | Base styling for all text | color, bgColor, bold, italic, underline |
MarkdownTheme | Element-specific styling | heading, link, code, quote, listBullet, hr, symbols |
SymbolTheme | Visual character sets | Defines glyphs for tables, bullets, and horizontal rules |
Sources: markdown.ts:384-419
Component-Level Customization
The Markdown component implements a rendering pipeline that applies themes during tokenization and final assembly. It supports specialized behaviors like hex-color swatches, where a colored chip is automatically prepended to detected CSS hex codes in prose.
The diagram shows how the Markdown component processes text tokens and applies theme-specific styling before final ANSI wrapping.
Sources: markdown.ts:421-460, markdown.ts:592-620
Web & Export Theming
The web export system uses a CSS variable-based architecture to provide a "dense devtool aesthetic." Themes are derived from a set of CSS variables defined on the :root element, allowing for easy switching between light and dark modes through tinted neutrals and accent colors.
Design Tokens
Web themes rely on the following primary variables:
- Colors:
--text,--accent,--success,--error,--warning, and--muted. - Backgrounds:
--body-bg,--container-bg, and--inset-bg. - Spacing/Layout:
--sidebar-width,--radius-card, and--line-height.
Sources: template.css:6-21
Functional CSS Utilities
The export styles use color-mix extensively to generate dynamic variants like --hairline (10% text color) and --hover-wash (5% text color), ensuring that UI borders and hover states remain visually subtle regardless of the base theme.
Sources: template.css:15-20
Agent-Driven Design System
The project includes a specialized designer agent responsible for implementing and reviewing UI designs according to strict consistency guidelines.
Implementation Phases
- Token-first analysis: Scanning for existing tokens and primitives before writing code.
- Minimal System Construction: Building missing primitives (palette, type scale) before implementation.
- Composition: Extending existing primitives instead of creating one-off "div soup."
- Verification: Ensuring zero "magic numbers" and that every color/spacing value maps to a token.
Sources: designer.md:20-33
Design Constraints
The system explicitly forbids "AI Slop Patterns" to maintain professional aesthetics. Prohibited patterns include:
- Excessive glassmorphism or glow effects.
- Pure black (#000) or pure white (#fff) backgrounds; neutrals must be tinted.
- Default system fonts like Inter or Roboto; unique type scales are preferred.
- Gray text on colored backgrounds (background-tinted shades should be used instead).
Sources: designer.md:46-64
Customization Mechanisms
Rule-Based Customization
The system supports "Rules" which are local constraints that agents must follow when working in specific domains. Rules can include globs to define their scope and can be marked to "always apply."
Sources: helpers.ts:145-177, custom-system-prompt.md:32-48
Prompt Customization
Users can customize the agent's behavior through:
systemPromptCustomization: High-level overrides of the system prompt.customPrompt: Specific instructions for the current session.appendPrompt: Instructions added to the end of the context.
Sources: custom-system-prompt.md:1-7
Summary
Theming and customization in Oh My Pi are managed through a combination of structured TypeScript interfaces for terminal rendering, a robust CSS-variable system for web exports, and agent-enforced design standards. This multi-layered approach ensures that the project maintains a consistent "devtool" aesthetic across all surfaces while allowing for granular user and domain-specific overrides.
Sources: DEVELOPMENT.md:118-120, designer.md:73-77