Skip to content
Skills Library
Design & UX · Building & coding

ui-component-builder

/ui-component-builder

Build production-ready UI components with accessibility, loading/empty/error states, responsive behavior, and reusable props — not retrofitted polish. Use when creating a new component. To review an existing UI use /design-review instead.

Licence
MIT
Last repository change
21.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Build production-ready UI components with accessibility, loading/empty/error states, responsive behavior, and reusable props — not retrofitted polish. Use when creating a new component. To review an existing UI use /design-review instead.

Original author description

Build production-ready UI components with accessibility, loading/empty/error states, responsive behavior, and reusable props — not retrofitted polish. Use when creating a new component. To review an existing UI use /design-review instead.

How it works

  1. Core Rule
  2. Kit Context
  3. When to Use
  4. When NOT to Use
  5. Hard Rules
  6. Process
  7. Output Format
  8. Notes
Original SKILL.md headings · 265 lines, 1,523 words
SKILL.md preview
---
name: ui-component-builder
description: Build production-ready UI components with accessibility, loading/empty/error states, responsive behavior, and reusable props — not retrofitted polish. Use when creating a new component. To review an existing UI use /design-review instead.
user-invocable: true
---

# UI Component Builder

## Core Rule

Production-ready means accessibility, states (loading/empty/error), edge cases, and responsive behavior are designed first — not retrofitted after the happy path ships.

## Kit Context

Before starting:

1. Read `CODEBASE_MAP.md` to identify the project's UI stack and component conventions
2. Read `DESIGN.md` if it exists — it is the source of truth for tokens, colors, typography, spacing
3. Read `CLAUDE.project.md` if it exists — project-specific UI rules override kit defaults
4. Read any framework-specific docs in `agent_docs/project/` (e.g., Next.js conventions, design system docs)

If a component library is already in use (shadcn, MUI, Chakra, Radix, custom), build on top of it — do not introduce a parallel system.

## When to Use

Invoke with `/ui-component-builder <component-name>` when:

- A new reusable UI component is needed (button, modal, table, form field, card, etc.)
- An existing one-off piece of UI needs to be extracted into a reusable component
- A component needs to be redesigned to meet production standards (accessibility, states, responsive)
- You want a component-architecture review *before* writing the implementation

## When NOT to Use

- For pages, routes, or layouts — those are application composition, not component design
- For trivial wrappers (a 5-line styling div) — inline is fine
- For full app scaffolding — combine `/shape-spec` with stack-specific tooling
- For pure visual review of existing components — use `/design-review`
- For pure accessibility audit of existing components — use `/accessibility-audit`

## Hard Rules

- **No new design tokens without DESIGN.md.** If colors, spacing, or typography need extending, stop and ask. New tokens are a Protected Change.
- **Accessibility is not optional.** Every interactive component must be keyboard-navigable, have correct ARIA semantics, and pass WCAG 2.1 AA contrast.
- **States are required, not optional.** Loading, empty, error, and disabled states must be considered before the component is "done." Skipping them is shipping a demo, not a component.
- **Match existing style.** If the project uses controlled inputs, do not introduce uncontrolled ones. If it uses Tailwind, do not introduce CSS modules.
- **No props soup.** If a component grows past ~8 props, split it or use composition (slots/children). The skill must surface this trade-off explicitly.

## Process

### Phase 1: Context Gathering

Establish what the component must fit into:

1. **Identify the stack** — React/Vue/Svelte/Solid? TypeScript? Styling system (Tailwind, CSS-in-JS, modules)?
2. **Locate the component library** — shadcn, MUI, Radix, Chakra, custom? Where do components live (`components/ui/`, `app/_components/`, etc.)?
3. **Find similar existing components** — pattern-match: is there a `Button` you should mirror? An existing `Modal` whose API you should follow?
4. **Check design tokens** — extract from `DESIGN.md`, Tailwind config, theme files
5. **Note the consumers** — who will use this component? Forms? Lists? Modals?

