better-web-ui

better-web-ui is an opinionated Agent Skills library for developers who can ship code just fine but would prefer the UI not look like it was assembled during a sleep-deprived Figma incident.

It helps AI coding agents generate, critique, refine, and systematize production-grade UI, UX, and motion work without defaulting to bland, generic output. In other words: it's for people who know the difference between “works” and “wow” and would like help crossing that gap without pretending they woke up as a principal product designer.

This repository is a skills package, not a starter app or deployment template.

The project follows the Agent Skills format and is designed to be installed through the skills CLI.

Direct skills.sh links

If search is being moody, use the direct directory pages:

• Creator page on skills.sh
• Repository page on skills.sh
• Example skill page: add-ui

The most reliable install command is still:

npx skills add aladicf/better-web-ui

Inspired by

• Impeccable — by Paul Bakaus

• Anthropic's upstream better-web-ui / frontend-design lineage — by Anthropic

• animations.dev and related motion-heavy UI work — by Emil Kowalski

• Refactoring UI — by Adam Wathan and Steve Schoger

• Design for Developers — by Adrian Twarog and George Moller

• Laws of UX — by Jon Yablonski

See NOTICE.md for the fuller attribution chain and source lineage.

What is this package for

Use better-web-ui when you want an agent to help with:

• generating multiple UI directions for new or existing sections, pages, shells, and components
• improving hierarchy, spacing, typography, color, and overall visual quality
• reviewing interfaces for UX issues, accessibility, performance, and polish
• designing empty states, onboarding, motion, depth, and stronger interaction details
• extracting reusable patterns and bringing drifted UI back in line with a system

This library is intentionally opinionated. It optimizes for distinctive, high-context, production-grade interfaces rather than lowest-common-denominator UI.

What it works with

better-web-ui is purposefully framework-agnostic so that everyone can benefit from it.

It is also stack-aware enough to respect what a project already uses.

It works with:

• React, Next.js, React Router, TanStack Start and Vite.
• Vue and Nuxt
• Svelte and SvelteKit
• Astro
• Solid and SolidStart
• plain HTML, CSS, and JavaScript
• custom design systems and in-house component libraries

It also adapts to common styling approaches such as Tailwind CSS, CSS modules, CSS-in-JS, token-based design systems, and vanilla CSS.

When a project already has an established stack, agents should match it first. When the stack is still open, the library provides pragmatic defaults and reference guidance rather than forcing one universal setup.

Installation

Install from GitHub:

npx skills add aladicf/better-web-ui

You can also browse the live directory entry directly on skills.sh:

• Creator page
• Repository page

Useful variations:

npx skills add aladicf/better-web-ui --list
npx skills add aladicf/better-web-ui --all
npx skills add aladicf/better-web-ui --skill add-ui --skill critique
npx skills add aladicf/better-web-ui -g

The external skills CLI owns the interactive install UI, the --all behavior, and the host-to-wrapper-root routing. This repository ships compatibility wrappers for multiple host layouts — including .github/skills for GitHub Copilot / VS Code, .cursor/skills for Cursor, plus the other supported roots listed below — but it does not contain the editor-detection logic that decides which wrapper root or wrapper-root set gets written during installation.

If a GitHub Copilot / VS Code install lands in .agents/skills instead of .github/skills, or if the interactive picker does not show an obvious install-all option at the top, that behavior is coming from the upstream skills CLI rather than from the canonical skills in this repository. As a current workaround, use npx skills add aladicf/better-web-ui --all when you want every skill without manually selecting each entry.

For contributor setup, local installs, and maintainer commands, see DEVELOPMENT.md.

First thing to do after installing

Run /setup first. Yes, before you go off and build the thing.

• Starting a new project? Run /setup so the skill learns your preferred framework, styling library, component library, and visual direction instead of hallucinating a stack with confidence.
• Installing into an existing or older project? Run /setup so the skill learns what is already there, or tell it explicitly which framework, styling library, and component library it should preserve.

/setup writes that context to .better-web-ui.md, so later sessions can keep your project-specific setup instead of guessing.

Upgrading from older installs

Upgrading from an older install such as 1.5.x is simple:

1. Reinstall the library with the same scope you use now (--all or the same --skill ... set).
2. Keep project-specific setup in .better-web-ui.md, not inside installed skill files.
3. If you still have legacy .impeccable.md context, migrate it into .better-web-ui.md.
4. Re-run /setup only if your product context, stack, or preferred libraries changed.

That is the whole trick: upgrade the library, keep your project specifics in .better-web-ui.md, and newer versions can improve without wiping your setup.

How to use it

Most hosts expose installed skills either as slash commands or through natural-language prompting.

Example prompts:

