sh-ui-cli 0.85.0 → 0.86.0

package/data/changelog/versions.json

@@ -2,6 +2,31 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.86.0",
+      "date": "2026-05-14",
+      "title": "Vite 플랫폼 프리셋 — sh_ui_create_project platform=vite (standalone)",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui-cli create --platform vite --structure standalone`** — Vite 5 + React 19 + Tailwind v4 SPA 스캐폴드 신설. ai-org 같은 Tauri 셸 + SPA 조합처럼 Next.js SSR/App Router 가 무용지물이고 HMR 속도·번들 크기에서 vite 가 유리한 워크로드를 위한 1급 진입점. `@tailwindcss/vite` 공식 플러그인 경유 (next 프리셋의 postcss 경로와 다름). flat·fsd arch 모두 호환 (`mes` 는 App Router 의존이라 제외). MCP `sh_ui_create_project` / `sh_ui_describe_template` 도 platform=vite 인식.",
+        "**`next-themes` 없이 self-rolled `useTheme` 훅 + `ThemeProvider`** — vite SPA 환경에 맞춰 context + `localStorage` + `document.documentElement.classList` 토글 + `prefers-color-scheme` 변화 구독을 ~70 줄로 직접 구현. `index.html` 의 inline FOUC 스크립트가 첫 paint 전에 dark class 박아 깜빡임 차단. registry 에는 theme 두지 않는 v0.63+ 정책 그대로.",
+        "**`vite-tsconfig-paths` 플러그인 포함** — tsconfig 의 `@/*` (fsd) / `@/lib/*` + `@/components/*` (flat) 별칭을 vite/rollup 빌드 타임에 그대로 해석. tsconfig.app.json 이 별칭 단일 소스, `vite.config.ts` 는 plugin 한 줄만 추가. tsconfig 별칭과 빌드 별칭이 어긋날 일 없음.",
+        "**monorepo + Tauri 통합은 후속**. v0.86.0 은 vite-standalone 한정. vite-monorepo (apps/{name} + packages/ui/ui-core 공유) 는 v0.87 에서 generateMonorepo platform 분기로 추가 예정. Tauri scaffold 자동화는 별도 PR 후보 (현재도 `tauri init` 으로 vite 앱을 wrap 가능 — `dist/` 표준 위치 그대로)."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.86.0"
+    },
+    {
+      "version": "0.85.1",
+      "date": "2026-05-13",
+      "title": "scaffold globals.css 에 external-imports sentinel — 폰트/디자인시스템 URL @import footgun 차단",
+      "type": "patch",
+      "highlights": [
+        "**4개 globals.css 템플릿에 `sh-ui:external-imports-start/-end` sentinel 블록 추가** — `@import 'tailwindcss'` 위에 명시적으로 외부 URL `@import` 자리 표시. 기존엔 사용자가 `@import 'tailwindcss'` 바로 아래에 폰트 URL `@import` 추가하면 (자연 직관) CSS spec (\"모든 `@import` 는 다른 rule 보다 앞에 와야 함\") 위반으로 Turbopack/lightningcss 가 `@import rules must precede all rules aside from @charset and @layer statements` 로 dev server 즉사. 라인 번호가 번들 후 (2874:8 류) 라 디버깅 동선이 길어 첫 인상에서 30분 헤매던 footgun.",
+        "**적용 범위**: `ui-app-template/src/styles/globals.css` (monorepo) · `nextjs-standalone/app/globals.css` (standalone fsd 의 베이스) · `nextjs-standalone/_arch/flat/app/globals.css` · `nextjs-standalone/_arch/mes/app/globals.css`. sentinel 안에 `@import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.css');` 류 예시도 주석으로 포함 — 새 사용자가 어디에 둘지 한눈에 발견.",
+        "**기존 프로젝트 마이그레이션은 별도 codemod 로 후속** — 현재는 신규 스캐폴드에만 sentinel emit. 기존 globals.css 자동 수술은 `sh_ui_migrate` 명령에 추후 추가."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.85.1"
+    },
     {
       "version": "0.85.0",
       "date": "2026-05-13",

package/package.json

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

package/src/constants.js

@@ -7,7 +7,7 @@
 
 // ─── 프로젝트 생성 (sh-ui-cli create) ───
 
-export const CREATE_PLATFORMS = ['next', 'flutter'];
+export const CREATE_PLATFORMS = ['next', 'flutter', 'vite'];
 
 export const CREATE_STRUCTURES = ['standalone', 'monorepo'];
 

package/src/create/architectures/archSchema.js

@@ -40,7 +40,7 @@ export const ArchSchema = z.object({
   // 이 arch 가 적용 가능한 플랫폼들. CLI 에서 platform/arch 조합이 호환되는지 검증.
   // 예: fsd/flat 은 ['next'], 미래에 추가될 flutter-clean 은 ['flutter'].
   // 같은 이름의 arch 가 두 플랫폼 모두 지원하는 케이스도 가능 (예: 'flat' 가 양쪽).
-  platforms: z.array(z.enum(['next', 'flutter'])).min(1),
+  platforms: z.array(z.enum(['next', 'flutter', 'vite'])).min(1),
 
   // 논리 키 → 파일시스템 경로 (앱 루트 기준 상대)
   paths: PathKeys,

package/src/create/architectures/flat.js

@@ -18,7 +18,7 @@ export const flatArch = {
   label: 'Flat',
   description:
     '슬라이스 없는 관용적 Next.js 구조 (lib/components/app). 작은 프로젝트, 데모, 일회성 도구에 적합.',
-  platforms: ['next'],
+  platforms: ['next', 'vite'],
 
   paths: {
     layouts:    'components/layouts',

package/src/create/architectures/fsd.js

@@ -12,7 +12,7 @@ export const fsdArch = {
   label: 'Feature-Sliced Design',
   description:
     '슬라이스 기반 폴더 구조 (entities/features/widgets/views/shared/app). 도메인이 큰 프로젝트에 적합.',
-  platforms: ['next'],
+  platforms: ['next', 'vite'],
 
   paths: {
     layouts:    'src/app/layouts',

package/src/create/describeTemplate.js

@@ -28,8 +28,8 @@ import { CSS_FRAMEWORK_DEFAULT } from '../constants.js';
 
 /**
  * @typedef {Object} DescribeOptions
- * @property {'next'|'flutter'} [platform]
- * @property {'standalone'|'monorepo'} [structure]   next 일 때만 의미
+ * @property {'next'|'flutter'|'vite'} [platform]
+ * @property {'standalone'|'monorepo'} [structure]   next/vite 일 때만 의미
  * @property {string} [arch]                          next 일 때 'fsd'|'flat'|'mes'
  * @property {string[]} [plugins]                     ['sentry', 'next-intl', 'auth-jwt']
  * @property {'tailwind'|'plain'|'css-modules'} [cssFramework]
@@ -71,6 +71,25 @@ export function describeTemplate(opts = {}) {
     ]);
   }
 
+  if (platform === 'vite') {
+    // standalone only in Phase 1. monorepo is added in Task 13.
+    const tpl = TEMPLATE_MANIFEST['vite-standalone'];
+    if (!tpl) {
+      throw new Error("Template manifest missing entry for 'vite-standalone'.");
+    }
+    const safeArchName = isKnownArch(archName) ? archName : DEFAULT_ARCH;
+    const archObj = getArchByName(safeArchName);
+    if (!archObj.platforms.includes('vite')) {
+      throw new Error(`Arch '${safeArchName}' is not compatible with vite.`);
+    }
+    const baseFiles = tpl.base.slice();
+    const archFiles = (tpl.arches?.[safeArchName] ?? []).slice();
+    return finalize([
+      makeGroup('base', '베이스 (vite-standalone)', baseFiles),
+      makeGroup('arch', `Arch (${safeArchName})`, archFiles),
+    ]);
+  }
+
   // platform === 'next'
   const safeArchName = isKnownArch(archName) ? archName : DEFAULT_ARCH;
   const archObj = getArchByName(safeArchName);

package/src/create/generator.js

@@ -191,7 +191,7 @@ export async function createProject(options = {}) {
   if (!process.stdin.isTTY) {
     assertNoTtyFlag(options.name, '<project-name> (positional)');
     assertNoTtyFlag(options.platform, '--platform');
-    if (options.platform === 'next') {
+    if (options.platform === 'next' || options.platform === 'vite') {
       assertNoTtyFlag(options.structure, '--structure');
     }
   }
@@ -208,6 +208,7 @@ export async function createProject(options = {}) {
     message: '플랫폼:',
     choices: [
       { name: 'Next.js', value: 'next' },
+      { name: 'Vite (SPA)', value: 'vite' },
       { name: 'Flutter', value: 'flutter' },
     ],
   });
@@ -221,6 +222,9 @@ export async function createProject(options = {}) {
   if (platform === 'next') {
     const archName = options.arch ?? DEFAULT_ARCH;
     arch = assertArchPlatformCompat(archName, 'next');
+  } else if (platform === 'vite') {
+    const archName = options.arch ?? DEFAULT_ARCH;  // 'fsd' default — flat 도 호환
+    arch = assertArchPlatformCompat(archName, 'vite');
   } else if (platform === 'flutter' && options.arch) {
     arch = assertArchPlatformCompat(options.arch, 'flutter');
   }
@@ -317,6 +321,47 @@ export async function createProject(options = {}) {
     return;
   }
 
+  if (platform === 'vite') {
+    // vite 는 next 와 동일하게 structure 옵션을 받지만 Phase 1 에서는 standalone 만 처리.
+    // monorepo 는 후속 task 에서 generateMonorepo 의 platform 분기로 연결.
+    const projectType = options.structure ?? await select({
+      message: '프로젝트 구조:',
+      choices: [
+        { name: '단독 (Vite standalone)', value: 'standalone' },
+        { name: '모노레포 (Turborepo + pnpm)', value: 'monorepo' },
+      ],
+    });
+
+    if (projectType === 'standalone') {
+      await generateViteStandalone(targetDir, projectName, theme, cssFramework, arch, themeBase);
+    } else {
+      // monorepo path is added in Task 12. For now, fail loudly so users know.
+      throw new Error(
+        'platform=vite + structure=monorepo 는 아직 구현되지 않았습니다 (Phase 2 — v0.87 예정). ' +
+        'standalone 을 사용하거나 platform=next 로 monorepo 를 만든 뒤 vite 앱을 수동으로 추가해주세요.',
+      );
+    }
+
+    await finalizeProject(targetDir, { dryRun: options.dryRun });
+
+    if (options.dryRun) {
+      const files = await listAllFiles(targetDir);
+      console.log(`\n[DRY RUN] ${projectName} 스캐폴드 시 작성될 파일 (${files.length}개):\n`);
+      for (const f of files.sort()) console.log(`  ${f}`);
+      await fs.remove(targetDir);
+      console.log(`\n실제 스캐폴드: --dry-run 제거 후 같은 명령 실행.`);
+      return;
+    }
+
+    console.log(`\n✅ ${projectName} Vite 프로젝트가 생성되었습니다!`);
+    console.log(`\n  cd ${projectName}`);
+    console.log('  pnpm install');
+    console.log('  pnpm dev\n');
+    console.log('다음 단계 — 베이스 컴포넌트 추가 (예시):');
+    console.log('  npx sh-ui-cli add button card input dialog\n');
+    return;
+  }
+
   // platform === 'next' 경로
   const projectType = options.structure ?? await select({
     message: '프로젝트 구조:',
@@ -690,6 +735,43 @@ async function generateStandalone(targetDir, projectName, plugins, theme, css, a
   await patchShUiConfig(path.join(targetDir, 'sh-ui.config.json'), css, themeBase);
 }
 
+async function generateViteStandalone(targetDir, projectName, theme, css, arch, themeBase) {
+  // 베이스 (arch-neutral) + arch 오버레이 — generateStandalone 과 같은 패턴.
+  await fs.copy(path.join(TEMPLATES_DIR, 'vite-standalone'), targetDir, {
+    filter: (src) => !src.includes(`${path.sep}_arch${path.sep}`) && !src.endsWith(`${path.sep}_arch`),
+  });
+  await ensureArchCleanup(targetDir);
+  await fs.copy(
+    path.join(TEMPLATES_DIR, 'vite-standalone', '_arch', arch.name),
+    targetDir,
+    { overwrite: true },
+  );
+  // vite 는 모든 소스가 src/ 아래 — arch.paths.layouts(next 관용) 앞에 src/ 를 붙여
+  // sentinel 위치를 보정한다. flat 의 components/layouts → src/components/layouts,
+  // fsd 의 src/app/layouts → src/app/layouts (변화 없음 — fsd 가 이미 src/ 박혀 있음).
+  const layoutsPath = arch.paths.layouts.startsWith('src/')
+    ? arch.paths.layouts
+    : `src/${arch.paths.layouts}`;
+  const sentinelPath = path.join(targetDir, `${layoutsPath}/RootLayout.tsx`);
+  if (!(await fs.pathExists(sentinelPath))) {
+    throw new Error(
+      `arch 오버레이 누락: vite-standalone + ${arch.name} 의 sentinel 파일(${layoutsPath}/RootLayout.tsx) 이 ${targetDir} 에 없습니다.`,
+    );
+  }
+
+  // package.json — name + dep sort
+  const pkgPath = path.join(targetDir, 'package.json');
+  const pkg = await fs.readJson(pkgPath);
+  pkg.name = projectName;
+  if (pkg.dependencies) pkg.dependencies = sortObjectKeys(pkg.dependencies);
+  if (pkg.devDependencies) pkg.devDependencies = sortObjectKeys(pkg.devDependencies);
+  await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+
+  await applyCssFrameworkVariant(targetDir, css, { isMonorepo: false, plugins: [], arch });
+  await injectCssTheme(targetDir, theme);
+  await patchShUiConfig(path.join(targetDir, 'sh-ui.config.json'), css, themeBase);
+}
+
 async function generateMonorepo(targetDir, projectName, plugins, { yes = false, theme, css, arch, themeBase } = {}) {
   await fs.copy(path.join(TEMPLATES_DIR, 'monorepo'), targetDir);
 
@@ -1755,9 +1837,10 @@ const OPTIONAL_DART_INJECTORS = [
 async function injectCssTheme(projectDir, theme) {
   if (!theme) return;
   const candidates = [
-    'src/shared/styles/tokens.css',  // FSD standalone
+    'src/shared/styles/tokens.css',  // FSD standalone (next + vite)
     'src/styles/tokens.css',          // monorepo ui-app-template (arch-neutral)
-    'lib/styles/tokens.css',          // flat standalone
+    'src/lib/styles/tokens.css',      // flat standalone (vite)
+    'lib/styles/tokens.css',          // flat standalone (next)
   ];
   for (const rel of candidates) {
     const abs = path.join(projectDir, rel);

package/src/create/templateManifest.js

@@ -324,5 +324,54 @@ export const TEMPLATE_MANIFEST = {
       "src/styles/tokens.css",
       "tsconfig.json"
     ]
+  },
+  "vite-standalone": {
+    "base": [
+      "CLAUDE.md",
+      "README.md",
+      "eslint.config.js",
+      "gitignore",
+      "index.html",
+      "package.json",
+      "src/App.tsx",
+      "src/Home.tsx",
+      "src/main.tsx",
+      "tsconfig.json",
+      "tsconfig.node.json",
+      "vite.config.ts",
+      "vitest.config.ts",
+      "vitest.setup.ts"
+    ],
+    "arches": {
+      "flat": [
+        "sh-ui.config.json",
+        "src/App.tsx",
+        "src/components/layouts/RootLayout.tsx",
+        "src/components/providers/GlobalProvider/index.tsx",
+        "src/components/providers/index.tsx",
+        "src/components/providers/theme/ThemeProvider.tsx",
+        "src/lib/api/queryClient.ts",
+        "src/lib/hooks/useTheme.ts",
+        "src/lib/styles/globals.css",
+        "src/lib/styles/tokens.css",
+        "src/lib/utils/utils.ts",
+        "src/main.tsx",
+        "tsconfig.app.json"
+      ],
+      "fsd": [
+        "sh-ui.config.json",
+        "src/App.tsx",
+        "src/app/layouts/RootLayout.tsx",
+        "src/app/providers/GlobalProvider/index.tsx",
+        "src/app/providers/theme/ThemeProvider.tsx",
+        "src/main.tsx",
+        "src/shared/api/queryClient.ts",
+        "src/shared/hooks/useTheme.ts",
+        "src/shared/lib/utils.ts",
+        "src/shared/styles/globals.css",
+        "src/shared/styles/tokens.css",
+        "tsconfig.app.json"
+      ]
+    }
   }
 };

package/src/mcp.mjs

@@ -366,7 +366,7 @@ export async function startMcpServer() {
     "sh_ui_create_project",
     {
       description:
-        "빈 폴더에 sh-ui 프로젝트 스캐폴드 — Next.js (standalone/monorepo) 또는 Flutter. " +
+        "빈 폴더에 sh-ui 프로젝트 스캐폴드 — Next.js (standalone/monorepo) | Vite (standalone) | Flutter. " +
         `FSD 폴더 구조 + 토큰 + sh-ui.config.json 일괄 생성. 사용자가 '새 프로젝트' / '빈 폴더' / '스캐폴드부터' 류 요청을 하면 이 툴 사용 (Bash 로 npx ${cliName} create 직접 호출보다 우선). ` +
         "**단일 진입점** — theme/plugins/cssFramework/structure 모두 호출 시점에 정해서 한 번에 박는다. 호출 후 sh-ui.config.json/tokens.css 를 손으로 패치하지 말 것 (다음 재스캐폴드 시 유실). " +
         "산출물: theme 인자가 프리셋이면 sh-ui.config.json 의 theme.base 가 그 이름, base64 면 'custom'. paths.styles · paths.tokens 도 자동 박혀서 sh_ui_add_component 가 사후 패치 없이 동작.",
@@ -397,13 +397,13 @@ export async function startMcpServer() {
       },
     },
     async (input) => {
-      if (input.platform === "next" && !input.structure) {
+      if ((input.platform === "next" || input.platform === "vite") && !input.structure) {
         return {
           isError: true,
           content: [
             {
               type: "text",
-              text: "platform=next 일 때 structure ('standalone' | 'monorepo') 가 필요합니다.",
+              text: `platform=${input.platform} 일 때 structure ('standalone' | 'monorepo') 가 필요합니다.`,
             },
           ],
         };
@@ -820,7 +820,7 @@ export async function startMcpServer() {
         platform: z.enum(CREATE_PLATFORMS)
           .describe("타겟 플랫폼"),
         structure: z.enum(CREATE_STRUCTURES).optional()
-          .describe("Next.js 구조. platform=next 일 때 의미. 기본 standalone"),
+          .describe("Next.js 구조. platform=next | vite 일 때 의미. 기본 standalone"),
         arch: z.enum(ARCH_NAMES).optional()
           .describe("아키텍처. platform=next 일 때 의미. 기본 fsd"),
         plugins: z.array(z.enum(PLUGIN_NAMES)).optional()

package/templates/nextjs-standalone/_arch/flat/app/globals.css

@@ -1,3 +1,9 @@
+/* sh-ui:external-imports-start
+ *   외부 폰트 / 아이콘셋 / 디자인시스템 URL @import 는 반드시 이 블록 안에 둘 것.
+ *   `@import 'tailwindcss'` 아래에 추가하면 CSS spec 위반으로 Turbopack 이 즉사.
+ *   예: @import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.css'); */
+/* sh-ui:external-imports-end */
+
 @import 'tailwindcss';
 @import '../lib/styles/tokens.css';
 

