TUI Designer - Retro/Cyberpunk Terminal UI Expert

Expert guidance for designing and implementing text-based user interfaces with authentic retro computing aesthetics: CRT monitors, phosphor glow, scanlines, and cyberpunk neon.

When to Use This Skill

Use this skill when:

• Creating terminal-style or hacker aesthetic UIs
• Implementing CRT monitor effects (scanlines, glow, barrel distortion)
• Building cyberpunk/synthwave/retrowave interfaces
• Using Tuimorphic components in React
• Implementing Metal shaders for retro effects in SwiftUI
• Designing neon glow text and UI elements
• Choosing color palettes for retro computing aesthetics
• Working with monospace fonts and box-drawing characters

Design Principles

The Retro/Cyberpunk Aesthetic

This aesthetic draws from:

• CRT monitors: Phosphor glow, scanlines, screen curvature, flicker
• Terminal interfaces: Monospace fonts, box-drawing characters, green/amber text
• Cyberpunk fiction: Neon colors, dark backgrounds, high contrast
• 1980s computing: ASCII art, limited color palettes, blocky graphics

Visual Elements Checklist

• Dark background (near-black with subtle color tint)
• Monospace typography throughout
• Box-drawing characters for borders and frames
• Neon glow on text and/or borders
• Scanline effect (subtle horizontal lines)
• Limited color palette (1-3 accent colors)
• High contrast between text and background
• Optional: CRT curvature, chromatic aberration, flicker

Quick Reference: Color Palettes

Phosphor Green (Classic Terminal)

Role	Hex	Usage
Bright	#00ff00	Primary text, highlights
Medium	#00cc00	Secondary text
Dark	#009900	Dimmed elements
Background	#001100	Main background
Deep BG	#000800	Panel backgrounds

Cyberpunk Neon

Role	Hex	Usage
Cyan	#00ffff	Primary accent
Magenta	#ff00ff	Secondary accent
Electric Blue	#0066ff	Tertiary
Hot Pink	#ff1493	Warnings
Background	#0a0a1a	Main background

Amber CRT

Role	Hex	Usage
Bright	#ffb000	Primary text
Medium	#cc8800	Secondary
Dark	#996600	Dimmed
Background	#1a1000	Main background

See color-palettes.md for complete specifications.

Typography

Recommended Fonts

Web:

font-family: 'GNU Unifont', 'IBM Plex Mono', 'JetBrains Mono',
             'SF Mono', 'Consolas', monospace;

SwiftUI:

.font(.system(size: 14, weight: .regular, design: .monospaced))

Box-Drawing Characters

Light:   ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼
Heavy:   ━ ┃ ┏ ┓ ┗ ┛ ┣ ┫ ┳ ┻ ╋
Double:  ═ ║ ╔ ╗ ╚ ╝ ╠ ╣ ╦ ╩ ╬
Rounded: ╭ ╮ ╰ ╯

See typography-guide.md for complete reference.

Copywriting

Terminal interfaces have a distinct voice: terse, technical, authoritative. Use these defaults unless the project specifies otherwise.

Core Principles

1. Terse and Direct - Every word earns its place
2. Technical Authority - The system knows what it's doing
3. Mechanical Precision - No hedging, apologies, or filler

Text Formatting

Element	Case	Example
Headers/Titles	UPPERCASE	SYSTEM STATUS
Labels	UPPERCASE	CPU USAGE:
Status indicators	UPPERCASE	ONLINE, OFFLINE
Commands/Input	lowercase	> run diagnostic
Body text	Sentence case	Connection established

Message Prefixes

[SYS] System message       [ERR] Error
[USR] User action          [WRN] Warning
[INF] Information          [NET] Network

Vocabulary Quick Reference

Action	Terminal Verbs
Start	INITIALIZE, BOOT, LAUNCH, ACTIVATE
Stop	TERMINATE, HALT, ABORT, KILL
Save	WRITE, COMMIT, STORE, PERSIST
Load	READ, FETCH, RETRIEVE, LOAD
Delete	PURGE, REMOVE, CLEAR, WIPE

