agentleFS
chinthakatchinthakat/agent-skills/skills/interface-craft/SKILL.md

interface-craft

Skill0 starsChanged 53 days agoMITView on GitHub

Build or review product UI — the screens people use repeatedly to do a job, as opposed to a marketing page. Covers hierarchy, density, forms, tables, feedback timing, destructive actions, consistency and an accessibility floor. Use when building an app screen, a dashboard, a settings page, an admin console or a form, and when reviewing one.

11 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Prefer undo over confirm. A confirm dialog is dismissed on reflex.

    line 102
  2. Distinctive:

    Keep destructive controls physically away from the ones next to them in the flow.

    line 107
  3. Distinctive:

    Do not invent a control that already exists in the platform.

    line 116
  4. Distinctive:

    Follow the platform's conventions for back, dismiss, and where the primary button sits in a dialog.

    line 119
  5. Distinctive:

    Not a phase. A floor, and it is low:

    line 125
  6. Distinctive:

    Never remove the outline without replacing it.

    line 128
  7. Distinctive:

    Test one flow with the keyboard alone, and one with a screen reader.

    line 137

“Common” is measured: kept by at least 6 in 10 of the 10 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

Interface craft

This is about product UI: the screens someone opens for the fifth time today to get something done. Different goals from a landing page — a landing page must be memorable, a tool must be forgettable, because attention spent on the interface is attention taken from the work.

1. One primary action per screen

Decide what this screen is for and let exactly one thing look like the answer. Everything else steps down: secondary buttons, tertiary links, items in a menu.

Three buttons of equal weight means the design has not decided, and the user has to. Count the things competing for attention on each screen; if it is more than one, the fix is demotion, not rearrangement.

Corollary: if the primary action is unclear to you, the requirements are unclear. Go back rather than designing around it.

2. Density is a decision, matched to frequency

UsedWants
Once (signup, setup)Generous space, one thing at a time, guidance
DailyModerate density, keyboard access, few clicks
All day (an operator's console)High density, everything visible, no wizards, no animations

Applying onboarding spaciousness to a tool someone lives in makes them scroll all day. Applying console density to a first-run flow overwhelms. Pick per screen, not per product, and say which you picked.

3. Hierarchy comes from structure, not decoration

Size, weight, spacing and position carry the hierarchy. Colour, borders and shadows are for grouping and state — using them to signal importance runs out quickly and fails for anyone who cannot distinguish them.

  • Group with proximity and whitespace before reaching for a card or a border. A page where every group is a bordered card has flattened its own hierarchy.
  • A consistent spacing scale (4 / 8 / 12 / 16 / 24 / 32) does more for perceived quality than any individual choice within it.
  • Align to a grid and keep to it. Misalignment is the thing people notice without being able to name.

4. Forms

Where most product UI lives, and where most of it is careless.

  • Labels above fields, always visible. Placeholder-as-label disappears the moment someone types and is unreadable for low vision.
  • One column. Multi-column forms cause skipped fields. Two fields side by side only when they are genuinely one thing (city/postcode, expiry/CVC).
  • Validate on blur and on submit, not on every keystroke. Never mark a field invalid before it has been left.
  • Never clear input on error. Especially passwords, and especially on mobile.
  • Say what is required, and mark the smaller set — if most fields are required, mark the optional ones instead.
  • The right keyboard and autofill on mobile: type, inputmode, autocomplete. Making someone switch to the numeric keyboard for a phone number is a small insult repeated thousands of times.
  • Submit must be reachable with the on-screen keyboard open.
  • Errors in a summary at the top for long forms, each linking to its field.
  • Preserve a draft for anything long. Browsers crash and sessions expire.

5. Tables and lists

  • Decide what is sortable, what is filterable, and what the default order is — and make the default the one people want most days.
  • Sticky header once the list is taller than the viewport.
  • Right-align numbers, use tabular figures so digits line up, and keep units and precision consistent down a column.
  • Decide the row action. Clicking the row, a trailing menu, or an explicit button — one of them, consistently, everywhere.
  • Paginate or virtualise past a threshold you have chosen, and show the total. "Showing 50 of 12,480" is information; a silently truncated list is a bug.
  • Bulk actions need a clear selection count and an undo.
  • On narrow screens a table becomes a list of cards, not a horizontally scrolling table, unless comparing columns is the whole point.

6. Feedback timing

Three thresholds worth designing to:

UnderThe user perceivesSo
~100 msInstantAcknowledge every press within this, even if the work continues
~1 sA pauseNo spinner needed, but do not let the UI appear frozen
~10 sLost attentionProgress, an estimate, or hand it off and notify

Latency you cannot remove can still be made to feel shorter by responding immediately and filling the wait with the shape of what is coming.

7. Destructive actions

  • Prefer undo over confirm. A confirm dialog is dismissed on reflex; an undo window is forgiving of the mistake that actually happened.
  • Where confirmation is warranted, name the object and its consequences — "Delete North Depot and its 214 records?" — and do not focus the destructive button by default.
  • Keep destructive controls physically away from the ones next to them in the flow. Adjacent Save and Delete is a trap.
  • Soft-delete wherever you can, so undo is real rather than a promise.

8. Consistency is a feature

  • One action has one name everywhere. The button that says Publish produces a message that says Published.
  • The same kind of object looks the same wherever it appears.
  • Do not invent a control that already exists in the platform. A custom select loses keyboard support, screen-reader support, mobile native pickers and autofill, in exchange for looking slightly different.
  • Follow the platform's conventions for back, dismiss, and where the primary button sits in a dialog. Users have expectations from everything else they use.

9. The accessibility floor

Not a phase. A floor, and it is low:

  • Keyboard reachable, in a sensible order, with a visible focus ring. Never remove the outline without replacing it.
  • Contrast at least 4.5:1 for body text, 3:1 for large text and for the boundaries of controls.
  • Never colour alone for state — pair it with a shape, an icon or a word.
  • Labels on everything, including icon-only buttons.
  • Announce what changed. A live region for anything that updates without a page change, so it is not silent for a screen reader.
  • Respect prefers-reduced-motion.
  • Touch targets at least 44×44 px with spacing between them.
  • Test one flow with the keyboard alone, and one with a screen reader. Both take minutes and both find things.

10. Motion earns its place

In product UI, motion has one job: showing what changed and where it came from. An item moving to the place it now lives, a panel opening from the control that opened it, a row settling after a sort.

Decorative entrance animations on every card are noise at first sight and friction by the fiftieth. Keep transitions fast — 150–250ms — and skip them entirely for anything used repeatedly.

Checklist

  • One primary action per screen; everything else demoted
  • Density chosen to match how often the screen is used
  • Hierarchy from size, weight, spacing and position; a consistent spacing scale
  • Forms: labels above, one column, validate on blur, input never cleared, right keyboard
  • Tables: default sort chosen, totals shown, row action consistent, narrow-screen behaviour decided
  • Acknowledge within ~100ms; progress or handoff beyond ~10s
  • Undo preferred over confirm; destructive controls separated and never default-focused
  • One name per action everywhere; native controls not reinvented
  • Keyboard reachable with visible focus; contrast met; never colour alone; labels on icon buttons
  • Reduced motion respected; motion only where it shows what changed

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.