spark-app-template

Spark App Template

目的

Spark App Template は、Web アプリケーションを構築するためのデフォルト設定とガイダンスを提供します。ユーザーが Web アプリの構築を依頼したとき、このスキルは機能的なアプリケーションを作成するための技術基盤とデザインの方向性を提供します。

このスキルを使用するタイミング

ユーザーが次のことを行う場合は、Spark App Template を有効にしてください。

• 新しい Web アプリケーションをゼロから構築したい
• 「どのスタックを使うべきですか？」と尋ねる
• デザイン、スタイリング、技術選定についてガイダンスが必要
• ダッシュボード、インタラクティブツール、データアプリ、コンテンツサイトを始めたい
• フレームワーク、ライブラリ、アプローチの選択についてサポートを求める

クイックスタートのワークフロー

重要：設定エラーを避けるため、必ず次の順序で実行してください。

1. プロジェクトを作成：pnpm create vite@latest my-app --template react-ts
2. 基本的な依存関係をインストール：pnpm install
3. TypeScript のパスエイリアスを設定（tsconfig.json と tsconfig.app.json の両方。以下のステップ 1 を参照）
4. Tailwind とツールをインストール：pnpm add -D tailwindcss @tailwindcss/vite @biomejs/biome
5. vite.config.ts を設定：Tailwind プラグインとパスエイリアスを追加
6. shadcn を初期化：pnpm dlx shadcn@latest init（エイリアスが正しく設定されているため、これで成功します）
7. 必要な shadcn コンポーネントをインストール：pnpm dlx shadcn add button card avatar ...（コンポーネントを書く前に実行）
8. 追加のパッケージをインストール：TanStack Router、Query、Zustand など
9. カスタムコンポーネントを書く（これで @/components/ui/* から安全にインポートできます）
10. ルーティングと状態管理を設定
11. 機能を実装

TypeScript のエラーや shadcn のインストール失敗を避けるため、ステップ 3、6、7 は必ずこの順序で実行してください。

複雑さのレベル

複雑さを理解すると、適切なスタックのバリエーションとデザインのアプローチを選べます。

1. マイクロツール（単一目的）

   • 例：計算機、変換ツール、カラーピッカー、タイマー
   • スタック：stacks/default-webapp.md
   • 重視する点：状態を最小限に抑えた、シンプルで焦点の定まった UI

2. コンテンツの紹介サイト（情報重視）

   • 例：ランディングページ、ポートフォリオ、ブログ、ドキュメント
   • スタック：stacks/content-showcase.md
   • 重視する点：タイポグラフィ、読みやすさ、視覚的な階層

3. 軽量アプリケーション（基本的な状態管理を備えた複数の機能）

   • 例：ToDo リスト、献立プランナー、支出管理ツール
   • スタック：stacks/default-webapp.md
   • 重視する点：機能のわかりやすさ、データの永続化、ユーザーフロー

4. 複雑なアプリケーション（高度な機能と複数のビュー）

   • 例：CRM、分析ダッシュボード、プロジェクト管理ツール
   • スタック：stacks/complex-application.md または stacks/data-dashboard.md
   • 重視する点：ナビゲーション、状態管理、パフォーマンスの最適化

コア技術スタック（共通基盤）

Spark App Template のすべてのアプリケーションで、次の基盤を使用します。

ビルドと開発

• ビルドツール：Vite（最新の安定版）
• フレームワーク：React 19+（新しいコンパイラー、フック、機能を活用）
• 言語：TypeScript
• パッケージマネージャー：pnpm
• リンティング：Biome（複雑なプラグインには ESLint を代替として使用）

ルーティングとデータ

• ルーティング：TanStack Router（ファイルベース、型安全）
• データ取得：TanStack Query
• フォーム：react-hook-form + Zod によるバリデーション

スタイリングと UI

• スタイリング：Tailwind CSS v4+（最新の @import 構文）
• コンポーネント：shadcn/ui（New York スタイル、45 以上のコンポーネント）
• アイコン：Lucide React（1000 以上のアイコン）
• カラーシステム：Radix Colors（OKLCH 形式）
• テーマ：next-themes（デフォルトは単一テーマ、ダークモードは任意）

ユーティリティと拡張機能

• アニメーション：Motion（旧称 framer-motion）
• 通知：Sonner
• ユーティリティ：CVA（または Tailwind Variants）+ clsx + tailwind-merge
• エラー処理：react-error-boundary

スタックのバリエーション

すべてのバリエーションで、上記のコア基盤を共有します。次のテンプレートでは、特定のパッケージとデザインのガイダンスを追加します。

デフォルト Web アプリ（stacks/default-webapp.md）

• 用途：ほとんどのアプリケーション、汎用ツール
• 追加パッケージ：なし
• デザインの重点：すっきりとしてモダンで、実用的

データダッシュボード（stacks/data-dashboard.md）

• 用途：分析、管理パネル、データ可視化
• 追加パッケージ：Recharts（チャート）、date-fns（日付処理）
• デザインの重点：データ密度、階層的な情報、情報を素早く読み取るパターン

コンテンツショーケース（stacks/content-showcase.md）

• 用途：マーケティングサイト、ポートフォリオ、ブログ、ドキュメント
• 追加パッケージ：marked（Markdown の解析）
• デザインの重点：タイポグラフィのスケール、読書体験、余白

複雑なアプリケーション（stacks/complex-application.md）

• 用途：複数ビューのアプリ、SaaS プラットフォーム、エンタープライズツール
• 追加パッケージ：Zustand（状態管理）、date-fns
• デザインの重点：ナビゲーションパターン、状態アーキテクチャ、パフォーマンス

React 19 以降の機能

最新の React の機能を有効にします。

React Compiler

• ステータス：React 19 以降で利用可能
• メリット：自動メモ化により、初回の読み込みと操作が大幅に高速化されます
• セットアップ：React 17 以降と互換性があり、コンパイラー設定で構成します

useActionState Hook

• 用途：フォーム処理、非同期アクション、読み込み状態
• メリット：状態管理を簡素化し、非同期処理を組み込みで処理します
• パターン：フォームの状態、処理中の状態、エラー処理を一元化します

useOptimistic Hook

• 用途：サーバーで確認される前に UI を即座に更新します
• メリット：体感速度と UX が向上します
• パターン：失敗時に自動でロールバックする楽観的な更新

Server Components

• ステータス：React 19 以降で安定版（フレームワークモードのみ）
• フレームワーク：Next.js、TanStack Start
• 注記：Vite と React を使う SPA アプリでは、クライアントサイドレンダリングを使用します

プロジェクト構成のテンプレート

my-app/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── biome.json
├── src/
│   ├── main.tsx              # App entry point
│   ├── App.tsx               # Root component
│   ├── index.css             # Global styles + theme
│   ├── components/
│   │   ├── ui/               # shadcn components (don't edit)
│   │   └── ...               # Custom components
│   ├── hooks/
│   │   └── use-mobile.tsx
│   ├── lib/
│   │   ├── utils.ts          # cn() utility
│   │   └── data.ts           # Data schemas (if needed)
│   └── routes/               # TanStack Router routes
│       └── __root.tsx
└── public/                   # Static assets

デザイン哲学

美しいウェブアプリケーションは、単なる機能性を超え、感情を呼び起こし、記憶に残る体験を生み出します。次の原則に従ってください。

基本原則

1. 削ぎ落としてシンプルに：最もシンプルで効果的な解決策に至るまで、取り除きます
2. 素材の誠実さ：デジタル素材には独自の特性があります。それを活かします
3. 細部への徹底したこだわり：何百もの思慮深い判断が、優れた成果を生み出します
4. 一貫したデザイン言語：すべての要素が統一されたシステムの一部として感じられるようにします
5. 際立つビジュアルアイデンティティ：ありふれたパターンではなく、記憶に残る美しさを生み出します

重要な要件

• OKLCH カラーフォーマットを使用する（2026 年の必須要件）
• 多用されているフォントを避ける：Inter、Roboto、Arial、Space Grotesk
• 個性が際立つタイポグラフィを選ぶ：references/typography-pairings.md を参照してください
• 色のコントラストを検証する：WCAG AA（通常のテキストは 4.5:1、大きなテキストは 3:1）
• デフォルトでは単一のテーマにする：明示的な依頼がない限り、ダークモードは使用しません
• 可変フォント：パフォーマンス向上のため、単一の可変フォントファイルを使用します

包括的なデザインガイダンスについては、references/design-system.md を参照してください。

パフォーマンス目標（Core Web Vitals）

次の指標を最適化してください。

• INP（次の描画までのインタラクション）：200ms 未満
• LCP（最大コンテンツの描画）：2.5s 未満
• CLS（累積レイアウトシフト）：0.1 未満

目標達成に役立つツール：

• 自動メモ化には React Compiler
• コード分割と遅延読み込みには Vite
• 画像の最適化（WebP、AVIF、遅延読み込み）
• フォントの最適化（可変フォント、font-display: swap）

詳しい最適化戦略については、references/performance-checklist.md を参照してください。

参考資料

詳細なガイダンスは references/ ディレクトリにあります。

1. design-system.md - 包括的なデザイン哲学、空間構成、背景、マイクロインタラクション
2. typography-pairings.md - 個性を引き立てるガイダンス付きの、際立つフォントの組み合わせ
3. color-palettes.md - WCAG に基づく検証済みの、厳選された OKLCH パレット
4. component-patterns.md - 一般的な shadcn の構成と使用パターン
5. performance-checklist.md - Web Vitals の最適化、React Compiler のセットアップ
6. prd-template.md - 新しいアプリ向けの簡易計画フレームワーク
7. radix-migration-guide.md - Radix に関する課題に対応する Base UI への移行手順

実装ワークフロー

ステップ 1：プロジェクトを初期化する

重要：検証エラーを避けるため、shadcn init の実行前にパスエイリアスを設定してください。

# Create Vite project
pnpm create vite@latest my-app --template react-ts
# Note: Working directory is now my-app/ - no need to cd

# Install dependencies
pnpm install

# Add Tailwind CSS and tooling
pnpm add -D tailwindcss@latest @tailwindcss/vite
pnpm add -D @biomejs/biome
pnpm add -D @tanstack/router-plugin

TypeScript のパスエイリアスを設定する（shadcn に必要）：

tsconfig.json* を更新します：

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

tsconfig.app.json* を更新します：

{
  "compilerOptions": {
    // ... existing options ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

vite.config.ts* を更新します：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
import path from 'path'

export default defineConfig({
  plugins: [
    TanStackRouterVite(),
    react(),
    tailwindcss(),
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

* 設定例は Vite + React + TypeScript テンプレートの構成に基づいています

これで shadcn init が成功します：

# Initialize shadcn (path aliases now configured)
pnpm dlx shadcn@latest init

# CRITICAL: Install shadcn components BEFORE writing custom components
# Identify which components you need first
pnpm dlx shadcn@latest add button card input form dialog avatar badge separator

# Add TanStack packages
pnpm add @tanstack/react-router @tanstack/react-query

# Add utilities
pnpm add lucide-react motion sonner react-hook-form zod @hookform/resolvers
pnpm add clsx tailwind-merge class-variance-authority
pnpm add react-error-boundary next-themes

ステップ 2：プロジェクトを設定する

具体的な設定例については、stacks/ のスタックテンプレートを参照してください。

ステップ 3：PRD を作成する（任意ですが推奨）

references/prd-template.md を使って、以下を計画します：

• 目的とミッション
• 複雑さのレベル
• 必須機能
• デザインの方向性
• 色とタイポグラフィの選択

ステップ 4：最初に shadcn コンポーネントをインストールする

重要：コンポーネントのインストール順序

インポートするカスタムコンポーネントを作成する前に、必ず shadcn コンポーネントをインストールしてください。これにより、TypeScript エラーやビルドの失敗を防げます。

❌ 誤った順序（エラーの原因になります）：

# 1. Write PersonDetail.tsx that imports '@/components/ui/card'
# 2. Run pnpm dlx shadcn add card
# 3. Fix TypeScript errors 'Cannot find module @/components/ui/card'

✅ 正しい順序：

# 1. Plan which shadcn components you need
#    Example: Card, Avatar, Badge, Separator, Button

# 2. Install ALL required shadcn components FIRST
pnpm dlx shadcn@latest add card avatar badge separator button

# 3. Verify installation
ls src/components/ui/  # Should show: card.tsx, avatar.tsx, badge.tsx, etc.

# 4. NOW write PersonDetail.tsx that imports from '@/components/ui/*'
#    TypeScript will have proper types and components will exist

計画チェックリスト：

1. アプリに必要な UI コンポーネントをすべて列挙する
2. shadcn コンポーネント（Card、Button など）を特定する
3. すべてのコンポーネントを指定して shadcn add コマンドを 1 回実行する
4. src/components/ui/ に配置されていることを確認する
5. それらをインポートするカスタムコンポーネントを作成する

ステップ 5：ベストプラクティスに沿って実装する

• shadcn のコンポーネントパターンに従う
• :root CSS 変数で OKLCH カラーを使用する
• レスポンシブデザインを実装する（モバイルファースト）
• エラーバウンダリーを追加する
• 画像とフォントを最適化する
• Core Web Vitals をテストする

よくあるパターン

テーマ設定（index.css）

@import 'tailwindcss';

:root {
  /* OKLCH colors - mandatory format */
  --background: oklch(0.97 0.01 75);
  --foreground: oklch(0.25 0.02 55);
  --primary: oklch(0.52 0.14 155);
  --accent: oklch(0.72 0.13 55);

  /* Add more theme variables */
  --radius: 0.75rem;
}

