frontend-design

フロントエンドデザインスキル — 体系的で創造的なウェブ開発

スキルの場所：{project_path}/skills/frontend-design/

このスキルでは、体系的なデザイントークンのアプローチを用いて、曖昧な UI スタイルの要件を、本番環境で使える高品質なフロントエンドコードに変換しながら、優れた創造性を維持します。すべての成果物で視覚的な一貫性、アクセシビリティへの準拠、保守性を確保します。

---

このスキルを使用する場面（トリガーパターン）

次の場合は必ずこのスキルを適用してください：

• ユーザーがウェブサイト、ウェブアプリケーション、ウェブコンポーネントの開発を依頼した場合
• ユーザーが「モダン」「プレミアム」「ミニマリスト」「ダークモード」「SaaS 風」などのデザインスタイルに言及した場合
• ダッシュボード、ランディングページ、管理パネル、またはその他のウェブ UI を構築する場合
• ユーザーが「見栄えを良くして」や「デザインを改善して」と依頼した場合
• コンポーネントライブラリやデザインシステムを作成する場合
• ユーザーが React、Vue、Svelte、Next.js、Nuxt などのフレームワークを指定した場合
• デザインやモックアップをコードに変換する場合
• ユーザーが Tailwind CSS、shadcn/ui、Material-UI、Chakra UI などに言及した場合

トリガーフレーズ：

• 「ウェブサイト／アプリ／コンポーネントを構築して」
• 「ダッシュボード／ランディングページを作成して」
• 「…の UI をデザインして」
• 「モダン／すっきり／プレミアムな見た目にして」
• 「これを…でスタイリングして」
• 「このデザインをコードに変換して」

次の場合は使用しないでください：

• バックエンド API の開発
• 純粋なロジックやアルゴリズムの実装
• 視覚要素を扱わないコード作業

---

スキルの構成

このスキルには以下が含まれます：

1. SKILL.md（このファイル）：基本的な手法とガイドライン
2. examples/css/：本番環境向けの CSS の例
   • tokens.css - デザイントークンシステム
   • components.css - 再利用可能なコンポーネントスタイル
   • utilities.css - ユーティリティクラス
3. examples/typescript/：TypeScript の実装例
   • design-tokens.ts - 型安全なトークン定義
   • theme-provider.tsx - テーマ管理
   • sample-components.tsx - コンポーネントの例
4. templates/：クイックスタート用テンプレート
   • tailwind-config.js - Tailwind の設定
   • globals.css - グローバルスタイルのテンプレート

---

基本原則（必須）

1. システムと創造性の両立

体系的な基盤：

• デザイントークンを先に定義し、UI コンポーネントはその後に作成する
• 任意のハードコード値（色、余白、シャドウ、角丸）は使用しない
• タイポグラフィ、余白、角丸、エレベーションには一貫したスケールを使用する
• すべての状態を網羅する（デフォルト／ホバー／アクティブ／フォーカス／無効に加え、読み込み中／空／エラー）
• アクセシビリティは後付けではなく、制約条件として扱う

創造的な実行：

• ありがちな「AI スロップ」風のデザイン（Inter／Roboto フォント、紫色のグラデーション、型にはまったレイアウト）は避ける
• 大胆な美的方向性を選ぶ：ブルータリズム、レトロフューチャー、ラグジュアリー、遊び心のあるスタイル、エディトリアルなど
• タイポグラフィ、色、レイアウト、モーションに意外性のある選択を取り入れる
• それぞれのデザインを、その用途に合わせて意図的に作り込まれた独自のものにする

2. トークンファーストの手法

Design Tokens → Component Styles → Page Layouts → Interactive States

トークンの定義を省略してはいけません。 すべての視覚的プロパティは、トークンシステムに基づいて設定する必要があります。

3. 柔軟な技術スタック

指定がない場合のデフォルトスタック：

• フレームワーク：React + TypeScript
• スタイリング：Tailwind CSS
• コンポーネント：shadcn/ui
• テーマ：CSS カスタムプロパティ（ライトモード／ダークモード）

サポート対象の代替技術：