Output of this phase: a short brief showing what you found. Do not skip — building components without locating prior art produces duplication.

### Phase 2: Component Architecture

Before writing code, design the shape:

**API surface**
- Name (clear, domain-appropriate, not generic like `Wrapper`)
- Props — required vs optional, controlled vs uncontrolled
- Slots / children patterns — for composition
- Imperative API (refs, methods) — only if absolutely needed
- Events / callbacks — naming convention from the project (`onChange` vs `onValueChange`)

**Composition strategy**
- Single component vs compound components (e.g., `<Select>`, `<Select.Item>`)
- Headless logic + styled wrapper (when reuse across themes matters)
- Single source of truth for state (controlled by default in form inputs)

**States to enumerate**

| State | Required? | Notes |
|---|---|---|
| Default | Always | The happy path |
| Hover / Focus | Interactive components | Visual + keyboard |
| Active / Pressed | Interactive components | Tactile feedback |
| Disabled | If component can be disabled | `aria-disabled` + style |
| Loading | If async work happens | Spinner / skeleton / shimmer |
| Empty | If component renders a collection | Helpful message + action |
| Error | If component can fail | Clear message + recovery path |
| Read-only | If editing can be locked | Visually distinct from disabled |

### Phase 3: Edge Cases & Responsive

Enumerate before implementation:

**Edge cases**
- Long content (overflow, truncation, wrap)
- No content (empty array, null, undefined)
- Many items (virtualization threshold? pagination?)
- Slow network (loading state visible?)
- Failed network (error state visible?)
- RTL languages (if i18n applies)
- Very long strings without spaces (`overflow-wrap: anywhere`)

**Responsive**
- Mobile (320-480px) — touch targets ≥44px, single column, no horizontal scroll
- Tablet (768-1024px) — adapt layout, not just shrink desktop
- Desktop (1280+) — readable line lengths (45-75 chars)
- Container queries when the component lives in variable-width slots

**Accessibility**
- Semantic HTML first (`<button>` not `<div onClick>`)
- Keyboard: Tab, Shift+Tab, Enter, Space, Esc — all must work
- ARIA: `role`, `aria-label`, `aria-describedby`, `aria-expanded`, etc. — only when semantic HTML doesn't cover it
- Focus management — visible focus ring, focus trap in modals, focus return on close
- Screen reader — labels, live regions for dynamic content, announcement of state changes
- Contrast — WCAG AA: 4.5:1 normal text, 3:1 large text and UI components

### Phase 4: Implementation

Now write the component. Order matters:

1. **Types / interfaces first** — define the contract before the body
2. **Semantic markup** — start with the right HTML element
3. **Accessibility wiring** — ARIA, keyboard handlers, focus management
4. **Styling** — using the project's system (Tailwind classes, CSS variables, etc.)
5. **States** — implement each enumerated state, not just the default
6. **Composition hooks** — `children`, slots, render props as appropriate
7. **Tests** — at minimum: renders, handles primary interaction, respects disabled state

Code example (React + TypeScript + Tailwind, adapt to your stack):

```tsx
type ButtonProps = {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  loading?: boolean
  disabled?: boolean
  leftIcon?: React.ReactNode
  rightIcon?: React.ReactNode
  children: React.ReactNode
} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'>

export function Button({
  variant = 'primary',
  size = 'md',
  loading = false,
  disabled = false,
  leftIcon,
  rightIcon,
  children,
  className,
  ...rest
}: ButtonProps) {
  const isDisabled = disabled || loading

  return (
    <button
      type="button"
      aria-busy={loading || undefined}
      aria-disabled={isDisabled || undefined}
      disabled={isDisabled}
      className={cn(buttonStyles({ variant, size }), className)}
      {...rest}
    >
      {loading ? <Spinner aria-hidden="true" /> : leftIcon}
      <span>{children}</span>
      {!loading && rightIcon}
    </button>
  )
}
```

### Phase 5: Documentation

Every reusable component ships with:

