@flextudio/scenario 0.1.0

package/contract-data/schema/v1/patterns/_base.style.mjs

@@ -0,0 +1,312 @@
+// _base.style.mjs
+// ─────────────────────────────────────────────────────────────────────────────
+// 엔진 메타데이터 생성을 위한 스타일 추상화 레이어.
+// 디자인 토큰 (spacing / typography / color) → 엔진 필드 객체
+// (Padding, Margin, FontStyle, BorderStyle, BgStyle) 매핑
+//
+// 컨트롤과 패턴 레이에어서 스탈 관련 메타데이터에 헬퍼 함수로 사용
+// 추상화 레이어를 메타데이터로 변환한 후 validation 실행
+//
+// ★ SSOT: 아래 토큰 테이블(SPACING / FONT_ROLE / COLOR)은 자체 값을 갖지 않고
+//   design-system/tokens.json 에서 파생한다. 이 모듈의 alias 이름(text.secondary /
+//   surface.brand 등)은 패턴 작성자(author)용 내부 어휘이고, 그 값은 전부 tokens.json
+//   의 슬롯에서 온다. raw `var(--colorXxx)` 를 이 파일에 직접 쓰지 않는다.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOKENS = JSON.parse(
+  readFileSync(join(__dirname, "../design-system/tokens.json"), "utf8"),
+);
+
+// tokens.json 영역 별칭.
+const PUBLIC_COLOR = TOKENS.color; // 외부 노출 design 키 슬롯 (main / body-soft / ...)
+const PALETTE = TOKENS.palette; // 내부 전용 raw primitive (blue / pink / sub7 / ...)
+
+// ============================================================================
+// 토큰 테이블 — tokens.json 파생 (자체 값 없음)
+// ============================================================================
+
+/**
+ * Spacing 스케일. tokens.json#/spacing 파생. 숫자 값은 테이블 우회 (resolveSpacing).
+ * xs/sm/md/lg/xl/xxl = 4/8/12/16/20/24.
+ */
+const SPACING = Object.freeze({ ...TOKENS.spacing });
+
+/**
+ * Typography 역할 프리셋. tokens.json#/typography 파생 (FontSize / FontWeight 짝).
+ * 짧은 alias(body-lg/md/sm)는 이 모듈 내부 편의용 — tokens.json 에는 노출하지 않는다.
+ */
+const FONT_ROLE = Object.freeze({
+  ...TOKENS.typography,
+  "body-lg": TOKENS.typography["body-large"],
+  "body-md": TOKENS.typography["body-medium"],
+  "body-sm": TOKENS.typography["body-small"],
+});
+
+/**
+ * 작성자용 의미 컬러 어휘 → tokens.json 슬롯 값.
+ * 모든 값은 PUBLIC_COLOR(외부 슬롯) 또는 PALETTE(내부 primitive)에서 온다 — 하드코딩 없음.
+ * 매핑은 DESIGN.md §Colors 기준 (Ink / Body / Body Soft / Muted ...).
+ */
+const COLOR = Object.freeze({
+  // Text / ink
+  "text.primary": PUBLIC_COLOR.ink, // Ink — 강조 (icon stroke 포함)
+  "text.body": PUBLIC_COLOR.body, // Body — 헤딩 / 본문 강조
+  "text.secondary": PUBLIC_COLOR["body-soft"], // Body Soft — 부제 / 라벨 / 캡션 (가장 자주)
+  "text.muted": PUBLIC_COLOR.muted, // Muted — placeholder / disabled / soft meta
+  "text.on-brand": PUBLIC_COLOR["on-brand"], // On Brand — Main / Sub / Semantic 배경 위 텍스트
+  "text.error": PUBLIC_COLOR.error,
+  "text.link": PALETTE.blue,
+
+  // Surface / background
+  surface: PUBLIC_COLOR.card, // 기본 카드 / 시트 배경
+  "surface.subtle": PUBLIC_COLOR.subtle, // 섹션 배경 / 구분된 영역
+  "surface.tag": PUBLIC_COLOR["surface-strong"], // 칩 / 뱃지 기본 배경
+  "surface.brand": PUBLIC_COLOR.main, // Main 필 (Primary CTA 등)
+  "surface.brand-soft": PUBLIC_COLOR["main-light"], // Main 약한 배경 (hover / soft emphasis)
+  "surface.dark": PUBLIC_COLOR.dark, // dark feature card / inversion
+
+  // Border
+  "border.default": PUBLIC_COLOR.hairline, // Hairline — 1px divider / card outline
+  "border.strong": PUBLIC_COLOR["hairline-strong"], // Hairline Strong — interactive boundary / focus
+  "border.ink": PUBLIC_COLOR.ink,
+
+  // Semantic (DESIGN.md §Components → status-badge)
+  "semantic.success": PUBLIC_COLOR.success,
+  "semantic.failure": PUBLIC_COLOR.error,
+  "semantic.preview": PUBLIC_COLOR.preview,
+  "semantic.warning": PUBLIC_COLOR.warning,
+  "semantic.info": PALETTE.blue,
+});
+
+// ============================================================================
+// 내부 resolver
+// ============================================================================
+
+function resolveSpacing(v) {
+  if (v == null || v === "") return "";
+  if (typeof v === "number") return String(v);
+  if (typeof v === "string") {
+    if (Object.hasOwn(SPACING, v)) return SPACING[v];
+    if (/^-?[0-9]+(\.[0-9]+)?$/.test(v)) return v;
+    throw new Error(`_base.style: 알 수 없는 spacing 토큰 '${v}'`);
+  }
+  throw new TypeError("_base.style: spacing 은 string|number 여야 함");
+}
+
+function resolveColor(v) {
+  if (v == null) return "";
+  if (typeof v !== "string") {
+    throw new TypeError("_base.style: color 는 string 이어야 함");
+  }
+  if (v === "") return "";
+  if (Object.hasOwn(COLOR, v)) return COLOR[v]; // 작성자 의미 어휘 (text.* / surface.* ...)
+  if (Object.hasOwn(PUBLIC_COLOR, v)) return PUBLIC_COLOR[v]; // tokens.json 외부 슬롯 (main / ink ...)
+  if (Object.hasOwn(PALETTE, v)) return PALETTE[v]; // tokens.json 내부 primitive (blue / pink ...)
+  return v; // raw escape hatch — var(--...), #hex, rgb(...), keyword
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Padding / Margin / AbsolutePosition 용 spacing 객체 생성.
+ *
+ *   padding("lg")                                      네 면 균일 16
+ *   padding(16)                                        네 면 균일 raw 숫자
+ *   padding({ all: "lg" })                             opts 형태 균일
+ *   padding({ x: "md", y: "sm" })                      x = L+R, y = T+B
+ *   padding({ top: 6, right: 12, btm: 6, left: 12 })   per-side 명시
+ *   padding({ top: "sm", x: "lg" })                    혼합 (top + axis)
+ *
+ * Uniform 모드:   { All, SizeUnit:"px", UseEach:false, UseAuto:true }.
+ * Per-side 모드: { Top, Right, Btm, Left, SizeUnit:"px",
+ *                  UseEach:true, UseAuto:true, All:"" }.
+ *
+ * per-side 모드에서 명시되지 않은 사이드는 "" (엔진 default).
+ */
+function spacingObject(input) {
+  // Uniform 단축.
+  if (typeof input === "string" || typeof input === "number") {
+    return {
+      All: resolveSpacing(input),
+      SizeUnit: "px",
+      UseEach: false,
+      UseAuto: true,
+    };
+  }
+  if (!input || typeof input !== "object") {
+    throw new TypeError("spacing(): input 은 string|number|object 여야 함");
+  }
+  const { all, x, y, top, right, btm, left } = input;
+
+  // 다른 키 없이 { all } 만 있으면 uniform.
+  if (
+    all != null &&
+    x == null &&
+    y == null &&
+    top == null &&
+    right == null &&
+    btm == null &&
+    left == null
+  ) {
+    return {
+      All: resolveSpacing(all),
+      SizeUnit: "px",
+      UseEach: false,
+      UseAuto: true,
+    };
+  }
+
+  const pick = (side, axis) =>
+    side != null
+      ? resolveSpacing(side)
+      : axis != null
+        ? resolveSpacing(axis)
+        : "";
+
+  return {
+    Top: pick(top, y),
+    Right: pick(right, x),
+    Btm: pick(btm, y),
+    Left: pick(left, x),
+    SizeUnit: "px",
+    UseEach: true,
+    UseAuto: true,
+    All: "",
+  };
+}
+
+export function padding(input) {
+  return spacingObject(input);
+}
+
+export function margin(input) {
+  return spacingObject(input);
+}
+
+/**
+ * FontStyle 객체 생성.
+ *
+ *   font({ size: "body-md", weight: "Regular", color: "text.primary" })
+ *   font({ size: 14, weight: "Medium", color: "var(--colorBlack)", align: "center" })
+ *   font({ size: "display-large", color: "text.primary" })
+ *   font({ size: "body-small", color: "text.secondary" })
+ *
+ * - `size`: 역할 토큰 ("body-md" / "title-large" / "display-medium" / ...) 또는
+ *   명시적 숫자 / 숫자 문자열. 역할 토큰이면 preset 에서 FontSize + FontWeight
+ * - `weight`: 엔진 enum ("Regular" / "Medium" / "SemiBold" / "Bold").
+ *   role 과 함께 주어지면 preset 을 override.
+ * - `color`: 의미적 토큰 ("text.primary" ...) 또는 raw 값
+ *   ("var(--colorBlack)" / "#333" / "rgb(0,0,0)").
+ * - `align`: FontAlign ("flex-start" / "center" / "flex-end").
+ */
+export function font(opts = {}) {
+  const { size, weight, color, align } = opts;
+
+  let preset = {};
+  let explicitSize;
+  if (size != null) {
+    if (typeof size === "string" && Object.hasOwn(FONT_ROLE, size)) {
+      preset = FONT_ROLE[size];
+    } else if (typeof size === "string" || typeof size === "number") {
+      explicitSize = String(size);
+    } else {
+      throw new TypeError(
+        "font(): 'size' 는 role 토큰 또는 string|number 여야 함",
+      );
+    }
+  }
+
+  const out = { UseFont: true };
+  if (explicitSize != null) out.FontSize = explicitSize;
+  else if (preset.FontSize != null) out.FontSize = preset.FontSize;
+
+  if (weight != null) out.FontWeight = weight;
+  else if (preset.FontWeight != null) out.FontWeight = preset.FontWeight;
+
+  if (color != null) out.FontColor = resolveColor(color);
+  if (align != null) out.FontAlign = align;
+  return out;
+}
+
+/**
+ * BorderStyle 객체 생성.
+ *
+ *   border({ radius: 8, color: "border.strong", size: 1 })  full border
+ *   border({ radius: 8 })                                    radius 만
+ *   border()                                                 { Useborder: false }
+ *
+ * - `radius`: number/string → BorderRadius. 가시 border 유무 무관.
+ * - `color`: 토큰 또는 raw → BorderColor (있으면 가시 border).
+ * - `size`: BorderSize (color 가 있을 때 default 1). number/string.
+ * - `type`: "solid" / "dashed" / "dotted" (default "solid").
+ * - `radiusSet`: "All" / "Top" / "Right" / "Bottom" / "Left" (default "All").
+ * - `sideSet`: BorderSize 가 적용될 사이드 (default "All").
+ */
+export function border(opts = {}) {
+  const { radius, color, size, type, radiusSet, sideSet } = opts;
+  const out = {};
+  if (radius != null) {
+    out.BorderRadius = String(radius);
+    out.RadiusSet = radiusSet ?? "All";
+  }
+  const hasVisibleBorder = color != null && color !== "";
+  if (hasVisibleBorder) {
+    out.BorderColor = resolveColor(color);
+    out.BorderSize = String(size ?? 1);
+    out.BorderType = type ?? "solid";
+    out.SizeSet = sideSet ?? "All";
+    out.Useborder = true;
+  } else if (radius != null) {
+    // radius 만 — 엔진이 BorderRadius 적용하도록 Useborder 는 true
+    out.Useborder = true;
+  } else {
+    out.Useborder = false;
+  }
+  return out;
+}
+
+/**
+ * BgStyle 객체 생성.
+ *
+ *   bg("surface.subtle")          { BgColor: "var(--colorGray9)", UseBackground: true }
+ *   bg("var(--colorBlack)")       { BgColor: "var(--colorBlack)", UseBackground: true }
+ *   bg("")                        { BgColor: "",                  UseBackground: false }
+ *   bg(null) | bg()               { BgColor: "",                  UseBackground: false }
+ *   bg({ color: "surface" })      { BgColor: "var(--colorWhite)", UseBackground: true }
+ */
+export function bg(input) {
+  if (input == null) {
+    return { BgColor: "", UseBackground: false };
+  }
+  if (typeof input === "string") {
+    if (input === "") return { BgColor: "", UseBackground: false };
+    return { BgColor: resolveColor(input), UseBackground: true };
+  }
+  if (typeof input === "object") {
+    const { color } = input;
+    if (color == null || color === "") {
+      return { BgColor: "", UseBackground: false };
+    }
+    return { BgColor: resolveColor(color), UseBackground: true };
+  }
+  throw new TypeError("bg(): input 은 string|object|null 이어야 함");
+}
+
+// ============================================================================
+// 토큰 레지스트리 (읽기 전용 introspection)
+// ============================================================================
+
+export const tokens = Object.freeze({
+  spacing: SPACING,
+  font: FONT_ROLE,
+  color: COLOR, // 작성자 의미 어휘 (text.* / surface.* / border.* / semantic.*)
+  slot: PUBLIC_COLOR, // tokens.json 외부 노출 슬롯 (main / ink / body-soft ...)
+  palette: PALETTE, // tokens.json 내부 전용 primitive (blue / pink / sub7 ...)
+});

package/contract-data/schema/v1/patterns/atom/badge.materialize.mjs

@@ -0,0 +1,68 @@
+// badge.materialize.mjs
+// pattern.atom.badge — Label 컨트롤 기반 pill 형 뱃지.
+//
+// 메타 구조:
+// - ControlType: Label, labeltext = label prop
+// - Width  = MatchText (텍스트 + Padding 만큼 fit)
+// - Height = MatchText (factory default)
+// - BgStyle: 5종 color 모두 동일 라이트 톤 (var(--colorSub10))
+// - BorderStyle: BorderRadius:"999" (pill) + Useborder:true (radius gate)
+// - FontStyle.FontColor: color prop 매핑
+// - FontStyle.FontSize + Padding: size prop 매핑
+
+import { makeLabel } from "../_base.controls.mjs";
+import { generateId } from "../_base.id.mjs";
+import { font, border, bg, padding, tokens } from "../_base.style.mjs";
+import { makeOverride } from "../_base.additional-meta.mjs";
+
+// color prop → FontColor 매핑 (사용자 명시). 값은 tokens.json 에서 (하드코딩 금지).
+const FONT_COLOR_BY_COLOR = Object.freeze({
+  green: tokens.slot.main,
+  black: tokens.palette.sub7,
+  red: tokens.palette.pink,
+  blue: tokens.palette.blue,
+  gray: tokens.palette.sub9,
+});
+
+// size prop → (FontSize, padX, padY) 매핑.
+const STYLE_BY_SIZE = Object.freeze({
+  md: { fontSize: 13, padX: 8, padY: 4 },
+  lg: { fontSize: 16, padX: 10, padY: 6 },
+});
+
+// 5종 color 공통 라이트 배경 — 의미색은 텍스트에만 적용되고 bg 는 통일된 톤 유지.
+const BG_TOKEN = tokens.palette.sub10;
+
+// 텍스트 + Padding 만큼만 차지 (Width fit).
+const W_FIT = Object.freeze({
+  MatchText: true,
+  SizeValue: "",
+  SizeUnit: "text",
+});
+
+export default function materialize(props, ctx) {
+  const { label, color, size } = props;
+  const fc = FONT_COLOR_BY_COLOR[color];
+  const sz = STYLE_BY_SIZE[size];
+  if (!fc) throw new Error(`badge.materialize: unknown color '${color}'`);
+  if (!sz) throw new Error(`badge.materialize: unknown size '${size}'`);
+  const ov = makeOverride(props.override, "badge");
+
+  const out = {
+    ...makeLabel({ text: label, name: "Badge" }),
+    Id: generateId(ctx),
+    Width: { ...W_FIT },
+    BgStyle: bg(BG_TOKEN),
+    BorderStyle: border({ radius: 999 }),
+    Padding: padding({ x: sz.padX, y: sz.padY }),
+    FontStyle: font({
+      size: sz.fontSize,
+      weight: "Bold",
+      color: fc,
+    }),
+  };
+
+  const result = ov.apply("root", out);
+  ov.finalize(["root"]);
+  return result;
+}

package/contract-data/schema/v1/patterns/atom/badge.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/patterns/atom/badge.schema.json",
+  "title": "pattern.atom.badge",
+  "description": "상태/카테고리 라벨용 pill 형 뱃지. Label + pill BorderRadius(999) + 라이트 배경(`var(--colorSub10)`) + Bold 텍스트. 너비는 텍스트에 맞춰 자동 fit, 높이도 텍스트 + Padding 으로 결정. color 는 의미적 5종(green/black/red/blue/gray) — FontColor 만 바뀌고 배경은 5종 모두 동일한 라이트 톤이라 인접 정보 위에 얹어도 충돌 없음. size 는 md/lg 두 단계.",
+  "x-tier": "atom",
+  "x-tags": ["badge", "tag", "status", "label", "chip"],
+  "x-related": [],
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["label", "color", "size"],
+  "properties": {
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 20,
+      "description": "뱃지에 표시할 짧은 텍스트. 다국어 토큰 `{{key}}` / 정적 바인딩 `{=Field}` 가능."
+    },
+    "color": {
+      "type": "string",
+      "enum": ["green", "black", "red", "blue", "gray"],
+      "description": "의미 색상 (FontColor 만 매핑, 배경은 모두 동일 라이트 톤). green=긍정/완료 / black=중립 강조 / red=경고/실패 / blue=정보 / gray=비활성/보조."
+    },
+    "size": {
+      "type": "string",
+      "enum": ["md", "lg"],
+      "description": "크기. md=폰트13/패딩 4·8 / lg=폰트16/패딩 6·10."
+    },
+    "override": {
+      "type": "object",
+      "propertyNames": { "enum": ["root"] },
+      "additionalProperties": { "type": "object" },
+      "description": "(L1 escape hatch) 패턴이 노출하지 않는 raw 엔진 메타데이터를 materialized 결과 노드에 deep-merge 로 주입한다. 이 패턴은 단일 컨트롤이라 anchor 는 'root'(결과 노드 자체) 하나. 값은 해당 ControlType 에 유효한 control 레벨 필드 패치이며, 어떤 엔진 스키마에든 정의된 필드명만 검증을 통과한다(예: ControlKey, DefaultValue, 이벤트 바인딩). ★ UseMove/MoveSteps 같은 Step 이동(Group 레벨) 기능은 atom 컨트롤이 아니라 Group(molecule 의 root anchor / raw Group)에 주입한다. 배열 필드는 deep-merge 가 아니라 통째 교체된다. props 로 충분한 일반 케이스엔 쓰지 않는다.",
+      "examples": [{ "root": { "UseClickEvent": true, "Events": { "Click": "openDetail" } } }]
+    }
+  },
+  "examples": [
+    { "label": "승인", "color": "green", "size": "md" },
+    { "label": "반려", "color": "red", "size": "md" },
+    { "label": "대기", "color": "gray", "size": "md" },
+    { "label": "NEW", "color": "blue", "size": "lg" },
+    { "label": "{{공지}}", "color": "black", "size": "md" }
+  ]
+}

