feat(controls): P0/P0.5 Control 전 항목 구현 및 라이트/다크 테마 시스템 구축

**packages/controls:**
- P0: Button, Input, Select, Checkbox/CheckboxGroup, RadioGroup, Switch,
       Modal, FormField, Alert, Progress/StepProgress
- P0.5: Textarea, PasswordInput(strength), OtpInput, SearchInput(debounce),
         Spinner(blocking/inline), ToastProvider/useToast, EmptyState, Skeleton
- controls.css: fs- 접두사, CSS 변수 기반 라이트/다크 공통 스타일
- package.json: ESM 전환, react peerDep, exports.styles 추가
- CONTROL_DESCRIPTORS: P0/P0.5 ready: true 반영

**apps/web/src/styles/global.css:**
- 라이트 모드(:root 기본값) + 다크 모드([data-theme="dark"] / prefers-color-scheme) 분리
- --ok-subtle / --warn-subtle / --err-subtle / --info-subtle 토큰 추가
- 기존 유틸 클래스 하드코딩 색상을 CSS 변수로 교체

**apps/web:**
- main.tsx: controls.css import, ThemeSetting 타입 + applyTheme/loadTheme 헬퍼,
            앱 초기화 시 FOUC 방지 테마 적용, App 컴포넌트에 theme 상태 추가
- SettingsView: theme prop 수신 → 테마 변경 시 data-theme + localStorage 저장

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SOIV

apps/web/src/main.tsx

@@ -3,6 +3,7 @@ import { createRoot } from "react-dom/client";
 
 import "./styles/global.css";
 import "./styles/login.css";
+import "@fieldstack/controls/styles";
 
 import { AppShell, type RouteKey } from "./components/AppShell";
 import { AdminPinModal } from "./components/AdminPinModal";
@@ -46,6 +47,30 @@ function getRouteFromHash(rawHash: string): RouteKey {
   return (valid as string[]).includes(hash) ? (hash as RouteKey) : "login";
 }
 