package/templates/nextjs-standalone/_arch/mes/app/globals.css

@@ -1,3 +1,9 @@
+/* sh-ui:external-imports-start
+ *   외부 폰트 / 아이콘셋 / 디자인시스템 URL @import 는 반드시 이 블록 안에 둘 것.
+ *   `@import 'tailwindcss'` 아래에 추가하면 CSS spec 위반으로 Turbopack 이 즉사.
+ *   예: @import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.css'); */
+/* sh-ui:external-imports-end */
+
 @import 'tailwindcss';
 @import '../src/lib/styles/tokens.css';
 

package/templates/nextjs-standalone/app/globals.css

@@ -1,3 +1,9 @@
+/* sh-ui:external-imports-start
+ *   외부 폰트 / 아이콘셋 / 디자인시스템 URL @import 는 반드시 이 블록 안에 둘 것.
+ *   `@import 'tailwindcss'` 아래에 추가하면 CSS spec 위반으로 Turbopack 이 즉사.
+ *   예: @import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.css'); */
+/* sh-ui:external-imports-end */
+
 @import 'tailwindcss';
 @import '../src/shared/styles/tokens.css';
 

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

@@ -1,3 +1,10 @@
+/* sh-ui:external-imports-start
+ *   외부 폰트 / 아이콘셋 / 디자인시스템 URL @import 는 반드시 이 블록 안에 둘 것.
+ *   `@import 'tailwindcss'` 아래에 추가하면 CSS spec ("모든 @import 는 다른 rule 보다
+ *   앞에 와야 함") 위반으로 Turbopack/lightningcss 가 parsing 거부 → dev server 즉사.
+ *   예: @import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.css'); */
+/* sh-ui:external-imports-end */
+
 @import 'tailwindcss';
 
 @source "../../../../../../apps/**/*.{ts,tsx}";