@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-accent: var(--accent);

  /* Radius system */
  --radius-sm: calc(var(--radius) * 0.5);
  --radius-md: var(--radius);
  --radius-lg: calc(var(--radius) * 1.5);
}

注：Tailwind CSS v4+ の @import 構文を使用しています。v3 では、代わりに @tailwind ディレクティブを使用してください。

フォーム処理

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
});

function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: '', password: '' }
  });

  async function onSubmit(data: z.infer<typeof schema>) {
    // Handle form submission
  }

  return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;
}

データ取得

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

function UserList() {
  const queryClient = useQueryClient();

  const { data, isLoading } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers
  });

  const createUser = useMutation({
    mutationFn: createUserAPI,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    }
  });

  if (isLoading) return <LoadingSpinner />;
  return <UserGrid users={data} onCreate={createUser.mutate} />;
}

トラブルシューティング

Radix UI のメンテナンスに関する懸念

Radix UI の更新頻度は低下しています。新しいプロジェクトや移行を検討する場合：

• Base UI への移行方法については、references/radix-migration-guide.md を参照してください
• shadcn/ui は Base UI を代替としてサポートするようになりました
• React Aria も優れた選択肢です（Adobe が支援しており、アクセシビリティに優れています）

パフォーマンスの問題

アプリの動作が遅い場合：

1. React Compiler を有効にして、自動メモ化を利用する
2. Chrome DevTools で Core Web Vitals を確認する
3. references/performance-checklist.md を使用する
4. TanStack Router の遅延読み込みによるコード分割を検討する

ビルドツールの代替案

Rolldown バンドラーを搭載した新しい Vite バージョンは、安定すればビルドを高速化できる可能性があります。安定版リリースの情報を確認してください。

システム要件

• Node.js：18 以上（または現行の LTS バージョン）
• パッケージマネージャー：パフォーマンスのため pnpm を推奨
• OS：macOS、Linux、または WSL2 を使用した Windows

次のステップ

スキャフォールディングの後：

1. 複雑さのレベルに応じたスタックテンプレートを確認する
2. スタイリングについてはデザインリファレンスを参照する
3. 機能とデザインを計画するため、PRD を作成する
4. ベストプラクティスに従って実装する
5. Core Web Vitals に合わせて最適化する
6. 本番環境にデプロイする（Vercel、Netlify など）

---

覚えておいてください：目標は、機能的でパフォーマンスに優れた Web アプリケーションです。シンプルに始め、ユーザーのニーズに応じて改善し、技術的な複雑さよりもユーザーエクスペリエンスを優先してください。