@cakejp/design-system 0.17.1 → 0.20.0

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

@@ -0,0 +1,35 @@
+import type * as React from "react";
+/**
+ * リンクの描画に使うコンポーネント（#236）
+ *
+ * DS 内でリンクを複数描く部品（Footer / MenuDrawer / SubNav / Pagination）は
+ * 素の `<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` で落ちる。
+ * Next.js App Router では、この prop を使う呼び出し側を `"use client"` にする
+ * （エラーメッセージは `"use server"` を示唆するが、正解は逆）。
+ *
+ * `Pagination` / `SubNav` / `ContentCard` は 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cakejp/design-system",
-  "version": "0.17.1",
+  "version": "0.20.0",
   "type": "module",
   "description": "Cake.jp Design System — UI コンポーネント・カラートークン・タイポグラフィ",
   "license": "UNLICENSED",
@@ -96,10 +96,11 @@
     "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",
+    "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",
     "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"
+    "test:a11y": "vitest run --config vitest.a11y.config.ts",
+    "check:consumer-types": "node scripts/check-consumer-types.mjs"
   },
   "dependencies": {
     "class-variance-authority": "^0.7.1",
@@ -110,6 +111,7 @@
     "react-hook-form": "^7.0.0",
     "sonner": "^2.0.0",
     "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0",
     "vaul": "^1.0.0"
   },
   "peerDependencies": {
@@ -174,7 +176,6 @@
     "storybook": "^10.3.3",
     "tailwindcss": "^4.2.1",
     "tsc-alias": "^1.8.16",
-    "tw-animate-css": "^1.4.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.48.0",
     "vaul": "^1.1.2",

package/src/components/COMPONENT_LOOKUP.md

@@ -57,7 +57,7 @@
 | Spinner | `@/components/foundations/spinner` | — | Default, Small, Large, InlineWithText, FullPage |
 | Switch | `@/components/foundations/switch` | — | Default, ON 状態, 無効, サイズ比較, ブロック型, 通知設定例（リスト型） |
 | Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption | `@/components/foundations/table` | — | Default, フッター付き, 商品比較例, カート注文サマリー |
-| Tabs, TabsList, TabsTrigger, TabsContent | `@/components/foundations/tabs` | **variant**: `underbar`, `segment`<br>**scrollable**: `true` | Default（Underbar）, タブ数バリエーション, 横スクロール（多数タブ）, PC モード（文字幅ベース）, Segment（ピル型）, Segment 3択, interaction: クリックと矢印キーでの切り替え |
+| Tabs, TabsList, TabsTrigger, TabsContent | `@/components/foundations/tabs` | **variant**: `underbar`, `segment`<br>**scrollable**: `true`<br>**size**: `md`, `sm` | Default（Underbar）, タブ数バリエーション, 横スクロール（多数タブ）, PC モード（文字幅ベース）, Segment（ピル型）, Segment 3択, 狭幅（サイドバー 266px）, interaction: クリックと矢印キーでの切り替え |
 | Textarea | `@/components/foundations/textarea` | — | Default, 無効, メッセージカード入力例, エラーパターン, レビュー投稿例, 文字数カウンタ |
 | ToggleGroup, ToggleGroupItem | `@/components/foundations/toggle-group` | **width**: `fit`, `full`<br>**variant**: `default`, `outline`<br>**size**: `default`, `sm`, `lg`<br>**variant**: `default`, `outline`<br>**size**: `default`, `sm`, `lg` | Default, 複数選択, サイズ, アイコン付き, アイコンのみ, 無効 |
 | Toggle | `@/components/foundations/toggle` | **variant**: `default`, `outline`<br>**size**: `default`, `sm`, `lg` | Default, TextFormatting, FavoriteToggle, Outline, Sizes |
@@ -70,7 +70,7 @@
 | Component | Import | Variants | Stories |
 |-----------|--------|----------|---------|
 | AdminHeader | `@/components/primitives/admin-header` | — | — |
-| AdminSideNav | `@/components/primitives/admin-side-nav` | — | — |
+| AdminSideNav | `@/components/primitives/admin-side-nav` | — | 下端寄り・多数項目・キーボード操作, interaction: flyout の開閉・フォーカス・viewport 境界 |
 | BannerCarousel | `@/components/primitives/banner-carousel` | — | Default, SmallBanners, LargeBanners |
 | BottomTabBar | `@/components/primitives/bottom-tab-bar` | — | Default（ホーム）, アクティブ状態, バッジ付き, バッジオーバーフロー（99+）, バナー付き, 記念日アクティブ |
 | BulkActionBar | `@/components/primitives/bulk-action-bar` | — | — |
@@ -81,6 +81,7 @@
 | CoachMark | `@/components/primitives/coach-mark` | — | オンボーディング, 全方向, オンボーディング各方向 |
 | Combobox | `@/components/primitives/combobox` | — | Default |
 | Container | `@/components/primitives/container` | — | Default（page / default gutter）, サイズ比較, gutter 比較 |
+| ContentCard, ContentList | `@/components/primitives/content-card` | — | 縦（グリッド一覧）, 一覧での高さ揃え, 横（画像が左）, リスト（Medium 型）, 長いタグラベル |
 | ContentCarousel | `@/components/primitives/content-carousel` | — | ヒーローバナー, 自動再生（5秒）, peek表示, 多列カード（PC 3枚）, 1枚のみ |
 | DatePicker, DateTimePicker | `@/components/primitives/date-picker` | — | 日付ピッカー, 初期値あり, 選択範囲を制限, 特定日を無効化, FormField 連携, 無効化, クリア可能（任意項目） |
 | EmptyState | `@/components/primitives/empty-state` | — | お気に入り商品（空）, カート（空）, ブックマーク（空）, 検索結果なし, 汎用（説明のみ） |
@@ -89,7 +90,7 @@
 | Footer | `@/components/primitives/footer` | — | Default, 最小構成, SNSリンク付き, 決済方法付き |
 | FormField | `@/components/primitives/form-field` | — | — |
 | FunnelShell | `@/components/primitives/funnel-shell` | — | 注文内容の確認（ご購入手続き） |
-| Header | `@/components/primitives/header` | — | ロゴ＋アクション, ロゴ＋未ログイン, ロゴ＋グローバルナビ＋検索スロット（PC）, ロゴ＋長いナビ（中幅で自動退避）, ロゴ＋ナビ（navBreakpoint=lg）, ロゴセンター（決済・申し込み用）, 戻る＋タイトル, 戻る＋検索バー, 戻る＋右側アクション, カスタムロゴ |
+| Header | `@/components/primitives/header` | — | ロゴ＋アクション, ロゴ＋未ログイン, ロゴ＋グローバルナビ＋検索スロット（PC）, ロゴ＋長いナビ（中幅で自動退避）, ロゴ＋ナビ（navBreakpoint=lg）, containerSize=page（本文と左端を揃える）, ロゴセンター（決済・申し込み用）, 戻る＋タイトル, 戻る＋検索バー, 戻る＋右側アクション, カスタムロゴ |
 | ImageCarousel | `@/components/primitives/image-carousel` | — | バナーカルーセル, 横長バナー, 正方形（商品画像）, OGP比率, 自動再生（3秒）, PC幅（ビューポート切替で確認）, トップページ ヒーローバナー |
 | ImageGallery | `@/components/primitives/image-gallery` | — | ドット付き, サムネイル付き, バナー（16:9）, PC商品詳細, 単一画像 |
 | ImageInput | `@/components/primitives/image-input` | **aspect**: `square`, `landscape`<br>**size**: `sm`, `md`, `lg` | 基本, 保存済み画像あり, 表示サイズ, FormField 連携, 検証エラー, クリア不可, 無効化 |
@@ -103,12 +104,13 @@
 | NumberInput, QuantitySelector | `@/components/primitives/number-input` | — | Default, コンパクト型（sm）, サイズ比較, 最小・最大値, 無効状態, エラー状態, ゴミ箱アイコン, ゴミ箱＋削除確認ダイアログ, 直接入力パターン, 商品詳細での使用例, カート内での使用例, 価格・在庫入力（管理画面）, interaction: 増減と min/max のクランプ |
 | PriceDisplay | `@/components/primitives/price-display` | — | Default, セール価格, サイズ比較, セール × サイズ, 税込ラベルなし, 高額商品, 価格レンジ |
 | ProgressSteps | `@/components/primitives/progress-steps` | — | ステップ1（カート）, ステップ2（注文内容）, ステップ3（確認）, ステップ4（完了）, 全ステップ一覧, 会員登録フロー |
-| SearchBar | `@/components/primitives/search-bar` | — | Default, Small（ヘッダー向け）, カスタムプレースホルダー |
+| Prose | `@/components/primitives/prose` | — | 記事本文（Container narrow と組み合わせ）, children を包む, 幅の広い表（ページを横に伸ばさない） |
+| SearchBar | `@/components/primitives/search-bar` | — | Default, Small（ヘッダー向け）, form モード（JS 不要・SEO 向け）, カスタムプレースホルダー |
 | SearchPanel | `@/components/primitives/search-panel` | — | — |
-| SectionHeader | `@/components/primitives/section-header` | — | Default, サブタイトル付き, リンクなし, カスタムラベル, カルーセルナビ付き, ナビのみ, ナビ（先頭位置）, アクションボタン付き, サブタイトル + アクション, サイズ一覧, キャプション付きサイズ比較, align=, LPヒーロー（SP 3xl / PC 5xl）, align=, start / center 比較 |
+| SectionHeader | `@/components/primitives/section-header` | — | Default, サブタイトル付き, リンクなし, カスタムラベル, カルーセルナビ付き, ナビのみ, ナビ（先頭位置）, アクションボタン付き, サブタイトル + アクション, 狭幅のサブタイトル + アクション, サイズ一覧, キャプション付きサイズ比較, align=, LPヒーロー（SP 3xl / PC 5xl）, align=, start / center 比較 |
 | SectionNav | `@/components/primitives/section-nav` | — | Vertical, Horizontal |
 | Section | `@/components/primitives/section` | — | 推奨: Section + Container, 背景画像 + scrim, 背景バリアント, 縦 spacing バリアント, 配下 Card のサーフェス伝播, ランディング見出し |
-| ShareButtons | `@/components/primitives/share-buttons` | — | Default, コピーフィードバック |
+| ShareButtons | `@/components/primitives/share-buttons` | — | Default, コピーフィードバック, 共有先を指定（Facebook / はてブ）, 組み込みに無い共有先を足す |
 | SideNav | `@/components/primitives/side-nav` | — | Default, WithGroupLabels, MypageExample, PrefixMatch |
 | SocialLoginButton | `@/components/primitives/social-login-button` | — | LINE, フルサイズ一覧, アイコンのみ |
 | StandardPageShell | `@/components/primitives/standard-page-shell` | — | 検索結果ページ |

package/src/preset-standalone.css

@@ -191,6 +191,7 @@
   --Surface-Primary: #FFFFFF;
   --Surface-Secondary: #FBF9F8;
   --Surface-Tertiary: #F4F2F1;
+  --Surface-Elevated: #FFFFFF;
   --Surface-Caution: #EC0000;
   --Surface-Caution-Light: #FFE7E6;
   --Surface-Accent-Primary: #E04B00;
@@ -266,12 +267,14 @@
   --Third-Party-LINE: #06C755;
   --Third-Party-Apple: #000000;
   --Third-Party-X: #000000;
+  --Third-Party-Hatena: #00A4DE;
 }
 
 .dark {
   --Surface-Primary: #000000E5;
   --Surface-Secondary: #FFFFFF1A;
   --Surface-Tertiary: #FFFFFF33;
+  --Surface-Elevated: #3A3736;
   --Surface-Caution: #EC0000;
   --Surface-Caution-Light: #FFE7E6;
   --Surface-Accent-Primary: #E04B00;

package/src/preset.css

@@ -19,7 +19,7 @@
  *   - シャドウ・角丸トークン
  *   - モーショントークン（--Motion-Duration-* / --Motion-Easing-*）
  *   - 重なり順トークン（--Z-*）
- *   - アニメーションユーティリティ
+ *   - アニメーションユーティリティ（tw-animate-css の animate-in 系 + 独自 keyframes）
  *   - 見た目を変えず44pxの操作領域を確保する tap-target ユーティリティ
  * ============================================ */
 
