Skip to content

[design] 공통 디자인 컨벤션 및 타이포그래피 기반 정립 - #536

Merged
i-meant-to-be merged 2 commits into
developfrom
design/#535-design-conventions-and-typography
Oct 24, 2026
Merged

[design] 공통 디자인 컨벤션 및 타이포그래피 기반 정립#536
i-meant-to-be merged 2 commits into
developfrom
design/#535-design-conventions-and-typography

Conversation

@i-meant-to-be

@i-meant-to-be i-meant-to-be commented Oct 24, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Contributor

🚩 연관 이슈

Closes #535

📝 작업 내용

화면마다 달랐던 시각 표현을 판단할 공통 디자인 기준을 추가하고, 새 UI에서 바로 사용할 수 있는 다섯 타이포그래피 역할을 구현했음. 진영 색상 이름과 Tailwind 기본 팔레트도 새 기준에 맞춰 정리했으며, 기존 화면의 글자·색상 전체 전환은 포함하지 않음.

디자인 지침과 문서 연결

  • docs/conventions/design.md 한 곳에서 기본 시각 방향, 의미별 색상, 글자 역할, 형태·공간 대응·움직임 기준을 소유함. 컴포넌트별 상세 치수표를 늘리지 않음.
  • 문서 지도에서 지침을 등록하고 페이지·공용 UI 작업의 필수 읽기에 포함했음. React·UI 지침에는 기존 UI 확인 → 역할·변형 선택 → 상태·문구·화면 조건 검증 흐름을 연결했음.
  • 중립·오류색은 Tailwind 4 기본 팔레트를 사용하도록 정하고, 현재 구현과 남은 전환 목표를 구분했음.

실제 사용 가능한 타이포그래피

역할 클래스 크기 / 굵기 / 행간
Headline text-ui-headline 28px / 700 / 36px
Title text-ui-title 24px / 600 / 32px
Body text-ui-body 16px / 400 / 24px
Label text-ui-label 16px / 600 / 24px
Caption text-ui-caption 14px / 400 / 20px

예를 들어 화면 제목은 text-ui-headline, 일반 설명은 text-ui-body와 별도 글자색을 조합함. md:text-ui-title 같은 화면 조건 조합도 사용할 수 있음. Pretendard 계열 글꼴을 상속하며 색상·자간을 역할에 고정하지 않음.

  • src/index.css의 @theme가 각 역할의 크기·굵기·행간을 함께 소유함. 기존 .text-title은 28px 크기만 지정하므로 새 Title 역할의 text-ui-title과 구분했음.
  • 사양 변경 시 디자인 문서 표와 CSS 정의를 반드시 같은 변경에서 갱신하도록 명시했음. 역할·클래스명 변경 시 사용처와 디자인 샘플 Story도 함께 갱신함.
  • 기존 --text-*-raw와 크기 전용 선택자는 사용처 호환을 위해 유지하고, 최신 타이포그래피로 교체 후 삭제 예정임을 주석으로 표시했음.

진영 이름과 기본 팔레트 정리

  • 색상·그림자 이름 및 소스·테스트에서 camp-*를 stance-*로 변경했음. 브랜드·진영 색상의 실제 값은 유지함.
  • blue·gray·neutral·red·slate·zinc 기본 팔레트를 v3 값으로 덮어쓰던 23개 선언을 제거했음. 해당 기본 클래스는 Tailwind 4의 내장값으로 표시됨.
  • 기존 UI가 소비하는 default-·semantic- 사용자 정의 색상은 유지함. 기존 화면의 색상·타이포그래피 전체 이관과 관련 없는 의존성 갱신은 포함하지 않음.

검증 결과

검증 실제 결과
전체 Vitest 76개 파일·666개 항목 통과(146.05초). 작업자 4개·상세 출력으로 전체 실행함
lint ESLint·Stylelint·타입 검사 통과, 기존 소켓 테스트 Hook 의존성 경고 1개 유지
생산 빌드 통과, 큰 번들 경고 유지. Sentry 외부 업로드는 실행하지 않음
Storybook 빌드 통과, 큰 번들·플러그인 소요 시간 안내 유지
생성 CSS·문서·포맷 5개 기본/md 글자 utility·문서 사양 일치, 진영 이름 미잔존, 기본 색상 재정의 23개 제거, 링크·앵커 43개·포맷·diff 검사 통과
브라우저·원격 CI·미리보기 PR 생성 전 미실행임

전체 테스트는 node node_modules/vitest/vitest.mjs run --maxWorkers=4 --reporter=verbose로 실행했으며 Windows 임시 경로를 node_modules/.cache/stance-validation으로 지정했음. 최초 단일 작업자 실행은 종료 결과가 없어 중단했고 원인은 미확정임. 전체 테스트에서 기존 Table의 button 중첩 경고도 관찰했으나 해당 구조는 변경하지 않았음.

