Docs

docs/system/studio.md

Studio 검수 기준

apps/studio는 공용 자산을 화면 맥락에서 구현하고 검수하는 애플리케이션이며 그 자체가 전달 대상 자산이다. 컴포넌트를 찾아보고 확인하는 표준 채널이 이 Studio다. Storybook은 두지 않기로 했다(2026-09-18, docs/process/ai-environment.md). 이 문서는 Studio 화면을 구성하는 기준이다.

구조 용어는 vocabulary.md, Focus 표시 규칙은 interaction.md를 따른다.

화면 예시에는 가능한 경우 다음 검수 컨트롤을 제공한다.

  • Light/Dark
  • 국문/영문/일어 콘텐츠와 typography
  • 모바일/데스크톱 반응형
  • 인터랙션과 상태
  • 출처와 oe mapping 상태

컴포넌트 Anatomy의 연결선은 Light/Dark 모두 oe-border-primary 회색조를 사용한다. 연결선과 숫자 마커의 진한 배경은 서로 다른 역할로 분리하며, 연결선에 foreground 또는 black 직접값을 사용하지 않는다.

Studio 문서 설명은 국문을 유지한다. 언어를 선택하면 컴포넌트 Preview 안의 Label, Value, Placeholder, 제품 사례 문구, 접근 가능한 이름과 해당 범위의 lang을 함께 바꾼다. 구조 명칭이 아닌 실제 Component/Example 콘텐츠를 한 언어로 하드코딩하지 않는다. 전체 문서 번역은 국문 문서가 완료된 뒤 별도 작업으로 다룬다.

Component catalog의 title, description, route와 Similar/Works with 관계는 공용 component-registry를 단일 원본으로 사용한다. 목록 순서도 registry가 소유하며 title의 알파벳순으로 둔다. Component를 성격별로 묶는 분류는 아직 정의하지 않았고, 정하지 않은 분류로 순서를 만들면 없는 위계를 암시하게 되므로 분류가 정해질 때까지 알파벳순을 유지한다. 모든 Component route는 공용 상세 page shell을 사용하고, 각 Workbench는 우측 On this page와 registry 관계를 연결한다.

Component 상세 화면의 Guidelines 하위 주제 제목은 공용 GuidelineTitle을 사용한다. 제목 앞에는 Remix RiBookOpenLine 16px을 Tertiary foreground로 배치하고 제목은 14px Semibold, 아이콘과 제목 간격은 8px로 유지한다. 컴포넌트별 Workbench에서 같은 스타일을 다시 만들지 않는다.

Guidelines의 Target area 예시, Do/Don’t 비교, 제출 지연 예시와 불릿 목록은 공용 component-guidelines 구성요소를 사용한다. Checkbox와 Switch처럼 같은 사용 원칙을 설명하는 컴포넌트는 시각 구조와 정보 위계를 공유하고, 실제 컴포넌트와 문구만 각 목적에 맞게 바꾼다.

Target area를 설명할 때는 실제 컴포넌트를 바꾸지 않고 공용 TargetArea Studio 표시를 겹친다. 영역 전체를 점선이나 색면으로 둘러싸지 않고, 실제 최소 조작 높이 또는 Row 높이의 옆에 1px 직선과 양끝 캡을 둔 치수선 및 숫자 Label을 표시한다. 이 측정 표시는 실제 제품 컴포넌트 스타일에 포함하지 않는다.

Studio의 수치 측정 Annotation은 Violet 계열을 공통으로 사용한다. 대상은 width·height·min/max·Target area 같은 크기, padding·gap·inset 같은 내부/외부 간격, radius, font-size·line-height·letter-spacing처럼 수치로 측정하는 Typography 스펙이다. 숫자가 token으로 표현되어도 역할이 치수이면 같은 Violet 표시를 사용한다. Font family·weight 명칭, semantic color 값, 상태, Anatomy 번호와 Swap 영역은 치수 Annotation이 아니므로 Violet 규칙을 적용하지 않는다. 치수 숫자 Pill은 border 없이 옅은 Violet 배경과 진한 Violet 글자만 사용한다.