@@ -35,6 +35,16 @@
 /* --- Layer 4: Motion Tokens (duration / easing) --- */
 @import "./styles/motion.css";
 
+/* --- Layer 5: Animation Utilities (tw-animate-css) ---
+   foundations の 12 部品（Dialog / Sheet / Popover / DropdownMenu / Select /
+   Tooltip / Drawer / AlertDialog / HoverCard / ContextMenu / Menubar /
+   NavigationMenu）が使う animate-in / zoom-in-* / slide-in-from-* は
+   Tailwind 本体ではなく tw-animate-css のユーティリティ。preset が配らないと、
+   自分で tw-animate-css を入れた consumer だけアニメーションが動く暗黙依存になる
+   （実例: cakejp-biz-mag のモバイルメニューが無言で無アニメーションだった）。
+   パッケージ解決で consumer の node_modules から読む（DS の dependency）。 */
+@import "tw-animate-css";
+
 /* --- Dark mode variant --- */
 @custom-variant dark (&:is(.dark *));
 
@@ -52,6 +62,14 @@
   --container-md: 48rem; /* 768px — SP/PC 境界（切替段。本番と一致） */
   --container-lg: 60rem; /* 960px — PC 中段（切替段。本番と一致） */
   --container-xl: 80rem; /* 1280px — コンテンツ上限段（DS 定義。本番の切替段ではない） */
