@cakejp/design-system 0.20.0 → 0.21.0

package/dist/types/components/primitives/notification-list.d.ts

@@ -14,6 +14,7 @@
  * | notifications | NotificationItem[] | — | 通知アイテム |
  * | variant | "vertical"\|"horizontal" | "vertical" | レイアウト |
  * | emptyMessage | string | — | 空の場合のメッセージ |
+ * | linkComponent | LinkComponent | "a" | リンクの描画に使うコンポーネント（next/link 等） |
  *
  * ### AI 向け使用ルール
  * - `vertical`: フロントの通知モーダル等（未読ドット + メッセージ上 + 日付下）
@@ -21,6 +22,7 @@
  * - 空の場合はベルアイコン + メッセージ表示
  */
 import * as React from "react";
+import type { LinkComponent } from "../../lib/link-component";
 export interface NotificationItem {
     /** 通知ID */
     id: string;
@@ -40,6 +42,13 @@ export interface NotificationListProps extends React.HTMLAttributes<HTMLDivEleme
     variant?: "vertical" | "horizontal";
     /** 空の場合のメッセージ */
     emptyMessage?: string;
+    /**
+     * リンクの描画に使うコンポーネント（既定 `a`）。`href` を持つ通知だけが対象で、
+     * `href` の無い通知は従来どおり `<div>`。
+     * `next/link` 等を渡すとクライアント遷移になる（#236）。
+     * この部品は Server Component のまま使える。
+     */
+    linkComponent?: LinkComponent;
 }
-declare function NotificationList({ notifications, variant, emptyMessage, className, ...props }: NotificationListProps): import("react/jsx-runtime").JSX.Element;
+declare function NotificationList({ notifications, variant, emptyMessage, linkComponent, className, ...props }: NotificationListProps): import("react/jsx-runtime").JSX.Element;
 export { NotificationList };

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

@@ -14,7 +14,10 @@ export interface NumberInputProps extends Omit<React.HTMLAttributes<HTMLDivEleme
     onChange?: (value: number) => void;
     /** 無効状態 */
     disabled?: boolean;
-    /** エラー状態 */
+    /**
+     * エラー状態。見た目の赤枠に加えて、入力欄に aria-invalid を付ける。
+     * FormField 配下では FormField の error があると自動で true（明示指定が優先）
+     */
     error?: boolean;
     /** サイズ（md = Pattern 2 サークル / sm = Pattern 1 ピル） */
     size?: "sm" | "md";
@@ -28,11 +31,13 @@ export interface NumberInputProps extends Omit<React.HTMLAttributes<HTMLDivEleme
     formatOptions?: Intl.NumberFormatOptions;
     /** formatOptions のロケール */
     locale?: string;
-    /** 入力欄の id。FormField / FieldLabel の htmlFor と揃える */
+    /** 入力欄の id。FormField 配下では未指定でも FormField の htmlFor と同じ id になる */
     inputId?: string;
     /**
      * 入力欄・増減ボタンの読み上げラベル。既定はカート数量向けの「数量」。
-     * 価格・在庫など数量以外に使うときは必ず指定する（例: "販売価格"）
+     * 価格・在庫など数量以外に使うときは必ず指定する（例: "販売価格"）。
+     * FormField 配下で未指定のときは FormField のラベルが名前になる
+     * （入力欄・グループ = ラベル、増減ボタン = 「ラベル 減らす / 増やす」）
      */
     label?: string;
 }
