@cakejp/design-system 0.11.0 → 0.13.0

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

@@ -0,0 +1,58 @@
+import * as React from "react";
+export type ContentCarouselItemsPerView = 1 | 2 | 3 | 4;
+export interface ContentCarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * スライド内容（ReactNode）のリスト。
+     * 画像URLではなく任意の JSX を受けるため、eyebrow / タイトル / 本文 / 価格 /
+     * バッジで構成したテキスト主体のヒーローバナー等を組める。
+     * 各スライドは DS コンポーネント（Badge, Button 等）と typo-* / セマンティック
+     * トークンで組むこと（スクラッチ禁止ルール準拠）。
+     */
+    slides: React.ReactNode[];
+    /** ドットインジケーター表示 */
+    showDots?: boolean;
+    /** 矢印ナビゲーション表示 */
+    showArrows?: boolean;
+    /** 自動再生（ミリ秒、0で無効） */
+    autoPlay?: number;
+    /**
+     * SP: 隣スライドをのぞかせる（peek）表示。
+     * true にすると各スライドが `calc(100% - 48px)` 幅になり、
+     * 右端に次スライドが見える。PC (@[960px]:) は常に全幅。
+     */
+    peek?: boolean;
+    /**
+     * PC（@[960px]:）で同時に見せるカード数。SP は従来どおり1枚表示。
+     * 求人カード等、EC 商品以外の複数カードを横スクロールさせる用途に使う。
+     */
+    itemsPerView?: ContentCarouselItemsPerView;
+    /** カルーセル全体の aria-label（スクリーンリーダー向け説明） */
+    ariaLabel?: string;
+}
+/**
+ * コンテンツカルーセル — ReactNode スライド対応
+ *
+ * `ImageCarousel` と同じ CSS scroll-snap ベースの実装だが、`images: string[]` ではなく
+ * `slides: ReactNode[]` を受け取る。テキスト主体のプロモスライド（eyebrow / タイトル /
+ * 本文 / 価格 / バッジ、画像は任意）を DS が autoplay / 矢印 / ドット / スワイプ付きで
+ * 提供し、consumer 側の手組みカルーセル（→意匠ドリフト）を不要にする。
+ *
+ * 矢印・ドットの意匠は `ImageCarousel` と同一（同じ markup を流用）。
+ *
+ * - SP（狭幅）: スワイプ操作 + ドットインジケーター、矢印は非表示
+ * - PC（@md: 以上）: 左右矢印ボタン（ホバーで出現）、ドット非表示
+ *
+ * ### インポート
+ * ```tsx
+ * import { ContentCarousel } from '../../components/primitives/content-carousel'
+ * ```
+ *
+ * ### AI 向け使用ルール
+ *
+ * - スライド内容は DS コンポーネント（Badge, Button, PriceDisplay 等）と
+ *   typo-* / セマンティックトークンで組む（生の色・影・角丸は禁止）
+ * - 画像だけのバナーは `ImageCarousel` を使う（こちらはテキスト主体向け）
+ * - 自動再生: `<ContentCarousel autoPlay={5000} />`
+ */
+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

@@ -0,0 +1,44 @@
+import type { Matcher } from "react-day-picker";
+export interface DatePickerProps {
+    /** 選択中の日付 */
+    value?: Date;
+    /** 日付が変わったときに呼ばれる。クリアされると `undefined` */
+    onChange?: (date?: Date) => void;
+    /** 未選択時の trigger 表示 */
+    placeholder?: string;
+    /** 選択可能な最小日（これより前を無効化） */
+    min?: Date;
+    /** 選択可能な最大日（これより後を無効化） */
+    max?: Date;
+    /** 個別に無効化する日（Calendar の disabled マッチャーをそのまま透過） */
+    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 の
+     * 兄弟として絶対配置するため、幅・レイアウト指定はラッパーが受け取る）。
+     */
+    className?: string;
+}
+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;
+    /** 時 Select の aria-label。既定「時」 */
+    hourLabel?: string;
+    /** 分 Select の aria-label。既定「分」 */
+    minuteLabel?: string;
+}
+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/error-state.d.ts

@@ -1,41 +1,68 @@
 import * as React from "react";
