refactor(ui): packages/ui → packages/controls 이름 변경 및 Control 구현 현황 문서화

- packages/ui 디렉토리를 packages/controls로 이동, 패키지명 @fieldstack/ui → @fieldstack/controls 변경
- Control 백로그 상태 기준에 '규격 확정' 단계 추가, P0/P0.5 전 항목을 '완료' → '규격 확정'으로 정정
- 로드맵 1.5.1 섹션에 실제 구현 미착수 상태 명시 및 체크리스트를 규격/구현 두 블록으로 분리
- 1.5.2 설치 마법사에 별도 Setup 시스템 분리 예정 및 DSM/Windows 스타일 참고 계획 주석 추가
- Phase 2 진입 게이트 Control 항목 체크 해제 (계약만 완료, packages/controls 구현 필요)

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

Author: SOIV

AGENTS.md

@@ -107,7 +107,7 @@ node dist/index.js
 
 Order (planned ESLint rule):
 1. External libraries (`react`, `express`)
-2. Internal packages (`@fieldstack/core`, `@fieldstack/ui`)
+2. Internal packages (`@fieldstack/core`, `@fieldstack/controls`)
 3. Relative imports (`./`, `../`)
 
 Use `import type` for types.
@@ -141,7 +141,7 @@ Use `import type` for types.
 ## UI/UX Guidelines (Planned)
 
 - UI is fully separated from core/module business logic.
-- Prefer `@fieldstack/ui` components for consistency.
+- Prefer `@fieldstack/controls` components for consistency.
 - Tailwind CSS is the planned styling approach.
 - Users can override UI with `apps/web/src/custom-ui/`.
 

README.md

@@ -33,26 +33,26 @@ Current phase: **Development in progress (Roadmap Phase 1.5)**
 - 🚧 Roadmap Phase 1.5 (Core Control Plane UI/UX) is in progress
 - 🎯 Target timeline remains **2026-2027**
 
-### Phase Progress
-
-| Phase | Scope (Roadmap) | Status | Progress |
-| ------- | ----------- | ------- | ------- |
-| Phase 1 | Core foundation setup | Completed ✅ | 100% |
-| Phase 1.5 | Core Control Plane UI/UX | In progress ⏳ | 40% |
-| Phase 2 | Core module development (Ledger, Subscription) | Not started 🚧 | 0% |
-| Phase 3 | Marketplace and website | Not started 🚧 | 0% |
-| Phase 4 | Deployment optimization | Not started 🚧 | 0% |
-| Phase 5 | Expansion and ecosystem | Not started 🚧 | 0% |
-| Phase 6 | Community growth (continuous) | Not started 🚧 | 0% |
-
-#### Phase 1.5 Snapshot (2026-02-26)
-
-- Control contracts (P0/P0.5): **100%**
-- `@fieldstack/ui` scaffold: **100%**
-- Render components (TSX + styles + a11y behaviors): **0%**
-- End-to-end flow verification: **0%**
-
-> Note: This phase table follows `docs/v2_FINANCIAL-LEDGER/roadmap/01-development-plan.md` and is updated as implementation progresses.
+### Phase Progress
+
+| Phase | Scope (Roadmap) | Status | Progress |
+| ------- | ----------- | ------- | ------- |
+| Phase 1 | Core foundation setup | Completed ✅ | 100% |
+| Phase 1.5 | Core Control Plane UI/UX | In progress ⏳ | 40% |
+| Phase 2 | Core module development (Ledger, Subscription) | Not started 🚧 | 0% |
+| Phase 3 | Marketplace and website | Not started 🚧 | 0% |
+| Phase 4 | Deployment optimization | Not started 🚧 | 0% |
+| Phase 5 | Expansion and ecosystem | Not started 🚧 | 0% |
+| Phase 6 | Community growth (continuous) | Not started 🚧 | 0% |
+
+#### Phase 1.5 Snapshot (2026-02-26)
+
+- Control contracts (P0/P0.5): **100%**
+- `@fieldstack/controls` scaffold: **100%**
+- Render components (TSX + styles + a11y behaviors): **0%**
+- End-to-end flow verification: **0%**
+
+> Note: This phase table follows `docs/v2_FINANCIAL-LEDGER/roadmap/01-development-plan.md` and is updated as implementation progresses.
 
 ---
 

README_ko.md

@@ -48,7 +48,7 @@ Fieldstack은 개인 생산성과 재무 관리를 위한 오픈소스 기반의
 #### Phase 1.5 스냅샷 (2026-02-26)
 
 - Control 계약(P0/P0.5): **100%**
