7장 계층과 작업 순서

화면은 Foundation/Token → Component → Pattern → (선택) Template → Page/Product 순서로 쌓습니다. 아래 계층이 값과 외형을 정하고 페이지는 조립만 하며, 역순으로 만들면 값이 흩어져 다시 모을 수 없습니다.

왜 필요한가

페이지를 만들다 보면 필요한 색이나 간격을 그 자리에 바로 적고 싶어집니다. 한 번은 빠릅니다. 그러나 같은 값이 여러 페이지에 흩어지면 다시 모을 방법이 없습니다.

Leysys는 이 비용을 실제로 치렀습니다. 2026-04 KST, 한 제품 저장소의 페이지들이 style="background-color: #fff"처럼 색을 직접 적고 있었습니다. 토큰을 거치지 않았으니 다크 모드로 바꿔도 이 색은 따라오지 않았습니다. 고치는 데 650개 파일에서 1,753곳을 일괄 치환해야 했습니다. 패턴 14개를 만들면서 각자 inline style을 복사해, 근거 없는 임시 값(ad-hoc)이 260건으로 늘어난 일도 있었습니다.

AI 에이전트와 일하면 이 문제가 커집니다. 에이전트는 주변 코드를 근거로 삼기 때문에, 잘못된 값 하나가 비슷한 화면마다 복제됩니다. 그래서 순서를 규칙으로 고정했습니다. 아래 계층이 확정된 뒤에 위 계층을 만들고, 페이지에서 먼저 값을 만드는 역순 작업을 하지 않습니다.

다섯 계층

Foundation / Token → Component → Pattern → optional Template → Page / Product

계층	맡는 것	예
Foundation / Token	색, 타이포그래피, 간격, 밀도 같은 원자 규칙과 값	--e-bg-neutral-minimal, --e-element-height-md
Component	하나의 UI 책임과 공개 구조. 높이, 안쪽 여백, 테두리, 포커스, 상태	e-button, ECard
Pattern	여러 컴포넌트의 반복 가능한 조합과 상호작용	결재 흐름, 목록 작업 화면
Template (선택)	여러 패턴과 컴포넌트를 route·업무 데이터 없이 완성 화면으로 묶음	대시보드, 일정 달력
Page / Product	route, API, 권한, 세션, 업무 데이터와 저장	제품 저장소의 화면

의존은 한 방향입니다. 위 계층은 아래 계층을 쓰고, 아래 계층은 위 계층을 모릅니다. 헤더, 사이드바, 페이지 여백, 블록 간격 같은 관계는 패턴과 스타터(starter, 제품이 설치해 쓰는 화면 골격)가 정합니다. 페이지는 route 데이터와 문구를 넣고 Tailwind로 배치만 합니다.

Template은 선택 계층입니다. 여러 패턴을 route와 업무 데이터 없이 완성 화면으로 조합했고, 그 화면이 실제로 재사용될 때만 둡니다. 현재는 대시보드와 일정 달력 템플릿이 EDS와 MDS에 각각 있습니다. 필요 없으면 Pattern에서 Page로 바로 갑니다. Template을 새 컴포넌트 묶음이나 두 번째 패턴 계층으로 쓰지 않습니다.

핵심 규칙