package/contract-data/schema/v1/patterns/atom/button.materialize.mjs

@@ -0,0 +1,91 @@
+// button.materialize.mjs
+// pattern.atom.button — DESIGN.md §Buttons 토큰 매핑.
+// v1 엔진에 Button ControlType 이 없으므로 Label + UseClickEvent 패턴.
+
+import { makeLabel, makeMoveSteps } from "../_base.controls.mjs";
+import { generateId } from "../_base.id.mjs";
+import { font, border, bg, padding, tokens } from "../_base.style.mjs";
+import { makeOverride } from "../_base.additional-meta.mjs";
+
+// variant → 색 토큰. DESIGN.md §Buttons.
+//
+// - primary:   surface.brand 채움 + on-brand 글자 (Main / White).
+// - secondary: surface 흰 카드 + border.strong 1px hairline + text.primary 검정 글자.
+// - tertiary:  배경 투명 + Main 글자 (tokens.json#/color main 슬롯).
+const VARIANT = Object.freeze({
+  primary: {
+    bg: "surface.brand",
+    fontColor: "text.on-brand",
+    borderColor: null,
+  },
+  secondary: {
+    bg: "surface",
+    fontColor: "text.primary",
+    borderColor: "border.strong",
+  },
+  tertiary: {
+    bg: null,
+    fontColor: tokens.slot.main,
+    borderColor: null,
+  },
+});
+
+// CTA 표준 사이즈 (DESIGN.md §Do's: BorderRadius "8", FontSize "16", FontWeight SemiBold).
+const HEIGHT_FIXED = Object.freeze({
+  SizeValue: "48",
+  SizeUnit: "px",
+  MatchText: false,
+});
+
+// width="fit": Width 메타를 MatchText 로 두면 엔진이 content + padding 으로 측정.
+const WIDTH_FIT = Object.freeze({
+  MatchText: true,
+  SizeValue: "",
+  SizeUnit: "text",
+});
+
+export default function materialize(props, ctx) {
+  const { label, variant, width, onClick, moveStep } = props;
+  const ov = makeOverride(props.override, "button");
+  const v = VARIANT[variant];
+  if (!v) {
+    throw new Error(`button.materialize: unknown variant '${variant}'`);
+  }
+
+  const out = {
+    ...makeLabel({ name: "Button", text: label }),
+    Id: generateId(ctx),
+    Height: { ...HEIGHT_FIXED },
+    FontStyle: font({
+      size: "title-medium", // 16 / SemiBold
+      weight: "SemiBold",
+      color: v.fontColor,
+      align: "center",
+    }),
+    BorderStyle: border({ radius: 8, color: v.borderColor }),
+    BgStyle: bg(v.bg),
+    Padding: padding({ y: "md", x: "lg" }), // 12 × 16
+  };
+
+  // width="full" → factory default Width(100%) 유지. "fit" → MatchText 로 덮음.
+  if (width === "fit") {
+    out.Width = { ...WIDTH_FIT };
+  }
+
+  // 핸들러 미지정 → 시각적 버튼. 지정 시 Label 의 click 패턴 활성.
+  if (onClick != null && onClick !== "") {
+    out.UseClickEvent = true;
+    out.Events = { Click: onClick };
+  }
+
+  // moveStep 지정 → 클릭 시 해당 Step 으로 이동 (Label.UseMove). onClick 과
+  // 함께 쓰면 엔진은 UseMove 를 먼저 처리한다 (label.schema 설명).
+  if (moveStep != null && moveStep !== "") {
+    out.UseMove = true;
+    out.MoveSteps = makeMoveSteps(moveStep);
+  }
+
+  const result = ov.apply("root", out);
+  ov.finalize(["root"]);
+  return result;
+}