+
+  /* ビューポート用（consumer の md: / lg: / xl:）。コンテナクエリ段と同じ値に揃える。
+     Tailwind v4 既定の --breakpoint-lg は 64rem(1024px) で、DS の PC 中段 960px と
+     64px ずれる。preset が配らないと全 consumer が @theme で書き直す必要があり、
+     書き忘れたプロダクトだけ切替位置がずれる（issue #242）。 */
+  --breakpoint-md: 48rem; /* 768px — SP/PC 境界 */
+  --breakpoint-lg: 60rem; /* 960px — PC 中段 */
+  --breakpoint-xl: 80rem; /* 1280px — コンテンツ上限段 */
 }
 
 /* --- Theme: Tailwind integration --- */
@@ -226,7 +244,7 @@
   --foreground: var(--Text-High-Emphasis);
   --card: var(--Surface-Secondary);
   --card-foreground: var(--Text-High-Emphasis);
-  --popover: var(--Surface-Primary);
+  --popover: var(--Surface-Elevated);
   --popover-foreground: var(--Text-High-Emphasis);
   --primary: var(--Brand-Cake-Orange);
   --primary-foreground: var(--Text-on-Inverse);
@@ -262,7 +280,7 @@
   --foreground: var(--Text-High-Emphasis);
   --card: var(--Surface-Secondary);
   --card-foreground: var(--Text-High-Emphasis);
