procedure-cli 1.0.2 → 1.0.3

package/templates/ink-tui/INK-TUI-UI-UX-GUIDELINE.md

@@ -0,0 +1,1070 @@
+# B3AWESOME CLI App UI/UX Guideline
+
+A comprehensive design system and UI/UX specification for building terminal-based CLI applications using **React + Ink.js**. This document captures every visual pattern, interaction model, and component specification so that new projects can reproduce the same polished CLI experience.
+
+---
+
+## Table of Contents
+
+1. [Design Philosophy](#1-design-philosophy)
+2. [Color System & Theme Architecture](#2-color-system--theme-architecture)
+3. [Typography & Text Hierarchy](#3-typography--text-hierarchy)
+4. [Layout System — The Gutter Pattern](#4-layout-system--the-gutter-pattern)
+5. [Screen Anatomy](#5-screen-anatomy)
+6. [Navigation Patterns](#6-navigation-patterns)
+7. [Wizard & Timeline Pattern](#7-wizard--timeline-pattern)
+8. [Form Patterns](#8-form-patterns)
+9. [Component Library](#9-component-library)
+10. [Welcome & Instruction Pattern](#10-welcome--instruction-pattern)
+11. [Confirmation & Destructive Actions](#11-confirmation--destructive-actions)
+12. [Empty & Error States](#12-empty--error-states)
+13. [ASCII Art Elements](#13-ascii-art-elements)
+14. [Theme Switching (Future)](#14-theme-switching-future)
+15. [Quick-Start Checklist](#15-quick-start-checklist)
+
+---
+
+## 1. Design Philosophy
+
+### Core Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Guided, not guessed** | Every screen tells the user what it does and what to do next. No blank screens, no mystery options. |
+| **Vertical rhythm** | Content flows top-to-bottom in a single column. The gutter line (`│`) creates visual continuity. |
+| **Progressive disclosure** | Show only what's needed at each step. Wizards reveal one step at a time. |
+| **Forgiving navigation** | Shift+Tab goes back. Esc returns to menu. Data is preserved when navigating backward. |
+| **Config-driven** | Criteria, labels, teams, titles, levels — all configurable. The UI adapts to config, not the reverse. |
+| **Minimal footprint** | No external UI libraries beyond Ink.js core. Every component is purpose-built and lightweight. |
+
+### Interaction Model
+
+```
+User sees Heading → reads Instruction → scans CTAs → selects action → enters content area
+```
+
+The user should **never** need to guess what a screen does or where they are in a workflow.
+
+---
+
+## 2. Color System & Theme Architecture
+
+### Semantic Color Roles
+
+The color system is **semantic** — components reference roles, not hex values. This enables runtime theme switching.
+
+| Role | Token | Purpose | Usage |
+|------|-------|---------|-------|
+| **brand** | `C.mauve` | Brand identity, active focus, cursor highlight | Banner, active step indicator, active select item (`❯`) |
+| **heading** | `C.sapphire` | Screen titles, section headers | `<Text color={C.sapphire} bold>` |
+| **success** | `C.green` | Completed steps, confirmed values, save success | Step indicator `◇`, welcome message, saved total |
+| **warning** | `C.peach` | Warnings, caution states | Warning messages (rarely used) |
+| **error** | `C.red` | Errors, destructive confirmations | Validation errors, delete confirmations |
+| **highlight** | `C.yellow` | In-progress input, typing indicator | Currently active TextInput value |
+| **accent** | `C.teal` | Secondary accent | Custom option indicator in multi-select |
+| **muted** | `C.overlay1` | Gutter lines, hints, instructions, dim labels | `┌ │ └`, descriptions, navigation hints |
+| **dimmed** | `C.overlay0` | Pending/inactive steps | Pending step indicator `○`, "No notes" text |
+| **input-active** | `C.inputing` | Value currently being typed | TextInput active value |
+| **input-confirmed** | `C.inputed` | Value already confirmed | Completed step summaries, confirmed field values |
+| **label** | `C.label` | General text labels, content text | Field labels, employee names, note content |
+
+### Built-in Theme Definitions
+
+Four themes ship pre-installed. Each maps the same semantic roles to theme-specific hex values.
+
+#### Catppuccin Mocha (Dark) — Default
+
+```typescript
+export const catppuccinMocha = {
+  name: 'catppuccin-mocha',
+  type: 'dark',
+  colors: {
+    mauve:    '#cba6f7',  // Catppuccin Mocha Mauve
+    green:    '#a6e3a1',  // Catppuccin Mocha Green
+    yellow:   '#f9e2af',  // Catppuccin Mocha Yellow
+    sapphire: '#74c7ec',  // Catppuccin Mocha Sapphire
+    teal:     '#94e2d5',  // Catppuccin Mocha Teal
+    red:      '#f38ba8',  // Catppuccin Mocha Red
+    peach:    '#fab387',  // Catppuccin Mocha Peach
+    overlay1: '#7f849c',  // Catppuccin Mocha Overlay1
+    overlay0: '#6c7086',  // Catppuccin Mocha Overlay0
+    inputing: '#f9e2af',  // = yellow
+    inputed:  '#a6e3a1',  // = green
+    label:    '#cdd6f4',  // Catppuccin Mocha Text
+  },
+} as const;
+```
+
+#### Catppuccin Latte (Light)
+
+```typescript
+export const catppuccinLatte = {
+  name: 'catppuccin-latte',
+  type: 'light',
+  colors: {
+    mauve:    '#8839ef',  // Catppuccin Latte Mauve
+    green:    '#40a02b',  // Catppuccin Latte Green
+    yellow:   '#df8e1d',  // Catppuccin Latte Yellow
+    sapphire: '#209fb5',  // Catppuccin Latte Sapphire
+    teal:     '#179299',  // Catppuccin Latte Teal
+    red:      '#d20f39',  // Catppuccin Latte Red
+    peach:    '#fe640b',  // Catppuccin Latte Peach
+    overlay1: '#8c8fa1',  // Catppuccin Latte Overlay1
+    overlay0: '#9ca0b0',  // Catppuccin Latte Overlay0
+    inputing: '#df8e1d',  // = yellow
+    inputed:  '#40a02b',  // = green
+    label:    '#4c4f69',  // Catppuccin Latte Text
+  },
+} as const;
+```
+
+#### Tokyo Night (Dark)
+
+```typescript
+export const tokyoNightDark = {
+  name: 'tokyonight-dark',
+  type: 'dark',
+  colors: {
+    mauve:    '#bb9af7',  // Tokyo Night Purple
+    green:    '#9ece6a',  // Tokyo Night Green
+    yellow:   '#e0af68',  // Tokyo Night Yellow
+    sapphire: '#7aa2f7',  // Tokyo Night Blue
+    teal:     '#73daca',  // Tokyo Night Teal
+    red:      '#f7768e',  // Tokyo Night Red
+    peach:    '#ff9e64',  // Tokyo Night Orange
+    overlay1: '#565f89',  // Tokyo Night Comment
+    overlay0: '#414868',  // Tokyo Night Dark3
+    inputing: '#e0af68',  // = yellow
+    inputed:  '#9ece6a',  // = green
+    label:    '#c0caf5',  // Tokyo Night Foreground
+  },
+} as const;
+```
+
+#### Tokyo Night Light
+
+```typescript
+export const tokyoNightLight = {
+  name: 'tokyonight-light',
+  type: 'light',
+  colors: {
+    mauve:    '#7847bd',  // Tokyo Night Light Purple
+    green:    '#485e30',  // Tokyo Night Light Green
+    yellow:   '#8f5e15',  // Tokyo Night Light Yellow
+    sapphire: '#2e7de9',  // Tokyo Night Light Blue
+    teal:     '#387068',  // Tokyo Night Light Teal
+    red:      '#f52a65',  // Tokyo Night Light Red
+    peach:    '#b15c00',  // Tokyo Night Light Orange
+    overlay1: '#9699a3',  // Tokyo Night Light Comment
+    overlay0: '#b4b5b9',  // Tokyo Night Light Dark3
+    inputing: '#8f5e15',  // = yellow
+    inputed:  '#485e30',  // = green
+    label:    '#3760bf',  // Tokyo Night Light Foreground
+  },
+} as const;
+```
+
+### Theme File Structure
+
+```
+src/lib/
+├── theme.ts              # Exports `C` — the active color tokens
+└── themes/
+    ├── index.ts          # Theme registry, loader, switcher
+    ├── catppuccin-mocha.ts
+    ├── catppuccin-latte.ts
+    ├── tokyonight-dark.ts
+    └── tokyonight-light.ts
+```
+
+### Theme Type Contract
+
+```typescript
+export interface ThemeDefinition {
+  name: string;
+  type: 'dark' | 'light';
+  colors: {
+    mauve: string;
+    green: string;
+    yellow: string;
+    sapphire: string;
+    teal: string;
+    red: string;
+    peach: string;
+    overlay1: string;
+    overlay0: string;
+    inputing: string;
+    inputed: string;
+    label: string;
+  };
+}
+```
+
+### Runtime Theme Switching
+
+```bash
+# Set theme via CLI command
+cli-name theme catppuccin-mocha      # default
+cli-name theme catppuccin-latte
+cli-name theme tokyonight-dark
+cli-name theme tokyonight-light
+
+# List available themes
+cli-name theme --list
+```
+
+**Implementation pattern:**
+1. Theme preference stored in config file (e.g., `data/config.json` → `{ "theme": "catppuccin-mocha" }`)
+2. On startup, `theme.ts` reads config → loads matching theme definition → exports `C` object
+3. All components import `C` from `theme.ts` — never reference hex values directly
+4. Theme switch updates config file → next render uses new colors
+
+---
+
+## 3. Typography & Text Hierarchy
+
+Terminal UI has no font sizes, so hierarchy is conveyed through **color**, **boldness**, and **position**.
+
+### Text Levels
+
+| Level | Style | Token | Example |
+|-------|-------|-------|---------|
+| **Banner** | Bold, brand color | `C.mauve` | ASCII art app name |
+| **Screen Heading** | Bold, heading color | `C.sapphire bold` | `Main Menu`, `New Assessment` |
+| **Screen Instruction** | Normal, muted | `C.overlay1` | `Follow each step to record an employee evaluation.` |
+| **Section Header** | Bold, heading color | `C.sapphire bold` | `Technical (50%)` within compare |
+| **Field Label** | Normal, muted | `C.overlay1` | `Name:`, `Team:`, `Scores:` |
+| **Field Value** | Normal or bold, label color | `C.label` or `C.inputed` | Employee name, confirmed input |
+| **Active Input** | Yellow/highlight | `C.inputing` | Text currently being typed |
+| **Confirmed Input** | Green/success | `C.inputed` | Completed step summary |
+| **Hint Text** | Normal, muted | `C.overlay1` | `Shift+Tab to go back`, `↑↓ move, enter select` |
+| **Error Text** | Normal, error color | `C.red` | `Name is required` |
+| **Dimmed Text** | Normal, dimmed | `C.overlay0` | Pending step labels, `No notes` |
+
+### Text Rules
+
+- **Headings** are always the first line of a screen, left-aligned, no gutter prefix
+- **Instructions** appear directly below the heading, same alignment, muted color, no bold
+- **Labels** use colon suffix: `Name: `, `Team: `, `Score: `
+- **Values** follow labels on the same line, using `C.label` or `C.inputed`
+- **Hints** appear below input areas, always `C.overlay1`
+- **Never** use ALL CAPS for emphasis — use bold + color instead
+
+---
+
+## 4. Layout System — The Gutter Pattern
+
+The gutter creates a continuous vertical line that visually groups related content, similar to a card or container in graphical UIs.
+
+### Gutter Characters
+
+```
+┌          ← Opening corner (start of content block)
+│  content ← Gutter line with 2-space indent after pipe
+│          ← Empty gutter line (spacer)
+└          ← Closing corner (end of content block)
+```
+
+### GutterLine Component
+
+```tsx
+// Every line inside a gutter block uses this component
+export function GutterLine({ children }: { children?: React.ReactNode }) {
+  return (
+    <Box flexDirection="row">
+      <Text color={C.overlay1}>{"│  "}</Text>
+      {children}
+    </Box>
+  );
+}
+```
+
+**Rules:**
+- Everything between `┌` and `└` uses `GutterLine` for content
+- `GutterLine` with no children renders an empty spacer line (`│`)
+- The gutter prefix is always `│` + 2 spaces, colored `C.overlay1`
+- CTAs (GutteredSelect) render their own gutter prefix internally — do not wrap in GutterLine
+- `┌` and `└` are standalone `<Text>` elements, not inside GutterLine
+
+### Nesting Pattern
+
+Gutter blocks do **not** nest. Each screen/view has exactly one gutter block.
+
+```
+Heading                    ← outside gutter
+Instruction                ← outside gutter
+┌                          ← gutter start
+│  Welcome message         ← GutterLine
+│  Instruction line 1      ← GutterLine
+│                          ← GutterLine spacer
+│  ❯ Option 1              ← GutteredSelect (internal gutter)
+│    Option 2              ← GutteredSelect (internal gutter)
+│    ↑↓ move, enter select ← GutteredSelect hint (internal gutter)
+└                          ← gutter end
+```
+
+---
+
+## 5. Screen Anatomy
+
+Every screen follows this consistent structure:
+
+```
+┌─────────────────────────────────────────────────┐
+│  Heading          (C.sapphire, bold)            │ ← 1. Screen title
+│  Instruction      (C.overlay1)                  │ ← 2. One-line description
+│  ┌                                              │ ← 3. Gutter open
+│  │  Context info  (C.overlay1 labels)           │ ← 4. Contextual data
+│  │                                              │ ← 5. Spacer
+│  │  ❯ Action 1   (GutteredSelect)              │ ← 6. CTAs
+│  │    Action 2                                  │
+│  │    ↑↓ move, enter select                     │
+│  └                                              │ ← 7. Gutter close
+└─────────────────────────────────────────────────┘
+```
+
+### Screen Types
+
+#### 1. Menu Screen (Main Menu, Sub-menus)
+
+```
+Heading
+┌
+│  Welcome / context info
+│
+│  ❯ CTA options...
+│    ↑↓ move, enter select
+└
+```
+
+- Welcome message or context above CTAs inside gutter
+- Always includes a "Back" option as last CTA
+
+#### 2. List Screen (View Employees, Search Results)
+
+```
+Heading
+Instruction
+┌
+│  Count info (e.g., "5 employees")
+│  ❯ Item 1 — description
+│    Item 2 — description
+│    Back to Menu
+│    ↑↓ move, enter select
+└
+```
+
+- Count summary before items
+- Scrollable with `maxVisible` prop
+- Back option at bottom of list
+
+#### 3. Detail Screen (Employee Detail)
+
+```
+Heading
+┌
+│  Name (bold)
+│  Label: Value
+│  Label: Value
+│
+│  Section data...
+│
+│  ❯ Action options...
+│    ↑↓ move, enter select
+└
+```
+
+- Read-only info block at top
+- Actions at bottom
+
+#### 4. Wizard Screen (New Assessment)
+
+```
+Heading
+Instruction
+┌
+◇  Step 1 (completed)
+│  Summary of step 1
+│
+◆  Step 2 (active)
+│  [Active step content — forms, selects]
+│
+○  Step 3 (pending)
+│
+○  Step 4 (pending)
+└
+```
+
+- Uses Timeline component with StepIndicator
+- One step active at a time
+- Completed steps show summaries
+
+#### 5. Confirmation Screen
+
+```
+Heading
+┌
+│  Warning/summary text
+│  Detail text
+│  ❯ Cancel (safe option first)
+│    Destructive action
+│    ↑↓ move, enter select
+└
+```
+
+- Safe option (Cancel) always listed first
+- Destructive option uses red text or clear labeling
+
+---
+
+## 6. Navigation Patterns
+
+### Global Navigation
+
+| Key | Context | Action |
+|-----|---------|--------|
+| `Esc` | Any screen except menu | Return to Main Menu |
+| `↑` / `↓` | GutteredSelect active | Move selection cursor |
+| `Enter` | GutteredSelect active | Confirm selection |
+| `Space` | GutteredMultiSelect active | Toggle item |
+| `Shift+Tab` | Wizard step / Form field | Go back to previous field/step |
+
+### Back Navigation Strategy
+
+Every view must have a **visible** way to go back:
+
+1. **Wizard steps**: Shift+Tab navigates to previous step/field. Hint text shows `Shift+Tab to go back`.
+2. **List/Menu screens**: Last CTA option is always `Back to Menu` / `Back to List` / `Back to Detail`.
+3. **Global**: Esc returns to Main Menu from any screen.
+
+### Shift+Tab Implementation
+
+```tsx
+useInput((_input, key) => {
+  if (!(key.shift && key.tab)) return;
+  // Navigate to previous phase, preserving form data
+  switch (phase) {
+    case 'field-2': setPhase('field-1'); break;
+    case 'field-3': setPhase('field-2'); break;
+    // ...
+  }
+});
+```
+
+**Rules:**
+- Form data is **preserved** when going back — never clear on Shift+Tab
+- Clear only the error state when going back
+- Sub-phases (e.g., `team-custom`) go back to their parent phase (`team`)
+
+---
+
+## 7. Wizard & Timeline Pattern
+
+### Timeline Component
+
+The Timeline renders a vertical wizard with step indicators and a continuous gutter line.
+
+```
+┌
+◇  Employee           ← completed (green diamond outline)
+│  John Doe — Senior  ← summary (green text)
+│
+◆  Interviewer        ← active (animated purple diamond)
+│  [form content]     ← active step content
+│
+○  Scores             ← pending (dim circle)
+│
+○  Notes              ← pending
+└
+```
+
+### Step Indicators
+
+| Status | Symbol | Animation | Color |
+|--------|--------|-----------|-------|
+| **Completed** | `◇` | None | `C.green` |
+| **Active** | `◆` → `◈` → `◇` → `◈` | 350ms cycle | `C.mauve` (bold) |
+| **Pending** | `○` | None | `C.overlay0` |
+
+### Step State Machine
+
+```
+pending → active → completed
+```
+
+- Only one step is active at a time
+- `currentStep` index controls which step is active
+- Steps before `currentStep` are completed; steps after are pending
+- Each step component calls `onComplete(data)` which advances `currentStep`
+
+### Summary Display
+
+When a step is completed, its summary appears below the indicator:
+
+```
+◇  Scores
+│  Tech: 4 | Eff: 3 | Adapt: 5 = 3.90
+```
+
+Summary is computed by a `getSummary(stepIndex)` function in the parent screen.
+
+---
+
+## 8. Form Patterns
+
+### TextInput
+
+```
+│  Field Label:         ← GutterLine with bold text
+│  [input value]        ← GutterLine with TextInput
+│  Error message        ← GutterLine with C.red (conditional)
+│  Hint text            ← GutterLine with C.overlay1
+```
+
+**Props pattern:**
+```tsx
+<GutterLine><Text bold>Employee Name:</Text></GutterLine>
+<GutterLine>
+  <TextInput
+    placeholder="Full name (required)"
+    defaultValue={form.name}
+    onSubmit={(val) => { /* validate and advance */ }}
+  />
+</GutterLine>
+{error && <GutterLine><Text color={C.red}>{error}</Text></GutterLine>}
+<GutterLine><Text color={C.overlay1}>Shift+Tab to go back</Text></GutterLine>
+```
+
+### GutteredSelect (Single Select)
+
+```
+│  ❯ Option 1 — description    ← active item (C.mauve, bold)
+│    Option 2 — description    ← inactive item
+│    Option 3 — description
+│    ↑↓ move, enter select     ← hint
+```
+
+**Every option should have a `description` prop** for context.
+
+**Scrolling**: When options exceed `maxVisible` (default 5), shows `↑ more` / `↓ more` indicators.
+
+### GutteredMultiSelect
+
+```
+│  ❯ ● Item 1 — description   ← selected (C.green dot)
+│    ○ Item 2 — description   ← unselected (C.overlay0 dot)
+│    ● Item 3 — description
+│    ↑↓ move, space toggle, enter confirm
+│  Selected: Item 1, Item 3
+```
+
+**Features:**
+- `●` for selected, `○` for unselected
+- Optional `allowCustom` for "Other (type custom)" option
+- Selected items shown at bottom as comma-separated list
+
+### Validation Pattern
+
+```tsx
+onSubmit={(val) => {
+  if (!validateRequired(val)) {
+    setError('Name is required');
+    return;  // Don't advance
+  }
+  setError('');
+  setForm({ ...form, name: val });
+  setPhase('next-field');
+}}
+```
+
+- Validate on submit, not on change
+- Show error below input in `C.red`
+- Clear error on successful validation or Shift+Tab
+
+### Optional Fields
+
+```
+│  Current Level:
+│  [input]
+│  Optional — press enter to skip · Shift+Tab to go back
+```
+
+- Hint explicitly states "Optional — press enter to skip"
+- Empty submit = `null` value
+
+---
+
+## 9. Component Library
+
+### Banner
+
+ASCII art header at the top of the application. Displayed once, always visible.
+
+```
+█▀▀ █▀█ █▀▄▀█ █▀█ █▀▀ ▀█▀ █▀▀ █▀█ █▀▀ █▄█
+█   █ █ █ ▀ █ █▀▀ █▀▀  █  █▀▀ █ █ █   ░█░
+▀▀▀ ▀▀▀ ▀   ▀ ▀   ▀▀▀  ▀  ▀▀▀ ▀ ▀ ▀▀▀ ░▀░
+App Subtitle
+────────────────────────────────────────────────
+```
+
+- Banner text: `C.mauve`
+- Subtitle: default text color
+- Separator: `─` repeated, `C.overlay1`
+- `marginBottom={0}` — spacing handled by parent
+
+### Timeline
+
+Vertical wizard container. Wraps step indicators + active step content.
+
+```tsx
+<Timeline steps={timelineSteps}>
+  {renderActiveStep()}
+</Timeline>
+```
+
+- `steps: TimelineStep[]` — name, status, summary
+- `children` — rendered inline under the active step
+- Handles `┌` / `└` corners and `│` spacers between steps
+
+### GutterLine
+
+Single line within a gutter block.
+
+```tsx
+<GutterLine>
+  <Text color={C.overlay1}>Label: </Text>
+  <Text color={C.label}>Value</Text>
+</GutterLine>
+```
+
+- Prefix: `│` + 2 spaces (`C.overlay1`)
+- Empty `<GutterLine />` = spacer line
+
+### GutteredSelect
+
+Custom single-select with gutter integration.
+
+```tsx
+<GutteredSelect
+  options={[
+    { label: 'Option 1', value: 'opt1', description: 'What this does' },
+    { label: 'Back', value: 'back', description: 'Return to previous screen' },
+  ]}
+  onChange={(val) => handleSelect(val)}
+  maxVisible={5}
+/>
+```
+
+- Renders own gutter prefix
+- Active item: `❯` in `C.mauve`
+- Scroll indicators when items exceed `maxVisible`
+- ANSI input normalization for deterministic key handling
+
+### GutteredMultiSelect
+
+Multi-select variant with space-to-toggle and enter-to-confirm.
+
+```tsx
+<GutteredMultiSelect
+  options={options}
+  onSubmit={(selectedIds) => handleSelection(selectedIds)}
+  allowCustom={true}
+  customPlaceholder="Type custom values"
+/>
+```
+
+### StepIndicator
+
+Animated step status indicator for timeline.
+
+```tsx
+<StepIndicator status="active" label="Scores" />
+```
+
+- `completed`: `◇` green + label in `C.label`
+- `active`: animated `◆◈◇◈` at 350ms in `C.mauve` + bold label
+- `pending`: `○` in `C.overlay0` + dim label
+
+---
+
+## 10. Welcome & Instruction Pattern
+
+### Main Menu Welcome
+
+Inside the gutter block, above CTAs:
+
+```
+Main Menu
+┌
+│  Welcome to [App Name]!          ← C.green, bold, GutterLine
+│  First line of description       ← C.overlay1, GutterLine
+│  Second line of description      ← C.overlay1, GutterLine
+│                                  ← GutterLine spacer
+│  ❯ First action                  ← CTAs start here
+│    Second action
+└
+```
+
+**Rules:**
+- Welcome line uses `C.green` bold
+- Description lines use `C.overlay1`
+- One empty GutterLine spacer between description and CTAs
+- Welcome and description are **inside** the gutter, same indent as CTAs
+
+### Per-Screen Instructions
+
+Below the heading, outside the gutter, left-aligned:
+
+```
+Screen Heading                     ← C.sapphire, bold
+One-line instruction text          ← C.overlay1, <Text>
+┌
+│  Content...
+└
+```
+
+**Rules:**
+- Instruction is a plain `<Text color={C.overlay1}>` — no GutterLine, no bold
+- Aligns left with the heading (no indent)
+- One line only — concise description of what the screen does
+- Not all screens need instructions — use for primary entry screens
+
+**Example instructions:**
+
+| Screen | Instruction |
+|--------|-------------|
+| New Assessment | Follow each step to record an employee evaluation. |
+| Edit Assessment | Update scores, notes, or assessed levels for this assessment. |
+| View Employees | Browse the employee list to view details and manage assessments. |
+| Search & Filter | Find employees by name, team, title, or level. |
+| Compare | Select two or more employees to compare their assessment results side by side. |
+| Export CSV | Export assessment data as CSV for reporting and analysis. |
+| Edit Employee | Update this employee's information. |
+
+---
+
+## 11. Confirmation & Destructive Actions
+
+### Confirmation Dialog Pattern
+
+```
+Delete Assessment                          ← C.sapphire heading
+┌
+│  Delete assessment by John (2025-01-15)? ← C.red warning text
+│  This cannot be undone.                  ← C.overlay1 detail
+│  ❯ Cancel                               ← Safe option FIRST
+│    Delete                                ← Destructive option
+└
+```
+
+### Rules
+
+1. **Cancel/safe option is always first** in the CTA list
+2. **Destructive text uses `C.red`** for the warning message
+3. **"This cannot be undone."** standard disclaimer in `C.overlay1`
+4. **Never auto-select the destructive option** — cursor starts on Cancel
+5. **Cascade warnings** — if deleting an employee also deletes N assessments, state it explicitly:
+   ```
+   │  Delete John Doe and all 3 assessments?
+   ```
+
+### Description Props
+
+Every CTA option includes a `description` for clarity:
+
+```tsx
+{ label: 'Cancel', value: 'cancel', description: 'Keep assessment and go back' }
+{ label: 'Delete', value: 'delete', description: 'Permanently remove this assessment' }
+```
+
+---
+
+## 12. Empty & Error States
+
+### Empty State
+
+When a list or view has no data:
+
+```
+View Employees
+┌
+│  No employees found              ← C.overlay1
+│  ❯ Create New Assessment         ← Constructive action
+│    Back to Menu
+└
+```
+
+**Rules:**
+- Show a clear message about what's empty
+- Offer a constructive action (create something)
+- Always include Back option
+
+### Error State
+
+```
+│  Error: Failed to load employees: database locked  ← C.red
+```
+
+or inline field error:
+
+```
+│  Employee Name:
+│  [input]
+│  Name is required                 ← C.red
+```
+
+**Rules:**
+- Errors use `C.red`
+- Field errors appear directly below the input
+- Screen-level errors appear as GutterLine inside the gutter
+- Never crash — always show error and offer navigation back
+
+### Loading State
+
+```
+Loading...    ← C.overlay1
+```
+
+- Shown during config/DB initialization
+- Minimal — just text, no spinner needed for fast loads
+- Use `ink-spinner` for longer async operations
+
+---
+
+## 13. ASCII Art Elements
+
+### Score Bars (Compare Screen)
+
+```
+│  John Doe    ████████████████░░░░  4.00
+│  Jane Smith  ████████████░░░░░░░░  3.00
+```
+
+```typescript
+const BAR_WIDTH = 20;
+function scoreBar(score: number | null, max: number = 5): string {
+  if (score === null) return '░'.repeat(BAR_WIDTH);
+  const filled = Math.round((score / max) * BAR_WIDTH);
+  return '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
+}
+```
+
+- Filled: `█` in `C.mauve`
+- Empty: `░`
+- Score value: `C.inputed` bold
+- Width: 20 characters
+
+### Separators
+
+```
+────────────────────────────────────────────────
+```
+
+- `─` repeated, colored `C.overlay1`
+- Used after Banner subtitle
+
+### Ranking Indicators
+
+```
+│  John Doe    4.50  #1  ← C.green for rank 1
+│  Jane Smith  3.80  #2  ← C.overlay1 for others
+```
+
+- Top rank: `C.green` with `★` suffix
+- Other ranks: `C.overlay1`
+
+### Gutter Corners & Lines
+
+| Character | Purpose | Color |
+|-----------|---------|-------|
+| `┌` | Block open | `C.overlay1` |
+| `│` | Vertical gutter | `C.overlay1` |
+| `└` | Block close | `C.overlay1` |
+| `─` | Horizontal separator | `C.overlay1` |
+
+### Selection Indicators
+
+| Character | Meaning | Color |
+|-----------|---------|-------|
+| `❯` | Active cursor | `C.mauve` bold |
+| `●` | Selected (multi) | `C.green` |
+| `○` | Unselected (multi) | `C.overlay0` |
+| `◇` | Completed step | `C.green` |
+| `◆` | Active step | `C.mauve` bold |
+| `✎` | Custom input option | default |
+
+---
+
+## 14. Theme Switching (Future)
+
+### CLI Command
+
+```bash
+# Switch theme
+cli-name theme tokyonight-dark
+
+# List available themes
+cli-name theme --list
+# Output:
+#   catppuccin-mocha  (dark)  ← active
+#   catppuccin-latte  (light)
+#   tokyonight-dark   (dark)
+#   tokyonight-light  (light)
+```
+
+### Implementation Architecture
+
+```
+src/lib/
+├── theme.ts                    # Reads config, exports active `C`
+└── themes/
+    ├── index.ts                # Registry + loader
+    ├── catppuccin-mocha.ts     # ThemeDefinition
+    ├── catppuccin-latte.ts     # ThemeDefinition
+    ├── tokyonight-dark.ts      # ThemeDefinition
+    └── tokyonight-light.ts     # ThemeDefinition
+
+data/
+└── config.json                 # { "theme": "catppuccin-mocha" }
+```
+
+### theme.ts Pattern
+
+```typescript
+import { loadThemePreference } from './themes/index.js';
+
+const theme = loadThemePreference(); // reads config.json, falls back to default
+
+export const C = theme.colors;
+```
+
+### themes/index.ts Pattern
+
+```typescript
+import { catppuccinMocha } from './catppuccin-mocha.js';
+import { catppuccinLatte } from './catppuccin-latte.js';
+import { tokyoNightDark } from './tokyonight-dark.js';
+import { tokyoNightLight } from './tokyonight-light.js';
+import type { ThemeDefinition } from '../types.js';
+
+const THEMES: Record<string, ThemeDefinition> = {
+  'catppuccin-mocha': catppuccinMocha,
+  'catppuccin-latte': catppuccinLatte,
+  'tokyonight-dark': tokyoNightDark,
+  'tokyonight-light': tokyoNightLight,
+};
+
+const DEFAULT_THEME = 'catppuccin-mocha';
+
+export function loadThemePreference(): ThemeDefinition {
+  // Read from config file, fallback to default
+  try {
+    const config = JSON.parse(readFileSync('data/config.json', 'utf-8'));
+    return THEMES[config.theme] ?? THEMES[DEFAULT_THEME]!;
+  } catch {
+    return THEMES[DEFAULT_THEME]!;
+  }
+}
+
+export function setTheme(themeName: string): boolean {
+  if (!THEMES[themeName]) return false;
+  // Write to config.json
+  writeConfigTheme(themeName);
+  return true;
+}
+
+export function listThemes(): ThemeDefinition[] {
+  return Object.values(THEMES);
+}
+```
+
+### Adding a Custom Theme
+
+To add a new theme:
+
+1. Create `src/lib/themes/my-theme.ts` implementing `ThemeDefinition`
+2. Register it in `themes/index.ts` THEMES record
+3. Rebuild — the theme is now available via `cli-name theme my-theme`
+
+---
+
+## 15. Quick-Start Checklist
+
+When creating a new CLI app with this design system:
+
+### Setup
+
+- [ ] Initialize project: React 19 + Ink.js 6 + TypeScript (ES2022, Node16, `react-jsx`)
+- [ ] Install: `react`, `ink`, `@inkjs/ui`, `ink-spinner`, `better-sqlite3`, `nanoid`
+- [ ] Create `src/lib/theme.ts` with semantic color tokens
+- [ ] Copy theme definitions for all 4 built-in themes
+- [ ] Create GutterLine, GutteredSelect, GutteredMultiSelect, StepIndicator, Timeline, Banner components
+
+### Screen Scaffolding
+
+- [ ] Entry point: `cli.tsx` → renders `<App />` via Ink's `render()`
+- [ ] App shell: Banner + screen router with `useState<Screen>('menu')`
+- [ ] Global Esc handler: `useInput` → return to menu
+- [ ] Main Menu with welcome message inside gutter
+- [ ] Each screen: Heading → Instruction → Gutter block → Content → CTAs
+
+### Interaction
+
+- [ ] Every GutteredSelect option has `label` + `value` + `description`
+- [ ] Every screen has a visible Back option
+- [ ] Shift+Tab navigates backward in all wizard steps and form fields
+- [ ] Form data preserved on backward navigation
+- [ ] Validation on submit, errors in `C.red`, cleared on re-attempt or Shift+Tab
+- [ ] Cancel before Delete in confirmation dialogs
+
+### Polish
+
+- [ ] Empty states with constructive actions
+- [ ] Error states with `C.red` and navigation back
+- [ ] Scroll indicators (`↑ more` / `↓ more`) for long lists
+- [ ] Navigation hints on every interactive element (`↑↓ move, enter select`, `Shift+Tab to go back`)
+- [ ] ASCII banner with brand identity
+
+---
+
+## Appendix: Reference Implementation
+
+This guideline was extracted from the **Team Competency Assessment Tool** — a production CLI app built with this exact design system. Source code structure:
+
+```
+src/
+├── cli.tsx                         # Entry point
+├── app.tsx                         # App shell, menu, screen router
+├── components/
+│   ├── banner.tsx                  # ASCII art header
+│   ├── timeline.tsx                # Vertical wizard with step indicators
+│   ├── step-indicator.tsx          # Animated ◆/◇/○ indicators
+│   ├── gutter-line.tsx             # │  prefix component
+│   └── guttered-select.tsx         # Select + MultiSelect with gutter
+├── screens/
+│   ├── new-assessment.tsx          # 6-step wizard
+│   ├── edit-assessment.tsx         # 4-step wizard
+│   ├── view-employees.tsx          # List → Detail → Actions
+│   ├── search.tsx                  # Filter → Results → Detail
+│   ├── compare.tsx                 # MultiSelect → Score bars
+│   ├── export.tsx                  # Menu → Result
+│   ├── edit-employee.tsx           # Multi-field form
+│   └── steps/                      # Wizard step components
+│       ├── employee-step.tsx       # 5-phase: Name→Team→Title→Level→Manager
+│       ├── interviewer-step.tsx    # 4-phase: Name→Team→Title→Level
+│       ├── scores-step.tsx         # Score input per criterion
+│       ├── notes-step.tsx          # Multi-field text input
+│       ├── assessed-levels-step.tsx# Add/remove skill entries
+│       └── confirm-step.tsx        # Review + save
+└── lib/
+    ├── theme.ts                    # Color tokens (C.mauve, C.green, etc.)
+    ├── types.ts                    # All TypeScript types
+    ├── config.ts                   # JSON config loader
+    ├── db.ts                       # SQLite CRUD
+    ├── csv.ts                      # CSV export
+    ├── employee-config.ts          # Teams, titles, levels
+    ├── validation.ts               # Score validation
+    └── input/
+        └── normalize-keys.ts       # ANSI input normalization
+```