feat: add DESIGN.md

[JustineDevs]

GitLeap Design System (DESIGN.md)

This file codifies the visual language, deterministic terminal math, and native Rezi design token primitives for GitLeap. AI coding agents must strictly adhere to these rules when generating UI layouts, terminal buffers, or static asset vectors.

---

1. Visual Theme & Atmosphere

• Core Philosophy: A high-performance, low-latency "Terminal-Plus" environment engineered for complex AST compilation pipelines, repository transmutations, and live developer event tracking.
• Density: Maximal data density. Avoid wasteful whitespace; maximize terminal cell allocation using precise grid splits and contiguous run-length encoding.
• The "One Gradient" Constraint: Absolute design strictness. Linear gradients are prohibited across the entire interface with exactly one exception: a single animated cosine-bell highlight sweep reserved exclusively for the wordmark sheen and active progression metrics. Everything else must remain solid flat color.

---

2. Color Palette & Semantic Roles

All color assignments must be driven by these exact hex values. Do not introduce parallel styling variables.

Token	Hex Value	Semantic System Role
COLOR.accent	#00E5A3	Transmuter Cyan: Primary action focus, active cursor pins, and successful execution states.
COLOR.primary	#7C3AED	Pipeline Purple: The Git/AI orchestration space background anchor and base progress metric color.
COLOR.textNormal	#F8FAFC	Token Text: Crisp, high-contrast off-white for reading configurations and raw terminal logs without eye strain.
COLOR.textMuted	#64748B	Diminished Text: Muted slate for file paths, commit hashes, inactive tabs, and timestamp data.
COLOR.bgCanvas	#0B0F19	Deep Terminal Canvas: The dark, saturated blue-gray background canvas for the entire terminal session.
COLOR.good	#00E5A3	Success Flag: Pristine states, complete refactors, and stable compilation.
COLOR.warn	#F59E0B	Worker Warning: Amber indicator for cache misses, rate limits, or AI self-correction loops.
COLOR.bad	#EF4444	Compile Error: Crimson indicator for syntax failures, blockages, or malicious injection attempts.

---

3. Typography & Interface Glyphs

Terminal interfaces rely heavily on specific monospace box-drawing primitives and diagnostic character glyphs to enforce visual structure.

export const ICON = {
  success: '✓',      // Task completions / validated runs
  prompt: '❯',       // Input field focus headers
  pause: '⏸',        // Paused event queues or worker states
  folder: '📂',       // Repository directories
  primitive: '🔹',    // AST token types or modular nodes
  manifest: '⚙',     // Configuration blocks or system states
  guide: '📝',        // Contributing documentation anchors
  package: '📦',     // Distributed code packages
  spinner: '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏' // 10-frame Braille interval cycle sequence (80ms updates)
} as const;

---

4. Layout Layout & Focus-Aware Boxing (RULE)

Layouts are split into explicit visual boxes using structural panel borders. The borders adapt dynamically depending on terminal system focus parameters:

export const RULE = {
  borderFocused: '#00E5A3',   // Maps to COLOR.accent (Tied to the actively focused pane)
  borderUnfocused: '#1E293B', // Muted Slicing Gray (Tied to inactive user blocks)
  dividerHorizontal: '#1E293B' // Structural segmentation lines
} as const;

export const GUTTER = {
  paddingLeft: 2,
  paddingRight: 2
} as const;

Split Panel Geometry

Panels draw an explicit top-line interrupt boundary to frame labels cleanly.

• Focused Active Window Style: ╭─ Title ───╮ rendered in #00E5A3
• Unfocused Window Style: ╭─ Title ───╮ rendered in #1E293B

---

5. Animation Mathematical Equations (Stateless & Deterministic)

Animations do not use component wrappers or framework state abstractions. They run on a headless, mathematical cosine-bell configuration to maintain absolute parity across active CLIs and static output vectors.

export const SHEEN_CONFIG = {
  SHEEN_PEAK: 1.0,      // Absolute peak luminescent intensity
  SHEEN_RADIUS: 6.0,    // Total grid cell sweep boundary radius
  SHEEN_TICK_MS: 50,    // Fixed processing loop clock tick length
  SHEEN_SPEED: 0.4,     // Cell progression velocity per loop iteration
  SHEEN_MAX: 100,       // Periodic envelope normalization boundary ceiling
} as const;

Cosine-Bell Intensity Distribution

To calculate the highlight mix for an explicit coordinate position (cellIndex) along a 1D line vector against an active animation step center (sheenCenter), developers must apply the following equation:

$$\text{Distance} = \vert{}\text{cellIndex} - \text{sheenCenter}\vert{}$$

$$\text{If Distance} \ge \text{SHEEN_RADIUS} \Rightarrow \text{Intensity} = 0$$

$$\text{Else} \Rightarrow \text{Intensity} = 0.5 \times \left(1 + \cos\left(\frac{\pi \times \text{Distance}}{\text{SHEEN_RADIUS}}\right)\right) \times \text{SHEEN_PEAK}$$

The resulting intensity factor is passed into a linear color interpolation utility (lerpHex) to morph base colors from COLOR.primary (#7C3AED) into the bright brand sheen highlight COLOR.accent (#00E5A3).

---

6. Implementation Architecture Guidelines (Rezi-First rendering)

• No Virtual DOM: React and Ink primitives are fully deprecated. All canvas layout calculations must map raw bytes or strings into flat text grids.
• Run-Length Optimization: When painting high-frequency color adjustments (such as moving progress indicators), developers must collect adjacent cells sharing identical hex codes into combined Run[] structures before writing to the terminal stream to protect process execution memory limits.
• Circular Navigation Constraints: All directional lists, tabs, or menus must utilize a strict modulo index wrap system to prevent out-of-bounds pointer breaks ((nextIndex + length) % length).

---

7. Design System AI Guardrails (Do's and Don'ts)

✅ DO

• Reuse the global color interpolation helper (lerpHex) for cell transitions rather than choosing pre-calculated midpoints.
• Use COLOR.textMuted (#64748B) generously for structural metadata, file locations, hashes, and timestamps to eliminate terminal noise.
• Swap boundary lines to RULE.borderFocused instantly when a component intercepts active keyboard inputs.

❌ DON'T

• NEVER introduce full multi-color backgrounds or rainbow terminal styles.
• NEVER render gradients anywhere inside the interface except across the designated wordmark canvas lines and active ProgressBar ticks.
• Do not drop standard elements into the layout without adding the structured GUTTER horizontal padding offsets.