sh-ui-cli 0.34.0 → 0.38.0

package/data/changelog/versions.json

@@ -2,6 +2,25 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.38.0",
+      "date": "2026-04-29",
+      "title": "테마 시스템 풀스택 — 5 프리셋 + 풀 토큰 편집기 + 스캐폴드 threading + CSS↔Flutter 변환기",
+      "type": "minor",
+      "highlights": [
+        "**프리셋 5종 (CLI + 플레이그라운드)** — neutral · slate · rose · emerald · violet. `sh-ui create --theme rose` 처럼 짧게 받거나 playground 에서 만든 base64 그대로. 플레이그라운드 토큰 편집기 위쪽 '프리셋' 행 클릭 한 번으로 light/dark/radius 동시 적용. sh-ui-cli/api 가 단일 소스",
+        "**쉬운 / 고급 토글** — 쉬운 모드는 베이스 톤 4(neutral/slate/warm/cool) + 포인트 컬러 1개 픽커(primary-foreground/primary-hover 자동 파생). 고급 모드는 8 카테고리 collapsible 섹션 — 색(15) · 크기 · 테두리 · 그림자 · 타이포 · 여백 · 폰트굵기 · 모션. 모든 슬라이더는 sh-ui Slider 사용",
+        "**그라데이션 빌더 + 슬롯 3개** (primary/surface/overlay) — 각도 슬라이더 + 2 컬러스톱 + 위치 슬라이더 + 라이브 프리뷰. CSS 변수 `--gradient-*` 로 캔버스 흘러감",
+        "**스캐폴드 threading 풀스택** — 색 15 + radius + 9 옵셔널 카테고리 (spacing 11 / typography 8 / weights 4 / controls 3 / borders 2 / durations 3 / shadows 4 / eases 2 / gradients 3). theme JSON 에 키가 있으면 tokens.css / sh_ui_tokens.dart 의 마커 섹션 교체, 없으면 템플릿 디폴트 유지. 디폴트와 다른 카테고리만 base64 에 포함돼 페이로드 최소화",
+        "**CSS↔Flutter 변환기** — shadow `0 1px 2px rgba(0,0,0,0.08)` → `BoxShadow(offset, blurRadius, spreadRadius, color: Color(0x14000000))` (alpha = 0.08 × 255). ease `cubic-bezier(0.4,0,0.2,1)` → `Cubic(0.4,0,0.2,1)` (named easing 도 정확한 4-인자로). gradient `linear-gradient(135deg, ...)` → `LinearGradient(begin: Alignment(-0.707,-0.707), end: Alignment(0.707,0.707), colors, stops)`. CSS deg → Flutter Alignment (0deg=topCenter, 시계방향)",
+        "**확장 색 직접 편집** — background-inverse / foreground-inverse / foreground-subtle 3개를 사용자가 직접 잡음. 기존 Dart 자동 inverse 거울 / 고정 foregroundSubtle 디폴트 폐기. 5 프리셋 light/dark 모두 15키 풀세트",
+        "**Flutter 템플릿** — ShUiGradientTokens 클래스 신설 + ShUiTheme 에 gradient 필드 통합. tokens.css / sh_ui_tokens.dart 에 카테고리별 마커 9쌍 (theme-space/text/weight/shadow/duration/ease/control/border-width/gradient)",
+        "**DatePicker 회귀 픽스 2개** — (1) container prop 누락 → 추가 (Select·Combobox·Popover 와 동일 패턴). 다크 모드를 page subtree 에만 입힌 환경에서 캘린더 popover 가 토큰 스코프 벗어나 흰 배경으로 뜨던 문제 해결. (2) 선택일 색을 --foreground 에서 --primary / --primary-foreground 로 전환 — rose/emerald 같은 primary 변경 프리셋이 캘린더에도 일관되게 반영. **호환성 주의**: primary 를 안 바꾸고 쓰던 사용자는 선택일 색이 검정 → 자기 primary 색으로 변경됨",
+        "**MCP** sh_ui_create_project 의 theme 파라미터가 프리셋 이름 수용 — IDE 에이전트가 `theme: \"slate\"` 한 줄로 호출. 짧은 오타는 base64 디코드 에러 대신 '알 수 없는 테마 프리셋: 지원 목록 …' 친절 안내",
+        "**테스트 104** (전 68 → +36). 옵셔널 카테고리 검증, 빌더 출력 형식, 파서 (rgba alpha / hex 8자리 / spread / multi-shadow / named ease / Alignment 각도 0·45·90·135·180), 잘못된 형식 throw, end-to-end Next + Flutter 스캐폴드 주입. localStorage 마이그레이션 (v0.34 까지 저장된 데이터는 새 키 디폴트 보강)"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.38.0"
+    },
     {
       "version": "0.34.0",
       "date": "2026-04-29",

package/data/registry/react/components/date-picker/index.tsx

@@ -329,6 +329,11 @@ export interface DatePickerProps {
    * @default true
    */
   closeOnSelect?: boolean;
+  /**
+   * Portal이 마운트될 DOM 노드. 토큰 스코프(다크 모드 등) 안에 popover를 띄우려면 해당 컨테이너 ref 전달.
+   * @default document.body
+   */
+  container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
   /**
    * compound 모드. 미지정 시 기본 레이아웃(Trigger + Content + Calendar)이 자동 렌더된다.
    * 직접 조립하려면 `DatePickerTrigger`/`DatePickerContent`/`DatePickerCalendar`/`DatePickerFooter`를 자식으로 넘긴다.
@@ -353,6 +358,7 @@ export function DatePicker({
   "aria-invalid": ariaInvalid,
   className,
   closeOnSelect = true,
+  container,
   children,
 }: DatePickerProps) {
   const isControlled = value !== undefined;
@@ -417,7 +423,7 @@ export function DatePicker({
         {children ?? (
           <>
             <DatePickerTrigger className={className} />
-            <DatePickerContent>
+            <DatePickerContent container={container}>
               <DatePickerCalendar />
             </DatePickerContent>
           </>
@@ -525,19 +531,24 @@ export interface DatePickerContentProps
    * @default "start"
    */
   align?: React.ComponentPropsWithoutRef<typeof BasePopover.Positioner>["align"];
+  /**
+   * Portal이 마운트될 DOM 노드. 토큰 스코프(다크 모드 등) 안에 popover를 띄우려면 해당 컨테이너 ref 전달.
+   * @default document.body
+   */
+  container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
 }
 
 /** 캘린더 popover 본문. portal로 마운트되며 `disabled`/`readOnly`이면 렌더되지 않는다. */
 export const DatePickerContent = React.forwardRef<HTMLDivElement, DatePickerContentProps>(
   function DatePickerContent(
-    { className, children, sideOffset = 4, side = "bottom", align = "start", ...props },
+    { className, children, sideOffset = 4, side = "bottom", align = "start", container, ...props },
     ref,
   ) {
     const ctx = useDatePickerContext("DatePickerContent");
     if (ctx.disabled || ctx.readOnly) return null;
 
     return (
-      <BasePopover.Portal>
+      <BasePopover.Portal container={container}>
         <BasePopover.Positioner
           className="sh-ui-date-picker__positioner"
           sideOffset={sideOffset}
@@ -639,6 +650,11 @@ export interface DateRangePickerProps {
   /** invalid 상태. */
   "aria-invalid"?: boolean | "true";
   className?: string;
+  /**
+   * Portal이 마운트될 DOM 노드. 토큰 스코프(다크 모드 등) 안에 popover를 띄우려면 해당 컨테이너 ref 전달.
+   * @default document.body
+   */
+  container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
 }
 
 /**
@@ -659,6 +675,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
       readOnly,
       "aria-invalid": ariaInvalid,
       className,
+      container,
     },
     ref,
   ) {
@@ -724,7 +741,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
         </BasePopover.Trigger>
 
         {!disabled && !readOnly && (
-          <BasePopover.Portal>
+          <BasePopover.Portal container={container}>
             <BasePopover.Positioner
               className="sh-ui-date-picker__positioner"
               sideOffset={4}

package/data/registry/react/components/date-picker/styles.css

@@ -207,37 +207,37 @@
 }
 
 .sh-ui-calendar__day--selected {
-  background: var(--foreground);
-  color: var(--background);
+  background: var(--primary);
+  color: var(--primary-foreground);
   font-weight: var(--weight-semibold);
 }
 
 .sh-ui-calendar__day--selected:hover:not(:disabled) {
-  background: var(--foreground);
-  opacity: 0.9;
+  background: var(--primary-hover);
+  color: var(--primary-foreground);
 }
 
 /* ── Range ── */
 
 .sh-ui-calendar__day--in-range {
-  background: color-mix(in srgb, var(--foreground) 10%, transparent);
+  background: color-mix(in srgb, var(--primary) 12%, transparent);
   border-radius: 0;
 }
 
 .sh-ui-calendar__day--in-range:hover:not(:disabled) {
-  background: color-mix(in srgb, var(--foreground) 18%, transparent);
+  background: color-mix(in srgb, var(--primary) 22%, transparent);
 }
 
 .sh-ui-calendar__day--range-start {
-  background: var(--foreground);
-  color: var(--background);
+  background: var(--primary);
+  color: var(--primary-foreground);
   font-weight: var(--weight-semibold);
   border-radius: calc(var(--radius) - 2px) 0 0 calc(var(--radius) - 2px);
 }
 
 .sh-ui-calendar__day--range-end {
-  background: var(--foreground);
-  color: var(--background);
+  background: var(--primary);
+  color: var(--primary-foreground);
   font-weight: var(--weight-semibold);
   border-radius: 0 calc(var(--radius) - 2px) calc(var(--radius) - 2px) 0;
 }
@@ -248,8 +248,8 @@
 
 .sh-ui-calendar__day--range-start:hover:not(:disabled),
 .sh-ui-calendar__day--range-end:hover:not(:disabled) {
-  background: var(--foreground);
-  opacity: 0.9;
+  background: var(--primary-hover);
+  color: var(--primary-foreground);
 }
 
 /* ── Hint (range picker) ── */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.34.0",
+  "version": "0.38.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/src/api.d.ts

@@ -40,3 +40,27 @@ export type PluginManifest = {
 };
 
 export const allPlugins: readonly PluginManifest[];
+
+/* ─────── 테마 프리셋 ─────── */
+
+export type ThemePresetName = 'neutral' | 'slate' | 'rose' | 'emerald' | 'violet';
+
+/** decode.js 의 TOKEN_KEYS — light/dark 양쪽이 가져야 하는 키 12개. */
+export type ThemeTokenKey =
+  | 'background' | 'background-subtle' | 'background-muted'
+  | 'foreground' | 'foreground-muted'
+  | 'border' | 'border-strong'
+  | 'primary' | 'primary-foreground' | 'primary-hover'
+  | 'danger' | 'danger-foreground';
+
+export interface ThemePreset {
+  /** UI 에 표시할 사람이 읽는 라벨. */
+  label: string;
+  light: Record<ThemeTokenKey, string>;
+  dark: Record<ThemeTokenKey, string>;
+  /** rem 단위 (0~1.5). */
+  radius: number;
+}
+
+export const THEME_PRESETS: Record<ThemePresetName, ThemePreset>;
+export const THEME_PRESET_NAMES: readonly ThemePresetName[];

package/src/api.js

@@ -19,3 +19,4 @@ export {
 } from './constants.js';
 
 export { allPlugins } from './create/plugins/index.js';
+export { THEME_PRESETS, THEME_PRESET_NAMES } from './create/theme/presets.js';

package/src/create/generator.js

@@ -4,13 +4,32 @@ import fs from 'fs-extra';
 import os from 'node:os';
 import path from 'node:path';
 import { getPluginChoices, getPluginsByNames } from './plugins/index.js';
-import { decodeTheme } from './theme/decode.js';
+import { resolveTheme } from './theme/decode.js';
+import { THEME_PRESETS, getThemePreset } from './theme/presets.js';
 import {
   replaceSection,
   buildCssColorsBlock,
   buildCssRadiusBlock,
+  buildCssSpacingBlock,
+  buildCssTypographyBlock,
+  buildCssWeightsBlock,
+  buildCssControlsBlock,
+  buildCssBordersBlock,
+  buildCssDurationsBlock,
+  buildCssShadowsBlock,
+  buildCssEasesBlock,
+  buildCssGradientsBlock,
   buildDartColorsBlock,
   buildDartRadiusBlock,
+  buildDartSpacingBlock,
+  buildDartTypographyBlock,
+  buildDartWeightsBlock,
+  buildDartControlsBlock,
+  buildDartBordersBlock,
+  buildDartDurationsBlock,
+  buildDartShadowsBlock,
+  buildDartEasesBlock,
+  buildDartGradientsBlock,
 } from './theme/inject.js';
 import { getTemplatesRoot } from '../paths.mjs';
 
@@ -52,7 +71,25 @@ export async function createProject(options = {}) {
     ],
   });
 
-  const theme = options.theme ? decodeTheme(options.theme) : null;
+  let theme = null;
+  if (options.theme) {
+    theme = resolveTheme(options.theme);
+  } else if (process.stdin.isTTY && !options.yes) {
+    // --yes 는 "선택 옵션은 기본값으로" 의미. 테마는 옵션이므로 prompt 우회.
+    const NONE = '__none__';
+    const choice = await select({
+      message: '테마:',
+      default: NONE,
+      choices: [
+        { name: '기본 (테마 없음 — sh-ui 기본 토큰 그대로)', value: NONE },
+        ...Object.entries(THEME_PRESETS).map(([name, preset]) => ({
+          name: preset.label,
+          value: name,
+        })),
+      ],
+    });
+    if (choice !== NONE) theme = getThemePreset(choice);
+  }
 
   // dry-run 은 tmpdir 에 그대로 생성한 뒤 파일 목록 출력 + 정리.
   // 사용자 cwd 를 건드리지 않으면서 실제 generation 흐름을 그대로 검증한다.
@@ -601,6 +638,34 @@ async function applyTransforms(targetDir, plugins) {
 // ─── Theme 주입 ───
 
 /** 여러 후보 경로 중 존재하는 첫 tokens.css 에 theme 주입 */
+/**
+ * 옵셔널 카테고리 → CSS 마커 / 빌더 매핑.
+ * theme 에 카테고리 키가 있을 때만 해당 마커 섹션 교체.
+ */
+const OPTIONAL_CSS_INJECTORS = [
+  ['spacing',    'theme-space',        buildCssSpacingBlock],
+  ['typography', 'theme-text',         buildCssTypographyBlock],
+  ['weights',    'theme-weight',       buildCssWeightsBlock],
+  ['controls',   'theme-control',      buildCssControlsBlock],
+  ['borders',    'theme-border-width', buildCssBordersBlock],
+  ['durations',  'theme-duration',     buildCssDurationsBlock],
+  ['shadows',    'theme-shadow',       buildCssShadowsBlock],
+  ['eases',      'theme-ease',         buildCssEasesBlock],
+  ['gradients',  'theme-gradient',     buildCssGradientsBlock],
+];
+
+const OPTIONAL_DART_INJECTORS = [
+  ['spacing',    'theme-space',        buildDartSpacingBlock],
+  ['typography', 'theme-text',         buildDartTypographyBlock],
+  ['weights',    'theme-weight',       buildDartWeightsBlock],
+  ['controls',   'theme-control',      buildDartControlsBlock],
+  ['borders',    'theme-border-width', buildDartBordersBlock],
+  ['durations',  'theme-duration',     buildDartDurationsBlock],
+  ['shadows',    'theme-shadow',       buildDartShadowsBlock],
+  ['eases',      'theme-ease',         buildDartEasesBlock],
+  ['gradients',  'theme-gradient',     buildDartGradientsBlock],
+];
+
 async function injectCssTheme(projectDir, theme) {
   if (!theme) return;
   const candidates = [
@@ -613,6 +678,11 @@ async function injectCssTheme(projectDir, theme) {
       let css = await fs.readFile(abs, 'utf-8');
       css = replaceSection(css, 'theme-colors', '/*', '*/', buildCssColorsBlock(theme));
       css = replaceSection(css, 'theme-radius', '/*', '*/', buildCssRadiusBlock(theme));
+      for (const [key, marker, builder] of OPTIONAL_CSS_INJECTORS) {
+        if (theme[key]) {
+          css = replaceSection(css, marker, '/*', '*/', builder(theme[key]));
+        }
+      }
       await fs.writeFile(abs, css);
       return;
     }
@@ -629,5 +699,10 @@ async function injectDartTheme(projectDir, theme) {
   let dart = await fs.readFile(abs, 'utf-8');
   dart = replaceSection(dart, 'theme-colors', '//', '', buildDartColorsBlock(theme));
   dart = replaceSection(dart, 'theme-radius', '//', '', buildDartRadiusBlock(theme));
+  for (const [key, marker, builder] of OPTIONAL_DART_INJECTORS) {
+    if (theme[key]) {
+      dart = replaceSection(dart, marker, '//', '', builder(theme[key]));
+    }
+  }
   await fs.writeFile(abs, dart);
 }

package/src/create/index.mjs

@@ -4,9 +4,11 @@ import { parseArgs } from './cli-args.js';
 import { createProject, addApp, addComponent } from './generator.js';
 import { allPlugins } from './plugins/index.js';
 import { CREATE_PLATFORMS, CREATE_STRUCTURES } from '../constants.js';
+import { THEME_PRESET_NAMES } from './theme/presets.js';
 
 const PLUGIN_NAMES = allPlugins.map((p) => p.name);
 const PLUGINS_LIST = PLUGIN_NAMES.join(', ');
+const THEME_PRESETS_LIST = THEME_PRESET_NAMES.join('|');
 
 export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next.js / Flutter)
 
@@ -19,7 +21,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
   --platform <${CREATE_PLATFORMS.join('|')}>          타겟 플랫폼
   --structure <${CREATE_STRUCTURES.join('|')}>  Next.js 프로젝트 구조 (next 일 때)
   --plugins <a,b>                    플러그인 (${PLUGINS_LIST}). 미지정/"" → 없음
-  --theme <base64>                   테마 JSON (base64). 선택
+  --theme <preset|base64>            프리셋 이름(${THEME_PRESETS_LIST}) 또는 playground base64. 선택
   --yes                              디렉토리 덮어쓰기 + 모노레포 기본값 자동 채택
   --dry-run                          파일을 쓰지 않고 작성될 파일 목록만 출력
   -h, --help                         이 도움말
@@ -30,6 +32,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
 예 (비대화형 / 에이전트 / CI):
   sh-ui create my-app --platform next --structure standalone --yes
   sh-ui create my-app --platform next --structure monorepo --plugins ${PLUGIN_NAMES.slice(0, 3).join(',')} --yes
+  sh-ui create my-app --platform next --structure standalone --theme rose --yes
   sh-ui create my-app --platform flutter --yes
 
 비대화형 환경(TTY 없음)에서는 누락된 필수 인자가 있으면 prompt 대신 에러로 종료한다.

package/src/create/theme/decode.js

@@ -1,11 +1,81 @@
+import { getThemePreset, THEME_PRESET_NAMES } from './presets.js';
+
 const TOKEN_KEYS = [
-  'background', 'background-subtle', 'background-muted',
-  'foreground', 'foreground-muted',
+  'background', 'background-subtle', 'background-muted', 'background-inverse',
+  'foreground', 'foreground-muted', 'foreground-subtle', 'foreground-inverse',
   'border', 'border-strong',
   'primary', 'primary-foreground', 'primary-hover',
   'danger', 'danger-foreground',
 ];
 
+/**
+ * 옵셔널 카테고리 검증 — 모두 Record<string, number>.
+ * 카테고리 누락은 OK (스캐폴드 시 해당 블록은 디폴트 유지). 형식만 위배되면 에러.
+ *
+ * 각 카테고리의 expectedKeys 가 정확히 일치해야 함 — 나머지/누락 키 모두 거부.
+ */
+const SCALAR_CATEGORIES = {
+  spacing: ['0', '1', '2', '3', '4', '5', '6', '8', '10', '12', '16'],
+  typography: ['xs', 'sm', 'base', 'lg', 'xl', '2xl', '3xl', '4xl'],
+  weights: ['regular', 'medium', 'semibold', 'bold'],
+  controls: ['sm', 'md', 'lg'],
+  borders: ['width', 'widthStrong'],
+  durations: ['fast', 'base', 'slow'],
+};
+
+/** Phase 3 — 문자열 카테고리. 형식 자체 검증은 inject 빌더에서 (CSS 그대로 통과 + Dart 변환 시 throw). */
+const STRING_CATEGORIES = {
+  shadows: ['sm', 'md', 'lg', 'xl'],
+  eases: ['standard', 'emphasized'],
+  gradients: ['primary', 'surface', 'overlay'],
+};
+
+const validateStringCategory = (name, expectedKeys, value) => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`theme 디코드 실패: ${name} 가 객체가 아님`);
+  }
+  for (const key of expectedKeys) {
+    if (!(key in value)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 누락`);
+    }
+    const v = value[key];
+    if (typeof v !== 'string' || v.length === 0) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 빈 문자열 또는 비-문자열 (받은 값: ${JSON.stringify(v)})`);
+    }
+    if (v.length > 512) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 너무 김 (>512자)`);
+    }
+  }
+  for (const key of Object.keys(value)) {
+    if (!expectedKeys.includes(key)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 는 알 수 없는 키`);
+    }
+  }
+};
+
+const validateScalarCategory = (name, expectedKeys, value) => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`theme 디코드 실패: ${name} 가 객체가 아님`);
+  }
+  for (const key of expectedKeys) {
+    if (!(key in value)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 누락`);
+    }
+    const v = value[key];
+    if (typeof v !== 'number' || Number.isNaN(v) || !Number.isFinite(v)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 유한 숫자가 아님 (받은 값: ${JSON.stringify(v)})`);
+    }
+    if (v < 0) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 음수 (받은 값: ${v})`);
+    }
+  }
+  for (const key of Object.keys(value)) {
+    if (!expectedKeys.includes(key)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 는 알 수 없는 키`);
+    }
+  }
+};
+
 const HEX_REGEX = /^#[0-9A-Fa-f]{6}$/;
 const BASE64_REGEX = /^[A-Za-z0-9+/]*={0,2}$/;
 const MAX_THEME_BYTES = 10 * 1024; // 정상 테마 ~860 바이트. 10KB 면 10× 여유.
