ui-skill

A systemic UI design skill for AI coding agents.

Install the /ui skill into Claude Code, Gemini CLI, or Google Antigravity with a single npx command. Instead of generating isolated components, ui-skill enforces a design-system-first workflow — anchoring every output to real design tokens, running accessibility and responsiveness checks before writing code, and producing components that are production-ready out of the box.

---

Quick Start

npx @lhi/ui-skill

That's it. The skill is installed into ~/.claude/skills/ui/ and immediately available in Claude Code as /ui.

---

Installation

Claude Code (default)

npx @lhi/ui-skill
# or explicitly:
npx @lhi/ui-skill --claude

Activates as /ui in the Claude Code slash-command menu.

Gemini CLI

npx @lhi/ui-skill --gemini

Then activate with:

gemini skills activate ui

Google Antigravity

npx @lhi/ui-skill --antigravity

No command needed — Antigravity activates the skill semantically when it detects design intent in your message.

All platforms at once

npx @lhi/ui-skill --all

Detects which agent environments exist on your machine and installs to all of them.

Custom path (monorepos, project-local install)

npx @lhi/ui-skill --path ./.claude/skills

Material Design 3 exclusive variant

npx @lhi/ui-skill --material               # /ui-material → Claude Code
npx @lhi/ui-skill --material --gemini      # /ui-material → Gemini CLI
npx @lhi/ui-skill --material --antigravity # /ui-material → Google Antigravity
npx @lhi/ui-skill --material --all         # /ui-material → all platforms

Installs /ui-material — a separate skill that enforces Material Design 3 exclusively. Every colour, shape, elevation, motion curve, and component spec is locked to the M3 specification. Built for enterprise products, Google ecosystem apps, and any project where M3 compliance is required.

Options reference

SKILLS
  (default)       Install /ui — the standard design engine
  --material      Install /ui-material — Material Design 3 exclusive variant

PLATFORMS
  --claude        ~/.claude/skills/          (default)
  --gemini        ~/.gemini/skills/
  --antigravity   ~/.gemini/antigravity/skills/
  --cursor        ~/.cursor/skills/
  --codex         ~/.codex/skills/
  --all           Install to all detected platforms
  --path <dir>    Install to a custom directory

OPTIONS
  --help          Show help

---

Usage

Claude Code

Type /ui in any Claude Code session to invoke the skill directly. You can pass an argument:

/ui init
/ui build hero section
/ui theme dark-pro
/ui audit

Or describe naturally — Claude will auto-invoke the skill when it detects design intent.

Gemini CLI & Antigravity

Just describe what you want. The skill description is designed so the agent activates it semantically:

"Design a dashboard layout with a collapsible sidebar"
"Build a data table component with sorting and empty state"
"Make this card look premium — glassmorphism, subtle animations"
"Audit the current page and tell me the top 3 visual improvements"
"Add staggered entry animations to this list"

---

What the Skill Does

ui-skill runs in five modes. It detects which mode you need from context — you never have to name them.

architect — Layout & UX planning

When you describe a page or feature you're building, the skill plans the layout before touching code:

• Defines the information hierarchy (what is most important on screen)
• Chooses a layout primitive (sidebar-main, dashboard-grid, centered-content, full-bleed)
• Specifies the responsive collapse strategy at each breakpoint
• Outputs a short annotated layout plan and asks for approval before writing JSX

build — Component implementation

Builds atomic, token-driven components that are complete on delivery:

• Runs the Pre-Flight Check first (see below)
• Uses only design tokens — no hardcoded hex values
• All four interactive states defined: hover, active, focus-visible, disabled
• Accepts a className prop for external overrides (shadcn pattern)
• Skeleton loaders and empty states always included unless the component is a pure primitive

theme — Design token systems

Generates or applies a full token set:

• Three background layers (base, subtle, raised)
• Foreground hierarchy (primary, secondary, muted, disabled)
• Brand colours with hover/active variants
• Semantic colours (success, warning, error, info)
• CSS custom properties in :root and .dark, mapped to a Tailwind config extension

Named themes (expand with specifics on request):

Theme	Aesthetic
minimal-light	Neutral greys, single accent, generous whitespace
dark-pro	Deep zinc backgrounds, subtle borders, electric accent
glass	Frosted glass surfaces, high-blur, light border overlays
cyberpunk	Neon accent on near-black, grid overlays, sharp geometry