package/contract-data/schema/v1/patterns/atom/button.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/patterns/atom/button.schema.json",
+  "title": "pattern.atom.button",
+  "description": "버튼 액션 아톰. v1 엔진에 'Button' ControlType 이 없으므로 Label + UseClickEvent 패턴으로 materialize. 시각적 강조 수준(variant) 3종 — primary 는 화면당 1개 CTA 권장(`Step.FixedContentsBottom` 자리), secondary 는 보조 액션, tertiary 는 인라인 텍스트 액션. 너비는 full(100%) 또는 fit(content + padding) 두 가지. 라운드/타이포/색은 DESIGN.md §Buttons + §Do's 기준이라 prop 으로 노출하지 않는다.",
+  "x-tier": "atom",
+  "x-tags": ["button", "action", "cta"],
+  "x-related": [],
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["label", "variant", "width"],
+  "properties": {
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 40,
+      "description": "버튼에 표시할 텍스트. 다국어 토큰 `{{key}}` 또는 데이터 바인딩 `{=Field}` 사용 가능."
+    },
+    "variant": {
+      "type": "string",
+      "enum": ["primary", "secondary", "tertiary"],
+      "description": "시각적 강조 수준. primary=Main 채움 + 흰 글자(CTA 표준) / secondary=흰 배경 + 1px Gray4 hairline + 검정 글자(보조 액션) / tertiary=투명 배경 + Main 글자(인라인 텍스트 액션)."
+    },
+    "width": {
+      "type": "string",
+      "enum": ["full", "fit"],
+      "description": "full=부모 너비 100% (CTA 표준 — Bottom 바, 폼 제출) / fit=내용 + padding 만큼(인라인 액션, 카드 내부 보조 버튼). fit 은 Width 메타를 MatchText 로 두어 엔진이 자동 측정."
+    },
+    "onClick": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100,
+      "description": "(선택) 클릭 핸들러 이름. `scenario.Events` 에 정의된 핸들러 키 — [event-ref] 룰로 정합 검증. 미지정 시 UseClickEvent:false (시각적 버튼만)."
+    },
+    "moveStep": {
+      "type": "string",
+      "pattern": "^Step[1-9][0-9]*$",
+      "description": "(선택) 클릭 시 이동할 대상 Step ID (예: 'Step3'). 지정 시 UseMove:true + MoveSteps 자동 생성 (해당 Step 으로 MoveTo:Next, Direction:toRight 단순 이동). onClick 과 함께 쓰면 엔진이 UseMove 를 먼저 처리. 더 복잡한 조건/방향은 override 로 MoveSteps 를 직접 지정."
+    },
+    "override": {
+      "type": "object",
+      "propertyNames": { "enum": ["root"] },
+      "additionalProperties": { "type": "object" },
+      "description": "(L1 escape hatch) 패턴이 노출하지 않는 raw 엔진 메타데이터를 materialized 결과 노드에 deep-merge 로 주입한다. 이 패턴은 단일 컨트롤이라 anchor 는 'root'(결과 노드 자체) 하나. 값은 해당 ControlType 에 유효한 control 레벨 필드 패치이며, 어떤 엔진 스키마에든 정의된 필드명만 검증을 통과한다(예: ControlKey, DefaultValue, 이벤트 바인딩). ★ UseMove/MoveSteps 같은 Step 이동(Group 레벨) 기능은 atom 컨트롤이 아니라 Group(molecule 의 root anchor / raw Group)에 주입한다. 배열 필드는 deep-merge 가 아니라 통째 교체된다. props 로 충분한 일반 케이스엔 쓰지 않는다.",
+      "examples": [{ "root": { "ControlKey": "ReadOnly" } }]
+    }
+  },
+  "examples": [
+    {
+      "label": "로그인",
+      "variant": "primary",
+      "width": "full",
+      "onClick": "submitLogin"
+    },
+    { "label": "{{취소}}", "variant": "secondary", "width": "fit" },
+    {
+      "label": "건너뛰기",
+      "variant": "tertiary",
+      "width": "fit",
+      "onClick": "skipStep"
+    },
+    {
+      "label": "조회",
+      "variant": "primary",
+      "width": "full",
+      "onClick": "runQuery"
+    },
+    { "label": "다음", "variant": "primary", "width": "full", "moveStep": "Step3" }
+  ]
+}

