@conscience-technology/ctds 0.0.0-stage → 0.1.0

package/assets/components/Onboarding/OnboardingPage.tsx

@@ -0,0 +1,1193 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { Badge } from "../Badge";
+import { Button } from "../Button";
+import { Icon } from "../Icon";
+import { FilterButton } from "../FilterButton";
+import { Input } from "../Input";
+import { SelectableCard } from "../SelectableCard";
+import { Slider } from "../Slider";
+import { Stepper } from "../Stepper";
+import { hexToOklch, isValidHex } from "../_color";
+import { palettePresets, type PaletteValue } from "../_data";
+import { useTheme } from "../ThemeController";
+import { OnboardingAxisPanel } from "./OnboardingAxisPanel";
+import { applyOnboarding, checkExistingFiles } from "./actions";
+import { PresetsGallery } from "./PresetsGallery";
+import { LayoutBuilder } from "./LayoutBuilder";
+import { DocsIndex } from "./DocsIndex";
+import {
+  DENSITY_CHOICES,
+  LAYOUT_CHOICES,
+  PALETTE_CHOICES,
+  THEME_CHOICES,
+  THEME_PRESETS,
+  THEME_VIBE_FALLBACK,
+  VIBE_CHOICES,
+  type DensityChoiceId,
+  type LayoutId,
+  type ThemeId,
+  type VibeId,
+} from "./wizardData";
+import styles from "./Onboarding.module.css";
+import "./palette.css";
+
+type StepKey = "theme" | "vibe" | "color" | "density" | "layout" | "summary";
+
+type Answers = {
+  theme: ThemeId | null;
+  vibe: VibeId | null;
+  palette: PaletteValue | null;
+  hue: number | null;
+  hueSource: "preset" | "hex" | null;
+  brandHex: string;
+  density: DensityChoiceId | null;
+  layout: LayoutId | null;
+};
+
+const STEPS: { key: StepKey; title: string; hint: string }[] = [
+  { key: "theme", title: "디자인 스타일", hint: "시작 번들. 축 디폴트 + DESIGN.md가 함께 적용." },
+  { key: "vibe", title: "프로덕트 분위기", hint: "코너 · 모션 · 강조색이 세트로 결정." },
+  { key: "density", title: "정보 밀도", hint: "한 화면에 얼마나 빽빽하게 담을지." },
+  { key: "color", title: "컬러 & 톤", hint: "팔레트 선택 + 브랜드 색." },
+  { key: "layout", title: "레이아웃", hint: "사이드바 · 탑바 조합." },
+  { key: "summary", title: "요약 & 적용", hint: "선택을 확인하고 프로젝트에 반영." },
+];
+
+export function OnboardingPage() {
+  const {
+    setShape,
+    setMotionMode,
+    setPalette,
+    setHue,
+    setDensity,
+    applyPreset,
+    voice,
+    focusRing,
+  } = useTheme();
+  const [mode, setMode] = useState<"wizard" | "free">("wizard");
+  const [stepIdx, setStepIdx] = useState(0);
+  /** 적용 확인 다이얼로그 상태. 적용 진행 중/완료/실패까지 담는다.
+   *  confirm 단계에서 existing(이미 있는 파일 목록)이 비어있지 않으면 "덮어쓸래?" 플로우. */
+  const [applyState, setApplyState] = useState<
+    | { phase: "idle" }
+    | { phase: "confirm"; existing: string[] }
+    | { phase: "applying" }
+    | { phase: "done"; files: string[] }
+    | { phase: "error"; message: string; files: string[] }
+  >({ phase: "idle" });
+  const [answers, setAnswers] = useState<Answers>({
+    theme: "none",
+    vibe: "balanced",
+    palette: "standard",
+    hue: 210,
+    hueSource: "preset",
+    brandHex: "",
+    density: "default",
+    layout: "topbar-sidebar",
+  });
+
+  const applyTheme = (t: ThemeId) => {
+    setAnswers((a) => ({ ...a, theme: t }));
+    // "none" 은 이후 축을 사용자가 직접 선택.
+    // pure/spare/expressive는 prompts/themes/<slug>.md의 Preset을 자동 매핑하고
+    // vibe/density도 테마가 커버하므로 answers에 미리 세팅 → vibe 단계 skip 가능.
+    if (t === "none") return;
+    const preset = THEME_PRESETS[t];
+    const vibeFallback = THEME_VIBE_FALLBACK[t];
+    applyPreset(preset);
+    setAnswers((a) => ({
+      ...a,
+      theme: t,
+      vibe: vibeFallback,
+      density: preset.density,
+    }));
+  };
+
+  const applyVibe = (v: VibeId) => {
+    const c = VIBE_CHOICES.find((x) => x.id === v);
+    if (!c) return;
+    setShape(c.values.shape);
+    setMotionMode(c.values.motion);
+    // serious vibe는 palette=mono를 승계.
+    if (c.values.palette) {
+      setPalette(c.values.palette);
+      setAnswers((a) => ({ ...a, vibe: v, palette: c.values.palette! }));
+      return;
+    }
+    setAnswers((a) => ({ ...a, vibe: v }));
+  };
+  const applyPalette = (v: PaletteValue) => {
+    setPalette(v);
+    setAnswers((a) => ({ ...a, palette: v }));
+  };
+  const applyHue = (h: number) => {
+    setHue(h);
+    setAnswers((a) => ({ ...a, hue: h, hueSource: "preset", brandHex: "" }));
+  };
+  /**
+   * hex 입력 시 그 색을 그대로 재현.
+   * 축이 L/C는 palette preset에서, hue는 slider에서 오므로 L/C에 가장 가까운
+   * preset을 매칭하고 base hue를 preset.hueShift만큼 역보정한다.
+   * 결과 oklch(L_preset, C_preset, baseHue + hueShift)가 입력 hex와 가장 근접.
+   */
+  const applyBrandHex = (hex: string) => {
+    const trimmed = hex.trim();
+    if (!trimmed) {
+      // hex 비우기 — 수동 모드 복귀. 축은 그대로 두고 answers만 정리.
+      setAnswers((a) => ({ ...a, brandHex: "", hueSource: "preset" }));
+      return;
+    }
+    if (!isValidHex(trimmed)) {
+      setAnswers((a) => ({ ...a, brandHex: trimmed }));
+      return;
+    }
+    const oklch = hexToOklch(trimmed);
+    if (!oklch) {
+      setAnswers((a) => ({ ...a, brandHex: trimmed }));
+      return;
+    }
+    // L/C 평면에서 가장 가까운 preset (chroma 가중치 ↑ — chroma가 톤 성격을 더 좌우)
+    const nearest = palettePresets.reduce((best, p) => {
+      const d =
+        (p.lightness - oklch.l) ** 2 + ((p.chroma - oklch.c) * 2) ** 2;
+      const bestD =
+        (best.lightness - oklch.l) ** 2 + ((best.chroma - oklch.c) * 2) ** 2;
+      return d < bestD ? p : best;
+    }, palettePresets[0]);
+    const baseHue = ((Math.round(oklch.h - nearest.hueShift) % 360) + 360) % 360;
+    setPalette(nearest.id);
+    setHue(baseHue);
+    setAnswers((a) => ({
+      ...a,
+      brandHex: trimmed,
+      palette: nearest.id,
+      hue: baseHue,
+      hueSource: "hex",
+    }));
+  };
+  const applyDensity = (v: DensityChoiceId) => {
+    setDensity(v);
+    setAnswers((a) => ({ ...a, density: v }));
+  };
+
+  /** 적용 흐름: 1) 확인 다이얼로그 open (기존 파일 조회) → 2) 사용자 확인 → 3) 미리보기 적용 + 파일 쓰기 */
+  const openApplyConfirm = async () => {
+    const { existing } = await checkExistingFiles();
+    setApplyState({ phase: "confirm", existing });
+  };
+
+  const runApply = async () => {
+    const vibe = VIBE_CHOICES.find((c) => c.id === answers.vibe);
+    const paletteChoice = PALETTE_CHOICES.find((c) => c.id === answers.palette);
+    const density = DENSITY_CHOICES.find((c) => c.id === answers.density);
+    if (!vibe || !paletteChoice || !density || !answers.theme) {
+      setApplyState({ phase: "error", message: "선택값이 비어있습니다", files: [] });
+      return;
+    }
+    // confirm 단계에서 기존 파일 발견했었다면 overwrite=true로 명시 승인 전달
+    const overwrite =
+      applyState.phase === "confirm" && applyState.existing.length > 0;
+    setApplyState({ phase: "applying" });
+    const hue = answers.hue ?? 210;
+    // 1) 브라우저 미리보기 반영
+    applyPreset({
+      mode: "light",
+      palette: paletteChoice.id,
+      hue,
+      shape: vibe.values.shape,
+      density: density.id,
+      motion: vibe.values.motion,
+      iconFamily: "phosphor",
+      lang: "ko",
+    });
+    // 2) 파일 쓰기 (server action)
+    const result = await applyOnboarding(
+      {
+        theme: answers.theme,
+        mode: "light",
+        palette: paletteChoice.id,
+        hue,
+        accentHue: null,
+        shape: vibe.values.shape,
+        density: density.id,
+        motion: vibe.values.motion,
+        iconFamily: "phosphor",
+        voice,
+        lang: "ko",
+        focusRing,
+        appliedAt: new Date().toISOString(),
+      },
+      { overwrite }
+    );
+    if (result.ok) {
+      setApplyState({ phase: "done", files: result.files });
+    } else {
+      setApplyState({
+        phase: "error",
+        message: result.error,
+        files: result.files,
+      });
+    }
+  };
+
+  // 페이지 진입 시 default answers를 축에 즉시 반영 (첫 렌더 톤 통일).
+  useEffect(() => {
+    if (answers.vibe) applyVibe(answers.vibe);
+    if (answers.palette) setPalette(answers.palette);
+    if (answers.hue != null) setHue(answers.hue);
+    if (answers.density) setDensity(answers.density);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const step = STEPS[stepIdx];
+  const canGoNext = useMemo(() => {
+    if (step.key === "theme") return answers.theme != null;
+    if (step.key === "vibe") return answers.vibe != null;
+    if (step.key === "color") return answers.palette != null;
+    if (step.key === "density") return answers.density != null;
+    if (step.key === "layout") return answers.layout != null;
+    return true;
+  }, [step.key, answers]);
+
+  if (mode === "free") {
+    return <FreeMode onBack={() => setMode("wizard")} />;
+  }
+
+  return (
+    <div className={styles.shell} data-palette="standard">
+      <Rail
+        stepIdx={stepIdx}
+        answers={answers}
+        onStepClick={(idx) => {
+          if (idx <= stepIdx || isStepReachable(idx, answers)) setStepIdx(idx);
+        }}
+        onFreeMode={() => setMode("free")}
+      />
+
+      <div className={styles.content}>
+          <div className={styles.contentInner}>
+            <header className={styles.stepHeader}>
+              <span className={styles.stepProgress}>
+                {stepIdx + 1} / {STEPS.length}
+              </span>
+              <h1 className={styles.stepTitle}>{stepTitle(step.key)}</h1>
+              <p className={styles.stepLead}>{stepLead(step.key)}</p>
+            </header>
+
+            <div className={styles.stepBody}>
+            {step.key === "theme" && (
+              <ThemeStep value={answers.theme} onChange={applyTheme} />
+            )}
+            {step.key === "vibe" && (
+              <VibeStep value={answers.vibe} onChange={applyVibe} />
+            )}
+            {step.key === "color" && (
+              <ColorStep
+                palette={answers.palette}
+                hue={answers.hue ?? 210}
+                hueSource={answers.hueSource}
+                brandHex={answers.brandHex}
+                onPalette={applyPalette}
+                onHueChange={applyHue}
+                onBrandHex={applyBrandHex}
+              />
+            )}
+            {step.key === "density" && (
+              <DensityStep value={answers.density} onChange={applyDensity} />
+            )}
+            {step.key === "layout" && (
+              <LayoutStep
+                value={answers.layout}
+                onChange={(v) => setAnswers((a) => ({ ...a, layout: v }))}
+              />
+            )}
+            {step.key === "summary" && <SummaryStep answers={answers} />}
+            </div>
+
+            <footer className={styles.stepFoot}>
+              <div className={styles.stepFootActions}>
+                <Button
+                  variant="secondary"
+                  size="lg"
+                  disabled={stepIdx === 0}
+                  onClick={() => setStepIdx((i) => Math.max(0, i - 1))}
+                >
+                  Back
+                </Button>
+                <Button
+                  variant="primary"
+                  size="lg"
+                  disabled={!canGoNext}
+                  onClick={() => {
+                    if (stepIdx === STEPS.length - 1) {
+                      openApplyConfirm();
+                      return;
+                    }
+                    setStepIdx((i) => nextStepIdx(i, answers));
+                  }}
+                  rightIcon={
+                    stepIdx === STEPS.length - 1 ? undefined : <Icon name="arrow-right" />
+                  }
+                >
+                  {stepIdx === STEPS.length - 1 ? "이 설정 적용" : "Next"}
+                </Button>
+              </div>
+            </footer>
+          </div>
+        </div>
+
+        {applyState.phase !== "idle" && (
+          <ApplyDialog
+            state={applyState}
+            onCancel={() => setApplyState({ phase: "idle" })}
+            onConfirm={runApply}
+          />
+        )}
+    </div>
+  );
+}
+
+// ────────────────────────────────────────────────────────
+// Apply dialog — confirm / applying / done / error
+// ────────────────────────────────────────────────────────
+
+type ApplyState =
+  | { phase: "confirm"; existing: string[] }
+  | { phase: "applying" }
+  | { phase: "done"; files: string[] }
+  | { phase: "error"; message: string; files: string[] };
+
+function ApplyDialog({
+  state,
+  onCancel,
+  onConfirm,
+}: {
+  state: ApplyState;
+  onCancel: () => void;
+  onConfirm: () => void;
+}) {
+  return (
+    <div className={styles.applyBackdrop} onClick={state.phase === "applying" ? undefined : onCancel}>
+      <div
+        className={styles.applyModal}
+        onClick={(e) => e.stopPropagation()}
+        role="dialog"
+        aria-modal="true"
+      >
+        {state.phase === "confirm" && (
+          <>
+            <h2 className={styles.applyTitle}>
+              {state.existing.length > 0
+                ? "기존 설정을 덮어쓸까요?"
+                : "이 설정을 프로젝트에 적용할까요?"}
+            </h2>
+            {state.existing.length > 0 ? (
+              <p className={styles.applyLead}>
+                이미 다음 파일이 존재합니다. 적용하면 <strong>덮어쓰여집니다</strong>.
+                커밋되지 않은 변경이 있는지 확인하세요.
+              </p>
+            ) : (
+              <p className={styles.applyLead}>
+                프로젝트 루트에 다음 두 파일이 생성됩니다. 모두 로컬 파일 작업이고 되돌릴 수 있어요.
+              </p>
+            )}
+            <ul className={styles.applyFileList}>
+              <li>
+                <code>ctds.config.json</code>
+                <span className={styles.applyFileHint}>
+                  {state.existing.includes("ctds.config.json")
+                    ? "기존 파일 덮어씀 · 축 값 JSON"
+                    : "축 값 JSON (AI 에이전트·ThemeController가 참조)"}
+                </span>
+              </li>
+              <li>
+                <code>DESIGN.md</code>
+                <span className={styles.applyFileHint}>
+                  {state.existing.includes("DESIGN.md")
+                    ? "기존 파일 덮어씀 · 테마·축 산문 요약"
+                    : "테마·축 산문 요약"}
+                </span>
+              </li>
+            </ul>
+            <div className={styles.applyActions}>
+              <Button variant="secondary" size="md" onClick={onCancel}>
+                취소
+              </Button>
+              <Button variant="primary" size="md" onClick={onConfirm}>
+                {state.existing.length > 0 ? "덮어쓰고 적용" : "적용"}
+              </Button>
+            </div>
+          </>
+        )}
+        {state.phase === "applying" && (
+          <>
+            <h2 className={styles.applyTitle}>적용 중…</h2>
+            <p className={styles.applyLead}>파일을 쓰는 중입니다.</p>
+          </>
+        )}
+        {state.phase === "done" && (
+          <>
+            <h2 className={styles.applyTitle}>적용 완료</h2>
+            <p className={styles.applyLead}>다음 파일이 생성/수정됐어요.</p>
+            <ul className={styles.applyFileList}>
+              {state.files.map((f) => (
+                <li key={f}>
+                  <code>{f}</code>
+                </li>
+              ))}
+            </ul>
+            <p className={styles.applyLead}>
+              이제 Claude Code 등 AI 에이전트가 <code>ctds.config.json</code>·<code>DESIGN.md</code>를 참조해
+              이 프로젝트의 축 값에 맞춰 코드를 생성할 수 있습니다.
+            </p>
+            <div className={styles.applyActions}>
+              <Button variant="primary" size="md" onClick={onCancel}>
+                닫기
+              </Button>
+            </div>
+          </>
+        )}
+        {state.phase === "error" && (
+          <>
+            <h2 className={styles.applyTitle}>적용 실패</h2>
+            <p className={styles.applyLead}>
+              파일 쓰기 중 오류가 발생했어요. 미리보기(브라우저 톤)는 적용됐지만 파일은 저장되지 않았습니다.
+            </p>
+            <pre className={styles.applyError}>{state.message}</pre>
+            {state.files.length > 0 && (
+              <>
+                <p className={styles.applyLead}>그 전에 성공한 파일:</p>
+                <ul className={styles.applyFileList}>
+                  {state.files.map((f) => (
+                    <li key={f}>
+                      <code>{f}</code>
+                    </li>
+                  ))}
+                </ul>
+              </>
+            )}
+            <div className={styles.applyActions}>
+              <Button variant="secondary" size="md" onClick={onCancel}>
+                닫기
+              </Button>
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ────────────────────────────────────────────────────────
+
+function stepTitle(k: StepKey): string {
+  if (k === "theme") return "디자인 스타일을 적용할까요?";
+  if (k === "vibe") return "이 프로덕트는 어떤 톤인가요?";
+  if (k === "color") return "컬러는 어떻게 갈까요?";
+  if (k === "density") return "화면에 정보가 얼마나 많나요?";
+  if (k === "layout") return "어떤 레이아웃이 어울릴까요?";
+  return "이렇게 설정할게요";
+}
+
+function stepLead(k: StepKey): string {
+  if (k === "theme")
+    return "스타일을 고르면 축 디폴트와 DESIGN.md가 함께 적용돼요. 축은 뒤에서 자유롭게 바꿀 수 있어요.";
+  if (k === "vibe") return "가장 가까운 하나만 골라주세요. Shape · Motion · Icon Weight가 세트로 결정돼요.";
+  if (k === "color")
+    return "먼저 팔레트를 고르고, 그 다음 브랜드 색을 슬라이더로 조정하거나 hex로 직접 넣어주세요.";
+  if (k === "density") return "한 화면에 담을 정보량. Density 축이 결정돼요.";
+  if (k === "layout") return "쓰임새에 맞는 사이드바·탑바 조합.";
+  return "선택을 확인하고 프로젝트에 적용하세요. 언제든 자유 조정으로 세부 축을 바꿀 수 있어요.";
+}
+
+/**
+ * step 도달 가능 여부. STEPS 순서가 바뀌어도 안전하도록 key 기반으로 판정.
+ * 각 step에 필요한 answers 필드를 매핑.
+ */
+const STEP_REQUIRES: Record<StepKey, (keyof Answers)[]> = {
+  theme: [],
+  vibe: ["theme"],
+  density: ["theme", "vibe"],
+  color: ["theme", "vibe", "density"],
+  layout: ["theme", "vibe", "density", "palette"],
+  summary: ["theme", "vibe", "density", "palette", "layout"],
+};
+
+function isStepReachable(idx: number, a: Answers): boolean {
+  const step = STEPS[idx];
+  if (!step) return false;
+  return STEP_REQUIRES[step.key].every((k) => a[k] != null);
+}
+
+/**
+ * 다음 step 인덱스 계산. 특수 룰:
+ * - theme 단계에서 none이 아닌 테마를 고르면 vibe 단계는 건너뜀 (테마가 vibe 축을 커버).
+ * 그 외엔 선형 +1.
+ */
+function nextStepIdx(current: number, a: Answers): number {
+  const curr = STEPS[current]?.key;
+  if (curr === "theme" && a.theme && a.theme !== "none") {
+    const colorIdx = STEPS.findIndex((s) => s.key === "color");
+    if (colorIdx > current) return colorIdx;
+  }
+  return Math.min(STEPS.length - 1, current + 1);
+}
+
+// ────────────────────────────────────────────────────────
+
+function Rail({
+  stepIdx,
+  answers,
+  onStepClick,
+  onFreeMode,
+}: {
+  stepIdx: number;
+  answers: Answers;
+  onStepClick: (i: number) => void;
+  onFreeMode: () => void;
+}) {
+  return (
+    <aside className={styles.rail}>
+      <div className={styles.railBrand} aria-hidden>
+        <Icon name="palette" size={18} />
+      </div>
+
+      <Stepper
+        className={styles.railSteps}
+        activeIndex={stepIdx}
+        onStepClick={onStepClick}
+      >
+        {STEPS.map((s, i) => (
+          <Stepper.Item
+            key={s.key}
+            title={s.title}
+            hint={s.hint}
+            disabled={i > stepIdx && !isStepReachable(i, answers)}
+          />
+        ))}
+      </Stepper>
+
+      <div className={styles.railFoot}>
+        <span>CTDS 온보딩</span>
+        <button
+          type="button"
+          className={styles.railFootBtn}
+          onClick={onFreeMode}
+        >
+          자유 조정
+          <Icon name="arrow-right" size={12} />
+        </button>
+      </div>
+    </aside>
+  );
+}
+
+// ────────────────────────────────────────────────────────
+
+/**
+ * 각 테마 미리보기 이미지. null이면 placeholder 블록 표시.
+ * 이미지는 web/public/onboarding/<slug>.png 에 둔다.
+ */
+const THEME_PREVIEW_IMG: Record<ThemeId, string | null> = {
+  none: null,
+  pure: "/onboarding/pure.png",
+  spare: "/onboarding/spare.png",
+  expressive: "/onboarding/expressive.png",
+};
+
+function ThemeStep({
+  value,
+  onChange,
+}: {
+  value: ThemeId | null;
+  onChange: (v: ThemeId) => void;
+}) {
+  const [hovered, setHovered] = useState<ThemeId | null>(null);
+  const [cursor, setCursor] = useState<{ x: number; y: number }>({ x: 0, y: 0 });
+
+  const handleMove = (e: React.MouseEvent) => {
+    setCursor({ x: e.clientX, y: e.clientY });
+  };
+
+  // "none"은 사진이 어차피 없으니 호버 미리보기 생략.
+  const showPreview = hovered !== null && hovered !== "none";
+  const previewSrc = hovered ? THEME_PREVIEW_IMG[hovered] : null;
+
+  // 커서 오른쪽 아래로 offset. 화면 밖 넘치면 왼쪽/위로 뒤집기.
+  const OFFSET_X = 20;
+  const OFFSET_Y = 20;
+  const PREVIEW_W = 384; // CSS와 동기 (space-24 * 4 = 96 * 4)
+  const PREVIEW_H = 288; // CSS와 동기 (space-24 * 3)
+  let left = cursor.x + OFFSET_X;
+  let top = cursor.y + OFFSET_Y;
+  if (typeof window !== "undefined") {
+    if (left + PREVIEW_W > window.innerWidth) left = cursor.x - OFFSET_X - PREVIEW_W;
+    if (top + PREVIEW_H > window.innerHeight) top = cursor.y - OFFSET_Y - PREVIEW_H;
+  }
+
+  return (
+    <>
+      <div className={styles.choiceList}>
+        {THEME_CHOICES.map((c) => (
+          <div
+            key={c.id}
+            onMouseEnter={() => setHovered(c.id)}
+            onMouseLeave={() => setHovered((prev) => (prev === c.id ? null : prev))}
+            onMouseMove={handleMove}
+          >
+            <SelectableCard
+              mode="radio"
+              name="onb-theme"
+              value={c.id}
+              checked={value === c.id}
+              onChange={() => onChange(c.id)}
+              title={
+                c.badge ? (
+                  <span className={styles.themeTitleRow}>
+                    <Badge size="sm" variant="soft" status={c.badgeStatus}>
+                      {c.badge}
+                    </Badge>
+                    <span>{c.title}</span>
+                  </span>
+                ) : (
+                  c.title
+                )
+              }
+              description={c.hint}
+            />
+          </div>
+        ))}
+      </div>
+
+      <div
+        className={styles.themeHoverLayer}
+        data-visible={showPreview || undefined}
+        style={{ transform: `translate(${left}px, ${top}px)` }}
+        aria-hidden
+      >
+        {previewSrc ? (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img src={previewSrc} alt="" className={styles.themeHoverImg} />
+        ) : (
+          <div className={styles.themeHoverPlaceholder}>
+            <span className={styles.themeHoverPlaceholderLabel}>
+              {hovered ?? ""}
+            </span>
+            <span className={styles.themeHoverPlaceholderHint}>
+              preview image TBD
+            </span>
+          </div>
+        )}
+      </div>
+    </>
+  );
+}
+
+function VibeStep({
+  value,
+  onChange,
+}: {
+  value: VibeId | null;
+  onChange: (v: VibeId) => void;
+}) {
+  return (
+    <div className={styles.choiceList}>
+      {VIBE_CHOICES.map((c) => (
+        <SelectableCard
+          key={c.id}
+          mode="radio"
+          name="onb-vibe"
+          value={c.id}
+          checked={value === c.id}
+          onChange={() => onChange(c.id)}
+          title={c.title}
+          description={c.hint}
+        />
+      ))}
+    </div>
+  );
+}
+
+function ColorStep({
+  palette,
+  hue,
+  hueSource,
+  brandHex,
+  onPalette,
+  onHueChange,
+  onBrandHex,
+}: {
+  palette: PaletteValue | null;
+  hue: number;
+  hueSource: "preset" | "hex" | null;
+  brandHex: string;
+  onPalette: (v: PaletteValue) => void;
+  onHueChange: (v: number) => void;
+  onBrandHex: (hex: string) => void;
+}) {
+  // hex가 유효하게 들어와 있으면 상단 컨트롤 비활성, 입력 섹션은 펼침.
+  const hexLocked = hueSource === "hex" && brandHex.trim().length > 0;
+  const [hexOpen, setHexOpen] = useState(hexLocked);
+  useEffect(() => {
+    if (hexLocked) setHexOpen(true);
+  }, [hexLocked]);
+
+  const hexInvalid =
+    brandHex.trim().length > 0 &&
+    (!isValidHex(brandHex.trim()) || hexToOklch(brandHex.trim()) == null);
+
+  const activePalette = palettePresets.find((p) => p.id === palette) ?? palettePresets[1];
+  const swatchColor = `oklch(${activePalette.lightness} ${activePalette.chroma} ${hue + activePalette.hueShift})`;
+  const activeHint = PALETTE_CHOICES.find((c) => c.id === palette)?.hint;
+
+  return (
+    <div className={styles.colorStep}>
+      <section className={styles.colorSection}>
+        <div className={styles.colorSectionHead}>
+          <span className={styles.colorSectionTitle}>팔레트 선택</span>
+          {activeHint && <span className={styles.colorSectionHint}>{activeHint}</span>}
+        </div>
+        <div className={styles.paletteRow} role="radiogroup" aria-label="팔레트 선택">
+          {PALETTE_CHOICES.map((c) => {
+            const preset = palettePresets.find((p) => p.id === c.id);
+            return (
+              <FilterButton
+                key={c.id}
+                size="md"
+                selected={palette === c.id}
+                disabled={hexLocked}
+                onClick={() => onPalette(c.id)}
+              >
+                {preset?.label ?? c.id}
+              </FilterButton>
+            );
+          })}
+        </div>
+      </section>
+
+      <section className={styles.colorSection}>
+        <span className={styles.colorSectionTitle}>브랜드 색</span>
+
+        <div className={styles.hueSliderBlock} data-locked={hexLocked || undefined}>
+          <span
+            className={styles.hueSliderSwatch}
+            style={{ background: swatchColor }}
+            aria-hidden
+          />
+          <Slider
+            min={0}
+            max={360}
+            value={hue}
+            onValueChange={onHueChange}
+            disabled={hexLocked}
+            aria-label="hue"
+          />
+          <span className={styles.hueSliderValue}>{hue}°</span>
+        </div>
+
+        <div className={styles.hexDisclosure}>
+          <button
+            type="button"
+            className={styles.hexToggle}
+            onClick={() => setHexOpen((v) => !v)}
+            aria-expanded={hexOpen}
+          >
+            <Icon name={hexOpen ? "caret-down" : "caret-right"} size={12} />
+            <span>브랜드 hex 직접 입력</span>
+            <span className={styles.hexOptionalTag}>선택</span>
+          </button>
+
+          {hexOpen && (
+            <div className={styles.hexBlock}>
+              <Input
+                size="md"
+                width="fill"
+                placeholder="#3B82F6"
+                value={brandHex}
+                onChange={(e) => onBrandHex(e.target.value)}
+                invalid={hexInvalid}
+                prefix={
+                  <span
+                    className={styles.hexBigSwatch}
+                    style={{
+                      background:
+                        brandHex && !hexInvalid
+                          ? brandHex.startsWith("#")
+                            ? brandHex
+                            : `#${brandHex}`
+                          : "transparent",
+                    }}
+                    aria-hidden
+                  />
+                }
+              />
+              <span className={styles.hexHelp}>
+                {hexLocked
+                  ? `${activePalette.label} 톤으로 매칭돼요`
+                  : hexInvalid
+                    ? "hex 형식이 올바르지 않아요"
+                    : "입력한 색을 그대로 재현해요"}
+              </span>
+            </div>
+          )}
+        </div>
+      </section>
+    </div>
+  );
+}
+
+function DensityStep({
+  value,
+  onChange,
+}: {
+  value: DensityChoiceId | null;
+  onChange: (v: DensityChoiceId) => void;
+}) {
+  return (
+    <div className={styles.choiceList}>
+      {DENSITY_CHOICES.map((c) => (
+        <SelectableCard
+          key={c.id}
+          mode="radio"
+          name="onb-density"
+          value={c.id}
+          checked={value === c.id}
+          onChange={() => onChange(c.id)}
+          title={c.title}
+          description={c.hint}
+        />
+      ))}
+    </div>
+  );
+}
+
+function LayoutStep({
+  value,
+  onChange,
+}: {
+  value: LayoutId | null;
+  onChange: (v: LayoutId) => void;
+}) {
+  const [hovered, setHovered] = useState<LayoutId | null>(null);
+  const [cursor, setCursor] = useState<{ x: number; y: number }>({ x: 0, y: 0 });
+
+  const handleMove = (e: React.MouseEvent) => {
+    setCursor({ x: e.clientX, y: e.clientY });
+  };
+
+  const hoveredChoice = hovered ? LAYOUT_CHOICES.find((c) => c.id === hovered) : null;
+
+  // ThemeStep과 동일한 커서 추적 로직.
+  const OFFSET_X = 20;
+  const OFFSET_Y = 20;
+  const PREVIEW_W = 384;
+  const PREVIEW_H = 256;
+  let left = cursor.x + OFFSET_X;
+  let top = cursor.y + OFFSET_Y;
+  if (typeof window !== "undefined") {
+    if (left + PREVIEW_W > window.innerWidth) left = cursor.x - OFFSET_X - PREVIEW_W;
+    if (top + PREVIEW_H > window.innerHeight) top = cursor.y - OFFSET_Y - PREVIEW_H;
+  }
+
+  return (
+    <>
+      <div className={styles.choiceList}>
+        {LAYOUT_CHOICES.map((c) => (
+          <div
+            key={c.id}
+            onMouseEnter={() => setHovered(c.id)}
+            onMouseLeave={() => setHovered((prev) => (prev === c.id ? null : prev))}
+            onMouseMove={handleMove}
+          >
+            <SelectableCard
+              mode="radio"
+              name="onb-layout"
+              value={c.id}
+              checked={value === c.id}
+              onChange={() => onChange(c.id)}
+              title={c.title}
+              description={c.hint}
+            />
+          </div>
+        ))}
+      </div>
+
+      <div
+        className={styles.themeHoverLayer}
+        data-visible={hoveredChoice ? true : undefined}
+        style={{ transform: `translate(${left}px, ${top}px)` }}
+        aria-hidden
+      >
+        {hoveredChoice && <LayoutWireframe sidebar={hoveredChoice.sidebar} topbar={hoveredChoice.topbar} />}
+      </div>
+    </>
+  );
+}
+
+/**
+ * 레이아웃 호버 미리보기 와이어프레임.
+ * 핵심 구조 — 탑바는 사이드바 "위"가 아니라 사이드바 "옆" (콘텐츠 영역 위에만).
+ * 즉 전체 레이아웃은 [좌사이드바 | (탑바 + 콘텐츠 세로)] 식 가로 분할.
+ */
+function LayoutWireframe({
+  sidebar,
+  topbar,
+}: {
+  sidebar: "left" | "right" | "dual" | "none";
+  topbar: boolean;
+}) {
+  return (
+    <div className={styles.layoutWire}>
+      {(sidebar === "left" || sidebar === "dual") && <div className={styles.layoutWireSidebar} />}
+      <div className={styles.layoutWireMain}>
+        {topbar && <div className={styles.layoutWireTopbar} />}
+        <div className={styles.layoutWireContent} />
+      </div>
+      {(sidebar === "right" || sidebar === "dual") && <div className={styles.layoutWireSidebar} />}
+    </div>
+  );
+}
+
+// ────────────────────────────────────────────────────────
+
+function SummaryStep({ answers }: { answers: Answers }) {
+  const [advancedOpen, setAdvancedOpen] = useState(false);
+
+  const theme = THEME_CHOICES.find((c) => c.id === answers.theme);
+  const vibe = VIBE_CHOICES.find((c) => c.id === answers.vibe);
+  const paletteChoice = PALETTE_CHOICES.find((c) => c.id === answers.palette);
+  const density = DENSITY_CHOICES.find((c) => c.id === answers.density);
+  const layout = LAYOUT_CHOICES.find((c) => c.id === answers.layout);
+
+  const hue = answers.hue ?? 210;
+
+  return (
+    <>
+      <div className={styles.summaryGrid}>
+        <SummaryCard
+          label="디자인 스타일"
+          value={theme?.title ?? "—"}
+          preview={
+            theme?.badge ? (
+              <Badge size="sm" variant="soft" status={theme.badgeStatus}>
+                {theme.badge}
+              </Badge>
+            ) : (
+              <span className={styles.summaryPreviewMuted}>Custom</span>
+            )
+          }
+        />
+        <SummaryCard
+          label="분위기"
+          value={vibe?.title ?? "—"}
+          preview={
+            vibe && (
+              <div className={styles.vibePreview} data-summary>
+                <span
+                  className={styles.vibePreviewBtn}
+                  data-shape={vibe.values.shape}
+                  aria-hidden
+                />
+                <span
+                  className={styles.vibePreviewChip}
+                  data-shape={vibe.values.shape}
+                  data-motion={vibe.values.motion}
+                  aria-hidden
+                />
+                <span
+                  className={styles.vibePreviewChip}
+                  data-shape={vibe.values.shape}
+                  data-motion={vibe.values.motion}
+                  data-variant="ghost"
+                  aria-hidden
+                />
+              </div>
+            )
+          }
+        />
+        <SummaryCard
+          label="컬러 & 톤"
+          value={paletteChoice?.title ?? "—"}
+          preview={
+            <div className={styles.colorPreview} aria-hidden>
+              <span
+                className={styles.colorPreviewSwatch}
+                style={{ background: `oklch(0.55 0.14 ${hue})` }}
+              />
+              <span
+                className={styles.colorPreviewSwatch}
+                data-tone="soft"
+                style={{ background: `oklch(0.78 0.08 ${hue})` }}
+              />
+              <span
+                className={styles.colorPreviewSwatch}
+                data-tone="deep"
+                style={{ background: `oklch(0.38 0.10 ${hue})` }}
+              />
+            </div>
+          }
+        />
+        <SummaryCard
+          label="정보 밀도"
+          value={density?.title ?? "—"}
+          preview={
+            density && (
+              <div
+                className={styles.densityPreview}
+                data-density={density.id}
+                aria-hidden
+              >
+                <span />
+                <span />
+                <span />
+                <span />
+              </div>
+            )
+          }
+        />
+        <SummaryCard
+          label="레이아웃"
+          value={layout?.title ?? "—"}
+          preview={
+            layout && (
+              <div
+                className={styles.layoutPreview}
+                data-sidebar={layout.sidebar}
+                data-topbar={layout.topbar ? "on" : "off"}
+                aria-hidden
+              >
+                {(layout.sidebar === "left" || layout.sidebar === "dual") && (
+                  <span className={styles.layoutPreviewRail} />
+                )}
+                <span className={styles.layoutPreviewMain}>
+                  {layout.topbar && <span className={styles.layoutPreviewBar} />}
+                  <span className={styles.layoutPreviewContent} />
+                </span>
+                {(layout.sidebar === "right" || layout.sidebar === "dual") && (
+                  <span className={styles.layoutPreviewRail} />
+                )}
+              </div>
+            )
+          }
+        />
+      </div>
+
+      <p className={styles.summaryHint}>
+        한 번 적용한 뒤 축을 바꾸면 이미 쌓인 컴포넌트·레이아웃이 자동 보정되지 않아요. 지금 신중히 결정해주세요.
+      </p>
+
+      <div className={styles.summaryAdvanced}>
+        <button
+          type="button"
+          className={styles.summaryAdvancedToggle}
+          onClick={() => setAdvancedOpen((v) => !v)}
+          aria-expanded={advancedOpen}
+        >
+          <span>고급 설정</span>
+          <Icon name={advancedOpen ? "caret-down" : "caret-right"} size={16} />
+
+        </button>
+        {advancedOpen && (
+          <div className={styles.summaryAdvancedBody}>
+            <OnboardingAxisPanel variant="wide" themeId={answers.theme} />
+          </div>
+        )}
+      </div>
+
+    </>
+  );
+}
+
+function SummaryCard({
+  label,
+  value,
+  preview,
+}: {
+  label: string;
+  value: string;
+  preview?: React.ReactNode;
+}) {
+  return (
+    <div className={styles.summaryCard}>
+      <div className={styles.summaryCardPreview}>{preview}</div>
+      <div className={styles.summaryCardText}>
+        <span className={styles.summaryLabel}>{label}</span>
+        <span className={styles.summaryValue}>{value}</span>
+      </div>
+    </div>
+  );
+}
+
+// ────────────────────────────────────────────────────────
+// Free mode: 위저드 밖 자유 조정 (기존 갤러리 뷰 재사용)
+// ────────────────────────────────────────────────────────
+
+function FreeMode({ onBack }: { onBack: () => void }) {
+  const [tab, setTab] = useState<"presets" | "layout" | "docs">("presets");
+
+  return (
+    <div className={styles.freeShell} data-palette="standard">
+      <div className={styles.freeAxis}>
+        <div className={styles.freeAxisScroll}>
+          <div className={styles.freeAxisInner}>
+            <OnboardingAxisPanel />
+          </div>
+        </div>
+      </div>
+      <div className={styles.freeContent}>
+        <div className={styles.freeContentInner}>
+          <div className={styles.freeHeader}>
+            <div>
+              <h1 className={styles.freeTitle}>자유 조정</h1>
+              <p className={styles.freeLead}>
+                좌측 축을 직접 조작하거나 아래에서 프리셋·레이아웃·문서를 골라 보세요.
+              </p>
+            </div>
+            <Button variant="ghost" size="sm" onClick={onBack}>
+              ← 위저드로
+            </Button>
+          </div>
+
+          <FreeTabs value={tab} onChange={setTab} />
+
+          {tab === "presets" && <PresetsGallery />}
+          {tab === "layout" && <LayoutBuilder />}
+          {tab === "docs" && <DocsIndex />}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function FreeTabs({
+  value,
+  onChange,
+}: {
+  value: "presets" | "layout" | "docs";
+  onChange: (v: "presets" | "layout" | "docs") => void;
+}) {
+  const tabs: { id: "presets" | "layout" | "docs"; label: string }[] = [
+    { id: "presets", label: "프리셋" },
+    { id: "layout", label: "레이아웃" },
+    { id: "docs", label: "컴포넌트 문서" },
+  ];
+  return (
+    <div className={styles.segment} role="tablist">
+      {tabs.map((t) => (
+        <button
+          key={t.id}
+          type="button"
+          className={styles.segmentItem}
+          data-active={value === t.id || undefined}
+          onClick={() => onChange(t.id)}
+          role="tab"
+          aria-selected={value === t.id}
+        >
+          {t.label}
+        </button>
+      ))}
+    </div>
+  );
+}