Skip to content

design.md

Latest commit

 

History

History
204 lines (162 loc) · 12 KB

design.md

File metadata and controls

204 lines (162 loc) · 12 KB
Raw

Study Builder Design System

1. Atmosphere & Identity

Study Builder는 “차분한 개인 학습서 서가와 실행 가능한 책상”처럼 느껴져야 한다. 홈은 사용자가 보유한 학습서와 마지막 학습 문맥을 조용히 정리하고, 위키 모드는 종이책처럼 읽히며, 학습 모드는 같은 문서 언어 안에 코드·파일·실행 결과를 정밀하게 결합한다. 시그니처는 러스트 색으로 표시되는 현재 문맥의 얇은 선이다. 이 선은 현재 책, 선택 문장, 현재 실습 단계, 실행 중인 파일을 같은 제품 안의 연결된 위치로 보이게 한다.

학습서는 위키형 학습서와 실습형 학습서로 구분한다. 금리·경제·글쓰기처럼 읽기와 문서 편집이 중심인 위키형 학습서는 학습 모드 진입점을 노출하지 않는다. Spring Boot처럼 연결된 프로젝트에서 실행할 실습이 정의된 학습서만 위키/학습 작업공간 전환과 실습 폴더를 제공한다.

시각적 기준은 기존 위키 프로토타입, Figma 학습 모드 audit/learning-mode/desktop-default.png, 프로젝트에 보존된 홈 기준 시안이다. Notion은 편집 마찰과 Library/Recents 정보 구조만, Figma는 최근 파일 탐색 밀도만, GitBook은 문서 계층만, Readwise는 이어 읽기와 개인 서가 구조만 참고한다.

2. Color

Role Token Value Usage
Paper --paper #FFFEFB 책 본문, 홈 중심 캔버스
App background --app-bg #F4F5F3 앱 전체 바탕
Soft surface --soft #F8F8F6 사이드바, 보조 패널
Elevated surface --surface-elevated #FFFFFF 입력, 팝오버, 활성 세그먼트
Ink --ink #202421 본문과 제목
Muted --muted #68706B 메타데이터, 보조 설명
Tertiary --tertiary #89908C 비활성·자리표시자
Line --line #DDE1DD 얇은 구분선
Strong line --line-strong #CBD2CD 입력·강조 경계
Accent --accent #A34D3B 현재 문맥, 주요 행동, 포커스
Accent dark --accent-dark #7F382C hover·강조 텍스트
Accent soft --accent-soft #F3DFD7 선택·현재 행
Accent faint --accent-faint #FBF0EB 인용·옅은 강조
Success --success #2F7653 통과·연결 완료
Success soft --success-soft #EDF5F0 성공 배경
Warning --warning #A87927 승인 대기·주의
Warning soft --warning-soft #FFF8E8 제안·승인 배경
Error --danger #B24D45 실패·삭제
Error soft --danger-soft #FBEFEC 실패 위치·로그 배경

색은 상태와 현재 문맥에만 사용한다. 장식용 그라데이션, AI 보라색, 네온 터미널을 사용하지 않는다. 상태는 반드시 아이콘과 텍스트를 함께 쓴다.

3. Typography

  • Primary: "Pretendard Variable", Pretendard, "Noto Sans KR", "Apple SD Gothic Neo", system-ui, sans-serif
  • Mono: "SFMono-Regular", "Cascadia Code", "JetBrains Mono", Consolas, monospace
  • 글꼴은 Primary와 Mono 두 계열만 사용한다.
Level Size Weight Line height Usage
Home title 30px 700 1.3 홈 인사 제목
Page title 34px 700 1.25 위키 페이지 제목
Practice title 30px 700 1.35 학습 가이드 제목
Section 22px 650 1.4 문서 H2
Subsection 17px 650 1.45 홈·패널 섹션
Reading body 17px 400 1.72 긴 한국어 본문
UI body 14px 400 1.55 설명·목록
UI label 13px 600 1.45 버튼·탭·트리
Caption 12px 500 1.4 상태·메타데이터
Code 13px 400 1.55 코드·명령·로그

제목은 -0.02em에서 -0.035em, 본문은 -0.01em까지의 음수 자간만 사용한다. 긴 한국어 문장은 word-break: keep-all을 기본으로 하고 좁은 UI에서는 overflow-wrap: anywhere를 허용한다.

4. Spacing & Layout