package/contract-data/schema/v1/patterns/atom/checkbox.materialize.mjs

@@ -0,0 +1,40 @@
+// checkbox.materialize.mjs
+// pattern.atom.checkbox — 단일 체크박스 + 라벨.
+//
+// Expo 디자인 — 체크 시 박스 내부가 Ink(var(--colorBlack)) 으로 채워지므로
+// ItemBgStyle.ItemBgColor 를 var(--colorBlack) 로 박는다. 나머지(체크 아이콘 색, 외곽선)
+// 은 엔진 기본값에 맡긴다.
+
+import { makeCheckBox } from "../_base.controls.mjs";
+import { generateId } from "../_base.id.mjs";
+import { font, tokens } from "../_base.style.mjs";
+import { makeOverride } from "../_base.additional-meta.mjs";
+
+// Expo 검정 채움 — DESIGN.md §Colors §Text 의 Ink (tokens.json#/color ink).
+const ITEM_BG_INK = Object.freeze({
+  ItemBgColor: tokens.slot.ink,
+  UseItemBackground: true,
+});
+
+export default function materialize(props, ctx) {
+  const { label, size = 16 } = props;
+  const ov = makeOverride(props.override, "checkbox");
+
+  const out = {
+    ...makeCheckBox({
+      name: "Checkbox",
+      items: [{ ItemName: label, ItemValue: "Y", ItemValueDel: "" }],
+    }),
+    Id: generateId(ctx),
+    FontStyle: font({
+      size, // 숫자 → 명시 FontSize. role 토큰 매칭 안 됨.
+      weight: "Regular",
+      color: "text.primary",
+    }),
+    ItemBgStyle: { ...ITEM_BG_INK },
+  };
+
+  const result = ov.apply("root", out);
+  ov.finalize(["root"]);
+  return result;
+}

