Web Frontend Builder

Open Elements テックスタックを使用して、本番環境対応のウェブフロントエンドアプリケーションを構築します。フロントエンドプロジェクトを作成または拡張するには、以下のステップに従ってください。

スタック: Next.js + React 18 + TypeScript (strict) + Tailwind CSS + shadcn/ui + pnpm

重要: ../../conventions/typescript.md のすべての規約が適用されます。判断に迷った場合はそのドキュメントを参照してください。

デザインガイドライン

デザイン方針と視覚品質については、frontend-design スキルを適用してください。主な原則:

• すべてのページとコンポーネントは、初期段階のプロジェクトであっても洗練されたプロフェッショナルな外観を持つ必要があります。
• 素の HTML 要素の代わりに shadcn/ui コンポーネントを使用します。
• open-elements-brand-guidelines スキルを使用して、Open Elements ブランドカラーとタイポグラフィを適用します。
• 一般的な AI の美学を避けます: 過度な中央配置、紫色グラデーション、均一な角丸、デフォルトの Inter フォントは使用しません。

新しいプロジェクトの作成

ステップ 1: Next.js でスキャフォールディング

pnpm create next-app <project-name> --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd <project-name>

ステップ 2: Next.js を設定

next.config.ts を編集してスタンドアロン出力を設定します(Docker デプロイメントに必須):

const nextConfig = {
  output: 'standalone',
};

重要: Next.js は next.config.ts(例: API リライト用の rewrites())をビルド時に評価します。next.config.ts で使用される環境変数(例: API リライト用の BACKEND_URL)は pnpm build の実行時に利用可能である必要があります。Docker では、これはビルド引数(ARG)として宣言し、ビルドステップ前に Dockerfile の環境変数(ENV)として設定する必要があります。docker-compose.yml の実行時のみの environment: エントリは遅すぎます。リライトルールはすでにビルド出力に焼き込まれています。fullstack-architecture-setup スキルで Dockerfile と Docker Compose の設定を確認してください。

ステップ 3: 厳密な TypeScript を有効化

tsconfig.json に "strict": true があることを確認します。これは必須条件です。

ステップ 4: shadcn/ui を初期化

pnpm dlx shadcn@latest init

プロンプトが表示されたら、プロジェクトのデザイン方針に一致するデフォルト値を選択します。その後、必要なコンポーネントをインストールします:

pnpm dlx shadcn@latest add button card input table dialog

開発中に必要に応じてさらにコンポーネントを追加してください。

ステップ 5: shadcn MCP サーバーを設定

プロジェクトの .mcp.json に追加します:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

ステップ 6: ブランドカラーとセマンティックトークンを設定

tailwind.config.ts で Open Elements ブランドカラーを設定して、ユーティリティクラスとして利用可能にします。正確なカラー値は open-elements-brand-guidelines スキルを使用して取得してください。

重要: shadcn/ui コンポーネントはセマンティック CSS カスタムプロパティ(例: --color-background、--color-popover、--color-border)を参照します。これらは src/app/globals.css の @theme ブロックで定義し、プロジェクトのブランドカラーにマップする必要があります。これらがないと、ダイアログ、ドロップダウン、テーブル、入力フィールドが透明な背景と欠落したボーダーでレンダリングされます。

必須セマンティックトークン(各種に該当する場合 -foreground があります):

トークン	目的
background / foreground	メインページの背景とテキスト
card / card-foreground	カード表面
popover / popover-foreground	ダイアログ、ドロップダウン、ポップオーバー
muted / muted-foreground	ホバー状態、無効化要素、セカンダリテキスト
accent / accent-foreground	ハイライト表示アイテム(例: ホバー中の選択肢)
primary / primary-foreground	プライマリアクションボタン
secondary / secondary-foreground	セカンダリアクションボタン
destructive / destructive-foreground	削除/エラーボタン
border	すべてのコンポーネントボーダー(テーブル、カード、入力)
input	入力フィールドボーダー
ring	フォーカスリング表示

