primer-design

Primer デザイン指示

このスキルでは、HitHub Primer ブランドのデザインガイドラインに準拠した、本番品質のフロントエンドインターフェースの作成方法を説明します。Primer デザインシステムのガイドライン、Brand UI、Primer React Components、Octicons に細心の注意を払い、実際に動作するコードを実装してください。

ユーザーは、作成するコンポーネント、ページ、アプリケーション、またはインターフェースのフロントエンド要件を提示します。目的、対象ユーザー、技術的な制約に関する情報が含まれる場合もあります。

デザインの検討

コーディングを始める前に、背景を理解し、明確なデザインの方向性を定めてください。

• 目的：このインターフェースはどのような問題を解決しますか？誰が利用しますか？
• トーン：GitHub のプロフェッショナルでありながら親しみやすいブランドボイスに従ってください。明快で、親しみやすく、開発者を意識した表現にします。
• 制約：技術要件（フレームワーク、パフォーマンス、アクセシビリティ）
• 差別化：このデザインを印象的なものにする要素は何ですか？意図的な視覚的階層を取り入れた、すっきりと機能的なデザインを重視してください。

重要：明確なコンセプトの方向性を選び、正確に実現してください。Primer デザインシステムでは、装飾よりも明快さと使いやすさを重視します。

そのうえで、次の条件を満たす動作するコードを実装してください。

• 本番品質で、機能すること
• 視覚的に明快で、使いやすいこと
• Primer の設計原則に沿って一貫性があること
• あらゆる細部まで入念に仕上げられていること

制約

必ずブランドガイドラインに従ってください：https://brand.github.com/。

まずはこちらを参照してください：https://primer.style/brand/introduction/getting-started/。

インストールとセットアップ

1. 必要なパッケージをインストールします。

npm install @primer/react-brand @primer/octicons-react

2. 重要：ルートのレイアウト／アプリファイルで Primer CSS をインポートしてください。

import "@primer/react-brand/lib/css/main.css";

3. 重要：Vite／React Router で CommonJS との互換性に対応します。分割代入を使ったデフォルトインポートを使用してください。

// ✅ CORRECT - Use default import with destructuring for CommonJS compatibility
import pkg from "@primer/react-brand";
const { ThemeProvider, Button, Hero, Heading, Text, Grid, Stack } = pkg;

4. ルートでアプリを ThemeProvider でラップします。

import pkg from "@primer/react-brand";
const { ThemeProvider } = pkg;

function App() {
  return (
    <ThemeProvider>
      <div>...</div>
    </ThemeProvider>
  )
}

Primer React Components の使用

カスタム HTML／CSS ではなく、必ず公式の Primer React ブランドコンポーネントを使用してください。主なコンポーネント：

Hero コンポーネント

カスタムスタイルには className プロパティを使うか、パディング／マージンの調整には Box コンポーネントを使用してください。

import pkg from "@primer/react-brand";
const { Hero, Box } = pkg;

// ✅ OPTION 1: Using className with custom CSS
<Hero className="custom-hero-padding" align="center">
  <Hero.Label>Label</Hero.Label>
  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
  <Hero.Description>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </Hero.Description>
  <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
  <Hero.SecondaryAction href="#">Secondary action</Hero.SecondaryAction>
  <Hero.Image src="/path/to/image.png" alt="Description" />
</Hero>

// ✅ OPTION 2: Using Box component for layout
<Box paddingBlockStart={128} paddingBlockEnd={128}>
  <Hero align="center">
    <Hero.Label>Label</Hero.Label>
    <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
    <Hero.Description>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    </Hero.Description>
    <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
  </Hero>
</Box>

Octicons を使った Button コンポーネント

参照先：https://primer.style/brand/components/Button/react/

import pkg from "@primer/react-brand";
const { Button } = pkg;
import { PackageIcon, SearchIcon } from "@primer/octicons-react";

// ✅ CORRECT - Use leadingVisual/trailingVisual props for icons
<Button 
  variant="primary"
  leadingVisual={<PackageIcon />}
  hasArrow={false}
  block
