Seamless Section Waves

When to use

• LP、採用ページ、サービスページなど複数セクションが連続する画面で、波形の区切りや背景色の接続を実装・修正するとき。
• 「セクション境界が硬い」「色が繋がらない」「1px の線が見える」「wave divider を入れたい」「CSS の丸い疑似要素が汚い」と言われたとき。
• 「FVから次をもっと一体化したい」「シームレスにスクロールしたくしたい」と言われ、単なる区切りではなく写真・面・モチーフ・次見出しの受け渡しが必要なとき。
• Tailwind / Next.js / static HTML いずれでも使える。class 名は案件ごとに変えてよいが、色 token と検証ルールは変えない。

Choose the seam mode first

Do not solve every boundary with a wave.

1. repair: remove a hairline, color mismatch, clipping bug, or duplicate divider without changing the art direction.
2. divider: implement a source-visible SVG boundary whose job is separation.
3. art-directed-bridge: answer an explicit request for unity, continuation, or scroll invitation. This mode must compose both sections together and produce seam-continuity/v1 evidence.

For art-directed-bridge, preserve the user's exact words in the parent manifest seam continuity.sourceRef. A generic breathing-space seam or one decorative wave is not an adequate interpretation of that request.

Hard rules

1. Bottom wave の fill は「次セクションの上端の solid color」と完全一致させる。第三の seam 色を作らない。
2. Wave 本体に rgba() や opacity を使わない。半透明 fill は下地と混ざって濁る。
3. CSS border-radius: 50% の ::before / ::after fake wave より SVG を優先する。fake wave は色ズレ、hairline、responsive 崩れが出やすい。
4. Wave は bottom: -1px で 1px 重ね、SVG は左右も 1px ずつ広げる。隙間を blur や shadow で隠さない。
5. 親 section は position: relative とし、wave をクリップしない。overflow: hidden が必要なら装飾用の子要素だけをクリップし、section 自体は overflow-y: visible を維持する。
6. padding-bottom は wave 高さを含める。content を wave の下に潜らせない。
7. 次セクションの最初の 40-80px は wave fill と同じ純色にする。radial、dash、shadow、image、mask を seam 上に置かない。
8. 既存の CSS fake wave と SVG wave を併存させない。古い ::after は content: none まで潰す。
9. art-directed-bridge は最低3層で構成する: target-surface と incoming-preview は必須、さらに outgoing-environment または connective-motif を使う。区切り線1本だけで一体感を表現しない。
10. 境界の不透明面は遷移先が所有する。写真を薄くする haze と、次色を 保証する opaque surface を同じ半透明 path に混ぜない。
11. 大きな曲線は測定した非対称 bezier、freeform path、または画面外に 中心を置いた真円弧を使う。中央対称の山形波や横長楕円を既定解にしない。
12. 次セクションの eyebrow、見出し、写真など最低1つを同じ境界 crop に 見せる。境界だけを綺麗にして次の内容を画面外へ追い出さない。
13. SCROLL cue は境界の意味を補助する場合だけ追加する。主CTAより弱く、 実在する次セクション fragment へ向け、動きは design-motion-sequencing に委譲する。
14. 構造コピー、CTA、人物の顔、次見出しを bridge が覆わないよう zLayer、mustStayBehind、mustNotCover を manifest に記録する。
15. Desktop と mobile の両方で、前セクション末尾と次セクション冒頭が 同時に入る seam crop を保存する。片側しか写らない crop は証拠ではない。

Art-directed four-layer bridge

Use this order as a composition model, not as four mandatory DOM wrappers.

1. outgoing-environment: keep the last meaningful part of the hero/photo visible long enough to retain context. Fade it only where the target surface takes ownership.
2. target-surface: paint one opaque, destination-owned field using the exact next-section color. Its bezier/freeform edge removes the hard horizontal cut.
3. connective-motif: carry one existing visual-language device across the boundary—oversized type, a measured line, numbering, dots, or a restrained accent. Do not invent a new motif family for the seam.
4. incoming-preview: reveal the next eyebrow, heading, portrait, or other narrative anchor inside the same viewport/crop. This is what turns a divider into a hand-off.