+export type NotFoundIllustrationProps = React.SVGProps<SVGSVGElement>;
+/**
+ * NotFound（404）向けの抽象イラスト（ケーキモチーフ / スライスが欠けた図）。
+ *
+ * 色は CSS 変数と currentColor のみで構成（HEX 直書きなし）。輪郭は
+ * currentColor を継承するため、親の text-color で線色を調整できる。
+ * 既定は装飾（`aria-hidden`）。単体で意味を持たせる場合は `aria-label` を渡す。
+ *
+ * ```tsx
+ * <NotFoundIllustration className="w-40 text-[var(--Border-Medium-Emphasis)]" />
+ * ```
+ */
+declare function NotFoundIllustration({ className, "aria-label": ariaLabel, ...props }: NotFoundIllustrationProps): import("react/jsx-runtime").JSX.Element;
+/** ErrorState の種別。既定は汎用エラー、notFound は 404 向けの定番構成 */
+export type ErrorStateKind = "error" | "notFound";
 export interface ErrorStateProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** エラーアイコン */
+    /**
+     * 状態の種別。
+     * - `"error"`（既定）: 汎用エラー。`icon` を Object-Caution 色で表示（現行不変）
+     * - `"notFound"`: 404 向け。既定でケーキイラスト + 見つからない旨の文言
+     */
+    kind?: ErrorStateKind;
+    /** アイコン / イラスト。省略時、notFound は既定イラスト、error は非表示 */
     icon?: React.ReactNode;
-    /** エラータイトル */
-    title: string;
-    /** エラーの説明テキスト */
+    /** タイトル。省略時は kind に応じた既定文言 */
+    title?: string;
+    /** 説明テキスト。省略時、notFound は既定文言、error は非表示 */
     description?: React.ReactNode;
     /** 再試行ボタンのクリックハンドラ。指定すると再試行ボタンを表示 */
     onRetry?: () => void;
     /** 再試行ボタンのラベル */
     retryLabel?: string;
-    /** 追加アクション（例: 「ホームに戻る」ボタン） */
+    /** 追加アクション（例: 「トップへ戻る」ボタン） */
     action?: React.ReactNode;
 }
 /**
- * エラー状態コンポーネント
+ * エラー状態 / 404 状態コンポーネント
  *
- * APIエラー、ネットワークエラー、タイムアウト等のエラー状態を表示するUI。
- * EmptyState と同様のレイアウトだが、再試行アクションに特化。
+ * APIエラー・ネットワークエラー・タイムアウト等（`kind="error"`）と、
+ * 404 Not Found（`kind="notFound"`）の定番構成を1つのコンポーネントで扱う。
+ * EmptyState と同様の中央寄せレイアウト。
  *
  * ### AI 向け使用ルール
  *
- * - `icon` にエラー種別に合ったアイコン（size-16）を渡す
- * - `title` でエラー内容を簡潔に伝える
- * - `description` で対処方法を案内
- * - `onRetry` を渡すと再試行ボタンが表示される
- * - `action` に追加のナビゲーションボタンを渡せる
- * - ページコンテンツの中央に配置
+ * - システムエラーは `kind="error"`（既定）。`icon`（size-16）+ `onRetry` を渡す
+ * - 404 ページは `kind="notFound"`。イラスト・見出し・説明は既定で入るため
+ *   基本は `action`（「トップへ戻る」等の導線）だけ渡せばよい
+ * - データが無いだけ（カート空・検索0件）は EmptyState を使う
  *
  * ```tsx
+ * // 汎用エラー
  * <ErrorState
  *   icon={<WifiOff className="size-16" />}
  *   title="接続エラー"
  *   description="ネットワークに接続できませんでした。"
  *   onRetry={() => location.reload()}
  * />
+ *
+ * // 404
+ * <ErrorState
+ *   kind="notFound"
+ *   action={<Button size="lg">トップへ戻る</Button>}
+ * />
  * ```
  */
-declare function ErrorState({ className, icon, title, description, onRetry, retryLabel, action, ...props }: ErrorStateProps): import("react/jsx-runtime").JSX.Element;
-export { ErrorState };
+declare function ErrorState({ className, kind, icon, title, description, onRetry, retryLabel, action, ...props }: ErrorStateProps): import("react/jsx-runtime").JSX.Element;
+export { ErrorState, NotFoundIllustration };

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

