Skip to main content
Agent skill

Shep:Ui Component

Use when creating, modifying, or reviewing web UI components. Triggers include "new component", "add component", "create UI", "build a widget", "update component", working with files in src/presentation/web/components/, or when the user asks to build any React component for the web UI. Part of the Shep autonomous SDLC platform — https://shep.bot

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Shep:Ui Component when an AI agent needs a reusable SKILL.md workflow for this job: Use when creating, modifying, or reviewing web UI components. Triggers include "new component", "add component", "create UI", "build a widget", "update component", working with files in src/presentation/web/components/, or when the user asks to build any React component for the web UI. Part of the Shep autonomous SDLC platform — https://shep.bot

When not to use it

Skip Shep:Ui Component when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/shepui-component
# Save SKILL.md to ~/.claude/skills/shepui-component/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/shepui-component/SKILL.md. For a shared project, commit the folder at .claude/skills/shepui-component/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Shep:Ui Component skill for this task: Use Shep:Ui Component when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
62/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Web UI Component Development

Build React components following the four-tier architecture, with mandatory Storybook stories, `data-testid` attributes, and unit tests.

## Four-Tier Hierarchy

``` Tier 0: ui/ -> shadcn/ui primitives (managed by CLI, rarely hand-edited) Tier 1: common/ -> Reusable composed components (combine ui/ primitives) Tier 2: layouts/ -> Page shells, structural wrappers (use ui/ + common/) Tier 3: features/ -> Domain-specific views bound to routes (use all tiers) ```

**Import rule:** A tier may only import from lower tiers, never upward.

``` features/ -> layouts/, common/, ui/ layouts/ -> common/, ui/ common/ -> ui/ ui/ -> external packages only ```

## File Structure

### Tier 0 (ui/) — flat files, no subfolder

``` components/ui/ button.tsx button.stories.tsx ```

### Tier 1-3 — subfolder per component

``` components/common/feature-list-item/ feature-list-item.tsx # Implementation feature-list-item.stories.tsx # Storybook stories (MANDATORY) index.ts # Barrel export ```

**Barrel export template:**

```typescript export { FeatureListItem } from './feature-list-item'; export type { FeatureListItemProps } from './feature-list-item'; ```

After creating any Tier 1-3 component, add it to the tier-level barrel:

- `components/common/index.ts` - `components/layouts/index.ts` - `components/features/index.ts`

## Component Template

```typescript 'use client'; // Only if the component uses hooks, event handlers, or browser APIs

import { cn } from '@/lib/utils';

export interface MyComponentProps { /** Brief prop description. */ label: string; className?: string; }

export function MyComponent({ label, className }: MyComponentProps) { return ( <div data-testid="my-component" className={cn('base-classes', className)} > {label} </div> ); } ```

### Rules

1. **Named exports only** — no default exports for components. 2. **`'use client'`** — add only when the component uses hooks, event handlers, or browser APIs. Omit for pure render components. 3. **`className` prop** — accept and merge via `cn()` for composability. 4. **Props interface** — always export the interface alongside the component.

## data-testid Convention

Every component MUST include `data-testid` on its root element for test targeting.

### Naming scheme: `kebab-case`, scoped to the component

| Component | data-testid | | ----------------------- | ------------------------- | | `FeatureListItem` | `feature-list-item` | | `FeatureStatusGroup` | `feature-status-group` | | `SidebarCollapseToggle` | `sidebar-collapse-toggle` | | `PageHeader` | `page-header` |

### Sub-elements: append a suffix

```typescript <div data-testid="feature-list-item"> <span data-testid="feature-list-item-label">{name}</span> <span data-testid="feature-list-item-meta">{duration}</span> </div> ```

### When to add data-testid

- Root element of every component: **always** - Sub-elements: only when tests need to target them specifically (labels, meta, actions) - Primitives in `ui/`: use `data-slot` instead (shadcn convention)

### In tests, prefer data-testid queries

```typescript screen.getByTestId('feature-list-item'); screen.getByTestId('feature-list-item-meta'); ```

Fall back to role/text queries when `data-testid` is not set:

```typescript screen.getByRole('button', { name: /submit/i }); screen.getByText('Auth Module'); ```

## Storybook Stories (MANDATORY)

Every component MUST have a colocated `.stories.tsx` file. This is non-negotiable.

### Story template