• /add-ui hero section for a B2B security product homepage
• /add-ui redesign this existing landing page while keeping the current section structure; explore five distinct directions through style, color, copy, and typography
• /add-ui redesign our existing login/register flow, keep the bones familiar, and give me compare-and-contrast options before applying one
• /critique this analytics dashboard for hierarchy and cognitive load
• /audit this checkout form for accessibility and performance issues
• /setup design context for a calm, trustworthy budgeting app
• Use animate to improve the motion and feedback in this drawer flow.

If a host does not surface slash commands clearly, users can still ask for a skill by name in plain language.

What functionality it includes

At a high level, better-web-ui covers four kinds of work:

Generate and shape UI

• create multiple UI directions with add-ui, including redesigns of existing sections, pages, and flows when the user wants to preserve the recognizable structure but evolve the style and messaging
• improve layout, responsiveness, hierarchy, typography, color, depth, imagery, and motion
• simplify cluttered surfaces and strengthen action clarity

Review and diagnose problems

• critique overall UX quality, hierarchy, IA, and cognitive load with critique
• run measurable accessibility, performance, responsive, theming, and anti-pattern checks with audit
• improve performance-sensitive UI with optimize

Handle specific product moments

• design onboarding with onboard
• improve empty states with empty-state
• tighten UX copy with clarify
• harden edge cases, overflow, i18n, and resilience with harden

Systematize and finish work

• extract reusable patterns with extract
• normalize drifted UI with normalize
• improve legacy or partially migrated surfaces with lower-risk modernization guidance
• add polish, delight, boldness, or restraint depending on what the interface needs

Shared design doctrine

The canonical shared reference set lives under skills/frontend-design/reference/.

If you want the map of the map, start with the frontend-design reference index.

For a maintainer-oriented doctrine map and validation workflow, use DEVELOPMENT.md.

Skill catalog

Meta and setup

• frontend-design — core design operating model and shared reference set
• setup — gather and persist project design context

Execution skills

• add-ui — generate 5 distinct UI directions for a requested new or existing section, page, flow, shell, or component, then help preview and apply one
• adapt — responsive and context-aware adaptation
• animate — motion, transitions, gestures, and micro-interactions
• arrange — layout composition, grouping, and spacing rhythm
• clarify — UX writing and copy clarity
• colorize — color systems and semantic color
• depth — elevation, layering, and depth systems
• distill — declutter and simplify noisy UI
• empty-state — design useful zero-data and no-results states
• extract — pull repeated UI into reusable components, patterns, and tokens
• harden — edge cases, i18n, errors, overflow, and resilience
• hierarchy — priority, emphasis, and action clarity
• imagery — screenshots, icons, photos, and media treatment
• normalize — bring drifted UI back into alignment with the design system
• onboard — first-run, activation, and onboarding strategy that gets users to value quickly
• typeset — typography, readability, and type hierarchy

Review and finishing

• audit — technical UI quality checks with scored findings and severity ratings
• critique — UX and design critique with scores and prioritized issues across the overall interface
• delight — add tasteful personality and memorable moments once the fundamentals are already working
• polish — final pass for alignment, consistency, and micro-detail quality
• quieter — reduce visual intensity without losing hierarchy or character
• bolder — increase visual confidence, contrast, and impact when the design feels too safe or generic

Advanced / specialized

• optimize — UI performance and rendering optimization
• showcase — ambitious, standout, technically impressive UI work

Quick skill picker for common ambiguities

If the problem is...	Use this	Not that
overall UX quality, hierarchy, IA, or cognitive load	critique	audit or polish
measurable accessibility, performance, responsive, theming, or anti-pattern checks	audit	critique
final alignment, consistency, and detail cleanup after the structure already works	polish	critique or audit
too many controls, choices, features, or competing elements	distill	quieter
structure is sound but the UI is too loud, saturated, or aggressive	quieter	distill
the UI feels too bland, safe, or underpowered	bolder	distill or quieter

The canonical source of truth for every skill lives under skills/.

Compatibility wrapper trees

This repo also ships generated compatibility wrappers so one canonical skill library can surface in multiple agent layouts.

• .agents/skills
• .github/skills
• .claude/skills
• .codex/skills
• .cursor/skills
• .opencode/skills
• .pi/skills

Those wrapper trees are shims only. Canonical edits belong in skills/. Maintainer workflow details live in DEVELOPMENT.md and repository-specific editing rules live in AGENTS.md.

Contributing

• CONTRIBUTING.md — pull request expectations and quality bar
• DEVELOPMENT.md — maintainer commands, validation, and local setup
• AGENTS.md — repository-specific rules for coding agents

License

This project uses the custom better-web-ui License in LICENSE.

It is MIT-based but adds source-availability and no-resale restrictions for the library itself, so it should not be described as plain MIT.