화면 프레임과 그 예외

Studio의 화면은 max-w-6xl 프레임과 px-4 py-5 sm:px-8 sm:py-8 여백을 공유한다. 화면을 옮길 때 본문이 위아래나 좌우로 밀리지 않게 하기 위해서다. 목록의 compact 밀도는 카드 그리드에만 적용하고 페이지 여백과 헤더 간격은 바꾸지 않는다.

/screens/*는 예외다. 그 아래 경로는 자산을 검수하는 화면이 아니라 제품 화면 자체를 구현하는 자리이므로, 문서형 레이아웃을 따르지 않고 각자의 레이아웃 규칙을 갖는다. 관리자는 뷰포트를 전부 쓰고, 앱 화면은 웹에서 접근했을 때 모바일 뷰가 화면 가운데에 선다.

  • 두 앱 화면은 공용 MobileWebView를 함께 쓴다. 화면마다 폭을 직접 적으면 한쪽만 고쳤을 때 두 화면의 기준이 갈린다.
  • 모바일 뷰는 기기 모형이 아니다. 둥근 모서리와 그림자로 상자를 만들지 않고 높이도 고정하지 않는다. 웹에서 앱에 접근한 실제 페이지이므로 창 높이를 그대로 쓰고, 넓은 화면에서 좌우 바닥과 만나는 자리만 한 줄로 구분한다.
  • 넓은 화면에서 좌우를 어떻게 확장할지는 정하지 않았다. 가능성만 열어 두었으므로 그 자리를 임의로 채우지 않는다.
  • Studio 내비게이션은 개별 화면(/screens/<루트>/<화면>)에서 그려지지 않는다. 작업 목록인 /screens·/screens/<루트>에서는 그려진다. 상단에 바가 얹히면 관리자 화면이 실제로 차지하는 높이를 볼 수 없고 앱 화면은 기기 상자 밖에 다른 것이 서게 된다. 그렇다고 돌아가는 링크를 화면 위에 고정하지도 않는다. 그 링크가 실제 화면 요소를 가려 무엇을 보고 있는지 확인하는 일을 방해하며, 이는 관리자 화면과 앱 화면이 다르지 않다. 돌아가는 길은 브라우저 뒤로 가기가 갖는다.
  • 메뉴에는 작업 목록인 /screens만 올리고 그 아래의 개별 화면은 올리지 않는다. 확정된 자산의 카탈로그와 섞이면 무엇이 검수를 마친 것인지 흐려지므로, 목록을 한 번 지나가게 해서 그 화면들이 만드는 중이라는 것을 먼저 알린다.
  • 각 루트의 첫 화면은 완성된 앱이 아니라 작업 목록이다. 이 아래는 기능 화면을 한 건씩 만드는 자리이고 화면끼리 이어지는 데모가 아니다. 무엇을 만들 예정이고 어디까지 왔는지를 먼저 보여 주지 않으면 열어 본 사람이 덜 만들어진 화면을 고장난 것으로 읽는다.
  • 화면은 눈으로 확인하려고 만든다. 화면에 보이는 요소가 실제로 동작하지 않을 수 있다. 목록의 첫 화면이 이 사실을 먼저 알린다. 화면마다 적지 않는 이유는 들어오는 사람이 모두 그 목록을 지나가기 때문이며, 화면마다 적으면 같은 말이 항목 수만큼 반복된다.
  • 목록의 항목은 어디까지 만드는 화면인지를 함께 밝힌다. 「홈(헤더와 메뉴까지만)」처럼 범위를 좁혀 적는다. 아직 만들지 않은 항목은 링크가 아니라 예정으로 둔다. 목록의 단일 원본은 screen-registry다.

예외의 경계는 경로로 긋는다. 「카탈로그 화면」처럼 성격으로 나누면 새 화면이 생길 때마다 어느 쪽인지 다시 판단하게 된다.

문서 화면

Studio는 docs/system의 문서를 Docs 메뉴에서 그대로 읽을 수 있게 표시한다. 저장소가 문서 원본을 소유하고 Studio는 표시만 하며, 별도 사본을 만들지 않는다.

  • 컴포넌트 상세 페이지 하단에는 그 컴포넌트의 명세 문서를 함께 표시한다. 기본 상태는 접힌 상태이며 제목과 파일 경로 링크만 보인다. 명세 전체를 펼쳐 두면 화면 검수의 흐름이 끊기고 아래 내용이 과하게 길어지므로, 필요할 때 펼쳐 본다. 화면과 명세가 어긋나는지를 같은 화면에서 확인하는 것이 목적이다. 페이지 상단의 명세 문서 보기로 바로 이동한다.
  • 문서 안의 상대 링크는 Studio route로 바꿔 표시한다. 문서끼리의 참조가 화면 밖으로 새지 않는다.
  • 표는 본문을 가로로 밀지 않도록 표 안에서만 스크롤한다.
  • 문서 본문 스타일은 Studio chrome이며 제품 컴포넌트 스타일에 포함하지 않는다.

Playground 종속 컨트롤 표시

  • 상위 Property가 활성화되어야 사용할 수 있는 하위 Playground control은 상위 control 바로 아래의 종속 그룹으로 묶는다.
  • Playground control은 Appearance → State → Content → Elements → Behavior 순서의 그룹으로 묶고 각 그룹에 제목을 둔다. Appearance는 Style·Size·Shape·Layout처럼 시각을 결정하는 Property, State는 Disabled·Read only·Invalid처럼 조작 가능성과 유효성, Content는 값과 문구, Elements는 교체하거나 표시 여부를 정하는 요소, Behavior는 범위·단계·선택 방식처럼 동작을 정하는 Property다. 성격이 다른 Property를 사이에 끼우지 않는다. 값 Property 사이에 시각 Property가 들어가면 무엇을 조절하는 중인지 알기 어려워진다. Appearance에 Property가 많으면 Style, Size, Layout처럼 더 나눌 수 있으나 다섯 그룹의 순서는 유지한다. 그룹은 Property의 성격으로 정하고 종속 관계로 정하지 않는다. 상위 Property가 꺼져 있어야 의미가 없어지는 control은 자기 성격의 그룹에 두고 비활성으로 표시한다. 같은 Property가 컴포넌트마다 다른 그룹에 놓이면 화면을 옮길 때 찾는 자리가 달라진다.
  • Playground control은 실제 public Property의 타입을 그대로 반영한다. Boolean Property만 Toggle을 사용하고 Enum은 선택 버튼, String/Number 값은 각각 Text/Number input을 사용한다. Label·Description처럼 UI를 설명하는 정적 텍스트 요소의 문구는 구조 검수용 Playground에서 편집하지 않고 Label, Description 같은 고정 문구를 사용한다. 해당 텍스트 요소가 Optional이면 Show label 같은 임의 문장 대신 실제 Property 이름인 Label, Description Boolean Toggle만 제공한다. 실제 문구를 입력하는 Text control은 콘텐츠 길이, 줄바꿈이나 언어별 문구 검수가 목적일 때만 제공한다. Input의 Value·Placeholder처럼 사용자가 실제로 입력하거나 제출하는 데이터는 이 정적 텍스트 규칙에서 제외하고 public Property 타입에 맞는 값 Control을 유지한다. 교체 가능한 ReactNode Slot은 None / Icon / Image처럼 검수할 콘텐츠 유형을 선택하며 실제 Property 이름인 Leading element, Trailing element를 label로 사용한다. 페이지마다 같은 Property를 Toggle, 문장형 label 또는 값 input으로 임의 변경하지 않는다. Image 유형은 공통 정사각 Avatar 샘플을 사용하며 페이지마다 임의 이미지를 만들지 않는다.
  • Desktop Playground에서는 Preview를 상단에 유지하고 Property panel의 내부 스크롤은 사용하지 않는다. Property panel의 왼쪽 열은 여러 컴포넌트에 공통적인 Appearance, Size, Layout, State를, 오른쪽 열은 컴포넌트 고유 구성이 많은 Content, Elements, Behavior를 표시한다. 좁은 viewport에서는 두 열을 다시 한 열로 합쳐 중첩 스크롤과 가로 압축을 피한다.
  • Preview surface는 Property panel의 전체 높이를 채운다. 그 안에서 컴포넌트를 세로로 어디에 두는지는 컴포넌트의 성격이 정하며, 상단과 가운데 두 방식을 모두 쓴다. 하나를 전체 규칙으로 정하지 않는다.
    • 상단 정렬은 부모 너비를 채우거나 아래로 자라는 컴포넌트가 쓴다. 한 줄 Form control과 Field, Popup이 열리는 Select·Combobox, 행 수가 달라지는 Textarea가 여기에 해당한다. 가운데에 두면 높이가 자랄 때 위아래가 함께 움직여 무엇이 늘어난 것인지 읽히지 않는다.
    • 가운데 정렬은 내용 너비를 쓰고 높이가 Size 단계로만 정해지는 컴포넌트가 쓴다. Button과 Badge가 여기에 해당한다. Property를 바꿀 때 컴포넌트가 같은 자리에서 변하므로 무엇이 달라졌는지 바로 보인다.
    • 어느 쪽을 골랐든 Property editor의 높이가 달라져도 Preview 안의 컴포넌트는 그 기준 위치를 유지한다.
  • 교체 가능한 Slot의 Icon 후보는 전체 Remix Icon catalog를 복제하지 않고 제한된 목록을 사용한다. 현재 후보는 Search, Password Lock, User, Global, Calendar다.
  • 종속 그룹은 영역의 border를 사용하지 않는다. 왼쪽에 폭 2px의 곧은 oe-border-primary 막대를 별도 요소로 두고 border-radius: 9999px로 선의 위아래 끝만 둥글게 처리하며, 콘텐츠는 16px 들여쓴다.
  • 단순한 시각 구분에는 이 표시를 사용하지 않는다. 상위값에 실제로 종속된 control에만 적용한다.

Component 상세 페이지 순서

  • 기본 정보 흐름은 Overview → Playground → Anatomy → Properties → Examples/Usage → Property map 순서다.
  • Component 상세 페이지의 첫 번째 Tab 진입점은 Playground로 바로 이동 skip link다. 이 링크는 #studio-preview를 focus target으로 사용하고, 다음 Tab에서 Playground의 첫 실제 Control로 이동해야 한다. 전역 Studio 설정을 건너뛰기 위해 양수 tabIndex로 순서를 재작성하지 않는다.
  • 신규 컴포넌트의 Studio 화면은 Playground, Anatomy와 Structure map까지 먼저 만든다. Properties, Examples/Usage, Guidelines와 Property map은 그 화면을 검수한 뒤 사용자가 다음 단계를 요청할 때 추가한다. 이 순서는 Studio 화면 범위에 대한 것이며 공용 package 구현, 접근성과 자동 테스트는 처음부터 함께 검증한다.
  • Anatomy는 컴포넌트의 구성 요소와 명칭을 먼저 이해시키는 영역이므로 Appearance, Style, Size, State, Elements 같은 Properties보다 앞에 둔다.
  • 컴포넌트 특성상 존재하지 않는 섹션은 생략할 수 있지만, 존재하는 섹션의 상대적인 순서는 유지한다.
  • 우측 On this page 항목도 실제 본문과 같은 순서를 사용한다. 목차는 평평한 단일 rail을 사용하며 화면의 활성 구간에 여러 섹션이 걸리면 해당 항목을 모두 강조하고, 활성 선의 위치와 높이는 300ms로 전환한다. 다른 Component로 이동하는 링크는 본문 하단 카드가 아니라 rail 아래의 낮은 위계 Related 링크로 제공한다.
  • 제목 위계는 페이지 제목 text-3xl, Section 제목 text-xl, Guidelines 그룹 제목 text-lg, Section 하위 그룹 제목과 Guidelines 규칙 제목 text-sm, 그룹 안 카드 라벨 text-xs를 사용한다. 그룹은 카드 묶음의 조건을, 카드 라벨은 그 한 칸이 무엇인지를 말하므로 두 층을 같은 크기로 쓰지 않는다. Guidelines 하위 주제 제목은 크기가 아니라 공용 GuidelineTitle의 아이콘으로 구분하므로 text-sm을 유지한다.
  • Guidelines 규칙 제목은 「~하기」 동사형으로 쓴다. 「Target area 확보하기」, 「Resize는 세로만 허용하기」처럼 무엇을 하라는 문장이어야 고르는 사람이 제목만 읽고 규칙을 알 수 있다. 금지하는 규칙도 「Resize와 Auto size는 같이 사용하지 않기」처럼 같은 형태를 유지하고, 「클릭 가능한 요소가 아니다」 같은 서술문으로 두지 않는다. 쓰임별 규칙은 「Chip을 Filter로 사용하기」처럼 컴포넌트 이름을 앞에 둔다. 요소 이름은 Anatomy에서 쓰는 이름을 그대로 쓴다.
  • Guidelines의 규칙 문구와 Do/Don't 라벨은 화면에서 일어나는 현상이 아니라 고르는 사람이 취할 행동으로 쓴다. 「줄이 맞지 않습니다」가 아니라 「다른 크기를 쓰지 않습니다」다. 읽는 사람은 이미 이 컴포넌트를 쓰기로 정하고 무엇을 고를지 판단하는 중이므로, 현상 서술은 그 판단에 쓰이지 않는다. Do는 「~을 씁니다」, Don't는 「~을 쓰지 않습니다」로 형태를 맞추고 왜 그런지는 그 아래 설명 목록이 담당한다.
  • Guidelines와 Property 카드의 설명에는 px 수치를 적지 않는다. 수치는 값을 나열하는 것이 목적인 Properties · Size 같은 자리와 명세 문서가 소유한다. 카드 설명은 그 항목이 무엇인지까지만 말하고 구현한 이유와 근거를 담지 않는다. 그만큼 전달할 내용이 있으면 명세 문서에 둔다.
  • Guidelines 규칙 제목은 해당 docs/system/components/{component}.md의 소제목과 같게 유지한다. 한쪽만 고치면 화면과 명세를 함께 보는 사람이 두 목록을 대조하지 못한다.
  • Guidelines 안에서 여러 규칙을 한 용도로 묶어야 하면 text-lg의 공용 GuidelineGroupTitle을 그 위에 둔다. 「Chip을 Filter로 사용하기」처럼 규칙 묶음이 어느 쓰임에 대한 것인지를 말하는 자리이며, 쓰임과 무관하게 늘 지키는 규칙을 묶을 때도 같은 단계를 사용한다. 쓰임이 여럿인 컴포넌트는 공통 규칙을 앞에 두고 쓰임별 조합을 그 뒤에 둔다. 이미 이 컴포넌트를 쓰기로 정한 사람에게 먼저 필요한 것은 어느 쓰임이든 지켜야 하는 것이다. 아래 단계인 GuidelineTitle이 책 아이콘 16px을 쓰므로, 그룹 제목은 목록 아이콘 20px을 써서 두 층이 같은 표시를 갖지 않게 한다. 묶을 규칙이 하나뿐이면 이 단계를 만들지 않는다.
  • 그룹 제목과 설명 바로 아래에는 그 쓰임을 직접 조작할 수 있는 시각 하나를 둔다. 규칙마다 붙는 시각은 그 아래 규칙 제목 밑에 둔다. 조작 가능한 시각을 규칙마다 반복하면 같은 화면을 여러 번 그리게 된다.
  • 쓰임과 무관한 공통 규칙 그룹에는 그룹 제목 아래 조작 시각을 두지 않는다. 조작할 쓰임이 없기 때문이며, 시각은 각 규칙 제목 아래에 두 칸 비교로 둔다. 두 칸은 Do와 Don't이거나 값의 길이나 모양처럼 나란히 놓고 견주는 쪽이다.
  • 문서에서 주요 Property로 언급한 Appearance, Style, Size, State, Layout, Element, Behavior 등은 각각 독립된 카드 또는 섹션에서 값과 차이를 확인할 수 있어야 한다.
  • Appearance, State, Size, Elements처럼 확인된 Property 범주가 명확하면 각각을 Properties · Appearance 같은 독립된 바깥 Section 카드로 만든다. 구체적인 범주를 다시 더 큰 포괄 카드 하나에 묶지 않는다.
  • Property Section의 직접 하위 제목과 카드는 해당 Property 값으로 구성한다. 예를 들어 Checkbox의 Properties · Appearance에서는 Rounded·Ghost가 직접 하위가 되며, 비교를 위한 Unchecked·Checked 상태는 각 Appearance 카드 내부에 배치한다. 비교 상태를 상위 그룹으로 만들어 Property 계층을 뒤집지 않는다.
  • 같은 섹션 안에서 제목·설명·카드 묶음이 Surface 밖에 반복되는 StateGroup 같은 구조는 그룹 사이를 32px 수준으로 분리한다. 제목 없이 카드만 연속되는 Elements 구조에는 기본 카드 간격을 유지한다.
  • Guidelines의 시각 카드는 안에 놓인 요소를 카드 너비만큼 늘린다. 공용 GuideVisual과 UsageComparison이 이 동작을 소유하므로 화면마다 w-full을 다시 붙이지 않는다. 두 열의 예시 크기가 서로 다르면 비교 대상이 아니라 크기 차이가 먼저 읽힌다.
  • Anatomy는 유형명·시각 예제·범례 전체를 Neutral 회색 Surface로 묶는다. Guidelines의 시각 예시 카드는 Neutral 회색 배경만 사용하고 바깥 border는 두지 않는다. 그 안에서 실제 화면 또는 컴포넌트를 감싸는 Container는 흰색 oe-background-primary Surface와 옅은 Neutral border를 사용한다. Properties, Layout과 State의 일반 예시는 흰색 Surface와 Neutral border를 유지한다. Playground는 검수용 테스트 환경임을 드러내기 위해 Neutral 회색 Surface와 2px oe-border-bold-primary 외곽을 사용하고, 그 안에서 실제 컴포넌트를 두는 영역만 흰색 oe-background-primary를 사용한다. 카드 구조 자체는 별도 화면 체계 재설계 전까지 임의로 제거하거나 다른 배경형으로 바꾸지 않는다.
  • Guidelines의 첫 꼭지는 이 컴포넌트를 쓸 자리인지 가리는 사용 조건이 될 수 있다. 그 자리가 아니면 나머지 규칙을 읽을 필요가 없기 때문이다. 둘 다 쓸 수 있는 자리에서 어느 쪽이 나은지 가리는 비교 꼭지는 뒤쪽에 둔다. 이미 이 컴포넌트를 쓰기로 정한 사람에게 먼저 필요한 것은 이 컴포넌트를 어떻게 쓰는지다. 다른 Component가 언급되는지는 기준이 아니며, 사용 조건도 결론이 다른 Component를 가리킬 수 있다.
  • Property map이나 Playground control에만 존재하고 별도 설명 카드가 없는 주요 Property를 발견하면 자동으로 카드를 만들지 말고 사용자에게 카드가 필요한지 묻는다.
  • name, value, form처럼 native 연결을 위한 기술 속성까지 모두 시각 카드로 만들지는 않는다. 시각·구조·동작을 이해하는 데 독립 설명이 필요한 상위 Property를 카드 점검 대상으로 삼는다.

Anatomy swap 표시

  • Studio의 Anatomy에서 leadingElement, trailingElement 또는 swap이라고 부르는 교체 가능 영역은 공통 AnatomySwapSlot 표시를 사용한다.
  • 기본 표시는 1px Pink 점선, 4px radius와 옅은 Pink 배경이다. 영역 크기만 실제 Slot 규격에 맞게 조정할 수 있다.
  • 이 표시는 Studio 문서에서 교체 가능한 Slot을 설명하기 위한 것이며 실제 제품 컴포넌트의 border나 background 스타일로 포함하지 않는다.
  • Component 문서와 Anatomy 명칭에는 해당 영역의 Optional 여부를 함께 표시한다.

Anatomy 번호와 범례

  • Anatomy Preview는 실제 컴포넌트를 그대로 사용하거나 정적 도식으로 그릴 수 있다. 그리는 경우에도 실제 컴포넌트와 다르게 보이면 안 되며 아이콘, 값, 선택 상태, 간격과 radius가 실제 렌더링과 일치해야 한다. 요소 이름을 컴포넌트 안에 넣지 않는다.
  • 번호 마커는 실제 요소를 밀지 않도록 컴포넌트 바깥에 배치하고 1px oe-border-primary 안내선으로 대상을 연결한다.
  • Text, Icon처럼 보이는 요소의 실제 클릭·터치 영역이 더 크더라도 번호선은 Hit area 중앙이 아니라 사용자가 화면에서 식별하는 글자 또는 아이콘의 시각 중심을 가리킨다. Container, Group, List 같은 묶음 영역만 별도 평행선으로 범위를 표시한다.
  • 번호 마커의 자리는 좌표를 손으로 적지 않고 가리킬 대상을 지정해 잡는다. 공용 AnatomyFrame 안에서 AnatomyNumber와 AnatomyBoundaryMarker가 대상 요소를 실제로 재어 위치와 안내선 길이를 정하므로, 예시 콘텐츠나 부품 크기가 바뀌어도 번호선이 대상에서 빗나가지 않는다. 대상은 구현이 이미 갖고 있는 data-slot selector를 우선 사용하고, 그런 표시가 없는 글자 요소는 화면에 보이는 요소 명칭으로, 묶음 영역은 품고 있는 부품 이름으로 지정한다. 도식으로 그리는 Anatomy에도 실제 구현과 같은 data-slot 이름을 붙여 무엇을 가리키는지 코드에서 읽히게 한다.
  • 같은 방향에 놓인 번호 마커는 하나의 축에 정렬하고 안내선 길이만 서로 다르게 한다. 대상마다 마커 높이가 몇 px씩 어긋나면 번호가 줄을 잃는다. 마커는 도식 바깥에 두어 실제 요소 위로 올라오지 않게 한다.
  • 글자만 담은 요소는 박스가 남은 공간까지 차지할 수 있으므로 번호선의 기준을 박스가 아니라 글자가 실제로 그려진 범위로 삼는다. flex-1이나 block으로 늘어난 Label과 Value가 여기에 해당한다.
  • Field는 Container 안쪽으로 들어가 글자 또는 글자가 놓이는 자리를 가리킨다. 한 줄 입력 요소는 박스가 Container 안쪽을 거의 다 채우므로 박스를 그대로 쓰면 번호선이 Container의 border에 닿아 끊긴 것처럼 보이고, 그러면 입력 영역이 아니라 외곽선을 가리키는 것으로 읽힌다. 세로 범위를 글자가 앉는 한 줄로 좁혀 Prefix나 Label 같은 다른 글자 요소와 같은 자리에서 안내선이 출발하게 한다.
  • 마커 방향은 그 방향에 놓인 다른 요소를 지나가지 않는 쪽으로 고른다. 같은 방향의 마커는 프레임이 계산한 하나의 rail에 정렬되고 안내선 길이만 서로 달라지므로, 안쪽 요소를 가리키는 긴 안내선이 같은 방향의 바깥쪽 요소를 통과한다. 그러면 두 안내선이 한 줄로 이어져 보여 바깥쪽 마커가 안쪽 요소를 가리키는 것으로 읽힌다. 한 행에 여러 요소가 나란히 있으면 안쪽 요소는 위나 아래로 빼고, 그 방향의 맨 끝 요소만 좌우로 둔다.
  • 마커와 안내선은 프레임 바깥에 놓이므로 Anatomy Surface의 여백이 그것을 담을 만큼 있어야 한다. 프레임을 고정 높이 안에 두지 않는 Anatomy는 Surface에 overflow-hidden이 있어 마커가 조용히 잘린다. 마커를 둔 방향마다 안내선 길이와 마커 크기를 합한 만큼 여백을 확보하고, 화면에서 실제로 재어 마커가 Surface 안에 들어오는지 확인한다.
  • 새 컴포넌트의 Anatomy도 같은 방식으로 만든다. 마커에 좌표 class를 직접 주거나 프레임 밖에 두거나 평행선을 span으로 그리면 component-anatomy.test.ts가 pnpm check에서 실패시킨다. 대상을 찾지 못한 마커는 화면에서 사라지므로 개발 중에는 어느 대상을 놓쳤는지 콘솔 경고로 알린다.
  • Anatomy 유형명, 시각 예제와 번호별 요소명 범례는 하나의 Neutral 회색 Surface 안에서 유형명 → 시각 예제 → 범례 순서로 구성한다. 범례를 같은 색의 별도 블록이나 회색 Anatomy 영역 밖의 흰 배경에 분리하지 않는다. Optional은 요소 이름 뒤에 옅은 위계로 표시한다.
  • 구조 설명이 더 필요하면 범례 아래 별도 텍스트 블록에 작성한다. 구조와 상태가 겹쳐 복잡해지면 Anatomy Preview를 둘 이상으로 분리한다.
  • 기본 요소와 Optional 요소가 한 Preview에서 같은 대상을 가리키는 것처럼 보이면 Basic anatomy와 Extended anatomy로 분리한다. Basic에는 최소 구조만 표시하고 Extended에는 Basic 번호를 반복하지 않는다. 여러 텍스트 요소를 감싸는 Content container처럼 단일 Label과 구분하기 어려운 그룹 요소는 Extended에서 Container 평행선으로 범위를 표시한다.
  • Anatomy와 구조 검수용 Playground의 콘텐츠는 제품 사례 문구 대신 Label, Right Description, Value / Placeholder처럼 실제 요소 명칭을 사용한다. 제품 맥락의 실제 문구는 Examples와 Usage에서 보여준다.

Anatomy Container 표시

  • Container 번호의 연결선은 실제 Container 내부로 들어가지 않는다.
  • 실제 외곽선과 일정한 간격을 둔 평행선으로 Container 범위를 표시한다. 번호에서 시작한 연결선은 이 평행선에서 끝난다.
  • 번호가 Container의 왼쪽이나 오른쪽에 있으면 외곽과 나란한 수직선을 사용하고, 위나 아래에 있으면 수평선을 사용한다.
  • 평행선은 실제 Container의 높이 또는 너비 범위에 맞추되 외곽선과 붙이거나 겹치지 않는다.
  • Group, List처럼 여러 하위 요소를 묶는 영역도 같은 규칙을 사용한다. 번호는 묶음 바깥에 두고, 연결선은 실제 콘텐츠로 들어가지 않은 채 영역 높이 또는 너비만큼 그린 평행선에서 끝낸다.
  • [ 또는 ]처럼 끝이 꺾인 bracket 형태는 사용하지 않는다.
  • 평행선을 화면에 직접 그리지 않고 공용 AnatomyBoundaryMarker에 대상을 지정한다. 평행선의 길이는 대상의 실제 높이 또는 너비를 따라가고, 외곽선과의 간격과 연결선 길이만 화면 사정에 맞게 조정한다.
  • 같은 방향에 평행선이 여럿 겹쳐 어느 영역을 가리키는지 읽히지 않으면 그중 하나를 반대쪽으로 옮긴다. 간격만 벌려 층을 쌓으면 마커와 다른 안내선이 그 사이에 끼게 된다.