1. 페이지는 컴포넌트, 패턴, Tailwind 유틸리티만으로 만듭니다. 값을 직접 적거나(하드코딩), inline style=을 쓰거나, Vue 파일에 <style>을 두지 않습니다. 색과 크기는 토큰을 거치고, 레이아웃과 간격은 Tailwind가 맡습니다. 굵기 유틸리티(font-*)는 타이포그래피 역할 클래스 위에서만 씁니다(예: e-body-sm font-medium).
2. 토큰과 클래스는 컴포넌트 계층에서만 만듭니다. 특정 페이지나 패턴만을 위한 토큰과 클래스는 만들지 않습니다.
3. 패턴은 새 토큰과 클래스를 하나도 만들지 않습니다. 기존 컴포넌트와 Tailwind 레이아웃만으로 조합합니다.
4. 부족한 것은 재사용할 수 있는 형태로 먼저 정착시킵니다. 페이지 작업 중 패턴이 모자라면 페이지 안에 임시로 만들지 않고 패턴 계층(pattern-app/*, m-pattern-app/*)에 만듭니다. 컴포넌트가 모자라면 선도 디자인 시스템(shadcn/ui, Nuxt UI, Primer)과 헤드리스 프리미티브(Reka UI, Base UI, Radix, Headless UI)의 공식 API를 참고해 컴포넌트 계층에 만듭니다.
5. 재사용할 수 있는 결함은 정본에서 고칩니다. 제품마다 덮어쓰는 CSS나 !important로 가리지 않습니다.

역할 분담

역할	담당	예
레이아웃, 간격, 반응형	Tailwind CSS	flex gap-4 p-6 md:grid-cols-2
컴포넌트 외형	디자인 시스템 CSS	e-button e-button-primary-bold e-button-md
색, 타이포그래피, 크기 체계	디자인 시스템 토큰	var(--e-bg-neutral-minimal), e-body-md
접근성, 키보드, ARIA	Reka UI (제품에서)	스타일 없는 헤드리스 프리미티브

디자인 시스템 CSS는 순수 CSS입니다. Tailwind 전용 문법을 쓰지 않으므로 Tailwind 없이 복사해도 동작합니다. Tailwind는 기본 설정을 바꾸지 않고, 추가만 허용합니다. 헤드리스 프리미티브(headless primitive)는 동작과 접근성만 제공하고 모양은 정하지 않는 라이브러리입니다. 그래서 프리미티브를 바꿔도 CSS는 그대로입니다.

실제 예

버튼 두 개

<!-- 하지 않는 것: 값이 페이지에 박혀 테마와 다크 모드가 따라오지 못합니다 -->
<div style="display: flex; justify-content: flex-end; gap: 8px">
  <button style="background: #0075ff; color: #fff; height: 32px">저장</button>
</div>

<!-- 하는 것: 배치는 Tailwind, 외형은 컴포넌트 클래스 -->
<div class="flex justify-end gap-2">
  <button class="e-button e-button-md e-button-neutral-subtle">취소</button>
  <button class="e-button e-button-md e-button-primary-bold">저장</button>
</div>

두 번째 코드는 색, 높이, 모서리 값을 하나도 적지 않습니다. 팔레트, 다크 모드, 밀도 프리셋이 바뀌면 컴포넌트 토큰을 따라 함께 바뀝니다.

결재 흐름: 패턴이 CSS를 가질 수 없을 때

결재 흐름 화면에는 단계마다 의견과 상태가 붙는 세로 진행 표시가 필요했습니다. 처음에는 이름에 결재 (approval)라는 업무 어휘가 들어간 Stepper 클래스로 만들었습니다. 그러나 패턴은 CSS를 소유할 수 없고, 디자인 시스템 컴포넌트 이름에는 업무 어휘를 넣지 않습니다. 그래서 둘로 나눴습니다.

• 표시 능력은 Stepper 컴포넌트가 가집니다. 이름은 업무와 무관한 .e-stepper-rail-*입니다.
• 결재라는 조합은 pattern-app/approval-workflow 패턴이 가집니다. 이 패턴 파일에는 <style>도 inline style도 없습니다.

이렇게 나누면 결재가 아닌 화면도 같은 세로 진행 표시를 쓸 수 있습니다.

경계와 예외

• 디자인 시스템 문서 앱. Leysys Design 문서 사이트의 셸과 타이포그래피 시연 페이지는 제품 화면이 아니라 디자인 시스템 자체의 메타 UI라 규칙 1의 범위 밖입니다. 이 예외를 제품 route로 복사하지 않습니다.
• 편차는 알림으로 다룹니다. 정본과 다른 조합, 이름, 간격은 위치와 근거, 규칙 ID가 있는 내부 알림(alert)으로 보고합니다. 의도한 응용과 실험, 제품별 예외는 허용합니다. 작업을 자동으로 막는 것은 컴파일·타입 오류, 순환 의존, 패키지 무결성 실패, 실행으로 재현한 runtime·접근성·보안 실패 같은 실제 고장뿐입니다.
• 유틸리티가 컴포넌트 규칙을 이깁니다. Tailwind v4의 cascade layer 순서에서 유틸리티는 컴포넌트 규칙보다 뒤에 있어, 명시도와 무관하게 이깁니다. 그래서 e-card-body에 p-*를 덧대면 카드의 크기 체계가 무너집니다. 밀도를 바꾸려면 e-card-sm, e-card-lg 같은 크기 단계를 고릅니다.
• 구조 컴포넌트의 이름. App, Shell, Panel, Card처럼 화면 구조를 나누는 컴포넌트의 이름 규칙은 13장에서 다룹니다.

정리

• 순서는 Foundation/Token → Component → Pattern → (선택) Template → Page/Product이고, 의존은 한 방향입니다.
• 페이지는 조립만 합니다. 값은 토큰, 외형은 컴포넌트, 배치와 간격은 Tailwind가 맡습니다.
• 토큰과 클래스는 컴포넌트 계층에서만 만들고, 패턴은 새 토큰과 클래스를 만들지 않습니다.
• 모자란 패턴과 컴포넌트는 페이지 안이 아니라 정본에 재사용 가능한 형태로 먼저 만듭니다.
• 정본과의 편차는 알림으로 기록하고, 실제 고장만 작업을 막습니다.

정본

• leysys-design AGENTS.md(파리티 미러 CLAUDE.md) 「핵심 7대 룰」, 「SSOT 운영 강제 룰」 — 계층 순서와 페이지·패턴 규칙
• leysys-design docs/decisions/STRUCTURAL-UI-VOCABULARY-2026-08-16.md — 설계 계층과 Template의 정의
• leysys-design docs/specs/CSS-ARCHITECTURE.md — 역할 분담과 Tailwind 사용 정책
• leysys-design docs/specs/PAGE-LAYOUT.md — 계층별 소유권과 금지 조립
• leysys-design docs/process/COMPONENT-PRINCIPLES.md — 작업 순서와 실제 위반 사례
• leysys-design docs/decisions/SSOT-POLICY-ADVISORY-ENFORCEMENT-2026-08-17.md — 편차를 알림으로 다루는 기준