+// ─── Theme ────────────────────────────────────────────────────
+type ThemeSetting = "light" | "dark" | "system";
+
+function applyTheme(setting: ThemeSetting) {
+  const root = document.documentElement;
+  if (setting === "system") {
+    root.removeAttribute("data-theme");
+  } else {
+    root.setAttribute("data-theme", setting);
+  }
+  try { localStorage.setItem("fs_theme", setting); } catch { /* ignore */ }
+}
+
+function loadTheme(): ThemeSetting {
+  try {
+    const saved = localStorage.getItem("fs_theme");
+    if (saved === "light" || saved === "dark" || saved === "system") return saved;
+  } catch { /* ignore */ }
+  return "system";
+}
+
+// 초기 테마 적용 (React 렌더 전에 FOUC 방지)
+applyTheme(loadTheme());
+
 // ─── Session Storage Keys ─────────────────────────────────────
 const SS = {
   auth:            "fs_auth",
@@ -57,6 +82,13 @@ const SS = {
 
 // ─── App Root ─────────────────────────────────────────────────
 function App({ installMode }: { installMode: InstallMode }) {
+  const [theme, setTheme] = useState<ThemeSetting>(loadTheme);
+
+  const handleThemeChange = (next: ThemeSetting) => {
+    setTheme(next);
+    applyTheme(next);
+  };
+
   const [isAuthenticated, setIsAuthenticated] = useState(
     () => sessionStorage.getItem(SS.auth) === "true",
   );
@@ -272,6 +304,8 @@ function App({ installMode }: { installMode: InstallMode }) {
         {isSettingsOpen && (
           <SettingsView
             isAdmin={isAdmin}
+            theme={theme}
+            onThemeChange={handleThemeChange}
             onClose={() => setIsSettingsOpen(false)}
             onToggleAdmin={() => {
               setIsAdmin((prev) => {

apps/web/src/styles/global.css

@@ -1,43 +1,122 @@
-/* ─── Design Tokens ──────────────────────────────────────────── */
+/* ─── Design Tokens: Light Mode (default) ────────────────────── */
 :root {
-  color-scheme: dark;
+  color-scheme: light dark;
 
   /* Backgrounds */
+  --bg:            #f4f4f9;
+  --bg-surface:    #ffffff;
+  --bg-elevated:   #ededf6;
+  --bg-hover:      #e4e4f0;
+
+  /* Borders */
+  --border:        #d0d0e4;
+  --border-subtle: #e4e4f2;
+
+  /* Text */
+  --text:          #0e0e18;
+  --text-muted:    #525278;
+  --text-faint:    #9898b8;
+
+  /* Accent (indigo — darker for light bg) */
+  --accent:        #5252e0;
+  --accent-hover:  #3e3ece;
+  --accent-subtle: rgba(82, 82, 224, 0.08);
+  --accent-border: rgba(82, 82, 224, 0.20);
+
+  /* Status */
+  --ok:         #16a34a;
+  --warn:       #b45309;
+  --err:        #b91c1c;
+  --info:       #1d4ed8;
+  --ok-subtle:  rgba(22, 163, 74,  0.10);
+  --warn-subtle:rgba(180, 83,  9,  0.10);
+  --err-subtle: rgba(185, 28, 28,  0.10);
+  --info-subtle:rgba(29,  78, 216, 0.10);
+
+  /* Aliases */
+  --primary:        var(--accent);
+  --primary-strong: var(--accent-hover);
+  --focus-ring:     rgba(82, 82, 224, 0.20);
+  --surface:        var(--bg-elevated);
+  --muted:          var(--text-muted);
+
+  /* Layout */
+  --sidebar-width: 220px;
+  --content-max:   900px;
+}
+
+/* ─── Design Tokens: Dark Mode ───────────────────────────────── */
+/* OS preference (no explicit theme set) */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    color-scheme: dark;
+
+    --bg:            #0e0e14;
+    --bg-surface:    #13131b;
+    --bg-elevated:   #1a1a25;
+    --bg-hover:      #20202e;
+
+    --border:        #2a2a3c;
+    --border-subtle: #1d1d2a;
+
+    --text:          #e0e0ec;
+    --text-muted:    #7878a0;
+    --text-faint:    #44445c;
+
+    --accent:        #7c7cf0;
+    --accent-hover:  #9191f5;
+    --accent-subtle: rgba(124, 124, 240, 0.12);
+    --accent-border: rgba(124, 124, 240, 0.20);
+
+    --ok:         #4ade80;
+    --warn:       #fbbf24;
+    --err:        #f87171;
+    --info:       #60a5fa;
+    --ok-subtle:  rgba(74,  222, 128, 0.12);
+    --warn-subtle:rgba(251, 191,  36, 0.12);
+    --err-subtle: rgba(248, 113, 113, 0.12);
+    --info-subtle:rgba(96,  165, 250, 0.12);
+
+    --focus-ring: rgba(124, 124, 240, 0.28);
+  }
+}
+
+/* Explicit dark theme */
+[data-theme="dark"] {
+  color-scheme: dark;
+
   --bg:            #0e0e14;
   --bg-surface:    #13131b;
   --bg-elevated:   #1a1a25;
   --bg-hover:      #20202e;
 
-  /* Borders */
   --border:        #2a2a3c;
   --border-subtle: #1d1d2a;
 
-  /* Text */
   --text:          #e0e0ec;
   --text-muted:    #7878a0;
   --text-faint:    #44445c;
 
-  /* Accent (indigo) */
   --accent:        #7c7cf0;
   --accent-hover:  #9191f5;
   --accent-subtle: rgba(124, 124, 240, 0.12);
+  --accent-border: rgba(124, 124, 240, 0.20);
+
+  --ok:         #4ade80;
+  --warn:       #fbbf24;
+  --err:        #f87171;
+  --info:       #60a5fa;
+  --ok-subtle:  rgba(74,  222, 128, 0.12);
+  --warn-subtle:rgba(251, 191,  36, 0.12);
+  --err-subtle: rgba(248, 113, 113, 0.12);
+  --info-subtle:rgba(96,  165, 250, 0.12);
+
+  --focus-ring: rgba(124, 124, 240, 0.28);
+}
 
-  /* Status */
-  --ok:   #4ade80;
-  --warn: #fbbf24;
-  --err:  #f87171;
-  --info: #60a5fa;
-
-  /* Aliases for backwards compat */
-  --primary:      var(--accent);
-  --primary-strong: var(--accent-hover);
-  --focus-ring:   rgba(124, 124, 240, 0.28);
-  --surface:      var(--bg-elevated);
-  --muted:        var(--text-muted);
-
-  /* Layout */
-  --sidebar-width: 220px;
-  --content-max:   900px;
+/* Explicit light theme */
+[data-theme="light"] {
+  color-scheme: light;
 }
 
 /* ─── Reset ──────────────────────────────────────────────────── */
@@ -94,15 +173,15 @@ body {
 }
 
 .badge-danger {
-  background: rgba(248, 113, 113, 0.14);
-  color: #f87171;
-  border: 1px solid rgba(248, 113, 113, 0.2);
+  background: var(--err-subtle);
+  color: var(--err);
+  border: 1px solid color-mix(in srgb, var(--err) 20%, transparent);
 }
 
 .badge-soft {
   background: var(--accent-subtle);
   color: var(--accent-hover);
-  border: 1px solid rgba(124, 124, 240, 0.2);
+  border: 1px solid var(--accent-border);
 }
 
 .chip {
@@ -114,10 +193,10 @@ body {
   font-weight: 700;
 }
 
-.chip-ready   { background: rgba(74, 222, 128, 0.12); color: #4ade80; }
-.chip-loading { background: rgba(96, 165, 250, 0.12); color: #60a5fa; }
-.chip-empty   { background: rgba(251, 191, 36, 0.12); color: #fbbf24; }
-.chip-error   { background: rgba(248, 113, 113, 0.12); color: #f87171; }
+.chip-ready   { background: var(--ok-subtle);   color: var(--ok);   }
+.chip-loading { background: var(--info-subtle);  color: var(--info); }
+.chip-empty   { background: var(--warn-subtle);  color: var(--warn); }
+.chip-error   { background: var(--err-subtle);   color: var(--err);  }
 
 /* ─── Form Controls ──────────────────────────────────────────── */
 .field {
@@ -157,6 +236,7 @@ body {
 
 .select option {
   background: var(--bg-elevated);
+  color: var(--text);
 }
 
 /* ─── Buttons ────────────────────────────────────────────────── */
@@ -176,7 +256,6 @@ body {
 .button:hover {
   background: var(--bg-hover);
   color: var(--text);
-  border-color: var(--border);
 }
 
 .button-primary {
@@ -191,13 +270,13 @@ body {
 }
 
 .button-danger {
-  background: rgba(248, 113, 113, 0.1);
+  background: var(--err-subtle);
   color: var(--err);
-  border-color: rgba(248, 113, 113, 0.2);
+  border-color: color-mix(in srgb, var(--err) 20%, transparent);
 }
 
 .button-danger:hover {
-  background: rgba(248, 113, 113, 0.18);
+  background: color-mix(in srgb, var(--err) 18%, transparent);
 }
 
 .button-block {
@@ -242,10 +321,10 @@ body {
   color: var(--text-muted);
 }
 
-.status-ready   { border-color: rgba(74, 222, 128, 0.25); }
-.status-loading { border-color: rgba(96, 165, 250, 0.25); }
-.status-empty   { border-color: rgba(251, 191, 36, 0.25); }
-.status-error   { border-color: rgba(248, 113, 113, 0.25); }
+.status-ready   { border-color: color-mix(in srgb, var(--ok)   25%, transparent); }
+.status-loading { border-color: color-mix(in srgb, var(--info)  25%, transparent); }
+.status-empty   { border-color: color-mix(in srgb, var(--warn)  25%, transparent); }
+.status-error   { border-color: color-mix(in srgb, var(--err)   25%, transparent); }
 
 /* ─── Panel ──────────────────────────────────────────────────── */
 .panel {

apps/web/src/views/SettingsView.tsx

@@ -2,17 +2,20 @@ import { useEffect, useRef, useState } from "react";
 
 import "../styles/settings.css";
 
+type ThemeSetting = "light" | "dark" | "system";
+
 interface SettingsViewProps {
   isAdmin: boolean;
+  theme: ThemeSetting;
+  onThemeChange: (theme: ThemeSetting) => void;
   onToggleAdmin: () => void;
   onClose: () => void;
   onSaved: () => void;
 }
 
-export function SettingsView({ isAdmin, onToggleAdmin, onClose, onSaved }: SettingsViewProps) {
+export function SettingsView({ isAdmin, theme, onThemeChange, onToggleAdmin, onClose, onSaved }: SettingsViewProps) {
   const [displayName, setDisplayName] = useState("");
   const [language, setLanguage] = useState("ko");
-  const [theme, setTheme] = useState("light");
   const dialogRef = useRef<HTMLDivElement>(null);
 
   const handleOverlayClick = (e: React.MouseEvent<HTMLDivElement>) => {
@@ -114,7 +117,7 @@ export function SettingsView({ isAdmin, onToggleAdmin, onClose, onSaved }: Setti
               <select
                 className="select"
                 value={theme}
-                onChange={(e) => setTheme(e.target.value)}
+                onChange={(e) => onThemeChange(e.target.value as ThemeSetting)}
               >
                 <option value="light">라이트</option>
                 <option value="dark">다크</option>

docs/v2_FINANCIAL-LEDGER/roadmap/01-development-plan.md

@@ -144,9 +144,11 @@ Control 전체 목록과 상태 관리는 별도 문서에서 관리:
 - [x] Control 우선순위 분류 (P0: Core 필수 / P0.5: 반복 사용 / P1/P2: 요청 기반)
 - [x] 신규 Control 추가 정책 확정 (요청 -> RFC/이슈 -> 디자인/접근성 검토 -> 릴리스)
 
-**packages/ui 실제 구현 (미착수):**
-- [ ] P0 Control 구현 — Button / Input / Select / Checkbox / Radio / Switch / Modal / Form Field / Alert / Progress
-- [ ] P0.5 Control 구현 — Textarea / Password Input / OTP Input / Search Input / Spinner / Toast / Empty State / Skeleton
+**packages/controls 실제 구현:**
+- [x] P0 Control 구현 — Button / Input / Select / Checkbox / Radio / Switch / Modal / Form Field / Alert / Progress
+- [x] P0.5 Control 구현 — Textarea / Password Input / OTP Input / Search Input / Spinner / Toast / EmptyState / Skeleton
+- [x] `global.css` 토큰 라이트/다크 분리 (`[data-theme]` + `prefers-color-scheme`)
+- [x] `controls.css` 작성 (fs- 접두사, CSS 변수 기반, 라이트/다크 공통)
 - [ ] Control 접근성 기준 체크 (focus ring, 명도 대비, aria role/label, tab 순서)
 - [ ] `apps/web` View에서 `@fieldstack/controls` Control로 교체 검증
 
@@ -225,7 +227,7 @@ Control 전체 목록과 상태 관리는 별도 문서에서 관리:
 - ✅ Phase 2 모듈 UI를 붙일 수 있는 라우팅/레이아웃 기반 확보
 
 ### Phase 2 진입 게이트 (권장)
-- [ ] Control 패키지 MVP 완료 (P0/P0.5 규격 확정됨 — `packages/ui` 실제 구현 및 `ready: true` 반영 필요)
+- [x] Control 패키지 MVP 완료 (P0/P0.5 구현 완료 — `packages/controls` 반영 + `ready: true`)
 - [ ] Auth/Install/Home/Settings/Admin 흐름에서 공통 Control 재사용 검증
 - [ ] 접근성/반응형/상태 처리(Loading/Empty/Error/Unauthorized) 기준 통과
 - [ ] 핵심 E2E 통과 (설치 -> 로그인 -> 홈 -> 설정/관리자)
@@ -240,6 +242,7 @@ Control 전체 목록과 상태 관리는 별도 문서에서 관리:
 | 2026-02-27 | Web 진입점을 React + TypeScript + Vite(`main.tsx`) 기준으로 전환 완료. 개발 실행 모드에 `dev:bypass` 추가. bypass 정책을 "설치만 스킵, 인증은 로그인부터"로 확정 |
 | 2026-04-12 | 1차 UI/UX 전면 개편. 다크 모드 디자인 토큰 시스템 구축 및 고정 220px 좌측 사이드바 레이아웃으로 재설계. AppShell A/B/C/D 변형 폐기 후 단일 Shell로 통합. 로그인/홈/설정/관리자 CSS 전체를 다크 토큰 기반으로 전환 |
 | 2026-04-12 | 임시 비밀번호 첫 로그인 강제 변경 화면(ChangePasswordView) 구현. 관리자 역할(isAdmin)과 PIN 인증(isPinVerified) 상태 분리 — 역할 보유자도 Admin 페이지 진입 시 PIN 재인증 필요. 비관리자 Admin 진입점 사이드바에서 숨김. Marketplace 사이드바 진입점 추가(Phase 3 플레이스홀더). @fieldstack/core ESM 빌드 전환 |
+| 2026-04-13 | P0/P0.5 Control 전 항목 `packages/controls`에 React 컴포넌트 구현 완료 (`ready: true`). `controls.css` 작성(fs- 접두사). `global.css` 토큰을 라이트 기본값 + 다크 오버라이드(`[data-theme]`/`prefers-color-scheme`) 구조로 재설계. Settings 테마 셀렉터 실제 동작 연결 (localStorage + data-theme 적용). |
 
 ---
 

packages/controls/package.json

@@ -2,17 +2,27 @@
   "name": "@fieldstack/controls",
   "private": true,
   "version": "0.0.0",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles": "./src/styles/controls.css"
+  },
   "scripts": {
     "build": "tsc",
     "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": {
-    "@fieldstack/core": "workspace:*"
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "devDependencies": {
+    "@types/react": "^19.2.14",
     "vitest": "^2.1.9"
   }
 }