State	Terminal Words
Working	PROCESSING, EXECUTING, RUNNING
Done	COMPLETE, SUCCESS, FINISHED
Failed	ERROR, FAULT, ABORTED
Ready	ONLINE, AVAILABLE, ARMED

Common Patterns

> INITIALIZING SYSTEM...
> LOADING MODULES [████████░░] 80%
> AUTHENTICATION COMPLETE
> SYSTEM READY

ERROR: ACCESS DENIED
ERR_CONNECTION_REFUSED: Timeout after 30s
WARNING: Low disk space (< 10%)

CONFIRM DELETE? [Y/N]
SELECT OPTION [1-5]:

Avoid

• "Please", "Sorry", "Oops"
• "Just", "Maybe", "Might"
• Excessive exclamation points
• Emoji (unless specifically requested)

See copywriting-guide.md for complete voice and tone reference.

---

Platform: React with Tuimorphic

Tuimorphic is a React component library providing 37 terminal-styled, accessible UI components.

Quick Start

npm install tuimorphic

import { Button, Card, Input } from 'tuimorphic';
import 'tuimorphic/styles.css';

function App() {
  return (
    <div className="theme-dark tint-green">
      <Card>
        <h1>SYSTEM ACCESS</h1>
        <Input placeholder="Enter command..." />
        <Button variant="primary">EXECUTE</Button>
      </Card>
    </div>
  );
}

Theme Configuration

Apply themes via CSS classes on a parent element:

// Dark mode with green tint
<div className="theme-dark tint-green">

// Light mode with cyan tint
<div className="theme-light tint-blue">

Available tints: tint-green, tint-blue, tint-red, tint-yellow, tint-purple, tint-orange, tint-pink

Key Components

Component	Usage
Button	Actions with variant="primary|secondary|ghost"
Input	Text input with terminal styling
Card	Container with box-drawing borders
Dialog	Modal dialogs
Menu	Dropdown menus
CodeBlock	Syntax-highlighted code
Table	Data tables
Tabs	Tabbed navigation
TreeView	File tree display

See tuimorphic-reference.md for complete API.

Adding Neon Glow

Enhance Tuimorphic with CSS glow effects:

/* Neon text glow */
.neon-text {
  color: #0ff;
  text-shadow:
    0 0 5px #fff,
    0 0 10px #fff,
    0 0 20px #0ff,
    0 0 40px #0ff,
    0 0 80px #0ff;
}

/* Neon border glow */
.neon-border {
  border-color: #0ff;
  box-shadow:
    0 0 5px #0ff,
    0 0 10px #0ff,
    inset 0 0 5px #0ff;
}

/* Flickering animation */
@keyframes flicker {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.95; }
  52% { opacity: 1; }
  54% { opacity: 0.9; }
}

.flicker {
  animation: flicker 3s infinite;
}

---

Platform: SwiftUI with Metal Shaders

iOS 17+ supports Metal shaders directly in SwiftUI via .colorEffect(), .distortionEffect(), and .layerEffect().

CRT Effect Implementation

CRT.metal:

#include <metal_stdlib>
#include <SwiftUI/SwiftUI.h>
using namespace metal;

[[stitchable]] half4 crtEffect(
    float2 position,
    SwiftUI::Layer layer,
    float time,
    float2 size,
    float scanlineIntensity,
    float distortionStrength
) {
    float2 uv = position / size;

    // Barrel distortion
    float2 center = uv - 0.5;
    float dist = length(center);
    float2 distorted = center * (1.0 + distortionStrength * dist * dist);
    float2 samplePos = (distorted + 0.5) * size;

    // Bounds check
    if (samplePos.x < 0 || samplePos.x > size.x ||
        samplePos.y < 0 || samplePos.y > size.y) {
        return half4(0, 0, 0, 1);
    }

    // Sample color
    half4 color = layer.sample(samplePos);

    // Scanlines
    float scanline = sin(position.y * 3.14159 * 2.0) * scanlineIntensity;
    color.rgb *= 1.0 - scanline;

    // Subtle color shift (chromatic aberration)
    color.r *= 1.0 + 0.02 * sin(time * 2.0);
    color.b *= 1.0 - 0.02 * sin(time * 2.0);

    // Slight flicker
    color.rgb *= 1.0 + 0.01 * sin(time * 60.0);

    return color;
}

