npm package: @lhi/ui-skill
Description: A systemic UI design skill for Claude Code, Gemini CLI, and Google Antigravity
Latest version: 2.1.2

# 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

```bash
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)

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

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

### Gemini CLI

```bash
npx @lhi/ui-skill --gemini
```

Then activate with:
```
gemini skills activate ui
```

### Google Antigravity

```bash
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

```bash
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)

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

### Material Design 3 exclusive variant

```bash
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:

```bash
# 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