@@ -60,7 +130,40 @@ export const decodeTheme = (b64) => {
   if (parsed.radius < 0 || parsed.radius > 1.5) {
     throw new Error(`theme 디코드 실패: radius 가 허용 범위(0~1.5)를 벗어남 (${parsed.radius})`);
   }
+  // 옵셔널 카테고리 — 누락은 OK, 들어 있으면 형식 검증.
+  for (const [category, expectedKeys] of Object.entries(SCALAR_CATEGORIES)) {
+    if (category in parsed) {
+      validateScalarCategory(category, expectedKeys, parsed[category]);
+    }
+  }
+  for (const [category, expectedKeys] of Object.entries(STRING_CATEGORIES)) {
+    if (category in parsed) {
+      validateStringCategory(category, expectedKeys, parsed[category]);
+    }
+  }
   return parsed;
 };
 
-export { TOKEN_KEYS };
+/**
+ * --theme 입력 1개 슬롯에 프리셋 이름과 base64 둘 다 받기 위한 리졸버.
+ * 프리셋 이름이면 미리 정의된 ThemeConfig 를, 그 외엔 base64 로 간주해 decodeTheme 위임.
+ * THEME_PRESET_NAMES 와 base64 알파벳은 둘 다 [a-z]+ 와 충돌하지만 프리셋 사전 매칭이 우선이라
+ * 'rose' 같이 우연히 base64 로도 파싱 가능한 짧은 토큰은 프리셋으로 해석된다 (의도).
+ */
+export const resolveTheme = (input) => {
+  if (typeof input !== 'string') {
+    throw new Error(`theme 입력 실패: 문자열이 아님`);
+  }
+  const preset = getThemePreset(input);
+  if (preset) return preset;
+  // 정상 base64 테마는 200자 이상. 그보다 짧으면 프리셋 오타로 보고 친절한 에러를.
+  if (input.length < 50) {
+    throw new Error(
+      `알 수 없는 테마 프리셋: '${input}'. 지원: ${THEME_PRESET_NAMES.join(', ')} ` +
+      `(또는 playground 에서 생성한 base64).`
+    );
+  }
+  return decodeTheme(input);
+};
+
+export { TOKEN_KEYS, THEME_PRESET_NAMES };