기본 단위는 4px다. 의도 토큰은 4, 8, 12, 16, 20, 24, 32, 40, 48, 64px을 사용한다.

  • 공통 상단 바: 56px.
  • 홈 왼쪽 내비게이션: 216–224px, 최근 학습 기록: 260–280px.
  • 위키 목차: 260px, 접힘 레일: 56px, 본문: 최대 780px.
  • 학습 모드 1440px: 실습 단계 240px, 학습 가이드 360–380px, 파일 트리 184px, 에디터 나머지 폭, Agent 레일 44px.
  • 학습 모드 1280px: 실습 단계 216px, 학습 가이드 320px, 파일 트리 176px.
  • 학습 모드 1024px: 실습 단계는 56px 레일, 학습 가이드는 260px 요약, 파일 트리는 168px로 유지한다. 사용자의 최신 결정에 따라 파일 트리는 숨기지 않는다.
  • 에디터 실사용 폭을 확보해야 할 때 가장 먼저 실습 단계와 학습 가이드를 축소한다. 파일 트리와 현재 파일 탭은 유지한다.
  • 터미널은 기본 접힘이고 실행·오류 확인 때만 에디터 아래 220–240px를 소유한다.
  • 전체 셸은 100dvh; 상단 바는 고정되고 각 패널이 자기 스크롤을 소유한다. 모든 grid/flex scroll child는 min-height: 0을 가진다.

5. Components

AppHeader

  • Structure: 제품/책 식별, 작업공간 모드, 검색, 상태/도구, 프로필.
  • Variants: home, wiki, practice.
  • States: default, hover, focus, menu-open.
  • Accessibility: 모든 아이콘 버튼은 한국어 aria-label; 검색은 실제 label을 가진다.
  • Layout: 고정 56px cluster.

WorkspaceModeSwitch

  • Structure: 위키 / 학습 두 세그먼트.
  • States: default, hover, focus, selected.
  • Motion: 선택 배경은 140ms opacity/transform; reduced-motion에서 즉시 전환.

HomeSidebar

  • Structure: 제품 식별, 주요 탐색, 보조 탐색.
  • States: default, hover, focus, selected.
  • Layout: fixed-sidenav-shell; 홈 캔버스만 스크롤한다.

ContinueLearning

  • Structure: 책 표식, 현재 페이지, 실습 단계, 이어보기 행동, 얇은 진도선, 연결 폴더 메타데이터.
  • Variants: wiki-only, practice-linked.
  • States: default, hover, focus.
  • Rule: 영웅 마케팅 카드가 아니라 구분선 안의 한 행이다.

BookLibraryItem

  • Structure: 작은 책 표식, 제목, 목표, 마지막 페이지, 최근 시각, 얇은 진도선, 컨텍스트 메뉴.
  • States: default, hover, focus, selected, empty.
  • Layout: 두 열에서 한 열로 자연스럽게 전환하는 intrinsic grid.

RecentLearningRail

  • Structure: 사건 아이콘, 학습 행동, 책, 시간, 모두 보기.
  • States: default, hover, focus.
  • Rule: 통계·활동 피드가 아니라 원래 학습서로 돌아가는 짧은 기록이다.

PracticeStepList

  • Structure: 현재 페이지, 5개 단계, 연결 폴더.
  • States: complete, current, upcoming, focus.
  • Layout: 고정 패널 또는 56px 단계 레일.

LearningGuidePanel

  • Structure: 페이지/목표, 현재 단계, 할 일, 관련 파일, 실행 명령, 이전/다음.
  • States: expanded, compact, focus.
  • Scroll owner: 패널 본문.

ProjectFileTree

  • Structure: 프로젝트 루트, 중첩 폴더, 파일 행.
  • States: collapsed, expanded, selected, modified, focus.
  • Rule: 1440/1280/1024의 모든 학습 모드 상태에서 보인다. 긴 파일명은 말줄임하고 전체 경로 tooltip을 제공한다.

ResizablePanelHandle

  • Structure: 인접 패널 사이 6px 경계, hover/focus 시에만 보이는 grip과 Accent 선.
  • States: default, hover, focus, dragging.
  • Interaction: 실습 목록·학습 가이드·파일 트리는 수평 폭을, 터미널은 높이를 마우스 드래그로 조절한다.
  • Accessibility: role="separator", 현재/최소/최대 값을 제공하고 방향키 8px 단위 조절을 지원한다.
  • Rule: 패널 크기 조절은 현재 파일, 코드, 실행 결과, Agent 상태를 초기화하지 않는다. 상단의 패널 구성 초기화로 기본 레이아웃을 복구할 수 있다.

CodeEditorFrame

  • Structure: 열린 파일 탭, 줄 번호, 코드, 문제 표시.
  • States: default, selected-code, modified, problem, focus.
  • Rule: Light theme을 유지하고 실패 줄은 텍스트·아이콘·배경으로 함께 표시한다.