package/templates/vite-standalone/CLAUDE.md

@@ -0,0 +1,7 @@
+# sh-ui app
+
+sh-ui 컴포넌트는 `npx sh-ui-cli add <name>` 으로 추가합니다. 토큰은
+`src/lib/styles/tokens.css` (flat) 또는 `src/shared/styles/tokens.css` (fsd) 입니다.
+
+`vite.config.ts` 의 `@tailwindcss/vite` 플러그인이 Tailwind v4 를 처리하므로 PostCSS
+설정 파일이 없습니다.

package/templates/vite-standalone/README.md

@@ -0,0 +1,23 @@
+# my-app
+
+Vite + React + sh-ui 스캐폴드.
+
+## 개발
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## 빌드
+
+```bash
+pnpm build
+pnpm preview
+```
+
+## 컴포넌트 추가
+
+```bash
+npx sh-ui-cli add button card input dialog
+```

package/templates/vite-standalone/_arch/flat/sh-ui.config.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
+  "platform": "react",
+  "cssFramework": "tailwind",
+  "theme": {
+    "base": "neutral",
+    "radius": "md",
+    "mode": "light-dark"
+  },
+  "paths": {
+    "tokens": "src/lib/styles/tokens.css",
+    "cssEntry": "src/lib/styles/globals.css",
+    "styles": "src/lib/styles",
+    "components": "src/components/common",
+    "utils": "src/lib/utils/utils.ts"
+  },
+  "aliases": {
+    "components": "@/components/common",
+    "utils": "@/lib/utils/utils",
+    "ui": "@/components/common"
+  }
+}