package/src/create/theme/inject.js

@@ -56,40 +56,32 @@ const toDartColor = (hex) => `Color(0xFF${hex.replace('#', '').toUpperCase()})`;
  *   inverse — 반대 모드의 편집값
  *   default — playground 가 노출하지 않음, 고정 기본값 사용
  */
+/**
+ * Dart ShUiColorTokens 필드 매핑. v0.37.0 부터 background-inverse / foreground-inverse /
+ * foreground-subtle 도 사용자가 직접 잡으므로 모두 self 룩업.
+ */
 const DART_FIELD_SOURCES = [
-  { field: 'background',           source: { kind: 'self', key: 'background' } },
-  { field: 'backgroundSubtle',     source: { kind: 'self', key: 'background-subtle' } },
-  { field: 'backgroundMuted',      source: { kind: 'self', key: 'background-muted' } },
-  { field: 'backgroundInverse',    source: { kind: 'inverse', key: 'background' } },
-  { field: 'foreground',           source: { kind: 'self', key: 'foreground' } },
-  { field: 'foregroundMuted',      source: { kind: 'self', key: 'foreground-muted' } },
-  { field: 'foregroundSubtle',     source: { kind: 'default' } },
-  { field: 'foregroundInverse',    source: { kind: 'inverse', key: 'foreground' } },
-  { field: 'border',               source: { kind: 'self', key: 'border' } },
-  { field: 'borderStrong',         source: { kind: 'self', key: 'border-strong' } },
-  { field: 'primary',              source: { kind: 'self', key: 'primary' } },
-  { field: 'primaryForeground',    source: { kind: 'self', key: 'primary-foreground' } },
-  { field: 'primaryHover',         source: { kind: 'self', key: 'primary-hover' } },
-  { field: 'danger',               source: { kind: 'self', key: 'danger' } },
-  { field: 'dangerForeground',     source: { kind: 'self', key: 'danger-foreground' } },
+  { field: 'background',           key: 'background' },
+  { field: 'backgroundSubtle',     key: 'background-subtle' },
+  { field: 'backgroundMuted',      key: 'background-muted' },
+  { field: 'backgroundInverse',    key: 'background-inverse' },
+  { field: 'foreground',           key: 'foreground' },
+  { field: 'foregroundMuted',      key: 'foreground-muted' },
+  { field: 'foregroundSubtle',     key: 'foreground-subtle' },
+  { field: 'foregroundInverse',    key: 'foreground-inverse' },
+  { field: 'border',               key: 'border' },
+  { field: 'borderStrong',         key: 'border-strong' },
+  { field: 'primary',              key: 'primary' },
+  { field: 'primaryForeground',    key: 'primary-foreground' },
+  { field: 'primaryHover',         key: 'primary-hover' },
+  { field: 'danger',               key: 'danger' },
+  { field: 'dangerForeground',     key: 'danger-foreground' },
 ];
 
