Skilld Tui Design

Design skilld CLI interactions

Build the user's whole command journey, including failure, cancellation, and the return to their shell. Read source decisions for the two reviewed Skills and their exact revisions.

Establish the contract

Read the project's GLOSSARY.md, COPY.md, and VISION.md when present. Keep canonical nouns and strings. Use short sentences with one idea each. Inspect the command parser, output renderer, and terminal lifecycle before changing behavior. Classify each affected surface as static output, a picker, a prompt, or a full-screen view. Include command help, parser errors, startup notices, and progress indicators in the inventory. List its starting state, successful outcome, expected failures, and cancellation behavior. Keep the existing JSON envelope, streams, and exit codes unless the task changes that contract.

Use the existing shared renderer and semantic palette. Avoid adding a second framework or per-screen theme. Start with crates/skilld-ui, crates/skilld-command/src/output.rs, and crates/skilld-native/src. Inspect command help and routing in crates/skilld-command/src/lib.rs.

Put the decision first

Static output starts with the requested result or the failed action. Group repeated records consistently. Place supporting metadata below each record. Use spacing and headings before adding boxes. Keep commands copyable. Preserve whitespace inside quoted arguments. Wrap prose and paths by terminal cells. Preserve the original value in machine output. Give empty results a useful next action based on available commands.

Pickers show the question, query, matching count, selected item, and valid keys. Full-screen views keep scope and current state visible. For large inventories, start with recommendations and counts. Open projects or folders before listing individual Skills. Use words for findings. Label identical copies as duplicates and show their paths; separate symlinks from directory copies. State when a filter changes only the view. An action review must still list every affected target. Spend rows on the user's decision. Do not reserve space for decorative panels. If a pane cannot show complete content, provide reachable scrolling or a detail view. At smaller sizes, simplify the layout before hiding required information. If the screen is unusable, block hidden actions and show the required size.

Use colour with independent cues

Inherit the terminal's foreground and background for body text. Share roles for brand, action, secondary information, success, warning, error, focus, and selection. Use one action accent across screens. Reserve status colours for actual status. Show ownership as a label, without implying safety or success. Pair colour with words, markers, bold text, or inverse selection. Make pane focus visible when colour is disabled. Honor NO_COLOR, TERM=dumb, and existing output capability detection. Never claim contrast across unknown terminal themes from one screenshot.

Make state and input agree

Use explicit states for loading, browsing, editing, review, applying, completion, and failure. Prefer tagged states carrying their required data over overlapping pending flags. Keep filesystem and network work outside the input loop. If operations can overlap, identify their results so stale work cannot replace the current view. Derive available actions and footer hints from the same state rules. Keep query editing separate from global shortcuts. Typing q in a query must remain possible. Make Escape predictable: cancel editing or review before leaving the whole screen. Preserve selection by stable identity when refreshing data. Bound scrolling and expose position when the remaining content is otherwise unclear. Provide discoverable help when the current footer cannot explain all controls.