Skip to content
Merged
60 changes: 60 additions & 0 deletions skills/terminal-ui-premium/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
name: terminal-ui-premium
description: Design and implement premium terminal-native interfaces for Ratatui or other TUI/CLI products. Use this skill when improving terminal UX, command panes, dashboards, onboarding, keyboard navigation, focus hierarchy, empty states, or visual polish for CLI-native tools.
---

This skill guides premium terminal UX work for production-grade CLI and TUI products.

Use it when the user wants the interface to feel calmer, more native, easier to navigate, and more trustworthy without turning the terminal into a fake GUI.

## Workflow

1. Inspect the existing render tree first.
Identify where layout, theme tokens, focus state, and empty states are defined before changing visuals.

2. Read [references/benchmark-cli-ux.md](references/benchmark-cli-ux.md) when choosing a direction.
It distills patterns from Ghostty, Warp, GitHub CLI, and Lazygit.

3. Pick one dominant direction and stay consistent.
For Forge, prefer calm operational minimalism: dark surfaces, quiet chrome, explicit focus, strong keyboard discoverability, and compact status language.

4. Apply hierarchy in this order:
- primary work surface first
- active context second
- navigation affordances third
- chrome last

5. Keep onboarding progressive.
Empty states should teach one next action, not explain the whole product.

6. Preserve terminal ergonomics.
Do not depend on color alone, avoid noisy animation, keep labels short, and make all important state readable as plain text.

## Design Rules

- Use spacing, contrast, and density before adding more borders.
- Focus should be obvious at a glance.
- A status badge should communicate state in 1 to 2 words.
- Keep one clear input anchor. If input is always available, it should feel pinned and dependable.
- Group command + context + outcome tightly so the user can scan history quickly.
- Prefer contextual shortcut rails over giant help paragraphs.
- Empty views should always answer: what appears here, and what should I do next?
- Accessibility matters in terminals too: stable text, readable contrast, and redundant cues beat flashy redraws.

## Ratatui Guidance

- Put palette decisions in `theme.rs`, not inline in views.
- Use fixed-height header bands for identity, mode, and status.
- Use subtle surface changes for nested regions instead of stacking heavy borders everywhere.
- Keep pane titles short and product-like.
- Align tabular content and truncate aggressively to avoid ragged walls of text.
- When adding onboarding hints, keep them tied to the currently focused pane.

## Delivery Standard

Ship the visual system and the behavior together:
- updated theme tokens
- improved focus states
- clearer empty states
- tighter navigation hints
- verified compile/test pass
79 changes: 79 additions & 0 deletions skills/terminal-ui-premium/references/benchmark-cli-ux.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Premium CLI/TUI Benchmarks

These notes are distilled from official product docs and repos. Re-read the linked sources when making larger design calls.

## Ghostty

Sources:
- https://ghostty.org/docs/about
- https://ghostty.org/docs/features
- https://ghostty.org/docs/config/keybind/reference

What to borrow:
- Native feel over decorative chrome. Ghostty explicitly aims to look, feel, and behave like a purpose-built native app on each platform.
- Fast + feature-rich + native is the standard, not a tradeoff.
- Platform conventions matter. Familiar shortcuts and window behaviors reduce learning cost.
- Useful secondary surfaces such as quick terminal, tabs, splits, and command palette should feel immediate, not bulky.

Implication for Forge:
- The UI should feel operational and settled by default.
- Focus states, keyboard hints, and pane titles should feel native and unsurprising.
- Styling should support the workflow, not advertise itself.

## Warp

Sources:
- https://docs.warp.dev/terminal/blocks
- https://docs.warp.dev/terminal/appearance/input-position

What to borrow:
- Commands and output are easier to scan when treated as a single unit.
- A pinned input anchor reduces disorientation.
- Navigation improves when the UI makes history feel structured instead of like an endless text dump.
- Input position and command palette are discoverable, not hidden power-user features.

Implication for Forge:
- Keep the command pane visually anchored.
- Tie recent command, AI state, and approvals closely to the current editor context.
- Make slash actions feel like a real palette, not a loose autocomplete list.

## GitHub CLI

Sources:
- https://cli.github.com/manual/gh_help_formatting
- https://github.blog/engineering/user-experience/building-a-more-accessible-github-cli/

