AI生成UIを超えるデザイン実装 — 型・トークン・条件分岐に判断を宿す実践テクニック

// まず、型で「許可される組み合わせ」を定義する
 
type ButtonVariant =
  | 'primary'     // メインアクション（最も視覚的に目立つ）
  | 'secondary'   // 補助的なアクション
  | 'destructive' // 削除・キャンセルなどの危険操作
  | 'ghost'       // 目立たない補助アクション
  | 'link';       // テキストリンク的なボタン
 
type ButtonSize =
  | 'sm'  // 34px - 密集レイアウト用（ただし実際は min-h-[34px] で調整）
  | 'md'  // 44px - タッチターゲット標準（モバイル・タブレット対応）
  | 'lg'; // 54px - CTA用（最も目立たせる場合）
 
type ButtonState =
  | 'default'   // 通常状態
  | 'loading'   // 処理中（cursor-wait, disabled）
  | 'disabled'  // 操作不可
  | 'success'   // 成功状態
  | 'error';    // エラー状態
 
interface ButtonProps {
  variant?: ButtonVariant;
  size?: ButtonSize;
  state?: ButtonState;
  children: React.ReactNode;
  onClick?: () => void | Promise<void>;
  ariaLabel?: string; // アクセシビリティ
}
 
export function Button({
  variant = 'primary',
  size = 'md',
  state = 'default',
  children,
  onClick,
  ariaLabel,
}: ButtonProps) {
  // 各 variant にはブランド判断が宿っている
  const variantStyles = {
    primary: {
      default: 'bg-primary text-white hover:bg-primary-dark focus:ring-primary/30',
      loading: 'bg-primary/70 text-white',
      disabled: 'bg-primary/40 text-white/70',
      success: 'bg-success text-white',
      error: 'bg-error text-white',
    },
    secondary: {
      default: 'bg-surface-alt text-text-primary hover:bg-gray-300 focus:ring-primary/20',
      loading: 'bg-surface-alt/70 text-text-primary',
      disabled: 'bg-surface-alt/50 text-text-primary/50',
      success: 'bg-success/20 text-success-dark border border-success/50',
      error: 'bg-error/20 text-error-dark border border-error/50',
    },
    destructive: {
      default: 'bg-error text-white hover:bg-error-dark focus:ring-error/30',
      loading: 'bg-error/70 text-white',
      disabled: 'bg-error/40 text-white/70',
      success: 'bg-success text-white',
      error: 'bg-error-dark text-white',
    },
    ghost: {
      default: 'text-text-primary hover:bg-surface-alt focus:ring-gray-300',
      loading: 'text-text-primary/70 bg-surface-alt/50',
      disabled: 'text-text-primary/40',
      success: 'text-success-dark bg-success/10',
      error: 'text-error-dark bg-error/10',
    },
    link: {
      default: 'text-primary underline hover:no-underline focus:ring-primary/30',
      loading: 'text-primary/70 cursor-wait',
      disabled: 'text-primary/40 cursor-not-allowed',
      success: 'text-success underline',
      error: 'text-error underline',
    },
  };
 
  const sizeStyles = {
    sm: 'px-2 py-1.5 text-sm',         // 34px (min-height で調整可能)
    md: 'px-4 py-2 text-base min-h-[44px]', // 44px 最小タッチターゲット
    lg: 'px-6 py-3 text-lg min-h-[54px]',   // 54px CTA用
  };
 
  const baseStyles = 'font-semibold rounded-md transition-all duration-150 focus:outline-none focus:ring-2';
 
  const isDisabled = state === 'disabled' || state === 'loading';
  const isLoading = state === 'loading';
 
  return (
    <button
      className={`${baseStyles} ${sizeStyles[size]} ${variantStyles[variant][state]}`}
      disabled={isDisabled}
      onClick={isLoading ? undefined : onClick}
      aria-busy={isLoading}
      aria-disabled={isDisabled}
      aria-label={ariaLabel}
    >
      {isLoading ? (
        <span className="flex items-center gap-sm">
          <span className="animate-spin w-4 h-4 border-2 border-current border-t-transparent rounded-full" />
          処理中…
        </span>
      ) : (
        children
      )}
    </button>
  );
}

// Button コンポーネント自体には as prop がないとします
// では、ボタン風のリンクを作りたい場合？
 
// 素朴な実装（判断が曖昧）
export function Button({ href, ...props }: ButtonProps & { href?: string }) {
  if (href) {
    return <a href={href} {...props} />;
  }
  return <button {...props} />;
}
 
// 良い実装: as prop で明示的に型指定
type ButtonElement = React.ElementType;
 
