@flextudio/scenario 0.1.0

package/contract-data/schema/v1/step.schema.json

@@ -0,0 +1,258 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/step.schema.json",
+  "title": "Step",
+  "description": "Steps[StepId] 의 값. StepType 누락 시 런타임은 StepView 로 처리.",
+  "type": "object",
+  "additionalProperties": true,
+
+  "properties": {
+    "StepType": {
+      "type": "string",
+      "enum": ["StepView", "StepDialog", "StepSub"],
+      "description": "누락 시 런타임은 StepView 로 처리. AI 생성 시 StepView 명시 권장."
+    },
+    "StepDialogType": {
+      "type": "string",
+      "enum": ["", "SlideUp", "PopUp"],
+      "description": "StepView 의 다이얼로그 변종. '' = 일반 화면, SlideUp = 바텀시트, PopUp = 중앙 팝업."
+    },
+    "StepName":  { "type": "string", "description": "내부 표시명 (디자인 탭 '스텝명')." },
+    "StepTitle": { "type": "string", "description": "상단 헤더 타이틀. UseStepHeader=true 일 때 표시." },
+    "StepRow":   { "type": "number", "description": "그리드 좌표." },
+    "StepCol":   { "type": "number", "description": "그리드 좌표." },
+
+    "Contents":            { "type": "array", "items": { "$ref": "group.schema.json" } },
+    "FixedContentsTop":    { "type": "array", "items": { "$ref": "group.schema.json" } },
+    "FixedContentsBottom": { "type": "array", "items": { "$ref": "group.schema.json" } },
+
+    "Padding": {
+      "$ref": "style-objects.schema.json#/$defs/spacing",
+      "$comment": "디자인 탭 '패딩(T,R,B,L)' 토글 ON 시 등장. OFF 시 키 자체 누락 — 런타임 기본값 padding: .5rem 1.25rem 0 1.25rem 적용."
+    },
+    "Margin":  { "$ref": "style-objects.schema.json#/$defs/spacing" },
+    "BgStyle": {
+      "$ref": "style-objects.schema.json#/$defs/bgStyle",
+      "$comment": "디자인 탭 '배경' 토글 ON 시 등장. OFF 시 키 자체 누락."
+    },
+
+    "UseStepHeader": { "type": "boolean", "description": "상단 헤더 사용. 디자인 탭 토글." },
+
+    "Next": {
+      "type": "array",
+      "description": "다음 Step 후보의 StepId 배열. forward-only. StepSub Step 에서는 사용 X.",
+      "items": { "type": "string", "pattern": "^Step[1-9][0-9]*$" }
+    },
+
+    "UseBackButton": {
+      "type": "boolean",
+      "description": "뒤로가기 토글. 디자인 ↔ 데이터 탭 공통. **StepSub 에서는 false 자동 강제**."
+    },
+    "BackButton": {
+      "type": "object",
+      "description": "뒤로가기 버튼. UseBackButton=true 일 때 동반 등장. 데이터 탭에서 세부 설정.",
+      "additionalProperties": true,
+      "properties": {
+        "Next": {
+          "description": "Step 모드의 이동 대상. \"None\" = 직전 스텝(PrevStack), 또는 본인 외 StepId 지정 가능. 자기 자신 StepId 참조 금지 (validate.mjs 후검증).",
+          "anyOf": [
+            { "type": "string", "const": "None" },
+            { "type": "string", "pattern": "^Step[1-9][0-9]*$" }
+          ]
+        },
+        "IsRestored": {
+          "type": "boolean",
+          "description": "콜렉션 이전 상태로 복원하기 토글. true=복원(취소 흐름), false=변경 유지(상세 화면 등)."
+        },
+        "BackButtonMode": {
+          "type": "string",
+          "enum": ["Step", "event"],
+          "description": "Step=이전 스텝 이동 (Next/IsRestored 적용). event=이벤트 실행 (BackButtonEvent 의 이벤트가 동작 제어 — 별도 추가 뒤로가기 동작 없음)."
+        },
+        "BackButtonEvent": {
+          "type": "string",
+          "description": "BackButtonMode='event' 일 때 실행할 이벤트 이름. 사용 안 할 때는 문자열 \"undefined\"."
+        }
+      }
+    },
+
+    "UseBottomButton": {
+      "type": "boolean",
+      "description": "하단 버튼 사용. **StepSub 에서는 false 자동 강제**."
+    },
+    "StepButton":      { "type": "object" },
+    "BottomButtons":   { "type": "array", "items": { "$ref": "bottom-buttons.schema.json" } },
+
+    "UseEvents": {
+      "type": "boolean",
+      "description": "Step 이벤트 사용. **StepSub 에서는 false 자동 강제**."
+    },
+    "Events": {
+      "description": "Step 이벤트 핸들러 맵. const.js STEP_EVENT 6종 + ScrollEnd. 자세한 명세는 step.md §Step Events 상세 명세. UseEvents=true 면 객체, false 면 빈 배열.",
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "UseEvents=true. StepEventOrder enum 으로 활성화 + 이벤트별 핸들러명 (scenario.Events 키 참조).",
+          "additionalProperties": false,
+          "properties": {
+            "StepEventOrder": {
+              "type": "array",
+              "uniqueItems": true,
+              "description": "활성화할 이벤트 enum. 여기 든 이벤트만 호출됨. const.js STEP_EVENT + ScrollEnd.",
+              "items": {
+                "type": "string",
+                "enum": ["Init", "Loaded", "OnBackLoaded", "OnLeave", "OnForeground", "ScrollEnd"]
+              }
+            },
+            "Init":         { "type": "string", "description": "Step 로드 직전 (DOM 그려지기 전). 샘플 데이터 / 카테고리 초기화 (`removeCategory + createCategory + addSector`)." },
+            "Loaded":       { "type": "string", "description": "Step UI 모두 그려진 후. DOM 의존 셋업 (Chart.js / Map / Canvas / Timer / CDN 라이브러리 로드)." },
+            "OnBackLoaded": { "type": "string", "description": "뒤로가기로 이 Step 복원 직후. 데이터 갱신 / 지도 재렌더링 — Init/Loaded 와 별개로 매 복귀 시 호출." },
+            "OnLeave":      { "type": "string", "description": "이 Step 이탈 직전 (Next/Back). Cleanup (`clearInterval` / 외부 SDK destroy)." },
+            "OnForeground": { "type": "string", "description": "**모바일 한정** — 앱이 백그라운드 → 포그라운드 복귀 시. 푸시 후 데이터 동기화 등." },
+            "ScrollEnd":    { "type": "string", "description": "Step 영역 스크롤이 끝까지 닿았을 때. 무한 스크롤 / 페이지네이션." }
+          },
+          "allOf": [
+            { "$comment": "EventOrder 의 각 이벤트는 동명 핸들러 키 필수.",
+              "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "Init"         } } }, "required": ["StepEventOrder"] }, "then": { "required": ["Init"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "Loaded"       } } }, "required": ["StepEventOrder"] }, "then": { "required": ["Loaded"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "OnBackLoaded" } } }, "required": ["StepEventOrder"] }, "then": { "required": ["OnBackLoaded"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "OnLeave"      } } }, "required": ["StepEventOrder"] }, "then": { "required": ["OnLeave"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "OnForeground" } } }, "required": ["StepEventOrder"] }, "then": { "required": ["OnForeground"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "ScrollEnd"    } } }, "required": ["StepEventOrder"] }, "then": { "required": ["ScrollEnd"] } }
+          ]
+        },
+        {
+          "type": "array",
+          "description": "UseEvents=false. 빈 배열로 둠. (`Events` 키 자체 누락 시 런타임 에러.)",
+          "maxItems": 0
+        }
+      ]
+    },
+
+    "Height": {
+      "$ref": "style-objects.schema.json#/$defs/sizeObject",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 디자인 탭에서 SlideUp/PopUp 선택 시만 노출. (Width 는 Step 차원에서 작성 금지 — SlideUp/PopUp 모두 항상 전체 너비 사용.)"
+    },
+    "PopupPosition": {
+      "type": "string",
+      "enum": ["Centered", "Top Left", "Top Center", "Top Right", "Bottom Left", "Bottom Center", "Bottom Right"],
+      "$comment": "PopUp 전용. 위치 지정."
+    },
+    "hideDlgHeader": {
+      "type": "boolean",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 헤더 숨김 토글."
+    },
+    "useDim": {
+      "type": "boolean",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 어두운 배경 dim 사용."
+    },
+    "dimTransp": {
+      "type": "number",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. dim 투명도 (0 ~ 1)."
+    },
+    "bgTransparent": {
+      "type": "boolean",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 배경 투명 토글."
+    },
+
+    "ScenarioId": {
+      "type": "string",
+      "description": "StepSub 의 호출 대상 시나리오 ID. 형식: 'flex||<숫자_숫자>' 또는 직접입력 문자열."
+    },
+    "ScenarioIdText": {
+      "type": "string",
+      "description": "StepSub 의 시나리오 ID 직접입력 모드 텍스트."
+    },
+    "Protocol": {
+      "type": "object",
+      "description": "StepSub 전용. 호출 시나리오 프로토콜. 참조.",
+      "additionalProperties": true,
+      "properties": {
+        "Protocol":     { "type": "string", "$comment": "레거시 호환. 보통 'Original' 고정." },
+        "StartStep":    { "type": "string", "description": "호출할 서브 시나리오의 시작 StepId." },
+        "StartStepText":{ "type": "string", "description": "StartStep 직접입력 모드 텍스트." },
+        "InitType": {
+          "type": "string",
+          "enum": ["Original", "Parent", "Current"],
+          "description": "Init(처음)으로 돌아갈 시나리오. Original=최상위, Parent=현재, Current=서브."
+        },
+        "UseBackButton": {
+          "type": "boolean",
+          "description": "호출한 시나리오로 돌아가기 허용 (UI 토글)."
+        },
+        "UseCopyCollectionToSub": {
+          "type": "boolean",
+          "description": "서브시나리오로 현재 콜렉션 전달."
+        },
+        "TargetStatusToSub": {
+          "type": "string",
+          "enum": ["all", "active", "selected", "last", "added", "updated", "deleted"],
+          "description": "콜렉션 전달 Status 필터. 기본 All."
+        },
+        "UseCopyCollectionToOrigin": {
+          "type": "boolean",
+          "description": "서브시나리오의 콜렉션으로 대체하기."
+        },
+        "TargetStatusToOrigin": {
+          "type": "string",
+          "enum": ["all", "active", "selected", "last", "added", "updated", "deleted"],
+          "description": "콜렉션 대체 Status 필터. 기본 All."
+        },
+        "beforeLoadSubScenario": {
+          "type": "string",
+          "description": "서브시나리오 로드 전 실행 스크립트. (afterLoadSubScenario 는 메타에 존재하지 않음.)"
+        }
+      }
+    },
+    "SubBackup": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "StepView ↔ StepSub 전환 시 이전 상태 복원용 백업 객체. 예: { UseBackButton: true, Contents: [] }. 직접 편집 금지 — 스튜디오가 자동 관리."
+    }
+  },
+
+  "allOf": [
+    {
+      "$comment": "StepSub 일 때 Protocol 필수.",
+      "if": {
+        "properties": { "StepType": { "const": "StepSub" } },
+        "required": ["StepType"]
+      },
+      "then": { "required": ["Protocol"] }
+    },
+    {
+      "$comment": "다이얼로그(SlideUp/PopUp) 가 아니면 다이얼로그 전용 키들 등장 금지. (Width 는 모든 Step 에서 작성 금지 — properties 에서 제거되어 strict-fields 단계에서 차단.)",
+      "if": {
+        "not": {
+          "properties": { "StepDialogType": { "enum": ["SlideUp", "PopUp"] } },
+          "required": ["StepDialogType"]
+        }
+      },
+      "then": {
+        "allOf": [
+          { "not": { "required": ["hideDlgHeader"] } },
+          { "not": { "required": ["useDim"] } },
+          { "not": { "required": ["dimTransp"] } },
+          { "not": { "required": ["bgTransparent"] } },
+          { "not": { "required": ["Height"] } }
+        ]
+      }
+    },
+    {
+      "$comment": "PopUp 이 아니면 PopupPosition 등장 금지 (PopUp 전용).",
+      "if": {
+        "not": {
+          "properties": { "StepDialogType": { "const": "PopUp" } },
+          "required": ["StepDialogType"]
+        }
+      },
+      "then": {
+        "allOf": [
+          { "not": { "required": ["PopupPosition"] } }
+        ]
+      }
+    }
+  ],
+
+  "$comment": "BottomButton 단일 항목 스키마는 bottom-buttons.schema.json 으로 분리."
+}

