h-lab/docs/superpowers/specs/2026-05-31-all-pages-design-uplift-design.md

전체 페이지 디자인/UX 개선 — 설계

작성일: 2026-05-31 상태: 승인됨 (구현 대기)

목적

12개 Thymeleaf 페이지 전반의 시각 품질과 UX를 끌어올린다. 방향은 미니멀·정보밀도 위주 + 가벼운 인터랙션 — 화려함보다 가독성(색 절제, 정렬, 여백, 숫자 강조)과 체감 UX(클릭 이동, 카운트업, 스켈레톤)를 우선한다.

배경 / 현재 상태

• layout/base.html은 variables.css + style.css + Lucide(CDN)만 로드한다. Tailwind 같은 유틸 CSS 프레임워크는 없다.
• 그런데 템플릿들은 Tailwind식 유틸 클래스(text-secondary, text-danger, truncate, grid, justify-center, items-start, flex-1, p-2/p-3/p-8, mb-1/mb-3, hover:text-white, gap-1/gap-3 등)를 광범위하게 사용한다 — 11개 파일에 162곳.
• style.css에 실제 정의된 유틸은 그중 일부(약 30%)뿐. 나머지는 조용히 무효가 되어, 페이지들이 인라인 스타일에 의존해 버티고 있다.
• 디자인 시스템은 "Premium Dark / Glassmorphism + 네온"(variables.css)이나, 페이지들이 토큰을 일부만 쓰고 색/막대/배지가 인라인 hex로 제각각이다.

→ 공유 CSS를 손보면 전 페이지가 동시에 개선된다는 것이 핵심 레버리지.

제약 / 비범위

• 백엔드 변경 없음. 현재 API가 필요한 데이터(카테고리 id 포함)를 모두 제공.
• 새 라이브러리 없음. Tailwind도 도입하지 않는다 — 실제 사용 중인 유틸만 style.css에 직접 정의하는 것이 YAGNI에 부합. 카운트업·스켈레톤·막대는 바닐라 CSS/JS.
• 시계열·신규 지표 없음. 기능/동작은 보존하고 시각·UX만 개선.
• 현재 데이터 분포(대부분 NEW/CHANNEL/Shorts/미분류)는 그대로. 막대가 0%/100%로 단조로워 보이는 건 데이터 특성이지 결함 아님.

전략: 공유 CSS 우선

페이지별로 따로 고치지 않고 variables.css + style.css를 끌어올려 전파한다. per-page 편집은 공유 CSS로 못 덮는 고유 요소·인터랙션에만 한정한다.

Phase 1 — 공유 파운데이션 (전 페이지 영향, 마크업 거의 불변)

1. 토큰 확장 (variables.css)

• 간격 스케일 변수(예: --space-1..6), 시맨틱 색 추가: --text-secondary(이미 일부 사용), --danger(있음)·--success(있음) 외 --warning, 그리고 --primary-rgb(현재 style.css에서 var(--primary-rgb) 참조하나 미정의 — 버그).
• 그림자/보더 토큰, 본문 font-feature-settings: "tnum"(tabular-nums) 기본 적용.

2. 유틸 백필 (style.css)

템플릿이 이미 참조하는 미정의 클래스를 일괄 정의(마크업 변경 0):

• 색: .text-secondary, .text-danger, .text-success, .text-white
• 레이아웃: .grid, .grid-cols-2/3 류(실사용분만), .flex-1, .justify-center, .items-start, .truncate
• 간격: .gap-1/3, .p-2/3/8, .mb-1/3, 기타 실사용분
• 상태: .hover\:text-white:hover 등 실사용 hover 유틸
• 원칙: grep으로 실제 사용된 클래스만 정의(미사용 유틸 양산 금지).

3. 공유 컴포넌트 정련 (style.css)

• .card: 여백·hover 일관성 점검(현행 유지 + 미세 조정).
• .btn 변형: .btn-secondary가 템플릿에서 쓰이나 정의 보강 필요 — 다크 글래스 스타일로 통일.
• 신규 .badge: 상태/배수 등 공통 배지(색 variant).
• 신규 .bar-track / .bar-fill: 현재 dashboard 인라인 막대를 공통 컴포넌트로(다른 페이지도 재사용 가능).
• 폼 요소: select / input 다크 테마 스타일 통일(현재 페이지마다 제각각).
• 테이블: thead 헤더·행 hover·우측 정렬·tabular-nums.
• 신규 .skeleton: 시머 로딩 블록(@keyframes + prefers-reduced-motion 가드).
• 색 절제 팔레트: 진행도 3톤(대기=muted → 진행중=primary → 완료=success) + 제외=danger.

