Design Better Skill: UX Heuristics for UI Code

What is the design-better skill?

The design-better skill sits in the skills folder of BuilderOS, a collection of agent skills from BuildGreatProducts. It is a craft layer for any coding agent that generates or reviews UI. Its aim is interfaces that feel designed, not only functional.

Style and craft are kept apart. A docs/design.md file owns colors, type and spacing tokens, while this skill owns hierarchy, interaction, accessibility, motion and polish. When the file is missing, the agent falls back to your codebase's existing conventions.

What changes in your agent's output

• Reviews cite rules by number, such as H22 for disabling an option instead of erroring after submit, and name the UX law behind a call, such as Hick's Law for too many options in one step.
• Every visual decision points at a design token by name. A token your design file lacks is flagged as a New Pattern, and nothing is hard-coded inline.
• A pre-flight checklist runs before delivery: states, labels, motion, contrast, target size, reflow at 320 CSS px and one dominant primary action.
• The closing note says which heuristic categories and laws dominated, and where one was knowingly skipped.

What the 50 heuristics cover

• Hierarchy and layout: one primary action per view, proximity and common region, snapping to the spacing scale, a 50 to 75 character reading line.
• Typography and color: documented type levels only, tabular figures in data, balanced headlines, 4.5:1 text contrast and 3:1 for UI components.
• Interaction and forms: feedback within 100 ms, easy reversal, single-column forms with top-aligned labels, the right inputmode, autocomplete and validation on blur.
• States and motion: empty, loading, error and success for every data view, skeletons over spinners, motion between 150 and 400 ms on transform and opacity.
• Accessibility, mobile and AI: WCAG 2.2 AA items, thumb-zone actions, safe-area insets, and a visible Stop control while AI responses stream.

Who the design-better skill is for

Best for

• Teams with a docs/design.md who want generated UI to follow it while also getting interaction, accessibility and state handling right.
• Reviews of a brief, a single file or an uncommitted diff, where numbered rules make feedback easy to act on.
• Projects that already use a build loop. The README lists this skill as the craft layer to pair with any build path.

Not for

• Choosing colors, fonts or a visual direction. Style comes from your design file or codebase. For another take on building interfaces, see frontend-design.
• A narrow, single-topic audit. This is a broad catalogue, so for a focused accessibility pass use accessibility-audit.
• Generating the tokens themselves. The skill reads them and flags gaps, but it does not create a design system.

Use it with UiChemy

The skill shapes the front-end code your agent writes. When that build has to live in WordPress, UiChemy AI to WordPress imports an AI build as an editable page, and Composer edits it inside Elementor or Gutenberg. Click Get Started on uichemy.com.

How to install Design Better Skill: UX Heuristics for UI Code

git clone https://github.com/BuildGreatProducts/builder-os.git

1. Clone the repository

   Run git clone https://github.com/BuildGreatProducts/builder-os.git. The skill sits in the skills/design-better folder.

2. Copy the skill folder

   Copy skills/design-better into your project's skills directory. The README gives .claude/skills/ for Claude Code as its example, and other agents use their own skills folder.

3. Add a style source

   Optional but recommended: place a docs/design.md in the project so the agent can reference tokens by name. Without it, the agent uses your theme config and CSS custom properties.

4. Trigger the skill

   Ask to design better, make this UI feel more designed, apply design polish or review this for craft, and name the file, brief or diff.

Check that it loaded

Ask the agent to review one component. It should cite heuristics by number, refer to tokens by name and run the pre-flight checklist before it finishes.

Read the official instructions on GitHub

Key features

• Fifty numbered heuristicsEach entry has a number, a short name, a one-line rule and a code action. Reviews cite them as H1 to H50, so feedback is specific and easy to track.
• Style and craft splitdocs/design.md owns style tokens and the skill owns craft. Missing tokens are flagged as New Patterns instead of inventing hex values, font names or arbitrary pixel sizes.
• Pre-flight checklistBefore delivery the agent confirms interactive states, the four data states, labelled inputs, motion rules, contrast, target size, 320 px reflow and a single dominant primary action.
• Forms done properlySingle-column layout, top-aligned labels, type and inputmode for mobile keyboards, autocomplete attributes, and validation on blur that clears on change.
• Four states for every data viewEmpty, loading, error and success are each designed and coded. Skeletons beat spinners for content, and errors say what happened, why and how to fix it.
• Motion with limitsUI motion stays in the 150 to 400 ms band, easing matches direction, only transform and opacity animate, and prefers-reduced-motion is honored.
• WCAG 2.2 AA coverageKeyboard operability, visible focus rings of at least 2 px, 24 by 24 CSS px targets, programmatic labels, focus not obscured by sticky bars and accessible authentication.
• Mobile and touch rulesPrimary actions in the thumb zone, safe-area insets on fixed bars, no hover-only critical information and a tap alternative for every drag.
• AI product patternsStreaming responses get a visible Stop control that aborts the request, and model output is treated as an editable draft with sources, retry and distinct error categories.

Frequently asked questions