• フレームワーク：Vue、Svelte、Angular、バニラ HTML/CSS
• スタイリング：CSS Modules、SCSS、Styled Components、Emotion
• ライブラリ：MUI、Ant Design、Chakra UI、Headless UI

4. Tailwind CSS のベストプラクティス

⚠️ 重要：Tailwind を CDN 経由で使用しないでください

必ずビルド時に統合してください：

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

ビルド時の統合が必須である理由：

• ✅ ツリーシェイキングが可能（バンドルサイズは 2～15KB。CDN 経由では 400KB 以上）
• ✅ デザイントークンを完全にカスタマイズ可能
• ✅ IDE の自動補完と型安全性
• ✅ バンドラー（Vite、webpack、Next.js）と統合可能

CDN の使用が許容されるのは次の場合のみ：

• 簡単なプロトタイプ／デモ
• 内部テスト

---

実装ワークフロー

フェーズ 1：デザイン分析とトークン定義

ステップ 1：コンテキストを理解する

- Purpose: What problem does this solve? Who uses it?
- Aesthetic Direction: Choose ONE bold direction
- Technical Constraints: Framework, performance, accessibility needs
- Differentiation: What makes this memorable?

ステップ 2：デザイントークンを生成する

包括的なトークンシステムを作成します（examples/css/tokens.css および examples/typescript/design-tokens.ts を参照）：

1. セマンティックカラーのスロット（ライトモード＋ダークモード）：

   --background, --surface, --surface-subtle
   --text, --text-secondary, --text-muted
   --border, --border-subtle
   --primary, --primary-hover, --primary-active, --primary-foreground
   --secondary, --secondary-hover, --secondary-foreground
   --accent, --success, --warning, --danger
   

2. タイポグラフィのスケール：

   Display: 3.5rem/4rem (56px/64px), weight 700-800
   H1: 2.5rem/3rem (40px/48px), weight 700
   H2: 2rem/2.5rem (32px/40px), weight 600
   H3: 1.5rem/2rem (24px/32px), weight 600
   Body: 1rem/1.5rem (16px/24px), weight 400
   Small: 0.875rem/1.25rem (14px/20px), weight 400
   Caption: 0.75rem/1rem (12px/16px), weight 400
   

3. スペーシングのスケール（8px システム）：

   0.5 → 4px, 1 → 8px, 2 → 16px, 3 → 24px, 4 → 32px
   5 → 40px, 6 → 48px, 8 → 64px, 12 → 96px, 16 → 128px
   

4. 角丸のスケール：

   xs: 2px (badges, tags)
   sm: 4px (buttons, inputs)
   md: 6px (cards, modals)
   lg: 8px (large cards, panels)
   xl: 12px (hero sections)
   2xl: 16px (special elements)
   full: 9999px (pills, avatars)
   

5. シャドウのスケール：

   sm: Subtle lift (buttons, inputs)
   md: Card elevation
   lg: Modals, dropdowns
   xl: Large modals, drawers
   

6. モーションのトークン：

   Duration: 150ms (micro), 220ms (default), 300ms (complex)
   Easing: ease-out (enter), ease-in (exit), ease-in-out (transition)
   

フェーズ 2：コンポーネント開発

ステップ 3：再利用可能なコンポーネントを構築する

次の構成に従います（examples/typescript/sample-components.tsx を参照）：

interface ComponentProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  state?: 'default' | 'hover' | 'active' | 'disabled' | 'loading';
}

必須のコンポーネント状態：

• デフォルト、ホバー、アクティブ、フォーカス、無効
• 読み込み中（スケルトン／スピナー）
• 空の状態（明確なメッセージ）
• エラー状態（復旧手順）

必須のコンポーネント機能：

• アクセシブル（ARIA ラベル、キーボード操作）
• レスポンシブ（モバイルファースト）
• テーマ対応（ライトモード／ダークモード）
• トークンベースのスタイリング（ハードコードされた値を使用しない）

フェーズ 3：ページの組み立て

ステップ 4：コンポーネントからページを構成する