```typescript import type { Meta, StoryObj } from '@storybook/react'; import { MyComponent } from './my-component';

// IMPORTANT: Use explicit type annotation, NOT `satisfies Meta<>` const meta: Meta<typeof MyComponent> = { title: 'Composed/MyComponent', // See title prefixes below component: MyComponent, parameters: { layout: 'padded', // 'centered' | 'padded' | 'fullscreen' }, tags: ['autodocs'], };

export default meta; type Story = StoryObj<typeof meta>;

export const Default: Story = { args: { label: 'Example', }, }; ```

### Title prefixes by tier

| Tier | Prefix | Example | | ----------- | ------------- | -------------------------- | | `ui/` | `Primitives/` | `Primitives/Button` | | `common/` | `Composed/` | `Composed/FeatureListItem` | | `layouts/` | `Layout/` | `Layout/AppSidebar` | | `features/` | `Features/` | `Features/VersionPage` |

### Decorators for context-dependent components

If the component requires a React context (e.g. `SidebarProvider`), wrap it:

```typescript const meta: Meta<typeof SidebarNavItem> = { // ... decorators: [ (Story) => ( <SidebarProvider> <SidebarMenu> <Story /> </SidebarMenu> </SidebarProvider> ), ], }; ```

Story-level decorator overrides (e.g. for alternate states):

```typescript export const Collapsed: Story = { args: { /* ... */ }, decorators: [ (Story) => ( <SidebarProvider defaultOpen={false}> <Story /> </SidebarProvider> ), ], }; ```

### Args and Controls (CRITICAL)

Storybook controls only appear when stories define `args`. **Never use hardcoded render-only stories** — always define `args` so the Controls panel works.

**Standard components (flat props):** Use `component` in meta and `args` in stories. Controls are auto-generated.

```typescript const meta: Meta<typeof MyComponent> = { component: MyComponent, args: { label: 'Default label', variant: 'primary', }, };

export const Default: Story = { args: { label: 'Example', }, }; ```

**Wrapped/nested-data components (e.g. React Flow nodes):** When a component receives data through a nested object (like `{ data }`) or requires wrapper context that prevents using `component` directly, use the **existing data interface** as the args type. Storybook auto-infers controls from the `args` values — no `argTypes` needed. Do NOT create a duplicate args interface.

```typescript import type { FeatureNodeData } from './feature-node-state-config';

// 1. Use the component's own data interface — controls auto-inferred from args const meta: Meta<FeatureNodeData> = { title: 'Composed/FeatureNode', args: { name: 'Auth Module', state: 'running', progress: 45, featureId: '#f1', lifecycle: 'requirements' }, };

type Story = StoryObj<FeatureNodeData>;

// 2. Pass args directly as data — no mapping function needed export const Default: Story = { render: (args) => <FeatureNode id="n1" data={args} type="featureNode" />, };

// 3. Stories needing callbacks pass them via story-level args export const WithAction: Story = { args: { onAction: () => undefined, onSettings: () => undefined }, render: (args) => <FeatureNode id="n1" data={args} type="featureNode" />, }; ```

Only add `argTypes` when you need to **override** defaults (e.g. `select` dropdown instead of free text, `range` slider instead of number input, or `{ table: { disable: true } }` to hide a field).

**Gallery/showcase stories** (AllStates, AllLifecycles) may use hardcoded render without args — controls are not useful when showing all variants at once. But the **Default** story must always have args.

### Story coverage requirements

Stories must cover:

- **Default state** — component with typical props - **All meaningful variants** — each status, size, or visual variant - **Edge cases** — empty content, long text, missing optional props - **Interactive states** — with click handlers (use `() => alert('Clicked!')` or `fn()` from `@storybook/test`)

### Layout parameter guidelines

| Layout | When to use | | ------------ | --------------------------------------------------- | | `centered` | Small, standalone primitives (Button, Badge, Input) | | `padded` | Medium composed components (ListItem, Card, Header) | | `fullscreen` | Full-width layouts (Sidebar, Dashboard, Page) |

## Unit Tests

### File location

Mirror the component tier structure under `tests/unit/presentation/web/`:

``` tests/unit/presentation/web/ button.test.tsx # ui/ tier common/feature-list-item.test.tsx # common/ tier layouts/app-sidebar.test.tsx # layouts/ tier features/version-page-client.test.tsx # features/ tier ```

### Test template