-  --popover: var(--Surface-Primary);
+  --popover: var(--Surface-Elevated);
   --popover-foreground: var(--Text-High-Emphasis);
   --primary: var(--Brand-Cake-Orange);
   --primary-foreground: var(--Text-on-Inverse);

package/src/styles/semantic.css

@@ -16,6 +16,12 @@
   --Surface-Primary: var(--Primitive-White-alpha-1000);
   --Surface-Secondary: var(--Primitive-Gray-50);
   --Surface-Tertiary: var(--Primitive-Gray-100);
+  /* 浮遊レイヤー（メニュー・ポップオーバー・ダイアログ・シート）と、
+     スクロール内容の上に重なるエッジ固定バー（Header / StickyActionBar /
+     BottomTabBar / AdminHeader / AdminSideNav / OrderSummary fixed）の地。
+     任意のコンテンツの上に重なるので必ず不透明にする（issue #262）。
+     light は Surface-Primary と同値（元から不透明）。 */
+  --Surface-Elevated: var(--Primitive-White-alpha-1000);
   --Surface-Caution: var(--Primitive-Sun-800);
   --Surface-Caution-Light: var(--Primitive-Sun-50);
   --Surface-Accent-Primary: var(--Primitive-Orange-700);
@@ -116,6 +122,7 @@
   --Third-Party-LINE: #06C755FF;
   --Third-Party-Apple: #000000FF;
   --Third-Party-X: #000000FF;
+  --Third-Party-Hatena: #00A4DEFF;
 }
 
 /* ============================================
@@ -128,6 +135,10 @@
   --Surface-Primary: var(--Primitive-Gray-alpha-900);
   --Surface-Secondary: var(--Primitive-White-alpha-100);
   --Surface-Tertiary: var(--Primitive-White-alpha-200);
+  /* dark の Surface-Primary は #000000E5 でアルファ付き。ページ地としては
+     下地に合成される前提なので妥当だが、浮遊レイヤーに使うと後ろが透ける。
+     一段明るい不透明色を elevation として持つ（issue #262）。 */
+  --Surface-Elevated: var(--Primitive-Gray-800);
   --Surface-Caution: var(--Primitive-Sun-800);
   --Surface-Caution-Light: var(--Primitive-Sun-50);
   --Surface-Accent-Primary: var(--Primitive-Orange-700);

