16장 패턴과 화면 구성
패턴은 기존 컴포넌트와 Tailwind 유틸리티만으로 반복되는 화면 구성을 정해 둔 것입니다. 같은 역할의 정보와 동작은 제품이 달라도 같은 패턴을 쓰고, 제품 고유의 기능 차이는 그대로 둡니다.
왜 필요한가
컴포넌트(15장)가 같아도 배치가 다르면 사용자는 화면마다 조작을 다시 배웁니다. 실제로 문서의 목록 예제와 콘솔 Starter(새 제품이 복사해 시작하는 화면 묶음)의 목록은 같은 Card class를 쓰면서도 따로 관리되었고, 조회 조건·동작 버튼·페이지네이션의 자리는 어디에도 정해져 있지 않았습니다. AI 에이전트는 가까운 화면을 따라 하므로 이런 차이는 빠르게 늘어납니다. 그래서 반복되는 구성을 패턴으로 한 번 정하고, 제품은 그것을 복사해 씁니다.
원칙 / 모델
계층에서의 위치
text
Foundation / Token → Component → Pattern → optional Template → Page / Product패턴(Pattern)은 여러 컴포넌트를 반복 가능한 상호작용과 구성으로 묶습니다. 템플릿(Template)은 여러 패턴을 route(화면 주소)와 업무 데이터 없이 완성 화면으로 묶는 선택 계층이고, 페이지(Page/Product)는 route·API·권한·세션·업무 데이터와 저장을 소유합니다. 계층 순서는 7장에서 다룹니다.
- 패턴은 컴포넌트와 Tailwind 유틸리티(레이아웃·간격)로만 만듭니다. 새 토큰, 새 class, 패턴 전용 CSS를 만들지 않습니다. 토큰과 class는 컴포넌트 계층에서만 정의합니다.
- 화면 작업 중 필요한 패턴이 없으면 페이지 안에 임시로 짜지 않고, EDS는
pattern-app/, MDS는m-pattern-app/에 재사용할 수 있는 패턴으로 먼저 만듭니다. 한 패턴은 한 진영의 컴포넌트만 씁니다. - 템플릿은 완성 화면이 실제로 재사용될 때만 둡니다. 지금은
DashboardTemplate과ScheduleCalendarTemplate이 있습니다. 필요 없으면 패턴에서 페이지로 바로 갑니다. - 패턴은 화면 영역과 구성 순서를 소유합니다. 데이터, 요청, 선택 상태, 업무 동작은 제품이 소유합니다.
문서 페이지의 황금 템플릿
컴포넌트 문서 페이지도 하나의 틀(황금 템플릿)을 따릅니다. 대표 규칙은 다음과 같습니다.
- 페이지 제목(H1)은 머리글만 갖고, 본문에서 다시 쓰지 않습니다.
- 선택할 수 있는 값을 다루는 섹션은 한 줄 설명, 선택 control, 시연 하나, 복사할 코드를 모두 갖춥니다.
- Vue 코드와 HTML 코드는 같은 시연 상태에서 계산합니다. API는 Vue 탭(Props → Emits → Slots)과 Class 탭으로 나눕니다.
- 상태 이름은 CSS pseudo-class를 따라 enabled → disabled → hover → focus → active 순서로 씁니다.
- 섹션의 id·제목·순서가 목차의 정본이라, 목차를 따로 관리하지 않습니다.
실제 예
목록
EDS 목록의 기본 구성은 registry 패턴 ETableCard가 소유합니다.
text
ETableCard
├─ Header(선택): 제목·설명
├─ Body: 영역 사이 16px
│ ├─ 조회: 검색 행 → 조회 조건 행
│ ├─ 목록 동작 행
│ └─ 표 + 페이지네이션
└─ Footer(선택): 카드 범위의 완료 동작- 동작 행은 하나이고 선택 전후로 모양이 바뀌지 않습니다. 삭제 같은 일괄 동작은 시작 쪽에 늘 보이고, 선택이 없으면 비활성입니다. 생성·업로드는 끝 쪽입니다. 예전에는 행을 고르면 동작 행이 통째로 바뀌었는데, 선택 전에는 무엇을 할 수 있는지 알 수 없고 레이아웃이 흔들려 이 방식을 버렸습니다.
- 선택한 수는 페이지네이션 행의 시작 쪽에서
role="status"로 알립니다. 「선택 해제」 버튼은 두지 않고 헤더 체크박스가 해제를 맡습니다. - 첫 데이터 열은 대상의 주 식별자(이름·제목)이고, 유형·상태는 그 뒤에 둡니다. 이름을 누르면 상세 시트가 열립니다. 체크박스와 부딪히므로 행 전체 클릭은 쓰지 않습니다.
- 페이지 크기는 20·50·100입니다. 결과가 없으면 페이지네이션을 그리지 않습니다. 16px 간격은 부모의
gap-4가 소유하는 EDS 기본값입니다.
레코드 상세와 변경 이력
상세는 머리글(이름·상태) → 식별 정보 → 탭 순서이고 첫 탭은 「일반」입니다. 사람이 적는 노트·통화·할 일은 ERecordActivity(「노트」 탭), 값의 변경 기록은 ERecordHistory가 맡으며 「변경 이력」은 마지막 탭입니다. 변경 이력은 누가·언제·무엇을·왜 바꿨는지 답합니다.
ts
{
occurredAt: "2026-09-19T07:25:00Z",
actor: { kind: "person", name: "김담당", affiliation: "본사" },
action: "상태 변경",
changes: [{ field: "상태", from: "기회", to: "실주" }],
reason: "경쟁사 선택",
}- 누가 — 이름을 보이고 내부 id는 보이지 않습니다. 이름을 누르면 사용자 카드가 열립니다. 행위 주체는 W3C PROV의 구분을 따라 사람·조직·소프트웨어로 나누고, 소프트웨어는 AI 에이전트·자동화·연동·가져오기로 나눕니다. 모르는 주체를 「시스템」으로 채우지 않고 「알 수 없음」으로 보입니다.
- 언제 — 조직 시간대의 분 단위 절대 시각입니다. 상대 시각은 캡처나 보고서로 옮기면 뜻이 달라져 쓰지 않습니다.
- 무엇을·왜 — 필드의 이전 값과 이후 값, 사유와 상세 사유입니다.
- 기록은 값을 바꾸는 쓰기와 함께 한 번 남기고 고치거나 지우지 않습니다. 기록을 시작하기 전의 이력은 지어내지 않고 기록 시작 시각을 알립니다.
활동 기록의 읽기 전용 표시는 화면 표현일 뿐 권한이 아닙니다. 서버는 행위 주체와 대상을 다시 검증합니다.
권한이 없을 때
권한 없는 화면 주소로 들어오면 다른 곳으로 보내지 않고 그 자리에서 403을 보입니다. 제목은 「접근 권한이 없습니다」, 본문은 「현재 역할로는 이 화면을 볼 수 없습니다. 필요하면 관리자에게 역할 변경을 요청해 주세요.」입니다. 그 역할로는 절대 쓸 수 없는 메뉴는 숨기고, 상태 때문에 막힌 동작은 비활성과 이유를 보입니다. 역할 체계는 22장에서 다룹니다.
CRM 공통 패턴
Zution과 Leyve Center가 같은 고객 관리 화면을 쓰도록 목록, 상세, 상태 변경, 리드 빠른 등록, 파이프라인 보드, 퍼널, 견적 줄 패턴을 design에 먼저 두었습니다. 상태 배지의 색은 상태 값이 아니라 분류가 정합니다. 진행은 info, 성사는 success, 종료는 neutral, 이탈은 warning입니다. 보드에서 카드를 끌어 상태를 바꿀 수 있지만, 끌지 않고도 같은 일을 하도록 카드마다 「상태 변경」 버튼을 둡니다. 상태 기본값과 지표 계산은 CRM 공통 계약이, 저장과 권한은 각 제품이, 화면 합성과 표시 규칙은 design이 소유합니다.
제품 간 일관성
일관성은 모든 제품의 화면을 똑같이 만드는 일이 아닙니다. 같은 대상과 역할에는 같은 용어, 정보의 상대 순서, 탐색·편집·저장·취소 패턴을 씁니다. 기능·권한·업무 대상·청구 주체가 다르면 그 차이를 유지합니다. 사업자 증빙이 있는 상세는 일반 → 증빙 → 계정 순서이고, 증빙이 없는 LeyVote 멤버 상세는 일반 → 계정 → 활동을 유지합니다. 없는 기능을 위해 빈 탭이나 가짜 필드를 만들지 않습니다.
경계와 예외
- 패턴은 데이터·권한·저장을 소유하지 않습니다. 결정이 design에 병합됐다고 제품 채택이나 배포가 끝난 것은 아닙니다.
- 패턴과 다른 배치는 위치·이유·규칙 ID가 있는 알림입니다. 입력 유실, 접근성 실패, overflow 같은 실제 고장만 배포를 막습니다.
- 날짜 중심 원장, 감사 로그, 집계 표는 엔티티 목록이 아닙니다. 「이름이 첫 열」 규칙을 그대로 쓰지 않습니다.
- 템플릿은 두 번째 패턴 계층이 아닙니다.
정리
- 패턴은 컴포넌트와 Tailwind만으로 만들고, 새 토큰·class를 만들지 않습니다.
- 목록은
ETableCard구성을, 상세는 일반 탭에서 변경 이력 탭까지의 순서를 따릅니다. - 변경 이력은 누가·언제·무엇을·왜를 답하고, 권한이 없으면 그 자리에서 이유를 보입니다.
- 같은 역할은 같은 패턴으로 만들고, 제품 고유의 차이는 유지합니다.
정본
leysys-designdocs/decisions/STRUCTURAL-UI-VOCABULARY-2026-08-16.md— 설계 계층과 Template의 범위leysys-designdocs/process/PAGE-GOLDEN-TEMPLATE.md— 컴포넌트 문서 페이지 규칙leysys-designdocs/decisions/CONSOLE-LIST-DEFAULT-PATTERN-2026-09-05.md— EDS 목록 기본 구성leysys-designdocs/decisions/LIST-BULK-ACTION-PLACEMENT-2026-09-11.md— 일괄 동작과 선택 수 위치leysys-designdocs/decisions/LIST-PRIMARY-TITLE-FIRST-2026-09-14.md— 주 식별자 우선 열 순서leysys-designdocs/decisions/RECORD-ACTIVITY-PATTERN-2026-09-13.md— 활동 기록leysys-designdocs/decisions/RECORD-HISTORY-2026-09-24.md— 변경 이력leysys-designdocs/decisions/CRM-COMMON-PATTERNS-2026-09-24.md— CRM 공통 패턴leysys-designdocs/decisions/CROSS-PROJECT-CONSISTENCY-2026-09-23.md— 제품 간 일관성- 접근 역할 체계 — 권한 없음 화면 문구와 행위 주체 라벨