>
  Add to Cart
</Button>

// Available variants: 'primary', 'secondary', 'subtle', 'accent'
// Available sizes: 'small', 'medium', 'large'
// Props: block, hasArrow, leadingVisual, trailingVisual

// ✅ Octicons support fill, className, and style props
<Button leadingVisual={<PackageIcon fill="#0969da" />}>
  Add to Cart
</Button>

// ✅ Also valid - using className
<Button leadingVisual={<PackageIcon className="custom-icon" />}>
  Add to Cart
</Button>

// ✅ Also valid - wrapping in div for additional styling
<Button leadingVisual={<div style={{ color: "#0969da" }}><PackageIcon /></div>}>
  Add to Cart
</Button>

レイアウトコンポーネント

import pkg from "@primer/react-brand";
const { Grid, Stack, Box } = pkg;

// Grid for responsive layouts
<Grid>
  <Grid.Column span={{ medium: 4 }}>Content</Grid.Column>
  <Grid.Column span={{ medium: 8 }}>Content</Grid.Column>
</Grid>

// Stack for consistent spacing
<Stack direction="vertical" gap="normal" padding="spacious">
  <div>Item 1</div>
  <div>Item 2</div>
</Stack>

// Box for padding, margin, background, and borders
<Box 
  paddingBlockStart={64} 
  paddingBlockEnd={64}
  backgroundColor="subtle"
  borderRadius="medium"
>
  <Heading>Content with spacing</Heading>
</Box>

Box コンポーネント：適切な間隔でレイアウトする際は、div の代わりに Box を使用してください。

• パディングのプロパティ：padding、paddingBlockStart、paddingBlockEnd、paddingInlineStart、paddingInlineEnd
• マージンのプロパティ：margin、marginBlockStart、marginBlockEnd、marginInlineStart、marginInlineEnd
• 値：スペーシングスケール（8、16、24、32、40、48、64、80、96、128）またはレスポンシブオブジェクトを使用します。
• 背景：backgroundColor="default" または "subtle"
• 枠線：borderColor、borderRadius、borderStyle

タイポグラフィコンポーネント

import pkg from "@primer/react-brand";
const { Heading, Text } = pkg;

<Heading as="h1" size="1">Main Heading</Heading>
<Heading as="h2" size="3">Section Heading</Heading>
<Text size="300" weight="semibold">Body text</Text>

Octicons を使ったアイコン

アイコンには、@primer/octicons-react の Octicons を必ず使用してください。

import { SearchIcon, PackageIcon, ChevronDownIcon } from "@primer/octicons-react";

// Use with Button leadingVisual/trailingVisual
<Button leadingVisual={<SearchIcon />}>Search</Button>

アイコンはこちらで確認できます：https://primer.style/octicons/

スタイリングの方針

1. カスタム HTML／CSS よりも Primer コンポーネントを優先する
2. ラッパーの div の代わりに、レイアウトの間隔（パディング、マージン）には Box コンポーネントを使用する
3. Primer コンポーネントの className プロパティを使い、外部 CSS でカスタムスタイルを設定する
4. インラインスタイルは、Box と className では適切に対応できない場合に限って使用する
5. CSS 変数ではなく、標準的な CSS 値（px、#0969da などの色）を使用する
6. GitHub のカラーパレットに従う：
   • プライマリブルー：#0969da
   • 成功を示すグリーン：#1f883d
   • 背景：#ffffff（白）、#f6f8fa（ライトグレー）
   • 枠線：#d0d7de
   • テキスト：#24292f（プライマリ）、#57606a（セカンダリ）

よく使うパターン

Box を使ったページレイアウト：

import pkg from "@primer/react-brand";
const { Box } = pkg;

