create-component

Astro コンポーネントの作成

機能リクエスト、デザイン、または静的なマークアップをもとに、新しい Astro コンポーネント、ページ、レイアウト、ルートを作成するときに、このスキルを使用します。

astro-best-practices が利用可能な場合は、プロジェクト全体の規約とレビュー基準に沿って、このスキルと併用してください。

ワークフロー

1. 適切なファイルの種類を選ぶ

要件に合う最もシンプルなプリミティブを選びます。

• コンポーネント：再利用可能な UI を src/components/ に配置します
• ページ：ルートエントリを src/pages/ に配置します
• レイアウト：共有シェルを src/layouts/ に配置します
• フレームワークアイランド：インタラクティブ性が必要な場合に限り、React、Vue などを使用します

クライアント側のフレームワーク状態が本当に必要な場合を除き、.astro から始めます。

2. コントラクトを明確にする

作成に取りかかる前に、次の点を確認します。

• ファイルが受け取る props
• 子要素または名前付きスロットをレンダリングするかどうか
• データを取得するかどうか
• インタラクティブ性が必要かどうか
• プロジェクトですでに採用されているスタイリング方法

公開するインターフェースは小さく保ちます。prop によってレンダリングが実質的に変わらないのであれば、その prop は不要な可能性があります。

3. 適切なデフォルトで作成する

型付き props とセマンティックな構造を使用します。

---
interface Props {
  title: string
  variant?: 'primary' | 'secondary'
}

const { title, variant = 'primary' } = Astro.props
---

<section class:list={['card', variant]}>
  <h2>{title}</h2>
  <slot />
</section>

<style>
  .card {
    padding: 1rem;
  }
</style>

適切なデフォルト：

• 汎用的な div よりセマンティックな要素を優先する
• 論理的な見出し構造にする
• 妥当な prop のデフォルト値を設定する
• プロジェクトで意図的に別のパターンを使っている場合を除き、スコープ付きスタイルを使用する
• マークアップが明確になる場合は、条件付きクラスに class:list を使用する

4. 必要な場合にのみインタラクティブ性を追加する

コンポーネントにクライアント側の動作が必要な場合：

• インタラクティブな部分はできるだけ小さく保ちます
• プロジェクトでそのパターンが採用されている場合は、フレームワークコンポーネントに分離します
• 動作する中で最も軽量なハイドレーションディレクティブを選びます

例：

---
import SearchBox from './SearchBox.tsx'
---

<SearchBox client:visible />

小さなインタラクティブなリーフコンポーネントで十分な場合は、ページの大部分をアイランドにすることは避けてください。

5. アクセシビリティと堅牢性を確認する

コンポーネントの完成とする前に、次の点を確認します。

• セマンティック HTML が適切である
• インタラクティブな要素にキーボードでアクセスできる
• 表示ラベルとアクセシブルな名前がある
• 画像の alt の扱いが適切である
• 見出しレベルが文脈に合っている
• フォーカス状態が見える状態に保たれている

6. コンポーネントをプロジェクトに適合させる

既存のコードベースに合わせます。

• 命名規則に従う
• 既存のレイアウトとスタイリング方法を維持する
• 相対インポートを使用し、読みやすく保つ
• 静的 HTML を再現するだけのためにフレームワークの依存関係を追加しない

このスキルを使用する場面

• 静的 HTML を Astro コンポーネントに変換する
• 新しいルートやレイアウトを作成する
• 大きな Astro ファイルを小さなパーツに分割する
• デザインをアクセシブルな Astro マークアップにする