@@ -54,7 +59,15 @@ export interface NumberInputProps extends Omit<React.HTMLAttributes<HTMLDivEleme
  *
  * ### ステート
  * - `disabled`: 全要素のテキスト/アイコンが `Text/Disable` (#B7B5B4)
- * - `error`: コンパクト型は赤枠（2px）、サークル型は数値コンテナが赤枠
+ * - `error`: コンパクト型は赤枠（2px）、サークル型は数値コンテナが赤枠。入力欄に `aria-invalid` が付く
+ *
+ * ### FormField との組み合わせ
+ * FormField の children に置くと、入力欄が id（label の htmlFor と一致）・aria-describedby
+ * （説明・エラー文）・エラー状態（FormField の error）を受け取る。`label` を指定しなければ
+ * 名前も FormField のラベルになる。FormField の外の DOM は変わらない。
+ * - 上限・下限: 対応するボタンは `aria-disabled`（native の `disabled` にしない）。
+ *   native で無効化すると、押した直後にボタンがフォーカスを失って body に落ちるため。
+ *   部品全体の `disabled` は従来どおり native の `disabled`（Tab 順から外す）
  * - `showTrash`: 値が min のとき − がゴミ箱アイコンに変化
  *
  * ### AI 向け使用ルール
@@ -71,7 +84,7 @@ export interface NumberInputProps extends Omit<React.HTMLAttributes<HTMLDivEleme
  *   同じものを探した人が見つけられず別実装が生まれた。機能名に改名し、
  *   旧名は deprecated alias として残している。
  */
-declare function NumberInput({ className, value, defaultValue, min, max, step, onChange, disabled, error, size, editable, showTrash, onDelete, formatOptions, locale, inputId, label, ...props }: NumberInputProps): import("react/jsx-runtime").JSX.Element;
+declare function NumberInput({ className, value, defaultValue, min, max, step, onChange, disabled, error, size, editable, showTrash, onDelete, formatOptions, locale, inputId, label: labelProp, ...props }: NumberInputProps): import("react/jsx-runtime").JSX.Element;
 export { NumberInput };
 /**
  * @deprecated 用途名（カート数量）ではなく機能名の `NumberInput` を使ってください。

package/dist/types/components/primitives/scroll-row.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+export interface ScrollRowProps extends React.ComponentProps<"div"> {
+    /**
+     * `Container` の gutter 分だけ左右へはみ出し、Container の外縁（SP では画面端）までスクロールさせる（既定 true）。
+     * 端の余白（padding / scroll-padding）は gutter と同じなので、1 枚目の左端は見出しとそろう。
+     * PC でも同じ（gutter 24px の中までスクロールする）。`Container` の外に置いたときは何も起きない（はみ出し・余白とも 0）。
+     * 余白を持つ親（Card 等）の中に置くときは false にする。
+     */
+    bleed?: boolean;
+    /** 子要素の左端でスナップさせる。スナップ後も端の余白を保つ */
+    snap?: boolean;
+}
+/**
+ * ScrollRow — 横スクロールの行
+ *
+ * カード・絵柄・タグなどを横 1 列に並べて横スクロールさせる薄いレイアウト primitive。
+ * `Container` の中に置くと、Container の gutter（CSS 変数 `--Container-Gutter`）を読んで
+ * 「外へはみ出す ＋ 同じ幅の端の余白 ＋ 同じ幅の scroll-padding」を付ける。
+ * 画面ごとに `-mx-4 px-4 scroll-px-4` を手で当てる必要が無く、gutter が変わる幅（md 以上 24px）や
+ * `gutter="tight"` にも自動で追従する。
+ *
+ * - 子要素は縮まない（`shrink-0`）。幅は子要素側で決める（`snap` 時の `snap-start` も含め、子の class より優先される）
+ * - 間隔は 12px（`gap-3`）。変えるときは `className` で上書きする
+ * - 上下に 4px の余白を持ち、同じだけ負のマージンで打ち消す（高さは子要素と同じ）。横スクロールの行は
+ *   上下にもはみ出しを切り取るため、子のフォーカスリングが切れないようにする
+ * - カテゴリ（丸いアイコン＋名前）の列は `CategoryScroll`、自動再生・ドット付きのバナーは
+ *   `ContentCarousel` を使う
+ *
+ * ### インポート
+ * ```tsx
+ * import { ScrollRow } from '../../components/primitives/scroll-row'
+ * ```
+ *
+ * ### AI 向け使用ルール
+ *
+ * - `Container` の直下（左右の余白を足さない親の中）に置く。外側に `-mx-*` を足さない（二重にはみ出す）
+ * - Card など余白を持つ親の中、または Container の `className` で左右の余白を変えた中では `bleed={false}`。
+ *   gutter の変数は Container の子孫すべてに届くため、そのままだと gutter 分はみ出す
+ * - 端の余白をやめたいときは `className="px-0"` ではなく `bleed={false}` を使う
+ * - 中にリンクやボタンが無い（キーボードで届かない）なら、`tabIndex={0}`・`role="region"`・`aria-label` を渡す
+ */
+declare function ScrollRow({ bleed, snap, className, ...props }: ScrollRowProps): import("react/jsx-runtime").JSX.Element;
+export { ScrollRow };

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

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { LinkComponent } from "../../lib/link-component";
 export type SectionHeaderSize = "3xl" | "2xl" | "xl" | "lg" | "md" | "sm";
 export type SectionHeaderDesktopSize = "5xl" | "4xl";
 export interface SectionHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -38,6 +39,12 @@ export interface SectionHeaderProps extends React.HTMLAttributes<HTMLDivElement>
     align?: "start" | "center";
     /** タイトルの上に置くスロット（Badge 等の eyebrow ラベル）。中央寄せ見出しで特に有用。 */
     eyebrow?: React.ReactNode;