詳細は shadcn/ui テーマドキュメントを参照してください。コンポーネントファイルにカラーをハードコードしないでください。常にセマンティックトークンを使用してください。

ステップ 7: セットアップを検証

pnpm dev

開発サーバーがエラーなく起動することを確認します。

機能開発

ページを追加

Next.js App Router の規約に従って src/app/ にページを作成します:

• src/app/page.tsx — ホームページ
• src/app/<route>/page.tsx — 追加ページ
• src/app/layout.tsx — 一貫したヘッダー/ナビゲーションとフッターを備えたルートレイアウト

重要: バックエンド API からデータをフェッチするページは、静的プリレンダリングされてはいけません。export const dynamic = 'force-dynamic' を使用してリクエスト時レンダリングを確保してください。

コンポーネントを追加

再利用可能なコンポーネントを src/components/ に配置します。これらの規約に従ってください:

• 1 ファイル 1 コンポーネント、エクスポート名と一致する PascalCase で命名
• shadcn/ui コンポーネントをビルディングブロックとして使用。素の HTML 相当物は作成しない
• shadcn/ui Blocks をレイアウト構造(サイドバーシェル、ダッシュボードレイアウト)の開始点として使用
• Tailwind のスペーシングスケールを使用した一貫した間隔(p-4、p-6、gap-4、gap-6)
• 可読性のためにコンテンツ幅を制限(max-w-screen-xl mx-auto)
• Tailwind のレスポンシブプリフィックス(sm:、md:、lg:)でレスポンシブデザインを確保

国際化

すべてのユーザー向けテキストは最初から i18n 対応にする必要があります:

• すべての表示文字列を一元的な場所(定数ファイルまたは翻訳ファイル)に抽出
• 一貫したキー命名を使用(page.section.element)
• プレースホルダ付きのパラメータ化されたメッセージを使用("Welcome, {name}" ではなく "Welcome, " + name は不可)
• 日付、数値、通貨のフォーマットをロケール対応に(Intl.DateTimeFormat、Intl.NumberFormat)

エラーハンドリング

• 詳細なエラーをブラウザコンソールにログ(HTTP ステータス、エンドポイント URL、エラー本体)
• 生のバックエンドエラーメッセージをユーザーに表示しない。シンプルでユーザーフレンドリーなメッセージを表示
• 共有 API クライアントレイヤーでバックエンドエラーハンドリングを一元化

テスト

プロジェクトに存在するテスティングフレームワークを使用(Jest、Vitest、または Node テストランナー):

pnpm test

• テストに説明的な名前を付ける: it('should return empty array when no items exist')
• 関連するテストを describe ブロックでグループ化
• 過度なモッキングを避ける。シンプルなスタブ/ダミー実装を優先

一般的なコマンド

• 依存関係をインストール: pnpm install
• 開発サーバー: pnpm dev
• ビルド: pnpm build
• テストを実行: pnpm test
• Lint: pnpm lint
• 型チェック: pnpm tsc --noEmit

品質チェックリスト

機能が完成したと判断する前に、以下を確認してください:

• pnpm build がエラーなく成功する
• pnpm lint が通る
• pnpm tsc --noEmit が型エラーを報告しない
• すべてのページがレスポンシブ(モバイル、タブレット、デスクトップ)
• shadcn/ui コンポーネントが存在する場所に素の HTML 要素がない
• ハードコードされたユーザー向け文字列がない。すべてが i18n 対応
• 本番コードに console.log がない。console.error、console.warn、console.info を使用
• 機密データがブラウザコンソールにログされていない
• next.config.ts でスタンドアロン出力が設定されている
• Tailwind config 経由でブランドカラーが適用されている
• すべての shadcn/ui セマンティック CSS トークンが globals.css の @theme ブロックで定義されている

リファレンス

• Next.js ドキュメント: https://nextjs.org/docs
• shadcn/ui コンポーネント: https://ui.shadcn.com/docs/components
• shadcn/ui Blocks: https://ui.shadcn.com/blocks
• Tailwind CSS: https://tailwindcss.com/docs