-const DART_DEFAULTS = {
-  light: { foregroundSubtle: '0xFFA3A3A3' },
-  dark:  { foregroundSubtle: '0xFF737373' },
-};
-
-const buildDartStaticConst = (mode, self, opposite) => {
-  const lines = DART_FIELD_SOURCES.map(({ field, source }) => {
-    switch (source.kind) {
-      case 'self':
-        return `    ${field}: ${toDartColor(self[source.key])},`;
-      case 'inverse':
-        return `    ${field}: ${toDartColor(opposite[source.key])},`;
-      case 'default':
-        return `    ${field}: Color(${DART_DEFAULTS[mode][field]}),`;
-    }
-  }).join('\n');
+const buildDartStaticConst = (mode, self) => {
+  const lines = DART_FIELD_SOURCES.map(({ field, key }) =>
+    `    ${field}: ${toDartColor(self[key])},`,
+  ).join('\n');
   return [
     `  static const ${mode} = ShUiColorTokens(`,
     lines,
@@ -99,9 +91,9 @@ const buildDartStaticConst = (mode, self, opposite) => {
 
 export const buildDartColorsBlock = (theme) => {
   return [
-    buildDartStaticConst('light', theme.light, theme.dark),
+    buildDartStaticConst('light', theme.light),
     '',
-    buildDartStaticConst('dark', theme.dark, theme.light),
+    buildDartStaticConst('dark', theme.dark),
   ].join('\n');
 };
 
@@ -109,3 +101,295 @@ export const buildDartRadiusBlock = (theme) => {
   const px = (theme.radius * 16).toFixed(1);
   return `    defaultRadius: ${px},`;
 };
+
+// ─── 옵셔널 카테고리 빌더 (Phase 2) ───
+//
+// 모두 마커 사이에 들어갈 본문만 만든다. CSS 는 변수 선언 N줄, Dart 는 필드 N줄.
+
+/* --- spacing --- */
+
+const SPACING_KEYS = ['0', '1', '2', '3', '4', '5', '6', '8', '10', '12', '16'];
+
+export const buildCssSpacingBlock = (spacing) =>
+  SPACING_KEYS.map((k) => `  --space-${k}: ${spacing[k]}px;`).join('\n');
+
+export const buildDartSpacingBlock = (spacing) =>
+  SPACING_KEYS.map((k) => `    s${k}: ${spacing[k].toFixed(1)},`).join('\n');
+
+/* --- typography --- */
+
+const TYPOGRAPHY_KEYS = ['xs', 'sm', 'base', 'lg', 'xl', '2xl', '3xl', '4xl'];
+
+export const buildCssTypographyBlock = (typography) =>
+  TYPOGRAPHY_KEYS.map((k) => `  --text-${k}: ${typography[k]}px;`).join('\n');
+
+// Dart 클래스는 'xl2'/'xl3'/'xl4' 명명 규칙 사용 (숫자 prefix 회피).
+const DART_TEXT_FIELD_NAMES = {
+  xs: 'xs', sm: 'sm', base: 'base', lg: 'lg', xl: 'xl',
+  '2xl': 'xl2', '3xl': 'xl3', '4xl': 'xl4',
+};
+
+export const buildDartTypographyBlock = (typography) =>
+  TYPOGRAPHY_KEYS
+    .map((k) => `    ${DART_TEXT_FIELD_NAMES[k]}: ${typography[k].toFixed(1)},`)
+    .join('\n');
+
+/* --- weights --- */
+
+const WEIGHT_KEYS = ['regular', 'medium', 'semibold', 'bold'];
+
+export const buildCssWeightsBlock = (weights) =>
+  WEIGHT_KEYS.map((k) => `  --weight-${k}: ${weights[k]};`).join('\n');
+
+export const buildDartWeightsBlock = (weights) =>
+  WEIGHT_KEYS.map((k) => `    ${k}: FontWeight.w${weights[k]},`).join('\n');
+
+/* --- controls --- */
+
+const CONTROL_KEYS = ['sm', 'md', 'lg'];
+
+export const buildCssControlsBlock = (controls) =>
+  CONTROL_KEYS.map((k) => `  --control-${k}: ${controls[k]}px;`).join('\n');
+
+export const buildDartControlsBlock = (controls) =>
+  CONTROL_KEYS.map((k) => `    ${k}: ${controls[k].toFixed(1)},`).join('\n');
+
+/* --- borders --- */
+
+export const buildCssBordersBlock = (borders) => [
+  `  --border-width: ${borders.width}px;`,
+  `  --border-width-strong: ${borders.widthStrong}px;`,
+].join('\n');
+
+export const buildDartBordersBlock = (borders) => [
+  `    normal: ${borders.width.toFixed(1)},`,
+  `    strong: ${borders.widthStrong.toFixed(1)},`,
+].join('\n');
+
+/* --- durations --- */
+
+const DURATION_KEYS = ['fast', 'base', 'slow'];
+
+export const buildCssDurationsBlock = (durations) =>
+  DURATION_KEYS.map((k) => `  --duration-${k}: ${durations[k]}ms;`).join('\n');
+
+export const buildDartDurationsBlock = (durations) =>
+  DURATION_KEYS
+    .map((k) => `    ${k}: Duration(milliseconds: ${Math.round(durations[k])}),`)
+    .join('\n');
+
+// ─── Phase 3 — string 카테고리: shadow / ease / gradient ───
+//
+// CSS 측은 사용자가 입력한 문자열을 거의 그대로 흘려보내고, Dart 측은 파서를 거쳐
+// BoxShadow / Cubic / LinearGradient 로 변환. 파서는 형식 위배 시 throw.
+
+/* --- 공통 유틸 --- */
+
+/** 괄호 깊이 0 인 위치에서만 콤마로 split. rgba(0,0,0,0.5) 같은 것을 보호. */
+const splitTopLevelByComma = (str) => {
+  const parts = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    if (c === '(') depth++;
+    else if (c === ')') depth--;
+    else if (c === ',' && depth === 0) {
+      parts.push(str.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  parts.push(str.slice(start).trim());
+  return parts.filter(Boolean);
+};
+
+/** 공백 split — 단 괄호 안은 그룹 유지. */
+const tokenizeSpaceAware = (str) => {
+  const tokens = [];
+  let depth = 0, start = 0;
+  const flush = (end) => {
+    const t = str.slice(start, end).trim();
+    if (t) tokens.push(t);
+  };
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    if (c === '(') depth++;
+    else if (c === ')') depth--;
+    else if (/\s/.test(c) && depth === 0) {
+      flush(i);
+      start = i + 1;
+    }
+  }
+  flush(str.length);
+  return tokens;
+};
+
+const cssLengthToPx = (s, ctx) => {
+  const m = s.match(/^(-?[\d.]+)(?:px)?$/);
+  if (!m) throw new Error(`${ctx}: 길이 단위 오류 — '${s}'`);
+  return parseFloat(m[1]);
+};
+
+/** CSS color → { r, g, b, a } (a ∈ 0..255). #RRGGBB / #RRGGBBAA / rgb() / rgba() 지원. */
+const parseCssColor = (s, ctx) => {
+  if (s.startsWith('#')) {
+    const hex = s.slice(1);
+    if (hex.length === 6) {
+      return {
+        r: parseInt(hex.slice(0, 2), 16),
+        g: parseInt(hex.slice(2, 4), 16),
+        b: parseInt(hex.slice(4, 6), 16),
+        a: 0xff,
+      };
+    }
+    if (hex.length === 8) {
+      return {
+        r: parseInt(hex.slice(0, 2), 16),
+        g: parseInt(hex.slice(2, 4), 16),
+        b: parseInt(hex.slice(4, 6), 16),
+        a: parseInt(hex.slice(6, 8), 16),
+      };
+    }
+    throw new Error(`${ctx}: hex 색은 #RRGGBB 또는 #RRGGBBAA 만 지원 — '${s}'`);
+  }
+  const m = s.match(/^rgba?\(\s*([^)]+)\)$/);
+  if (m) {
+    const parts = m[1].split(',').map((p) => p.trim());
+    if (parts.length < 3 || parts.length > 4) {
+      throw new Error(`${ctx}: rgb/rgba 인자 수 오류 — '${s}'`);
+    }
+    const r = parseInt(parts[0], 10);
+    const g = parseInt(parts[1], 10);
+    const b = parseInt(parts[2], 10);
+    const a = parts[3] !== undefined ? Math.round(parseFloat(parts[3]) * 255) : 0xff;
+    if ([r, g, b, a].some((n) => Number.isNaN(n))) {
+      throw new Error(`${ctx}: rgb/rgba 숫자 파싱 실패 — '${s}'`);
+    }
+    return { r, g, b, a };
+  }
+  throw new Error(`${ctx}: 색 형식 미지원 (#hex / rgb() / rgba() 만) — '${s}'`);
+};
+
+const colorToARGBHex = ({ a, r, g, b }) => {
+  const v = (((a & 0xff) << 24) | ((r & 0xff) << 16) | ((g & 0xff) << 8) | (b & 0xff)) >>> 0;
+  return v.toString(16).toUpperCase().padStart(8, '0');
+};
+
+/* --- shadow --- */
+
+const SHADOW_KEYS = ['sm', 'md', 'lg', 'xl'];
+
+export const buildCssShadowsBlock = (shadows) =>
+  SHADOW_KEYS.map((k) => `  --shadow-${k}: ${shadows[k]};`).join('\n');
+
+const parseSingleBoxShadow = (s) => {
+  const tokens = tokenizeSpaceAware(s);
+  if (tokens.length < 4 || tokens.length > 5) {
+    throw new Error(`shadow: 토큰 수 4~5 (offset-x offset-y blur [spread] color) — '${s}'`);
+  }
+  const offsetX = cssLengthToPx(tokens[0], 'shadow.offset-x');
+  const offsetY = cssLengthToPx(tokens[1], 'shadow.offset-y');
+  const blur = cssLengthToPx(tokens[2], 'shadow.blur');
+  let spread = 0;
+  let colorStr;
+  if (tokens.length === 4) {
+    colorStr = tokens[3];
+  } else {
+    spread = cssLengthToPx(tokens[3], 'shadow.spread');
+    colorStr = tokens[4];
+  }
+  const color = parseCssColor(colorStr, 'shadow.color');
+  return { offsetX, offsetY, blur, spread, color };
+};
+
+export const cssShadowToDartList = (cssValue) => {
+  const items = splitTopLevelByComma(cssValue).map(parseSingleBoxShadow);
+  const dartItems = items.map((it) => {
+    const hex = colorToARGBHex(it.color);
+    return `BoxShadow(offset: Offset(${it.offsetX.toFixed(1)}, ${it.offsetY.toFixed(1)}), blurRadius: ${it.blur.toFixed(1)}, spreadRadius: ${it.spread.toFixed(1)}, color: Color(0x${hex}))`;
+  });
+  return `<BoxShadow>[${dartItems.join(', ')}]`;
+};
+
+export const buildDartShadowsBlock = (shadows) =>
+  SHADOW_KEYS.map((k) => `    ${k}: ${cssShadowToDartList(shadows[k])},`).join('\n');
+
+/* --- ease --- */
+
+const EASE_KEYS = ['standard', 'emphasized'];
+
+const NAMED_EASES = {
+  linear: [0, 0, 1, 1],
+  ease: [0.25, 0.1, 0.25, 1],
+  'ease-in': [0.42, 0, 1, 1],
+  'ease-out': [0, 0, 0.58, 1],
+  'ease-in-out': [0.42, 0, 0.58, 1],
+};
+
+export const buildCssEasesBlock = (eases) =>
+  EASE_KEYS.map((k) => `  --ease-${k}: ${eases[k]};`).join('\n');
+
+export const cssEaseToDartCubic = (cssValue) => {
+  const trimmed = cssValue.trim();
+  if (NAMED_EASES[trimmed]) {
+    const [x1, y1, x2, y2] = NAMED_EASES[trimmed];
+    return `Cubic(${x1}, ${y1}, ${x2}, ${y2})`;
+  }
+  const m = trimmed.match(/^cubic-bezier\(([^)]+)\)$/);
+  if (!m) throw new Error(`ease: cubic-bezier(...) 또는 named easing 만 — '${cssValue}'`);
+  const nums = m[1].split(',').map((s) => parseFloat(s.trim()));
+  if (nums.length !== 4 || nums.some((n) => Number.isNaN(n))) {
+    throw new Error(`ease: cubic-bezier 인자 4개 숫자 필요 — '${cssValue}'`);
+  }
+  return `Cubic(${nums.join(', ')})`;
+};
+
+export const buildDartEasesBlock = (eases) =>
+  EASE_KEYS.map((k) => `    ${k}: ${cssEaseToDartCubic(eases[k])},`).join('\n');
+
+/* --- gradient --- */
+
+const GRADIENT_KEYS = ['primary', 'surface', 'overlay'];
+
+export const buildCssGradientsBlock = (gradients) =>
+  GRADIENT_KEYS.map((k) => `  --gradient-${k}: ${gradients[k]};`).join('\n');
+
+/**
+ * CSS gradient 의 deg → Flutter Alignment(begin, end).
+ * CSS 0deg=위쪽, 시계방향. Flutter Alignment 의 +y 는 아래.
+ */
+const angleToBeginEnd = (deg) => {
+  const rad = (deg * Math.PI) / 180;
+  const ex = Math.sin(rad);
+  const ey = -Math.cos(rad);
+  const round3 = (v) => parseFloat(v.toFixed(3));
+  return {
+    begin: [round3(-ex), round3(-ey)],
+    end: [round3(ex), round3(ey)],
+  };
+};
+
+export const cssGradientToDartLinear = (cssValue) => {
+  const trimmed = cssValue.trim();
+  const m = trimmed.match(/^linear-gradient\(([\s\S]+)\)$/);
+  if (!m) throw new Error(`gradient: linear-gradient(...) 만 — '${cssValue}'`);
+  const parts = splitTopLevelByComma(m[1]);
+  if (parts.length < 3) throw new Error(`gradient: 인자 부족 (각도 + 스톱 ≥ 2) — '${cssValue}'`);
+  const angleM = parts[0].match(/^(-?[\d.]+)deg$/);
+  if (!angleM) throw new Error(`gradient: 첫 인자가 <angle>deg 아님 — '${parts[0]}'`);
+  const angle = parseFloat(angleM[1]);
+  const stops = parts.slice(1).map((s) => {
+    const tokens = tokenizeSpaceAware(s);
+    if (tokens.length !== 2) throw new Error(`gradient: 스톱 형식 '<color> <pos>%' — '${s}'`);
+    const color = parseCssColor(tokens[0], 'gradient.stop.color');
+    const pm = tokens[1].match(/^([\d.]+)%$/);
+    if (!pm) throw new Error(`gradient: 스톱 위치 % 형식 — '${tokens[1]}'`);
+    return { color, position: parseFloat(pm[1]) };
+  });
+  const { begin, end } = angleToBeginEnd(angle);
+  const colorList = stops.map((st) => `Color(0x${colorToARGBHex(st.color)})`).join(', ');
+  const stopList = stops.map((st) => (st.position / 100).toFixed(2)).join(', ');
+  return `LinearGradient(begin: Alignment(${begin[0]}, ${begin[1]}), end: Alignment(${end[0]}, ${end[1]}), colors: <Color>[${colorList}], stops: <double>[${stopList}])`;
+};
+
+export const buildDartGradientsBlock = (gradients) =>
+  GRADIENT_KEYS.map((k) => `    ${k}: ${cssGradientToDartLinear(gradients[k])},`).join('\n');

package/src/create/theme/presets.js

@@ -0,0 +1,147 @@
+// 프로젝트 스캐폴드용 테마 프리셋. 사용자가 --theme <name> 또는 대화형 프롬프트에서
+// 고르면 generator 가 tokens.css / sh_ui_tokens.dart 에 그대로 주입한다.
+//
+// 색은 shadcn/ui · Tailwind 팔레트를 참고해 light/dark 모두 충분한 명도 대비를 갖도록 잡았다.
+// radius 만 살짝 변주해 프리셋 별 인상 차이를 더했다 (slate=0.375 sharp, rose=0.75 round, …).
+//
+// 새 프리셋을 추가하면 cli-args.js 의 VALID_THEME_PRESETS 에도 자동 반영된다 (이 파일에서 derive).
+
+const NEUTRAL_LIGHT = {
+  'background': '#FFFFFF',
+  'background-subtle': '#FAFAFA',
+  'background-muted': '#F5F5F5',
+  'background-inverse': '#0A0A0A',
+  'foreground': '#0A0A0A',
+  'foreground-muted': '#525252',
+  'foreground-subtle': '#A3A3A3',
+  'foreground-inverse': '#FFFFFF',
+  'border': '#E5E5E5',
+  'border-strong': '#D4D4D4',
+  'primary': '#171717',
+  'primary-foreground': '#FAFAFA',
+  'primary-hover': '#262626',
+  'danger': '#DC2626',
+  'danger-foreground': '#FFFFFF',
+};
+
+const NEUTRAL_DARK = {
+  'background': '#0A0A0A',
+  'background-subtle': '#171717',
+  'background-muted': '#262626',
+  'background-inverse': '#FFFFFF',
+  'foreground': '#FAFAFA',
+  'foreground-muted': '#A3A3A3',
+  'foreground-subtle': '#737373',
+  'foreground-inverse': '#0A0A0A',
+  'border': '#262626',
+  'border-strong': '#404040',
+  'primary': '#FAFAFA',
+  'primary-foreground': '#171717',
+  'primary-hover': '#E5E5E5',
+  'danger': '#DC2626',
+  'danger-foreground': '#FFFFFF',
+};
+
+export const THEME_PRESETS = {
+  neutral: {
+    label: '뉴트럴 — 흑백 강조 (sh-ui 기본)',
+    light: NEUTRAL_LIGHT,
+    dark: NEUTRAL_DARK,
+    radius: 0.5,
+  },
+  slate: {
+    label: '슬레이트 — 차분한 슬레이트 + 인디고',
+    light: {
+      'background': '#FFFFFF',
+      'background-subtle': '#F8FAFC',
+      'background-muted': '#F1F5F9',
+      'background-inverse': '#0F172A',
+      'foreground': '#0F172A',
+      'foreground-muted': '#475569',
+      'foreground-subtle': '#94A3B8',
+      'foreground-inverse': '#F1F5F9',
+      'border': '#E2E8F0',
+      'border-strong': '#CBD5E1',
+      'primary': '#4F46E5',
+      'primary-foreground': '#FFFFFF',
+      'primary-hover': '#4338CA',
+      'danger': '#DC2626',
+      'danger-foreground': '#FFFFFF',
+    },
+    dark: {
+      'background': '#0F172A',
+      'background-subtle': '#1E293B',
+      'background-muted': '#334155',
+      'background-inverse': '#FFFFFF',
+      'foreground': '#F1F5F9',
+      'foreground-muted': '#94A3B8',
+      'foreground-subtle': '#64748B',
+      'foreground-inverse': '#0F172A',
+      'border': '#334155',
+      'border-strong': '#475569',
+      'primary': '#818CF8',
+      'primary-foreground': '#1E1B4B',
+      'primary-hover': '#A5B4FC',
+      'danger': '#F87171',
+      'danger-foreground': '#450A0A',
+    },
+    radius: 0.375,
+  },
+  rose: {
+    label: '로즈 — 핑크 강조 + 둥근 모서리',
+    light: {
+      ...NEUTRAL_LIGHT,
+      'primary': '#E11D48',
+      'primary-foreground': '#FFF1F2',
+      'primary-hover': '#BE123C',
+    },
+    dark: {
+      ...NEUTRAL_DARK,
+      'primary': '#FB7185',
+      'primary-foreground': '#4C0519',
+      'primary-hover': '#FDA4AF',
+    },
+    radius: 0.75,
+  },
+  emerald: {
+    label: '에메랄드 — 그린 강조',
+    light: {
+      ...NEUTRAL_LIGHT,
+      'primary': '#059669',
+      'primary-foreground': '#ECFDF5',
+      'primary-hover': '#047857',
+    },
+    dark: {
+      ...NEUTRAL_DARK,
+      'primary': '#34D399',
+      'primary-foreground': '#022C22',
+      'primary-hover': '#6EE7B7',
+    },
+    radius: 0.5,
+  },
+  violet: {
+    label: '바이올렛 — 퍼플 강조 + 살짝 라운드',
+    light: {
+      ...NEUTRAL_LIGHT,
+      'primary': '#7C3AED',
+      'primary-foreground': '#F5F3FF',
+      'primary-hover': '#6D28D9',
+    },
+    dark: {
+      ...NEUTRAL_DARK,
+      'primary': '#A78BFA',
+      'primary-foreground': '#1E1B4B',
+      'primary-hover': '#C4B5FD',
+    },
+    radius: 0.625,
+  },
+};
+
+export const THEME_PRESET_NAMES = Object.keys(THEME_PRESETS);
+
+/** 프리셋 객체에서 inject 가 기대하는 ThemeConfig 형태(light/dark/radius)만 추출 */
+export const getThemePreset = (name) => {
+  const preset = THEME_PRESETS[name];
+  if (!preset) return null;
+  return { light: preset.light, dark: preset.dark, radius: preset.radius };
+};

package/src/mcp.mjs

@@ -38,12 +38,14 @@ import {
   THEME_MODES,
 } from "./constants.js";
 import { allPlugins } from "./create/plugins/index.js";
+import { THEME_PRESET_NAMES } from "./create/theme/presets.js";
 
 const PLATFORMS = INIT_PLATFORMS;
 const BASES = THEME_BASES;
 const RADII = THEME_RADII;
 const MODES = THEME_MODES;
 const PLUGIN_NAMES = allPlugins.map((p) => p.name);
+const THEME_PRESETS_LIST = THEME_PRESET_NAMES.join(", ");
 
 const INIT_DESCRIPTIONS = {
   platform: {
@@ -178,7 +180,7 @@ export async function startMcpServer() {
         plugins: z.array(z.enum(PLUGIN_NAMES)).optional()
           .describe(`Next.js 플러그인 (${PLUGIN_NAMES.join(', ')}). 미지정시 빈 배열`),
         theme: z.string().optional()
-          .describe("base64 인코딩된 테마 JSON (선택)"),
+          .describe(`프리셋 이름 (${THEME_PRESETS_LIST}) 또는 playground 에서 생성한 base64 (선택)`),
         cwd: z.string().optional()
           .describe("부모 디렉토리. 기본 process.cwd()"),
         force: z.boolean().optional()

package/templates/flutter-standalone/lib/sh_ui/foundation/sh_ui_tokens.dart

@@ -122,6 +122,7 @@ class ShUiSpacingTokens {
   });
 
   static const tokens = ShUiSpacingTokens(
+    // sh-ui:theme-space-start
     s0: 0.0,
     s1: 4.0,
     s2: 8.0,
@@ -133,6 +134,7 @@ class ShUiSpacingTokens {
     s10: 40.0,
     s12: 48.0,
     s16: 64.0,
+    // sh-ui:theme-space-end
   );
 }
 
@@ -159,6 +161,7 @@ class ShUiTextTokens {
   });
 
   static const tokens = ShUiTextTokens(
+    // sh-ui:theme-text-start
     xs: 12.0,
     sm: 14.0,
     base: 16.0,
@@ -167,6 +170,7 @@ class ShUiTextTokens {
     xl2: 24.0,
     xl3: 30.0,
     xl4: 36.0,
+    // sh-ui:theme-text-end
   );
 }
 
@@ -185,10 +189,12 @@ class ShUiWeightTokens {
   });
 
   static const tokens = ShUiWeightTokens(
+    // sh-ui:theme-weight-start
     regular: FontWeight.w400,
     medium: FontWeight.w500,
     semibold: FontWeight.w600,
     bold: FontWeight.w700,
+    // sh-ui:theme-weight-end
   );
 }
 
@@ -207,10 +213,12 @@ class ShUiShadowTokens {
   });
 
   static const tokens = ShUiShadowTokens(
+    // sh-ui:theme-shadow-start
     sm: <BoxShadow>[BoxShadow(offset: Offset(0.0, 1.0), blurRadius: 2.0, spreadRadius: 0.0, color: Color(0x14000000))],
     md: <BoxShadow>[BoxShadow(offset: Offset(0.0, 4.0), blurRadius: 12.0, spreadRadius: 0.0, color: Color(0x1F000000))],
     lg: <BoxShadow>[BoxShadow(offset: Offset(0.0, 8.0), blurRadius: 24.0, spreadRadius: 0.0, color: Color(0x26000000))],
     xl: <BoxShadow>[BoxShadow(offset: Offset(0.0, 16.0), blurRadius: 48.0, spreadRadius: 0.0, color: Color(0x2E000000))],
+    // sh-ui:theme-shadow-end
   );
 }
 