@@ -44,6 +44,15 @@ export interface FunnelShellProps {
     bottomAction?: React.ReactNode;
     /** ルート要素の追加クラス */
     className?: string;
+    /**
+     * `<main>` の id（既定 "main-content"）。内蔵の SkipLink の飛び先（`#${mainId}`）と対になる。
+     */
+    mainId?: string;
+    /**
+     * DOM 先頭に SkipLink（キーボードで本文へ飛ぶ a11y リンク）を標準内蔵する。
+     * `sr-only` なので視覚には影響しない。`false` で無効化。
+     */
+    skipLink?: false;
 }
 /**
  * FunnelShell — EC 購入導線等のファネル用集中モード（Full Page）のシェル。
@@ -77,9 +86,11 @@ export interface FunnelShellProps {
  *   で表す。各ステップはドット（上）＋ラベル（下）の縦積みで、コネクタ線はドット中心の
  *   高さで隣ステップ中心まで引く。ラベルは SP でも省略しない。
  * - `bottomAction` を渡すと本文の下余白はシェルが管理する（二重がけ／付け忘れの構造的防止）。
+ * - 地が Surface-Secondary なので、配下 `Card` の既定サーフェスを白にする文脈
+ *   （`--card-surface`）をシェルが宣言する。`Card` は `surface` 未指定のまま地から浮く（#150）。
  *
  * 管理画面の集中編集は `WorkspaceShell`（EC 購入導線＝本コンポーネント）。
  * 判断基準は contracts/screen-patterns.json（focused-workspace）を参照。
  */
-declare function FunnelShell({ logo, title, onBack, backLabel, steps, activeStep, children, bottomAction, className, }: FunnelShellProps): import("react/jsx-runtime").JSX.Element;
+declare function FunnelShell({ logo, title, onBack, backLabel, steps, activeStep, children, bottomAction, className, mainId, skipLink, }: FunnelShellProps): import("react/jsx-runtime").JSX.Element;
 export { FunnelShell };

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

@@ -6,6 +6,12 @@ export interface HeaderAction {
     label: string;
     /** クリックハンドラ */
     onClick?: () => void;
+    /**
+     * リンク先。指定すると `<a>`（Button asChild）で描画し、
+     * 中クリック/Cmd+クリックでの新規タブ・リンクコピー・hoverプレビューが効くようになる。
+     * onClick と併用可（両方付与される）
+     */
+    href?: string;
     /** バッジ数（通知やカート件数） */
     badge?: React.ReactNode;
 }