SwiftUI View Modifier:

struct CRTEffectModifier: ViewModifier {
    @State private var startTime = Date()
    var scanlineIntensity: Float = 0.1
    var distortionStrength: Float = 0.1

    func body(content: Content) -> some View {
        TimelineView(.animation) { timeline in
            let time = Float(timeline.date.timeIntervalSince(startTime))
            GeometryReader { geo in
                content
                    .layerEffect(
                        ShaderLibrary.crtEffect(
                            .float(time),
                            .float2(geo.size),
                            .float(scanlineIntensity),
                            .float(distortionStrength)
                        ),
                        maxSampleOffset: .init(width: 10, height: 10)
                    )
            }
        }
    }
}

extension View {
    func crtEffect(
        scanlines: Float = 0.1,
        distortion: Float = 0.1
    ) -> some View {
        modifier(CRTEffectModifier(
            scanlineIntensity: scanlines,
            distortionStrength: distortion
        ))
    }
}

Usage:

Text("SYSTEM ONLINE")
    .font(.system(size: 24, weight: .bold, design: .monospaced))
    .foregroundColor(.green)
    .crtEffect(scanlines: 0.15, distortion: 0.08)

Neon Glow in SwiftUI

extension View {
    func neonGlow(color: Color, radius: CGFloat = 10) -> some View {
        self
            .shadow(color: color.opacity(0.8), radius: radius / 4)
            .shadow(color: color.opacity(0.6), radius: radius / 2)
            .shadow(color: color.opacity(0.4), radius: radius)
            .shadow(color: color.opacity(0.2), radius: radius * 2)
    }
}

// Usage
Text("NEON")
    .font(.system(size: 48, design: .monospaced))
    .foregroundColor(.cyan)
    .neonGlow(color: .cyan, radius: 15)

See metal-shaders-ios.md for complete shader code.

---

Platform: CSS/Vanilla Web

Scanlines Overlay

.crt-container {
    position: relative;
    background: #000800;
}

.crt-container::after {
    content: '';
    position: absolute;
    inset: 0;
    background: repeating-linear-gradient(
        0deg,
        rgba(0, 0, 0, 0.15),
        rgba(0, 0, 0, 0.15) 1px,
        transparent 1px,
        transparent 2px
    );
    pointer-events: none;
}

Neon Text Effect

.neon-text {
    color: #0ff;
    text-shadow:
        /* White core */
        0 0 5px #fff,
        0 0 10px #fff,
        /* Colored glow layers */
        0 0 20px #0ff,
        0 0 30px #0ff,
        0 0 40px #0ff,
        0 0 55px #0ff,
        0 0 75px #0ff;
}

CRT Curvature (CSS Transform)

.crt-screen {
    border-radius: 20px;
    transform: perspective(1000px) rotateX(2deg);
    box-shadow:
        inset 0 0 50px rgba(0, 255, 0, 0.1),
        0 0 20px rgba(0, 255, 0, 0.2);
}

WebGL CRT with CRTFilter.js

<script type="module">
import { CRTFilterWebGL } from 'crtfilter';

const canvas = document.getElementById('crt-canvas');
const crt = new CRTFilterWebGL(canvas, {
    scanlineIntensity: 0.15,
    glowBloom: 0.3,
    chromaticAberration: 0.002,
    barrelDistortion: 0.1,
    staticNoise: 0.03,
    flicker: true,
    retraceLines: true
});

crt.start();
</script>

See crt-effects-web.md for complete techniques.

---

Effect Patterns

Scanlines

Platform	Implementation
CSS	repeating-linear-gradient pseudo-element
SwiftUI	Metal shader with sin(position.y * frequency)
WebGL	Fragment shader brightness modulation

Bloom/Glow