+    /**
+     * `moreHref` のリンク（タイトル行のリンクと「もっと見る」）の描画に使うコンポーネント（既定 `a`）。
+     * `next/link` 等を渡すとクライアント遷移になる（#236）。
+     * この部品は Server Component のまま使える。
+     */
+    linkComponent?: LinkComponent;
 }
 /**
  * セクションヘッダーコンポーネント
@@ -48,7 +55,7 @@ export interface SectionHeaderProps extends React.HTMLAttributes<HTMLDivElement>
  * Figma準拠:
  * - 6段階のサイズ（3xl〜sm）で見出し階層を表現
  * - タイトル行: タイトル（左）+ もっと見る（右）を items-baseline で配置
- * - もっと見る: Bold 14px、オレンジ（accent-primary）
+ * - もっと見る: typo-label-lg、グレー（Text-Medium-Emphasis）+ 常時下線（ブランド色は使わない。hover で濃いグレー）
  * - キャプション: 3xl〜lg は 16px / md〜sm は 14px
  *
  * ### AI 向け使用ルール
@@ -63,5 +70,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, desktopSize, 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, linkComponent, ...props }: SectionHeaderProps): import("react/jsx-runtime").JSX.Element;
 export { SectionHeader };

package/dist/types/components/primitives/side-nav.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { LinkComponent } from "../../lib/link-component";
 export interface SideNavItem {
     /** Lucide / iconsax アイコン等の ReactNode */
     icon: React.ReactNode;
@@ -42,6 +43,12 @@ export interface SideNavProps extends React.HTMLAttributes<HTMLElement> {
     groups: SideNavGroup[];
     /** aria-label */
     ariaLabel?: string;
+    /**
+     * リンクの描画に使うコンポーネント（既定 `a`）。
+     * `next/link` 等を渡すとクライアント遷移になる（#236）。
+     * 項目の `onClick`（`storyId` 指定時の遷移の差し替え）と `aria-current` は linkComponent 経由でも保たれる。
+     */
+    linkComponent?: LinkComponent;
 }
 /**
  * サイドナビゲーション
@@ -78,6 +85,11 @@ export interface SideNavProps extends React.HTMLAttributes<HTMLElement> {
  * | activeMatch | "exact" \| "prefix" | "exact" | currentPath の照合方法。prefix は配下ページ全体でアクティブ |
  * | isActive | (item) => boolean | — | アクティブ判定を上書きする述語（最優先） |
  * | ariaLabel | string | "サイドメニュー" | aria-label |
+ * | linkComponent | LinkComponent | "a" | リンクの描画に使うコンポーネント（next/link 等） |
+ *
+ * 全項目の `<a>` に `onClick`（`storyId` 指定時の遷移の差し替え）を付けるため、React Server Components
+ * では Server Component から描けない（`Event handlers cannot be passed to Client Component props` で落ちる）。
+ * Next.js App Router では呼び出し側のファイルを `"use client"` にする（`linkComponent` の有無によらない）。
  */
-declare function SideNav({ activeMenu, currentPath, activeMatch, isActive, groups, ariaLabel, className, ...props }: SideNavProps): import("react/jsx-runtime").JSX.Element;
+declare function SideNav({ activeMenu, currentPath, activeMatch, isActive, groups, ariaLabel, linkComponent, className, ...props }: SideNavProps): import("react/jsx-runtime").JSX.Element;
 export { SideNav };

