@cakejp/design-system 0.12.0 → 0.13.0

package/dist/types/components/ec/admin-shell.d.ts

@@ -4,6 +4,22 @@
  * 本番の shop_layout.ctp を参考に、Header + SideNav + Main Content の構造を再現。
  * 汎用の枠は primitives（AdminSideNav / AdminHeader）に切り出し、
  * Cake.jp 管理メニュー等のドメイン既定値はこの ec レイヤーで束ねる。
+ *
+ * ## サイドナビの構造（採用前に確認すること）
+ *
+ * - **PC**: 左端固定の **72px アイコンレール**（アイコン + 短いラベル、サブメニューは hover ポップアップ）。
+ *   幅が無いため、バッジ・見出し・説明文からなる**ブランドブロックをレール上部に置くことはできない**。
+ *   他ブランドの管理画面でブランドを出したい場合は `brand`（ヘッダー左側）を使う。
+ * - **SP**: ドロワー。上部見出しは `sidebarHeader`（未指定なら `shopName`）で差し替えられる。
+ *
+ * 「幅の広いブランド付きサイドバー」を前提にした画面は、この骨格とは別パターンなので
+ * そのまま置き換えられない（DS に issue を立てること）。
+ *
+ * ## 配下 Card のサーフェス
+ *
+ * 地が Surface-Secondary なので、シェルが配下 `Card` の既定サーフェスを白にする文脈
+ * （`--card-surface`）を宣言する。`Card` は `surface` 未指定のまま地から浮く（#150）。
+ *
  * 参照元:
  * - admin-test-htdocs/app/views/layouts/shop_layout.ctp
  * - admin-test-htdocs/app/views/elements/shop_layout/header.ctp
@@ -28,8 +44,20 @@ export interface AdminShellProps {
         label: string;
         href?: string;
     }[];
-    /** ショップ名 */
+    /** ショップ名。ヘッダーの `{shopName}管理` と SP ドロワー見出しの既定値になる */
     shopName?: string;
+    /**
+     * ヘッダー左側のブランド表示を差し替える（既定=`{shopName}管理` の文字列）。
+     * ロゴ画像・バッジ付きブランドブロック等、文字列で表せない表現に使う。
+     * ※ PC の左サイドナビは 72px のアイコンレールでブランドブロックを置く領域が無いため、
+     *   他ブランドの管理画面はここ（ヘッダー）でブランドを表現する。
+     */
+    brand?: React.ReactNode;
+    /**
+     * SP ドロワー上部の見出しを差し替える（既定=`shopName` の文字列）。
+     * バッジ＋見出し＋説明のようなブランドブロックを置ける。
+     */
+    sidebarHeader?: React.ReactNode;
     /** サイドナビ項目（既定=Cake.jp 管理メニュー。利用側で差し替え可） */
     navItems?: AdminNavItem[];
     /** ヘッダー右側のアクション slot（既定=通知ベル＋プロフィール） */
@@ -52,4 +80,4 @@ export interface AdminShellProps {
      */
     skipLink?: false;
 }