- Use established tokens and components only
- Mobile-first responsive design
- Loading states for async content
- Empty states with clear CTAs
- Error states with recovery options

フェーズ 4：品質保証

ステップ 5：セルフレビューのチェックリスト

• すべての色がセマンティックトークンを使用している（無作為な hex/rgb 値を使用していない）
• すべてのスペーシングがスペーシングスケールに基づいている
• すべての角丸が角丸スケールに基づいている
• シャドウが階層に基づいて適切に設定されている
• 適切な行の高さ（1.5 以上）を備えた明確な文字の階層がある
• すべてのインタラクティブな状態が実装され、テストされている
• アクセシビリティ：WCAG AA のコントラスト、キーボード操作、ARIA、フォーカスインジケーター
• レスポンシブ：モバイル（375px）、タブレット（768px）、デスクトップ（1024px 以上）で動作する
• 読み込み中／空／エラーの状態が含まれている
• コードが保守しやすい（DRY、明確な命名、ドキュメント化）

---

デザイン方向のテンプレート

1. ミニマルで上質な SaaS（最も汎用的）

Visual Style: Minimal Premium SaaS
- Generous whitespace (1.5-2x standard padding)
- Near-white background with subtle surface contrast
- Light borders (1px, low-opacity)
- Very subtle elevation (avoid heavy shadows)
- Unified control height: 44-48px
- Medium-large radius: 6-8px
- Gentle hover states (background shift only)
- Clear but not harsh focus rings
- Low-contrast dividers
- Priority: Readability and consistency

**最適な用途：**エンタープライズアプリ、B2B SaaS、生産性向上ツール

2. 大胆なエディトリアル

Visual Style: Bold Editorial
- Strong typographic hierarchy (large display fonts)
- High contrast (black/white or dark/light extremes)
- Generous use of negative space
- Asymmetric layouts with intentional imbalance
- Grid-breaking elements
- Minimal color palette (1-2 accent colors max)
- Sharp, geometric shapes
- Dramatic scale differences
- Priority: Visual impact and memorability

**最適な用途：**マーケティングサイト、ポートフォリオ、コンテンツ中心のサイト

3. 柔らかく、オーガニック

Visual Style: Soft & Organic
- Rounded corners everywhere (12-24px radius)
- Soft shadows and subtle gradients
- Pastel or muted color palette
- Gentle animations (ease-in-out, 300-400ms)
- Curved elements and flowing layouts
- Generous padding (1.5-2x standard)
- Soft, blurred backgrounds
- Priority: Approachability and comfort

**最適な用途：**コンシューマーアプリ、ウェルネス、ライフスタイルブランド

4. ダークネオン（控えめ）