package/templates/vite-standalone/_arch/flat/src/App.tsx

@@ -0,0 +1,13 @@
+import { RootLayout } from '@/components/layouts/RootLayout';
+import { GlobalProvider } from '@/components/providers';
+import Home from './Home';
+
+export default function App() {
+  return (
+    <GlobalProvider>
+      <RootLayout>
+        <Home />
+      </RootLayout>
+    </GlobalProvider>
+  );
+}

package/templates/vite-standalone/_arch/flat/src/components/layouts/RootLayout.tsx

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+
+export function RootLayout({ children }: { children: ReactNode }) {
+  return <div className="min-h-screen bg-background text-foreground">{children}</div>;
+}

package/templates/vite-standalone/_arch/flat/src/components/providers/GlobalProvider/index.tsx

@@ -0,0 +1,13 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import { type ReactNode, useState } from 'react';
+import { createQueryClient } from '@/lib/api/queryClient';
+import { ThemeProvider } from '../theme/ThemeProvider';
+
+export function GlobalProvider({ children }: { children: ReactNode }) {
+  const [queryClient] = useState(() => createQueryClient());
+  return (
+    <ThemeProvider>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </ThemeProvider>
+  );
+}

package/templates/vite-standalone/_arch/flat/src/components/providers/index.tsx