interface PolymorphicProps<T extends ButtonElement = 'button'> {
  as?: T;
  variant?: ButtonVariant;
  size?: ButtonSize;
  children: React.ReactNode;
}
 
type PolymorphicRef<T extends ButtonElement> = React.ComponentPropsWithRef<T>['ref'];
 
export const Button = React.forwardRef(
  <T extends ButtonElement = 'button'>(
    { as: Component = 'button' as T, variant = 'primary', size = 'md', ...props }: PolymorphicProps<T>,
    ref: PolymorphicRef<T>
  ) => {
    return (
      <Component
        ref={ref}
        className={`button button--${variant} button--${size}`}
        {...props}
      />
    );
  }
);
 
// 使い方
<Button>クリック</Button>                    // <button>
<Button as="a" href="/next">リンク</Button>  // <a>
<Button as="label" htmlFor="check">チェック</Button> // <label>

// ❌ 単純な実装
function Input({ error }: { error?: string }) {
  return (
    <>
      <input className={error ? 'border-red-500' : 'border-gray-300'} />
      {error && <span className="text-red-500">{error}</span>}
    </>
  );
}
 
// ✅ セマンティック実装
type ValidationState = 'default' | 'validating' | 'invalid' | 'valid';
 
interface InputProps {
  value: string;
  onChange: (val: string) => void;
  validationState?: ValidationState;
  errorMessage?: string;
  successMessage?: string;
  isRequired?: boolean;
  ariaDescribedBy?: string;
}
 
export function Input({
  value,
  onChange,
  validationState = 'default',
  errorMessage,
  successMessage,
  isRequired,
  ariaDescribedBy,
}: InputProps) {
  const inputId = `input-${Math.random().toString(36).slice(2)}`;
  const validationId = `${inputId}-validation`;
 
  // 状態に応じたスタイルロジック
  const getStateStyles = (state: ValidationState) => {
    switch (state) {
      case 'validating':
        return 'border-blue-400 bg-blue-50 cursor-wait';
      case 'invalid':
        return 'border-red-500 bg-red-50 focus:ring-red-300';
      case 'valid':
        return 'border-green-500 bg-green-50 focus:ring-green-300';
      default:
        return 'border-gray-300 focus:ring-blue-300';
    }
  };
 
  // アクセシビリティ属性の条件付き付与
  const getAriaProps = () => {
    const attrs: Record<string, any> = {
      'aria-invalid': validationState === 'invalid',
      'aria-busy': validationState === 'validating',
      'aria-required': isRequired,
    };
 
    if (validationState === 'invalid' || validationState === 'validating') {
      attrs['aria-describedby'] = [validationId, ariaDescribedBy]
        .filter(Boolean)
        .join(' ');
    }
 
    return attrs;
  };
 
  return (
    <div className="flex flex-col gap-sm">
      <input
        id={inputId}
        value={value}
        onChange={(e) => onChange(e.target.value)}
        className={`border-2 px-3 py-2 rounded-md transition-all ${getStateStyles(
          validationState
        )}`}
        {...getAriaProps()}
      />
 
      {/* 条件付きメッセージ表示: role と aria-live で自動読み上げ */}
      {validationState === 'invalid' && errorMessage && (
        <div
          id={validationId}
          role="alert"
          aria-live="assertive"
          className="text-red-600 text-sm font-medium"
        >
          {errorMessage}
        </div>
      )}
 
      {validationState === 'valid' && successMessage && (
        <div
          id={validationId}
          role="status"
          aria-live="polite"
          className="text-green-600 text-sm font-medium"
        >
          {successMessage}
        </div>
      )}
 
      {validationState === 'validating' && (
        <div className="text-blue-600 text-sm flex items-center gap-xs">
          <span className="animate-spin w-3 h-3 border-2 border-current border-t-transparent rounded-full" />
          検証中…
        </div>
      )}
    </div>
  );
}

// カード風のコンポーネント: 複雑な内部構造を持つ
interface CardProps {
  children: React.ReactNode;
}
 
export function Card({ children }: CardProps) {
  return <div className="border rounded-lg p-lg">{children}</div>;
}
 
interface CardHeaderProps {
  children: React.ReactNode;
}
 
export function CardHeader({ children }: CardHeaderProps) {
  return <div className="border-b pb-md mb-md font-semibold text-lg">{children}</div>;
}
 
interface CardBodyProps {
  children: React.ReactNode;
}
 
export function CardBody({ children }: CardBodyProps) {
  return <div>{children}</div>;
}
 
interface CardFooterProps {
  children: React.ReactNode;
}
 
