By 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:
- Prefer the libraries already present in the repository before proposing new dependencies.
- Treat the product as a premium terminal experience inspired by modern coding terminals such as Gemini CLI.
- Optimize the interface for Python engineering tasks, not for generic chat alone.
- 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:
- welcome
- workspace trust context
- theme selection
- provider selection
- API key or local runtime setup
- approval mode selection
- 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:
- Reuse the existing package stack first.
- Keep render logic separate from provider logic.
- Centralize theme tokens instead of hardcoding colors in many places.
- Design empty, loading, success, and error states together.
- 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