검증 환경은 Node 24.21.0·npm 12.2.1·Vite 8.3.5·Vitest 4.1.12·Tailwind 4.3.3·Storybook 10.6.3임. 별도로 남아 있는 package-lock.json 변경은 이 PR에서 제외하며, 로컬 검증은 해당 설치 환경에서 수행했음. 이 PR에 포함될 기존 잠금 파일을 기준으로 새로 설치한 결과는 아니므로 원격 CI의 설치·테스트·lint 확인이 필요함.

🗣️ 리뷰 요구사항 (선택)

  • 역할별 문서 사양과 @theme 정의가 일치하고, 기존 글자 선택자를 새 역할과 혼동하지 않는지 확인함.
  • 진영색 이름의 모든 사용처·테스트가 함께 바뀌었는지와, 기본 팔레트 재정의 제거에 따른 기존 화면의 색감 차이를 확인함.
  • 기존 화면 전체 이관 없이 새 공통 역할만 제공하는 범위와 사양·소스 동시 갱신 규칙을 확인함.
  • PR 생성 후 포함된 잠금 파일 기준 CI와 미리보기 결과를 확인함. 아직 실행하지 않은 결과를 통과로 기록하지 않음.

일반 테스트·lint CI 외의 생성 CSS·빌드·시각 검증을 다음과 같이 확인함.

npm run build
npm run build-storybook -- --disable-telemetry
npm run storybook

Storybook의 Design System/DesignSystemSample에서 다섯 역할의 크기·굵기·행간과 색상 분리를 확인함. 실제 화면에서는 진영색의 찬반 대응, 기존 크기 전용 선택자의 표시 유지, 기본 회색·오류색 변경, 한국어·영어 긴 문구·좁은 화면의 읽기 상태를 확인함. Safari·Firefox·색 대비·움직임 감소 및 미리보기의 정적 자산 로딩은 수동 확인 범위임.

Summary by CodeRabbit

  • 새로운 기능

    • 공통 디자인 가이드와 작업별 필수 참고 문서를 추가했습니다.
    • 색상과 타이포그래피 사용 원칙, 화면 구성과 반응형·움직임 대응 지침을 정리했습니다.
    • 디자인 시스템 예시에서 새 타이포그래피 역할을 확인할 수 있습니다.

  • 변경 사항

    • 찬성·반대 색상 표현을 새 색상 체계에 맞게 조정했습니다. 타이머, 발언 기록, 보고서 등 관련 화면에 적용됩니다.
    • 기본 팔레트와 타이포그래피 토큰을 정리했습니다. 기존 색상 전환 및 화면 전반의 글자 역할 적용은 아직 진행 중입니다.

@i-meant-to-be i-meant-to-be added docs 문서 관련 작업 design UI 관련 labels Oct 24, 2026
@coderabbitai

coderabbitai Bot commented Oct 24, 2026 •
edited
Loading

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: dbd3a213-d5e8-4f3c-ac74-5d3de73d5a0d
Commits

Reviewing files that changed from the base of the PR and between 5736bb0 and 1c23713.

Files selected for processing: 19
  • docs/README.md
  • docs/conventions/design.md
  • docs/conventions/react-and-ui.md
  • src/components/DesignSystemSample/DesignSystemSample.stories.tsx
  • src/components/ProsAndConsTitle/PropsAndConsTitle.tsx
  • src/components/TimerProgressBar/TimerProgressBar.test.tsx
  • src/components/TimerProgressBar/TimerProgressBar.tsx
  • src/index.css
  • src/page/AudienceSharePage/AudienceSharePage.test.tsx
  • src/page/AudienceSharePage/components/AudienceNormalTimer.test.tsx
  • src/page/AudienceSharePage/components/AudienceTimeBasedTimerDisplay.test.tsx
  • src/page/AudienceSharePage/components/AudienceTimeBasedTimerDisplay.tsx
  • src/page/DebateTranscriptPage/components/ReportView.tsx
  • src/page/DebateTranscriptPage/components/TranscriptView.tsx
  • src/page/DebateTranscriptPage/stanceStyle.ts
  • src/page/TimerPage/components/CircularTimer.tsx
  • src/page/TimerPage/components/NormalTimer.tsx
  • src/page/TimerPage/components/TimeBasedTimer.tsx
  • src/page/TimerPage/components/TimerController.tsx

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

공통 디자인 컨벤션과 다섯 가지 타이포그래피 토큰을 추가했습니다. 전역 CSS와 디자인 샘플을 갱신하고, 진영 색상 클래스명을 camp-*에서 stance-*로 변경했습니다.