@@ -227,9 +235,11 @@ class ShUiDurationTokens {
   });
 
   static const tokens = ShUiDurationTokens(
+    // sh-ui:theme-duration-start
     fast: Duration(milliseconds: 120),
     base: Duration(milliseconds: 160),
     slow: Duration(milliseconds: 200),
+    // sh-ui:theme-duration-end
   );
 }
 
@@ -244,8 +254,10 @@ class ShUiEaseTokens {
   });
 
   static const tokens = ShUiEaseTokens(
+    // sh-ui:theme-ease-start
     standard: Cubic(0.4, 0, 0.2, 1),
     emphasized: Cubic(0.2, 0, 0, 1),
+    // sh-ui:theme-ease-end
   );
 }
 
@@ -262,9 +274,11 @@ class ShUiControlTokens {
   });
 
   static const tokens = ShUiControlTokens(
+    // sh-ui:theme-control-start
     sm: 32.0,
     md: 40.0,
     lg: 48.0,
+    // sh-ui:theme-control-end
   );
 }
 
@@ -279,8 +293,10 @@ class ShUiBorderWidthTokens {
   });
 
   static const tokens = ShUiBorderWidthTokens(
+    // sh-ui:theme-border-width-start
     normal: 1.0,
     strong: 2.0,
+    // sh-ui:theme-border-width-end
   );
 }
 