export function CardFooter({ children }: CardFooterProps) {
  return (
    <div className="border-t mt-md pt-md flex gap-md justify-end">{children}</div>
  );
}
 
// 使い方
<Card>
  <CardHeader>ユーザー情報</CardHeader>
  <CardBody>
    <p>名前: 山田太郎</p>
    <p>メール: yamada@example.com</p>
  </CardBody>
  <CardFooter>
    <Button>キャンセル</Button>
    <Button variant="primary">保存</Button>
  </CardFooter>
</Card>

// より柔軟性を持たせたい場合
interface CardProps {
  header?: React.ReactNode;
  body: React.ReactNode;
  footer?: React.ReactNode;
}
 
export function Card({ header, body, footer }: CardProps) {
  return (
    <div className="border rounded-lg p-lg">
      {header && <div className="border-b pb-md mb-md font-semibold text-lg">{header}</div>}
      <div>{body}</div>
      {footer && (
        <div className="border-t mt-md pt-md flex gap-md justify-end">{footer}</div>
      )}
    </div>
  );
}
 
// 使い方
<Card
  header="ユーザー情報"
  body={<p>名前: 山田太郎</p>}
  footer={<Button>保存</Button>}
/>

// データフローを柔軟に制御したい場合
interface DataListProps<T> {
  data: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  renderEmpty?: () => React.ReactNode;
  isLoading?: boolean;
}
 
export function DataList<T>({
  data,
  renderItem,
  renderEmpty,
  isLoading,
}: DataListProps<T>) {
  if (isLoading) {
    return <div className="p-lg text-center">読み込み中…</div>;
  }
 
  if (data.length === 0) {
    return renderEmpty?.() ?? <div className="p-lg text-center">データがありません</div>;
  }
 
  return <div className="space-y-md">{data.map((item, i) => renderItem(item, i))}</div>;
}
 
// 使い方
<DataList
  data={users}
  renderItem={(user) => (
    <div className="border p-md">
      <p>{user.name}</p>
      <p className="text-gray-500">{user.email}</p>
    </div>
  )}
  renderEmpty={() => <p className="text-center text-gray-400">ユーザーが見つかりません</p>}
/>

# デザイントークン定義ファイル (design-tokens.ts)
 
以下の内容を Antigravity が参照できる状態にしてください:
 
## Color Palette
- primary: oklch(0.55 0.2 260)
- secondary: oklch(0.65 0.15 260)
- success: oklch(0.58 0.15 142)
- warning: oklch(0.68 0.15 65)
- error: oklch(0.55 0.2 25)
- surface: oklch(0.98 0.002 0)
 
## Spacing Scale (Fibonacci)
- xs: 0.25rem (4px)
- sm: 0.5rem (8px)
- md: 1rem (16px)
- lg: 1.5rem (24px)
- xl: 2.5rem (40px)
- xxl: 4rem (64px)
 
## Typography
- base: 1rem / 1.6 line-height
- h2: 1.75rem / 1.3 line-height (見出しは行間を詰めて視覚的重量を出す)
- h1: 2.25rem / 1.2 line-height

# Button コンポーネント実装依頼
 
上記のトークンファイルを参照してください。
 
## 要件
 
1. **variant の5パターン実装**:
   - primary: 最も視覚的に目立つ主要アクション
   - secondary: 補助的なアクション
   - destructive: 削除・キャンセルなどの危険操作。エラーカラーを使用し、ユーザーの注意を引く
   - ghost: 目立たない補助アクション。背景は透明で、ホバー時のみ背景色を付ける
   - link: テキストリンク風。下線あり、ホバー時に下線なし
 
2. **size の3パターン**:
   - sm: 密集レイアウト用（テキストサイズ: text-sm）
   - md: タッチターゲット標準。min-h-[44px] で高齢ユーザーの指にも対応
   - lg: CTA用の最大サイズ。min-h-[54px]
 
3. **state の管理**:
   - default: 通常状態
   - loading: 処理中。cursor-wait を表示し、opacity-70 で視覚的に無効化。ARIA: aria-busy="true"
   - disabled: 操作不可。opacity-50, cursor-not-allowed. ARIA: aria-disabled="true"
   - success: 成功後の表示。サクセスカラーを使用
   - error: エラー表示。エラーカラーを使用
 
4. **アクセシビリティ**:
   - aria-busy, aria-disabled を state に基づいて動的に付与
   - disabled 属性の管理（loading または disabled 時は disabled 属性をセット）
   - focus:ring-2 で focus-visible を視覚化
 