@@ -0,0 +1 @@
+export { GlobalProvider } from './GlobalProvider';

package/templates/vite-standalone/_arch/flat/src/components/providers/theme/ThemeProvider.tsx

@@ -0,0 +1,59 @@
+import { createContext, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+export type Theme = 'light' | 'dark' | 'system';
+
+type ThemeContextValue = {
+  theme: Theme;
+  resolvedTheme: 'light' | 'dark';
+  setTheme: (theme: Theme) => void;
+};
+
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+const STORAGE_KEY = 'theme';
+
+function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+function resolveTheme(theme: Theme): 'light' | 'dark' {
+  return theme === 'system' ? getSystemTheme() : theme;
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    if (typeof window === 'undefined') return 'system';
+    return (localStorage.getItem(STORAGE_KEY) as Theme) ?? 'system';
+  });
+
+  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => resolveTheme(theme));
+
+  useEffect(() => {
+    const resolved = resolveTheme(theme);
+    setResolvedTheme(resolved);
+    document.documentElement.classList.toggle('dark', resolved === 'dark');
+  }, [theme]);
+
+  useEffect(() => {
+    if (theme !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = () => {
+      const resolved = getSystemTheme();
+      setResolvedTheme(resolved);
+      document.documentElement.classList.toggle('dark', resolved === 'dark');
+    };
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, [theme]);
+
+  const setTheme = useCallback((next: Theme) => {
+    setThemeState(next);
+    if (next === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, next);
+  }, []);
+
+  const value = useMemo(() => ({ theme, resolvedTheme, setTheme }), [theme, resolvedTheme, setTheme]);
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}

package/templates/vite-standalone/_arch/flat/src/lib/api/queryClient.ts

@@ -0,0 +1,12 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        refetchOnWindowFocus: false,
+      },
+    },
+  });
+}