package/templates/AGENTS.md

@@ -1,6 +1,8 @@
 <!--
-  このファイルは @cakejp/design-system の postinstall で自動設置されました。
-  最新ルールを取り込むには: npx cakejp-ds init --force
+  DS 共通ルールの正本。npm package に同梱され、consumer からは
+  node_modules/@cakejp/design-system/templates/ 配下を参照して読む。
+  consumer のリポジトリへ本文をコピーしないこと（写しは必ず古くなる）。
+  consumer ルートに置かれるのは、この正本を指すポインタ（*.stub.md）だけ。
 -->
 
 # このプロジェクトは @cakejp/design-system に準拠する

package/templates/AGENTS.stub.md

@@ -0,0 +1,25 @@
+<!--
+  このファイルは @cakejp/design-system の postinstall で自動設置されました。
+  DS 共通ルールは package 内の正本を参照します（このファイルへは複製しません）。
+  プロジェクト固有のルールは下の「プロジェクト固有ルール」以下へ自由に書けます。
+  DS 側の更新は npm install だけで反映されるため、書き写す必要はありません。
+-->
+
+# このプロジェクトは @cakejp/design-system に準拠する
+
+Codex（および他の AI エージェント）は UI を作成・変更・レビューする前に、
+**DS 共通ルールの正本を必ず読み込むこと**。
+
+## 📖 DS 共通ルール（正本・必読）
+
+- `node_modules/@cakejp/design-system/templates/AGENTS.md`
+
+このファイルへ内容を書き写さないこと。**手元の写しは必ず古くなる**（DS 側にルールが
+追加されても写しには反映されない）。正本は `npm install` のたびに最新へ更新される。
+
+正本から辿る必読ファイル（`CLAUDE.md` / `contracts/*.json` / `tokens.json` 等）も
+すべて `node_modules/@cakejp/design-system/` 配下にある。
+
+## プロジェクト固有ルール
+
+<!-- ここから下はプロジェクト固有。DS の更新で上書きされません。 -->

package/templates/CLAUDE.md

@@ -1,6 +1,8 @@
 <!--
-  このファイルは @cakejp/design-system の postinstall で自動設置されました。
-  最新ルールを取り込むには: npx cakejp-ds init --force
+  DS 共通ルールの正本。npm package に同梱され、consumer からは
+  node_modules/@cakejp/design-system/templates/ 配下を参照して読む。
+  consumer のリポジトリへ本文をコピーしないこと（写しは必ず古くなる）。
+  consumer ルートに置かれるのは、この正本を指すポインタ（*.stub.md）だけ。
 -->
 
 # このプロジェクトは @cakejp/design-system に準拠する

package/templates/CLAUDE.stub.md

@@ -0,0 +1,25 @@
+<!--
+  このファイルは @cakejp/design-system の postinstall で自動設置されました。
+  DS 共通ルールは package 内の正本を参照します（このファイルへは複製しません）。
+  プロジェクト固有のルールは下の「プロジェクト固有ルール」以下へ自由に書けます。
+  DS 側の更新は npm install だけで反映されるため、書き写す必要はありません。
+-->
+
+# このプロジェクトは @cakejp/design-system に準拠する
+
+Claude Code（および他の AI エージェント）は UI を作成・変更・レビューする前に、
+**DS 共通ルールの正本を必ず読み込むこと**。
+
+## 📖 DS 共通ルール（正本・必読）
+
+- `node_modules/@cakejp/design-system/templates/CLAUDE.md`
+
+このファイルへ内容を書き写さないこと。**手元の写しは必ず古くなる**（DS 側にルールが
+追加されても写しには反映されない）。正本は `npm install` のたびに最新へ更新される。
+
+正本から辿る必読ファイル（`CLAUDE.md` / `contracts/*.json` / `tokens.json` 等）も
+すべて `node_modules/@cakejp/design-system/` 配下にある。
+
+## プロジェクト固有ルール
+
+<!-- ここから下はプロジェクト固有。DS の更新で上書きされません。 -->