Prefer one dominant crest and one secondary shoulder in a bezier. Keep the lowest/highest point away from the exact viewport center unless the source clearly uses symmetry. On mobile, reduce amplitude and re-anchor the cue; do not merely squeeze the desktop path until it becomes an ellipse-like dome.

Recommended stacking topology:

structural hero copy / CTA              z 5+
scroll cue                              z 4–7, but below primary CTA
opaque target surface + connector       z 3–4
oversized cross-boundary watermark      z 2–3
outgoing photo + haze                   z 0–2
incoming structural content             next section flow, above its decoration

The exact integers are local; the ordering and declared occlusion constraints are not.

Token + markup recipe

色は「現在セクション」ではなく「遷移先」を named target にする。

:root {
  --bg-white: #ffffff;
  --bg-paper: #fdfbf6;
  --bg-rice: #f4fbf8;
  --bg-mint: #f3faf7;
  --wave-h: 72px;
}

.wave {
  position: absolute;
  left: 0;
  right: 0;
  bottom: -1px;
  z-index: 5;
  height: var(--wave-h);
  margin: 0;
  padding: 0;
  line-height: 0;
  color: var(--wave-to);
  pointer-events: none;
  overflow: hidden;
}

.wave__svg {
  display: block;
  width: calc(100% + 2px);
  max-width: none;
  height: 100%;
  margin-left: -1px;
}

.wave path {
  fill: currentColor;
}

.wave--to-white { --wave-to: var(--bg-white); }
.wave--to-paper { --wave-to: var(--bg-paper); }
.wave--to-rice { --wave-to: var(--bg-rice); }
.wave--to-mint { --wave-to: var(--bg-mint); }

.has-wave {
  position: relative;
  padding-bottom: calc(var(--wave-h) + 24px);
  margin-bottom: 0;
  overflow: visible;
}

.has-wave.needs-x-clip {
  overflow-x: clip;
  overflow-y: visible;
}

<section class="section section--paper has-wave">
  <div class="container">
    <!-- content -->
  </div>
  <div class="wave wave--to-rice" aria-hidden="true">
    <svg class="wave__svg" viewBox="0 0 1440 80" preserveAspectRatio="none" focusable="false">
      <path d="M0 80V38c120-26 240 22 360 10s240-44 360-28 240 40 360 30 240-36 360-18v48H0z" />
    </svg>
  </div>
</section>

<section class="section section--rice">
  <div class="container">
    <!-- next content -->
  </div>
</section>

Tailwind mapping tips:

• relative, pb-[calc(var(--wave-h)+24px)], overflow-visible, pointer-events-none, absolute inset-x-0 -bottom-px, h-[var(--wave-h)] で組む。
• Arbitrary values は wave 基盤だけに閉じる。背景色は Tailwind 色名に寄せず、CSS variables / design tokens で exact hex を共有する。
• React component 化する場合は <SectionWave to="rice" /> のように destination token だけを渡す。current section 名を渡さない。

Bridge patterns

Mid CTA continuous gradient:

.mid-cta {
  position: relative;
  padding: 56px 0;
  background: linear-gradient(
    180deg,
    var(--bg-paper) 0%,
    var(--bg-rice) 48%,
    var(--bg-mint) 100%
  );
  border: 0;
}

.mid-cta__inner {
  position: relative;
  z-index: 1;
  padding: 28px 32px;
  border-radius: 24px;
  background: rgba(255, 255, 255, 0.55);
  box-shadow: 0 18px 48px rgba(15, 63, 71, 0.06);
  backdrop-filter: blur(6px);
}

• CTA strip を横一面の黄色・teal・accent 色にしない。前セクション solid から中間色を通り、次セクション solid へ縦に接続する。
• CTA の上に入る前セクション bottom wave は --to-paper など CTA 上端色へ、CTA 自身の bottom wave は次セクション上端色へ向ける。