-export declare function AdminShell({ children, activeNav, title, breadcrumbs, shopName, navItems, headerActions, onBack, backLabel, mainId, skipLink, }: AdminShellProps): import("react/jsx-runtime").JSX.Element;
+export declare function AdminShell({ children, activeNav, title, breadcrumbs, shopName, brand, sidebarHeader, navItems, headerActions, onBack, backLabel, mainId, skipLink, }: AdminShellProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/components/foundations/card.d.ts

@@ -2,9 +2,33 @@ import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 /**
  * Card の背景サーフェス。
- * - `default`: `bg-card`（= Surface-Secondary）。通常の白/明るい地の上で使う既定値。
- * - `primary`: `Surface-Primary`（白）。グレー Section（Surface-Tertiary）の地の上に
- *   置く際、既定の `bg-card` ではコントラストが不足するため白背景に切り替える。
+ * - `default`: `--card-surface`（親から伝播したサーフェス文脈）→ 無ければ `--card`
+ *   （= Surface-Secondary）。通常の白/明るい地の上ではこれまで通り `bg-card` と同値。
+ * - `primary`: `Surface-Primary`（白）。文脈に関係なく白で固定したいときに明示指定する。
+ *
+ * ## サーフェス文脈の伝播（#150）
+ *
+ * `Section background="subtle" | "accent-subtle"` は配下に `--card-surface: var(--Surface-Primary)`
+ * を流す。そのため**グレー地の Section に置いた Card は `surface` 未指定でも自動で白**になり、
+ * 「あとからカードを1枚足したら prop を付け忘れてグレー地に沈む」事故が構造的に起きない。
+ *
+ * 伝播は CSS カスタムプロパティのカスケードだけで成立する（React context 不使用）。
+ * したがって Card / Section は Server Component のまま使え、DS の `Section` を使わない
+ * 自前のグレー地でも同じ効果を得られる:
+ *
+ * ```tsx
+ * // 任意の要素にサーフェス文脈を宣言する（consumer 側の escape hatch）
+ * <div className="bg-[var(--Surface-Tertiary)] [--card-surface:var(--Surface-Primary)]">
+ *   <Card />  // 白になる
+ * </div>
+ * ```
+ *
+ * dark では `Section` は伝播値を `Surface-Secondary` に据え置く（dark のカードは半透明白で
+ * 地に重なり一段明るく浮くため、白の強制は elevation の反転になる）。自前で文脈を宣言する
+ * ときも dark に配慮するなら `dark:[--card-surface:var(--Surface-Secondary)]` を併記する。
+ *
+ * 逆に文脈を無視して Surface-Secondary に固定したい 1 枚だけは
+ * `<Card className="bg-card">` で上書きする（className が最後に勝つ）。
  */
 declare const cardVariants: (props?: {
     surface?: "default" | "primary";

package/dist/types/components/foundations/field.d.ts

@@ -7,12 +7,14 @@
  *
  * ### インポート
  * ```tsx
- * import { FieldSet, FieldLegend, FieldGroup, FieldDescription, FieldError, FieldSeparator } from "../../components/foundations/field"
+ * import { Field, FieldLabel, FieldSet, FieldLegend, FieldGroup, FieldDescription, FieldError, FieldSeparator } from "../../components/foundations/field"
  * ```
  *
  * ### 構成要素
  * | 要素 | DOM | 役割 |
  * |------|-----|------|
+ * | `Field` | `<div role="group">` | **1 フィールド分の箱**（縦リズムの最小単位）。`orientation` で vertical / horizontal / responsive |
+ * | `FieldLabel` | `<Label>` ラップ | Field 内のラベル（`htmlFor` で入力と関連付け） |
  * | `FieldSet` | `<fieldset>` | フォーム全体 or 大セクション。legend + 複数グループを縦リズム gap-6 で並べる |
  * | `FieldLegend` | `<legend>` | FieldSet の見出し |
  * | `FieldGroup` | `<div role="group">` | 関連する複数フィールドを section-content リズム gap-4 で束ねる |
@@ -21,11 +23,30 @@
  * | `FieldSeparator` | `<Separator>` ラップ | フィールド群の区切り。children を渡すと中央ラベル付き |
  *
  * ### AI 向け使用ルール
- * - 個々の入力欄は `FormField`（primitives）を使う。Field 群はその外側の骨格を組む
+ * - ラベル + 入力 + エラーが一体で済むなら `FormField`（primitives）が最短。
+ *   ラベル・入力・説明・エラーを個別に組み立てたいときは `Field` + `FieldLabel` を使う
+ * - `Field` は `FieldGroup` の中に置く（`orientation="responsive"` は `FieldGroup` の
+ *   `@container/field-group` を基準に、狭いと縦・広いと横へ切り替わる）
  * - 余白は composition.json の縦リズムに従う（FieldSet=gap-6 / FieldGroup=gap-4）。手で mt-/mb- を足さない
  * - 見出しは `FieldLegend`、グループ横断の区切りは `FieldSeparator` を使う
  */
 import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+import { Label } from "../../components/foundations/label";
+/**
+ * Field — 1 フィールド分の箱（ラベル + 入力 + 説明/エラー）。
+ * `FieldGroup`（gap-4）の中に並べる**縦リズムの最小単位**。
+ * これが無いと「1 フィールドの内側の並べ方」が consumer 実装依存になる。
+ */
+declare const fieldVariants: (props?: {
+    orientation?: "horizontal" | "vertical" | "responsive";
+} & import("class-variance-authority/types").ClassProp) => string;
+declare function Field({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>): import("react/jsx-runtime").JSX.Element;
+/**
+ * FieldLabel — Field 内のラベル。DS の `Label` に DS のタイポ（typo-label-md）と
+ * 無効時の色を当てたもの。`htmlFor` で入力と関連付ける。
+ */
+declare function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>): import("react/jsx-runtime").JSX.Element;
 /**
  * FieldSet — フォーム全体 or 大きなセクションの枠。
  * `<fieldset>` の既定スタイル（ブラウザ枠線・padding）をリセットし、
@@ -55,4 +76,6 @@ declare function FieldError({ className, children, ...props }: React.ComponentPr
  * 上下に余白を持たせる。children を渡すと中央にラベル（「または」等）を表示。
  */
 declare function FieldSeparator({ className, children, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
-export { FieldSet, FieldLegend, FieldGroup, FieldDescription, FieldError, FieldSeparator, };
+export { Field, FieldLabel, FieldSet, FieldLegend, FieldGroup, FieldDescription, FieldError, FieldSeparator, };
+export { fieldVariants };
+export type FieldProps = React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>;

package/dist/types/components/foundations/input.d.ts

@@ -4,8 +4,10 @@ export interface InputProps extends React.ComponentProps<"input"> {
      * 文字数カウンタを表示する。`maxLength` とセットで使い、入力欄の
      * 右下に `{現在}/{max}` を表示する。上限に達すると Text-Caution 色になる。
      * 制御（`value`）/ 非制御（`defaultValue`）どちらでも追従する。
+     * 非制御時は実際の DOM の値を数えるため、react-hook-form の `register()` の
+     * ように `ref` 経由で外部から値が入るケースでも初期表示から正しく数える。
      */
     showCount?: boolean;
 }
-declare function Input({ className, type, showCount, maxLength, value, defaultValue, onChange, ...props }: InputProps): import("react/jsx-runtime").JSX.Element;
+declare function Input({ className, type, showCount, maxLength, value, defaultValue, onChange, ref, ...props }: InputProps): import("react/jsx-runtime").JSX.Element;
 export { Input };

package/dist/types/components/foundations/textarea.d.ts

@@ -4,8 +4,10 @@ export interface TextareaProps extends React.ComponentProps<"textarea"> {
      * 文字数カウンタを表示する。`maxLength` とセットで使い、入力欄の
      * 右下に `{現在}/{max}` を表示する。上限に達すると Text-Caution 色になる。
      * 制御（`value`）/ 非制御（`defaultValue`）どちらでも追従する。
+     * 非制御時は実際の DOM の値を数えるため、react-hook-form の `register()` の
+     * ように `ref` 経由で外部から値が入るケースでも初期表示から正しく数える。
      */
     showCount?: boolean;
 }
-declare function Textarea({ className, showCount, maxLength, value, defaultValue, onChange, ...props }: TextareaProps): import("react/jsx-runtime").JSX.Element;
+declare function Textarea({ className, showCount, maxLength, value, defaultValue, onChange, ref, ...props }: TextareaProps): import("react/jsx-runtime").JSX.Element;
 export { Textarea };

package/dist/types/components/primitives/chat-composer.d.ts

@@ -0,0 +1,87 @@
+/** 添付が受理されなかったときのコールバック引数。 */
+export interface ChatComposerAttachmentError {
+    /** `max-files`: 件数上限超過 / `max-size`: サイズ上限超過 */
+    code: "max-files" | "max-size";
+    /** 受理されなかったファイル */
+    file: File;
+    /** 超過した上限値（max-files は件数、max-size は MB） */
+    limit: number;
+}
+export interface ChatComposerProps {
+    /** 入力値（制御） */
+    value: string;
+    /** 入力変更（制御） */
+    onChange: (value: string) => void;
+    /**
+     * 送信。本文と添付ファイルを受け取る。
+     * 本文と添付がどちらも空のときは呼ばれない。
+     */
+    onSubmit: (value: string, files: File[]) => void;
+    /**
+     * 送信キー。
+     * - `enter`（既定）: Enter で送信 / Shift+Enter で改行
+     * - `mod-enter`: ⌘/Ctrl+Enter で送信 / Enter は改行
+     *
+     * どちらでも IME 変換確定の Enter では送信しない。
+     */
+    submitKey?: "enter" | "mod-enter";
+    /**
+     * 添付ファイル（制御）。指定すると表示はこの値に従う。
+     * 未指定なら内部 state で保持する。
+     */
+    attachments?: File[];
+    /** 添付が変わったときのコールバック */
+    onAttachmentsChange?: (files: File[]) => void;
+    /** 受け付ける MIME/拡張子（例: "image/*,.pdf"） */
+    accept?: string;
+    /** 添付できる最大件数。超過分は受理せず onAttachmentError を呼ぶ。 */
+    maxFiles?: number;
+    /** 1ファイルあたりの上限サイズ（MB）。超過ファイルは受理せず onAttachmentError を呼ぶ。 */
+    maxSizeMb?: number;
+    /** 添付が受理されなかったときのコールバック */
+    onAttachmentError?: (error: ChatComposerAttachmentError) => void;
+    /** 無効化（入力・添付・送信すべて） */
+    disabled?: boolean;
+    /** 送信中。送信ボタンを無効化し二重送信を防ぐ。 */
+    isSubmitting?: boolean;
+    /** 入力欄のプレースホルダ */
+    placeholder?: string;
+    /** 入力欄の最大文字数。指定すると文字数カウンタを表示する。 */
+    maxLength?: number;
+    /** 入力欄の visually-hidden ラベル（スクリーンリーダー向け） */
+    label?: string;
+    /** 入力欄の初期表示行数 */
+    rows?: number;
+    /** 入力欄の id。未指定なら自動採番。 */
+    id?: string;
+    /** マウント時に入力欄へフォーカスする */
+    autoFocus?: boolean;
+    /** 追加クラス（ルート要素） */
+    className?: string;
+}
+/**
+ * ## ChatComposer / メッセージコンポーザ
+ *
+ * テキスト入力 + 添付 + 送信を1つの枠にまとめた汎用コンポーザ。
+ * チャット・問い合わせ・レビュー返信など「短文を繰り返し送る」UI に使う。
+ *
+ * 中身は DS の既存部品の組み合わせ（Textarea / FileInput / Chip / Button）で、
+ * 送信キーの挙動・添付の見せ方・送信ボタンの意匠を DS 側で標準化する。
+ *
+ * ### インポート
+ * ```tsx
+ * import { ChatComposer } from "../../components/primitives/chat-composer"
+ * ```
+ *
+ * ### 送信キー
+ * 既定は Enter 送信 / Shift+Enter 改行。長文入力が主なら `submitKey="mod-enter"`。
+ * どちらでも **IME 変換中の Enter では送信しない**（日本語入力での誤送信防止）。
+ *
+ * ### AI 向け使用ルール
+ * - チャット入力欄を Textarea + Button で手組みしない。ChatComposer を使う
+ * - 添付は `attachments` / `onAttachmentsChange` で制御し、Chip の removable で表示される
+ * - 送信中は `isSubmitting` を立てる（送信ボタンが無効化され二重送信を防げる）
+ * - `<form>` は内包しない。フォーム内に置いても入れ子にならない
+ */
+declare function ChatComposer({ value, onChange, onSubmit, submitKey, attachments, onAttachmentsChange, accept, maxFiles, maxSizeMb, onAttachmentError, disabled, isSubmitting, placeholder, maxLength, label, rows, id, autoFocus, className, }: ChatComposerProps): import("react/jsx-runtime").JSX.Element;
+export { ChatComposer };

package/dist/types/components/primitives/content-carousel.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+export type ContentCarouselItemsPerView = 1 | 2 | 3 | 4;
 export interface ContentCarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
     /**
      * スライド内容（ReactNode）のリスト。
@@ -20,6 +21,11 @@ export interface ContentCarouselProps extends Omit<React.HTMLAttributes<HTMLDivE
      * 右端に次スライドが見える。PC (@[960px]:) は常に全幅。
      */
     peek?: boolean;
+    /**
+     * PC（@[960px]:）で同時に見せるカード数。SP は従来どおり1枚表示。
+     * 求人カード等、EC 商品以外の複数カードを横スクロールさせる用途に使う。
+     */
+    itemsPerView?: ContentCarouselItemsPerView;
     /** カルーセル全体の aria-label（スクリーンリーダー向け説明） */
     ariaLabel?: string;
 }
@@ -48,5 +54,5 @@ export interface ContentCarouselProps extends Omit<React.HTMLAttributes<HTMLDivE
  * - 画像だけのバナーは `ImageCarousel` を使う（こちらはテキスト主体向け）
  * - 自動再生: `<ContentCarousel autoPlay={5000} />`
  */
-declare function ContentCarousel({ slides, showDots, showArrows, autoPlay, peek, ariaLabel, className, ...props }: ContentCarouselProps): import("react/jsx-runtime").JSX.Element;
+declare function ContentCarousel({ slides, showDots, showArrows, autoPlay, peek, itemsPerView, ariaLabel, className, ...props }: ContentCarouselProps): import("react/jsx-runtime").JSX.Element;
 export { ContentCarousel };

package/dist/types/components/primitives/date-picker.d.ts

@@ -14,12 +14,24 @@ export interface DatePickerProps {
     disabledDates?: Matcher | Matcher[];
     /** trigger を無効化する */
     disabled?: boolean;
+    /**
+     * 選択済みの値を消すクリアボタン（×）を trigger 右端に出す。既定 false（後方互換）。
+     * `value` があり `disabled` でないときだけ描画し、押すと `onChange(undefined)` を呼ぶ。
+     * 未指定だと「カレンダーを開いて選択済みの日付を再クリック」しかクリア手段が無く、
+     * 画面から発見できないため、任意項目（null 許容）では true にする。
+     */
+    clearable?: boolean;
+    /** クリアボタンの aria-label。既定「日付をクリア」 */
+    clearLabel?: string;
     /** trigger の id（FormField の htmlFor と接続） */
     id?: string;
-    /** 追加クラス（trigger に付与） */
+    /**
+     * 追加クラス。**外側のラッパー要素**に付与する（クリアボタンを trigger の
+     * 兄弟として絶対配置するため、幅・レイアウト指定はラッパーが受け取る）。
+     */
     className?: string;
 }
-declare function DatePicker({ value, onChange, placeholder, min, max, disabledDates, disabled, id, className, }: DatePickerProps): import("react/jsx-runtime").JSX.Element;
+declare function DatePicker({ value, onChange, placeholder, min, max, disabledDates, disabled, clearable, clearLabel, id, className, }: DatePickerProps): import("react/jsx-runtime").JSX.Element;
 export interface DateTimePickerProps extends DatePickerProps {
     /** 分の刻み（分 Select の選択肢間隔）。既定 5 分 */
     minuteStep?: number;
@@ -28,5 +40,5 @@ export interface DateTimePickerProps extends DatePickerProps {
     /** 分 Select の aria-label。既定「分」 */
     minuteLabel?: string;
 }
-declare function DateTimePicker({ value, onChange, minuteStep, hourLabel, minuteLabel, disabled, className, ...dateProps }: DateTimePickerProps): import("react/jsx-runtime").JSX.Element;
+declare function DateTimePicker({ value, onChange, minuteStep, hourLabel, minuteLabel, clearLabel, disabled, className, ...dateProps }: DateTimePickerProps): import("react/jsx-runtime").JSX.Element;
 export { DatePicker, DateTimePicker };

package/dist/types/components/primitives/funnel-shell.d.ts

@@ -86,6 +86,8 @@ export interface FunnelShellProps {
  *   で表す。各ステップはドット（上）＋ラベル（下）の縦積みで、コネクタ線はドット中心の
  *   高さで隣ステップ中心まで引く。ラベルは SP でも省略しない。
  * - `bottomAction` を渡すと本文の下余白はシェルが管理する（二重がけ／付け忘れの構造的防止）。
+ * - 地が Surface-Secondary なので、配下 `Card` の既定サーフェスを白にする文脈
+ *   （`--card-surface`）をシェルが宣言する。`Card` は `surface` 未指定のまま地から浮く（#150）。
  *
  * 管理画面の集中編集は `WorkspaceShell`（EC 購入導線＝本コンポーネント）。
  * 判断基準は contracts/screen-patterns.json（focused-workspace）を参照。

package/dist/types/components/primitives/image-input.d.ts

@@ -0,0 +1,119 @@
+import { type VariantProps } from "class-variance-authority";
+/** 選択されたファイルが受理されなかったときのコールバック引数。 */
+export interface ImageInputValidationError {
+    /** `accept`: 形式不一致 / `max-size`: サイズ上限超過 */
+    code: "accept" | "max-size";
+    /** 受理されなかったファイル */
+    file: File;
+    /** 表示に使う日本語メッセージ */
+    message: string;
+}
+/**
+ * accept（例: "image/png,image/jpeg" / "image/*"）に対して File の MIME を検査する。
+ * ネイティブの accept はファイル選択ダイアログの絞り込みでしかなく強制力がないため、
+ * 選択後に必ずここで検査する。accept が空なら全許可。
+ */
+export declare function isAcceptedImageType(file: File, accept: string): boolean;
+/**
+ * accept を日本語エラー文言用の形式名に整形する（例: "image/png,image/jpeg" → "PNG、JPEG"）。
+ */
+export declare function formatAcceptedFormats(accept: string): string;
+/**
+ * 上限サイズ（MB）を表示用に整形する（1MB 未満は KB 表記）。
+ */
+export declare function formatMaxSize(maxSizeMb: number): string;
+/**
+ * プレビュー枠の寸法。
+ * 任意値 px は 4px グリッド上の値（156=4×39 / 380=4×95 / 568=4×142）で、
+ * 「画像入力の枠サイズ」という固有寸法のため spacing トークンの対象外。
+ * landscape は OGP 相当の 1200:630（≒1.9:1）。
+ */
+declare const imageInputPreviewVariants: (props?: {
+    aspect?: "square" | "landscape";
+    size?: "sm" | "lg" | "md";
+} & import("class-variance-authority/types").ClassProp) => string;
+export interface ImageInputProps extends VariantProps<typeof imageInputPreviewVariants> {
+    /**
+     * 現在の値。`File`=新規に選択された画像 / `string`=保存済み画像の URL / `null`=未設定。
+     * 制御コンポーネントのため必ず渡す。
+     */
+    value: File | string | null;
+    /** 値の変更。クリア時は `null` が渡る。検証を通ったファイルだけが渡る。 */
+    onChange: (file: File | null) => void;
+    /** フォーカスが部品の外へ抜けたときに呼ぶ（React Hook Form の touched 連携用） */
+    onBlur?: () => void;
+    /** 内包する `<input type="file">` の id。Label / FormField の htmlFor と揃える。 */
+    id?: string;
+    /** input name（フォーム送信用） */
+    name?: string;
+    /** 受け付ける MIME/拡張子 */
+    accept?: string;
+    /** 1ファイルあたりの上限サイズ（MB）。超過ファイルは受理しない。 */
+    maxSizeMb?: number;
+    /** プレビューの表示方法 */
+    objectFit?: "cover" | "contain";
+    /** 無効化 */
+    disabled?: boolean;
+    /** クリアボタンを表示する。false で「画像を必ず1枚持つ」入力にできる。 */
+    clearable?: boolean;
+    /**
+     * 外部（React Hook Form 等）から与えるエラーメッセージ。
+     * 指定するとこちらが優先して表示される（内蔵検証のエラーより上位）。
+     */
+    error?: string;
+    /**
+     * 内蔵検証で弾かれたときのコールバック。
+     * 既定ではインラインの FieldError に日本語で表示されるため、
+     * Dialog / トーストで通知したい場合のみ使う。
+     */
+    onValidationError?: (error: ImageInputValidationError) => void;
+    /** プレビュー画像の alt */
+    alt?: string;
+    /** 未選択時にプレビュー枠へ表示する文言 */
+    placeholder?: string;
+    /** 「画像を選択」ボタンの文言 */
+    buttonLabel?: string;
+    /** 説明文などの id（内包 input の aria-describedby に連結する） */
+    "aria-describedby"?: string;
+    /** 追加クラス（ルート要素） */
+    className?: string;
+}
+/**
+ * ## ImageInput / 画像入力
+ *
+ * **1枚の画像**を選ぶフォーム部品。プレビュー + ファイル選択 + 形式/サイズ検証 + クリアを内包する。
+ * 値は `File | string | null`（`string` は保存済み画像の URL）で、そのままフォームの値として扱える。
+ *
+ * ### FileInput / ImageUploader との使い分け
+ * | 用途 | 使う部品 |
+ * |------|---------|
+ * | 画像 1 枚の入力（プレビュー付き・値をフォームに持つ） | **ImageInput**（primitives） |
+ * | 画像以外も含む汎用の添付（PDF / CSV 等・1行表示） | `FileInput`（foundations） |
+ * | 複数枚の画像を並べて管理するグリッド（追加・削除・並び順） | `ImageUploader`（primitives） |
+ *
+ * ### インポート
+ * ```tsx
+ * import { ImageInput } from "../../components/primitives/image-input"
+ * ```
+ *
+ * ### 表示サイズ
+ * `aspect`（square / landscape）× `size`（sm / md / lg）の組み合わせで指定する。
+ * 例: 正方形サムネイル=`aspect="square" size="sm"` / OGP 相当のバナー=`aspect="landscape" size="lg"`。
+ *
+ * ### エラー表示
+ * 形式・サイズの検証エラーは**インラインの `FieldError`**（`role="alert"`）に日本語で表示し、
+ * 内包 input に `aria-invalid` / `aria-describedby` を付けて紐付ける。
+ * モーダルで通知したい場合だけ `onValidationError` を使って consumer 側で出す。
+ *
+ * ### 非同期検証
+ * 画像の寸法チェック等の非同期検証は本部品には持たせていない。
+ * `onChange` を受けた consumer 側で検証し、結果を `error` prop で戻す。
+ *
+ * ### AI 向け使用ルール
+ * - `<input type="file">` + `<img>` で画像入力を手組みしない
+ * - `value` / `onChange` の制御コンポーネント。保存済み画像は URL 文字列をそのまま渡す
+ * - ラベル・必須バッジは `FormField` でラップし、`id` を `htmlFor` と揃える
+ * - プレビューの objectURL は内部で解放される。consumer 側で createObjectURL しない
+ */
+declare function ImageInput({ value, onChange, onBlur, id, name, accept, maxSizeMb, aspect, size, objectFit, disabled, clearable, error, onValidationError, alt, placeholder, buttonLabel, className, "aria-describedby": ariaDescribedby, }: ImageInputProps): import("react/jsx-runtime").JSX.Element;
+export { ImageInput, imageInputPreviewVariants };

package/dist/types/components/primitives/section-header.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 export type SectionHeaderSize = "3xl" | "2xl" | "xl" | "lg" | "md" | "sm";
+export type SectionHeaderDesktopSize = "5xl" | "4xl";
 export interface SectionHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
     /** セクションタイトル */
     title: string;
@@ -21,8 +22,13 @@ export interface SectionHeaderProps extends React.HTMLAttributes<HTMLDivElement>
     prevDisabled?: boolean;
     /** カルーセル用: 次へボタン無効化 */
     nextDisabled?: boolean;
-    /** タイトルのサイズ（Figma 準拠: 3xl=28px / 2xl=24px / xl=21px / lg=18px / md=16px / sm=14px） */
+    /** SPを含む基本サイズ（3xl=通常ページの主見出し。2xl以下=セクション見出し） */
     size?: SectionHeaderSize;
+    /**
+     * LP・マーケティング系ヒーローのPCサイズ。
+     * `size="3xl" desktopSize="5xl"` のように指定し、通常ページでは使わない。
+     */
+    desktopSize?: SectionHeaderDesktopSize;
     /** 見出しのHTML要素を上書き（デフォルトは size に応じて h1〜h6 を自動選択） */
     as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
     /**
@@ -48,6 +54,7 @@ export interface SectionHeaderProps extends React.HTMLAttributes<HTMLDivElement>
  * ### AI 向け使用ルール
  *
  * - ページの主タイトル: `size="3xl"` or `size="2xl"`
+ * - LP・マーケティング系ヒーロー: `size="3xl" desktopSize="4xl"` または `desktopSize="5xl"`
  * - セクション見出し（ランキング等）: `size="xl"` or `size="lg"`（デフォルト）
  * - 小見出し・グループラベル: `size="md"` or `size="sm"`
  * - `as` で見出しレベルを上書き可能（同一ページに h1 が複数必要な場合など）
@@ -55,5 +62,5 @@ export interface SectionHeaderProps extends React.HTMLAttributes<HTMLDivElement>
  * - `action` に任意の ReactNode（Button 等）を渡して右側にアクションを配置可能
  * - `align="center"` でランディング/ガイド系の中央寄せ大見出しに切替（`eyebrow` に Badge 等を載せられる）
  */
-declare function SectionHeader({ className, title, subtitle, moreHref, moreLabel, onMoreClick, action, onPrev, onNext, prevDisabled, nextDisabled, size, as, align, eyebrow, ...props }: SectionHeaderProps): import("react/jsx-runtime").JSX.Element;
+declare function SectionHeader({ className, title, subtitle, moreHref, moreLabel, onMoreClick, action, onPrev, onNext, prevDisabled, nextDisabled, size, desktopSize, as, align, eyebrow, ...props }: SectionHeaderProps): import("react/jsx-runtime").JSX.Element;
 export { SectionHeader };

package/dist/types/components/primitives/section.d.ts

@@ -1,5 +1,12 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
+export type SectionScrim = "none" | "dark" | "light" | "bottom-dark";
+export interface SectionProps extends Omit<React.ComponentProps<"section">, "background">, VariantProps<typeof sectionVariants> {
+    /** 背景画像 URL。左右余白は引き続き内側の Container が所有する */
+    backgroundImage?: string;
+    /** 背景画像上の文字を読みやすくする DS 管理のオーバーレイ */
+    scrim?: SectionScrim;
+}
 /**
  * Section — 全幅の縦リズム＋（任意で）背景色付きの帯。
  *
@@ -8,6 +15,8 @@ import { type VariantProps } from "class-variance-authority";
  *   背景色は Section（全幅）が持ち、中央寄せは Container が持つ ── この分担により
  *   「背景帯は画面端まで、コンテンツは中央寄せ」が二重がけなしで成立する。
  * - 縦余白は SP/PC ペアで `--Space-Section-*` トークンを消費する（rem 直書きの撲滅）。
+ * - **色地の Section（`subtle` / `accent-subtle`）は配下 Card のサーフェス文脈を宣言する**
+ *   （`--card-surface: var(--Surface-Primary)`）。詳細は下記。
  *
  * 推奨パターン:
  * ```tsx
@@ -17,10 +26,34 @@ import { type VariantProps } from "class-variance-authority";
  *   </Container>
  * </Section>
  * ```
+ *
+ * ## 配下 Card へのサーフェス伝播（#150）
+ *
+ * `background="subtle"`（Surface-Tertiary）/ `"accent-subtle"` は色地なので、既定の
+ * `bg-card`（Surface-Secondary）のままでは Card が地に沈む。Section が
+ * `--card-surface: var(--Surface-Primary)` を配下に流すことで、**Section 配下の Card は
+ * `surface` 未指定でも白**になる（`Card surface="primary"` の明示指定は従来通り優先）。
+ *
+ * 「グレー地の上の Card は白」を**構造で**保証するのが狙いで、あとからカードを足しても
+ * prop の付け忘れが起きない。伝播は CSS カスタムプロパティのカスケードのみで、React context は
+ * 使わない（Server Component のまま使える／DS 外の要素は影響を受けない）。
+ *
+ * `background="none"` は文脈をリセットしない。色地 Section の内側に入れ子にした
+ * `background="none"` の Section は背景が透過して外側の色地が見えるため、
+ * 配下の Card も外側の文脈（白）を引き継ぐのが正しい。
+ *
+ * dark では伝播値を切り替えない（`Surface-Secondary` のまま）。dark の Surface-Secondary は
+ * 「地の上に重ねる半透明白」なので色地の上でも一段明るく浮き、そもそも沈まない。
+ * ここで `Surface-Primary`（ほぼ不透明の黒）を強制すると地より暗い「穴」になり
+ * elevation が反転する。※ `Card surface="primary"` の**明示指定**は light/dark とも
+ * Surface-Primary で固定（明示は明示のまま）。
  */
 declare const sectionVariants: (props?: {
     spacing?: "sm" | "lg" | "xl" | "md";
     background?: "none" | "accent-subtle" | "subtle";
 } & import("class-variance-authority/types").ClassProp) => string;
-declare function Section({ className, spacing, background, ...props }: React.ComponentProps<"section"> & VariantProps<typeof sectionVariants>): import("react/jsx-runtime").JSX.Element;
-export { Section, sectionVariants };
+declare const sectionScrimVariants: (props?: {
+    scrim?: "none" | "light" | "dark" | "bottom-dark";
+} & import("class-variance-authority/types").ClassProp) => string;
+declare function Section({ className, spacing, background, backgroundImage, scrim, style, ...props }: SectionProps): import("react/jsx-runtime").JSX.Element;
+export { Section, sectionVariants, sectionScrimVariants };

package/dist/types/components/primitives/timeline.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+export interface TimelineItem {
+    /** 省略時は1始まりの連番を表示。IconBadge 等の ReactNode も渡せる */
+    marker?: React.ReactNode;
+    /** 各項目の見出し */
+    title: React.ReactNode;
+    /** Card・本文・メタ情報等の任意コンテンツ */
+    children?: React.ReactNode;
+}
+export interface TimelineProps extends Omit<React.ComponentProps<"ol">, "children"> {
+    items: TimelineItem[];
+    /** タイムライン全体の日本語ラベル */
+    ariaLabel?: string;
+}
+/**
+ * 本文付きの縦タイムライン。
+ *
+ * 応募フロー・オンボーディング手順・注文／配送履歴のように、各段階へ本文を
+ * ぶら下げる用途で使う。現在位置を示す横型の `ProgressSteps` とは役割が異なる。
+ * コネクター線は DS が所有するため consumer 側で `::before` を手組みしない。
+ */
+declare function Timeline({ items, ariaLabel, className, ...props }: TimelineProps): import("react/jsx-runtime").JSX.Element;
+export { Timeline };

package/dist/types/components/primitives/workspace-shell.d.ts

@@ -62,6 +62,8 @@ export interface WorkspaceShellProps {
  *   右上=`primaryAction`（ワークスペース全体の上位アクションがある場合のみ）。
  * - `sectionNav` は編集内ナビのみ。グロナビは置かない。
  * - `sectionNav` は Surface-Secondary から浮いた独立パネルとして、シェル側で角丸パネルにラップされる。
+ * - 地が Surface-Secondary なので、配下 `Card` の既定サーフェスを白にする文脈
+ *   （`--card-surface`）をシェルが宣言する。`Card` は `surface` 未指定のまま地から浮く（#150）。
  * - 標準的な編集は `AdminShell`（Standard Page（Edit）／旧 Form Page）。複雑・集中編集・没入執筆のみ本コンポーネント。
  *
  * 判断基準は contracts/screen-patterns.json / guidelines/foundations/screen-patterns.md を参照。