Platform	Implementation
CSS	Multiple text-shadow with increasing blur
SwiftUI	Multiple .shadow() modifiers
WebGL	Gaussian blur pass + additive blend
Three.js	UnrealBloomPass with luminanceThreshold

Chromatic Aberration

Platform	Implementation
CSS	Three overlapping elements with color channel offset
SwiftUI	Sample texture at offset positions per RGB channel
WebGL	Sample UV with slight offset per channel

Flicker

Platform	Implementation
CSS	@keyframes animation varying opacity 0.9-1.0
SwiftUI	Timer-driven opacity or shader time-based
WebGL	Time-based noise multiplier

---

Performance Considerations

CSS Effects

• box-shadow and text-shadow are GPU-accelerated but expensive with many layers
• Limit to 4-5 shadow layers for glow effects
• Use will-change: transform for animated elements
• Consider prefers-reduced-motion media query

SwiftUI/Metal

• Metal shaders run at 60-120fps on all devices supporting iOS 17+
• .layerEffect() processes every pixel - keep shaders simple
• Pre-compile shaders with .compile() (iOS 18+)
• Test on older devices (A12 minimum for iOS 17)

WebGL

• CRTFilter.js uses hardware acceleration, minimal performance impact
• Bloom effects in Three.js require render-to-texture passes
• Consider lower resolution render targets for mobile

General

• Reduce effect intensity on mobile devices
• Provide option to disable effects for accessibility
• Profile with actual content, not just empty screens

---

Templates

Ready-to-use starter files:

• react-tuimorphic-starter.tsx - React app with Tuimorphic
• swiftui-crt-view.swift - SwiftUI view with CRT effect
• crt-shader.metal - Complete Metal shader
• neon-glow.css - CSS neon effects

---

Common Pitfalls

This section documents real failure modes and edge cases that break TUI implementations. These are non-obvious gotchas discovered through practical use across platforms.

Terminal Compatibility Issues

Problem: Escape sequences vary across terminal emulators. What works in iTerm2 may fail in older xterm, SSH terminals, or Windows Terminal.

Common failures:

