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 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?
mkdir -p ~/.claude/skills/shepui-component # Save SKILL.md to ~/.claude/skills/shepui-component/SKILL.md
- 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.
- 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.
- 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.
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.