BottomPanel

  • Structure: 터미널/테스트/문제 탭, 실행 상태, 로그.
  • States: closed, command-approval, running, failed, passed.
  • Motion: 높이를 직접 애니메이션하지 않고 콘텐츠를 opacity/transform으로 전환한다.

AgentContextPanel

  • Structure: 참고 문맥, 오류 요약, 도움 단계, 행동.
  • States: minimized, summary, hint, diff-ready, success.
  • Rule: 전역 채팅이 아니라 현재 실패에 귀속된 검사 패널이다.

LearningDiffView

  • Structure: 변경 파일, 이유, 기존/제안 줄, 적용/직접 수정/취소.
  • States: pending, applied, cancelled.
  • Accessibility: 추가/삭제는 +/− 접두사와 텍스트 레이블을 함께 사용한다.

SaveToWikiPreview

  • Structure: 생성될 노트, 삽입 페이지와 위치, 적용/취소.
  • States: preview, saved.
  • Rule: 승인 전 위키 본문을 변경하지 않는다.

StatusToast

  • Structure: 상태 아이콘, 메시지, 선택적 되돌리기.
  • States: success, warning, error.
  • Motion: 160ms opacity/translateY; 자동 닫힘은 중요한 승인 결과에 사용하지 않는다.

6. Motion & Interaction

Type Duration Easing Usage
Micro 120ms ease-out hover, press, focus
Standard 180ms ease-in-out 탭, 패널 내용 전환
Panel 220ms cubic-bezier(0.16, 1, 0.3, 1) Agent·터미널 열기
  • 애니메이션은 transform, opacity, filter만 사용한다.
  • 버튼은 active에서 translateY(1px) 이하로 반응한다.
  • 탭/세그먼트는 위치 관계를 설명하는 경우에만 선택 배경이 이동한다.
  • 실행 흐름은 승인 → running → failed/passed의 의미 있는 상태 전환만 애니메이션한다.
  • 위키 편집 모드의 문단은 블록 핸들을 드래그해 재정렬한다. 드래그 중 원본은 반투명하게, 삽입 위치는 2px Accent 선으로 표시하고 본문 선택·직접 편집과 충돌하지 않게 한다.
  • prefers-reduced-motion: reduce에서는 모든 공간 이동을 제거한다.
  • 포커스는 2px 러스트 링과 2px offset으로 항상 보인다.

7. Depth & Surface

전략은 mixed지만 기본은 borders-only다.

  • 페이지·패널 구분: 1px --line과 tonal shift.
  • 카드형 표면은 책 항목, 승인 제안, 오류 요약처럼 실제 경계가 필요한 곳에만 쓴다.
  • 모서리 반경: 메뉴/버튼 4–6px, 패널/제안 6–8px. 8px를 넘지 않는다.
  • 그림자: 팝오버·floating toolbar·toast만 0 8px 24px rgba(32, 44, 37, 0.12) 이하.
  • 코드 에디터와 터미널은 검은 박스로 분리하지 않고 --soft 계열의 미세한 명도 차를 쓴다.

8. Accessibility Constraints & Accepted Debt

Constraints

  • 목표: WCAG 2.2 AA.
  • 본문 4.5:1, 큰 텍스트와 UI 경계 3:1 이상.
  • 모든 주요 흐름은 키보드로 완료 가능해야 한다.
  • 아이콘 버튼에는 label과 tooltip이 모두 있어야 한다.
  • 오류·성공·현재 상태는 색만으로 표현하지 않는다.
  • Esc는 Agent·승인·팝오버를 닫고 이전 초점으로 돌아간다.
  • 파일 트리와 단계 목록은 방향키 탐색을 지원하거나 각 행이 자연스러운 Tab 순서를 가진다.
  • 1280px에서 코드 영역이 읽을 수 있어야 하며 1024px에서도 파일 트리는 보인다.

Accepted Debt

Item Location Why accepted Owner / Exit
브라우저 fallback의 privileged 기능 없음 npm run dev Sites/UI 검토 계약을 유지하며 실제 파일·PTY 권한은 Electron에만 둔다 desktop E2E를 완료 기준으로 사용
브라우저 fallback 새로고침 후 로컬 상태 초기화 브라우저 검토 화면 영구 저장소는 Electron userData에만 존재한다 desktop 재시작 복구 검증 유지
unsigned·not-notarized macOS 산출물 배포 MVP는 로컬 개발·검증용 current-architecture package만 대상이다 Developer ID 서명·공증 단계