• 256-color vs ANSI: Terminals support different color depths. Code using #rgb hex colors works in modern terminals but falls back to 16-color ANSI on older systems.
• Reset sequences: Forgetting to reset text attributes (\x1b[0m or \x1b[m) can poison the terminal state for subsequent output.
• Unicode box-drawing on Windows: Windows PowerShell/Terminal may not render ─ │ ┌ ┐ correctly. Test on Windows before shipping.
• VT100 incompleteness: SSH to older Linux systems often hits VT100-only support. Box-drawing characters render as gibberish.

Prevention:

• Test on target terminals: iTerm2, Terminal.app, Windows Terminal, SSH Linux, Alacritty
• Fall back to ASCII when box-drawing fails: use +, -, | as fallback
• Always reset attributes after styled text: \x1b[0m is your friend
• Detect terminal capability: Check TERM env var (TERM=xterm-256color vs TERM=xterm)

Example safe wrapper:

const supportsUnicode = process.env.TERM && process.env.TERM.includes('256');
const border = supportsUnicode ? '─' : '-';

Layout Breaks on Resize

Problem: Fixed-width layouts collapse when terminal resizes. Common in web-based TUI where aspect ratio changes unexpectedly.

Common failures:

• Hardcoded line widths: A centered header assuming 80-column width breaks on a 60-column terminal.
• Overflow hidden without truncation: Content that's 100% width + padding exceeds container, causing text to spill or wrap unexpectedly.
• Aspect ratio assumptions: Scanline overlays, CRT curves assume 16:9. On ultra-wide or mobile, artifacts become obvious.
• Grid layouts with fixed items: Using display: grid with grid-template-columns: 100px 200px 100px fails to adapt to small screens.

Prevention:

• Use viewport-relative units: vw, vh, or calc(100% - Xpx)
• Implement text truncation with ellipsis: overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
• Test at: 120 columns, 80 columns, 40 columns (mobile), ultra-wide
• For scanline effects, use percentage-based frequency that scales with viewport
• Use CSS @media or JS ResizeObserver to adapt layout dynamically

Scanline example that fails:

/* ❌ Breaks on narrow screens */
background: repeating-linear-gradient(0deg, transparent, transparent 20px, black 20px, black 21px);

Better approach:

/* ✅ Scales with viewport height */
background: repeating-linear-gradient(0deg, transparent, transparent calc(2% of height), black calc(2% of height), black calc(2% of height + 1px));

Input Handling Edge Cases

Problem: User input isn't just alphanumeric. Real-world input includes multi-byte UTF-8, special keys, paste buffers, and autocomplete.

Common failures:

• UTF-8 character counting: JavaScript's string.length counts UTF-16 code units, not characters. A 4-byte emoji 🎮 has length: 2, breaking cursor positioning and validation.
• Paste buffer handling: Users paste large blocks of text. Input handlers without streaming cause UI to freeze.
• Arrow keys vs WASD: Terminal-based games assume WASD but users expect arrow keys. Missing support = bad UX.
• Special keys lost in translation: Ctrl+C, Ctrl+Z, Tab work differently across platforms. SSH terminals lose some meta-keys.
• IME composition: Input Method Engine (for Chinese, Japanese, Korean) sends partial characters before final composition. Validating on every keystroke breaks IME input.

Prevention:

• Use grapheme-aware libraries: Intl.Segmenter (modern), or graphemesplitter npm package
• Implement paste as multi-character stream, not a single event
• Support both arrow keys AND WASD for navigation
• Handle IME: validate only on final compositionend, not compositionupdate
• Test on macOS (Command key), Windows (Alt), Linux (various WM behavior)

Correct UTF-8 cursor positioning:

// ❌ Wrong: counts UTF-16 code units
const cursorPos = input.value.length;  // "🎮🎮" = length: 4

// ✅ Correct: counts grapheme clusters
const segmenter = new Intl.Segmenter();
const cursorPos = [...segmenter.segment(input.value)].length;  // "🎮🎮" = 2

Performance Issues

Problem: TUI effects (scanlines, glow, flicker) are expensive. Naive implementations cause jank and CPU/battery drain.

Common failures:

• Continuous redraws: Updating DOM every frame via JS (not GPU) causes 60+ reflows per second. Leads to choppy animation, 100%+ CPU.
• Too many text-shadow layers: Each text-shadow: 0 0 5px, 0 0 10px, 0 0 20px, ... requires a separate GPU pass. 10+ shadows = measurable lag.
• Flickering at high frequency: setInterval(..., 16ms) for flicker ties to animation frame time, causing stutter if main thread is busy.
• Scanline overlay recompute: Recalculating repeating-linear-gradient on every resize (without debounce) causes jank.
• WebGL without throttling: Full-screen CRT shaders running at 120fps on low-end mobile = instant battery drain.

Prevention:

• Use CSS @keyframes for continuous effects (GPU-accelerated)
• Limit neon glow to 3-4 text-shadow layers; test on mobile
• Debounce resize handlers: ResizeObserver with throttle, or window.requestAnimationFrame
• Use will-change: transform, filter sparingly on elements that animate
• Provide reduced-motion option: prefers-reduced-motion: reduce
• On mobile, detect CPU capacity: throttle effects on low-power devices

Flicker that performs well:

/* ✅ GPU-accelerated, smooth */
@keyframes flicker {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.95; }
}
.flicker { animation: flicker 3s infinite; }

Flicker that causes jank:

// ❌ Main thread blocked, stutter
setInterval(() => {
  element.style.opacity = Math.random() > 0.5 ? 1 : 0.9;
}, 50);

Accessibility Gaps

Problem: Terminal UIs often ignore accessibility. Screen readers, keyboard navigation, color contrast all suffer.

Common failures:

• No keyboard navigation: Clickable elements only respond to mouse. Screen reader users and keyboard-only users are blocked.
• Color-only status indicators: Red text for error, green for success. Colorblind users (8% of males, 0.5% of females) can't distinguish.
• Missing ARIA labels: Screen readers announce "Button" instead of "Execute command". Confusing for blind users.
• Fixed-size text: Neon glow at 48px looks cool but breaks at 14px for visually impaired users. No zoom support = inaccessible.
• No focus indicators: After Tab-navigating to a button, there's no visible focus ring. Users lose their place.
• Animated elements without pause: Flicker and scanlines can trigger photosensitive epilepsy. Missing prefers-reduced-motion support = legal/safety risk.

Prevention:

• Implement full keyboard navigation: Tab/Shift+Tab, Enter to activate, Arrow keys for lists
• Test with screen reader: VoiceOver (macOS), NVDA (Windows), JAWS
• Add ARIA labels: aria-label="Start system", aria-describedby="help-text"
• Ensure 4.5:1 contrast ratio for text (WCAG AA standard)
• Provide prefers-reduced-motion alternative: disable flicker, scanlines, animations
• Focus indicators: :focus { outline: 2px solid #0ff; } is mandatory

Accessible neon button:

<button
  aria-label="Execute diagnostic"
  className="neon-button"
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  EXECUTE
</button>

<style>
  .neon-button:focus {
    outline: 2px solid #0ff;
    outline-offset: 2px;
  }
  
  @media (prefers-reduced-motion: reduce) {
    .neon-button {
      text-shadow: none; /* Remove glow */
      animation: none;   /* Remove flicker */
    }
  }
</style>

Terminal Emulator Differences

Quick reference for platform-specific behaviors:

Emulator	Notable Quirks	Fix
iTerm2 (macOS)	Renders all Unicode correctly; true-color support	None needed
Terminal.app (macOS)	Limited color palette; older xterm behavior	Test with 256-color mode
Alacritty	Ultra-fast; true-color; may not render some Unicode	Works reliably if iTerm2 works
Windows Terminal	Supports true-color; WSL integration works well	None needed for modern code
PowerShell	Old versions render box-drawing as ?; use fallback	Check $PSVersionTable
SSH/xterm	VT100 only; no true-color; no mouse events	Fall back to ASCII + ANSI colors
Tmux	Passthrough mode required for true-color: set -g default-terminal "tmux-256color"	Configure tmux.conf
Screen	Even older terminal support; avoid fancy effects	Use ASCII-only mode

Platform detection example:

if [[ "$TERM" == "xterm" ]]; then
  # Old terminal: use ASCII
  BORDER="+"
  COLORS="ANSI"
elif [[ "$TERM" == *"256color"* ]]; then
  # Modern terminal: use box-drawing + 256 colors
  BORDER="─"
  COLORS="256"
else
  # Unknown: default to safe
  BORDER="+"
  COLORS="ANSI"
fi

When CRT Effects Backfire

Problem: Scanlines, glow, and distortion look cool in mockups but cause problems in practice.

Common failures:

• Scanlines reduce readability: Fine horizontal lines over text make it harder to read, especially on mobile or at distance. People with low vision can't read it.
• Glow hides text: Heavy neon glow (text-shadow with 10+ layers) blurs text edges, reducing legibility.
• Barrel distortion breaks alignment: CRT curvature looks authentic but makes content appear misaligned. Users think UI is broken.
• Flicker induces motion sickness: Subtle flicker causes nausea in some users. Photosensitive epilepsy is a real safety concern.

Prevention:

• Use subtle scanlines: 10-15% opacity, visible but not interfering with text
• Limit glow intensity: if glow radius > 20px, text becomes unreadable
• Distortion is decorative only: never use it for critical layout
• Always provide prefers-reduced-motion escape hatch
• Test with actual users: "Can you read this comfortably?"

---

Resources

Libraries

• Tuimorphic - React terminal UI components
• Inferno - Metal shaders for SwiftUI
• CRTFilter.js - WebGL CRT effects
• @react-three/postprocessing - React Three.js effects

Documentation

• SwiftUI Metal Shaders
• CSS text-shadow

Inspiration

• SRCL / Sacred Computer - Design influence for Tuimorphic
• Cool Retro Term - Terminal emulator with CRT effects