-- `@fieldstack/ui` 패키지 기초 스캐폴딩: **100%**
+- `@fieldstack/controls` 패키지 기초 스캐폴딩: **100%**
 - 실제 렌더 컴포넌트 구현(TSX + 스타일 + 접근성 동작): **0%**
 - 설치 -> 로그인 -> 홈 -> 설정/관리자 흐름 통합 검증(E2E): **0%**
 

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

@@ -127,21 +127,35 @@ Fieldstack/
 > 원칙: "모든 Control 선제 구현"이 아니라, Core 흐름에 필요한 Control MVP를 먼저 고정하고,
 > 추가 Control은 Phase 2 모듈 개발/커뮤니티 요청 기반으로 점진 확장한다.
 
+> **현재 상태:** P0/P0.5 Control은 규격·계약 정의만 완료된 상태이며, `packages/controls` 실제 구현은 미착수입니다.
+> `apps/web` 각 View에 인라인으로 작성된 UI가 현재 동작 레퍼런스이고,
+> 2026-04-12 확정된 다크 모드 디자인 토큰 시스템을 기반으로 `packages/controls` 구현을 진행하면 됩니다.
+> 상세 구현 상태는 `docs/v2_FINANCIAL-LEDGER/ui/03-control-backlog.md` 기준으로 추적합니다.
+
 Control 전체 목록과 상태 관리는 별도 문서에서 관리:
 - `docs/v2_FINANCIAL-LEDGER/ui/03-control-backlog.md` (P0 -> P0.5 -> P1)
 
+**규격 확정 (완료):**
 - [x] Button 규격 확정 (Primary/Secondary/Danger/Ghost, size, loading, disabled)
 - [x] Toggle/Switch 규격 확정 (on/off 상태, 라벨 결합, 키보드 조작)
 - [x] ComboBox/Select 규격 확정 (단일/다중 선택, 검색, 빈 상태)
 - [x] Checkbox/Radio 규격 확정 (단일/그룹 선택, indeterminate 포함)
 - [x] Input 계열 공통 규칙 확정 (text/email/password/number/search/tel/url, validation/error/help text)