5. **コメント記述**:
   - なぜその条件分岐を選んだのか、各セクションに「理由」を書いてください
   - 例: "// min-h-[44px]: 高齢者やタッチペン利用者を含む全ユーザーが安全に操作できるサイズ"
 
## 出力形式
 
TypeScript React component (React.forwardRef なし、シンプルな関数コンポーネント)

# レビューチェックリスト
 
Antigravity が出力したコンポーネントを検査:
 
□ **トークンの使用**
  - oklch で定義された色のみ使用されているか？
  - ハードコードされた色値 (#RGB や rgb()) がないか？
  - spacing は token を参照しているか？
 
□ **型の厳密性**
  - variant, size, state は制限された文字列リテラルか？
  - 無効な組み合わせを型レベルで排除できるか？
 
□ **アクセシビリティ**
  - aria-* 属性が state に応じて条件付き付与されているか？
  - disabled 属性と disabled 状態が連動しているか？
  - focus-visible が css で表現されているか？
 
□ **条件分岐の明瞭性**
  - 各分岐に「なぜこうするのか」コメントがあるか？
  - 複雑な三項演算子を避け、変数に分離しているか？
 
□ **パフォーマンス**
  - 不要な className 連結がないか？
  - styles オブジェクトが最適化されているか？
 
修正が必要な場合は、Antigravity に「なぜ」を追加するよう指示する。

// components/Button.stories.tsx
import { Button } from './Button';
 
export default {
  title: 'Components/Button',
  component: Button,
};
 
export const Primary = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
};
 
export const PrimaryLoading = {
  args: {
    variant: 'primary',
    state: 'loading',
    children: 'Processing',
  },
};
 
export const Destructive = {
  args: {
    variant: 'destructive',
    children: 'Delete',
  },
};
 
export const DestructiveDisabled = {
  args: {
    variant: 'destructive',
    state: 'disabled',
    children: 'Delete',
  },
};

// token-sync.ts - Figma のトークンをコードに自動生成
 
import { readFileSync } from 'fs';
 
const figmaTokens = JSON.parse(readFileSync('./tokens.json', 'utf-8'));
 
// oklch 色値を Tailwind カスタムカラーに変換
const colors = Object.entries(figmaTokens.colors).reduce((acc, [key, value]) => {
  acc[key] = value; // oklch() 形式のまま
  return acc;
}, {});
 
export const tailwindConfig = {
  theme: {
    colors,
  },
};

# デザイン判断ログ
 
## 2026-03-27: oklch 色空間への移行
 
**判断**: RGB や HSL ではなく oklch を採用
 
**理由**:
- 知覚均等性が高く、lightness の差が画面のどこでも同じに見える
- UI 色の調整が容易（saturation を減らすだけで淡い版が得られる）
- 印刷業界の CIELAB が基になっており、デザイナーの感覚と合致しやすい
 
**代替案との比較**:
- HSL: 色相の変化で彩度・明度が勝手に変わる（デメリット）
- Tailwind 標準カラー: ブランド性が弱い（デメリット）
 
**影響範囲**:
- tailwind.config.ts
- Figma デザイントークン
- サイト全体のブランドカラー
 
---
 
## 2026-03-27: ボタンの min-h-[44px] 化
 
**判断**: すべてのボタンに 44px 最小高さを設定
 
**理由**:
- WCAG 2.5.5 (Target Size) で「最小44×44pxの操作対象」を推奨
- 高齢者、視力低下者、触覚障害者の操作性向上
- モバイル・タッチペン環境での誤クリック防止
 
**代替案との比較**:
- 32px (Apple HIG): iOS 内部アプリケーション用。Web は44px推奨
- 54px (Google Material): 大きすぎる。md サイズは 44px で十分
 
**段階的導入**:
- Phase 1: 新規コンポーネントに適用 ✅
- Phase 2: 既存ボタンを段階移行
- Phase 3: フォーム入力も同基準に統一予定

// FormField: Label + Input + Error の一体化
interface FormFieldProps {
  label: string;
  value: string;
  onChange: (val: string) => void;
  error?: string;
  isRequired?: boolean;
}
 
export function FormField({
  label,
  value,
  onChange,
  error,
  isRequired,
}: FormFieldProps) {
  const id = `field-${Math.random().toString(36).slice(2)}`;
 
  return (
    <div className="flex flex-col gap-sm">
      <label htmlFor={id} className="font-medium">
        {label}
        {isRequired && <span className="text-error ml-1">*</span>}
      </label>
 
      <Input
        id={id}
        value={value}
        onChange={onChange}
        validationState={error ? 'invalid' : 'default'}
        errorMessage={error}
        ariaDescribedBy={id}
      />
    </div>
  );
}