package/contract-data/schema/v1/patterns/atom/checkbox.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/patterns/atom/checkbox.schema.json",
+  "title": "pattern.atom.checkbox",
+  "description": "단일 체크박스 아톰. label 옆에 사각 체크박스를 표시한다. Expo 디자인 언어 — 체크 시 박스 내부가 Ink(검정) 으로 채워진다(`ItemBgStyle.ItemBgColor: var(--colorBlack)`). 폼 동의 / 토글 / 선택지 1개에 사용. 다중 선택 그룹은 RadioBox 또는 다중 체크박스 패턴(별도) 사용.",
+  "x-tier": "atom",
+  "x-tags": ["checkbox", "toggle", "form"],
+  "x-related": [],
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["label"],
+  "properties": {
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 60,
+      "description": "체크박스 옆 라벨 텍스트. 다국어 토큰 `{{key}}` 사용 가능."
+    },
+    "size": {
+      "type": "integer",
+      "minimum": 10,
+      "maximum": 32,
+      "default": 16,
+      "description": "텍스트 크기(px). 체크박스 아이콘도 폰트 크기와 함께 스케일. 기본 16."
+    },
+    "override": {
+      "type": "object",
+      "propertyNames": { "enum": ["root"] },
+      "additionalProperties": { "type": "object" },
+      "description": "(L1 escape hatch) 패턴이 노출하지 않는 raw 엔진 메타데이터를 materialized 결과 노드에 deep-merge 로 주입한다. 이 패턴은 단일 컨트롤이라 anchor 는 'root'(결과 노드 자체) 하나. 값은 해당 ControlType 에 유효한 control 레벨 필드 패치이며, 어떤 엔진 스키마에든 정의된 필드명만 검증을 통과한다(예: ControlKey, DefaultValue, 이벤트 바인딩). ★ UseMove/MoveSteps 같은 Step 이동(Group 레벨) 기능은 atom 컨트롤이 아니라 Group(molecule 의 root anchor / raw Group)에 주입한다. 배열 필드는 deep-merge 가 아니라 통째 교체된다. props 로 충분한 일반 케이스엔 쓰지 않는다.",
+      "examples": [{ "root": { "DefaultValue": true } }]
+    }
+  },
+  "examples": [
+    { "label": "약관에 동의합니다" },
+    { "label": "기억하기", "size": 14 },
+    { "label": "{{필수항목동의}}", "size": 16 }
+  ]
+}