@@ -297,6 +313,27 @@ class ShUiOpacityTokens {
   );
 }
 
+@immutable
+class ShUiGradientTokens {
+  final LinearGradient primary;
+  final LinearGradient surface;
+  final LinearGradient overlay;
+
+  const ShUiGradientTokens({
+    required this.primary,
+    required this.surface,
+    required this.overlay,
+  });
+
+  static const tokens = ShUiGradientTokens(
+    // sh-ui:theme-gradient-start
+    primary: LinearGradient(begin: Alignment(-0.707, 0.707), end: Alignment(0.707, -0.707), colors: <Color>[Color(0xFF171717), Color(0xFF525252)], stops: <double>[0.00, 1.00]),
+    surface: LinearGradient(begin: Alignment(0.0, -1.0), end: Alignment(0.0, 1.0), colors: <Color>[Color(0xFFFFFFFF), Color(0xFFF5F5F5)], stops: <double>[0.00, 1.00]),
+    overlay: LinearGradient(begin: Alignment(0.0, -1.0), end: Alignment(0.0, 1.0), colors: <Color>[Color(0xFF000000), Color(0xFF1F1F1F)], stops: <double>[0.00, 1.00]),
+    // sh-ui:theme-gradient-end
+  );
+}
+
 @immutable
 class ShUiBreakpointTokens {
   final double sm;
@@ -330,6 +367,7 @@ class ShUiTheme extends ThemeExtension<ShUiTheme> {
   final ShUiEaseTokens ease;
   final ShUiControlTokens control;
   final ShUiBorderWidthTokens borderWidth;
+  final ShUiGradientTokens gradient;
   final ShUiOpacityTokens opacity;
   final ShUiBreakpointTokens breakpoint;
 
@@ -344,6 +382,7 @@ class ShUiTheme extends ThemeExtension<ShUiTheme> {
     required this.ease,
     required this.control,
     required this.borderWidth,
+    required this.gradient,
     required this.opacity,
     required this.breakpoint,
   });
@@ -359,6 +398,7 @@ class ShUiTheme extends ThemeExtension<ShUiTheme> {
     ease: ShUiEaseTokens.tokens,
     control: ShUiControlTokens.tokens,
     borderWidth: ShUiBorderWidthTokens.tokens,
+    gradient: ShUiGradientTokens.tokens,
     opacity: ShUiOpacityTokens.tokens,
     breakpoint: ShUiBreakpointTokens.tokens,
   );
@@ -373,13 +413,14 @@ class ShUiTheme extends ThemeExtension<ShUiTheme> {
     ease: ShUiEaseTokens.tokens,
     control: ShUiControlTokens.tokens,
     borderWidth: ShUiBorderWidthTokens.tokens,
+    gradient: ShUiGradientTokens.tokens,
     opacity: ShUiOpacityTokens.tokens,
     breakpoint: ShUiBreakpointTokens.tokens,
   );
 
   @override
-  ShUiTheme copyWith({ShUiColorTokens? colors, ShUiRadiusTokens? radius, ShUiSpacingTokens? spacing, ShUiTextTokens? text, ShUiWeightTokens? weight, ShUiShadowTokens? shadow, ShUiDurationTokens? duration, ShUiEaseTokens? ease, ShUiControlTokens? control, ShUiBorderWidthTokens? borderWidth, ShUiOpacityTokens? opacity, ShUiBreakpointTokens? breakpoint}) =>
-      ShUiTheme(colors: colors ?? this.colors, radius: radius ?? this.radius, spacing: spacing ?? this.spacing, text: text ?? this.text, weight: weight ?? this.weight, shadow: shadow ?? this.shadow, duration: duration ?? this.duration, ease: ease ?? this.ease, control: control ?? this.control, borderWidth: borderWidth ?? this.borderWidth, opacity: opacity ?? this.opacity, breakpoint: breakpoint ?? this.breakpoint);
+  ShUiTheme copyWith({ShUiColorTokens? colors, ShUiRadiusTokens? radius, ShUiSpacingTokens? spacing, ShUiTextTokens? text, ShUiWeightTokens? weight, ShUiShadowTokens? shadow, ShUiDurationTokens? duration, ShUiEaseTokens? ease, ShUiControlTokens? control, ShUiBorderWidthTokens? borderWidth, ShUiGradientTokens? gradient, ShUiOpacityTokens? opacity, ShUiBreakpointTokens? breakpoint}) =>
+      ShUiTheme(colors: colors ?? this.colors, radius: radius ?? this.radius, spacing: spacing ?? this.spacing, text: text ?? this.text, weight: weight ?? this.weight, shadow: shadow ?? this.shadow, duration: duration ?? this.duration, ease: ease ?? this.ease, control: control ?? this.control, borderWidth: borderWidth ?? this.borderWidth, gradient: gradient ?? this.gradient, opacity: opacity ?? this.opacity, breakpoint: breakpoint ?? this.breakpoint);
 
   @override
   ShUiTheme lerp(ThemeExtension<ShUiTheme>? other, double t) {

package/templates/nextjs-standalone/src/shared/styles/tokens.css

@@ -42,6 +42,7 @@
   /* sh-ui:theme-radius-start */
   --radius: 0.5rem;
   /* sh-ui:theme-radius-end */
+  /* sh-ui:theme-space-start */
   --space-0: 0px;
   --space-1: 4px;
   --space-2: 8px;
@@ -53,6 +54,8 @@
   --space-10: 40px;
   --space-12: 48px;
   --space-16: 64px;
+  /* sh-ui:theme-space-end */
+  /* sh-ui:theme-text-start */
   --text-xs: 12px;
   --text-sm: 14px;
   --text-base: 16px;
@@ -61,24 +64,42 @@
   --text-2xl: 24px;
   --text-3xl: 30px;
   --text-4xl: 36px;
+  /* sh-ui:theme-text-end */
+  /* sh-ui:theme-weight-start */
   --weight-regular: 400;
   --weight-medium: 500;
   --weight-semibold: 600;
   --weight-bold: 700;
+  /* sh-ui:theme-weight-end */
+  /* sh-ui:theme-shadow-start */
   --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.08);
   --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.12);
   --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.15);
   --shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.18);