What to borrow:
- Text output can still feel polished when alignment, truncation, hyperlinks, and relative time are handled deliberately.
- Accessibility in terminals requires stable text, high contrast, and structure that assistive tech can infer from plain text.
- Avoid relying on redraw-heavy spinners when contextual status text can do the job better.
- Color should be customizable and should never be the only carrier of meaning.

Implication for Forge:
- Use labels plus color for states like dirty, queued, failed, and approved.
- Prefer static textual status summaries over ornamental motion.
- Keep tables, badges, and event lines readable in plain text.

## Lazygit

Source:
- https://github.com/jesseduffield/lazygit

What to borrow:
- Terminal tools feel premium when they collapse painful workflows into obvious, keyboard-first actions.
- Dense UIs can still feel approachable when every pane has a clear purpose and the next action is obvious.
- Filtering, contextual actions, compare flows, undo, and history all increase trust because the user stays in control.

Implication for Forge:
- Every pane should make the next move legible.
- Empty states should point to one concrete action.
- Dense operational data is fine if hierarchy stays crisp.

## Shared Principles

- Calm default state, strong active state.
- One dominant work surface, not five competing ones.
- Progressive disclosure: teach only the next action.
- Keyboard hints belong near the place they matter.
- Dense information is acceptable when structure is explicit.
- Premium terminal UX is mostly restraint, clarity, and confidence.
41 changes: 39 additions & 2 deletions src/ai/providers/mock.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
use crate::ai::provider::{AiFuture, AiProvider};
use crate::domain::{AiCitation, AiRequest, AiRequestKind, AiResponse};
use crate::domain::{
AiActionProposal, AiCitation, AiRequest, AiRequestKind, AiResponse, SafetyClass,
};
use crate::shared::time::now_utc;

pub struct MockProvider {
Expand Down Expand Up @@ -59,6 +61,41 @@ fn mock_response(request: AiRequest, model: Option<String>) -> AiResponse {
));
}

let proposals = match request.kind {
AiRequestKind::Assist => vec![
AiActionProposal {
summary: "Inspect the current repository state".to_string(),
detail: "Check the working tree before taking additional action.".to_string(),
command: Some("git status".to_string()),
safety_class: SafetyClass::Passive,
},
AiActionProposal {
summary: "Run the Rust test suite".to_string(),
detail: "Confirm the current behavior against the latest local changes."
.to_string(),
command: Some("cargo test".to_string()),
safety_class: SafetyClass::Caution,
},
],
AiRequestKind::Diagnose => vec![
AiActionProposal {
summary: "Re-run tests to reproduce the failure".to_string(),
detail: "Use a fresh test run so the latest output is captured in Forge."
.to_string(),
command: Some("cargo test".to_string()),
safety_class: SafetyClass::Caution,
},
AiActionProposal {
summary: "Review the current diff".to_string(),
detail:
"Inspect the working tree for recent changes that correlate with the failure."
.to_string(),
command: Some("git diff --stat".to_string()),
safety_class: SafetyClass::Passive,
},
],
};