- **Props table** — name, type, default, description
- **Usage examples** — at least three: minimal, common, advanced
- **Accessibility notes** — keyboard shortcuts, ARIA roles in use, known limitations
- **Visual states** — list each state with when it appears

If the project has Storybook, MDX, or a docs site, add a story / page. Otherwise, put usage examples in a comment block at the top of the file.

## Output Format

When the skill runs, deliver the component as a structured package:

```markdown
# Component: <Name>

## Architecture Brief

- **Stack:** <framework + styling + types>
- **Library context:** <existing components mirrored / extended>
- **Composition pattern:** <single / compound / headless>
- **Why this shape:** <one paragraph rationale>

## Props API

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| ... | ... | ... | ... | ... |

## States Enumerated

| State | Visual treatment | Interaction |
|---|---|---|
| Default | ... | ... |
| Loading | ... | ... |
| Empty | ... | ... |
| Error | ... | ... |
| Disabled | ... | ... |

## Edge Cases Handled

- Overflow: <strategy>
- No content: <empty state design>
- Failed load: <error recovery>
- Long strings: <wrap behavior>
- RTL: <handled / not applicable>

## Responsive Behavior

| Breakpoint | Adaptation |
|---|---|
| Mobile (320-480px) | ... |
| Tablet (768-1024px) | ... |
| Desktop (1280+) | ... |

## Accessibility

- **Semantic HTML:** <element + reason>
- **Keyboard:** Tab / Enter / Space / Esc — what each does
- **ARIA:** <attributes used and why>
- **Focus management:** <strategy>
- **Contrast:** <ratios met>

## Implementation

<code, in the project's conventions>

## Usage Examples

### Minimal
<code>

### Common case
<code>

### Advanced / composed
<code>

## Tests

<test file or test outline>

## Open Questions

<anything that requires user input — design tokens to add, ambiguous behavior, scope to confirm>
```

## Notes

- This skill **produces** components, unlike `/design-review` and `/accessibility-audit` which **review** them. Use those after this skill ships a component to catch what slipped through.
- If the user asks for "a quick button" — push back gently. Either it is a one-off (then inline it, no skill needed) or it is reusable (then states and accessibility are not optional).
- For component **libraries** (10+ components with shared system), invoke `/shape-spec` first to capture the system-level decisions, then run this skill per component.
- When a component is being **refactored**, also run `/refactoring-guide` to plan the migration of existing call sites.
- If the project lacks a `DESIGN.md`, surface this as an open question — building production components without tokens is a recipe for inconsistency.

Versions

The database has no other skills named ui-component-builder.

Database snapshot: 13.11.2026 · package version 698b0da89955 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100frontend-component-build
    Build production-ready frontend components with accessible markup, sensible props, defined states, and tested behavior. Use this skill whenever the user wants to build a component from scratch, refactor an existing one, design a component API, or implement a UI element with…
  • 100responsive-design-system
    Use when multiple pages or products need coherent responsive components and patterns. Create a reusable responsive component system with predictable tokens and states. Do not use when one-off graphic or single nonreusable visual.
  • 90ui
    Build, review, polish or restyle a screen, component or flow (web, SwiftUI, Compose, React Native, desktop) with all states, motion and a11y. Use when asked to "make this look better", "review the UI/UX", "polish", "feels janky", add loading/empty/error states, animate, or fix a…
  • 90component-builder
    Build new interface components and bounded composition patterns inside an existing project. Use for named components, interface blocks, and workspaces. Preserve the target project's design system and stack; for a complete new page with page-level structure and multiple sections,…
  • 90ux-flow
    Maps a user journey end to end, including error, empty, loading, permission and edge paths, as a step table and mermaid flowchart. Use for signup, onboarding, checkout, the core task, settings or any multi-step interaction before it is designed or built.
  • 100components
    Build composable UI with a small public props contract, loading/error/empty states, Reicon icons by default, and mobile-first layout. Use when implementing or refactoring pages, screens, components, dialogs, tables, navigation, “buat component”, “prop terlalu banyak”, “API…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.