```typescript import { describe, it, expect, vi } from 'vitest'; import { render, screen } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import { MyComponent } from '@/components/common/my-component';

describe('MyComponent', () => { it('renders label text', () => { render(<MyComponent label="Hello" />); expect(screen.getByTestId('my-component')).toBeInTheDocument(); expect(screen.getByText('Hello')).toBeInTheDocument(); });

it('fires onClick when clicked', async () => { const handleClick = vi.fn(); const user = userEvent.setup(); render(<MyComponent label="Click me" onClick={handleClick} />); await user.click(screen.getByTestId('my-component')); expect(handleClick).toHaveBeenCalledOnce(); });

it('applies custom className', () => { render(<MyComponent label="Styled" className="custom-class" />); expect(screen.getByTestId('my-component')).toHaveClass('custom-class'); }); }); ```

### Context-dependent component helper

```typescript import { SidebarProvider } from '@/components/ui/sidebar';

function renderWithSidebar(ui: React.ReactElement) { return render(<SidebarProvider>{ui}</SidebarProvider>); } ```

### Timer/interval testing

```typescript beforeEach(() => vi.useFakeTimers()); afterEach(() => vi.useRealTimers());

it('updates after 1 second', () => { vi.setSystemTime(Date.now()); render(<ElapsedTime startedAt={Date.now()} />); act(() => vi.advanceTimersByTime(1000)); expect(screen.getByText('00:01')).toBeInTheDocument(); }); ```

## Styling Patterns

### Tailwind + cn() for conditional classes

```typescript import { cn } from '@/lib/utils';

<div className={cn( 'flex items-center gap-2 rounded-md px-2', isActive && 'bg-sidebar-accent text-sidebar-accent-foreground', className )} /> ```

### CVA for variant-driven components

```typescript import { cva, type VariantProps } from 'class-variance-authority';

const myVariants = cva('base-classes', { variants: { variant: { default: 'bg-primary text-primary-foreground', outline: 'border bg-background', }, size: { default: 'h-9 px-4', sm: 'h-7 px-3 text-xs', }, }, defaultVariants: { variant: 'default', size: 'default', }, }); ```

### Design tokens — use semantic color names

``` bg-background, text-foreground # Page-level bg-primary, text-primary-foreground # Brand actions bg-muted, text-muted-foreground # De-emphasized bg-sidebar-accent # Sidebar hover/active text-destructive # Errors border, bg-input # Form elements ```

### Numeric display: always use `tabular-nums`

```typescript <span className="tabular-nums">05:30</span> ```

### Icons: lucide-react

```typescript import { Home, CircleAlert, Loader2 } from 'lucide-react'; import type { LucideIcon } from 'lucide-react';

// As prop type interface Props { icon: LucideIcon; }

// Semantic icon coloring <CircleAlert className="text-amber-500" /> <Loader2 className="text-blue-500 animate-spin" /> <CircleCheck className="text-emerald-500" /> ```

## Checklist

Before considering a component done, verify:

- [ ] Component file created with proper structure - [ ] `data-testid` on root element (and sub-elements where needed) - [ ] Props interface exported - [ ] `className` prop accepted and merged via `cn()` - [ ] Barrel export (`index.ts`) created - [ ] Tier-level barrel updated (`common/index.ts`, etc.) - [ ] Storybook stories colocated with all variants covered - [ ] Default story has `args` defined (controls must work) - [ ] Stories use explicit `Meta<typeof X>` type annotation (not `satisfies`) - [ ] Story title uses correct tier prefix (`Primitives/`, `Composed/`, `Layout/`, `Features/`) - [ ] Unit test created in `tests/unit/presentation/web/[tier]/` - [ ] `pnpm typecheck:web` passes - [ ] `pnpm test:single tests/unit/presentation/web` passes - [ ] `pnpm build:storybook` passes

## Common Mistakes

- **`satisfies Meta<>`** — causes TS2742 error. Use explicit type annotation instead. - **Missing `'use client'`** — required when using `useState`, `useEffect`, event handlers. - **Forgetting barrel exports** — both component-level `index.ts` and tier-level barrel. - **Inline meta in stories** — no default exports, always `export const Default: Story`. - **Missing `data-testid`** — every component root must have one. - **Magic numbers in styles** — use design tokens and Tailwind spacing scale. - **Uppercase in commit subjects** — commitlint rejects it; use all-lowercase. - **Render-only stories without `args`** — controls panel will be empty. Always define `args`. For nested-data components, reuse the component's data interface as args type (don't create a duplicate), add `argTypes` for control customization, and pass `args` directly as data.

Intended uses

  • Use Shep:Ui Component when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.