@charcoal-ui/react 6.0.0-rc.3 → 6.0.0-rc.5

package/src/__tests__/token-v1-compat.test.ts

@@ -6,7 +6,7 @@ import postcss, { type Rule } from 'postcss'
 // Design Token 1.0互換モードの「見た目の非破壊」を検証する。
 //
 // 移行: 旧 `@charcoal-ui/react/dist/index.css` (v1, --charcoal-* を直接使用)
-//   →  新 コンポーネントCSS (v2, --charcoal-color-* を使用) + `_token_v1.css` remap
+//   →  新 コンポーネントCSS (v2, --charcoal-color-* を使用) + `v1/remap.css` remap
 //
 // 非破壊であるためには、各 (セレクタ, プロパティ) で新CSSが使う 1つの --charcoal-color-*
 // が、旧CSSで使われていた「単一の」--charcoal-* に対応していなければならない。同じ新トークンが
@@ -99,7 +99,6 @@ describe('Design Token 1.0互換: 旧 index.css の見た目を壊さない', ()
           - .charcoal-button | color → --charcoal-text2
           - .charcoal-checkbox__label_div | color → --charcoal-text2
           - .charcoal-ui-dropdown-selector-text | color → --charcoal-text2
-          - .charcoal-field-label | color → --charcoal-text1
           - .charcoal-modal-header-title | color → --charcoal-text1
           - .charcoal-multi-select-label | color → --charcoal-text2
           - .charcoal-radio__label_div | color → --charcoal-text2

package/src/__tests__/token-v1-remap.test.ts

@@ -3,9 +3,9 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import postcss from 'postcss'
 
-// Design Token 1.0互換モード (`@charcoal-ui/theme/css/_token_v1.css`) の remap を検証する。
+// Design Token 1.0互換モード (`@charcoal-ui/theme/css/v1/remap.css`) の remap を検証する。
 //
-// アプリは 1.0互換 (`_token_v1.css`) か 2.0 (`_variables_*.css`) のいずれかで --charcoal-color-*
+// アプリは 1.0互換 (`v1/remap.css`) か 2.0 (`v2/{light,dark}.css`) のいずれかで --charcoal-color-*
 // を供給し、コンポーネント実装CSS (`@charcoal-ui/react`) がそれを消費する。remap が
 // 「壊さない・冗長でない・正しい」ことを次で担保する:
 //   1. 非破壊: コンポーネントが使う --charcoal-color-* は全て remap 経由で解決できる。
@@ -13,8 +13,8 @@ import postcss from 'postcss'
 //   3. 冗長でない: 2.0 API にも無く・内部参照も無く・コンポーネントも使わないトークンを持たない。
 
 const cssDir = path.resolve(import.meta.dirname, '../../../theme/src/css')
-const tokenV1Path = path.join(cssDir, '_token_v1.css')
-const variables2Path = path.join(cssDir, '_variables_light.css')
+const tokenV1Path = path.join(cssDir, 'v1/remap.css')
+const variables2Path = path.join(cssDir, 'v2/light.css')
 const componentsDir = path.resolve(import.meta.dirname, '../components')
 
 const COLOR_PREFIX = '--charcoal-color-'
@@ -89,7 +89,7 @@ for (const file of componentCssFiles) {
     componentUsed.add(v)
 }
 
-describe('Design Token 1.0互換 (_token_v1.css) remap', () => {
+describe('Design Token 1.0互換 (v1/remap.css) remap', () => {
   it('重複定義がない', () => {
     expect(duplicates).toEqual([])
   })
@@ -119,7 +119,7 @@ describe('Design Token 1.0互換 (_token_v1.css) remap', () => {
   })
 
   it.each(componentCssFiles)(
-    '%s: 使用する --charcoal-color-* は全て _token_v1.css 経由で解決する (非破壊)',
+    '%s: 使用する --charcoal-color-* は全て v1/remap.css 経由で解決する (非破壊)',
     async (file) => {
       const css = await fs.readFile(file, 'utf-8')
       const unresolved = [...usedColorVars(css)]

package/src/_lib/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,7 @@
+import { useEffect, useLayoutEffect } from 'react'
+
+/**
+ * SSR では useLayoutEffect が警告を出すため、サーバーでは useEffect にフォールバックする
+ */
+export const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect

package/src/components/Carousel/MIGRATION.md

@@ -5,7 +5,9 @@
 
 ## 移行の要点
 
-- **import 差し替え + `children` → `items` がほぼ唯一の必須変更**。
+- **import 差し替えがほぼ唯一の必須変更**。`children` はそのまま渡せる（ただし自前の
+  `flex` ラッパーは外して **1 スライド 1 直接子要素**にし、ラッパーの `gap` は
+  各スライドの `margin` に置き換える）。
 - `onScroll` / `onResize` / `onScrollStateChange` / `ref`（`resetScroll()`）/ `defaultScroll` /
   `hasGradient` は **sandbox と同じシグネチャ**で利用できる（drop-in 互換）。
 - `scrollAmountCoef` は `scrollStep`（関数も可）に名称変更。`fadeInGradient` / `buttonOffset` 系 /
@@ -17,7 +19,7 @@
 |                | sandbox (`@charcoal-ui/react-sandbox`) | react (`@charcoal-ui/react`)                    |
 | -------------- | -------------------------------------- | ----------------------------------------------- |
 | スクロール     | react-spring による JS アニメーション  | ネイティブ overflow + CSS `scroll-snap`         |
-| 子要素         | `children`（任意のノード）             | `items: { id; children }[]`                     |
+| 子要素         | `children`（任意のノード）             | `children`（1 直接子要素 = 1 スライド）         |
 | インジケーター | なし                                   | CSS `::scroll-marker` / JS フォールバックの dot |
 | スタイル       | styled-components                      | プレーン CSS（`index.css`）                     |
 
@@ -28,14 +30,15 @@
 + import { Carousel } from '@charcoal-ui/react'
 ```
 
-公開型: `CarouselProps` / `CarouselItem` / `CarouselHandlerRef` / `ScrollAlign` / `ScrollStep` /
+公開型: `CarouselProps` / `CarouselHandlerRef` / `ScrollAlign` / `ScrollStep` /
 `ScrollStepContext` / `ScrollSnap` / `ScrollSnapType` / `ScrollSnapAlign`。
 
-## 子要素: `children` → `items`
+## 子要素: `children`（そのまま渡せる）
 
-最大の変更点。子ノードを直接渡す形から、`id` 付きの配列に変える。
-sandbox では自前で `flex` ラッパーや `gap` を組んでいたが、新版はレイアウト（`gap: 24px`、S は `0`）を
-コンポーネント側 CSS が持つので、**ラッパーで囲まず 1 スライド 1 要素**で渡す。
+sandbox と同じく子ノードを直接渡し、スライドの寸法・間隔も sandbox 同様に利用者が持つ
+（コンポーネントの責務はスクロールと indicator / arrow によるページ送りのみ）。
+ただし**直接子要素 1 つを 1 スライド**として数えるので、`flex` ラッパーは外し、
+`gap` の代わりに各スライドの `margin` などで間隔を注入する。
 
 ```diff
 - <Carousel hasGradient defaultScroll={{ align: 'center' }} scrollAmountCoef={0.75}>
@@ -45,38 +48,36 @@ sandbox では自前で `flex` ラッパーや `gap` を組んでいたが、新
 -     ))}
 -   </div>
 - </Carousel>
-+ <Carousel
-+   size="M"
-+   hasGradient
-+   defaultScroll={{ align: 'center' }}
-+   scrollStep={0.75}
-+   items={items.map((i) => ({ id: String(i), children: <Slide /> }))}
-+ />
++ <Carousel hasGradient defaultScroll={{ align: 'center' }} scrollStep={0.75}>
++   {items.map((i) => (
++     <Slide key={i} style={{ marginInlineEnd: 8 }} />
++   ))}
++ </Carousel>
 ```
 
-`id` はキー安定化（再レンダー・スクロール命令の宛先識別）に使うので、配列内で一意かつ安定した値にする。
+`key` は再レンダー時のスライド識別に使うので、一意かつ安定した値にする。
 
 ## props 対応表
 
-| sandbox                                           | react                                          | 備考                                                                                                      |
-| ------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `children`                                        | `items: { id: string; children: ReactNode }[]` | 上記参照                                                                                                  |
-| `scrollAmountCoef`（既定 `0.75`）                 | `scrollStep`（既定 `0.75`）                    | `number`（表示幅比）に加え `(ctx) => px` の関数も渡せる                                                   |
-| `defaultScroll: { align, offset }`                | `defaultScroll: { align, offset }`             | `align` は `'left' \| 'center' \| 'right'`。ほぼ同等                                                      |
-| `hasGradient`                                     | `hasGradient`（既定 `false`）                  | 実装が mask → 背景色オーバーレイに変更                                                                    |
-| `fadeInGradient`                                  | （廃止）                                       | 常にオーバーレイ式フェード                                                                                |
-| `buttonOffset` / `buttonPadding` / `bottomOffset` | （廃止）                                       | ボタン配置は CSS グリッド（左右 72px ゾーン）に固定                                                       |
-| `centerItems`                                     | （廃止）                                       | レイアウトは `flex` + `gap` 固定                                                                          |
-| `onScroll(left)`                                  | `onScroll(left)`                               | ✅ そのまま対応（scroll で発火）                                                                          |
-| `onResize(width)`                                 | `onResize(width)`                              | ✅ scroller 幅の変化で発火                                                                                |
-| `onScrollStateChange(canScroll)`                  | `onScrollStateChange(canScroll)`               | ✅ `canPrev \|\| canNext` の変化で発火                                                                    |
-| `ref`（`CarouselHandlerRef.resetScroll()`）       | `ref`（`CarouselHandlerRef.resetScroll()`）    | ✅ `forwardRef` で対応。`defaultScroll` の初期位置へ戻す                                                  |
-| —                                                 | `size: 'S' \| 'M'`（既定 `'M'`）               | 新規。`S` は 1 枚全幅 + `mandatory` スナップ                                                              |
-| —                                                 | `navigationButtons?: boolean`                  | 既定は `size === 'M'`                                                                                     |
-| —                                                 | `indicator?: boolean`                          | 既定は `size === 'S'`                                                                                     |
-| —                                                 | `fullWidth?: boolean`（既定 `false`）          | `100vw` 表示                                                                                              |
-| —                                                 | `className?: string`                           | ルートに付与                                                                                              |
-| —                                                 | `scrollSnap?: { type?; align? }`               | `type`: `none`/`proximity`/`mandatory`、`align`: `center`/`start`。未指定で M=none / S=mandatory / center |
+| sandbox                                           | react                                       | 備考                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `children`                                        | `children`                                  | ✅ そのまま対応（1 直接子要素 = 1 スライド。ラッパーは外す。上記参照）                                    |
+| `scrollAmountCoef`（既定 `0.75`）                 | `scrollStep`（既定 `0.75`）                 | `number`（表示幅比）に加え `(ctx) => px` の関数も渡せる                                                   |
+| `defaultScroll: { align, offset }`                | `defaultScroll: { align, offset }`          | `align` は `'left' \| 'center' \| 'right'`。ほぼ同等                                                      |
+| `hasGradient`                                     | `hasGradient`（既定 `false`）               | ✅ そのまま対応（mask による透過フェード）                                                                |
+| `fadeInGradient`                                  | （廃止）                                    | スクロール可能な側のみ常にフェード                                                                        |
+| `buttonOffset` / `buttonPadding` / `bottomOffset` | （廃止）                                    | ボタン配置は CSS グリッド（左右 72px ゾーン）に固定                                                       |
+| `centerItems`                                     | （廃止）                                    | スライドの寸法・間隔は children 側で注入する（sandbox 同様）                                              |
+| `onScroll(left)`                                  | `onScroll(left)`                            | ✅ そのまま対応（scroll で発火）                                                                          |
+| `onResize(width)`                                 | `onResize(width)`                           | ✅ scroller 幅の変化で発火                                                                                |
+| `onScrollStateChange(canScroll)`                  | `onScrollStateChange(canScroll)`            | ✅ `canPrev \|\| canNext` の変化で発火                                                                    |
+| `ref`（`CarouselHandlerRef.resetScroll()`）       | `ref`（`CarouselHandlerRef.resetScroll()`） | ✅ `forwardRef` で対応。`defaultScroll` の初期位置へ戻す                                                  |
+| —                                                 | `size: 'S' \| 'M'`（既定 `'M'`）            | 新規。`S` は 1 枚全幅 + `mandatory` スナップ                                                              |
+| —                                                 | `navigationButtons?: boolean`               | 既定は `size === 'M'`                                                                                     |
+| —                                                 | `indicator?: boolean`                       | 既定は `size === 'S'`                                                                                     |
+| —                                                 | `fullWidth?: boolean`（既定 `false`）       | `100vw` 表示                                                                                              |
+| —                                                 | `className?: string`                        | ルートに付与                                                                                              |
+| —                                                 | `scrollSnap?: { type?; align? }`            | `type`: `none`/`proximity`/`mandatory`、`align`: `center`/`start`。未指定で M=none / S=mandatory / center |
 
 ## 挙動の変更（移行時に確認すること）
 
@@ -92,8 +93,6 @@ sandbox では自前で `flex` ラッパーや `gap` を組んでいたが、新
   非対応環境では JS フォールバック）。
 - **キーボード操作**: スクローラーが `tabIndex={0}` でフォーカス可能になり、`←` / `→` で 1 ステップスクロール。
   フォーカスリングは charcoal 標準（`box-shadow: 0 0 0 4px rgba(0, 150, 250, 0.32)`）。
-- **グラデーション**: `mask` による透過から、背景色（`#fff`）オーバーレイ方式に変更。
-  ダークモードは現状未対応（背景色固定）。
 
 ## スクロール量を細かく制御したい場合
 
@@ -101,17 +100,18 @@ sandbox では自前で `flex` ラッパーや `gap` を組んでいたが、新
 
 ```tsx
 // 表示幅の比率（sandbox の scrollAmountCoef 相当）
-<Carousel items={items} scrollStep={0.5} />
+<Carousel scrollStep={0.5}>{slides}</Carousel>
 
 // 進む px を直接返す（端は残り全部、など）
 <Carousel
-  items={items}
   scrollStep={({ clientWidth, scrollWidth, scrollLeft, direction }) =>
     direction === 'next'
       ? Math.min(clientWidth * 0.8, scrollWidth - clientWidth - scrollLeft)
       : Math.min(clientWidth * 0.8, scrollLeft)
   }
-/>
+>
+  {slides}
+</Carousel>
 ```
 
 戻り値は「進む量の絶対値（px）」。符号（prev / next）はコンポーネント側で付与する。

package/src/components/Carousel/__snapshots__/index.css.snap

@@ -12,10 +12,19 @@
   position: relative;
 }
 
+/* フォーカスリングは scroller ではなく viewport に描く。scroller に置くと
+     hasGradient の mask（mask-clip: border-box）で外側の box-shadow ごと消えるため。 */
+
+.charcoal-carousel__viewport[data-focus-visible] {
+  box-shadow: 0 0 0 4px rgba(0, 150, 250, 0.32);
+}
+
+/* スライド間隔は所有しない（sandbox 同様、利用者が children 側で注入する）。
+   このコンポーネントの責務はスクロールと indicator / arrow によるページ送りのみ。 */
+
 .charcoal-carousel__scroller {
   position: relative;
   display: flex;
-  gap: 24px;
   overflow-x: auto;
   overflow-y: hidden;
   overscroll-behavior-x: contain;
@@ -28,14 +37,6 @@
   display: none;
 }
 
-.charcoal-carousel__scroller[data-focus-visible] {
-  box-shadow: 0 0 0 4px rgba(0, 150, 250, 0.32);
-}
-
-.charcoal-carousel[data-size='S'] .charcoal-carousel__scroller {
-  gap: 0;
-}
-
 /* スクロールスナップ type は prop（scrollSnap.type）で scroller に出し分ける。
    align は基底 .charcoal-carousel__item の後（後述）に置く（no-descending-specificity 回避）。
    未指定時の既定（M=none / S=mandatory / align=center）は JS 側で data 属性に解決する。 */
@@ -52,38 +53,39 @@
   scroll-snap-type: x mandatory;
 }
 
-/* グラデーション: はみ出してスクロール可能な側のみ、端のアイテムを背景色（白）へ
-   フェードさせる。mask による透過ではなく、72px の「背景色→透明」オーバーレイを
-   ビューポートに重ねて白で覆う。スクロール可能な側だけ data-can-prev/next で出し分ける。 */
+/* グラデーション: mask で端のアイテム自体を透明へフェードさせる（下の背景色を
+   問わない）。mask の色はアルファとしてだけ効く（#000=表示 / transparent=透過）。
+   左フェード・右フェードの 2 レイヤーを intersect で合成し、はみ出して
+   スクロール可能な側のみ data-can-prev/next で 72px のフェード帯を枠内に置く。
+   無効な側はフェード帯ごと枠外へスライドして隠す（mask-image と違い
+   mask-position は補間可能なので、切替が 0.2s のフェードになる）。 */
 
-.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::before, .charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::after {
-  content: '';
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  width: 72px;
-  pointer-events: none;
-  opacity: 0;
-  transition: 0.2s opacity;
-  z-index: 1;
+.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__scroller {
+  mask-image: linear-gradient(to right, transparent, #000 72px),
+    linear-gradient(to left, transparent, #000 72px);
+  /* 枠外へ 72px スライドしても反対側の端が欠けないよう、レイヤー幅に 72px 足す */
+  mask-size: calc(100% + 72px) 100%;
+  mask-repeat: no-repeat;
+  mask-composite: intersect;
+  mask-position: -72px 0,
+    0 0;
+  /* 0.2s ease-in は react-sandbox の LeftGradient と同じ値 */
+  transition: 0.2s ease-in mask-position;
 }
 
-.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::before {
-  left: 0;
-  background: linear-gradient(to right, #fff, transparent);
+.charcoal-carousel[data-has-gradient='true'][data-can-prev='true'] .charcoal-carousel__scroller {
+  mask-position: 0 0,
+    0 0;
 }
 
-.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::after {
-  right: 0;
-  background: linear-gradient(to left, #fff, transparent);
+.charcoal-carousel[data-has-gradient='true'][data-can-next='true'] .charcoal-carousel__scroller {
+  mask-position: -72px 0,
+    -72px 0;
 }
 
-.charcoal-carousel[data-has-gradient='true'][data-can-prev='true'] .charcoal-carousel__viewport::before {
-  opacity: 1;
-}
-
-.charcoal-carousel[data-has-gradient='true'][data-can-next='true'] .charcoal-carousel__viewport::after {
-  opacity: 1;
+.charcoal-carousel[data-has-gradient='true'][data-can-prev='true'][data-can-next='true'] .charcoal-carousel__scroller {
+  mask-position: 0 0,
+    -72px 0;
 }
 
 .charcoal-carousel__item {
@@ -108,7 +110,7 @@
 
 /* ── Navigation Buttons (charcoal IconButton, variant=Overlay size=S) ── */
 
-/* マスクと同じ 72px 1fr 72px グリッド。各ボタンは 72px ゾーンの中央に置く。 */
+/* マスクの透過域と同じ 72px 1fr 72px グリッド。各ボタンは 72px ゾーンの中央に置く。 */
 
 .charcoal-carousel__navigation {
   position: absolute;
@@ -117,8 +119,8 @@
   display: grid;
   grid-template-columns: 72px 1fr 72px;
   align-items: center;
-  /* 白フェード（z-index: 1）より上にボタンを表示する */
-  z-index: 2;
+  /* アイテム内のコンテンツより上にボタンを表示する */
+  z-index: 1;
   /* sandbox 同様、通常は隠してカルーセル hover 時にフェードイン表示する。 */
   opacity: 0;
   transition: 0.4s opacity;

package/src/components/Carousel/index.css

@@ -10,12 +10,19 @@
 
 .charcoal-carousel__viewport {
   position: relative;
+
+  /* フォーカスリングは scroller ではなく viewport に描く。scroller に置くと
+     hasGradient の mask（mask-clip: border-box）で外側の box-shadow ごと消えるため。 */
+  &[data-focus-visible] {
+    box-shadow: 0 0 0 4px rgba(0, 150, 250, 0.32);
+  }
 }
 
+/* スライド間隔は所有しない（sandbox 同様、利用者が children 側で注入する）。
+   このコンポーネントの責務はスクロールと indicator / arrow によるページ送りのみ。 */
 .charcoal-carousel__scroller {
   position: relative;
   display: flex;
-  gap: 24px;
   overflow-x: auto;
   overflow-y: hidden;
   overscroll-behavior-x: contain;
@@ -26,14 +33,6 @@
   &::-webkit-scrollbar {
     display: none;
   }
-
-  &[data-focus-visible] {
-    box-shadow: 0 0 0 4px rgba(0, 150, 250, 0.32);
-  }
-}
-
-.charcoal-carousel[data-size='S'] .charcoal-carousel__scroller {
-  gap: 0;
 }
 
 /* スクロールスナップ type は prop（scrollSnap.type）で scroller に出し分ける。
@@ -53,44 +52,46 @@
   scroll-snap-type: x mandatory;
 }
 
-/* グラデーション: はみ出してスクロール可能な側のみ、端のアイテムを背景色（白）へ
-   フェードさせる。mask による透過ではなく、72px の「背景色→透明」オーバーレイを
-   ビューポートに重ねて白で覆う。スクロール可能な側だけ data-can-prev/next で出し分ける。 */
-.charcoal-carousel[data-has-gradient='true']
-  .charcoal-carousel__viewport::before,
-.charcoal-carousel[data-has-gradient='true']
-  .charcoal-carousel__viewport::after {
-  content: '';
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  width: 72px;
-  pointer-events: none;
-  opacity: 0;
-  transition: 0.2s opacity;
-  z-index: 1;
-}
-
-.charcoal-carousel[data-has-gradient='true']
-  .charcoal-carousel__viewport::before {
-  left: 0;
-  background: linear-gradient(to right, #fff, transparent);
-}
-
-.charcoal-carousel[data-has-gradient='true']
-  .charcoal-carousel__viewport::after {
-  right: 0;
-  background: linear-gradient(to left, #fff, transparent);
+/* グラデーション: mask で端のアイテム自体を透明へフェードさせる（下の背景色を
+   問わない）。mask の色はアルファとしてだけ効く（#000=表示 / transparent=透過）。
+   左フェード・右フェードの 2 レイヤーを intersect で合成し、はみ出して
+   スクロール可能な側のみ data-can-prev/next で 72px のフェード帯を枠内に置く。
+   無効な側はフェード帯ごと枠外へスライドして隠す（mask-image と違い
+   mask-position は補間可能なので、切替が 0.2s のフェードになる）。 */
+.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__scroller {
+  mask-image:
+    linear-gradient(to right, transparent, #000 72px),
+    linear-gradient(to left, transparent, #000 72px);
+  /* 枠外へ 72px スライドしても反対側の端が欠けないよう、レイヤー幅に 72px 足す */
+  mask-size: calc(100% + 72px) 100%;
+  mask-repeat: no-repeat;
+  mask-composite: intersect;
+  mask-position:
+    -72px 0,
+    0 0;
+  /* 0.2s ease-in は react-sandbox の LeftGradient と同じ値 */
+  transition: 0.2s ease-in mask-position;
 }
 
 .charcoal-carousel[data-has-gradient='true'][data-can-prev='true']
-  .charcoal-carousel__viewport::before {
-  opacity: 1;
+  .charcoal-carousel__scroller {
+  mask-position:
+    0 0,
+    0 0;
 }
 
 .charcoal-carousel[data-has-gradient='true'][data-can-next='true']
-  .charcoal-carousel__viewport::after {
-  opacity: 1;
+  .charcoal-carousel__scroller {
+  mask-position:
+    -72px 0,
+    -72px 0;
+}
+
+.charcoal-carousel[data-has-gradient='true'][data-can-prev='true'][data-can-next='true']
+  .charcoal-carousel__scroller {
+  mask-position:
+    0 0,
+    -72px 0;
 }
 
 .charcoal-carousel__item {
@@ -114,7 +115,7 @@
 
 /* ── Navigation Buttons (charcoal IconButton, variant=Overlay size=S) ── */
 
-/* マスクと同じ 72px 1fr 72px グリッド。各ボタンは 72px ゾーンの中央に置く。 */
+/* マスクの透過域と同じ 72px 1fr 72px グリッド。各ボタンは 72px ゾーンの中央に置く。 */
 .charcoal-carousel__navigation {
   position: absolute;
   inset: 0;
@@ -122,8 +123,8 @@
   display: grid;
   grid-template-columns: 72px 1fr 72px;
   align-items: center;
-  /* 白フェード（z-index: 1）より上にボタンを表示する */
-  z-index: 2;
+  /* アイテム内のコンテンツより上にボタンを表示する */
+  z-index: 1;
   /* sandbox 同様、通常は隠してカルーセル hover 時にフェードイン表示する。 */
   opacity: 0;
   transition: 0.4s opacity;