Visual Style: Dark Neon
- Dark background (#0a0a0a to #1a1a1a, NOT pure black)
- High contrast text (#ffffff or #fafafa)
- Accent colors ONLY for CTAs and key states
- Subtle glow on hover (box-shadow with accent color)
- Minimal borders (use subtle outlines)
- Optional: Subtle noise texture
- Restrained use of neon (less is more)
- Priority: Focus and sophisticated edge

**最適な用途：**開発者向けツール、ゲーム、テクノロジー製品

5. 遊び心のあるカラフルなデザイン

Visual Style: Playful & Colorful
- Vibrant color palette (3-5 colors)
- Rounded corners (8-16px)
- Micro-animations on hover/interaction
- Generous padding and breathing room
- Friendly, geometric illustrations
- Smooth transitions (200-250ms)
- High energy but balanced
- Priority: Delight and engagement

**最適な用途：**コンシューマーアプリ、子ども向け製品、クリエイティブツール

---

標準的なプロンプトのワークフロー

マスタープロンプトのテンプレート

You are a Design Systems Engineer + Senior Frontend UI Developer with expertise in creative design execution.

[TECH STACK]
- Framework: {{FRAMEWORK = React + TypeScript}}
- Styling: {{STYLING = Tailwind CSS}}
- Components: {{UI_LIB = shadcn/ui}}
- Theme: CSS variables (light/dark modes)

[DESIGN SYSTEM RULES - MANDATORY]
1. Layout: 8px spacing system; mobile-first responsive
2. Typography: Clear hierarchy (Display/H1/H2/H3/Body/Small/Caption); line-height 1.5+
3. Colors: Semantic tokens ONLY (no hardcoded values)
4. Shape: Tiered radius system; tap targets ≥ 44px
5. Elevation: Minimal shadows; borders for hierarchy
6. Motion: Subtle transitions (150-220ms); restrained animations
7. Accessibility: WCAG AA; keyboard navigation; ARIA; focus indicators

[AESTHETIC DIRECTION]
Style: {{STYLE = Minimal Premium SaaS}}
Key Differentiator: {{UNIQUE_FEATURE}}
Target Audience: {{AUDIENCE}}

[INTERACTION STATES - REQUIRED]
✓ Default, Hover, Active, Focus, Disabled
✓ Loading (skeleton), Empty (with messaging), Error (with recovery)

[OUTPUT REQUIREMENTS]
1. Design Tokens (CSS variables + TypeScript types)
2. Component implementations (copy-paste ready)
3. Page layouts with all states
4. NO hardcoded values; reference tokens only
5. Minimal but clear code comments

トークン生成プロンプト

Generate a complete Design Token system including:

1. Semantic color slots (CSS custom properties):
   - Light mode + Dark mode variants
   - Background, surface, text, border, primary, secondary, accent, semantic colors
   - Interactive states for each (hover, active)

2. Typography scale:
   - Display, H1-H6, Body, Small, Caption, Monospace
   - Include: font-size, line-height, font-weight, letter-spacing

3. Spacing scale (8px base):
   - 0.5, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24 (in rem)

4. Radius scale:
   - xs (2px), sm (4px), md (6px), lg (8px), xl (12px), 2xl (16px), full

5. Shadow scale:
   - sm, md, lg, xl (with color and blur values)
   - Usage guidelines for each tier

6. Motion tokens:
   - Duration: fast (150ms), base (220ms), slow (300ms)
   - Easing: ease-out, ease-in, ease-in-out

7. Component density:
   - Button heights: sm (36px), md (44px), lg (48px)
   - Input heights: sm (36px), md (40px)
   - Padding scales

Output format:
- CSS custom properties (globals.css)
- Tailwind config integration
- TypeScript type definitions
- Usage examples for each token category

DO NOT write component code yet.

コンポーネント実装プロンプト

Using the established Design Tokens, implement: <{{COMPONENT_NAME}} />

Requirements:
- Props: variant, size, state, className (for composition)
- States: default, hover, focus, active, disabled, loading, error
- Accessibility: keyboard navigation, ARIA labels, focus management
- Responsive: mobile-first, touch-friendly (44px+ tap targets)
- Styling: Use tokens ONLY (no hardcoded values)
- TypeScript: Full type safety with exported interfaces

Include:
1. Component implementation
2. Usage examples (3-5 variants)
3. Loading state example
4. Error state example
5. Accessibility notes

Output: Production-ready, copy-paste code with JSDoc comments.

ページ開発プロンプト

Build page: {{PAGE_NAME}}

Using:
- Established Design Tokens
- Implemented Components
- {{STYLE}} aesthetic direction

Requirements:
- Responsive layout (mobile/tablet/desktop)
- All interaction states (hover/focus/active/disabled)
- Loading skeleton for async content
- Empty state with clear CTA
- Error state with recovery options
- Accessible (keyboard nav, ARIA, WCAG AA)
- No hardcoded styles (components + utility classes only)

Include:
1. Page component with mock data
2. Loading state variant
3. Empty state variant
4. Error state variant
5. Responsive behavior notes

Output: Complete, runnable page component.

レビューと最適化のプロンプト

You are a Frontend Code Reviewer specializing in design systems and accessibility.

Review the implementation and check:

1. Token Compliance:
   - Any hardcoded colors, sizes, shadows, radius?
   - All values from established scales?

2. Typography:
   - Clear hierarchy?
   - Comfortable line-height (1.5+)?
   - Appropriate font sizes for each level?

3. Spacing & Layout:
   - Consistent use of spacing scale?
   - Adequate whitespace?
   - No awkward gaps or cramped sections?

4. Interactive States:
   - Hover/focus/active clearly distinct?
   - Disabled state obviously different?
   - Loading/empty/error states implemented?

5. Accessibility:
   - WCAG AA contrast met?
   - Keyboard reachable?
   - ARIA labels complete?
   - Focus indicators visible?
   - Semantic HTML?

6. Responsive Design:
   - Mobile layout functional (375px)?
   - Tablet optimized (768px)?
   - Desktop enhanced (1024px+)?
   - Touch targets ≥ 44px?

7. Maintainability:
   - DRY principles followed?
   - Clear component boundaries?
   - Consistent naming?
   - Adequate comments?

8. Creative Execution:
   - Matches intended aesthetic?
   - Avoids generic patterns?
   - Unique and memorable?

Output:
- Findings (sorted by severity: Critical, High, Medium, Low)
- Specific fixes (code patches)
- Improvement suggestions

---

よくある落とし穴と解決策

❌ 問題：美的表現が曖昧

✅ 解決策：実行可能な仕様を必ず提示する

DON'T: "Make it modern and clean"
DO: 
- Whitespace: 1.5x standard padding (24px instead of 16px)
- Typography: Display 56px, H1 40px, Body 16px, line-height 1.6
- Colors: Neutral gray scale (50-900) + single accent color
- Shadows: Maximum 2 shadow tokens (card + modal only)
- Radius: Consistent 6px (buttons/inputs) and 8px (cards)
- Borders: 1px with --border-subtle (#e5e7eb in light mode)
- Transitions: 150ms ease-out only

❌ 問題：各コンポーネントが独自のスタイルを作ってしまう

✅ 解決策：トークンのみを使用するルールを徹底する

RULE: Every visual property must map to a token.

Violations:
- ❌ bg-gray-100 (hardcoded Tailwind color)
- ❌ p-[17px] (arbitrary padding not in scale)
- ❌ rounded-[5px] (radius not in scale)
- ❌ shadow-[0_2px_8px_rgba(0,0,0,0.1)] (arbitrary shadow)

Correct:
- ✅ bg-surface (semantic token)
- ✅ p-4 (maps to spacing scale: 16px)
- ✅ rounded-md (maps to radius scale: 6px)
- ✅ shadow-sm (maps to shadow token)

❌ 問題：インタラクティブな状態が不足している

✅ 解決策：状態の網羅性をチェックリストで確認する

For EVERY interactive element, implement:

Visual States:
- [ ] Default (base appearance)
- [ ] Hover (background shift, shadow, scale)
- [ ] Active (pressed state, slightly darker)
- [ ] Focus (visible ring, keyboard accessible)
- [ ] Disabled (reduced opacity, cursor not-allowed)

Data States:
- [ ] Loading (skeleton or spinner with same dimensions)
- [ ] Empty (clear message + CTA)
- [ ] Error (error message + retry option)

Test each state in isolation and in combination.

❌ 問題：ありきたりな AI デザイン

✅ 解決策：創造性と差別化を必ず取り入れる

BANNED PATTERNS (overused in AI-generated UIs):
- ❌ Inter/Roboto/System fonts as primary choice
- ❌ Purple gradients on white backgrounds
- ❌ Card-grid-card-grid layouts only
- ❌ Generic blue (#3b82f6) as primary
- ❌ Default Tailwind color palette with no customization

REQUIRED CREATIVE CHOICES:
- ✅ Select distinctive fonts (Google Fonts, Adobe Fonts, custom)
- ✅ Build custom color palette (not Tailwind defaults)
- ✅ Design unique layouts (asymmetry, overlap, grid-breaking)
- ✅ Add personality: illustrations, icons, textures, patterns
- ✅ Create signature elements (unique buttons, cards, headers)

Ask yourself: "Would someone recognize this as uniquely designed for this purpose?"

❌ 問題：アクセシビリティが後回しになっている

✅ 解決策：アクセシビリティを制約条件として扱う

Build accessibility IN, not ON:

Color Contrast:
- Run contrast checker on all text/background pairs
- Minimum WCAG AA: 4.5:1 (normal text), 3:1 (large text)
- Use tools: WebAIM Contrast Checker, Chrome DevTools

Keyboard Navigation:
- Tab order follows visual flow
- All interactive elements keyboard reachable
- Focus indicator always visible (outline or ring)
- Escape closes modals/dropdowns

ARIA & Semantics:
- Use semantic HTML first (<button>, <nav>, <main>)
- Add ARIA only when semantic HTML insufficient
- aria-label for icon-only buttons
- aria-describedby for form errors
- aria-expanded for disclosure widgets

Test with:
- Keyboard only (no mouse)
- Screen reader (NVDA, JAWS, VoiceOver)
- Reduced motion preference (prefers-reduced-motion)

---

クイックスタート：完全な例

You are a Design Systems Engineer + Senior Frontend UI Developer.

[STACK]
React + TypeScript + Tailwind CSS + shadcn/ui

[TASK]
Build a Team Dashboard for a project management app.

[AESTHETIC]
Style: Minimal Premium SaaS
Unique Element: Subtle animated background gradient
Audience: Product managers and software teams

[REQUIREMENTS]
1. Components needed:
   - Header with search and user menu
   - Team members grid (name, role, avatar, status)
   - Invite modal (name, email, role selector)
   - Empty state (no team members yet)
   - Loading skeleton

2. Features:
   - Search/filter team members
   - Click to view member details
   - Invite button opens modal
   - Sort by name/role/status

3. States:
   - Loading (skeleton grid)
   - Empty (with invite CTA)
   - Populated (member cards)
   - Error (failed to load)

[OUTPUT]
1. Design Tokens (globals.css + tailwind.config.ts)
2. Component implementations:
   - TeamMemberCard
   - InviteModal
   - SearchBar
   - UserMenu
3. TeamDashboard page component
4. All states (loading/empty/error)
5. Full TypeScript types
6. Accessibility notes

Rules:
- Mobile-first responsive
- No hardcoded values (use tokens)
- WCAG AA compliance
- Include hover/focus/active states
- Add subtle micro-interactions

---

例とテンプレート

このスキルには、examples/ に本番環境ですぐに使える例が含まれています：

CSS の例（examples/css/）

tokens.css — 完全なデザイントークンシステム

• セマンティックカラートークン（ライトモード＋ダークモード）
• 流動的なサイズ設定を備えたタイポグラフィスケール
• スペーシング、角丸、シャドウ、モーションのスケール
• すぐに使える CSS カスタムプロパティ

components.css — コンポーネントスタイルライブラリ

• ボタン（バリエーション、サイズ、状態）
• 入力欄、テキストエリア、セレクト
• カード、モーダル、ツールチップ
• ナビゲーション、ヘッダー、フッター
• 読み込み中のスケルトン
• 状態ごとのバリエーションをすべて用意（ホバー／フォーカス／アクティブ／無効）

utilities.css — ユーティリティクラスライブラリ

• レイアウトユーティリティ（flex、grid、container）
• スペーシングユーティリティ（margin、padding）
• タイポグラフィユーティリティ（サイズ、ウェイト、行の高さ）
• 状態ユーティリティ（hover、focus、group の各バリエーション）

TypeScript の例（examples/typescript/）

design-tokens.ts — 型安全なトークン定義

• トークンのインターフェースと型
• デザインシステムの設定
• テーマの型定義
• トークンのバリデーター

theme-provider.tsx — テーマ管理システム

• テーマコンテキストプロバイダー
• ダークモードの切り替え
• システム設定の検出
• テーマの永続化（localStorage）

sample-components.tsx — 本番環境向けコンポーネントの例

• ボタンコンポーネント（すべてのバリエーション）
• 入力コンポーネント（バリデーション付き）
• カードコンポーネント（読み込み状態付き）
• モーダルコンポーネント（フォーカス管理付き）
• すべて完全な TypeScript 型とアクセシビリティに対応

テンプレート（templates/）

tailwind-config.js — 最適化された Tailwind の設定

• カスタムカラーパレット
• タイポグラフィプラグインの設定
• スペーシングとサイズのスケール
• プラグインの設定

globals.css — グローバルスタイルのテンプレート

• CSS リセット／ノーマライズ
• トークン定義
• 基本的な要素のスタイル
• ユーティリティクラス

---

出力品質基準

すべての成果物は、次の基準を満たす必要があります。

コード品質

• ✅ 本番環境で使用可能（コピー＆ペーストしてデプロイ可能）
• ✅ 完全な型安全性を備えた TypeScript
• ✅ ESLint／Prettier に準拠
• ✅ マジックナンバーのハードコーディングなし
• ✅ DRY（繰り返しを避ける）
• ✅ 明確で説明的な命名
• ✅ 複雑なロジックには JSDoc コメントを記載

デザイン品質

• ✅ 独自性があり、記憶に残る美しさ
• ✅ トークンの一貫した使用
• ✅ 統一感のあるビジュアル言語
• ✅ 工夫されたマイクロインタラクション
• ✅ 洗練された細部（シャドウ、トランジション、スペーシング）

アクセシビリティ品質

• ✅ WCAG AA 以上（できれば AAA）
• ✅ キーボードで操作可能
• ✅ スクリーンリーダーに対応
• ✅ フォーカス管理
• ✅ セマンティック HTML
• ✅ 必要に応じて ARIA を使用

パフォーマンス品質

• ✅ バンドルサイズを最適化（ツリーシェイキング）
• ✅ 重いコンポーネントを遅延読み込み
• ✅ 可能な場合は CSS のみでアニメーションを実装
• ✅ 再レンダリングを最小限に抑制（React memo/useMemo）
• ✅ レスポンシブ画像（srcset、sizes）

---

検証チェックリスト

コードを納品する前に、次の項目を確認してください。

トークンとシステム：

• すべての色がセマンティックトークンに基づいている（hex/rgb のハードコーディングなし）
• すべてのスペーシングがスペーシングスケールに基づいている（8px システム）
• すべての角丸が角丸スケールに基づいている（xs/sm/md/lg/xl/2xl/full）
• シャドウは最小限で、使用する理由が明確
• タイポグラフィの階層が明確（Display/H1/H2/H3/Body/Small/Caption）
• 行の高さが読みやすい（本文は 1.5 以上）

状態とインタラクション：

• デフォルト状態を実装
• ホバー状態（視覚的なフィードバック）
• アクティブ状態（押下時の表示）
• フォーカス状態（キーボードリングが見える）
• 無効状態（不透明度を下げ、ポインターを無効化）
• 読み込み状態（スケルトンまたはスピナー）
• 空の状態（明確なメッセージと CTA）
• エラー状態（メッセージと復旧方法）

アクセシビリティ：

• WCAG AA のコントラスト比（テキストは 4.5:1、大きなテキストは 3:1）
• キーボード操作によるナビゲーションが完了
• フォーカスインジケーターが常に見える
• セマンティック HTML を使用
• 必要な箇所に ARIA ラベルを設定
• フォームのラベルを関連付け
• 画像に代替テキストを設定

レスポンシブデザイン：

• モバイルレイアウト（375px 以上）が機能する
• タブレットレイアウト（768px 以上）を最適化
• デスクトップレイアウト（1024px 以上）を強化
• タッチターゲットが 44px 以上
• すべての画面サイズでテキストを読みやすい
• 横スクロールが発生しない

クリエイティブな実現：

• 独自性のある美しさ（ありきたりではない）
• 指定されたデザインの方向性に合致
• 記憶に残る視覚要素
• 統一感のあるデザイン言語
• 細部まで洗練

コード品質：

• TypeScript の型が完全
• リンターエラーなし
• DRY の原則に準拠
• コンポーネントの境界が明確
• 命名規則が一貫
• 適切なコメントを記載
• 本番環境で使用可能（そのままデプロイ可能）

---

高度なテクニック

1. 流動的なタイポグラフィ

/* Responsive type scale using clamp() */
:root {
  --font-size-sm: clamp(0.875rem, 0.8rem + 0.2vw, 1rem);
  --font-size-base: clamp(1rem, 0.9rem + 0.3vw, 1.125rem);
  --font-size-lg: clamp(1.125rem, 1rem + 0.4vw, 1.25rem);
  --font-size-xl: clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);
  --font-size-2xl: clamp(1.5rem, 1.3rem + 0.7vw, 2rem);
  --font-size-3xl: clamp(1.875rem, 1.5rem + 1vw, 2.5rem);
  --font-size-4xl: clamp(2.25rem, 1.8rem + 1.5vw, 3.5rem);
}

2. 高度なカラーシステム

/* Color with opacity variants using oklch */
:root {
  --primary-base: oklch(60% 0.15 250);
  --primary-subtle: oklch(95% 0.02 250);
  --primary-muted: oklch(85% 0.05 250);
  --primary-emphasis: oklch(50% 0.18 250);
  --primary-foreground: oklch(98% 0.01 250);
}

/* Dark mode: adjust lightness only */
[data-theme="dark"] {
  --primary-base: oklch(70% 0.15 250);
  --primary-subtle: oklch(20% 0.02 250);
  --primary-muted: oklch(30% 0.05 250);
  --primary-emphasis: oklch(80% 0.18 250);
  --primary-foreground: oklch(10% 0.01 250);
}

3. スケルトン読み込みパターン

// Animated skeleton with shimmer effect
const Skeleton = ({ className }: { className?: string }) => (
  <div
    className={cn(
      "animate-pulse rounded-md bg-surface-subtle",
      "relative overflow-hidden",
      "before:absolute before:inset-0",
      "before:-translate-x-full before:animate-shimmer",
      "before:bg-gradient-to-r before:from-transparent before:via-white/10 before:to-transparent",
      className
    )}
  />
);

// Usage in components
<Card>
  <Skeleton className="h-4 w-3/4 mb-2" />
  <Skeleton className="h-4 w-1/2 mb-4" />
  <Skeleton className="h-32 w-full" />
</Card>

4. 高度なモーション

/* Page transitions */
@keyframes fade-in {
  from {
    opacity: 0;
    transform: translateY(8px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* Staggered animations */
.stagger-item {
  animation: fade-in 0.3s ease-out backwards;
}
.stagger-item:nth-child(1) { animation-delay: 0ms; }
.stagger-item:nth-child(2) { animation-delay: 50ms; }
.stagger-item:nth-child(3) { animation-delay: 100ms; }
.stagger-item:nth-child(4) { animation-delay: 150ms; }

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

---

卓越するためのヒント

1. 常にトークンから始める — コンポーネントから始めないでください
2. モバイルファーストで考える — 375px向けに設計し、より広い画面向けに拡張します
3. 状態を早い段階で検証する — 各インタラクティブ状態を個別にテストします
4. 大胆な美しさを追求する — ありきたりなパターンは避けます
5. アクセシビリティは妥協できません — 最初から組み込みます
6. 実際のコンテンツを使う — 実際のテキスト、画像、データでテストします
7. 自分の成果物を見直す — 提出前に自己監査します
8. 判断を記録する — 複雑なスタイル設定の選択理由を説明します
9. 保守しやすさを保つ — 将来の開発者に感謝されます
10. 本番環境に対応したコードを納品する — 納品物に「TODO」や「FIXME」を残しません

---

参考資料とリソース

• Tailwind CSS: https://tailwindcss.com/docs
• shadcn/ui: https://ui.shadcn.com
• WCAG ガイドライン: https://www.w3.org/WAI/WCAG21/quickref/
• カラーコントラストチェッカー: https://webaim.org/resources/contrastchecker/
• タイポグラフィスケール: https://typescale.com
• モジュラースケール: https://www.modularscale.com
• CSS カスタムプロパティ: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties

---

バージョン: 2.0.0
最終更新: 2024年12月
ライセンス: MIT
メンテナンス担当: z-ai platform team