package/templates/vite-standalone/_arch/flat/src/lib/hooks/useTheme.ts

@@ -0,0 +1,8 @@
+import { useContext } from 'react';
+import { ThemeContext } from '@/components/providers/theme/ThemeProvider';
+
+export function useTheme() {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error('useTheme must be used within a ThemeProvider');
+  return ctx;
+}

package/templates/vite-standalone/_arch/flat/src/lib/styles/globals.css

@@ -0,0 +1,35 @@
+/* sh-ui:external-imports-start
+ *   외부 폰트 / 아이콘셋 / 디자인시스템 URL @import 는 반드시 이 블록 안에 둘 것. */
+/* sh-ui:external-imports-end */
+
+@import 'tailwindcss';
+@import './tokens.css';
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-background-subtle: var(--background-subtle);
+  --color-background-muted: var(--background-muted);
+  --color-background-inverse: var(--background-inverse);
+  --color-foreground: var(--foreground);
+  --color-foreground-muted: var(--foreground-muted);
+  --color-foreground-subtle: var(--foreground-subtle);
+  --color-foreground-inverse: var(--foreground-inverse);
+  --color-border: var(--border);
+  --color-border-strong: var(--border-strong);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary-hover: var(--primary-hover);
+  --color-ring: var(--ring);
+  --color-danger: var(--danger);
+  --color-danger-hover: var(--danger-hover);
+  --color-danger-foreground: var(--danger-foreground);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+  --color-sidebar-bg: var(--sidebar-bg);
+}