@flextudio/scenario 0.1.0

package/contract-data/schema/v1/design-system/tests/materialize.test.mjs

@@ -0,0 +1,1093 @@
+// design-system/tests/materialize.test.mjs
+// 실행: node --test meta-contract/schema/v1/design-system/tests/materialize.test.mjs
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  materializeDesign,
+  applyDesign,
+  designTokens,
+  designKnownKeys,
+} from "../materialize.mjs";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Typography
+// ────────────────────────────────────────────────────────────────────────────
+
+test("text role → FontSize + FontWeight", () => {
+  const { raw, sourceMap, errors } = materializeDesign({ font: "body-large" });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.FontStyle, {
+    UseFont: true,
+    FontSize: "16",
+    FontWeight: "Regular",
+  });
+  assert.equal(sourceMap["FontStyle.FontSize"], "$.design.font");
+  assert.equal(sourceMap["FontStyle.FontWeight"], "$.design.font");
+});
+
+test("text + color + align → 통합 FontStyle", () => {
+  const { raw, errors } = materializeDesign({
+    font: "title-medium",
+    color: "body",
+    align: "center",
+  });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.FontStyle, {
+    UseFont: true,
+    FontSize: "16",
+    FontWeight: "SemiBold",
+    FontColor: "var(--colorGray1)",
+    FontAlign: "center",
+  });
+});
+
+test("unknown typography role → error", () => {
+  const { raw, errors } = materializeDesign({ font: "huge-cool-text" });
+  assert.equal(errors.length, 1);
+  assert.equal(errors[0].path, "$.design.font");
+  assert.match(errors[0].message, /unknown typography role slot 'huge-cool-text'/);
+  assert.equal(raw.FontStyle, undefined);
+});
+
+test("FontWeight override 불가 — text 는 role 만", () => {
+  // weight 키 자체가 없어야 함. 추상화 어휘에 없으니 unknown key 로 거부됨.
+  const { errors } = materializeDesign({ font: "body-large", weight: "Bold" });
+  assert.ok(errors.some((e) => /unknown design key 'weight'/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Color slot — no raw escape
+// ────────────────────────────────────────────────────────────────────────────
+
+test("raw color escape 거부 — var(--colorPurple) 같은 값 불가", () => {
+  const { raw, errors } = materializeDesign({ color: "var(--colorPurple)" });
+  assert.equal(errors.length, 1);
+  assert.match(errors[0].message, /unknown text color slot/);
+  assert.equal(raw.FontStyle, undefined);
+});
+
+test("color slot 'body-soft' → Gray3", () => {
+  const { raw, errors } = materializeDesign({ color: "body-soft" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.FontStyle.FontColor, "var(--colorGray3)");
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Width / Height
+// ────────────────────────────────────────────────────────────────────────────
+
+test("w='full' → 100%", () => {
+  const { raw, errors } = materializeDesign({ w: "full" });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.Width, {
+    SizeValue: "100",
+    SizeUnit: "%",
+    MatchText: false,
+  });
+});
+
+test("h='text' → MatchText", () => {
+  const { raw, errors } = materializeDesign({ h: "text" });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.Height, {
+    MatchText: true,
+    SizeValue: "",
+    SizeUnit: "text",
+  });
+});
+
+test("w='48px' → fixed pixel", () => {
+  const { raw, errors } = materializeDesign({ w: "48px" });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.Width, {
+    SizeValue: "48",
+    SizeUnit: "px",
+    MatchText: false,
+  });
+});
+
+test("w='50%' → percent", () => {
+  const { raw, errors } = materializeDesign({ w: "50%" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.Width.SizeValue, "50");
+  assert.equal(raw.Width.SizeUnit, "%");
+});
+
+test("size '50' 단위 없음 → error", () => {
+  const { errors } = materializeDesign({ w: "50" });
+  assert.equal(errors.length, 1);
+  assert.match(errors[0].message, /invalid size '50'/);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Padding / Margin — string shorthand
+// ────────────────────────────────────────────────────────────────────────────
+
+test("p='16' → uniform per-side", () => {
+  const { raw, errors } = materializeDesign({ p: "16" });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.Padding, {
+    UseEach: true,
+    UseAuto: true,
+    All: "",
+    Top: "16",
+    Right: "16",
+    Btm: "16",
+    Left: "16",
+    SizeUnit: "px",
+  });
+});
+
+test("p='16 20' → vertical horizontal", () => {
+  const { raw } = materializeDesign({ p: "16 20" });
+  assert.equal(raw.Padding.Top, "16");
+  assert.equal(raw.Padding.Btm, "16");
+  assert.equal(raw.Padding.Right, "20");
+  assert.equal(raw.Padding.Left, "20");
+});
+
+test("p='4 8 12' → top horizontal bottom", () => {
+  const { raw } = materializeDesign({ p: "4 8 12" });
+  assert.equal(raw.Padding.Top, "4");
+  assert.equal(raw.Padding.Right, "8");
+  assert.equal(raw.Padding.Left, "8");
+  assert.equal(raw.Padding.Btm, "12");
+});
+
+test("p='4 8 12 16' → TRBL CSS order", () => {
+  const { raw } = materializeDesign({ p: "4 8 12 16" });
+  assert.equal(raw.Padding.Top, "4");
+  assert.equal(raw.Padding.Right, "8");
+  assert.equal(raw.Padding.Btm, "12");
+  assert.equal(raw.Padding.Left, "16");
+});
+
+test("p='1 2 3 4 5' → 5개는 error", () => {
+  const { errors } = materializeDesign({ p: "1 2 3 4 5" });
+  assert.equal(errors.length, 1);
+  assert.match(errors[0].message, /1–4 values/);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Padding / Margin — object form { t, r, b, l }
+// ────────────────────────────────────────────────────────────────────────────
+
+test("m={ t:8, b:8 } 부분 지정 → 나머지 ''", () => {
+  const { raw, errors } = materializeDesign({ m: { t: 8, b: 8 } });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.Margin.Top, "8");
+  assert.equal(raw.Margin.Btm, "8");
+  assert.equal(raw.Margin.Right, "");
+  assert.equal(raw.Margin.Left, "");
+});
+
+test("p={ t, r, b, l } 전체 지정", () => {
+  const { raw } = materializeDesign({ p: { t: 4, r: 8, b: 12, l: 16 } });
+  assert.equal(raw.Padding.Top, "4");
+  assert.equal(raw.Padding.Right, "8");
+  assert.equal(raw.Padding.Btm, "12");
+  assert.equal(raw.Padding.Left, "16");
+});
+
+test("p object 에 unknown key → error", () => {
+  const { errors } = materializeDesign({ p: { top: 8 } });
+  assert.ok(errors.some((e) => /unknown spacing key 'top'/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// BgStyle
+// ────────────────────────────────────────────────────────────────────────────
+
+test("bg='card' → White surface", () => {
+  const { raw, errors } = materializeDesign({ bg: "card" });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.BgStyle, {
+    UseBackground: true,
+    BgColor: "var(--colorWhite)",
+    UseImage: false,
+    Image: {},
+  });
+});
+
+test("bg='#abc' raw escape 거부", () => {
+  const { errors } = materializeDesign({ bg: "#abc" });
+  assert.equal(errors.length, 1);
+  assert.match(errors[0].message, /unknown bg color slot/);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// BorderStyle (border + radius)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("border='hairline' radius='16' → full border + radius", () => {
+  const { raw, errors } = materializeDesign({
+    border: "hairline",
+    radius: "16",
+  });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.BorderStyle, {
+    Useborder: true,
+    BorderColor: "var(--colorGray5)",
+    BorderSize: 1,
+    BorderType: "solid",
+    SizeSet: "All",
+    BorderRadius: "16",
+    RadiusSet: "All",
+  });
+});
+
+test("radius='9999' alone → pill (RadiusSet None, Useborder true)", () => {
+  const { raw } = materializeDesign({ radius: "9999" });
+  assert.equal(raw.BorderStyle.BorderRadius, "9999");
+  assert.equal(raw.BorderStyle.RadiusSet, "None");
+  assert.equal(raw.BorderStyle.Useborder, true);
+});
+
+test("border=false → Useborder:false", () => {
+  const { raw } = materializeDesign({ border: false });
+  assert.deepEqual(raw.BorderStyle, { Useborder: false });
+});
+
+test("border='none' → 동일 (Useborder:false)", () => {
+  const { raw } = materializeDesign({ border: "none" });
+  assert.deepEqual(raw.BorderStyle, { Useborder: false });
+});
+
+test("radius 숫자 형식 오류 — number 타입 거부", () => {
+  const { errors } = materializeDesign({ radius: 16 });
+  assert.equal(errors.length, 1);
+  assert.match(errors[0].message, /radius must be a non-negative integer string/);
+});
+
+test("radius 숫자 형식 오류 — 음수 문자열", () => {
+  const { errors } = materializeDesign({ radius: "-8" });
+  assert.match(errors[0].message, /radius must be a non-negative integer/);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Elevation
+// ────────────────────────────────────────────────────────────────────────────
+
+test("elevation='rect-shadow' → ContentStyle", () => {
+  const { raw, errors } = materializeDesign({ elevation: "rect-shadow" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.ContentStyle, "styleRectangleShadow");
+});
+
+test("elevation unknown → error", () => {
+  const { errors } = materializeDesign({ elevation: "fancy-glow" });
+  assert.match(errors[0].message, /unknown elevation slot 'fancy-glow'/);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// flex layout (DisplayStyle)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("flex={ dir:'row' } → 최소 DisplayStyle (UseDisplay + Flex + dir)", () => {
+  const { raw, errors } = materializeDesign({ flex: { dir: "row" } });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.DisplayStyle, {
+    UseDisplay: true,
+    DisplayType: "Flex",
+    FlexDirection: "row",
+  });
+});
+
+test("flex.dir 누락 → error", () => {
+  const { errors } = materializeDesign({ flex: { align: "center" } });
+  assert.ok(errors.some((e) => /flex\.dir is required/.test(e.message)));
+});
+
+test("flex.dir unknown → error", () => {
+  const { errors } = materializeDesign({ flex: { dir: "rows" } });
+  assert.ok(errors.some((e) => /unknown dir 'rows'/.test(e.message)));
+});
+
+test("flex={ dir:'column', align:'between', valign:'center', gap:8 } → DisplayStyle 풀세트", () => {
+  const { raw } = materializeDesign({
+    flex: { dir: "column", align: "between", valign: "center", gap: 8 },
+  });
+  assert.equal(raw.DisplayStyle.FlexDirection, "column");
+  assert.equal(raw.DisplayStyle.DisplayAlign, "Between");
+  assert.equal(raw.DisplayStyle.flexBoxType, "space");
+  assert.equal(raw.DisplayStyle.DisplayVerticalAlign, "Center");
+  assert.equal(raw.DisplayStyle.rowGapValue, "8");
+  assert.equal(raw.DisplayStyle.rowGapUnit, "px");
+  assert.equal(raw.DisplayStyle.columnGapValue, "8");
+  assert.equal(raw.DisplayStyle.columnGapUnit, "px");
+});
+
+test("flex flexbox 어휘 alias — valign/align start·end → canonical 토큰", () => {
+  // 모델이 CSS flex vocab(start/end/flex-start/flex-end)을 쓰는 케이스를 결정적 정규화.
+  const vs = materializeDesign({ flex: { dir: "row", valign: "start" } });
+  assert.deepEqual(vs.errors, []);
+  assert.equal(vs.raw.DisplayStyle.DisplayVerticalAlign, "Top");
+
+  const ve = materializeDesign({ flex: { dir: "row", valign: "flex-end" } });
+  assert.deepEqual(ve.errors, []);
+  assert.equal(ve.raw.DisplayStyle.DisplayVerticalAlign, "Bottom");
+
+  const as = materializeDesign({ flex: { dir: "row", align: "start" } });
+  assert.deepEqual(as.errors, []);
+  assert.equal(as.raw.DisplayStyle.DisplayAlign, "Left");
+  assert.equal(as.raw.DisplayStyle.flexBoxType, "align");
+
+  const ae = materializeDesign({ flex: { dir: "row", align: "end" } });
+  assert.deepEqual(ae.errors, []);
+  assert.equal(ae.raw.DisplayStyle.DisplayAlign, "Right");
+});
+
+test("flex.gap={ row:8, col:12 } → 각 축 따로", () => {
+  const { raw } = materializeDesign({
+    flex: { dir: "row", gap: { row: 8, col: 12 } },
+  });
+  assert.equal(raw.DisplayStyle.rowGapValue, "8");
+  assert.equal(raw.DisplayStyle.columnGapValue, "12");
+});
+
+test("flex.gap={ col:12 } 부분 — 명시한 축만 emit", () => {
+  const { raw } = materializeDesign({
+    flex: { dir: "row", gap: { col: 12 } },
+  });
+  assert.equal(raw.DisplayStyle.columnGapValue, "12");
+  assert.equal(raw.DisplayStyle.columnGapUnit, "px");
+  assert.equal(raw.DisplayStyle.rowGapValue, undefined);
+});
+
+test("flex.align='left' (non-between) → flexBoxType:'align'", () => {
+  const { raw } = materializeDesign({
+    flex: { dir: "row", align: "left" },
+  });
+  assert.equal(raw.DisplayStyle.DisplayAlign, "Left");
+  assert.equal(raw.DisplayStyle.flexBoxType, "align");
+});
+
+test("flex unknown key → error", () => {
+  const { errors } = materializeDesign({
+    flex: { dir: "row", direction: "row-reverse" },
+  });
+  assert.ok(errors.some((e) => /unknown flex key 'direction'/.test(e.message)));
+});
+
+test("flex.gap unknown sub-key → error", () => {
+  const { errors } = materializeDesign({
+    flex: { dir: "row", gap: { x: 8 } },
+  });
+  assert.ok(errors.some((e) => /unknown gap key 'x'/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// border object form (per-side + type)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("border 객체 form (color + type) — defaults size/SizeSet", () => {
+  const { raw, errors } = materializeDesign({
+    border: { color: "hairline-strong", type: "dashed" },
+  });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(raw.BorderStyle, {
+    Useborder: true,
+    BorderColor: "var(--colorGray4)",
+    BorderType: "dashed",
+    SizeSet: "All",
+    BorderSize: 1,
+  });
+});
+
+test("border 객체 form (color + size) — uniform 크기 override", () => {
+  const { raw } = materializeDesign({
+    border: { color: "hairline", size: "2" },
+  });
+  assert.equal(raw.BorderStyle.BorderSize, "2");
+  assert.equal(raw.BorderStyle.SizeSet, "All");
+});
+
+test("border 객체 form (sides) — SizeSet:'Each' + 4 사이드", () => {
+  const { raw, sourceMap } = materializeDesign({
+    border: {
+      color: "ink",
+      sides: { t: "2", r: "3", b: "2", l: "2" },
+    },
+  });
+  assert.equal(raw.BorderStyle.SizeSet, "Each");
+  assert.equal(raw.BorderStyle.BorderSize, "");
+  assert.equal(raw.BorderStyle.Top, "2");
+  assert.equal(raw.BorderStyle.Right, "3");
+  assert.equal(raw.BorderStyle.Bottom, "2");
+  assert.equal(raw.BorderStyle.Left, "2");
+  assert.equal(sourceMap["BorderStyle.Top"], "$.design.border.sides.t");
+  assert.equal(sourceMap["BorderStyle.Right"], "$.design.border.sides.r");
+});
+
+test("border 객체 form (sides 부분 지정) — 미지정 사이드는 ''", () => {
+  const { raw } = materializeDesign({
+    border: { color: "hairline", sides: { t: "2", b: "2" } },
+  });
+  assert.equal(raw.BorderStyle.Top, "2");
+  assert.equal(raw.BorderStyle.Btm, undefined); // BorderStyle uses Bottom not Btm
+  assert.equal(raw.BorderStyle.Bottom, "2");
+  assert.equal(raw.BorderStyle.Right, "");
+  assert.equal(raw.BorderStyle.Left, "");
+});
+
+test("border 객체 form: size + sides 동시 사용 → error", () => {
+  const { errors } = materializeDesign({
+    border: { color: "hairline", size: "2", sides: { t: "1" } },
+  });
+  assert.ok(errors.some((e) => /mutually exclusive/.test(e.message)));
+});
+
+test("border 객체 form: color 누락 → error", () => {
+  const { errors } = materializeDesign({
+    border: { type: "dashed" },
+  });
+  assert.ok(errors.some((e) => /must have 'color'/.test(e.message)));
+});
+
+test("border 객체 form: unknown type → error", () => {
+  const { errors } = materializeDesign({
+    border: { color: "hairline", type: "double" },
+  });
+  assert.ok(errors.some((e) => /unknown border type 'double'/.test(e.message)));
+});
+
+test("border 객체 form: unknown 키 → error", () => {
+  const { errors } = materializeDesign({
+    border: { color: "hairline", weight: "1" },
+  });
+  assert.ok(errors.some((e) => /unknown border key 'weight'/.test(e.message)));
+});
+
+test("border 객체 form: sides unknown 사이드 → error", () => {
+  const { errors } = materializeDesign({
+    border: { color: "hairline", sides: { top: "2" } },
+  });
+  assert.ok(errors.some((e) => /unknown side key 'top'/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// radius object form (per-corner)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("radius 객체 form (per-corner) — RadiusSet:'Each' + 4 코너", () => {
+  const { raw, sourceMap } = materializeDesign({
+    radius: { tl: "12", tr: "2", br: "15", bl: "43" },
+  });
+  assert.equal(raw.BorderStyle.BorderRadius, "");
+  assert.equal(raw.BorderStyle.RadiusSet, "Each");
+  assert.equal(raw.BorderStyle.RadiusTopLeft, "12");
+  assert.equal(raw.BorderStyle.RadiusTopRight, "2");
+  assert.equal(raw.BorderStyle.RadiusBottomRight, "15");
+  assert.equal(raw.BorderStyle.RadiusBottomLeft, "43");
+  assert.equal(raw.BorderStyle.Useborder, true);
+  assert.equal(sourceMap["BorderStyle.RadiusTopLeft"], "$.design.radius.tl");
+  assert.equal(sourceMap["BorderStyle.RadiusBottomLeft"], "$.design.radius.bl");
+});
+
+test("radius 객체 form (부분) — 누락 코너는 ''", () => {
+  const { raw } = materializeDesign({
+    radius: { tl: "12", tr: "12" },
+  });
+  assert.equal(raw.BorderStyle.RadiusTopLeft, "12");
+  assert.equal(raw.BorderStyle.RadiusTopRight, "12");
+  assert.equal(raw.BorderStyle.RadiusBottomLeft, "");
+  assert.equal(raw.BorderStyle.RadiusBottomRight, "");
+});
+
+test("radius 객체 form: unknown 코너 → error", () => {
+  const { errors } = materializeDesign({
+    radius: { topLeft: "12" },
+  });
+  assert.ok(errors.some((e) => /unknown radius key 'topLeft'/.test(e.message)));
+});
+
+test("border 객체 + radius 객체 결합 → BorderStyle 한 객체로 머지", () => {
+  const { raw } = materializeDesign({
+    border: { color: "hairline", sides: { t: "1" } },
+    radius: { tl: "8", tr: "8" },
+  });
+  assert.equal(raw.BorderStyle.SizeSet, "Each");
+  assert.equal(raw.BorderStyle.RadiusSet, "Each");
+  assert.equal(raw.BorderStyle.Top, "1");
+  assert.equal(raw.BorderStyle.RadiusTopLeft, "8");
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// caption (CaptionStyle)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("caption.font='body-medium' → CaptionStyle.FontSize/FontWeight + UseDesign", () => {
+  const { raw, sourceMap } = materializeDesign({
+    caption: { font: "body-medium" },
+  });
+  assert.equal(raw.CaptionStyle.UseDesign, true);
+  assert.equal(raw.CaptionStyle.FontSize, "14");
+  assert.equal(raw.CaptionStyle.FontWeight, "Regular");
+  assert.equal(sourceMap["CaptionStyle.FontSize"], "$.design.caption.font");
+});
+
+test("caption.color='body-soft' → CaptionStyle.FontColor", () => {
+  const { raw, sourceMap } = materializeDesign({
+    caption: { color: "body-soft" },
+  });
+  assert.equal(raw.CaptionStyle.UseDesign, true);
+  assert.equal(raw.CaptionStyle.FontColor, "var(--colorGray3)");
+  assert.equal(sourceMap["CaptionStyle.FontColor"], "$.design.caption.color");
+});
+
+test("caption.font 가 display 계열 → error (5 roles만 허용)", () => {
+  const { errors } = materializeDesign({
+    caption: { font: "display-large" },
+  });
+  assert.ok(
+    errors.some((e) =>
+      /unknown caption typography role 'display-large'/.test(e.message),
+    ),
+  );
+});
+
+test("caption unknown key → error", () => {
+  const { errors } = materializeDesign({
+    caption: { weight: "Bold" },
+  });
+  assert.ok(errors.some((e) => /unknown caption key 'weight'/.test(e.message)));
+});
+
+test("caption.pos='top' → CaptionPosition:'Top'", () => {
+  const { raw, sourceMap } = materializeDesign({
+    caption: { pos: "top" },
+  });
+  assert.equal(raw.CaptionStyle.UseDesign, true);
+  assert.equal(raw.CaptionStyle.CaptionPosition, "Top");
+  assert.equal(sourceMap["CaptionStyle.CaptionPosition"], "$.design.caption.pos");
+});
+
+test("caption.align='end' → CaptionStyle.FontAlign:'flex-end'", () => {
+  const { raw } = materializeDesign({ caption: { align: "end" } });
+  assert.equal(raw.CaptionStyle.FontAlign, "flex-end");
+});
+
+test("caption 풀세트 (text/color/pos/align)", () => {
+  const { raw } = materializeDesign({
+    caption: { font: "caption", color: "muted", pos: "left", align: "start" },
+  });
+  assert.equal(raw.CaptionStyle.FontSize, "12");
+  assert.equal(raw.CaptionStyle.FontColor, "var(--colorGray4)");
+  assert.equal(raw.CaptionStyle.CaptionPosition, "Left");
+  assert.equal(raw.CaptionStyle.FontAlign, "flex-start");
+});
+
+test("caption.pos unknown → error", () => {
+  const { errors } = materializeDesign({ caption: { pos: "right" } });
+  assert.ok(errors.some((e) => /unknown caption pos 'right'/.test(e.message)));
+});
+
+test("caption.text → 루트 Caption 내용 (CaptionStyle 와 별개)", () => {
+  const { raw, sourceMap, errors } = materializeDesign({
+    caption: { text: "이름" },
+  });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.Caption, "이름");
+  // 스타일 토글은 CaptionStyle 에, 내용은 루트 Caption 에 — 분리
+  assert.equal(raw.CaptionStyle.UseDesign, true);
+  assert.equal(sourceMap["Caption"], "$.design.caption.text");
+});
+
+test("caption.text + font 공존 → Caption(내용) + CaptionStyle(스타일) 각각", () => {
+  const { raw, errors } = materializeDesign({
+    caption: { text: "이름", font: "body-small", color: "body-soft" },
+  });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.Caption, "이름");
+  assert.equal(raw.CaptionStyle.FontSize, "13");
+  assert.equal(raw.CaptionStyle.FontColor, "var(--colorGray3)");
+});
+
+test("caption.text 비문자열 → error", () => {
+  const { raw, errors } = materializeDesign({ caption: { text: 123 } });
+  assert.ok(
+    errors.some(
+      (e) =>
+        e.path === "$.design.caption.text" &&
+        /caption.text must be a string/.test(e.message),
+    ),
+    `expected caption.text string error, got: ${JSON.stringify(errors)}`,
+  );
+  assert.equal(raw.Caption, undefined);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// abs (UseAbsoluteLayout + AbsolutePosition)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("abs={ b:'20', r:'20' } → UseAbsoluteLayout + AbsolutePosition (Btm/Right)", () => {
+  const { raw, sourceMap } = materializeDesign({
+    abs: { b: "20", r: "20" },
+  });
+  assert.equal(raw.UseAbsoluteLayout, true);
+  assert.equal(raw.AbsolutePosition.Btm, "20");
+  assert.equal(raw.AbsolutePosition.Right, "20");
+  assert.equal(raw.AbsolutePosition.Top, "");
+  assert.equal(raw.AbsolutePosition.Left, "");
+  assert.equal(raw.AbsolutePosition.SizeUnit, "px");
+  assert.equal(sourceMap["AbsolutePosition.Btm"], "$.design.abs.b");
+  assert.equal(sourceMap["AbsolutePosition.Right"], "$.design.abs.r");
+  assert.equal(sourceMap["UseAbsoluteLayout"], "$.design.abs");
+});
+
+test("abs unknown key → error", () => {
+  const { errors } = materializeDesign({ abs: { top: 10 } });
+  assert.ok(errors.some((e) => /unknown abs key 'top'/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// opacity
+// ────────────────────────────────────────────────────────────────────────────
+
+test("opacity=80 → UseOpacity:true + OpacityValue:'80'", () => {
+  const { raw, sourceMap } = materializeDesign({ opacity: 80 });
+  assert.equal(raw.UseOpacity, true);
+  assert.equal(raw.OpacityValue, "80");
+  assert.equal(sourceMap["UseOpacity"], "$.design.opacity");
+  assert.equal(sourceMap["OpacityValue"], "$.design.opacity");
+});
+
+test("opacity 범위 밖 → error", () => {
+  const { errors: e1 } = materializeDesign({ opacity: 150 });
+  assert.ok(e1.some((e) => /out of range/.test(e.message)));
+  const { errors: e2 } = materializeDesign({ opacity: -1 });
+  assert.ok(e2.some((e) => /out of range/.test(e.message)));
+});
+
+test("opacity 비정수 → error", () => {
+  const { errors } = materializeDesign({ opacity: 50.5 });
+  assert.ok(errors.some((e) => /must be an integer/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// itemBg (CheckBox/RadioBox 항목 기본 배경)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("itemBg='subtle' → ItemBgStyle (UseBackground + BgColor)", () => {
+  const { raw, sourceMap } = materializeDesign({ itemBg: "subtle" });
+  assert.deepEqual(raw.ItemBgStyle, {
+    UseBackground: true,
+    BgColor: "var(--colorGray9)",
+    UseImage: false,
+    Image: {},
+  });
+  assert.equal(sourceMap["ItemBgStyle.BgColor"], "$.design.itemBg");
+  assert.equal(sourceMap["ItemBgStyle"], "$.design.itemBg");
+});
+
+test("itemBg raw 색 거부 → error", () => {
+  const { errors } = materializeDesign({ itemBg: "#abc" });
+  assert.ok(errors.some((e) => /unknown itemBg color slot/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// tabHeader (Tab 4중 헤더 스타일)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("tabHeader.container — arrange + bg + p → TabHeader 객체", () => {
+  const { raw, errors, sourceMap } = materializeDesign({
+    tabHeader: {
+      container: {
+        arrange: { type: "equal", align: "center" },
+        bg: "card",
+        p: "0 16",
+      },
+    },
+  });
+  assert.deepEqual(errors, []);
+  assert.ok(raw.TabHeader);
+  assert.equal(raw.TabHeader.BgStyle.BgColor, "var(--colorWhite)");
+  assert.equal(raw.TabHeader.Padding.Top, "0");
+  assert.equal(raw.TabHeader.Padding.Right, "16");
+  assert.equal(raw.TabHeader.ArrangeItemsStyle.UseArrangeItems, true);
+  assert.equal(raw.TabHeader.ArrangeItemsStyle.ArrangeItemsType, "EqualDistribution");
+  assert.equal(raw.TabHeader.ArrangeItemsStyle.ArrangeItemsAlign, "Center");
+  assert.equal(sourceMap["TabHeader.BgStyle.BgColor"], "$.design.tabHeader.container.bg");
+  assert.equal(sourceMap["TabHeader.ArrangeItemsStyle"], "$.design.tabHeader.container.arrange");
+});
+
+test("tabHeader.item — text/color/align/p → TabHeaderItem 객체", () => {
+  const { raw, sourceMap } = materializeDesign({
+    tabHeader: {
+      item: {
+        font: "body-medium",
+        color: "body-soft",
+        align: "center",
+        p: "12 0",
+      },
+    },
+  });
+  assert.ok(raw.TabHeaderItem);
+  assert.equal(raw.TabHeaderItem.FontStyle.FontSize, "14");
+  assert.equal(raw.TabHeaderItem.FontStyle.FontColor, "var(--colorGray3)");
+  assert.equal(raw.TabHeaderItem.FontStyle.FontAlign, "center");
+  assert.equal(raw.TabHeaderItem.Padding.Top, "12");
+  assert.equal(sourceMap["TabHeaderItem.FontStyle.FontColor"], "$.design.tabHeader.item.color");
+});
+
+test("tabHeader 4 sub-block 모두 — 정확한 raw key 매핑", () => {
+  const { raw } = materializeDesign({
+    tabHeader: {
+      container: { bg: "card" },
+      selectedContainer: { bg: "subtle" },
+      item: { color: "body-soft" },
+      selectedItem: { color: "main" },
+    },
+  });
+  assert.equal(raw.TabHeader.BgStyle.BgColor, "var(--colorWhite)");
+  assert.equal(raw.SelectTabHeader.BgStyle.BgColor, "var(--colorGray9)");
+  assert.equal(raw.TabHeaderItem.FontStyle.FontColor, "var(--colorGray3)");
+  assert.equal(raw.SelectTabHeaderItem.FontStyle.FontColor, "var(--colorMain)");
+});
+
+test("tabHeader.selectedItem — border per-side (b: '2') → SelectTabHeaderItem.BorderStyle Each", () => {
+  const { raw } = materializeDesign({
+    tabHeader: {
+      selectedItem: {
+        color: "main",
+        border: { color: "main", sides: { b: "2" } },
+      },
+    },
+  });
+  assert.equal(raw.SelectTabHeaderItem.BorderStyle.SizeSet, "Each");
+  assert.equal(raw.SelectTabHeaderItem.BorderStyle.Bottom, "2");
+  assert.equal(raw.SelectTabHeaderItem.BorderStyle.BorderColor, "var(--colorMain)");
+});
+
+test("tabHeader.container 에 font 키 → error (item 키 차단)", () => {
+  const { errors } = materializeDesign({
+    tabHeader: { container: { font: "body-medium" } },
+  });
+  assert.ok(
+    errors.some((e) => /unknown tabHeader\.container key 'font'/.test(e.message)),
+  );
+});
+
+test("tabHeader.item 에 arrange 키 → error (container 전용 키 차단)", () => {
+  const { errors } = materializeDesign({
+    tabHeader: { item: { arrange: { type: "equal" } } },
+  });
+  assert.ok(
+    errors.some((e) => /unknown tabHeader\.item key 'arrange'/.test(e.message)),
+  );
+});
+
+test("tabHeader unknown sub-block 키 → error", () => {
+  const { errors } = materializeDesign({
+    tabHeader: { footer: { bg: "card" } },
+  });
+  assert.ok(errors.some((e) => /unknown tabHeader key 'footer'/.test(e.message)));
+});
+
+test("tabHeader.arrange.type unknown → error", () => {
+  const { errors } = materializeDesign({
+    tabHeader: { container: { arrange: { type: "stretch" } } },
+  });
+  assert.ok(errors.some((e) => /unknown arrange type 'stretch'/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// UseFixedSize
+// ────────────────────────────────────────────────────────────────────────────
+
+test("fixed=true → UseFixedSize:true", () => {
+  const { raw, errors } = materializeDesign({ fixed: true });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.UseFixedSize, true);
+});
+
+test("fixed='yes' → 타입 에러", () => {
+  const { errors } = materializeDesign({ fixed: "yes" });
+  assert.match(errors[0].message, /fixed must be boolean/);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Unknown design key
+// ────────────────────────────────────────────────────────────────────────────
+
+test("unknown design key → error 산출 + 알려진 leaf 는 그대로 처리", () => {
+  const { raw, errors } = materializeDesign({
+    font: "body-large",
+    sparkle: "high",
+  });
+  assert.equal(raw.FontStyle.FontSize, "16");
+  assert.ok(errors.some((e) => /unknown design key 'sparkle'/.test(e.message)));
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// applyDesign — control merge
+// ────────────────────────────────────────────────────────────────────────────
+
+test("applyDesign: design 없는 control 통과", () => {
+  const ctrl = { ControlType: "Label", labeltext: "hi" };
+  const { control, errors } = applyDesign(ctrl);
+  assert.deepEqual(errors, []);
+  assert.equal(control, ctrl); // 같은 reference
+});
+
+test("applyDesign: design 키 제거 + raw style 머지", () => {
+  const ctrl = {
+    ControlType: "Label",
+    labeltext: "hi",
+    design: { font: "body-large", color: "body", w: "full" },
+  };
+  const { control, errors } = applyDesign(ctrl);
+  assert.deepEqual(errors, []);
+  assert.equal(control.design, undefined);
+  assert.equal(control.FontStyle.FontColor, "var(--colorGray1)");
+  assert.equal(control.Width.SizeValue, "100");
+});
+
+test("applyDesign: 같은 leaf 겹침 시 design 우선, 안 겹친 leaf 는 raw 보존", () => {
+  const ctrl = {
+    ControlType: "Label",
+    labeltext: "hi",
+    FontStyle: {
+      UseFont: true,
+      FontSize: "20",
+      FontColor: "#abc",
+      LetterSpacing: "0.4",
+    },
+    design: { color: "body" },
+  };
+  const { control } = applyDesign(ctrl);
+  // design.color 가 FontColor 덮어씀
+  assert.equal(control.FontStyle.FontColor, "var(--colorGray1)");
+  // design 이 안 건드린 FontSize, LetterSpacing 은 raw 그대로
+  assert.equal(control.FontStyle.FontSize, "20");
+  assert.equal(control.FontStyle.LetterSpacing, "0.4");
+});
+
+test("applyDesign: sourceMap 반환 (역매핑용)", () => {
+  const ctrl = {
+    ControlType: "Label",
+    design: { color: "body" },
+  };
+  const { sourceMap } = applyDesign(ctrl);
+  assert.equal(sourceMap["FontStyle.FontColor"], "$.design.color");
+});
+
+test("applyDesign: design 만으로 모든 style — raw FontStyle 없음 → design 의 FontStyle 그대로", () => {
+  const ctrl = {
+    ControlType: "Label",
+    design: { font: "body-large", color: "body" },
+  };
+  const { control } = applyDesign(ctrl);
+  assert.deepEqual(control.FontStyle, {
+    UseFont: true,
+    FontSize: "16",
+    FontWeight: "Regular",
+    FontColor: "var(--colorGray1)",
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// applyDesign: flex Group-only 강제
+// ────────────────────────────────────────────────────────────────────────────
+
+test("applyDesign: flex on Group → DisplayStyle 정상 emit", () => {
+  const grp = {
+    ContentsType: "Group",
+    design: { flex: { dir: "row", gap: 8 } },
+    Contents: [],
+  };
+  const { control, errors } = applyDesign(grp);
+  assert.deepEqual(errors, []);
+  assert.equal(control.DisplayStyle.FlexDirection, "row");
+  assert.equal(control.DisplayStyle.columnGapValue, "8");
+});
+
+test("applyDesign: flex on Control → error + DisplayStyle 미생성", () => {
+  const ctrl = {
+    ControlType: "Label",
+    labeltext: "x",
+    design: { flex: { dir: "row" }, color: "body" },
+  };
+  const { control, errors } = applyDesign(ctrl);
+  assert.ok(
+    errors.some(
+      (e) =>
+        e.path === "$.design.flex" &&
+        /allowed only on Groups/.test(e.message),
+    ),
+    `expected Group-only error, got: ${JSON.stringify(errors)}`,
+  );
+  // 잘못된 DisplayStyle 이 emit 되지 않아야 함
+  assert.equal(control.DisplayStyle, undefined);
+  // flex 외 다른 design 키는 정상 처리
+  assert.equal(control.FontStyle.FontColor, "var(--colorGray1)");
+});
+
+test("applyDesign: flex on Control + 다른 design key 도 함께 → 나머지는 통과", () => {
+  const ctrl = {
+    ControlType: "Label",
+    labeltext: "x",
+    design: { flex: { dir: "row" }, w: "full", font: "body-large" },
+  };
+  const { control, errors } = applyDesign(ctrl);
+  // flex 에러 1개만
+  assert.equal(errors.filter((e) => /flex/.test(e.message)).length, 1);
+  assert.equal(control.DisplayStyle, undefined);
+  // w, text 는 그대로 적용
+  assert.equal(control.Width.SizeValue, "100");
+  assert.equal(control.FontStyle.FontSize, "16");
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// surface 프리셋 (Group 전용 매크로 — Paper)
+// ────────────────────────────────────────────────────────────────────────────
+
+test("surface 'elevated' → card bg + radius 16 + radius-shadow", () => {
+  const { raw, errors } = materializeDesign({ surface: "elevated" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.BgStyle.UseBackground, true);
+  assert.equal(raw.BgStyle.BgColor, "var(--colorWhite)");
+  assert.equal(raw.BorderStyle.BorderRadius, "16");
+  assert.equal(raw.BorderStyle.RadiusSet, "All");
+  assert.equal(raw.ContentStyle, "styleRadiusShadow");
+});
+
+test("surface 'outlined' → card bg + hairline border + radius 16, 그림자 없음", () => {
+  const { raw, errors } = materializeDesign({ surface: "outlined" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.BgStyle.BgColor, "var(--colorWhite)");
+  assert.equal(raw.BorderStyle.Useborder, true);
+  assert.equal(raw.BorderStyle.BorderColor, "var(--colorGray5)");
+  assert.equal(raw.BorderStyle.BorderRadius, "16");
+  assert.equal(raw.ContentStyle, undefined);
+});
+
+test("surface 'flat' → card bg + radius 16, 테두리·그림자 없음", () => {
+  const { raw, errors } = materializeDesign({ surface: "flat" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.BgStyle.BgColor, "var(--colorWhite)");
+  assert.equal(raw.BorderStyle.BorderRadius, "16");
+  assert.equal(raw.BorderStyle.BorderColor, undefined);
+  assert.equal(raw.ContentStyle, undefined);
+});
+
+test("surface + 명시 키 override — radius 가 프리셋을 덮음", () => {
+  const { raw, errors } = materializeDesign({ surface: "elevated", radius: "20" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.BorderStyle.BorderRadius, "20");
+  assert.equal(raw.ContentStyle, "styleRadiusShadow"); // 프리셋 나머지는 유지
+  assert.equal(raw.BgStyle.BgColor, "var(--colorWhite)");
+});
+
+test("surface + 명시 border override — 프리셋에 없던 키 추가", () => {
+  const { raw, errors } = materializeDesign({ surface: "elevated", border: "main" });
+  assert.deepEqual(errors, []);
+  assert.equal(raw.BorderStyle.BorderColor, "var(--colorMain)");
+  assert.equal(raw.BorderStyle.BorderRadius, "16"); // 프리셋 radius 유지
+});
+
+test("surface unknown preset → error", () => {
+  const { errors } = materializeDesign({ surface: "paper" });
+  assert.ok(
+    errors.some(
+      (e) =>
+        e.path === "$.design.surface" &&
+        /unknown surface preset/.test(e.message),
+    ),
+    `expected unknown-preset error, got: ${JSON.stringify(errors)}`,
+  );
+});
+
+test("applyDesign: surface on Group → 정상 expand", () => {
+  const grp = {
+    ContentsType: "Group",
+    design: { surface: "elevated", p: "16" },
+    Contents: [],
+  };
+  const { control, errors } = applyDesign(grp);
+  assert.deepEqual(errors, []);
+  assert.equal(control.BgStyle.BgColor, "var(--colorWhite)");
+  assert.equal(control.ContentStyle, "styleRadiusShadow");
+  assert.equal(control.Padding.Top, "16");
+});
+
+test("applyDesign: surface on Control → error + 미expand", () => {
+  const ctrl = {
+    ControlType: "Label",
+    labeltext: "x",
+    design: { surface: "elevated", color: "body" },
+  };
+  const { control, errors } = applyDesign(ctrl);
+  assert.ok(
+    errors.some(
+      (e) =>
+        e.path === "$.design.surface" &&
+        /allowed only on Groups/.test(e.message),
+    ),
+    `expected Group-only error, got: ${JSON.stringify(errors)}`,
+  );
+  // surface 가 strip 되어 BgStyle/ContentStyle 미생성
+  assert.equal(control.BgStyle, undefined);
+  assert.equal(control.ContentStyle, undefined);
+  // surface 외 다른 design 키는 정상 처리
+  assert.equal(control.FontStyle.FontColor, "var(--colorGray1)");
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Domain-level sourceMap fallback
+//   FontStyle / BgStyle / BorderStyle 는 leaf 키만 매핑되므로 파생 leaf
+//   (UseFont, UseBackground, Useborder 등) 에러 역매핑을 위해 도메인 레벨
+//   엔트리도 함께 등록한다.
+// ────────────────────────────────────────────────────────────────────────────
+
+test("sourceMap: FontStyle 생성 시 도메인 레벨 'FontStyle' 엔트리도 등록", () => {
+  const { sourceMap } = materializeDesign({ color: "body" });
+  assert.equal(sourceMap["FontStyle.FontColor"], "$.design.color");
+  assert.equal(sourceMap["FontStyle"], "$.design");
+});
+
+test("sourceMap: BgStyle 생성 시 도메인 레벨 'BgStyle' 엔트리도 등록", () => {
+  const { sourceMap } = materializeDesign({ bg: "card" });
+  assert.equal(sourceMap["BgStyle.BgColor"], "$.design.bg");
+  assert.equal(sourceMap["BgStyle"], "$.design");
+});
+
+test("sourceMap: BorderStyle 생성 시 도메인 레벨 'BorderStyle' 엔트리도 등록", () => {
+  const { sourceMap } = materializeDesign({
+    border: "hairline",
+    radius: "16",
+  });
+  assert.equal(sourceMap["BorderStyle.BorderColor"], "$.design.border");
+  assert.equal(sourceMap["BorderStyle.BorderRadius"], "$.design.radius");
+  assert.equal(sourceMap["BorderStyle"], "$.design");
+});
+
+test("sourceMap: 도메인 미생성 시 fallback 엔트리도 없음", () => {
+  // w / h 만 사용 — FontStyle / BgStyle / BorderStyle 어느 도메인도 생성 안 됨.
+  const { sourceMap } = materializeDesign({ w: "full", h: "text" });
+  assert.equal(sourceMap["FontStyle"], undefined);
+  assert.equal(sourceMap["BgStyle"], undefined);
+  assert.equal(sourceMap["BorderStyle"], undefined);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// Introspection
+// ────────────────────────────────────────────────────────────────────────────
+
+test("designKnownKeys 노출 (introspection / docs sync 용)", () => {
+  assert.ok(designKnownKeys.includes("font"));
+  assert.ok(designKnownKeys.includes("flex"));
+  assert.ok(designKnownKeys.includes("caption"));
+  assert.ok(designKnownKeys.includes("abs"));
+  assert.ok(designKnownKeys.includes("opacity"));
+  assert.ok(designKnownKeys.includes("fixed"));
+  assert.ok(!designKnownKeys.includes("row"));
+});
+
+test("designTokens 노출", () => {
+  assert.ok(designTokens.typography["body-large"]);
+  assert.ok(designTokens.color["body"]);
+  assert.ok(designTokens.elevation["rect-shadow"]);
+});