UI Spec to Component

Overview

Transform natural language UI specifications into production-ready React components with shadcn/ui integration, TypeScript type safety, Tailwind CSS styling, and built-in accessibility features.

When to Use This Skill

Use this skill when:

• User describes UI components or layouts in natural language (Japanese or English)
• Need to create reusable React components for the ScaffAI project
• Converting design requirements into shadcn/ui-based implementations
• Building forms, cards, modals, tables, or other interactive UI elements
• Require TypeScript, Tailwind CSS, and accessibility compliance

Trigger examples:

• "プロジェクトカード、タイトル・ステータス・更新日表示、クリックで詳細へ"
• "足場図面のツールパネル、線・矩形・円・テキストボタン"
• "見積入力フォーム、項目名・数量・単価・自動計算表示"

Core Workflow

Step 1: Parse UI Specification

Extract component requirements from the user's description:

1. Identify component type: Card, Form, Table, Modal, Button, etc.
2. Extract data fields: What information to display or collect
3. Detect interactions: Click handlers, form submissions, state changes
4. Determine layout: Grid, flex, list, or custom arrangement
5. Identify parent-child relationships: Nested components or composition patterns

Example:

Input: "プロジェクトカード、タイトル・ステータス・更新日表示、クリックで詳細へ"

Parsed:
- Component Type: Card
- Data Fields:
  - title (string)
  - status (enum: active/pending/completed)
  - updatedAt (Date)
- Interactions:
  - onClick → navigate to details
- Layout: Vertical stack with badge for status
- Accessibility: Button role, keyboard navigation

Step 2: Select shadcn/ui Components

Map the UI requirements to appropriate shadcn/ui components:

Common Mappings:

• Card/Panel → Card, CardHeader, CardContent
• Button → Button (with variant: default, outline, ghost, destructive)
• Form → Form, FormField, Input, Label
• Modal/Dialog → Dialog, DialogContent, DialogTrigger
• Table → Table, TableHeader, TableBody, TableRow
• List → Custom with Card or native <ul>
• Dropdown → Select, SelectTrigger, SelectContent
• Status Badge → Badge
• Loading → Skeleton
• Notification → useToast hook

Reference: Load references/shadcn_components.md for complete component API and usage patterns.

Step 3: Design TypeScript Interfaces

Define TypeScript types for props and data:

// Component props interface
interface ComponentNameProps {
  // Data props
  title: string;
  status: 'active' | 'pending' | 'completed';
  updatedAt: Date;

  // Event handlers
  onClick?: () => void;

  // Optional styling
  className?: string;
}

// Data model (if needed)
interface DataModel {
  id: string;
  // ... other fields
}

Step 4: Generate React Component

Create a TypeScript React component with:

• shadcn/ui component imports
• TypeScript props interface
• JSDoc comments in Japanese
• Tailwind CSS styling
• ARIA attributes for accessibility
• Event handlers
• Conditional rendering
• Error states

Template structure:

import * as React from 'react';
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';

/**
 * コンポーネントの説明（日本語）
 *
 * @param props - コンポーネントのプロパティ
 * @returns JSX.Element
 */
interface ComponentNameProps {
  title: string;
  status: 'active' | 'pending' | 'completed';
  updatedAt: Date;
  onClick?: () => void;
  className?: string;
}

export function ComponentName({
  title,
  status,
  updatedAt,
  onClick,
  className,
}: ComponentNameProps) {
  // ステータスバッジの色を決定
  const statusVariant = {
    active: 'default',
    pending: 'secondary',
    completed: 'outline',
  }[status] as 'default' | 'secondary' | 'outline';

  // 更新日のフォーマット
  const formattedDate = new Intl.DateTimeFormat('ja-JP', {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
  }).format(updatedAt);

  return (
    <Card
      className={cn('cursor-pointer hover:shadow-lg transition-shadow', className)}
      onClick={onClick}
      role="button"
      tabIndex={0}
      onKeyDown={(e) => {
        if (e.key === 'Enter' || e.key === ' ') {
          onClick?.();
        }
      }}
    >
      <CardHeader>
        <CardTitle className="flex items-center justify-between">
          <span>{title}</span>
          <Badge variant={statusVariant}>
            {status === 'active' && '稼働中'}
            {status === 'pending' && '保留中'}
            {status === 'completed' && '完了'}
          </Badge>
        </CardTitle>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">
          更新日: {formattedDate}
        </p>
      </CardContent>
    </Card>
  );
}

Step 5: Add Accessibility Features

Ensure WCAG compliance:

1. Semantic HTML: Use appropriate HTML5 elements
2. ARIA Attributes: Add role, aria-label, aria-describedby when needed
3. Keyboard Navigation: Support Tab, Enter, Space, Escape keys
4. Focus Management: Visible focus indicators, logical tab order
5. Screen Reader Support: Meaningful labels and descriptions
6. Color Contrast: Ensure 4.5:1 contrast ratio minimum

Accessibility Checklist:

• Keyboard accessible (Tab, Enter, Space)
• Focus indicators visible
• ARIA labels for icon-only buttons
• Color not sole indicator
• Error messages announced to screen readers
• Heading hierarchy logical

Step 6: Add Responsive Design

Use Tailwind CSS responsive prefixes:

<div className="
  grid grid-cols-1           // Mobile: 1 column
  sm:grid-cols-2             // Small: 2 columns
  md:grid-cols-3             // Medium: 3 columns
  lg:grid-cols-4             // Large: 4 columns
  gap-4                      // Consistent spacing
">
  {/* Cards */}
</div>

Breakpoints:

• sm: 640px
• md: 768px
• lg: 1024px
• xl: 1280px
• 2xl: 1536px

Step 7: Generate Usage Example

Provide a complete usage example:

// pages/projects.tsx
import { ComponentName } from '@/components/ComponentName';
import { useRouter } from 'next/navigation';

export default function ProjectsPage() {
  const router = useRouter();

  const projects = [
    {
      id: '1',
      title: 'プロジェクトA',
      status: 'active' as const,
      updatedAt: new Date('2025-10-22'),
    },
    // ... more projects
  ];

  return (
    <div className="container mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">プロジェクト一覧</h1>
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
        {projects.map((project) => (
          <ComponentName
            key={project.id}
            title={project.title}
            status={project.status}
            updatedAt={project.updatedAt}
            onClick={() => router.push(`/projects/${project.id}`)}
          />
        ))}
      </div>
    </div>
  );
}

Output Format

Provide the complete implementation in the following structure:

## 📋 コンポーネント仕様
[UI要件の要約]

## 🎨 使用するshadcn/uiコンポーネント
- [コンポーネント1]
- [コンポーネント2]

## 📘 TypeScript型定義

\`\`\`typescript
[インターフェース定義]
\`\`\`

## ⚛️ Reactコンポーネント実装

\`\`\`tsx
[完全なコンポーネントコード]
\`\`\`

## ♿ アクセシビリティ対応
- [実装された機能1]
- [実装された機能2]

## 📱 レスポンシブ対応
- モバイル: [説明]
- タブレット: [説明]
- デスクトップ: [説明]

## 📝 使用例

\`\`\`tsx
[実際の使用例コード]
\`\`\`

## 🎯 追加実装の提案（オプション）
- [拡張機能の提案1]
- [拡張機能の提案2]

Best Practices

1. Component Composition: Break complex UIs into smaller, reusable components
2. TypeScript Strict Mode: Use strict type checking for props and state
3. Tailwind Utilities: Prefer Tailwind utilities over custom CSS
4. Consistent Naming: Use PascalCase for components, camelCase for props
5. Japanese Comments: All JSDoc comments in Japanese for ScaffAI project
6. Accessibility First: Never skip accessibility features
7. Performance: Use React.memo for expensive components
8. Error Boundaries: Wrap complex components in error boundaries

Common ScaffAI Component Patterns

Project Card

Input: "プロジェクトカード、名前・ステータス・更新日・クリックで詳細"
Output: Card component with Badge, formatted date, onClick handler

Drawing Toolbar

Input: "作図ツールパネル、線・矩形・円・テキストボタン、選択中のツールをハイライト"
Output: Toolbar with Button group, active state management

Estimate Form

Input: "見積入力フォーム、項目名・数量・単価、合計を自動計算"
Output: Form with Input fields, auto-calculated total, validation

Modal Dialog

Input: "確認ダイアログ、削除確認メッセージ・キャンセル・削除ボタン"
Output: Dialog component with danger variant button

Integration with ScaffAI

This skill is designed for the ScaffAI project structure:

• Components: Generate in frontend/components/ or frontend/app/(protected)/[page]/components/
• UI Kit: Use shadcn/ui from frontend/components/ui/
• Types: Share types with backend in shared/types/
• Styling: Follow Tailwind config in frontend/tailwind.config.ts
• Accessibility: Meet ScaffAI WCAG 2.1 AA requirements
• i18n: Japanese-first UI text, prepared for future localization

Loading Reference Documentation

When implementing complex components, load the shadcn/ui reference:

Read references/shadcn_components.md for:
- Complete component API
- Import statements
- Usage patterns
- Variant options

This ensures accurate shadcn/ui component usage without guessing APIs.