myhiss-terminal-design

name	myhiss-terminal-design
description	Designs the Myhiss terminal UX and visual system. Invoke when building or refining TUI/CLI screens, onboarding flows, themes, or terminal interaction patterns.

Myhiss Terminal Design

Purpose

This skill defines how Myhiss should look and behave in the terminal.

Use it when the task involves:

• onboarding screens
• theme selection
• provider selection
• terminal layouts
• diff previews
• approval prompts
• color systems
• keyboard-first flows

Project Context

Myhiss is a Python-focused coding assistant, but the current product runtime is a Node.js + TypeScript CLI/TUI.

Design decisions must therefore follow these rules:

1. Prefer the libraries already present in the repository before proposing new dependencies.
2. Treat the product as a premium terminal experience inspired by modern coding terminals such as Gemini CLI.
3. Optimize the interface for Python engineering tasks, not for generic chat alone.
4. Keep all critical interactions readable in standard dark terminals first.

Design Targets

The UI should feel:

• calm
• technical
• precise
• minimal
• trustworthy

The visual identity should emphasize:

• black or near-black backgrounds
• green as the primary brand accent
• lighter green for success and selected states
• restrained brown or muted amber for secondary snake-inspired accents
• high contrast for code, warnings, and approval flows

Core UX Principles

1. Keyboard First

Every primary action must be reachable without a mouse.

Preferred interactions:

• arrow navigation for lists
• enter to confirm
• escape to cancel or go back
• single-key shortcuts only when clearly discoverable

2. Progressive Onboarding

The first-run flow should be short and sequential:

1. welcome
2. workspace trust context
3. theme selection
4. provider selection
5. API key or local runtime setup
6. approval mode selection
7. first prompt screen

Do not show advanced settings before the user can complete the initial run.

3. Readability Over Decoration

Do not overload the screen with borders, badges, or multiple simultaneous panels unless they add operational value.

Prioritize:

• short labels
• strong hierarchy
• clear selected state
• one primary call to action per screen

4. Code-Centric Interactions

All code-related surfaces must support:

• syntax-aware highlighting when available
• before/after comparisons
• explicit confirmation before applying edits
• compact but readable file path display

Required Screens

Welcome

Must communicate:

• what Myhiss does
• current workspace context
• whether the workspace is trusted
• the next action the user needs to take

Theme Selection

Must provide:

• dark
• light
• system

Optional accessibility variants can come later, but the base flow must work first.

Provider Selection

Must distinguish between:

• cloud providers requiring credentials
• local providers like Ollama

The selected provider state must remain obvious after selection.

Approval Mode

Must provide:

• read-only
• ask-before-write
• auto-approve

The active mode must remain visible when the user reaches the prompt workspace.

Prompt Workspace

Must include:

• active provider
• active model
• active approval mode
• current workspace or file context
• input zone
• status or feedback line

Change Review

Must clearly separate:

• added content
• removed content
• unchanged context

Approval actions must be unambiguous.

Preferred labels:

• Apply
• Reject
• Revise

Layout Rules

• Design for narrow and medium terminal widths first.
• Avoid requiring full-screen width to understand a flow.
• Keep important actions within the first visible viewport.
• Use horizontal separators sparingly.
• Do not rely on color alone to communicate meaning.

Theming Rules

Theme tokens should be conceptual before implementation:

• background
• foreground
• muted
• accent
• success
• warning
• danger
• info
• selection
• diffAdded
• diffRemoved

When a theme is incomplete, dark mode is the default fallback.

Content Style

Text in the UI should be:

• short
• direct
• operational

Avoid:

• marketing copy in core flows
• long paragraphs during onboarding
• vague button labels such as Continue or Okay when a precise action exists

Prefer:

• Select theme
• Choose provider
• Enter API key
• Review changes
• Apply patch

Implementation Guidance

When proposing implementation work:

1. Reuse the existing package stack first.
2. Keep render logic separate from provider logic.
3. Centralize theme tokens instead of hardcoding colors in many places.
4. Design empty, loading, success, and error states together.
5. Treat diff review as a first-class screen, not an afterthought.

Gotchas

• Do not assume all terminals render Unicode identically.
• Do not depend only on color for diffs or selection state.
• Do not hide destructive actions behind unclear shortcuts.
• Do not mix provider setup, theme setup, and prompt entry on one crowded screen.
• Do not introduce Python TUI libraries into the main runtime unless the project intentionally adds a Python sub-application.
• Do not break narrow-width rendering with long unwrapped paths or labels.

Definition of Done

A terminal design task is ready when:

• the flow is understandable without explanation
• the selected state is always obvious
• onboarding is sequential and low-friction
• change review is safe and readable
• the interface remains usable in common dark terminal themes