Page Header
packages/ui/src/page-header.tsx
본문의 맨 위 한 줄이다. 헤더와 좌측 메뉴를 뺀 자리의 맨 위에 서며, 지금 보고 있는 화면이 무엇이고 그 화면이 어디에 있는지를 말한다. 탭과 동작 버튼의 자리도 함께 갖는다.
역할과 경계
- 관리자 웹 화면의 머리다. 좌측 메뉴에서 고른 화면이 자기 이름과 경로를 이 자리에서 말한다. 최소 폭은
1024px이며 그보다 좁은 구간을 설계하지 않는다 — quality.md가 「관리자 웹은lg까지만 대응한다」로 정해 둔 범위다. PageHeader는 경로와 제목, 동작 버튼의 자리, 즐겨찾기 별과 설명 아이콘의 자리, 그리고 탭 줄을 놓는 자리를 소유한다. 그 안에 무엇이 서는지는 소유하지 않는다 — 동작 버튼은ReactNode로 받고, 탭은 값과 이름만 받는다.- 상세 화면이 제목 아래 함께 보여 주는 값은 갖지 않는다. 소유자, 생성일, 식별자가 그런 값이다. 이 머리는 각 메뉴의 첫 화면이 공통으로 쓰는 자리이고, 그 값들은 화면마다 다른 대상의 속성이다.
- 탭 줄 자체는 tabs.md가 소유한다. 이 머리는 그 줄을 어디에 놓는지와 줄 아래 선만 갖는다.
Tabs가 그 선을 긋지 않기로 정해 두었고, 머리의 아래 경계선이 그 선이 된다. - 탭을 쓸 때는 쓰는 쪽이
Tabs로 이 머리와 본문을 함께 감싼다. 탭 줄과 그 탭이 여는 칸은 서로를 가리켜야 하는데 칸은 이 머리의 바깥에 있다. 같은 규칙을 tabs.md의 「역할과 경계」가 소유한다. - 나란히 선 동작 버튼 사이 간격은 interaction.md의 「나란히 선 버튼 사이」가 소유한다. 이 머리는 그 값을 자기 자리에 적용할 뿐이다.
- 구성 요소를 부르는 이름은 vocabulary.md를 따른다. 경로는 업계에서 굳은 Breadcrumb 대신
Path로 부른다 — 코드의 property 이름이path이고, 한 컴포넌트 안에서 두 이름을 섞지 않는다.
App Header와의 경계
둘을 한 컴포넌트에 담지 않는다. 둘 다 「화면의 위에 서서 그 화면의 이름을 말하는 줄」이지만 서는 자리와 높이의 규칙이 다르다.
| Page Header | App Header | |
|---|---|---|
| 서는 자리 | 관리자 웹 본문의 머리. 헤더와 좌측 메뉴를 뺀 자리의 맨 위 | 모바일 화면의 최상단 한 줄. 그 위에 아무것도 없다 |
| 높이 | 내용이 정한다. 탭 줄과 설명 아이콘, 동작 버튼이 화면마다 있고 없다 | 56px 한 값으로 고정한다 |
| 제목 | 24px. 화면의 이름이자 그 화면의 <h1> |
16px. 한 줄에서 자른다 |
| 좌우 자리 | 오른쪽 하나뿐이고 동작 버튼이 선다 | 좌우 둘이고 성격이 같은 아이콘 자리다 |
| 경로 | 갖는다 | 갖지 않는다. 뒤로 가는 길이 그 역할을 한다 |
| 스크롤 | 자리에 머문다. 아래 선은 모양이 정한다 | 붙을 수 있고 본문이 아래로 들어가면 선이 나타난다 |
높이가 둘을 가르는 자리다. App Header가 높이를 내용에 맡기지 않는 것은 설명 줄이 있는 화면과 없는 화면을 오갈 때 그 줄이 늘었다 줄면 아래 본문이 위아래로 밀리기 때문이다. Page Header는 반대로 탭 줄과 동작 버튼이 화면마다 달라 한 값으로 묶을 수 없고, 화면을 오가도 본문이 밀리지 않는 자리에 있다.
Anatomy
- Root: 머리 전체를 감싸며 모양(
variant)과 좌우 여백, 아래 경계선을 소유한다. - Path: 첫 화면부터 지금 화면까지의 경로다. 제목보다 먼저 읽히고 제목보다 작고 옅다. 마지막 항목이 지금 보고 있는 화면이다.
- Title: 화면의 이름이며
<h1>이다. 한 화면에 하나다. - Actions (Optional): 제목 오른쪽에 서는 동작 버튼의 자리다. 경로와 제목 두 줄 전체와 나란히 서고 그 높이의 가운데에 놓인다.
- Tabs (Optional): 화면 안을 가르는 탭 줄이다. 머리의 아래쪽에 서고 밑줄이 아래 경계선과 겹친다.
별과 설명 아이콘은 번호를 갖지 않는다. 별은 Title에 딸린 표시이고 설명 아이콘은 Path에 딸린 표시이므로, 저마다 그 요소의 자리 안에 선다.
Properties
path: 필수다. 첫 화면부터 지금 화면까지의 경로이며 마지막 항목이 지금 보고 있는 화면이다. 어느 항목도 링크가 아니다 — 까닭은 아래 Guidelines의 「경로는 링크가 아니다」가 갖는다.title: 필수다. 화면의 이름이며<h1>으로 선다.titleId: 제목에 걸id다. 표처럼 이름이 필요한 요소가aria-labelledby로 이 제목을 가리킬 때 쓴다. 넘기지 않으면id가 붙지 않는다. 쓰는 법은 아래 Guidelines의 「제목을 다른 요소의 이름으로 쓰기」가 갖는다.variant(Style):surface | ghost, 기본값surface.surface는 흰 바탕을 깔고 아래를 선으로 끊는다.ghost는 바탕과 선을 모두 걷는다. 고르는 기준은 아래 Guidelines의 「모양 고르기」가 갖는다.ghost라는 값 이름이 Button의ghost와 뜻이 겹친다. 저쪽은 배경이 없는 버튼이고 이쪽은 면과 선이 없는 머리다. 이름을 고치지 않은 것은 채움 스타일의 값 이름이 저장소에서 셋으로 갈려 있어 한 컴포넌트만 먼저 고치면 갈림이 넷이 되기 때문이다. 미룬 결정은docs/process/open-questions.md의 「채움 스타일 값 이름」이 갖는다.
tabs:{ value, label }[]. 넘기지 않으면 탭 줄이 서지 않는다. 넘기면 머리의 아래 여백이 사라진다 — 탭의 밑줄이 아래 경계선 자리에 겹쳐 앉아야 하기 때문이다.actions:ReactNode. 넘기지 않으면 그 자리를 그리지 않고 제목이 그 자리까지 쓴다. 버튼을 감싸지 않고 Fragment로 그대로 넘긴다 — 사이 간격은 이 자리가 갖는다.favorite:false | true. 넘기지 않으면 별이 서지 않는다.false를 넘기는 것과 넘기지 않는 것이 다르다 —false는 「담겨 있지 않다」이고 넘기지 않는 것은 「담는 자리가 아니다」다.onFavoriteChange: 별을 눌렀을 때 다음 값으로 부른다.description:ReactNode. 넘기지 않으면 경로 끝에 설명 아이콘이 서지 않는다. 넘긴 글은 아직 어디에도 그려지지 않는다 — 아래 「현재 정의하지 않은 항목」이 그것을 갖는다.- State: 없다. 이 머리는 자기 상태를 갖지 않는다. 별의 켜짐과 꺼짐은
favorite이 쥐는 값이고 켜진 탭은Tabs가 쥔다.
Guidelines
모양 고르기
- 본문이 머리 바로 아래에서 통째로 스크롤되는 화면에는
surface를 쓴다. 아래 선이 스크롤되는 자리와 고정된 자리를 가른다. - 본문이 카드 몇 장으로 나뉜 화면에는
ghost를 쓴다. 끊을 자리가 이미 카드의 경계로 있어서 머리의 선까지 더하면 가로선이 두 겹으로 겹친다. - 모양을 고르는 기준은 머리가 아니라 그 아래 본문의 모양이다. 머리만 보고 고르면 같은 화면에서 선이 두 번 그어진다.
ghost를 쓰는 화면은 본문의 위쪽 여백을 좁게 둔다. 머리가 면을 갖지 않으므로 머리의 아래 여백과 본문의 위 여백이 그대로 이어져 한 덩이로 벌어진다.
경로는 링크가 아니다
- 마지막 항목은 누를 곳이 아니다. 지금 보고 있는 화면이므로 눌러서 갈 자리가 없다.
aria-current="page"로 그 사실을 알린다. - 앞선 항목들도 링크로 세우지 않는다. 갈 주소가 아직 없다. 링크로 세우면 눌러도 아무 일이 없는 자리가 눌리는 것처럼 보이고, 포인터와 색이 그 약속을 먼저 한다.
- 앞 항목을 열 때는 그 항목이 가리키는 화면이 실제로 있는지를 먼저 본다. 좌측 메뉴의 묶음 이름은 화면이 아니라 묶음이므로 열 자리가 없는 경우가 있다. 열기로 하면 링크가 되는 항목과 되지 않는 항목이 한 줄에 섞이는 것을 어떻게 알릴지 함께 정한다.
- 경로의 이름은 좌측 메뉴의 묶음 이름을 그대로 쓴다. 헤더에서 들어오는 화면처럼 좌측 메뉴와 맞물리지 않는 자리는 그 화면이 속한 묶음을 적는다.
- 마지막 항목과
title을 같게 둔다. 다르면 경로가 가리키는 자리와 제목이 말하는 자리가 갈린다.
제목 줄의 네 갈래
저장소에서 제목 줄을 가진 화면은 28곳이고, 그 가운데 26곳의 <h1>이 text-2xl font-semibold text-oe-foreground-primary를 글자 그대로 들고 있다. 제목의 단계는 이미 한 값으로 정해져 있다. 이 머리가 새로 정한 값이 아니라 그 값을 그대로 들고 행간과 자간만 더 적는다.
갈리는 것은 제목이 아니라 그 줄의 구조이며 네 갈래다.
| 갈래 | 곳 | 이 API가 받는가 |
|---|---|---|
| 제목만 | 4 | 받는다. path에 한 항목만 넘기면 경로 줄이 그 이름 하나로 선다 |
| 제목 + 아래 설명 | 5 | 받지 못한다. description은 경로 끝의 아이콘으로만 서고 제목 아래에 줄로 서지 않는다 |
| 제목 + 오른쪽 동작 | 5 | 받는다. actions가 그 자리다 |
| 경로 + 제목(+ 탭·동작·별·설명) | 3 | 이 컴포넌트가 그 갈래다 |
- 앞의 세 갈래를 이 컴포넌트로 갈아타는 일은 하지 않았다. 경로가 없는 화면에 경로를 만들어 붙이는 일이 되므로 화면마다 그 화면이 어느 묶음에 속하는지를 먼저 정해야 한다.
- 둘째 갈래를 받으려면 제목 아래 설명 줄을 Property로 열어야 한다. 지금
description이 그 자리가 아니라는 것을 먼저 읽어야 하므로, 열 때는 이름을 가른다.
제목을 다른 요소의 이름으로 쓰기
- 표처럼 이름이 필요한 요소가 이 머리의 제목을 가리킬 때
titleId로id를 준다. table.md의 「표에 이름 붙이기」가 그 기본 길을aria-labelledby로 정해 두었다. - 화면 코드가
<h1>에 직접id를 적는 길을 두지 않았다. 화면마다 손으로 적으면 같은id가 두 번 서는 날이 온다. 값은 화면이 정하되 그 값을 머리에 넘긴다. - 값은 화면의 상수로 한 자리에 둔다. 제목을 그리는 쪽과 그 이름을 가리키는 쪽이 서로를 import 하지 않으므로, 둘이 함께 읽는 자리가 그 값을 갖는다.
즐겨찾기 별 두기
- 별은 제목 옆에 붙는다. 오른쪽 동작 버튼과 달리 이 화면이 다루는 대상을 바꾸는 것이 아니라 화면 자체를 각자 담아 두는 표시다.
- 이름은 켜짐과 꺼짐에서 같은 것을 쓴다. 지금 담겨 있는지는
aria-pressed가 이미 말하므로, 이름까지 바꾸면 상태와 누르면 일어날 일이 뒤섞인다. - 별은 저장을 거치지 않고 누른 즉시 반영한다. 담아 두는 표시는 고르는 값이 아니라 조작이다.
Specification
값은 page-header.tsx가 소유한다.
자리와 여백
- 좌우 24px, 위 16px. 좌우는 관리자 웹 본문의 여백과 같은 값이다 — 머리와 본문의 시작점이 어긋나면 제목과 그 아래 내용이 다른 줄에서 시작한 것으로 보인다.
oe의 여백 토큰은 16px과 40px 둘뿐이라 이 값을 담은 것이 없다. 머리 혼자 쓰는 값이 아니라 관리자 웹 본문이 쓰는 값이므로, 토큰이 생기는 자리도 머리가 아니라 그 레이아웃이다.
- 아래 여백은 탭이 있으면 0, 없으면 20px이다. 탭이 있을 때 0인 것이 규칙이다 — 탭의 밑줄이 아래 경계선 자리에 겹쳐 앉아야 하고, 여백이 남으면 밑줄이 선에서 그만큼 떠서 가로선이 두 줄로 보인다.
- 높이를 고정하지 않는다. 설명 아이콘과 탭 줄, 동작 버튼이 화면마다 있고 없으므로 높이는 내용이 정한다.
- 본문이 스크롤되어도 이 자리는 줄어들지 않는다.
경로
- 글자 12px, 색은
oe-foreground-tertiary. 마지막 항목만oe-foreground-secondary로 한 단계 진하다 — 지금 보고 있는 화면이라 경로 안에서 먼저 읽혀야 한다. - 항목 사이 4px. 꺾쇠는 14px이고 색은
oe-foreground-subtle로 경로 글자보다 한 단계 옅다. 구분 표시이고 읽을 글자가 아니므로 낭독기에 읽히지 않는다. - 꺾쇠와 그 뒤 글자가 한 항목으로 묶여 함께 줄을 넘는다. 묶지 않으면 꺾쇠만 줄 끝에 남는다.
aria-label="현재 위치"를 가진<nav>에<ol>로 선다. 마지막 항목만aria-current="page"를 갖는다.
제목
- 24px 글자가 32px 줄에 서고 자간을 한 단계 좁힌다.
font-semibold에 색은oe-foreground-primary다. - 경로 줄과 제목 줄 사이 6px.
- 자리가 모자랄 때 줄어드는 것은 제목이다. 동작 버튼의 자리는 줄어들지 않는다.
별과 설명 아이콘
- 별은 제목과의 사이 2px에 선다. 나란히 선 버튼 사이의 6px과 갈리는 것은 별이 버튼 묶음이 아니라 제목에 딸린 표시이기 때문이다. Toggle Button의 Ghost를 쓰고 켜지면 아이콘이 Fill로 바뀐다.
- 설명 아이콘은 경로의 마지막 항목 바로 뒤에 선다. 지금 화면의 이름이 나오는 자리이고, 설명은 그 이름을 보충하는 글이기 때문이다.
- 설명 아이콘의 글자색이 Button이 주는 값을 덮어쓴다. Ghost neutral이 주는
neutral-800대신 경로 글자와 같은oe-foreground-tertiary를 얹었다. 이 줄의 어느 것도 먼저 읽혀야 하는 것이 아니기 때문이며, 가리키면Button이 가진 색으로 진해진다. 같은 성격의 아이콘 버튼이 몇 군데 더 나오면Button에 그 단계를 둘지 판단한다 — 미룬 결정은docs/process/open-questions.md가 갖는다. - 아이콘 버튼은 28px이고 경로 글자 줄은 16px이다. 넘치는 만큼을 위아래로 덜어 내어 줄 높이를 글자에 맞춘다 — 그러지 않으면 이 줄만 12px 높아져 제목이 함께 밀린다.
동작 버튼
- 경로와 제목 두 줄 전체와 나란히 서고 그 높이의 가운데에 놓인다. 제목 줄에만 맞추면 버튼 위로 경로 줄만큼이 빈자리로 남는다.
- 버튼 사이 6px. 값과 까닭은 interaction.md의 「나란히 선 버튼 사이」가 소유한다.
- 버튼의 크기 단계는 쓰는 화면이 정한다. 저장소에 쓰인 두 자리는 모두 Small이다.
모양
surface:oe-background-primary면에 아래 1pxoe-border-secondary.ghost: 면과 선을 모두 두지 않는다.- 선을 켜고 끄는 것이 아니라 class 자체를 두고 뺀다. App Header가 선의 색만 바꾸는 것과 갈리는 것은, 그쪽은 한 화면 안에서 스크롤에 따라 바뀌어 1px이 생기고 사라지면 본문이 움직이기 때문이고, 이쪽은 화면마다 한 번 정해져 바뀌지 않기 때문이다.
탭 줄
- 제목 줄 아래 16px에 선다. 모양은 Tabs의
underline이고 줄 아래 선은 머리의 아래 경계선이다. ghost에서도 탭을 둘 수 있으나 그때는 줄 아래 선이 없다. 밑줄만 공중에 뜨므로 탭을 쓰는 머리는surface로 둔다.
현재 정의하지 않은 항목
description의 글이 어디에도 그려지지 않는다. 아이콘만 세우고 누르면 펼쳐지는 자리를 붙이지 않았다. 저장소에 팝오버 컴포넌트가 없어서다 — 글을 띄워 보이는 자산이 아직 없다. 붙일 때는 펼쳐지는 자리가 Tooltip인지 Popover인지, 포인터로 열리는지 눌러서 열리는지, 키보드로 닫는 길을 함께 정해야 한다. 남은 일은docs/process/open-questions.md의 「Page Header의 설명이 아직 그려지지 않는다」가 갖는다.- 세 단계 이상의 경로. 저장소에 쓰인 경로는 모두 두 단계다. 세 단계 이상에서 줄이 넘칠 때 접을지 가운데를 줄일지, 접는다면 무엇을 남길지를 정하지 않았다. 지금은 넘친 항목이 다음 줄로 내려간다.
- 앱 화면에서 쓸 수 있는지. 관리자 웹 화면에서만 쓰고 있으며 앱 화면의 기준을 따로 보지 않았다. 앱은 모바일 뷰가 기준이라 좌우 24px과 제목 24px이 그대로 맞는지, 최상단의 App Header와 이 머리가 한 화면에 함께 설 자리가 있는지를 먼저 정해야 한다.
- 제목 아래 설명 줄. 위 「제목 줄의 네 갈래」의 둘째 갈래를 받지 못한다. 열 때는
description과 이름을 가른다. - 스크롤에 따라 붙는 머리. 이 머리는 자리에 머문다. 본문이 길어질 때 제목과 탭 줄이 위에 붙어 남을지는 정하지 않았다 — 붙이기로 하면 그때 선이 생기고 사라지는 문제가 App Header와 같은 꼴로 돌아온다.
- 동작 버튼이 많을 때. 지금은 버튼이 늘어나면 제목이 먼저 줄어든다. 몇 개를 넘으면 더보기로 접을지, 접는다면 어느 버튼을 남길지를 정하지 않았다.