-- [ ] Control 접근성 기준 체크 (focus ring, 명도 대비, aria role/label, tab 순서)
 - [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
+- [ ] Control 접근성 기준 체크 (focus ring, 명도 대비, aria role/label, tab 순서)
+- [ ] `apps/web` View에서 `@fieldstack/controls` Control로 교체 검증
+
 #### 1.5.2 설치 마법사 (초기 설정)
 **예상 기간: 4일**
 
+> **향후 계획:** 현재 구현은 Phase 1.5 범위 내 기본 흐름 검증 목적이며, 완성 이후 별도 Setup 설치 시스템으로 분리 개발 예정.
+> UX 방향은 Synology DSM 초기 설정 또는 Windows 설치 마법사 스타일을 참고할 예정.
+
 - [x] 개발용 bypass 실행 모드 제공 (`dev:bypass`, `dev:web:bypass`, `dev:api:bypass`)
 - [ ] Welcome 화면
 - [ ] Configuration 화면 (관리자 계정, DB, 선택 옵션)
@@ -211,7 +225,7 @@ Control 전체 목록과 상태 관리는 별도 문서에서 관리:
 - ✅ Phase 2 모듈 UI를 붙일 수 있는 라우팅/레이아웃 기반 확보
 
 ### Phase 2 진입 게이트 (권장)
-- [x] Control 패키지 MVP 완료 (Button/Input/Select/Toggle/Checkbox/Radio/Modal/Form + P0.5 계약)
+- [ ] Control 패키지 MVP 완료 (P0/P0.5 규격 확정됨 — `packages/ui` 실제 구현 및 `ready: true` 반영 필요)
 - [ ] Auth/Install/Home/Settings/Admin 흐름에서 공통 Control 재사용 검증
 - [ ] 접근성/반응형/상태 처리(Loading/Empty/Error/Unauthorized) 기준 통과
 - [ ] 핵심 E2E 통과 (설치 -> 로그인 -> 홈 -> 설정/관리자)

docs/v2_FINANCIAL-LEDGER/technical/00-tech-stack.md

@@ -100,10 +100,10 @@
 **채택 방향 (2026-02): Radix + shadcn 패턴 + 내부 래퍼**
 - **Radix UI Primitives** - 접근성/키보드 동작/상태 머신 기반 Primitive
 - **shadcn/ui 패턴** - Tailwind 기반 스타일/조합 패턴 참고
-- **@fieldstack/ui (내부 패키지)** - 앱/모듈에서 사용하는 단일 진입점
+- **@fieldstack/controls (내부 패키지)** - 앱/모듈에서 사용하는 단일 진입점
 
 **적용 원칙:**
-- 외부 라이브러리를 앱/모듈에서 직접 import하지 않고 `@fieldstack/ui`를 통해 사용
+- 외부 라이브러리를 앱/모듈에서 직접 import하지 않고 `@fieldstack/controls`를 통해 사용
 - Phase 1.5에서는 P0/P0.5 중심으로 Control MVP를 우선 구현
 - P1/P2는 모듈 요구사항/커뮤니티 요청 기반으로 점진 확장
 

docs/v2_FINANCIAL-LEDGER/ui/01-core-components.md

@@ -4,21 +4,21 @@
 
 모듈 개발자가 UI/UX를 처음부터 만들 필요 없이, Core에서 제공하는 컴포넌트를 사용하여 빠르고 일관된 인터페이스를 구축할 수 있도록 지원합니다.
 
-## 장점
+## 장점
 
 - ✅ 통일된 디자인 시스템
 - ✅ 즉시 사용 가능한 컴포넌트
-- ✅ 반응형 자동 처리
-- ✅ 다크모드 자동 지원
-- ✅ 접근성 자동 처리
-
-## 구현 방향 (Phase 1.5 기준)
-
-- Control 구현은 `Radix UI Primitives` 기반으로 진행
-- 스타일/조합 패턴은 `shadcn/ui` 방식을 참고
-- 실제 앱/모듈에서는 외부 라이브러리를 직접 사용하지 않고 `@fieldstack/ui`를 통해서만 사용
-- 우선순위는 `P0 -> P0.5 -> P1 -> P2` 순서로 적용
-- 상세 목록/상태는 `ui/03-control-backlog.md`에서 관리
+- ✅ 반응형 자동 처리
+- ✅ 다크모드 자동 지원
+- ✅ 접근성 자동 처리
+
+## 구현 방향 (Phase 1.5 기준)
+
+- Control 구현은 `Radix UI Primitives` 기반으로 진행
+- 스타일/조합 패턴은 `shadcn/ui` 방식을 참고
+- 실제 앱/모듈에서는 외부 라이브러리를 직접 사용하지 않고 `@fieldstack/controls`를 통해서만 사용
+- 우선순위는 `P0 -> P0.5 -> P1 -> P2` 순서로 적용
+- 상세 목록/상태는 `ui/03-control-backlog.md`에서 관리
 
 ## Core UI 구성
 
@@ -174,4 +174,4 @@ FormBuilder 컴포넌트를 가져와서 사용합니다. 폼의 구조를 정
 
 테마 파일에서 전체 앱의 시각 기준값을 관리합니다. 색상으로는 주색상(파란색 #3B82F6), 부차색상(회색 #6B7280), 위험색(빨간색 #EF4444), 성공색(초록색 #10B981)이 정의되어 있습니다. 폰트로는 일반 텍스트용 Inter와 코드용 JetBrains Mono를 사용합니다. 간격은 작음(0.5rem), 보통(1rem), 큼(1.5rem) 세 단계로 정의되어 있습니다.
 
-사용자는 자유롭게 테마를 커스터마이징할 수 있습니다.
+사용자는 자유롭게 테마를 커스터마이징할 수 있습니다.

docs/v2_FINANCIAL-LEDGER/ui/03-control-backlog.md

@@ -15,36 +15,45 @@ Phase 2 이후 모듈/커뮤니티 요청에 따라 점진 확장하기 위한 
 ## 상태 기준
 
 - `미착수` - 구현 시작 전
+- `규격 확정` - 인터페이스/계약 정의 완료, `packages/ui` 실제 구현 미착수
 - `진행중` - 작업 중
-- `완료` - Control 패키지 반영 완료
+- `완료` - `packages/ui`에 실제 컴포넌트 반영 + `ready: true` 확인 완료
+
+> **현재 상태 (2026-04-12 기준):**
+> P0/P0.5 전 항목은 `규격 확정` 상태입니다. `packages/controls/src/components/index.ts`에 계약 타입만 선언되어 있으며
+> 실제 React 컴포넌트는 미구현입니다 (`ready: false`).
+>
+> `apps/web` 각 View에서 인라인으로 사용 중인 스타일/구조가 사실상의 레퍼런스이며,
+> 2026-04-12 UI/UX 전면 개편으로 확정된 **다크 모드 디자인 토큰 시스템**을 기반으로
+> `packages/controls` 구현을 진행하면 됩니다.
 
 ## P0 (Core 필수)
 
 | Control | 우선순위 | 1.5 구현상태 | 비고 |
 | --- | --- | --- | --- |
-| Button | P0 | 완료 | Primary/Secondary/Danger/Ghost |
-| Input | P0 | 완료 | text/email/number/password |
-| Select / ComboBox | P0 | 완료 | single/multi + search |
-| Checkbox | P0 | 완료 | 단일/그룹 + indeterminate |
-| Radio | P0 | 완료 | 단일 선택 그룹 |
-| Switch / Toggle | P0 | 완료 | on/off + keyboard |
-| Modal / Dialog | P0 | 완료 | confirm/alert/prompt 패턴 |
-| Form Field Wrapper | P0 | 완료 | label/help/error/required |
-| Alert / Inline Message | P0 | 완료 | success/warning/error/info |
-| Progress | P0 | 완료 | linear + step progress |
+| Button | P0 | 규격 확정 | Primary/Secondary/Danger/Ghost |
+| Input | P0 | 규격 확정 | text/email/number/password |
+| Select / ComboBox | P0 | 규격 확정 | single/multi + search |
+| Checkbox | P0 | 규격 확정 | 단일/그룹 + indeterminate |
+| Radio | P0 | 규격 확정 | 단일 선택 그룹 |
+| Switch / Toggle | P0 | 규격 확정 | on/off + keyboard |
+| Modal / Dialog | P0 | 규격 확정 | confirm/alert/prompt 패턴 |
+| Form Field Wrapper | P0 | 규격 확정 | label/help/error/required |
+| Alert / Inline Message | P0 | 규격 확정 | success/warning/error/info |
+| Progress | P0 | 규격 확정 | linear + step progress |
 
 ## P0.5 (핵심 흐름 반복 사용)
 
 | Control | 우선순위 | 1.5 구현상태 | 비고 |
 | --- | --- | --- | --- |
-| Textarea | P0.5 | 완료 | multi-line input |
-| Password Input | P0.5 | 완료 | show/hide + strength hint |
-| OTP / PIN Input | P0.5 | 완료 | 4~6자리 step-up 인증 |
-| Search Input | P0.5 | 완료 | debounce/clear |
-| Spinner / Loader | P0.5 | 완료 | blocking/non-blocking 로딩 |
-| Toast / Notification | P0.5 | 완료 | 전역 피드백 메시지 |
-| Empty State Block | P0.5 | 완료 | CTA 포함 빈 상태 |
-| Skeleton Loader | P0.5 | 완료 | list/card/form skeleton |
+| Textarea | P0.5 | 규격 확정 | multi-line input |
+| Password Input | P0.5 | 규격 확정 | show/hide + strength hint |
+| OTP / PIN Input | P0.5 | 규격 확정 | 4~6자리 step-up 인증 |
+| Search Input | P0.5 | 규격 확정 | debounce/clear |
+| Spinner / Loader | P0.5 | 규격 확정 | blocking/non-blocking 로딩 |
+| Toast / Notification | P0.5 | 규격 확정 | 전역 피드백 메시지 |
+| Empty State Block | P0.5 | 규격 확정 | CTA 포함 빈 상태 |
+| Skeleton Loader | P0.5 | 규격 확정 | list/card/form skeleton |
 
 ## P1 (자주 쓰이지만 일부 우선 구현)
 

packages/ui/package.json packages/controls/package.jsonpackages/ui/package.json renamed to packages/controls/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@fieldstack/ui",
+  "name": "@fieldstack/controls",
   "private": true,
   "version": "0.0.0",
   "main": "dist/index.js",

packages/ui/src/components/index.ts packages/controls/src/components/index.tspackages/ui/src/components/index.ts renamed to packages/controls/src/components/index.ts

@@ -4,7 +4,7 @@ export interface UiProviderConfig {
 }
 
 export interface UiPackageMetadata {
-  name: "@fieldstack/ui";
+  name: "@fieldstack/controls";
   version: string;
 }
 
@@ -14,6 +14,6 @@ export const UI_PROVIDER_CONFIG_DEFAULTS: UiProviderConfig = {
 };
 
 export const UI_PACKAGE_METADATA: UiPackageMetadata = {
-  name: "@fieldstack/ui",
+  name: "@fieldstack/controls",
   version: "0.0.0"
 };