sh-ui-cli 0.77.0 → 0.79.0

package/data/changelog/versions.json

@@ -2,6 +2,51 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.79.0",
+      "date": "2026-05-12",
+      "title": "no-restricted toLocaleDateString — SSR hydration mismatch 회귀 가드",
+      "type": "minor",
+      "highlights": [
+        "**ESLint `no-restricted-syntax` 룰 추가** — 인자 0개의 `.toLocaleDateString()` / `.toLocaleString()` / `.toLocaleTimeString()` 호출을 error 로 차단. Node 기본 로케일(en-US) 과 브라우저 로케일(ko-KR) 이 달라 SSR 출력이 hydrate 시 mismatch 나던 함정의 회귀 가드.",
+        "**대체 경로 안내가 에러 메시지에 박힘** — `@/src/shared/lib/formatDate` 의 `formatDate` / `formatDateTime` (default `ko-KR`), next-intl locale 추종이면 `useFormatDate` 훅, 숫자는 `formatPrice`. AST selector 가 `arguments.length === 0` 만 매칭하므로 의도된 locale 명시 호출 (`toLocaleDateString('ko-KR', { ... })`) 은 통과.",
+        "**적용 범위** — monorepo `@workspace/eslint-config/base` (next.js · react-internal 등 모든 워크스페이스 config 가 상속) + `nextjs-standalone` 의 fsd / flat / mes arch 오버레이 3종.",
+        "**템플릿 CLAUDE.md 추가** — `nextjs-standalone` / `monorepo` 시작 템플릿에 `CLAUDE.md` 신규. 날짜·숫자 포맷 컨벤션 + sh-ui 컴포넌트 우선 + 토큰 사용 원칙 명시. AI 에이전트가 코드 작성 시점에 컨텍스트로 읽고 미리 피할 수 있게."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.79.0"
+    },
+    {
+      "version": "0.78.0",
+      "date": "2026-05-12",
+      "title": "minor — Next.js 호환성 fixes (exports map · relative imports · FOUC · SelectValue label · sidebar tokens)",
+      "type": "minor",
+      "highlights": [
+        "**ui-core `package.json` exports map 수정** — `./components/*: ./src/components/*.tsx` → `./src/components/*/index.tsx`. 폴더+index 패턴에 맞춰 `@workspace/ui-core/components/<name>` import 가 즉시 resolve. v0.77 까지 scaffold 직후 매번 손으로 패치해야 했던 버그.",
+        "**registry typecheck 통과** — `markdown-editor` / `sidebar` 의 inter-component 상대 import 에 `/index.tsx` 명시 (node16/nodenext + bundler 둘 다 동작). `sidebar` 의 `PopoverTrigger` render callback 의 implicit `any` 도 명시 타입.",
+        "**`SidebarMenuButton` render 자식 `data-active` 보존** — `cloneElement` 가 사용자가 박은 `data-active` 를 sh-ui 자동값으로 덮어쓰던 버그. 이제 자식 명시값이 우선. 자기 디자인 시스템 active state 를 `[data-active]` 셀렉터로 다루는 흐름 가능.",
+        "**`SelectValue` children render 패턴 추가** — `<SelectValue>{(v) => labels[v as string]}</SelectValue>` 형태로 value → label 매핑. i18n 라벨 노출에 필수 (예: `light` → `라이트`).",
+        "**`CodeEditor` 에 `yaml` / `plaintext` 추가** — `@codemirror/lang-yaml` deps + language enum 확장. YAML convention 파일에 syntax highlighting.",
+        "**Sidebar 토큰 1급 노출** — `--sidebar-bg` / `--sidebar-fg` / `--sidebar-border` / `--sidebar-accent` / `--sidebar-accent-fg` 가 `tokens.css` 메인 셋과 globals.css 의 `@theme inline` 매핑에 정식 등재. Tailwind `bg-sidebar-bg` utility 직접 사용 가능.",
+        "**RootLayout FOUC 차단 inline script** — next-themes mount 전 첫 paint 에 dark/light class 적용. 다크모드 진입 시 light 한 frame 깜빡임 해소. 모든 arch (fsd/flat/mes) × (nextjs-app/nextjs-standalone) 템플릿에 적용.",
+        "**auth-jwt dev bypass flag** — `NEXT_PUBLIC_DEV_AUTH_BYPASS=true` 시 dev 환경에서 proxy.ts 가드 우회. `.env.example` 에 자리표시자 포함, production 빌드에선 무시.",
+        "**i18n boilerplate 확장** — `nav` / `app` / `form` 네임스페이스 + `common` 에 create/name/description/empty 추가.",
+        "**MCP 가이드 추가** — Base UI 합성 함정 (SSR hydration mismatch, `DropdownMenuItem` 안 `DialogTrigger` 가 안 열리는 패턴) 회피 코드 예시를 sh_ui_* 툴 description 에 박음."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.78.0"
+    },
+    {
+      "version": "0.77.1",
+      "date": "2026-05-12",
+      "title": "security — `sh_ui_create_project` / `sh_ui_add_app` path traversal 차단",
+      "type": "patch",
+      "highlights": [
+        "**path traversal 차단** — MCP 호출자가 `name` 인자에 `../` / 절대경로 / 선행 `.` 을 넣어 부모 디렉토리 밖의 임의 경로를 지정하던 흐름 차단. 영숫자 + `_` / `-` / `.` 만 허용 (단, `.` 로 시작 불가).",
+        "**임의 디렉토리 삭제 봉쇄** — `force: true` + 내부 `yes: true` 조합으로 `fs.remove(targetDir)` 가 traversal 경로에 실행되던 흐름을 진입부 검증 + `assertWithin(parent, child)` 가드로 이중 차단.",
+        "CLI / MCP 두 경로 모두 `createProject` / `addApp` 진입부에서 일괄 검증 — 호출 표면 어느 쪽으로도 우회 불가.",
+        "회귀 가드 — `test/name-validation.test.js` 추가 (traversal, 절대경로, 숨김 디렉토리, 셸 메타문자, NUL 바이트 등 29 케이스)."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.77.1"
+    },
     {
       "version": "0.77.0",
       "date": "2026-05-11",

package/data/registry/react/components/code-editor/index.module.tsx

@@ -9,11 +9,13 @@ import { json } from "@codemirror/lang-json";
 import { css as cssLang } from "@codemirror/lang-css";
 import { html } from "@codemirror/lang-html";
 import { markdown } from "@codemirror/lang-markdown";
+import { yaml } from "@codemirror/lang-yaml";
 import styles from "./styles.module.css";
 
 import { cn } from "@SH_UI_UTILS@";
 export type CodeEditorLanguage =
   | "text"
+  | "plaintext"
   | "javascript"
   | "typescript"
   | "jsx"
@@ -21,7 +23,8 @@ export type CodeEditorLanguage =
   | "json"
   | "css"
   | "html"
-  | "markdown";
+  | "markdown"
+  | "yaml";
 
 export interface CodeEditorProps {
   /**
@@ -79,7 +82,10 @@ function languageExtension(language: CodeEditorLanguage): Extension {
       return html();
     case "markdown":
       return markdown();
+    case "yaml":
+      return yaml();
     case "text":
+    case "plaintext":
     default:
       return [];
   }

package/data/registry/react/components/code-editor/index.tailwind.tsx

@@ -9,11 +9,12 @@ import { json } from "@codemirror/lang-json";
 import { css as cssLang } from "@codemirror/lang-css";
 import { html } from "@codemirror/lang-html";
 import { markdown } from "@codemirror/lang-markdown";
+import { yaml } from "@codemirror/lang-yaml";
 
 import { cn } from "@SH_UI_UTILS@";
 export type CodeEditorLanguage =
-  | "text" | "javascript" | "typescript" | "jsx" | "tsx"
-  | "json" | "css" | "html" | "markdown";
+  | "text" | "plaintext" | "javascript" | "typescript" | "jsx" | "tsx"
+  | "json" | "css" | "html" | "markdown" | "yaml";
 
 export interface CodeEditorProps {
   value?: string;
@@ -42,7 +43,9 @@ function languageExtension(language: CodeEditorLanguage): Extension {
     case "css": return cssLang();
     case "html": return html();
     case "markdown": return markdown();
+    case "yaml": return yaml();
     case "text":
+    case "plaintext":
     default: return [];
   }
 }

package/data/registry/react/components/code-editor/index.tsx

@@ -9,11 +9,13 @@ import { json } from "@codemirror/lang-json";
 import { css as cssLang } from "@codemirror/lang-css";
 import { html } from "@codemirror/lang-html";
 import { markdown } from "@codemirror/lang-markdown";
+import { yaml } from "@codemirror/lang-yaml";
 import "./styles.css";
 
 import { cn } from "@SH_UI_UTILS@";
 export type CodeEditorLanguage =
   | "text"
+  | "plaintext"
   | "javascript"
   | "typescript"
   | "jsx"
@@ -21,7 +23,8 @@ export type CodeEditorLanguage =
   | "json"
   | "css"
   | "html"
-  | "markdown";
+  | "markdown"
+  | "yaml";
 
 export interface CodeEditorProps {
   /**
@@ -79,7 +82,10 @@ function languageExtension(language: CodeEditorLanguage): Extension {
       return html();
     case "markdown":
       return markdown();
+    case "yaml":
+      return yaml();
     case "text":
+    case "plaintext":
     default:
       return [];
   }

package/data/registry/react/components/markdown-editor/index.module.tsx

@@ -3,7 +3,7 @@
 import { useState } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
-import { CodeEditor } from "../code-editor";
+import { CodeEditor } from "../code-editor/index.tsx";
 import styles from "./styles.module.css";
 
 import { cn } from "@SH_UI_UTILS@";

package/data/registry/react/components/markdown-editor/index.tailwind.tsx

@@ -3,7 +3,7 @@
 import { useState } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
-import { CodeEditor } from "../code-editor";
+import { CodeEditor } from "../code-editor/index.tsx";
 
 import { cn } from "@SH_UI_UTILS@";
 export interface MarkdownEditorProps {

package/data/registry/react/components/markdown-editor/index.tsx

@@ -3,7 +3,7 @@
 import { useState } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
-import { CodeEditor } from "../code-editor";
+import { CodeEditor } from "../code-editor/index.tsx";
 import "./styles.css";
 
 import { cn } from "@SH_UI_UTILS@";

package/data/registry/react/components/select/index.module.tsx

@@ -8,24 +8,35 @@ import styles from "./styles.module.css";
 import { cn } from "@SH_UI_UTILS@";
 export const Select = BaseSelect.Root;
 
-/** shadcn 호환: <SelectValue placeholder="..." /> */
+/**
+ * shadcn 호환 SelectValue. children 으로 value → label 매핑 함수 전달 가능.
+ *
+ *   <SelectValue placeholder="모드">
+ *     {(v) => ({ light: "라이트", dark: "다크" })[v as string] ?? null}
+ *   </SelectValue>
+ */
 export function SelectValue({
   placeholder,
   className,
+  children,
   ...props
-}: { placeholder?: string; className?: string } & Omit<
+}: {
+  placeholder?: string;
+  className?: string;
+  children?: (value: unknown) => React.ReactNode;
+} & Omit<
   React.ComponentPropsWithoutRef<typeof BaseSelect.Value>,
   "children"
 >) {
   return (
     <BaseSelect.Value className={cn(styles.select__value, className)} {...props}>
-      {(value) =>
-        value !== null && value !== undefined && value !== "" ? (
-          (value as React.ReactNode)
-        ) : (
-          <span className={styles.select__placeholder}>{placeholder}</span>
-        )
-      }
+      {(value) => {
+        if (value === null || value === undefined || value === "") {
+          return <span className={styles.select__placeholder}>{placeholder}</span>;
+        }
+        if (children) return children(value);
+        return value as React.ReactNode;
+      }}
     </BaseSelect.Value>
   );
 }

package/data/registry/react/components/select/index.tailwind.tsx

@@ -7,18 +7,31 @@ import { Select as BaseSelect } from "@base-ui/react/select";
 import { cn } from "@SH_UI_UTILS@";
 export const Select = BaseSelect.Root;
 
-export function SelectValue({ placeholder, className, ...props }: { placeholder?: string; className?: string } & Omit<
+/**
+ * Select 트리거 안에 현재 선택값을 표시. children 으로 value→label 매핑 함수
+ * 전달 가능 (i18n / 다른 표시 텍스트). 미지정 시 value 를 그대로 렌더.
+ */
+export function SelectValue({
+  placeholder,
+  className,
+  children,
+  ...props
+}: {
+  placeholder?: string;
+  className?: string;
+  children?: (value: unknown) => React.ReactNode;
+} & Omit<
   React.ComponentPropsWithoutRef<typeof BaseSelect.Value>, "children"
 >) {
   return (
     <BaseSelect.Value className={cn("flex-1 text-left overflow-hidden text-ellipsis whitespace-nowrap", className)} {...props}>
-      {(value) =>
-        value !== null && value !== undefined && value !== "" ? (
-          (value as React.ReactNode)
-        ) : (
-          <span className="text-foreground-subtle">{placeholder}</span>
-        )
-      }
+      {(value) => {
+        if (value === null || value === undefined || value === "") {
+          return <span className="text-foreground-subtle">{placeholder}</span>;
+        }
+        if (children) return children(value);
+        return value as React.ReactNode;
+      }}
     </BaseSelect.Value>
   );
 }

package/data/registry/react/components/select/index.tsx

@@ -8,24 +8,43 @@ import "./styles.css";
 import { cn } from "@SH_UI_UTILS@";
 export const Select = BaseSelect.Root;
 
-/** shadcn 호환: <SelectValue placeholder="..." /> */
+/**
+ * Select 트리거 안에 현재 선택값을 표시. shadcn 호환 형태.
+ *
+ * 기본은 raw value 를 그대로 렌더. value 와 label 이 다르면 (예: 다국어 라벨)
+ * children 으로 매핑 함수를 전달해 직접 표시할 노드를 만든다.
+ *
+ *   // 1) 기본: value 그대로 표시
+ *   <SelectValue placeholder="선택" />
+ *
+ *   // 2) value → label 매핑 (i18n)
+ *   <SelectValue placeholder="모드">
+ *     {(v) => ({ light: "라이트", dark: "다크" })[v as string] ?? null}
+ *   </SelectValue>
+ */
 export function SelectValue({
   placeholder,
   className,
+  children,
   ...props
-}: { placeholder?: string; className?: string } & Omit<
+}: {
+  placeholder?: string;
+  className?: string;
+  /** value 를 표시 노드로 매핑. 미지정 시 value 를 그대로 렌더. */
+  children?: (value: unknown) => React.ReactNode;
+} & Omit<
   React.ComponentPropsWithoutRef<typeof BaseSelect.Value>,
   "children"
 >) {
   return (
     <BaseSelect.Value className={cn("sh-ui-select__value", className)} {...props}>
-      {(value) =>
-        value !== null && value !== undefined && value !== "" ? (
-          (value as React.ReactNode)
-        ) : (
-          <span className="sh-ui-select__placeholder">{placeholder}</span>
-        )
-      }
+      {(value) => {
+        if (value === null || value === undefined || value === "") {
+          return <span className="sh-ui-select__placeholder">{placeholder}</span>;
+        }
+        if (children) return children(value);
+        return value as React.ReactNode;
+      }}
     </BaseSelect.Value>
   );
 }

package/data/registry/react/components/sidebar/index.module.tsx

@@ -3,7 +3,7 @@
 import * as React from "react";
 import { cn } from "@SH_UI_UTILS@";
 import { ChevronRightIcon, PanelLeftIcon } from "lucide-react";
-import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover/index.tsx";
 import styles from "./styles.module.css";
 
 const SIDEBAR_COOKIE_NAME = "sidebar_state";
@@ -643,7 +643,9 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
       className);
 
     if (render && React.isValidElement(render)) {
-      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode; "data-active"?: string | boolean }>;
+      const childDataActive = child.props["data-active"];
+      const dataActive = childDataActive !== undefined ? childDataActive : resolvedIsActive || undefined;
       return React.cloneElement(
         child,
         {
@@ -651,7 +653,7 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
           ...props,
           onClick: handleClick,
           className: cn(child.props.className, cls),
-          "data-active": resolvedIsActive || undefined,
+          "data-active": dataActive,
         } as Record<string, unknown>,
         children ?? child.props.children,
       );
@@ -724,14 +726,16 @@ export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarM
       className);
 
     if (render && React.isValidElement(render)) {
-      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode; "data-active"?: string | boolean }>;
+      const childDataActive = child.props["data-active"];
+      const dataActive = childDataActive !== undefined ? childDataActive : resolvedIsActive || undefined;
       return React.cloneElement(
         child,
         {
           ref,
           ...props,
           className: cn(child.props.className, cls),
-          "data-active": resolvedIsActive || undefined,
+          "data-active": dataActive,
         } as Record<string, unknown>,
         children ?? child.props.children,
       );
@@ -876,7 +880,7 @@ export function SidebarCollapsibleTrigger({
         openOnHover
         delay={0}
         closeDelay={150}
-        render={(triggerProps) => (
+        render={(triggerProps: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
           <button
             {...triggerProps}
             {...props}

package/data/registry/react/components/sidebar/index.tailwind.tsx

@@ -3,7 +3,7 @@
 import * as React from "react";
 import { cn } from "@SH_UI_UTILS@";
 import { ChevronRightIcon, PanelLeftIcon } from "lucide-react";
-import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover/index.tsx";
 
 const SIDEBAR_COOKIE_NAME = "sidebar_state";
 const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
@@ -384,7 +384,9 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
     const cls = cn(menuButtonBase, menuButtonSize[size], className);
 
     if (render && React.isValidElement(render)) {
-      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode; "data-active"?: string | boolean }>;
+      const childDataActive = child.props["data-active"];
+      const dataActive = childDataActive !== undefined ? childDataActive : resolvedIsActive || undefined;
       return React.cloneElement(
         child,
         {
@@ -392,7 +394,7 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
           ...props,
           onClick: handleClick,
           className: cn(child.props.className, cls),
-          "data-active": resolvedIsActive || undefined,
+          "data-active": dataActive,
         } as Record<string, unknown>,
         children ?? child.props.children,
       );
@@ -440,14 +442,16 @@ export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarM
     const cls = cn(menuSubButtonBase, size === "sm" && "text-[length:var(--text-xs)]", className);
 
     if (render && React.isValidElement(render)) {
-      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
+      const child = render as React.ReactElement<{ className?: string; children?: React.ReactNode; "data-active"?: string | boolean }>;
+      const childDataActive = child.props["data-active"];
+      const dataActive = childDataActive !== undefined ? childDataActive : resolvedIsActive || undefined;
       return React.cloneElement(
         child,
         {
           ref,
           ...props,
           className: cn(child.props.className, cls),
-          "data-active": resolvedIsActive || undefined,
+          "data-active": dataActive,
         } as Record<string, unknown>,
         children ?? child.props.children,
       );
@@ -524,7 +528,7 @@ export function SidebarCollapsibleTrigger({ className, size = "md", children, on
         openOnHover
         delay={0}
         closeDelay={150}
-        render={(triggerProps) => (
+        render={(triggerProps: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
           <button {...triggerProps} {...props} type="button" className={cls} data-state={isOpen ? "open" : "closed"}>
             {content}
           </button>

package/data/registry/react/components/sidebar/index.tsx

@@ -3,7 +3,7 @@
 import * as React from "react";
 import { cn } from "@SH_UI_UTILS@";
 import { ChevronRightIcon, PanelLeftIcon } from "lucide-react";
-import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover/index.tsx";
 import "./styles.css";
 
 const SIDEBAR_COOKIE_NAME = "sidebar_state";
@@ -647,7 +647,16 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
       const child = render as React.ReactElement<{
         className?: string;
         children?: React.ReactNode;
+        "data-active"?: string | boolean;
       }>;
+      // 자식이 명시한 data-active 가 있으면 보존 (사용자가 자기 디자인 시스템의
+      // active state 를 data-active 셀렉터로 다루는 경우). 그 외엔 sh-ui 의
+      // 자동 추론값 사용.
+      const childDataActive = child.props["data-active"];
+      const dataActive =
+        childDataActive !== undefined
+          ? childDataActive
+          : resolvedIsActive || undefined;
       return React.cloneElement(
         child,
         {
@@ -655,7 +664,7 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
           ...props,
           onClick: handleClick,
           className: cn(child.props.className, cls),
-          "data-active": resolvedIsActive || undefined,
+          "data-active": dataActive,
         } as Record<string, unknown>,
         children ?? child.props.children,
       );
@@ -734,14 +743,21 @@ export const SidebarMenuSubButton = React.forwardRef<HTMLAnchorElement, SidebarM
       const child = render as React.ReactElement<{
         className?: string;
         children?: React.ReactNode;
+        "data-active"?: string | boolean;
       }>;
+      // 자식이 명시한 data-active 우선 (자기 디자인 시스템 호환).
+      const childDataActive = child.props["data-active"];
+      const dataActive =
+        childDataActive !== undefined
+          ? childDataActive
+          : resolvedIsActive || undefined;
       return React.cloneElement(
         child,
         {
           ref,
           ...props,
           className: cn(child.props.className, cls),
-          "data-active": resolvedIsActive || undefined,
+          "data-active": dataActive,
         } as Record<string, unknown>,
         children ?? child.props.children,
       );
@@ -886,7 +902,7 @@ export function SidebarCollapsibleTrigger({
         openOnHover
         delay={0}
         closeDelay={150}
-        render={(triggerProps) => (
+        render={(triggerProps: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
           <button
             {...triggerProps}
             {...props}

package/data/registry/react/registry.json

@@ -576,7 +576,8 @@
         "@codemirror/lang-json",
         "@codemirror/lang-css",
         "@codemirror/lang-html",
-        "@codemirror/lang-markdown"
+        "@codemirror/lang-markdown",
+        "@codemirror/lang-yaml"
       ],
       "registryDependencies": [
         "utils"

package/data/tokens/src/semantic.json

@@ -28,7 +28,14 @@
       "foreground": { "$value": "{color.white}", "$type": "color" },
       "hover":      { "$value": "{color.red.700}", "$type": "color" }
     },
-    "ring": { "$value": "{color.{base}.400}", "$type": "color" }
+    "ring": { "$value": "{color.{base}.400}", "$type": "color" },
+    "sidebar": {
+      "bg":         { "$value": "{color.{base}.50}",  "$type": "color" },
+      "fg":         { "$value": "{color.{base}.950}", "$type": "color" },
+      "border":     { "$value": "{color.{base}.200}", "$type": "color" },
+      "accent":     { "$value": "{color.{base}.100}", "$type": "color" },
+      "accent-fg":  { "$value": "{color.{base}.950}", "$type": "color" }
+    }
   },
 
   "dark": {
@@ -58,7 +65,14 @@
       "foreground": { "$value": "{color.white}", "$type": "color" },
       "hover":      { "$value": "{color.red.500}", "$type": "color" }
     },
-    "ring": { "$value": "{color.{base}.500}", "$type": "color" }
+    "ring": { "$value": "{color.{base}.500}", "$type": "color" },
+    "sidebar": {
+      "bg":         { "$value": "{color.{base}.900}", "$type": "color" },
+      "fg":         { "$value": "{color.{base}.50}",  "$type": "color" },
+      "border":     { "$value": "{color.{base}.800}", "$type": "color" },
+      "accent":     { "$value": "{color.{base}.800}", "$type": "color" },
+      "accent-fg":  { "$value": "{color.{base}.50}",  "$type": "color" }
+    }
   },
 
   "radius": {

package/package.json

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

package/src/create/generator.js

@@ -152,6 +152,41 @@ function assertNoTtyFlag(value, flagLabel) {
   }
 }
 
+// 프로젝트/앱 이름을 디렉토리명으로 안전하게 쓸 수 있는지 검증.
+// MCP (sh_ui_create_project / sh_ui_add_app) 는 LLM/외부 호출자가 임의의 문자열을 넘길 수
+// 있는데, 그 값이 그대로 `path.resolve(parent, name)` 에 들어간다. 검증이 없으면 '../'
+// 시퀀스로 부모 디렉토리를 벗어나 임의 위치에 파일 쓰기 / 기존 디렉토리 삭제(force+yes 경로)
+// 까지 가능. 진입부에서 한 번 막아 두면 CLI 와 MCP 양쪽 모두 자동 차단.
+export function validateProjectName(name, label = 'name') {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error(`${label} 가 비어있습니다.`);
+  }
+  if (name.length > 214) {
+    throw new Error(`${label} 가 너무 깁니다 (최대 214자).`);
+  }
+  // 선행 '.' 차단 → '..', '.ssh', '.git' 등 숨김/특수 디렉토리 봉쇄.
+  // 영숫자 + '.' + '_' + '-' 만 허용 → 경로 구분자('/', '\\'), NUL, 셸 메타문자 일괄 차단.
+  if (name.startsWith('.') || !/^[a-zA-Z0-9._-]+$/.test(name)) {
+    throw new Error(
+      `${label} '${name}' 가 유효하지 않습니다 — ` +
+      `영숫자, '_', '-', '.' 만 허용하며 '.' 로 시작할 수 없습니다 (디렉토리 이름만 허용, 경로 불가).`,
+    );
+  }
+  return name;
+}
+
+// 방어 가드 — validateProjectName 이 이미 traversal 을 차단하지만, 파괴적 작업(`fs.remove`)
+// 직전에 한 번 더 봉쇄해 향후 다른 진입점이 추가되거나 검증을 우회하는 코드 패스가 생겨도
+// 부모 디렉토리 밖을 건드리지 않도록 보장. parent 의 진짜 하위가 아니면 throw.
+function assertWithin(parent, child) {
+  const rel = path.relative(parent, child);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(
+      `safety: 대상 경로 '${child}' 가 부모 '${parent}' 외부 또는 부모 그 자체입니다 — 처리 거부.`,
+    );
+  }
+}
+
 export async function createProject(options = {}) {
   if (!process.stdin.isTTY) {
     assertNoTtyFlag(options.name, '<project-name> (positional)');
@@ -161,10 +196,13 @@ export async function createProject(options = {}) {
     }
   }
 
-  const projectName = options.name ?? await input({
-    message: '프로젝트 이름:',
-    default: 'my-app',
-  });
+  const projectName = validateProjectName(
+    options.name ?? await input({
+      message: '프로젝트 이름:',
+      default: 'my-app',
+    }),
+    '프로젝트 이름',
+  );
 
   const platform = options.platform ?? await select({
     message: '플랫폼:',
@@ -247,6 +285,12 @@ export async function createProject(options = {}) {
     ? await fs.mkdtemp(path.join(os.tmpdir(), 'sh-ui-dry-'))
     : path.resolve(process.cwd(), projectName);
 
+  // 방어 가드 — projectName 검증을 이미 통과했어도 `fs.remove` 직전에 한 번 더 확인.
+  // dry-run 은 tmpdir 이라 parent 가 cwd 가 아니므로 스킵.
+  if (!options.dryRun) {
+    assertWithin(process.cwd(), targetDir);
+  }
+
   if (!options.dryRun && await fs.pathExists(targetDir)) {
     if (options.yes) {
       await fs.remove(targetDir);
@@ -361,10 +405,13 @@ export async function addApp(options = {}) {
     throw new Error('비대화형 환경(TTY 없음)에서는 name 이 필요합니다.');
   }
 
-  const appName = options.name ?? await input({
-    message: '앱 이름:',
-    default: 'web',
-  });
+  const appName = validateProjectName(
+    options.name ?? await input({
+      message: '앱 이름:',
+      default: 'web',
+    }),
+    '앱 이름',
+  );
 
   const port = options.port ?? (process.stdin.isTTY
     ? await input({ message: '포트 번호:', default: '3000' })
@@ -1504,8 +1551,13 @@ const stripLocalePrefix = (pathname: string): string => {
  * - \`/\` + HOME_REDIRECT 설정 → 해당 경로로 리다이렉트 (인증 가드보다 먼저)
  * - intl 이 로케일 prefix 처리 + NEXT_LOCALE 쿠키 set
  * - 그 위에 인증 가드 — 토큰 없고 인증 라우트도 아니면 /sign-in 으로 redirect
+ * - dev + \`NEXT_PUBLIC_DEV_AUTH_BYPASS=true\` → 가드 전체 우회 (개발용)
  * - AT 만료 검사나 refresh 는 하지 않는다 (BFF 가 처리)
  */
+const DEV_BYPASS =
+  process.env.NODE_ENV !== 'production' &&
+  process.env.NEXT_PUBLIC_DEV_AUTH_BYPASS === 'true';
+
 export default function proxy(req: NextRequest) {
   const intlRes = intl(req);
   const pathname = stripLocalePrefix(req.nextUrl.pathname);
@@ -1516,6 +1568,7 @@ export default function proxy(req: NextRequest) {
     return NextResponse.redirect(new URL(HOME_REDIRECT, req.url));
   }
 
+  if (DEV_BYPASS) return intlRes;
   if (isAuthRoute) return intlRes;
   if (!hasToken) return NextResponse.redirect(new URL('/sign-in', req.url));
 

package/src/create/plugins/authJwt.js

@@ -16,10 +16,14 @@ export const authJwtPlugin = {
   envVars: [
     '# Auth (auth-jwt)',
     'COOKIE_SECURE=false',
+    '# Dev 시 인증 가드 우회 — proxy.ts 가 이 flag 를 보면 /sign-in 으로 redirect 안 함.',
+    '# 실제 백엔드 연동 후엔 반드시 비워야 함 (또는 NODE_ENV 가 production 이면 무시).',
+    'NEXT_PUBLIC_DEV_AUTH_BYPASS=false',
   ],
 
   turboEnvVars: [
     'COOKIE_SECURE',
+    'NEXT_PUBLIC_DEV_AUTH_BYPASS',
   ],
 
   providerImports: [],
@@ -101,10 +105,15 @@ const HOME_REDIRECT = '';
  * - \`/\` + HOME_REDIRECT 설정 → 해당 경로로 리다이렉트
  * - AT 쿠키 없음 + 인증 라우트 아님 → /sign-in 으로 리다이렉트
  * - AT 쿠키 있음 또는 인증 라우트 → 통과
+ * - dev + \`NEXT_PUBLIC_DEV_AUTH_BYPASS=true\` → 가드 전체 우회 (개발용)
  *
  * AT 가 만료된 채 통과한 요청은 BFF (/api/proxy) 가 401 을 받아
  * refreshSession 으로 갱신을 시도한다.
  */
+const DEV_BYPASS =
+  process.env.NODE_ENV !== 'production' &&
+  process.env.NEXT_PUBLIC_DEV_AUTH_BYPASS === 'true';
+
 export default function proxy(req: NextRequest) {
   const { pathname } = req.nextUrl;
   const hasToken = !!req.cookies.get('accessToken')?.value;
@@ -114,6 +123,7 @@ export default function proxy(req: NextRequest) {
     return NextResponse.redirect(new URL(HOME_REDIRECT, req.url));
   }
 
+  if (DEV_BYPASS) return NextResponse.next();
   if (isAuthRoute) return NextResponse.next();
   if (!hasToken) return NextResponse.redirect(new URL('/sign-in', req.url));
 

package/src/create/plugins/nextIntl.js

@@ -271,8 +271,25 @@ export const { Link, redirect, usePathname, useRouter, getPathname } =
     "save": "저장",
     "delete": "삭제",
     "edit": "수정",
+    "create": "만들기",
     "search": "검색",
-    "back": "뒤로"
+    "back": "뒤로",
+    "name": "이름",
+    "description": "설명",
+    "empty": "아직 항목이 없습니다."
+  },
+  "nav": {
+    "home": "홈",
+    "settings": "설정"
+  },
+  "app": {
+    "title": "App"
+  },
+  "form": {
+    "required": "필수 항목입니다.",
+    "invalid": "올바른 값을 입력하세요.",
+    "submit": "제출",
+    "reset": "초기화"
   },
   "error": {
     "title": "오류가 발생했습니다",
@@ -302,8 +319,25 @@ export const { Link, redirect, usePathname, useRouter, getPathname } =
     "save": "Save",
     "delete": "Delete",
     "edit": "Edit",
+    "create": "Create",
     "search": "Search",
-    "back": "Back"
+    "back": "Back",
+    "name": "Name",
+    "description": "Description",
+    "empty": "No items yet."
+  },
+  "nav": {
+    "home": "Home",
+    "settings": "Settings"
+  },
+  "app": {
+    "title": "App"
+  },
+  "form": {
+    "required": "This field is required.",
+    "invalid": "Please enter a valid value.",
+    "submit": "Submit",
+    "reset": "Reset"
   },
   "error": {
     "title": "Something went wrong",

package/src/mcp.mjs

@@ -32,7 +32,7 @@ import { list } from "./list.mjs";
 import { remove } from "./remove.mjs";
 import { renameApp } from "./rename-app.mjs";
 import { migrateToV065 } from "./migrate-v065.mjs";
-import { createProject, addApp } from "./create/generator.js";
+import { createProject, addApp, validateProjectName } from "./create/generator.js";
 import {
   getRegistryRoot,
   getSummariesPath,
@@ -263,6 +263,59 @@ CLI \`sh-ui add <name>\` 은 monorepo 의 어느 디렉토리에서든 (apps/web
 - 다이얼로그 cancel 버튼을 \`<Button onClick={() => setOpen(false)}>\` 로 우회 → 정석은 \`<DialogClose render={<Button>취소</Button>} />\` (Base UI render prop)
 - table 외관의 카드 그리드를 raw \`<div>\` 로 → \`Card\` / \`CardHeader\` / \`CardContent\` / \`CardFooter\` 사용
 
+## Base UI 합성 함정 (Next.js App Router)
+
+Base UI 위에 빌드된 sh-ui 컴포넌트 (\`DropdownMenu\` / \`Select\` / \`Dialog\` / \`Popover\` / \`Tooltip\` / \`Combobox\`) 두 가지 알려진 패턴:
+
+### 1. SSR hydration warning (auto-id)
+
+Base UI 의 \`useId()\` 가 서버/클라이언트 ID 가 다를 수 있어 hydration mismatch 경고. 동작은 무해하지만 콘솔 노이즈.
+
+**회피 패턴 — mounted gate** (sidebar header 등 항상 보이는 trigger 에 적용):
+
+\`\`\`tsx
+const [mounted, setMounted] = useState(false);
+useEffect(() => setMounted(true), []);
+
+if (!mounted) {
+  // trigger 외형만 그대로, dropdown wrapping 없이 placeholder 렌더
+  return <div className={TRIGGER_CLS}>…</div>;
+}
+return (
+  <DropdownMenu>
+    <DropdownMenuTrigger className={TRIGGER_CLS}>…</DropdownMenuTrigger>
+    <DropdownMenuContent>…</DropdownMenuContent>
+  </DropdownMenu>
+);
+\`\`\`
+
+### 2. \`DropdownMenuItem\` 안에 \`DialogTrigger\` render 시 dialog 안 열림
+
+두 Base UI primitive 의 render-prop 체인이 onClick / onSelect 충돌.
+
+**잘못된 패턴**:
+\`\`\`tsx
+<DropdownMenuItem onSelect={(e) => e.preventDefault()}>
+  <DialogTrigger render={<Button>…</Button>} />   // 안 열림
+</DropdownMenuItem>
+\`\`\`
+
+**정석 패턴 — controlled dialog 를 sibling 으로**:
+\`\`\`tsx
+const [open, setOpen] = useState(false);
+return (
+  <>
+    <DropdownMenu>
+      …
+      <DropdownMenuItem onClick={() => setOpen(true)}>…</DropdownMenuItem>
+    </DropdownMenu>
+    <MyDialog open={open} onOpenChange={setOpen} />
+  </>
+);
+\`\`\`
+
+다이얼로그 컴포넌트는 controlled (\`open\`/\`onOpenChange\`) 모드를 지원하도록 작성해 둘 것.
+
 ## 앱 이름 변경 (monorepo)
 
 사용자가 "apps/web 을 apps/dashboard 로 바꿔줘" 같이 모노레포 앱 이름 변경을 요청하면 \`sh_ui_rename_app\` 사용 — 손으로 6~10 군데 (디렉토리, package.json name, tsconfig paths, Dockerfile WORKDIR, next.config transpilePackages, sh-ui.config aliases, README, .github/workflows) 갈아엎지 않도록 자동화. \`dryRun: true\` 로 먼저 변경 매트릭스 보여주고 사용자 확인 후 실행 권장.
@@ -354,6 +407,13 @@ export async function startMcpServer() {
           ],
         };
       }
+      // path traversal 차단 — existsSync probe / fs.remove 흐름이 임의 경로로
+      // 흘러가지 않도록 입력 검증을 가장 먼저.
+      try {
+        validateProjectName(input.name, "name");
+      } catch (e) {
+        return { isError: true, content: [{ type: "text", text: e.message }] };
+      }
       const targetParent = resolveCwd(input);
       const targetDir = resolve(targetParent, input.name);
       if (existsSync(targetDir) && !input.force) {
@@ -413,6 +473,11 @@ export async function startMcpServer() {
       },
     },
     async (input) => {
+      try {
+        validateProjectName(input.name, "name");
+      } catch (e) {
+        return { isError: true, content: [{ type: "text", text: e.message }] };
+      }
       const text = await captureConsole(() =>
         addApp({
           name: input.name,

package/templates/monorepo/CLAUDE.md

@@ -0,0 +1,40 @@
+# 프로젝트 작업 규칙
+
+sh-ui CLI 가 스캐폴드한 monorepo (Turborepo + pnpm workspace). AI 에이전트
+(Claude / Cursor / Codex 등) 가 이 파일을 컨텍스트로 읽고 아래 규칙을 따른다.
+
+## 구조
+
+- `apps/<name>/` — Next.js 앱. 라우트 + 비즈니스 로직.
+- `packages/ui/ui-core/` — 모든 앱이 공유하는 sh-ui 컴포넌트 / 훅 / 유틸 SoT.
+  컴포넌트 추가는 여기에 한 번만.
+- `packages/ui/ui-apps/ui-<name>/` — 앱별 토큰 (color/spacing/font) 만 보관.
+  컴포넌트는 두지 않음 (v0.65+ `tokens-only` 마커).
+- `packages/eslint-config/` · `packages/typescript-config/` — 공용 설정.
+
+## 날짜 / 숫자 포맷
+
+- raw `Date.prototype.toLocaleDateString()` / `toLocaleString()` / `toLocaleTimeString()`
+  호출 **금지** — SSR(Node) 와 브라우저의 기본 로케일이 달라 hydration mismatch 의
+  원인. ESLint `no-restricted-syntax` 룰이 인자 0개의 호출을 막는다
+  (`@workspace/eslint-config/base` 에 정의).
+- 대신 `@/src/shared/lib/formatDate` 의 `formatDate(date)` / `formatDateTime(date)`
+  사용 (default locale `ko-KR`, 서버·클라이언트 동일 출력 보장).
+- next-intl locale 추종이 필요하면 `@/src/shared/hooks/useFormatDate` 훅 사용.
+- 동일 원칙이 숫자에도 적용 — raw `Number.prototype.toLocaleString()` 금지,
+  `formatPrice` 사용.
+- 인자가 명시된 호출 (`toLocaleDateString('ko-KR', { ... })`) 은 의도된 사용이므로
+  허용. 다만 SSR 출력 결정성을 위해서는 util 경유가 안전.
+
+## 새 앱 추가
+
+`sh_ui_add_app` MCP 툴 또는 `npx sh-ui-cli add app <name>` — `apps/<name>/` +
+`packages/ui/ui-apps/ui-<name>/` 를 한 번에 만든다. 앱별로 다른 톤 가능 (예:
+marketing = rose, admin = emerald). 컴포넌트는 `ui-core` 단일 SoT 라 두 앱이
+자동 공유.
+
+## 토큰 사용
+
+- 색상 / 간격 / 폰트 크기는 항상 토큰 변수 경유 (`var(--space-3)`, `bg-fg`,
+  `text-fg-muted` 등). 매직 px / hex 직접 하드코딩 금지.
+- 토큰 정의부는 `packages/ui/ui-apps/ui-<name>/src/styles/tokens.css`.

package/templates/monorepo/packages/eslint-config/base.js

@@ -18,6 +18,15 @@ export const config = [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `@/src/shared/lib/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },
   {

package/templates/monorepo/packages/ui/ui-core/package.json

@@ -28,7 +28,7 @@
     "typescript": "^5.9.3"
   },
   "exports": {
-    "./components/*": "./src/components/*.tsx",
+    "./components/*": "./src/components/*/index.tsx",
     "./hooks/*": "./src/hooks/*.ts",
     "./lib/*": "./src/lib/*.ts"
   }

package/templates/nextjs-app/_arch/flat/components/layouts/RootLayout.tsx

@@ -1,10 +1,16 @@
 import { GlobalProvider } from '@/components/providers';
 
+/** FOUC 차단 — next-themes mount 전에 첫 paint 에 dark/light class 박기. */
+const themeInitScript = `try{var t=localStorage.getItem('theme');var c=document.documentElement.classList;if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches)){c.add('dark');}else if(t==='light'){c.add('light');}}catch(e){}`;
+
 export function RootLayout({ children }: { children: React.ReactNode }) {
   // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
   // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
       <body>
         <GlobalProvider>{children}</GlobalProvider>
       </body>

package/templates/nextjs-app/_arch/fsd/src/app/layouts/RootLayout.tsx

@@ -1,10 +1,21 @@
 import { GlobalProvider } from '@/src/app/providers';
 
+/**
+ * 첫 paint 전에 localStorage 의 theme 값을 읽어 <html> 에 class 를 박는
+ * FOUC 차단 inline script. next-themes 의 ThemeProvider 가 client mount 후
+ * 동일 작업을 하지만, mount 전 한 frame 동안 light/dark 깜빡임이 생긴다.
+ * 이걸 막으려고 SSR 응답 head 안쪽에 동기 실행 script 박음.
+ */
+const themeInitScript = `try{var t=localStorage.getItem('theme');var c=document.documentElement.classList;if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches)){c.add('dark');}else if(t==='light'){c.add('light');}}catch(e){}`;
+
 export function RootLayout({ children }: { children: React.ReactNode }) {
   // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
   // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
       <body>
         <GlobalProvider>{children}</GlobalProvider>
       </body>

package/templates/nextjs-app/_arch/mes/src/components/layouts/RootLayout.tsx

@@ -1,10 +1,16 @@
 import { GlobalProvider } from '@/components/providers';
 
+/** FOUC 차단 — next-themes mount 전에 첫 paint 에 dark/light class 박기. */
+const themeInitScript = `try{var t=localStorage.getItem('theme');var c=document.documentElement.classList;if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches)){c.add('dark');}else if(t==='light'){c.add('light');}}catch(e){}`;
+
 export function RootLayout({ children }: { children: React.ReactNode }) {
   // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
   // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
       <body>
         <GlobalProvider>{children}</GlobalProvider>
       </body>

package/templates/nextjs-standalone/CLAUDE.md

@@ -0,0 +1,30 @@
+# 프로젝트 작업 규칙
+
+sh-ui CLI 가 스캐폴드한 Next.js standalone 프로젝트. AI 에이전트 (Claude / Cursor /
+Codex 등) 가 이 파일을 컨텍스트로 읽고 아래 규칙을 따른다.
+
+## 날짜 / 숫자 포맷
+
+- raw `Date.prototype.toLocaleDateString()` / `toLocaleString()` / `toLocaleTimeString()`
+  호출 **금지** — SSR(Node) 와 브라우저의 기본 로케일이 달라 hydration mismatch 의
+  원인. ESLint `no-restricted-syntax` 룰이 인자 0개의 호출을 막는다.
+- 대신 `@/src/shared/lib/formatDate` 의 `formatDate(date)` / `formatDateTime(date)`
+  사용 (default locale `ko-KR`, 서버·클라이언트 동일 출력 보장).
+- next-intl locale 추종이 필요하면 `@/src/shared/hooks/useFormatDate` 훅 사용.
+- 동일 원칙이 숫자에도 적용 — raw `Number.prototype.toLocaleString()` 금지,
+  `@/src/shared/lib/formatPrice` 의 `formatPrice` 사용.
+- 인자가 명시된 호출 (`toLocaleDateString('ko-KR', { ... })`) 은 의도된 사용이므로
+  허용. 다만 SSR 출력 결정성을 위해서는 util 경유가 안전.
+
+## sh-ui 컴포넌트 우선
+
+- shadcn/ui 류 외부 라이브러리 대신 이 프로젝트의 `components/ui/*` (sh-ui 레지스트리)
+  사용. Base UI (`@base-ui-components/react`) 위에 빌드되어 있음.
+- 새 컴포넌트가 필요하면 `npx sh-ui-cli add <name>` 또는 sh-ui MCP 의
+  `sh_ui_add_component` 사용.
+
+## 토큰 사용
+
+- 색상 / 간격 / 폰트 크기는 항상 토큰 변수 경유 (`var(--space-3)`, `bg-fg`,
+  `text-fg-muted` 등). 매직 px / hex 직접 하드코딩 금지.
+- 토큰 정의부는 `app/globals.css` 또는 `src/shared/styles/tokens.css`.

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

@@ -35,6 +35,11 @@
   --color-warning-foreground: var(--warning-foreground);
   --color-info: var(--info);
   --color-info-foreground: var(--info-foreground);
+  --color-sidebar-bg: var(--sidebar-bg);
+  --color-sidebar-fg: var(--sidebar-fg);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-fg: var(--sidebar-accent-fg);
   --radius-sm: calc(var(--radius) - 2px);
   --radius-md: var(--radius);
   --radius-lg: calc(var(--radius) + 2px);

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

@@ -1,10 +1,16 @@
 import { GlobalProvider } from '@/components/providers';
 
+/** FOUC 차단 — next-themes mount 전에 첫 paint 에 dark/light class 박기. */
+const themeInitScript = `try{var t=localStorage.getItem('theme');var c=document.documentElement.classList;if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches)){c.add('dark');}else if(t==='light'){c.add('light');}}catch(e){}`;
+
 export function RootLayout({ children }: { children: React.ReactNode }) {
   // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
   // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
       <body>
         <GlobalProvider>{children}</GlobalProvider>
       </body>

package/templates/nextjs-standalone/_arch/flat/eslint.config.js

@@ -27,6 +27,15 @@ export default [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `lib/utils/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },
 

package/templates/nextjs-standalone/_arch/fsd/src/app/layouts/RootLayout.tsx

@@ -1,10 +1,16 @@
 import { GlobalProvider } from '@/src/app/providers';
 
+/** FOUC 차단 — next-themes mount 전에 첫 paint 에 dark/light class 박기. */
+const themeInitScript = `try{var t=localStorage.getItem('theme');var c=document.documentElement.classList;if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches)){c.add('dark');}else if(t==='light'){c.add('light');}}catch(e){}`;
+
 export function RootLayout({ children }: { children: React.ReactNode }) {
   // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
   // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
       <body>
         <GlobalProvider>{children}</GlobalProvider>
       </body>

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

@@ -35,6 +35,11 @@
   --color-warning-foreground: var(--warning-foreground);
   --color-info: var(--info);
   --color-info-foreground: var(--info-foreground);
+  --color-sidebar-bg: var(--sidebar-bg);
+  --color-sidebar-fg: var(--sidebar-fg);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-fg: var(--sidebar-accent-fg);
   --radius-sm: calc(var(--radius) - 2px);
   --radius-md: var(--radius);
   --radius-lg: calc(var(--radius) + 2px);

package/templates/nextjs-standalone/_arch/mes/eslint.config.js

@@ -27,6 +27,15 @@ export default [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `src/lib/utils/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },
 

package/templates/nextjs-standalone/_arch/mes/src/components/layouts/RootLayout.tsx

@@ -1,10 +1,16 @@
 import { GlobalProvider } from '@/components/providers';
 
+/** FOUC 차단 — next-themes mount 전에 첫 paint 에 dark/light class 박기. */
+const themeInitScript = `try{var t=localStorage.getItem('theme');var c=document.documentElement.classList;if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches)){c.add('dark');}else if(t==='light'){c.add('light');}}catch(e){}`;
+
 export function RootLayout({ children }: { children: React.ReactNode }) {
   // `lang` 은 앱의 주 언어. 영어 등 다른 언어 우선이면 'en' 으로 바꾸거나
   // next-intl 플러그인을 활성화해 라우트 기반 자동 분기로 전환하세요.
   return (
     <html lang='ko' suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
       <body>
         <GlobalProvider>{children}</GlobalProvider>
       </body>

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

@@ -31,6 +31,11 @@
   --color-warning-foreground: var(--warning-foreground);
   --color-info: var(--info);
   --color-info-foreground: var(--info-foreground);
+  --color-sidebar-bg: var(--sidebar-bg);
+  --color-sidebar-fg: var(--sidebar-fg);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-fg: var(--sidebar-accent-fg);
   --radius-sm: calc(var(--radius) - 2px);
   --radius-md: var(--radius);
   --radius-lg: calc(var(--radius) + 2px);

package/templates/nextjs-standalone/eslint.config.js

@@ -27,6 +27,15 @@ export default [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `@/src/shared/lib/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },
 

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

@@ -35,6 +35,11 @@
   --color-warning-foreground: var(--warning-foreground);
   --color-info: var(--info);
   --color-info-foreground: var(--info-foreground);
+  --color-sidebar-bg: var(--sidebar-bg);
+  --color-sidebar-fg: var(--sidebar-fg);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-fg: var(--sidebar-accent-fg);
   --radius-sm: calc(var(--radius) - 2px);
   --radius-md: var(--radius);
   --radius-lg: calc(var(--radius) + 2px);