<Box backgroundColor="subtle" style={{ minHeight: "100vh" }}>
  <Box 
    as="header" 
    backgroundColor="default" 
    borderColor="default"
    borderStyle="solid-bottom"
    paddingBlockStart={16} 
    paddingBlockEnd={16}
  >
    {/* Navigation */}
  </Box>
  <Box 
    as="main" 
    style={{ maxWidth: "1280px", margin: "0 auto" }}
    paddingBlockStart={48}
    paddingBlockEnd={48}
    paddingInlineStart={24}
    paddingInlineEnd={24}
  >
    {/* Content */}
  </Box>
  <Box 
    as="footer"
    borderColor="default"
    borderStyle="solid-top"
    paddingBlockStart={32}
    paddingBlockEnd={32}
  >
    {/* Footer */}
  </Box>
</Box>

Box を使ったカードコンポーネント：

<Box
  backgroundColor="default"
  borderColor="default"
  borderStyle="solid"
  borderRadius="medium"
  padding={24}
>
  {/* Card content */}
</Box>

アイコンのスタイリング：

// ✅ OPTION 1: Use fill prop directly on icon
<PackageIcon size={24} fill="#0969da" />

// ✅ OPTION 2: Use className prop
<PackageIcon size={24} className="custom-icon" />

// ✅ OPTION 3: Wrap in div (inherits currentColor)
<div style={{ color: "#0969da" }}>
  <PackageIcon size={24} />
</div>

// Octicons support: size, fill, className, style, aria-label, and all SVG props

コンポーネントリファレンス

コンポーネントと API の全ドキュメント：

• コンポーネントの概要：https://primer.style/brand/components/
• Button：https://primer.style/brand/components/Button/react/
• Hero：https://primer.style/brand/components/Hero/react/
• タイポグラフィ：https://primer.style/brand/typography/
• グリッド／レイアウト：https://primer.style/brand/layout/

アクセシビリティ

アクセシビリティのガイドラインに必ず従ってください：https://primer.style/accessibility/

• セマンティックな HTML を使用する
• 見出しの階層を適切に設定する
• 画像に代替テキストを設定する
• インタラクティブ要素にフォーカス状態を設定する
• 必要に応じて ARIA ラベルを設定する

テスト要件

作業を完了する前に、必ず変更をビルドしてテストしてください：

1. npm run build を実行して、TypeScript のエラーがないことを確認する
2. 開発モードでアプリケーションをテストする（npm run dev）
3. すべてのルートとナビゲーションが正しく動作することを確認する
4. レスポンシブな動作とアクセシビリティを確認する
5. ビルドまたは実行に失敗する変更を決して引き渡さない

よくある問題と解決策

問題：「Named export not found」エラーまたは CommonJS モジュールの警告

// ❌ WRONG - Named imports fail with CommonJS in dev/SSR
import { Button } from '@primer/react-brand';

// ❌ WRONG - Namespace imports may be undefined
import * as PrimerBrand from "@primer/react-brand";

// ✅ CORRECT - Use default import with destructuring
import pkg from "@primer/react-brand";
const { Button } = pkg;

問題：Primer コンポーネントにカスタムの間隔を設定したい

// ❌ AVOID - Wrapper divs add unnecessary DOM nesting
<div style={{ padding: "80px 24px" }}>
  <Hero>...</Hero>
</div>

// ✅ BETTER - Use className with CSS file
<Hero className="hero-spacing">...</Hero>

// ✅ BEST - Use Box component for layout
<Box paddingBlockStart={80} paddingBlockEnd={80} paddingInlineStart={24} paddingInlineEnd={24}>
  <Hero>...</Hero>
</Box>

問題：Octicon の色が反映されない

// ✅ CORRECT - Use fill prop for icon color
<PackageIcon fill="#0969da" />

// ✅ ALSO CORRECT - Set color on parent (icon inherits via currentColor)
<div style={{ color: "#0969da" }}>
  <PackageIcon />
</div>

// ✅ ALSO CORRECT - Use className
<PackageIcon className="text-blue" />

問題：ルートが機能しない（404 エラー）

• 新しいルートは必ず route() 関数を使って app/routes.ts に追加する

import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("products", "routes/products.tsx"),
] satisfies RouteConfig;