package/dist/types/components/primitives/sub-nav.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { type LinkComponent } from "../../lib/link-component";
+import type { LinkComponent } from "../../lib/link-component";
 export interface SubNavItem {
     /** 表示ラベル */
     label: string;

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const tagVariants: (props?: {
-    variant?: "accent" | "default" | "success" | "info" | "warning" | "caution" | "sale" | "info-fill" | "timesale" | "berry" | "coupon";
+    variant?: "accent" | "image" | "default" | "success" | "info" | "warning" | "caution" | "sale" | "info-fill" | "timesale" | "berry" | "coupon";
     size?: "sm" | "md";
 } & import("class-variance-authority/types").ClassProp) => string;
 export interface TagProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof tagVariants> {

package/dist/types/index.d.ts

@@ -1,6 +1,8 @@
 import "./index.css";
 export { cn } from "./lib/utils";
-export { FOCUS_RING, FOCUS_RING_WITHIN, FOCUS_RING_INSET } from "./lib/focus-ring";
+export { FOCUS_RING, FOCUS_RING_WITHIN, FOCUS_RING_INSET, FOCUS_RING_ONLY } from "./lib/focus-ring";
+export { FORCED_COLORS_FOCUS, FORCED_COLORS_FOCUS_WITHIN, FORCED_COLORS_FOCUS_INSET, FORCED_COLORS_MENU_ITEM, FORCED_COLORS_COMMAND_ITEM, } from "./lib/focus-ring";
+export type { LinkComponent } from "./lib/link-component";
 export { toast } from "sonner";
 export { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "./components/foundations/accordion";
 export { Alert, AlertDescription, AlertTitle } from "./components/foundations/alert";
@@ -19,6 +21,8 @@ export { CheckboxGroup, CheckboxGroupItem } from "./components/foundations/check
 export type { CheckboxGroupProps } from "./components/foundations/checkbox-group";
 export { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./components/foundations/collapsible";
 export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from "./components/foundations/command";
+export { ConfirmDialogProvider, useConfirm } from "./components/foundations/confirm-dialog";
+export type { ConfirmDialogProviderProps, ConfirmFn, ConfirmOptions } from "./components/foundations/confirm-dialog";
 export { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from "./components/foundations/context-menu";
 export { DataTable, DataTableTable, DataTableHeader, DataTableBody, DataTableRow, DataTableHead, DataTableCell, DataTableAvatarCell, DataTableImageCell, DataTableLinkCell, DataTableCheckboxCell, DataTableActionCell, DataTableInputCell, DataTableSelectCell, DataTableNumberCell, DataTableDragHandleCell, DataTableBulkActions, DataTableSectionRow, DataTableAddRow, DataTableEmptyState, } from "./components/foundations/data-table";
 export type { SortDirection } from "./components/foundations/data-table";
@@ -155,6 +159,8 @@ export type { SearchBarProps } from "./components/primitives/search-bar";
 export { SearchPanel } from "./components/primitives/search-panel";
 export type { SearchPanelProps } from "./components/primitives/search-panel";
 export { Container, containerVariants } from "./components/primitives/container";
+export { ScrollRow } from "./components/primitives/scroll-row";
+export type { ScrollRowProps } from "./components/primitives/scroll-row";
 export { Section, sectionVariants, sectionScrimVariants } from "./components/primitives/section";
 export type { SectionProps, SectionScrim } from "./components/primitives/section";
 export { SectionHeader } from "./components/primitives/section-header";

package/dist/types/lib/field-labelling.d.ts

@@ -2,9 +2,8 @@
  * ## フィールドのラベル関連付け（DS 全体の方針 / issue #202）
  *
  * Radix ベースのコントロール（Select / Switch / Checkbox / Slider 等）は
- * `<button>` や `<span role="...">` として描画されるため、**隣に `<Label htmlFor>` を
- * 置いてもアクセシブルネームにならない**（`<label for>` が名前を与えるのは
- * labelable な要素だけで、`<button>` は対象外）。
+ * `<button>` や `<span role="...">` として描画される。単一フィールドは context の
+ * `aria-labelledby`、複数選択肢は各コントロールの native label または明示的な ARIA 名を使う。
  *
  * そこで DS は次の方針を採る:
  *
@@ -13,6 +12,8 @@
  * 2. コントロール側は `aria-labelledby` を **既定値として** その id にする。
  *    利用側が `aria-label` / `aria-labelledby` を明示した場合はそちらを優先する。
  * 3. ラッパー無しで単体利用するときは、利用側が `aria-label`（日本語）を書く。
+ * 4. ラッパーの説明・エラーは `aria-describedby` に、エラーの有無は `aria-invalid` に載せる。
+ *    `aria-describedby` は利用側の指定と **連結** し、`aria-invalid` は利用側の明示値を優先する。
  *
  * `<label for>` が有効なネイティブ入力（Input / Textarea）は従来どおり
  * `htmlFor` ↔ `id` の関連付けで足りるため、context の `controlId` を使う。
@@ -36,31 +37,45 @@ export interface FieldLabellingValue {
 declare const FieldLabellingContext: React.Context<FieldLabellingValue>;
 /** ラッパー内かどうかを問わず使える。ラッパー外では null。 */
 declare function useFieldLabelling(): FieldLabellingValue | null;
+type AriaInvalid = React.AriaAttributes["aria-invalid"];
+/**
+ * 空白区切りの id 列を連結する。空と重複は除く（順序は最初に現れた位置を保つ）。
+ * どれも無ければ undefined。
+ */
+declare function mergeIdRefs(...lists: Array<string | undefined>): string | undefined;
 /**
  * Radix トリガー系コントロール向けの aria 属性を解決する。
  *
- * 利用側の明示指定（aria-label / aria-labelledby / id / aria-describedby）を必ず優先し、
- * 何も指定が無いときだけラッパーの id を当てる。
+ * - 名前（aria-label / aria-labelledby）と id は利用側の明示指定を必ず優先し、
+ *   何も指定が無いときだけラッパーの id を当てる。
+ * - aria-describedby は **連結** する。利用側が指定してもラッパーの説明・エラーの id を
+ *   落とさない（エラー文が読み上げから消えるのを防ぐ）。同じ id は 1 回だけにする。
+ * - aria-invalid は利用側の明示値を優先し、無ければラッパーに error があるとき true。
  */
 declare function resolveFieldAria(props: {
     id?: string;
     "aria-label"?: string;
     "aria-labelledby"?: string;
     "aria-describedby"?: string;
-}, field: FieldLabellingValue | null): {
+    "aria-invalid"?: AriaInvalid;
+}, field: FieldLabellingValue | null, suppressDefaultLabelledBy?: boolean): {
     id?: string;
     "aria-labelledby"?: string;
     "aria-describedby"?: string;
+    "aria-invalid"?: AriaInvalid;
 };
 /**
  * ネイティブ入力（Input / Textarea）向け。
- * 名前は `<label for>` ↔ `id` で付くので、ここでは id と説明の関連付けだけ行う。
+ * 名前は `<label for>` ↔ `id` で付くので、ここでは id・説明の関連付け・エラー状態だけ扱う。
+ * aria-describedby の連結と aria-invalid の扱いは {@link resolveFieldAria} と同じ。
  */
 declare function resolveNativeFieldAria(props: {
     id?: string;
     "aria-describedby"?: string;
+    "aria-invalid"?: AriaInvalid;
 }, field: FieldLabellingValue | null): {
     id?: string;
     "aria-describedby"?: string;
+    "aria-invalid"?: AriaInvalid;
 };
-export { FieldLabellingContext, useFieldLabelling, resolveFieldAria, resolveNativeFieldAria, };
+export { FieldLabellingContext, useFieldLabelling, resolveFieldAria, resolveNativeFieldAria, mergeIdRefs, };

package/dist/types/lib/focus-ring.d.ts

@@ -18,13 +18,63 @@
  * `hover:not-focus-within:*` と書いてフォーカス中は hover を抑制すること。
  * この順序は `__tests__/focus-visible-contract.test.ts` で固定している。
  */
+/**
+ * 強制配色（forced-colors / Windows のハイコントラスト）用のフォーカス表示。
+ *
+ * DS のリングは `box-shadow` で描くが、forced-colors ではブラウザが box-shadow を描かない。
+ * さらに多くの部品は `outline-none` なので、そのままだとキーボードで動かしても現在地がどこにも
+ * 出ない（WCAG 2.4.7）。そこで `forced-colors:` でだけ実線の輪郭線（outline）を足す。
+ * 色は OS の選択色 `Highlight`（ブラウザ標準のフォーカスリングと同じ色）。
+ * `forced-colors` 以外では何も効かないので、通常表示は変わらない。
+ *
+ * - `outline-solid` が要る: 部品の `outline-none` は `outline-style: none` で、
+ *   `outline-2` だけでは上書きできない（`outline-solid` が `outline-style` を実線にする）
+ * - 輪郭線は `outline-offset` だけ離して描くのでレイアウトは動かない
+ *
+ * {@link FOCUS_RING} / {@link FOCUS_RING_WITHIN} / {@link FOCUS_RING_INSET} / {@link FOCUS_RING_ONLY} はこれを含むので、
+ * それらを使う部品は何もしなくてよい。`focus-visible:ring-*` を自前で書いている部品だけ、
+ * リングと一緒にこれを足す（`FOCUS_RING_*` 定数に寄せられるなら寄せる）。
+ *
+ * @example
+ * <button className={cn("outline-none focus-visible:ring-2 ...", FORCED_COLORS_FOCUS)} />
+ */
+export declare const FORCED_COLORS_FOCUS = "forced-colors:focus-visible:outline-solid forced-colors:focus-visible:outline-2 forced-colors:focus-visible:outline-offset-2 forced-colors:focus-visible:outline-[Highlight]";
+/**
+ * {@link FORCED_COLORS_FOCUS} の `focus-within` 版。ラッパーが枠を描く合成コントロール用
+ * （{@link FOCUS_RING_WITHIN} と対）。内側の要素にも outline が付く部品は、二重にならないよう
+ * 内側へ `forced-colors:focus-visible:outline-none` を足すこと。
+ */
+export declare const FORCED_COLORS_FOCUS_WITHIN = "forced-colors:focus-within:outline-solid forced-colors:focus-within:outline-2 forced-colors:focus-within:outline-offset-2 forced-colors:focus-within:outline-[Highlight]";
+/**
+ * {@link FORCED_COLORS_FOCUS} の内側版。`overflow-hidden` の内側にある要素用
+ * （{@link FOCUS_RING_INSET} と対。外向きの輪郭線は切り取られるので内側に描く）。
+ */
+export declare const FORCED_COLORS_FOCUS_INSET = "forced-colors:focus-visible:outline-solid forced-colors:focus-visible:outline-2 forced-colors:focus-visible:-outline-offset-2 forced-colors:focus-visible:outline-[Highlight]";
+/**
+ * メニュー項目（DropdownMenu / ContextMenu / Menubar / Select の項目）の「いま選んでいる位置」の
+ * forced-colors 表示。通常表示は `focus:bg-accent`（薄い地）で示すが、forced-colors では地が Canvas に
+ * 置き換わり、どの項目にフォーカスがあるか分からない。OS の選択色（Highlight / HighlightText）で塗る
+ * （OS 標準のメニューと同じ見え方）。中のアイコン・ショートカット文字も読めるよう子孫の文字色も揃え、
+ * destructive など他の `focus:bg-*` に負けないよう `!` を付ける。
+ *
+ * 項目は `outline-none` にしておくこと。`outline-hidden` は forced-colors で常時 2px の輪郭線を出すため、
+ * 全項目に枠が付いて選択位置が埋もれる。
+ */
+export declare const FORCED_COLORS_MENU_ITEM = "forced-colors:focus:bg-[Highlight]! forced-colors:focus:text-[HighlightText]! forced-colors:focus:[&_*]:text-[HighlightText]!";
+/** {@link FORCED_COLORS_MENU_ITEM} の cmdk（Command）版。選択中の項目は focus ではなく `data-selected` で示される。 */
+export declare const FORCED_COLORS_COMMAND_ITEM = "forced-colors:data-[selected=true]:bg-[Highlight]! forced-colors:data-[selected=true]:text-[HighlightText]! forced-colors:data-[selected=true]:[&_*]:text-[HighlightText]!";
 /**
  * 要素自身がフォーカスを受け取るコントロール用（input / button / trigger 等）。
  *
+ * リングの色は既定では従来どおり緑の 50% 透過。**枠幅 0 の要素**（枠なしの Button・NumberInput(sm) の
+ * ボタン等）では緑の枠が出ずリングだけが手がかりになり、50% のリングは 3:1 に届かないため、
+ * 高コントラスト（`prefers-contrast: more` / `data-contrast="more"`）のときだけ `--Focus-Ring-Control`
+ * （不透明な緑）に切り替わる（{@link FOCUS_RING_ONLY} と同じ色指定）。
+ *
  * @example
  * <input className={cn("border ...", FOCUS_RING)} />
  */
-export declare const FOCUS_RING = "focus-visible:border-[var(--Focus-High-Emphasis)] focus-visible:ring-[3px] focus-visible:ring-[var(--Focus-High-Emphasis)]/50";
+export declare const FOCUS_RING: string;
 /**
  * ラッパーが枠を描き、内側の要素がフォーカスを受け取る合成コントロール用
  * （SearchBar の枠、FileInput の label 等）。
@@ -34,9 +84,26 @@ export declare const FOCUS_RING = "focus-visible:border-[var(--Focus-High-Emphas
  * @example
  * <div className={cn("border hover:not-focus-within:border-x", FOCUS_RING_WITHIN)}>
  */
-export declare const FOCUS_RING_WITHIN = "focus-within:border-[var(--Focus-High-Emphasis)] focus-within:ring-[3px] focus-within:ring-[var(--Focus-High-Emphasis)]/50";
+export declare const FOCUS_RING_WITHIN: string;
+/**
+ * リングだけ（枠の色は変えない）でフォーカスを示す部品用。Switch / ListItem / カルーセル等。
+ *
+ * 既定は {@link FOCUS_RING} と同じ緑の 50% リング（`--Focus-High-Emphasis` を 50% 透過）。
+ * 50% のリングは白地に対して 3:1 に届かないため、高コントラスト
+ * （`prefers-contrast: more` / `data-contrast="more"`）のときだけ `--Focus-Ring-Control`
+ * （不透明な緑）に切り替わる。`--Focus-Ring-Control` は semantic.css の高コントラスト節でだけ宣言され、
+ * 未宣言のときはフォールバックの 50% リングになるので、既定の見た目は変わらない。
+ *
+ * 枠も緑にできる部品は、これではなく {@link FOCUS_RING} を使う。
+ * `ring-[var(--Focus-High-Emphasis)]/50` を直接書かない（高コントラスト時に切り替わらない）。
+ *
+ * @example
+ * <button className={cn("outline-none", FOCUS_RING_ONLY)} />
+ */
+export declare const FOCUS_RING_ONLY: string;
 /**
  * `overflow-hidden` なコンテナの内側にある要素用（リングが外にはみ出すと
  * 切り取られてしまうため内側に描く）。SearchBar の検索ボタン等。
+ * リングの色は {@link FOCUS_RING_ONLY} と同じ（高コントラスト時に切り替わる）。
  */
-export declare const FOCUS_RING_INSET = "focus-visible:ring-[3px] focus-visible:ring-inset focus-visible:ring-[var(--Focus-High-Emphasis)]/50";
+export declare const FOCUS_RING_INSET: string;

package/dist/types/lib/high-contrast.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 高コントラスト（`prefers-contrast: more` / `data-contrast="more"`）のときだけ現れる輪郭。
+ *
+ * 枠を持たず、地の色だけで形を示している操作部品（Combobox / MultiSelect のトリガー、
+ * NumberInput size="sm" の丸型の地）は、既定では背景との差が 3:1 に届かない
+ * （WCAG 1.4.11・issue #301）。既定の見た目は変えず、高コントラストのときだけ
+ * `--Border-Control`（semantic.css の高コントラスト節でだけ宣言される）の 1px の線を内側に描く。
+ *
+ * - 未宣言のとき（= 既定）は透明の outline なので何も見えない。レイアウトにも影響しない
+ *   （border と違い要素の内側の寸法を変えない）。
+ * - outline-offset を -1px にして、`overflow-hidden` の親に切り取られないよう要素の内側に収める。
+ * - outline-solid は Button 基底の `outline-none`（outline-style: none）を打ち消すために必要。
+ * - エラー（aria-invalid）のときは outline を透明にする。トリガーのエラーの赤枠は内側リング（inset-ring・
+ *   Border-Caution）で描いており、高コントラストの灰色の outline が同じ画素に重なると赤が隠れるため。
+ *   outline を赤にすると、既定でも角丸のアンチエイリアス部分で赤の outline と赤の内側リングが重なって
+ *   濃くなる（main と画素が変わる）ので、赤にはせず透明にして、赤の内側リング（4.6:1 以上）をそのまま見せる。
+ *   既定の outline は元から透明なので、既定の表示は変わらない。
+ * - forced-colors（Windows のハイコントラスト）では透明の outline も表示色で描かれるため、
+ *   境界の無かったトリガーに線が出る（意図した挙動）。エラー時の CanvasText は各部品の
+ *   `forced-colors:aria-invalid:outline-[CanvasText]` が上書きする。
+ *
+ * 枠を持つ部品は、これではなく `border-[var(--Border-Control,var(--Border-Medium-Emphasis))]` の形で
+ * 枠の色そのものを切り替える。
+ */
+export declare const HIGH_CONTRAST_OUTLINE = "outline-solid outline-1 -outline-offset-1 outline-[color:var(--Border-Control,transparent)] aria-invalid:outline-transparent";

package/dist/types/lib/image-index.d.ts

@@ -0,0 +1,2 @@
+/** images 更新時に、現在の画像を維持しつつ有効な index へ補正する。 */
+export declare function reconcileImageIndex(previousImages: string[], images: string[], currentIndex: number): number;

package/dist/types/lib/link-component.d.ts

@@ -2,34 +2,39 @@ import type * as React from "react";
 /**
  * リンクの描画に使うコンポーネント（#236）
  *
- * DS 内でリンクを複数描く部品（Footer / MenuDrawer / SubNav / Pagination）は
- * 素の `<a>` を描くため、Next.js の `next/link` 等を差し込めずクライアント遷移に
- * ならない。`asChild` は複数リンクを内部で描く部品には向かないため、
- * 「リンク実装そのもの」を差し替える prop を共通の型で用意する。
+ * DS 内でリンクを描く部品は素の `<a>` を描くため、Next.js の `next/link` 等を
+ * 差し込めずクライアント遷移にならない。`asChild` は複数リンクを内部で描く部品には
+ * 向かないため、「リンク実装そのもの」を差し替える prop を共通の型で用意する。
  *
  * 例: `<Footer linkComponent={Link} … />`（next/link をそのまま渡せる）
  *
- * ⚠️ `Footer` / `MenuDrawer` は Client Component。React Server Components では
- * Server Component からこの prop を渡すと client 境界を越えて関数を渡すことに
- * なり、`Functions cannot be passed directly to Client Components` で落ちる。
+ * 対応部品: Footer / MenuDrawer / SubNav / Pagination（PaginationLink・Previous・Next）/
+ * ContentCard / AdminSideNav / SideNav / BottomTabBar / Header / AdminShell / MypageShell /
+ * BreadcrumbLink / ListItem / SectionHeader / ProductCard / ProductListItem / ShopCard /
+ * ProductCarousel / ProductDetailBar / ProductDetailSidebar / BannerCarousel / ImageCarousel /
+ * CategoryScroll / CategoryShortcuts / NotificationList / AnniversaryCard / DataTableLinkCell / Chip。
+ * 未指定なら従来どおり素の `<a>`。`external: true` を持つ Footer / DataTableLinkCell の外部リンクは
+ * 常に素の `<a target="_blank">`。
+ *
+ * ⚠️ Client Component の部品（`Footer` / `MenuDrawer` / `Header` / `AdminSideNav` / `AdminShell` /
+ * `ListItem` / `ImageCarousel`。`MypageShell` も内部で `Header` へ渡す）は、React Server Components
+ * では Server Component からこの prop を渡すと client 境界を越えて関数を渡すことになり、
+ * `Functions cannot be passed directly to Client Components` で落ちる。
  * Next.js App Router では、この prop を使う呼び出し側を `"use client"` にする
  * （エラーメッセージは `"use server"` を示唆するが、正解は逆）。
  *
- * `Pagination` / `SubNav` / `ContentCard` は Server Component のまま使えるため、
- * この prop を使うだけで呼び出し側を `"use client"` にする必要はない。
+ * ⚠️ 内部で host 要素（`<a>` / `<button>`）にイベントハンドラを直接付ける部品は、`"use client"` を持たなくても
+ * Server Component から描けない（`Event handlers cannot be passed to Client Component props` で落ちる。
+ * `linkComponent` の有無によらない）。呼び出し側を `"use client"` にする。無条件: `SideNav`（全項目の
+ * `onClick`）/ `ProductDetailBar`（全タブの `onClick`）。条件付き: `ProductCard` / `ProductCarousel`
+ * （`shopHref` 指定時のショップ名リンク、`showCartButton` 指定時のカートボタン）/ `ProductDetailSidebar`
+ * （`sizeOptions` 指定時）/ `Chip`（`removable` 指定時）。`MypageShell` も内部で `SideNav` を描く。
+ *
+ * それ以外（`Pagination` / `SubNav` / `ContentCard` / `BottomTabBar` / `SectionHeader` / `ProductListItem` /
+ * `ShopCard` / `BannerCarousel` / `CategoryScroll` / `CategoryShortcuts` / `NotificationList` /
+ * `AnniversaryCard` / `DataTableLinkCell` / `BreadcrumbLink`、および上の条件付きの部品の条件外）は
+ * Server Component のまま使えるため、この prop を使うだけで呼び出し側を `"use client"` にする必要はない。
  */
 export type LinkComponent = React.ComponentType<React.AnchorHTMLAttributes<HTMLAnchorElement> & {
     href: string;
 }>;
-/**
- * 実際に使うリンク実装を決める。
- *
- * 外部リンク（`target="_blank"` を付けるもの）は framework のリンク部品に通す
- * 意味が無いため、常に素の `<a>` にフォールバックする。
- *
- * `isExternal` を渡せるのは、項目に `external` フラグを持つ `Footer` だけ。
- * MenuDrawer / SubNav / Pagination の項目に `external` は無く、渡した href は
- * すべて `linkComponent` で描かれる（外部 URL を出し分けたい場合は consumer 側で
- * ラップする）。
- */
-export declare function resolveLinkComponent(linkComponent: LinkComponent | undefined, isExternal?: boolean): React.ElementType;

package/dist/types/lib/use-prefers-reduced-motion.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 利用者が OS の「視差効果を減らす / アニメーションを減らす」（prefers-reduced-motion: reduce）を
+ * 選んでいるかを返す。設定の変更にも追従する。
+ *
+ * CSS で止められない動き（JS の自動再生・`scrollTo({ behavior: "smooth" })` など）を
+ * 止める判定に使う。CSS のアニメーションは `motion-reduce:` バリアントや
+ * `--Motion-Duration-*` トークンで止める。
+ */
+export declare function usePrefersReducedMotion(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cakejp/design-system",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "Cake.jp Design System — UI コンポーネント・カラートークン・タイポグラフィ",
   "license": "UNLICENSED",
@@ -96,11 +96,19 @@
     "generate:lint-rules": "node scripts/generate-lint-rules.mjs",
     "generate:lookup": "node scripts/generate-component-lookup.mjs",
     "lint:contrast": "node scripts/check-contrast.mjs",
-    "check": "tsc --noEmit -p tsconfig.app.json && npm run typecheck:stories && bash scripts/check-deps.sh && bash scripts/check-drift.sh && bash scripts/check-docs-drift.sh && bash scripts/lint-scratch.sh && bash scripts/check-story-reuse.sh && bash scripts/check-responsive.sh && node scripts/check-border-color.mjs && npm run lint:contrast && bash scripts/lint-scratch.sh --components && bash scripts/check-generated-drift.sh && bash scripts/check-agents-mirror.sh",
+    "lint:css-vars": "node scripts/check-css-vars.mjs",
+    "lint:vrt-baselines": "node scripts/check-vrt-baselines.mjs",
+    "check": "tsc --noEmit -p tsconfig.app.json && npm run typecheck:stories && bash scripts/check-deps.sh && bash scripts/check-drift.sh && bash scripts/check-docs-drift.sh && bash scripts/lint-scratch.sh && bash scripts/check-story-reuse.sh && bash scripts/check-responsive.sh && node scripts/check-border-color.mjs && node scripts/check-css-vars.mjs && npm run lint:contrast && bash scripts/lint-scratch.sh --components && bash scripts/check-generated-drift.sh && bash scripts/check-agents-mirror.sh && node scripts/check-vrt-baselines.mjs",
     "test": "vitest run --config vitest.config.ts",
     "test:interaction": "vitest run --config vitest.storybook.config.ts",
     "test:a11y": "vitest run --config vitest.a11y.config.ts",
-    "check:consumer-types": "node scripts/check-consumer-types.mjs"
+    "test:interaction:webkit": "CAKE_BROWSER=webkit vitest run --config vitest.storybook.config.ts",
+    "test:a11y:webkit": "CAKE_BROWSER=webkit vitest run --config vitest.a11y.config.ts",
+    "test:forced-colors": "vitest run --config vitest.forced-colors.config.ts",
+    "test:vrt": "vitest run --config vitest.vrt.config.ts",
+    "test:vrt:docker": "bash scripts/vrt-docker.sh",
+    "check:consumer-types": "node scripts/check-consumer-types.mjs",
+    "check:hydration": "node scripts/check-hydration.mjs"
   },
   "dependencies": {
     "class-variance-authority": "^0.7.1",