AiResponse {
request_id: request.id,
created_at: now_utc(),
Expand All @@ -67,7 +104,7 @@ fn mock_response(request: AiRequest, model: Option<String>) -> AiResponse {
summary: format!("Mock AI response for `{}`", request.prompt),
message,
recommendations,
proposals: Vec::new(),
proposals,
citations: vec![AiCitation {
label: "context".to_string(),
detail: format!(
Expand Down
80 changes: 76 additions & 4 deletions src/ai/providers/openai.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ use serde_json::{json, Value};

use crate::ai::provider::{AiFuture, AiProvider};
use crate::config::AiConfig;
use crate::domain::{AiCitation, AiRequest, AiResponse};
use crate::domain::{AiActionProposal, AiCitation, AiRequest, AiResponse, SafetyClass};
use crate::shared::error::AiError;
use crate::shared::time::now_utc;

Expand Down Expand Up @@ -121,7 +121,16 @@ impl AiProvider for OpenAiProvider {
summary: structured.summary,
message: structured.message,
recommendations: structured.recommendations,
proposals: Vec::new(),
proposals: structured
.proposals
.into_iter()
.map(|proposal| AiActionProposal {
summary: proposal.summary,
detail: proposal.detail,
command: (!proposal.command.trim().is_empty()).then_some(proposal.command),
safety_class: proposal.safety_class,
})
.collect(),
citations: structured
.citations
.into_iter()
Expand Down Expand Up @@ -172,6 +181,10 @@ fn build_developer_prompt(request: &AiRequest) -> String {
"Use the provided repository/runtime context. Be concrete, grounded, and concise.\n",
"Do not claim certainty when evidence is weak.\n",
"Do not propose hidden actions.\n",
"Only include action proposals when they are directly grounded in the supplied context.\n",
"Each proposal must be a single inspectable command. If no grounded action is appropriate, return an empty proposals array.\n",
"The proposal safety_class is a best-effort hint using one of: Passive, Safe, Caution, Risky, Destructive.\n",
"Return at most 3 proposals.\n",
"Return JSON matching the requested schema.\n\n",
"Request kind: {}\n",
"UI focus: {}\n",
Expand Down Expand Up @@ -285,7 +298,7 @@ fn response_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["summary", "message", "recommendations", "citations"],
"required": ["summary", "message", "recommendations", "proposals", "citations"],
"properties": {
"summary": {
"type": "string",
Expand All @@ -300,6 +313,27 @@ fn response_schema() -> Value {
"items": { "type": "string" },
"description": "Concrete next steps or checks."
},
"proposals": {
"type": "array",
"description": "Optional grounded actions. Use an empty array when no direct action should be suggested.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["summary", "detail", "command", "safety_class"],
"properties": {
"summary": { "type": "string" },
"detail": { "type": "string" },
"command": {
"type": "string",
"description": "A single shell command to run. Do not include explanations here."
},
"safety_class": {
"type": "string",
"enum": ["Passive", "Safe", "Caution", "Risky", "Destructive"]
}
}
}
},
"citations": {
"type": "array",
"items": {
Expand Down Expand Up @@ -387,6 +421,7 @@ struct StructuredAiResponse {
summary: String,
message: String,
recommendations: Vec<String>,
proposals: Vec<StructuredProposal>,
citations: Vec<StructuredCitation>,
}

Expand All @@ -396,6 +431,14 @@ struct StructuredCitation {
detail: String,
}

#[derive(Debug, Deserialize)]
struct StructuredProposal {
summary: String,
detail: String,
command: String,
safety_class: SafetyClass,
}

#[cfg(test)]
mod tests {
use serde_json::json;
Expand All @@ -413,7 +456,7 @@ mod tests {
"output": [
{
"content": [
{ "type": "output_text", "text": "{\"summary\":\"s\",\"message\":\"m\",\"recommendations\":[],\"citations\":[]}" }
{ "type": "output_text", "text": "{\"summary\":\"s\",\"message\":\"m\",\"recommendations\":[],\"proposals\":[],\"citations\":[]}" }
]
}
]
Expand Down Expand Up @@ -443,5 +486,34 @@ mod tests {
let payload = build_payload(&request, "gpt-5-mini");
assert_eq!(payload["text"]["format"]["type"], "json_schema");
assert_eq!(payload["model"], "gpt-5-mini");
assert!(payload["text"]["format"]["schema"]["required"]
.as_array()
.expect("schema required array should exist")
.iter()
.any(|value| value == "proposals"));
}

#[test]
fn structured_response_parses_proposals() {
let parsed: StructuredAiResponse = serde_json::from_value(json!({
"summary": "Forge found a likely next step",
"message": "The latest logs suggest rerunning the test suite.",
"recommendations": ["Inspect the newest stderr lines first."],
"proposals": [
{
"summary": "Rerun the Rust test suite",
"detail": "Verify the current failure state before changing code.",
"command": "cargo test",
"safety_class": "Caution"
}
],
"citations": [
{ "label": "timeline", "detail": "Recent command failure was captured in the event stream." }
]
}))
.expect("structured response should deserialize");

assert_eq!(parsed.proposals.len(), 1);
assert_eq!(parsed.proposals[0].command, "cargo test");
}
}
13 changes: 13 additions & 0 deletions src/app/effects.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,20 @@ pub enum UiIntent {
KeyChar(char),
Backspace,
Submit,
InsertNewline,
ClearInput,
MoveCursorLeft,
MoveCursorRight,
MoveCursorUp,
MoveCursorDown,
MoveCursorHome,
MoveCursorEnd,
RecallPreviousHistory,
RecallNextHistory,
CycleInputMode,
PrevCommandSuggestion,
NextCommandSuggestion,
AcceptCommandSuggestion,
NextFocus,
PrevFocus,
NextTab,
Expand Down
Loading
Loading