motion — Animations & micro-interactions

Adds purposeful motion using Framer Motion or CSS transitions:

• Fade-in and stagger patterns for content areas and lists
• Spring physics for modals, drawers, and cards (physical feel)
• Button press feedback (scale, shadow response)
• Number counter animations for dashboards
• All animations wrapped in a prefers-reduced-motion guard

audit — Visual quality review

Scores the current UI across seven categories and returns ranked, actionable fixes:

## UI Audit Report

Score: 6.5 / 10

| Category           | Score |
|--------------------|-------|
| Visual Hierarchy   |  7/10 |
| Typography         |  6/10 |
| Depth & Layering   |  5/10 |
| Interactive States |  6/10 |
| Responsiveness     |  8/10 |
| Accessibility      |  6/10 |
| Motion             |  6/10 |

Top 3 improvements (highest ROI first):

1. [Depth & Layering] — specific fix with before/after code
2. [Interactive States] — specific fix with before/after code
3. [Accessibility] — specific fix with before/after code

Every finding includes a concrete before/after code snippet. No vague feedback.

---

Pre-Flight Check

Before writing any code, the skill verifies four things and reports what it finds:

1. Design System Anchor Looks for DESIGN.md, design-tokens.css, or tailwind.config. If found, reads it and honours every token decision. If not found, proposes a minimal token set (4 brand colours, 1 type scale, 4 spacing steps) before building anything.

2. Accessibility

• Text contrast meets WCAG AA (4.5:1 body, 3:1 large text)
• Interactive elements have aria-label or visible label
• Focus states are visible and not removed without a replacement

3. Responsive Strategy

• Layout is mobile-first
• Defined behaviour at sm, md, and lg breakpoints
• No fixed pixel widths on containers

4. Performance

• Images use next/image or native loading="lazy"
• Animations respect prefers-reduced-motion
• No oversized inline assets

---

Visual Fidelity Rules

These are the specific rules that separate a functional UI from a polished one. The skill enforces all of them on every build.

Depth & Layering Layer two shadows: one tight and dark for depth, one wide and soft for ambient light. Use backdrop-blur on floating surfaces. Use border-black/8 (rgba(0,0,0,0.08)) instead of border-gray-200 — it adapts to themes.

Dynamic States Every interactive element must define all four states — hover, active, focus-visible, disabled — with smooth transitions (duration-150). No exceptions.

Typography

• Headings: tracking-tight leading-tight (letter-spacing −0.02em to −0.04em)
• Body: tracking-normal leading-relaxed (line-height 1.6–1.75)
• Labels: tracking-widest text-xs uppercase
• Never more than 2 font weights in a single component

Empty & Loading States A finished component is never broken when empty. Skeleton loaders use animate-pulse with geometry that matches the real layout. Empty states have an icon, heading, and optional CTA — never just "No data."

---

Project Structure

When scaffolding a new project or adding the first component, the skill ensures this structure exists:

src/
├── components/
│   ├── ui/          # Primitives: Button, Input, Card, Badge, Avatar
│   └── features/    # Domain patterns: DataTable, UserCard, Sidebar
├── hooks/           # Logic isolated from rendering
├── lib/
│   └── utils.ts     # cn() — Tailwind class merging (clsx + tailwind-merge)
└── styles/
    ├── globals.css  # CSS custom properties / design tokens
    └── tokens.ts    # JS-accessible token constants

---

Bundled References

The skill loads detailed guides from references/ on demand — keeping the main SKILL.md focused while making deep knowledge available when needed.

File	Contents
design-tokens.md	Full CSS custom property system, dark mode variants, and complete Tailwind config mapping
motion-patterns.md	Framer Motion recipe library: fade-in, stagger, spring modal, drawer, skeleton, number counter
component-patterns.md	Full implementations of Button, Card, Input, Badge, and EmptyState with all states
visual-fidelity.md	Deep-dives on layered shadows, glassmorphism, border opacity, typography scale, and contrast tables

---

Contributing

Issues and pull requests welcome. The skill lives in skills/ui/SKILL.md — most improvements go there or in the references/ files.

To test locally before publishing:

# Install to a local test path
node bin/install.js --path /tmp/ui-skill-test

# Verify the output
ls /tmp/ui-skill-test/ui

---

License

MIT