@@ -46,6 +52,14 @@ export interface HeaderProps extends React.HTMLAttributes<HTMLElement> {
      * SP では非表示。本番の "ケーキ / スイーツ / ランキング…" メニューに対応。
      */
     navItems?: HeaderNavItem[];
+    /**
+     * PC（@[768px]+）のロゴ行で navItems と actions の間にインライン配置する検索スロット
+     * （variant="logo" のみ）。`SearchBar` 等を渡す。`flex-1 max-w-[400px]` で伸縮し、
+     * 既存のロゴ・ナビ・アクションを潰さない。SP 行には出さない
+     * （SP の常設検索は従来どおり `bottomSlot` で運用する）。
+     * navItems が無く searchSlot だけを渡した場合も PC 行を描画する。
+     */
+    searchSlot?: React.ReactNode;
     /** 右側に配置するカスタム要素（variant="back"で使用） */
     rightSlot?: React.ReactNode;
     /** 検索バーなど中央に配置するカスタム要素（variant="back-search"で使用） */
@@ -65,5 +79,5 @@ export interface HeaderProps extends React.HTMLAttributes<HTMLElement> {
  * アプリ全体で使われるヘッダーの3パターンを1コンポーネントで提供。
  * ロゴ＋アクション、戻るボタン＋タイトル、戻るボタン＋検索の3バリエーション。
  */
-declare function Header({ className, variant, logo, title, onBack, backLabel, actions, navItems, rightSlot, centerSlot, bottomSlot, disableSticky, ...props }: HeaderProps): import("react/jsx-runtime").JSX.Element;
+declare function Header({ className, variant, logo, title, onBack, backLabel, actions, navItems, searchSlot, rightSlot, centerSlot, bottomSlot, disableSticky, ...props }: HeaderProps): import("react/jsx-runtime").JSX.Element;
 export { Header };

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-nav.d.ts

@@ -14,6 +14,14 @@ export interface SectionNavProps extends React.HTMLAttributes<HTMLElement> {
     items: SectionNavItem[];
     /** アクティブなセクションの key（利用側が scrollspy 等で制御。本体では監視しない） */
     activeKey?: string;
+    /**
+     * レイアウト方向（既定 "vertical"）。
+     * - "vertical": 縦積みの目次（WorkspaceShell の左レール等）。従来の挙動。
+     * - "horizontal": 横並びの Tabs アンダーバー式（ガイド・FAQ 等の長い静的ページの
+     *   ページ内ジャンプナビ）。横スクロール対応（overflow-x-auto）。sticky は内蔵しない
+     *   （sticky/top オフセットは利用側が className で付与する）。
+     */
+    orientation?: "vertical" | "horizontal";
     /** aria-label */
     ariaLabel?: string;
     /** 項目クリック時のコールバック（任意） */
@@ -31,13 +39,14 @@ export interface SectionNavProps extends React.HTMLAttributes<HTMLElement> {
  * - 固有幅・背景・境界を持たない（`w-full`）。パネル化・幅決定はシェル／利用側の責務。
  *   （SideNav の `w-64` 固定が WorkspaceShell で幅ミスマッチを起こした反省）
  * - IntersectionObserver は内包しない。`activeKey` を利用側が渡す。
+ * - sticky は内蔵しない。sticky／top オフセットは利用側が className で付与する。
  *
  * ### インポート
  * ```tsx
  * import { SectionNav } from '../../components/primitives/section-nav'
  * ```
  *
- * ### 使い方
+ * ### 使い方（vertical＝既定）
  * ```tsx
  * <SectionNav
  *   activeKey="basic"
@@ -48,13 +57,30 @@ export interface SectionNavProps extends React.HTMLAttributes<HTMLElement> {
  * />
  * ```
  *
+ * ### 使い方（horizontal＝ページ内ジャンプの sticky アンダーバー）
+ * ガイド・FAQ のような長い静的ページ向け。sticky は利用側で付与する。
+ * ジャンプ先セクション側には `scroll-mt-*`（sticky ナビ高さ + α）を付けて、
+ * 見出しがナビの裏に隠れないようにする。
+ * ```tsx
+ * // ナビ: ヘッダー（h-14）直下に貼り付ける
+ * <SectionNav
+ *   orientation="horizontal"
+ *   activeKey={active}
+ *   className="sticky top-14 z-30 border-b border-[var(--Border-Low-Emphasis)] bg-[var(--Surface-Primary)]"
+ *   items={items}
+ * />
+ * // ターゲット: ナビ高さぶん上に余白を確保（scroll-mt-28 ≒ header 56px + nav 48px）
+ * <section id="basic" className="scroll-mt-28">…</section>
+ * ```
+ *
  * ### Props
  * | Prop | 型 | デフォルト | 説明 |
  * |------|-----|-----------|------|
  * | items | SectionNavItem[] | — | 目次項目（アンカー、必須） |
  * | activeKey | string | — | アクティブなセクションの key |
+ * | orientation | "vertical"\|"horizontal" | "vertical" | 縦積み目次 / 横アンダーバー |
  * | ariaLabel | string | "ページ内セクション" | aria-label |
  * | onItemClick | (key: string) => void | — | 項目クリック時のコールバック |
  */
-declare function SectionNav({ items, activeKey, ariaLabel, onItemClick, className, ...props }: SectionNavProps): import("react/jsx-runtime").JSX.Element;
+declare function SectionNav({ items, activeKey, orientation, ariaLabel, onItemClick, className, ...props }: SectionNavProps): import("react/jsx-runtime").JSX.Element;
 export { SectionNav };

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/share-buttons.d.ts

@@ -1,11 +1,17 @@
 import * as React from "react";
-export interface ShareButtonsProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface ShareButtonsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onCopy"> {
     /** シェアURL */
     url?: string;
     /** シェアテキスト */
     text?: string;
     /** コピーボタンのラベル */
     copyLabel?: string;
+    /** コピー成功時に一時表示するラベル（約2秒） */
+    copiedLabel?: string;
+    /** コピー失敗時に一時表示するラベル（約2秒） */
+    copyErrorLabel?: string;
+    /** コピー完了時のコールバック（成功/失敗） */
+    onCopy?: (result: "success" | "error") => void;
 }
 /**
  * シェアボタンコンポーネント
@@ -19,5 +25,5 @@ export interface ShareButtonsProps extends React.HTMLAttributes<HTMLDivElement>
  * - `url` と `text` でシェア内容を指定
  * - ボタンは横並び、等幅表示
  */
-declare function ShareButtons({ className, url, text, copyLabel, ...props }: ShareButtonsProps): import("react/jsx-runtime").JSX.Element;
+declare function ShareButtons({ className, url, text, copyLabel, copiedLabel, copyErrorLabel, onCopy, ...props }: ShareButtonsProps): import("react/jsx-runtime").JSX.Element;
 export { ShareButtons };

package/dist/types/components/primitives/standard-page-shell.d.ts

@@ -21,6 +21,16 @@ export interface StandardPageShellProps {
     children: React.ReactNode;
     /** ルート要素の追加クラス。 */
     className?: string;
+    /**
+     * `<main>` の id（既定 "main-content"）。内蔵の SkipLink の飛び先（`#${mainId}`）と対になる。
+     * スキップ先アンカーを別 id にしたい場合に変更する。
+     */
+    mainId?: string;
+    /**
+     * DOM 先頭に SkipLink（キーボードで本文へ飛ぶ a11y リンク）を標準内蔵する。
+     * `sr-only` なので視覚には影響しない。`false` で無効化。
+     */
+    skipLink?: false;
 }
 /**
  * StandardPageShell — 消費者向け標準ページ（standard-page-view / standard-page-edit）の骨格。
@@ -47,5 +57,5 @@ export interface StandardPageShellProps {
  *
  * 判断基準は contracts/composition.json（pageSkeletons）/ contracts/screen-patterns.json を参照。
  */
-declare function StandardPageShell({ header, bottomTab, footer, children, className, }: StandardPageShellProps): import("react/jsx-runtime").JSX.Element;
+declare function StandardPageShell({ header, bottomTab, footer, children, className, mainId, skipLink, }: StandardPageShellProps): import("react/jsx-runtime").JSX.Element;
 export { StandardPageShell };

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

@@ -32,6 +32,24 @@ export interface WorkspaceShellProps {
     children: React.ReactNode;
     /** ルート要素の追加クラス */
     className?: string;
+    /**
+     * 編集本体 `<main>` の id（既定 "main-content"）。内蔵の SkipLink の飛び先（`#${mainId}`）と対になる。
+     */
+    mainId?: string;
+    /**
+     * DOM 先頭に SkipLink（キーボードで本文へ飛ぶ a11y リンク）を標準内蔵する。
+     * `sr-only` なので視覚には影響しない。`false` で無効化。
+     */
+    skipLink?: false;
+    /**
+     * 編集ヘッダーのレイアウト（既定 "start"、現行と同じ挙動）。
+     * "center" にすると左=戻る導線／中央=タイトル／右=primaryAction の
+     * 3 カラム grid（`grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)]`）に固定し、
+     * primaryAction の有無・幅に関わらずタイトルを真の中央に揃える。
+     * consumer が `[&>[data-slot=header]]:!grid ...` のようなセレクタ上書きで
+     * 実現していた構成を公開 API として公式化したもの（#112）。
+     */
+    headerLayout?: "start" | "center";
 }
 /**
  * WorkspaceShell — Focused Workspace（全画面集中編集）のシェル。
@@ -44,9 +62,11 @@ 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 を参照。
  */
-declare function WorkspaceShell({ title, onBack, backLabel, primaryAction, sectionNav, asidePanel, children, className, }: WorkspaceShellProps): import("react/jsx-runtime").JSX.Element;
+declare function WorkspaceShell({ title, onBack, backLabel, primaryAction, sectionNav, asidePanel, children, className, mainId, skipLink, headerLayout, }: WorkspaceShellProps): import("react/jsx-runtime").JSX.Element;
 export { WorkspaceShell };