+  /* sh-ui:theme-shadow-end */
+  /* sh-ui:theme-duration-start */
   --duration-fast: 120ms;
   --duration-base: 160ms;
   --duration-slow: 200ms;
+  /* sh-ui:theme-duration-end */
+  /* sh-ui:theme-ease-start */
   --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
   --ease-emphasized: cubic-bezier(0.2, 0, 0, 1);
+  /* sh-ui:theme-ease-end */
+  /* sh-ui:theme-control-start */
   --control-sm: 32px;
   --control-md: 40px;
   --control-lg: 48px;
+  /* sh-ui:theme-control-end */
+  /* sh-ui:theme-border-width-start */
   --border-width: 1px;
   --border-width-strong: 2px;
+  /* sh-ui:theme-border-width-end */
+  /* sh-ui:theme-gradient-start */
+  --gradient-primary: linear-gradient(135deg, #171717 0%, #525252 100%);
+  --gradient-surface: linear-gradient(180deg, #FFFFFF 0%, #F5F5F5 100%);
+  --gradient-overlay: linear-gradient(180deg, #000000 0%, #1F1F1F 100%);
+  /* sh-ui:theme-gradient-end */
   --opacity-disabled: 0.5;
   --z-base: 0;
   --z-sticky: 100;

package/templates/ui-app-template/src/styles/tokens.css

@@ -42,6 +42,7 @@
   /* sh-ui:theme-radius-start */
   --radius: 0.5rem;
   /* sh-ui:theme-radius-end */
+  /* sh-ui:theme-space-start */
   --space-0: 0px;
   --space-1: 4px;
   --space-2: 8px;
@@ -53,6 +54,8 @@
   --space-10: 40px;
   --space-12: 48px;
   --space-16: 64px;
+  /* sh-ui:theme-space-end */
+  /* sh-ui:theme-text-start */
   --text-xs: 12px;
   --text-sm: 14px;
   --text-base: 16px;
@@ -61,24 +64,42 @@
   --text-2xl: 24px;
   --text-3xl: 30px;
   --text-4xl: 36px;
+  /* sh-ui:theme-text-end */
+  /* sh-ui:theme-weight-start */
   --weight-regular: 400;
   --weight-medium: 500;
   --weight-semibold: 600;
   --weight-bold: 700;
+  /* sh-ui:theme-weight-end */
+  /* sh-ui:theme-shadow-start */
   --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.08);
   --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.12);
   --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.15);
   --shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.18);
+  /* sh-ui:theme-shadow-end */
+  /* sh-ui:theme-duration-start */
   --duration-fast: 120ms;
   --duration-base: 160ms;
   --duration-slow: 200ms;
+  /* sh-ui:theme-duration-end */
+  /* sh-ui:theme-ease-start */
   --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
   --ease-emphasized: cubic-bezier(0.2, 0, 0, 1);
+  /* sh-ui:theme-ease-end */
+  /* sh-ui:theme-control-start */
   --control-sm: 32px;
   --control-md: 40px;
   --control-lg: 48px;
+  /* sh-ui:theme-control-end */
+  /* sh-ui:theme-border-width-start */
   --border-width: 1px;
   --border-width-strong: 2px;
+  /* sh-ui:theme-border-width-end */
+  /* sh-ui:theme-gradient-start */
+  --gradient-primary: linear-gradient(135deg, #171717 0%, #525252 100%);
+  --gradient-surface: linear-gradient(180deg, #FFFFFF 0%, #F5F5F5 100%);
+  --gradient-overlay: linear-gradient(180deg, #000000 0%, #1F1F1F 100%);
+  /* sh-ui:theme-gradient-end */
   --opacity-disabled: 0.5;
   --z-base: 0;
   --z-sticky: 100;