TSK-025-00 Epic: App-wide UI Kit Foundation and Screen Rhythm Modernization

[ClarusIubar]

TSK-025-00 Epic: App-wide UI Kit Foundation and Screen Rhythm Modernization

한국어 우선 요약

TSK-025는 앱 전체 UI kit 기반 화면 리듬 현대화 parent입니다. 디자인 핸드오프 문서는 복붙 대상이 아니라 surface/card/button/chip/form/list rhythm과 semantic token 원칙을 고정하는 기준이며, child issue 단위로 화면별 migration과 quality gate를 진행합니다.

One-Sentence Summary

Create an app-wide UI kit and migrate screen rhythm so surfaces, cards, buttons, chips, forms, metrics, sheets, and lists stop being rebuilt independently per screen.

Why This Work Exists

Partial UI patches are no longer enough. The app currently has screen-specific visual systems for drawers, My Page, Feed, Event, Course, and map sheets. The repeated failure mode is not one broken drawer; it is the absence of a shared primitive layer and source-quality gates. Without those, each new feature can reintroduce nested cards, raw colors, ad hoc spacing, and incompatible button/card rhythm.

Source Material

• Design handoff package: C:/Users/PC/OneDrive/.../design_handoff_jamissue
• README.md: live app first, prototype copy/paste forbidden, P0 wrapping/overflow issues, P1 theme/drawer/app shell, P2 activity/comment/tourism sheets.
• drawer-spec.md: AppCapsule + left/right drawers sharing one shell, simultaneous drawer prevention, AppChrome composition.
• comment-tourism-spec.md: TourismInfoSheet and FeedCommentSheet use common sheet rhythm; KTO remains informational only.
• season-theme-spec.md: semantic CSS variables drive seasonal tone; component code must not hardcode theme values.

Design Handoff Decisions To Preserve

• Use the handoff package as a design-system reference, not as copy/paste implementation code.
• Live app behavior remains the product source of truth when prototype examples conflict with existing production behavior.
• UI modernization is a layout/composition/token migration, not a user-facing copy rewrite.
• Feature screens must own domain data and actions only; app-wide UI kit primitives own surface, card, button, chip, form, list, metric, and empty-state rhythm.
• Component code must consume semantic tokens. Raw prototype colors, inline styles, and ad hoc shadows/radii/spacing are not implementation rules.
• Do not add production theme switchers or developer-only controls to user UI.
• Do not add a new icon library in this roadmap. Keep the current local SVG/icon policy unless a later child explicitly changes it.

Global Composition Rules

• SectionHeader owns labels, headings, descriptions, and optional actions. It does not create a card by itself.
• ContentCard is for real content items, summaries, forms, or repeated list units. It must not be nested inside another ContentCard.
• AppSurface owns page/panel/sheet surface rhythm, not domain behavior.
• ActionButton, FilterChip, FormField, MetricTile, ListItem, EmptyState, MediaFrame, and InlineMeta own reusable visual rhythm only.
• Feature components may compose primitives and pass domain data/actions, but must not define their own raw color/shadow/radius system.
• Existing behavior and routes remain stable unless a child issue explicitly says otherwise.

Issue Structure And Order

• TSK-025-01 visual-system-audit-baseline: prove the current problem before abstraction.
• TSK-025-02 app-ui-kit-foundation: add primitives and composition gates before migration.
• TSK-025-03 my-page-settings-drawer-migration: migrate the most nested/problematic surfaces first. PR #701, merge 5335e53967715db1f69e0f2e6cb6298f10bab57b.
• TSK-025-04 feed-modern-rhythm-migration: modernize feed rhythm while preserving social actions. PR #702, merge 2c6263a0533aee2cb341237b582e6c699c6b0c10.
• TSK-025-05 event-course-list-migration: bring list-heavy Event/Course screens onto common rhythm. PR #703, merge 50c19d402a3344e917347fb642a72f77a793bc5b.
• TSK-025-06 map-sheet-tourism-migration: align bottom sheets and KTO informational content. PR #704, merge 2221422254875bc7ace0dc3c7a91c3c9b667b7ab.
• TSK-025-07 visual-system-quality-gate: prevent backsliding into feature-owned visual systems. PR #705, merge 88a1fa8aaf6cd11d4b22f2bb4108fe77d2aa5579.
• TSK-025-08 docs-traceability: document the final contract and evidence. PR #706, merge d57b12dd507e24ef4b0751948ea4c946057aed6a.

Non-Goals

• No API path, response shape, DB schema, OAuth, KTO, or Naver map contract changes.
• No user-facing copy rewrite. Broken encoding or functional aria/label repair is allowed.
• No one-shot all-screen redesign PR.
• No prototype HTML/JSX copy/paste.
• No new icon package.

Architecture Boundary Gate

Durability: durable
Architecture profile: components, CSS tokens, source-quality tests, E2E scenarios
Responsibility map: UI kit owns visual rhythm primitives; feature screens own domain data/actions only; semantic tokens own color/spacing/radius/elevation values; tests own composition and hardcoding gates.
Dependency direction: feature screens -> UI kit -> semantic tokens. UI kit must not import feature screens, API clients, auth stores, map SDK, or KTO clients.
External dependency boundary: none for UI kit. Existing API/OAuth/KTO/Naver map boundaries remain untouched.
Validation seam: primitive unit tests, source-quality checks, and per-screen E2E geometry/interaction tests.
Scope map: child issues TSK-025-01 through TSK-025-08 own audit, foundation, migrations, gate, and docs.
Architecture risk: over-abstraction and behavior drift; mitigate by small primitive interfaces, screen-by-screen migration, and behavior preservation assertions.
Single-file exception: none.

• TSK-025-09 release-v1.4.0-rc.1 and Wiki update: published RC prerelease and updated GitHub Wiki evidence. Release release-v1.4.0-rc.1, Wiki commit 5cea857.

Parent Completion Conditions

This parent stays open until all child issues are complete and each child has PR, validation, UI evidence where applicable, merge SHA, and completion comment.

Roadmap Decision Record Addendum

Out of Scope

• No one-shot app-wide redesign PR.
• No API path, response shape, DB schema, OAuth, KTO, or Naver map contract change.
• No user-facing copy rewrite except broken encoding or objectively incorrect aria/label repair in touched scope.
• No prototype HTML/JSX copy-paste; handoff documents define rhythm and composition, not source code.

Interface Strategy

• TSK-025-02 owns the stable UI kit primitive interfaces.
• TSK-025-03 through TSK-025-06 consume those primitives without changing feature API/data contracts.
• TSK-025-07 owns source-quality enforcement for token, composition, and hardcoding boundaries.
• TSK-025-08 owns documentation and completion evidence only.

Data Flow / Migration Flow

• Existing feature data flows stay in their current screens/adapters.
• Migration children map existing prepared view data into UI kit props.
• UI kit primitives do not fetch data, mutate global state, import domain clients, or own feature behavior.
• Visual values flow from season/theme semantic tokens into UI kit CSS, then into feature composition.