White to mint fade:

.effects-before-service {
  background: linear-gradient(
    180deg,
    var(--bg-white) 0%,
    var(--bg-white) 62%,
    var(--bg-rice) 100%
  );
}

.service {
  background:
    radial-gradient(520px 340px at 8% 42%, rgba(167, 224, 222, 0.18), transparent 70%),
    var(--bg-rice);
}

.service::before {
  top: 220px; /* keep decoration away from seam */
}

• 白から mint など大きい色差へ移るときは、前セクション下部を次色へ寄せてから wave を重ねる。
• 次セクション上端は必ず pure solid。装飾は seam から 40-80px 以上離す。

Verification checklist

• Pixel sample: boundary の同じ x 座標で、wave fill 内の y - 8px と次セクション上端の y + 8px を RGB sampling する。両方が destination token hex と一致すること。AA 許容は各 channel ±1 まで。
• getComputedStyle(wave).color と次セクションの top solid token が一致しているか確認する。
• 親 .has-wave が position: relative、padding-bottom >= wave height、overflow-y: visible になっているか確認する。
• SVG が preserveAspectRatio="none"、display:block、width: calc(100% + 2px)、margin-left:-1px になっているか確認する。
• 古い section::after / section::before fake wave、border-block、1px border、divider shadow が残っていないか rg "::after|::before|border-block|border-top|border-bottom" で確認する。
• Screenshot で見るだけで終えない。境界の色ズレは pixel sample で判定する。
• art-directed-bridge crop は、前セクションの意味のある末尾と次セクションの eyebrow/見出し/写真を同時に含む。境界の上下5pxだけを切り出さない。
• Desktop と mobile の双方で、bridge path、connective motif、incoming preview が残り、構造コピーや人物の顔を覆っていないことを確認する。
• scripts/check_seam_pixels.py で opaque bridge と next-section solid の sample を同じ destination hex に照合し、seam-pixel-check/v1 JSON を保存する。

SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
"$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
  "$SKILL_ROOT/seamless-section-waves/scripts/check_seam_pixels.py" \
  reports/seams/hero-next.png \
  --from-section hero-section --to-section next-section \
  --expected '#fcfbf4' \
  --sample bridge-fill:100,899 --sample next-surface:100,909 \
  --out reports/seams/hero-next-color.json

seam-continuity/v1 report contract

art-directed-bridge produces one hash-bound report for the parent mockup-to-code manifest as specialistReports.seamContinuity.

{
  "schemaVersion": "seam-continuity/v1",
  "status": "ready",
  "sourceRef": {"path": "reports/seam-source.txt", "quote": "シームレスにスクロールしたくなる"},
  "seams": [{
    "from": "hero-section",
    "to": "next-section",
    "surfaceOwner": "to-section",
    "geometryPrimitive": "bezier",
    "layers": ["outgoing-environment", "target-surface", "connective-motif", "incoming-preview"],
    "previewTargets": ["next.title"],
    "cueTarget": "hero.scrollCue",
    "desktopEvidencePath": "reports/seams/hero-next.png",
    "mobileEvidencePath": "reports/seams/hero-next-mobile.png",
    "colorSampleReport": "reports/seams/hero-next-color.json"
  }]
}

Use status: ready before CSS after the source quote, layer plan, geometry, preview target, and planned evidence paths are fixed. Change to status: pass only after both crops and the passing pixel report exist. Do not mark the report pass from CSS inspection alone.

Failure modes

Worked pattern checklist

Apply these patterns to the current project rather than depending on an external example checkout:

• .hh-wave, .hh-wave--to-*, --hh-wave-to, --hh-bg-*
• .has-wave padding and overflow rules
• Mid CTA vertical bridge gradient
• Effects -> Service fade, with Service top kept pure rice
• Removed CSS-only ::after fake waves that used wrong seam colors