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
- SergioRibera/definitive-uxtheir own version, first seen Nov 15, 2026
- AnnenkovLabs/flectentheir own version, first seen Nov 15, 2026
- Dimon94/dveritytheir own version, first seen Nov 15, 2026
- Dimon94/skillstheir own version, first seen Nov 15, 2026
- Tresnanda/kyberntheir own version, first seen Nov 8, 2026
- cill-i-am/skillstheir own version, first seen Nov 1, 2026
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-aiSkillfixing-metadata
Ship correct, complete metadata.
Also in 3 projects that use this
wxyhgkSkillfind-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
VercelSkillbaseline-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-lgtmSkillmake-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
swyxioSkillmobile-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
attentiondotnetSkillanimation-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
Other versions25 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 25
- jakubkrehel/skills★ 12ksame name
- trycompai/crm★ 12ksame name
- talebook/talebook★ 5.9ksame name
- moumen-soliman/uitripled★ 1.4ksame name
- Atharvsinh-codez/ObsidianUI★ 562same name
- boraoztunc/skills★ 473same name
- Dimon94/dverity★ 107same name
- Dimon94/skills★ 107same name
- Tresnanda/kybern★ 92same name
- 0xPasho/agentcut★ 21same name
15 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
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
- Very specific: line 23
Use a spacing scale (1, 2, 4 cells).
- Distinctive: line 29
When geometric centering looks wrong in a terminal, adjust optically.
- Distinctive: line 36
Use 3-4 color tiers consistently:
- Distinctive: line 42
Never use bright colors for passive elements.
- Distinctive: line 59
Every keypress that does something should produce visible feedback within one frame.
- Very specific: line 80
Always show available keys in a footer or status bar.
“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.
Files
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
| Category | When to Use |
| Layout | Alignment, spacing, responsive sizing, content regions |
| Color | Palette consistency, contrast, semantic color usage |
| Interaction | Focus management, key hints, modal flow, feedback |
| Typography | Text 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
| Mistake | Fix |
| Inconsistent padding between similar widgets | Use a spacing constant |
| Bright colors on passive/decorative elements | Reserve bright for actions and focus |
| No visible focus indicator | Add border color or background change on focus |
| Content overflows and wraps badly | Set overflow: hidden with text-overflow: ellipsis |
| No key hints visible | Add contextual footer with available actions |
| Large empty regions at default size | Use fr units to distribute space |
| Mixed border styles in one view | Standardize on one style per element tier |
| No feedback on async operations | Show 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
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
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.