Phase 2 — 페이지별 폴리시 & 인터랙션

dashboard.html

• 비주얼: KPI 카운트업, 깔때기(8px 트랙·우측 정렬 값 (%)·로드 시 width 트랜지션), 떡상 행 순위 번호(1–5)·라운드 썸네일·배수 배지(수집함과 동일 색 규칙: ≥10 red / ≥2 amber / else green).
• 인터랙션(클릭 딥링크):
  • KPI/깔때기 단계 → 미검토=/collection?status=NEW, 작업대상=?status=TARGET, 완료=?status=DONE, 발행완료=/publish, 수집영상=/collection
  • 카테고리 막대 → /collection?categoryId=ID, 출처 → ?source=CHANNEL|SEARCH, Shorts/롱폼 → ?shortsOnly=true
  • 미분류 막대는 categoryId 없이 /collection로(미분류 전용 필터는 비범위).

collection.html

• URLSearchParams 초기 필터 수신(~8줄): 로드 시 status/categoryId/source/shortsOnly를 읽어 폼 컨트롤(fStatus 등)에 세팅 후 첫 loadVideos() 호출. 이게 있어야 대시보드 딥링크가 실제 필터된다.
• 필터바/결과 테이블 정련(공유 CSS 위에 소폭).

그 외 페이지

• board / publish / discover / channels / videos / production / production_detail / channel_detail / multi_channel_videos / rework: 공유 CSS로 대부분 자동 개선. 각 페이지 고유 요소(칸반 컬럼, 발행 카드, 디스커버 그리드, 상세 통계 등)만 소폭 다듬기 + hover + 스켈레톤 적용.

전역

• 클릭 가능한 요소 포인터/hover 강조, 새로고침 버튼 로딩 중 아이콘 스핀.
• 모든 애니메이션 prefers-reduced-motion: reduce 존중.

데이터 흐름 (인터랙션)

dashboard KPI/막대 클릭
  → <a href="/collection?status=NEW"> (또는 categoryId/source/shortsOnly)
    → collection.html 로드
       → URLSearchParams 파싱 → 폼 컨트롤 세팅 → loadVideos() → 필터된 결과

에러 / 빈 상태

• 로딩: 텍스트 "로딩 중…" → .skeleton 시머 블록.
• 데이터 0: 기존 안내 문구 유지.
• 알 수 없는 URL 파라미터 값(collection): 무시하고 기본(전체)로 폴백 — 폼 <select>에 없는 값이면 빈 선택 처리.

검증 방법

테스트 인프라가 없으므로(기존 관행) 페이즈마다:

1. compileJava(템플릿만 바뀌면 생략 가능) + bootRun 기동(에러 0).
2. 대표 페이지 브라우저 스크린샷 확인: Phase 1 = dashboard/collection/board/publish(공유 CSS 전파 확인), Phase 2 = 변경 페이지별.
3. 인터랙션: 대시보드 KPI/막대 클릭 → 수집함이 해당 필터로 열리는지 실제 클릭 검증.

영향 / 변경 파일 요약

• 주력 수정: static/css/variables.css, static/css/style.css.
• Phase 2 수정: dashboard.html, collection.html(딥링크 수신), 그 외 템플릿 소폭.
• 필요 시 static/js/common.js(공통 헬퍼: 카운트업 등).
• 백엔드/엔드포인트 변경 없음.

위험 / 주의

• 유틸 백필 시 기존 인라인 스타일과 충돌 가능 — 유틸은 인라인보다 우선순위 낮으므로 대부분 안전하나, 동일 속성을 다루는 유틸 정의 시 회귀 없는지 대표 페이지로 확인.
• --primary-rgb 미정의는 현재 모바일 테이블 뱃지에서 깨져 있을 수 있음(Phase 1에서 함께 수정).
• 색 팔레트 축소가 단계 구분을 흐리지 않도록 명도/톤 차이 확보.