package/contract-data/schema/v1/style-objects.md

@@ -0,0 +1,183 @@
+# Style Objects (style-objects.schema.json)
+
+Group / Control / BottomButton 등에서 **반복적으로 등장하는 디자인/레이아웃 객체**를 한 곳에 모은 카탈로그. 다른 schema는 `$ref` 로 참조한다. 모든 정의는 `style-objects.schema.json#/$defs/<name>` 형태.
+
+> **데이터 관련 객체** (`dataConnection`, `sectorFilter`, DataUsage 분기, Filter 카탈로그) 는 별도 `data-objects.{schema.json,md}` 에 정의됨. 본 파일은 디자인/레이아웃만 다룸.
+
+## 1. `sizeObject` — Width / Height
+
+```jsonc
+{
+  "MatchText": false,
+  "SizeValue": 100,        // number 또는 string
+  "SizeUnit": "%"          // %, px, vh, vw, text
+}
+```
+
+규칙:
+- `MatchText: true` → 컨텐츠에 맞춤. `SizeValue` 는 무시되고 보통 빈 문자열 `""`.
+- `SizeUnit: "text"` → MatchText 모드에서 자주 사용 (예: 라벨 너비 = 텍스트 길이).
+- `calc()` 표현 사용 가능: `"SizeValue": "calc(100% - 40px)"` (`+`/`-` 좌우 공백 필수).
+
+## 2. `spacing` — Padding / Margin / AbsolutePosition
+
+```jsonc
+{
+  "UseAuto": true,
+  "UseEach": true,
+  "All": "",
+  "Top": "10",
+  "Right": "8",
+  "Btm": "10",
+  "Left": "8",
+  "SizeUnit": "px"
+}
+```
+
+규칙:
+- **하단 키 명명: `Btm`** 사용 (Padding/Margin/AbsolutePosition). BorderStyle만 `Bottom` 사용.
+- 사용하지 않는 방향은 키 자체를 **생략**. 빈 문자열 `""` 은 "미설정"으로 동작 안 함.
+- `UseEach: true` → 방향별로 다른 값. `UseEach: false` → `All` 만 사용.
+
+## 3. `absolutePosition` — 절대 위치 오버레이
+
+`spacing` 과 동일 구조. 사용처:
+
+```jsonc
+{
+  "UseAbsoluteLayout": true,
+  "AbsolutePosition": { "Btm": "20", "Right": "20", "SizeUnit": "px" }
+}
+```
+
+상단/하단, 좌측/우측 동시 설정 불가 (한쪽만).
+
+## 4. `displayStyle` — Flex/Display 레이아웃
+
+```jsonc
+{
+  "UseDisplay": true,
+  "DisplayType": "Flex",
+  "FlexDirection": "column",          // row | column | wrap
+  "FlexWrap": false,
+  "DisplayAlign": "Left",             // Left | Center | Right | Between
+  "DisplayVerticalAlign": "Top",      // Top | Center | Bottom
+  "flexBoxType": "align",
+  "columnGapValue": "8", "columnGapUnit": "px",
+  "rowGapValue": "8",    "rowGapUnit": "px"
+}
+```
+
+## 5. `fontStyle`
+
+```jsonc
+{
+  "UseFont": true,
+  "FontColor": "var(--colorBlack)",   // 권장 토큰 (§10 컬러 카탈로그). legacy @colorBlack 도 통용.
+  "FontSize": "14",
+  "FontWeight": "Medium",             // Regular | Medium | SemiBold | Bold
+  "FontAlign": "flex-start",          // flex-start | center | flex-end
+  "UseBold": false
+}
+```
+
+## 6. `borderStyle`
+
+```jsonc
+{
+  "Useborder": true,
+  "BorderColor": "var(--colorGray3)",
+  "BorderSize": 1,
+  "BorderType": "solid",
+  "SizeSet": "All",                   // All | Top | Right | Bottom | Left
+  "BorderRadius": "8",
+  "RadiusSet": "All"
+}
+```
+
+**주의:** BorderStyle은 하단 키를 `Bottom` 으로 쓴다 (Padding/Margin/AbsolutePosition은 `Btm`).
+
+## 7. `bgStyle`
+
+```jsonc
+{
+  "UseBackground": true,
+  "BgColor": "var(--colorWhite)",
+  "UseImage": false,
+  "Image": {}
+}
+```
+
+## 8. `captionStyle`
+
+```jsonc
+{
+  "UseDesign": true,
+  "FontWeight": "SemiBold",
+  "CaptionPosition": "",              // "" | Left | Top
+  "FontSize": "13",
+  "FontAlign": "flex-start"
+}
+```
+
+`CaptionPosition` 값:
+- `""` — `styleInputValueLine` 기본 (스타일이 캡션 자체 렌더링)
+- `"Left"` — 입력 옆
+- `"Top"` — 입력 위 (row 레이아웃)
+
+## 9. 데이터 바인딩은 별도 파일
+
+`dataConnection`, `sectorFilter`, DataUsage 분기, Filter 카탈로그 등 **데이터 관련 객체는 `data-objects.{schema.json,md}` 로 분리**되어 있다. 본 파일은 디자인/레이아웃 객체만 다룸.
+
+## 10. `colorToken` — 권장 컬러 토큰 카탈로그
+
+`$defs/colorToken` 에 enum 으로 정의. AI 생성 시 `BgColor`, `FontColor`, `BorderColor` 에 이 토큰 사용 권장. 실 메타는 hex(`#000`), legacy(`@colorBlack`), 임의 `var()` 도 통용 — schema 는 string 으로 유지.
+
+| 토큰 | 용도 |
+|---|---|
+| `var(--colorMain)` | Primary brand color |
+| `var(--colorMainLight)` | Primary light background |
+| `var(--colorWhite)` | White |
+| `var(--colorBlack)` | Black (강조 텍스트, 아이콘) |
+| `var(--colorGray1)` | Darkest gray (primary text) |
+| `var(--colorGray2)` | Dark gray (secondary text) |
+| `var(--colorGray3)` | Medium gray (tertiary text) |
+| `var(--colorGray4)` | Light gray (disabled, placeholder) |
+| `var(--colorGray5)` | Lighter gray (border, divider) |
+| `var(--colorGray9)` | Near-white gray (background) |
+| `var(--colorGray10)` | Lightest gray (tag background) |
+| `var(--colorRed)` | Error / Delete |
+| `var(--colorRedLight)` | Error background |
+| `var(--colorBlue)` | Info / Link |
+| `var(--colorBlueLight)` | Info background |
+| `var(--colorGreen)` | Success / Approved |
+| `var(--colorGreenLight)` | Success background |
+| `var(--colorOrange)` | Warning / Required indicator |
+| `var(--colorPurple)` | Accent |
+| `var(--colorPurpleLight)` | Accent background |
+| `var(--colorYellow)` | Caution / Pending |
+| `var(--colorYellowLight)` | Caution background |
+| `var(--colorMint)` | Mint / Complete |
+| `var(--colorMintLight)` | Mint background |
+| `var(--colorSub0)` | Supplementary color 0 |
+| `var(--colorSub0Light)` | Supplementary color 0 background |
+| `var(--colorSub1)` | Supplementary color 1 |
+| `var(--colorSub3)` | Supplementary color 3 |
+
+총 28개 토큰. catalog.json `colorTokens` 와 동기화.
+
+### 허용되는 색상 값 형태
+
+`BgColor` / `FontColor` / `BorderColor` 등 모든 색상 필드는 `type: string` 으로 자유. 다음 형태 모두 허용:
+
+| 형태 | 예시 | 비고 |
+|---|---|---|
+| 권장 토큰 | `var(--colorMain)`, `var(--colorOrange)` | 위 28개 |
+| Hex | `#333333`, `#000`, `#abc` | 3/6 자리 모두 OK |
+| Hex + alpha | `#33333380` | 8자리 |
+| RGB / RGBA | `rgb(255, 0, 0)`, `rgba(33, 21, 7, 0.654)` | |
+| HSL / HSLA | `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)` | |
+| Legacy 토큰 | `@colorBlack`, `@colorMain` | 운영 메타에서 등장 |
+| CSS keyword | `red`, `white`, `transparent` | |
+
+→ schema 는 strict enum 강제 안 함. `$defs/colorToken` 은 **AI 생성 가이드** 역할이며, AI가 우선 권장 토큰 중 선택하고, 토큰에 없는 디자인 요청(예: "정확히 #ff5733") 만 hex/rgba 로 폴백.

