agentleFS
dedalus-labsdedalus-labs/wingman/.agents/skills/better-interface/SKILL.md

better-interface

Skill181 starsChanged 7 months agoMITView on GitHub

Design engineering principles for making TUI interfaces feel polished. Use when building Textual widgets, reviewing TUI code, implementing transitions, focus states, alignment, spacing, or any visual detail work. Triggers on TUI polish, design details, "make it feel better", "feels off", layout alignment, color consistency, responsive sizing.

25 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use fixing-metadata, find-animation-opportunities and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • agentset-aiSkill

    fixing-metadata

    Ship correct, complete metadata.

    Also in 3 projects that use this

  • wxyhgkSkill

    find-animation-opportunities

    Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

    Also in 6 projects that use this

  • VercelSkill

    baseline-ui

    Validates animation durations, enforces typography scale, checks component accessibility, and prevents layout anti-patterns in Tailwind CSS projects. Use when building UI components, reviewing CSS utilities, styling React views, or enforcing design consistency.

    Also in 3 projects that use this

  • studio-lgtmSkill

    make-interfaces-feel-better

    Apply design engineering best practices to polish UI components - use when reviewing or improving interfaces, animations, typography, or interaction details.

    Also in 4 projects that use this

  • swyxioSkill

    mobile-native

    Apply swyx's native mobile UX preferences when designing or critiquing iPhone/iPad flows, adapting tablet layouts, choosing communication-app notification behavior, or opening notifications/deep links/widgets/shortcuts before local content is ready. Also use for iOS/iPadOS generated build configuration, signing/install/launch problems, and device playtesting. Keep existing native or cross-platform stacks; excludes browser-only responsive work and backend-only changes without native UX or delivery implications.

    Also in 3 projects that use this

  • attentiondotnetSkill

    animation-vocabulary

    Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

    Also in 6 projects that use this

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 25 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use a spacing scale (1, 2, 4 cells).

    line 23
  2. Distinctive:

    When geometric centering looks wrong in a terminal, adjust optically.

    line 29
  3. Distinctive:

    Use 3-4 color tiers consistently:

    line 36
  4. Distinctive:

    Never use bright colors for passive elements.

    line 42
  5. Distinctive:

    Every keypress that does something should produce visible feedback within one frame.

    line 59
  6. Very specific:

    Always show available keys in a footer or status bar.

    line 80

“Common” is measured: kept by at least 6 in 10 of the 25 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Details that make TUI interfaces feel better

Great TUIs rarely come from a single thing. It's a collection of small details that compound into a professional experience. Apply these principles when building or reviewing Textual/terminal UI code.

Quick Reference

CategoryWhen to Use
LayoutAlignment, spacing, responsive sizing, content regions
ColorPalette consistency, contrast, semantic color usage
InteractionFocus management, key hints, modal flow, feedback
TypographyText truncation, wrapping, Unicode, monospace alignment

Core Principles

1. Consistent Spacing

Use a spacing scale (1, 2, 4 cells). Mismatched padding between related elements is the most common thing that makes TUIs feel off. Textual's padding and margin CSS properties use cell units.

2. Optical Alignment Over Grid Alignment

When geometric centering looks wrong in a terminal, adjust optically. Asymmetric Unicode characters (arrows, bullets) and mixed-width content need manual nudging. A centered title above left-aligned content often needs 1 cell of left padding removed.

3. Color Hierarchy

Use 3-4 color tiers consistently:

  • Primary: key actions, active focus (bright, saturated)
  • Secondary: labels, metadata (dimmed)
  • Muted: borders, separators (very dim)
  • Danger/Success: semantic states only (red/green)

Never use bright colors for passive elements. Reserve saturation for things the user needs to notice.

4. Focus is Sacred

The focused widget must be visually distinct at a glance. Use border color changes, not just cursor position. A user glancing at the screen should instantly know where input will go.

5. Responsive Layout

TUI must work at 80x24 minimum. Use fr units and max-width/ min-width in Textual CSS to adapt. Content that overflows should truncate with ellipsis, never wrap into garbage.

6. Feedback on Every Action

Every keypress that does something should produce visible feedback within one frame. If an operation takes time, show a spinner or status message immediately — don't let the user wonder if their input was received.

7. Subtle Transitions

Textual supports CSS transitions. Use short durations (150-300ms) for background color and opacity changes on hover/focus. Never animate layout properties (width, height) — terminal reflow is not smooth.

8. Border Consistency

Pick one border style and stick with it. tall for primary containers, round for cards/modals, heavy for emphasis. Mixing ascii, tall, round, and heavy in one screen looks incoherent.

9. Key Hints

Always show available keys in a footer or status bar. Format as key action pairs separated by thin spaces. Dim the keys relative to the actions. Update hints contextually as focus moves.

10. Content Density

Terminal space is precious. Default to dense layouts. Use blank lines only to separate logical groups, never for decoration. Single-line headers over multi-line. Abbreviate labels when the full form is obvious from context.

Common Mistakes

MistakeFix
Inconsistent padding between similar widgetsUse a spacing constant
Bright colors on passive/decorative elementsReserve bright for actions and focus
No visible focus indicatorAdd border color or background change on focus
Content overflows and wraps badlySet overflow: hidden with text-overflow: ellipsis
No key hints visibleAdd contextual footer with available actions
Large empty regions at default sizeUse fr units to distribute space
Mixed border styles in one viewStandardize on one style per element tier
No feedback on async operationsShow spinner/status immediately on action

Review Checklist

  • Spacing is consistent between related elements
  • Focused widget is visually distinct (border or background)
  • Color usage follows the 3-4 tier hierarchy
  • Layout works at 80x24 minimum terminal size
  • Long text truncates with ellipsis, never wraps into garbage
  • Key hints are visible and contextually updated
  • Every user action produces visible feedback
  • Border styles are consistent within each tier
  • No bright colors on passive elements
  • Transitions are short (150-300ms) and only on color/opacity

Reference Files

  • layout.md — Alignment, spacing, responsive sizing
  • color.md — Palette consistency, contrast, semantic usage
  • interaction.md — Focus management, key hints, modals
  • typography.md — Truncation, wrapping, Unicode alignment

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.