agentleFS
TomSzenessyTomSzenessy/AI_TEMPLATE/.agents/skills/ux-quality/SKILL.md

ux-quality

Skill0 starsChanged 11 days agoMITView on GitHub

The UI/UX bar for building and reviewing interfaces: platform conventions (Apple HIG, Material), design tokens, every screen state, accessibility, ethical onboarding and persuasion, and screenshot review at real device sizes. Use whenever a change touches what users see or tap.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    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:

    Benchmark: put your screenshots next to the design references in docs/product/research.md.

    line 38
  2. Distinctive:

    Never deceive: no dark patterns (confirmshaming, hidden costs, forced continuity, pre-checked consent, fake urgency or social proof).

    line 89
  3. Very specific:

    Run make ui-review (mechanics in docs/building.md).

    line 109

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

UX quality

The bar for anything users see or touch. Builders apply it while working; the critic role reviews against the same list. Project-specific choices live in docs/design.md (created by product-kickoff) and override nothing here silently: record deliberate deviations there.

Foundations

  • Platform conventions first: Apple Human Interface Guidelines on iOS and macOS, Material 3 on Android, established web patterns on the web. Deviate deliberately and record why.
  • Tokens are the single source: colours, type, spacing, radius, and motion come from one tokens file (the design-tokens skill defines its format), never ad-hoc values. Check contrast with python3 .agents/skills/design-tokens/contrast.py <tokens file>.
  • Hierarchy: one primary action per screen, a consistent spacing scale, readable body text (16 px on the web, Dynamic Type on Apple platforms).

Visual bar: designed, not assembled

  • Build on proven parts: a component library and one icon set that fit the stack (for example shadcn/ui or Radix with Lucide on the web; native controls and SF Symbols or Material Symbols on mobile), styled by the tokens.
  • Rhythm: a 4 or 8 point spacing scale, three or four type sizes with a clear hierarchy, one accent colour used sparingly, consistent radius and elevation.
  • Real content: real copy, names, and data shapes; never lorem ipsum or framework defaults (favicon, titles, starter pages).
  • Life: subtle motion (150-250 ms) on state changes, immediate feedback on every tap, empty states with a helpful next action.
  • Benchmark: put your screenshots next to the design references in docs/product/research.md. If yours would look out of place among them, iterate before moving on.

Avoid the generic AI look

Defaults a model reaches for when the brief leaves the look free; each needs a reason from the product, not habit. A recorded brief in docs/design.md wins.

  • Palette: purple/indigo gradients; near-black with one neon accent and glowing edges; warm cream ground with serif display and a terracotta accent. If the look can be guessed from the category alone, redo it. Pick light or dark from where and when it is used, not the category.
  • Type: one overused display face (Inter as display, Space Grotesk, Fraunces, Playfair, DM Sans), gradient text, a kicker/eyebrow above every heading, mono type as a "technical" costume, 01/02/03 section numbers.
  • Layout: rows of same-size icon + heading + text cards, nested cards, the big-number hero-metric block, a modal for a task that needs no interruption, oversized padding everywhere.
  • Surface: decorative glass/blur, coloured border-left accents on cards and alerts, hard offset shadows outside a deliberately neobrutalist world, maximum rounding on everything, sparkline/ring filler instead of content.
  • Icons: emoji or unicode glyphs as icons; mix of stroke weights.
  • Unthemed defaults: browser text selection, caret, scrollbars, focus rings, and untabulated numerals in data tables; style them from the tokens.
  • Motion: the same entrance animation on every section; one authored moment beats scattered effects.

Every screen has every state

Empty, loading (skeletons over spinners), error (what happened and how to recover), offline, partial data, success, long or localized content, and permission denied. A screen with only the happy path is not done.

Accessibility is part of done

WCAG 2.2 AA contrast; touch targets of at least 44 pt (iOS) or 48 dp (Android); screen-reader labels; logical focus and keyboard order; respect reduced motion; layouts survive 200% text size; never use colour alone. Prove large text with a capture taken at that size, never a default-size one: xcrun simctl ui booted content_size accessibility-extra-large (reset with large), adb shell settings put system font_scale 2.0, or browser zoom 200%.

Onboarding and user psychology, used ethically

  • Time to value: let people do the core thing before sign-up when possible; ask for permissions in context, with the reason.
  • Lower effort: progressive disclosure, good defaults, few fields, recognition over recall, visible progress.
  • Feedback: respond within about 100 ms; optimistic updates where safe; prefer undo over confirmation dialogs.
  • Never deceive: no dark patterns (confirmshaming, hidden costs, forced continuity, pre-checked consent, fake urgency or social proof). Privacy and cancel choices get equal visual weight.

Copy

Plain and specific; buttons start with a verb; errors say what happened and what to do next; no blame, no jargon.

Review loop (vision-capable reviewer)

Vocabulary: audit is measurable (contrast, states, targets, responsive, performance via web-quality) and fixes nothing; critique is judgment (hierarchy, fit to the product, specificity, cognitive load: more than four visible choices at a decision point is a finding; run it with the critic role, not the builder); polish fixes what both found, in this order: blocked or inaccessible tasks, missing states, system drift, visual detail. Steps 1-2 below are audit and critique, step 3 is polish.

  1. Run make ui-review (mechanics in docs/building.md). For native apps use the simulator or emulator. Without a browser, say so and ask the owner for screenshots; never claim a visual review you did not do.
  2. Open every screenshot (you or the critic role, vision-capable) and compare it with this list, docs/design.md, the approved mockup, and the design references. In the run's entry in docs/product/ui-reviews.md, write findings and set Verdict: pass only when nothing blocks. A passing review of the current code closes a UI feature and is required before release.
  3. Fix, re-screenshot, and use parity-check's imgdiff.py --mode pixel at the same viewport and state to catch unintended changes (layout mode ignores colour and text).
  4. For key flows, walk through as a first-time user: count steps and time to the first moment of value.

UI UX Pro Max (make upstream ID=ui-ux-pro-max-design-intel): CSV data of visual styles, palettes, font pairings, chart types, motion timings and do/don't UX rules per product category. Pull the one CSV for the decision in front of you when the brief in docs/design.md leaves a style, palette, pairing or chart choice open and you would otherwise guess; skip it when the brief or tokens already decide. Read the CSV as data; never run its script.

Done when

You ran the real build and looked at it, every state exists, contrast and accessibility checks pass, screenshots were reviewed with no blocker, and deviations are recorded in docs/design.md.

Impeccable (make upstream ID=impeccable-frontend-polish): one reference per design dimension (typeset, layout, colorize, animate, harden, polish). Pull the file for the dimension a screen failed in review; skip when it passed.

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.