package/contract-data/schema/v1/style-objects.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/style-objects.schema.json",
+  "title": "Style Objects",
+  "description": "Group/Control/BottomButton 등에서 공통 사용되는 스타일/레이아웃 객체 카탈로그. 모든 객체는 additionalProperties: true (런타임에서 추가 키를 무시하지 않으므로 유연성 유지).",
+
+  "$defs": {
+    "colorToken": {
+      "type": "string",
+      "description": "권장 컬러 토큰. AI 생성 시 이 enum 값들 중에서 선택 권장. 단 BgColor/FontColor/BorderColor 등 색상 필드는 type:string 으로 두며 다음 형태 모두 허용: ① 토큰(`var(--colorMain)`), ② hex(`#333333`, `#000`, `#abc`), ③ rgb/rgba(`rgb(255,0,0)`, `rgba(33,21,7,0.654)`), ④ hsl/hsla, ⑤ legacy(`@colorBlack`), ⑥ CSS color keyword(`red`, `transparent`).",
+      "enum": [
+        "var(--colorMain)",       "var(--colorMainLight)",
+        "var(--colorWhite)",      "var(--colorBlack)",
+        "var(--colorGray1)",      "var(--colorGray2)",      "var(--colorGray3)",
+        "var(--colorGray4)",      "var(--colorGray5)",
+        "var(--colorGray9)",      "var(--colorGray10)",
+        "var(--colorRed)",        "var(--colorRedLight)",
+        "var(--colorBlue)",       "var(--colorBlueLight)",
+        "var(--colorGreen)",      "var(--colorGreenLight)",
+        "var(--colorOrange)",
+        "var(--colorPurple)",     "var(--colorPurpleLight)",
+        "var(--colorYellow)",     "var(--colorYellowLight)",
+        "var(--colorMint)",       "var(--colorMintLight)",
+        "var(--colorSub0)",       "var(--colorSub0Light)",
+        "var(--colorSub1)",       "var(--colorSub3)"
+      ]
+    },
+
+    "sizeObject": {
+      "type": "object",
+      "description": "Width/Height 등 크기 표현. MatchText=true 면 컨텐츠에 맞춤 (SizeValue 무시).",
+      "additionalProperties": false,
+      "properties": {
+        "MatchText": { "type": "boolean" },
+        "SizeValue": { "type": ["number", "string"] },
+        "SizeUnit":  { "type": "string", "examples": ["%", "px", "text"] }
+      }
+    },
+
+    "spacing": {
+      "type": "object",
+      "description": "Padding / Margin / AbsolutePosition 공통 형태. 사용하는 방향만 키 포함. 빈 문자열은 미설정. 하단은 'Btm' 사용 (BorderStyle만 'Bottom').",
+      "additionalProperties": true,
+      "properties": {
+        "UseAuto":  { "type": "boolean" },
+        "UseEach":  { "type": "boolean" },
+        "All":      { "type": "string" },
+        "Top":      { "type": "string" },
+        "Right":    { "type": "string" },
+        "Btm":      { "type": "string" },
+        "Left":     { "type": "string" },
+        "SizeUnit": { "type": "string" }
+      }
+    },
+
+    "absolutePosition": {
+      "allOf": [{ "$ref": "#/$defs/spacing" }],
+      "description": "절대 위치 오버레이. 사용 방향만 키 포함. 값은 '0' 이상의 숫자 문자열."
+    },
+
+    "displayStyle": {
+      "type": "object",
+      "description": "Flex/Display 레이아웃 제어.",
+      "additionalProperties": true,
+      "properties": {
+        "UseDisplay":           { "type": "boolean" },
+        "DisplayType":          { "type": "string", "examples": ["Flex", "None"] },
+        "FlexDirection":        { "type": "string", "examples": ["row", "column", "wrap"] },
+        "FlexWrap":             { "type": "boolean" },
+        "DisplayAlign":         { "type": "string", "examples": ["Left", "Center", "Right", "Between"] },
+        "DisplayVerticalAlign": { "type": "string", "examples": ["Top", "Center", "Bottom"] },
+        "flexBoxType":          { "type": "string", "examples": ["align", "space"] },
+        "columnGapValue":       { "type": "string" },
+        "columnGapUnit":        { "type": "string", "examples": ["px"] },
+        "rowGapValue":          { "type": "string" },
+        "rowGapUnit":           { "type": "string", "examples": ["px"] }
+      }
+    },
+
+    "fontStyle": {
+      "type": "object",
+      "description": "폰트 표현. 색상은 $defs/colorToken 의 var(--colorXxx) 사용 권장 (legacy `@colorXxx` 도 통용).",
+      "additionalProperties": true,
+      "properties": {
+        "UseFont":       { "type": "boolean" },
+        "FontColor":     { "type": "string", "$comment": "권장: $defs/colorToken enum. 실 메타는 hex/legacy 도 통용." },
+        "FontSize":      { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장." },
+        "FontWeight":    { "type": "string", "examples": ["Regular", "Medium", "SemiBold", "Bold"] },
+        "FontAlign":     { "type": "string", "examples": ["flex-start", "center", "flex-end"] },
+        "UseBold":       { "type": "boolean" },
+        "LetterSpacing": { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장.", "description": "자간. ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." }
+      }
+    },
+
+    "borderStyle": {
+      "type": "object",
+      "description": "테두리. 하단은 'Bottom' 사용 (Padding/Margin은 'Btm'). SizeSet/RadiusSet 이 'Each' 면 per-side / per-corner 키 (Top/Right/Bottom/Left, RadiusTopLeft/RadiusTopRight/RadiusBottomLeft/RadiusBottomRight) 가 활성화되고 균일 키 (BorderSize / BorderRadius) 는 '' 로 비움 — 균일 vs 개별은 상호배타.",
+      "additionalProperties": true,
+      "properties": {
+        "Useborder":           { "type": "boolean" },
+        "BorderColor":         { "type": "string", "$comment": "권장: $defs/colorToken enum. 토큰 외 hex(#333333) / rgb·rgba / hsl·hsla / legacy(@colorXxx) / CSS keyword 모두 허용."},
+        "BorderSize":          { "type": ["number", "string"], "description": "균일 두께. SizeSet:'Each' 면 '' 로 비우고 Top/Right/Bottom/Left 사용." },
+        "BorderType":          { "type": "string", "examples": ["solid", "dashed", "dotted"] },
+        "SizeSet":              { "type": "string", "examples": ["All", "Each", "Top", "Right", "Bottom", "Left"], "description": "균일 두께 = 'All', 사이드별 두께 = 'Each' (Top/Right/Bottom/Left 활성)." },
+        "Top":                 { "type": "string", "description": "SizeSet:'Each' 일 때 상단 두께. 미지정은 ''." },
+        "Right":               { "type": "string", "description": "SizeSet:'Each' 일 때 우측 두께. 미지정은 ''." },
+        "Bottom":              { "type": "string", "description": "SizeSet:'Each' 일 때 하단 두께. 미지정은 ''. (★ Padding/Margin 은 'Btm' 사용)" },
+        "Left":                { "type": "string", "description": "SizeSet:'Each' 일 때 좌측 두께. 미지정은 ''." },
+        "BorderRadius":        { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장.", "description": "균일 반경. RadiusSet:'Each' 면 '' 로 비우고 RadiusTopLeft/TopRight/BottomLeft/BottomRight 사용. '9999' 는 자동 RadiusSet:'None' (pill)." },
+        "RadiusSet":           { "type": "string", "examples": ["All", "Each", "None", "Top", "Right", "Bottom", "Left"], "description": "균일 반경 = 'All', 코너별 반경 = 'Each' (RadiusTopLeft 등 활성), pill = 'None'." },
+        "RadiusTopLeft":       { "type": "string", "description": "RadiusSet:'Each' 일 때 좌상단 반경. 미지정은 ''." },
+        "RadiusTopRight":      { "type": "string", "description": "RadiusSet:'Each' 일 때 우상단 반경. 미지정은 ''." },
+        "RadiusBottomLeft":    { "type": "string", "description": "RadiusSet:'Each' 일 때 좌하단 반경. 미지정은 ''." },
+        "RadiusBottomRight":   { "type": "string", "description": "RadiusSet:'Each' 일 때 우하단 반경. 미지정은 ''." }
+      }
+    },
+
+    "bgStyle": {
+      "type": "object",
+      "description": "배경 색/이미지. UseBackground=true 일 때 BgColor 필요.",
+      "additionalProperties": true,
+      "properties": {
+        "UseBackground": { "type": "boolean" },
+        "BgColor":       { "type": "string", "$comment": "권장: $defs/colorToken enum. 토큰 외 hex(#333333) / rgb·rgba / hsl·hsla / legacy(@colorXxx) / CSS keyword 모두 허용."},
+        "UseImage":      { "type": "boolean" },
+        "Image":         { "type": "object" }
+      }
+    },
+
+    "captionStyle": {
+      "type": "object",
+      "description": "Control의 Caption 영역 스타일.",
+      "additionalProperties": true,
+      "properties": {
+        "UseDesign":       { "type": "boolean" },
+        "FontColor":       { "type": "string", "$comment": "권장: $defs/colorToken enum. 토큰 외 hex / rgb / legacy / CSS keyword 도 통용." },
+        "FontWeight":      { "type": "string", "examples": ["Regular", "Medium", "SemiBold", "Bold"] },
+        "CaptionPosition": { "type": "string", "examples": ["", "Left", "Top"] },
+        "FontSize":        { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장." },
+        "FontAlign":       { "type": "string", "examples": ["flex-start", "center", "flex-end"] }
+      }
+    },
+
+    "arrangeItemsStyle": {
+      "type": "object",
+      "description": "탭/리스트 헤더 아이템 정렬·배치. ArrangeItemsType 으로 너비 정책, ArrangeItemsAlign 으로 정렬을 지정.",
+      "additionalProperties": true,
+      "properties": {
+        "UseArrangeItems":   { "type": "boolean" },
+        "ArrangeItemsType":  { "type": "string", "examples": ["MatchText", "EqualDistribution", "Fixed"], "description": "MatchText=텍스트 크기에 맞춤 / EqualDistribution=균등분배 / Fixed=고정 너비." },
+        "ArrangeItemsAlign": { "type": "string", "examples": ["Left", "Center", "Right", "Between"], "description": "헤더 영역 안에서의 정렬." }
+      }
+    }
+  }
+}