Changes

공통 디자인 시스템

Layer / File(s) Summary
디자인 기준과 작업 지침
docs/conventions/design.md, docs/conventions/react-and-ui.md, docs/README.md		 색상, 타이포그래피, 형태, 반응형 대응 및 움직임 기준을 문서화했습니다. 작업별 필수 문서 안내와 UI 작성 지침을 갱신했습니다.
전역 디자인 토큰과 샘플
src/index.css, src/components/DesignSystemSample/DesignSystemSample.stories.tsx		 전역 CSS에 다섯 가지 text-ui-* 토큰을 추가했습니다. 진영 색상·그림자 변수 이름을 변경하고, 디자인 샘플을 새 타이포그래피 예시로 갱신했습니다.
진영 색상 명칭의 사용처 갱신
src/components/ProsAndConsTitle/PropsAndConsTitle.tsx, src/components/TimerProgressBar/*, src/page/AudienceSharePage/*, src/page/DebateTranscriptPage/*, src/page/TimerPage/components/*		 찬성·반대 색상 클래스 사용처와 관련 테스트를 stance-* 명칭으로 변경했습니다. 일부 색상 값과 조건 분기는 유지했습니다.

Priority: Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Possibly related PRs

Suggested labels: feat

Suggested reviewers: coli-geonwoo, jaeml06, useon

Merge Risk: Minimal · up to 1c237

The design tokens and stance color renames are consistently defined and consumed, so the change is mergeable with normal checks.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 15 files. (4 skipped: … Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed PR 제목은 공통 디자인 컨벤션과 타이포그래피 기반을 정립하는 주요 변경 사항을 정확하고 간결하게 설명합니다.
Linked Issues check Passed 직접 연결된 활성 이슈는 #535입니다. docs/conventions/design.md에 시각 방향, 색상, 정보 위계, 형태, 공간 제약, 움직임 기준을 추가하고 문서 지도와 React·UI 지침에 연결했습니다. src/index.css에 text-ui-headline, text-ui-title, text-ui-body, `text-u…
Out of Scope Changes check Passed 변경 범위는 #535의 문서 추가, 타이포그래피 utility 정의와 샘플 갱신, 진영 색상·그림자 명칭 변경, Tailwind 기본 팔레트 재정의 제거, 관련 사용처·테스트 갱신으로 제한됩니다. 기존 화면의 전체 타이포그래피·색상 전환이나 의존성 갱신은 추가하지 않았습니다. 확인된 변경은 이슈 목표를 지원하므로 구체적인 무관 변경은 없습니다.
Full details: Linked Issues check

Explanation

직접 연결된 활성 이슈는 #535입니다. docs/conventions/design.md에 시각 방향, 색상, 정보 위계, 형태, 공간 제약, 움직임 기준을 추가하고 문서 지도와 React·UI 지침에 연결했습니다. src/index.css에 text-ui-headline, text-ui-title, text-ui-body, text-ui-label, text-ui-caption을 크기·굵기·행간과 함께 정의했습니다. 디자인 샘플 Story도 새 역할을 사용합니다. 기존 글자 선택자와 raw 변수는 삭제 예정 주석과 함께 유지합니다. 관련 진영 색상과 그림자 명칭을 camp-*에서 stance-*로 변경하고 테스트 기대값도 갱신했습니다. Tailwind 기본 팔레트 재정의 제거와 검증 결과 및 미실행 범위도 기록했습니다. 변경 내용은 #535의 코딩 요구사항을 충족합니다.

Full details: Docstring Coverage

Explanation

Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 15 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

토끼가 새 색 이름을 살펴보네
파랑과 빨강, stance로 가지런하네
다섯 글자 토큰이 CSS에 앉고
샘플 Story도 새 옷을 입네
문서 곁에서 당근을 나누네

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Oct 24, 2026

Copy link
Copy Markdown

🚀 Preview 배포 완료!

환경 URL
Preview 열기
API Dev 환경

PR이 닫히면 자동으로 정리됩니다.

@i-meant-to-be
i-meant-to-be merged commit 4c90945 into develop Oct 24, 2026
3 checks passed
@github-actions

github-actions Bot commented Oct 24, 2026

Copy link
Copy Markdown

🧹 Preview 배포가 정리되었습니다.

This branch was successfully deployed

2 active deployments
DEPLOY_DEV — 1c23713c Deployed Oct 24, 2026 by i-meant-to-be via build-and-deploy #203
PREVIEW_ENV — 1c23713c Deployed Oct 24, 2026 by i-meant-to-be via cleanup #51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

design UI 관련 docs 문서 관련 작업

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[DESIGN] 공통 디자인 컨벤션 및 타이포그래피 기반 정립

1 participant

@i-meant-to-be