package/tokens.json

@@ -119,6 +119,11 @@
           "hex": "#F4F2F1",
           "usage": "ターシャリ背景"
         },
+        "elevated": {
+          "value": "Primitive-White-alpha-1000",
+          "hex": "#FFFFFF",
+          "usage": "浮遊レイヤー（メニュー・ポップオーバー・ダイアログ・シート）と、スクロール内容の上に重なるエッジ固定バー（Header / StickyActionBar / BottomTabBar 等）の地。必ず不透明にする"
+        },
         "caution": {
           "value": "Primitive-Sun-800",
           "hex": "#EC0000",
@@ -463,6 +468,10 @@
         "x": {
           "value": "#000000FF",
           "usage": "Third-Party-X のCSS契約値"
+        },
+        "hatena": {
+          "value": "#00A4DEFF",
+          "usage": "Third-Party-Hatena のCSS契約値（はてなブックマーク）"
         }
       }
     },
@@ -480,6 +489,10 @@
           "value": "var(--Primitive-White-alpha-200)",
           "usage": "Surface-Tertiary のCSS契約値"
         },
+        "elevated": {
+          "value": "var(--Primitive-Gray-800)",
+          "usage": "Surface-Elevated のCSS契約値"
+        },
         "caution": {
           "value": "var(--Primitive-Sun-800)",
           "usage": "Surface-Caution のCSS契約値"
@@ -931,11 +944,12 @@
     }
   },
   "breakpoints": {
-    "comment": "役割は二層。(1) 切替段=md / lg の2つだけ（値は本番 cakejp.css の境界に一致させた正本。レイアウトの変形はこの2段でのみ行う）。(2) 上限段=xl（1280。「切替段」ではなく DS が定めるコンテンツ幅の上限段。本番に 1280 の切替段は無い＝1025/1441 はある）。DS 内部はコンテナクエリ @md: / @lg: / @xl:（preset.css の --container-md / --container-lg / --container-xl）で参照し、生 CSS ではこの px 値をメディアクエリに直書きする（CSS 変数はメディアクエリに使えないため、値の配布は本トークンが担う）。独自のブレイクポイント値を発明しない",
+    "comment": "役割は二層。(1) 切替段=md / lg の2つだけ（値は本番 cakejp.css の境界に一致させた正本。レイアウトの変形はこの2段でのみ行う）。(2) 上限段=xl（1280。「切替段」ではなく DS が定めるコンテンツ幅の上限段。本番に 1280 の切替段は無い＝1025/1441 はある）。DS 内部はコンテナクエリ @md: / @lg: / @xl:（preset.css の --container-md / --container-lg / --container-xl）で参照し、生 CSS ではこの px 値をメディアクエリに直書きする（CSS 変数はメディアクエリに使えないため、値の配布は本トークンが担う）。consumer が書くビューポートの md: / lg: / xl: も preset.css の --breakpoint-md / --breakpoint-lg / --breakpoint-xl が同じ段に揃える（Tailwind v4 既定の lg は 1024px で DS の 960px と 64px ずれるため）。値を変えるときは tokens.json と preset.css の --container-* / --breakpoint-* を必ず同時に更新する。独自のブレイクポイント値を発明しない",
     "md": {
       "px": 768,
       "rem": "48rem",
       "container": "--container-md",
+      "viewport": "--breakpoint-md",
       "role": "切替段",
       "usage": "SP/PC 境界。767px 以下=SP / 768px 以上=PC。本番 cakejp.css の max-width:767px / min-width:768px と一致"
     },
@@ -943,6 +957,7 @@
       "px": 960,
       "rem": "60rem",
       "container": "--container-lg",
+      "viewport": "--breakpoint-lg",
       "role": "切替段",
       "usage": "PC 中段。本番 cakejp.css の min-width:960px 段と一致"
     },
@@ -950,6 +965,7 @@
       "px": 1280,
       "rem": "80rem",
       "container": "--container-xl",
+      "viewport": "--breakpoint-xl",
       "role": "上限段",
       "usage": "コンテンツ上限段（切替段ではない）。ページコンテナの標準上限で、1280px 以上では原則レイアウト変形を追加しない。本番 cakejp.css に 1280 の切替段は無い（1025 / 1441 はある）——DS が定める標準上限。実例: MypageShell の PC グリッド max-w-[1280px]"
     }