Docs

docs/system/components/admin-header.md

Admin Header

packages/ui/src/admin-header.tsx

관리자 웹의 맨 위 한 줄이다. 왼쪽에 시스템을 알리는 로고가 서고 오른쪽에 화면과 상관없이 늘 같은 자리를 지키는 Utility와 로그인한 사람이 선다. 가운데는 비워 둔다.

역할과 경계

  • AdminHeader는 Container와 Logo, Utility 넷, 로그인한 사람을 소유한다. 한 화면에 하나만 둔다.
  • 관리자 웹에서만 쓴다. 모바일 화면의 맨 윗줄은 app-header.md가 맡는다. 두 헤더를 한 화면에서 함께 쓰지 않는다.
  • 이 줄은 좌측 메뉴의 오른쪽에서 시작한다. 가로 전체에 두면 흰 헤더와 짙은 레일이 맞붙어 한 화면이 위아래로 잘려 보인다. 그 배치는 관리자 레이아웃이 소유한다.
  • 화면의 이름을 말하지 않는다. 지금 보고 있는 화면의 경로와 이름은 본문의 맨 위 줄이 맡는다(Page Header, 아직 초안이다).
  • 좌측 메뉴를 모른다. 메뉴가 접혀 헤더가 왼쪽 끝까지 늘어났는지만 leadingInset 한 값으로 받는다. Side Navigation은 아직 초안이며, 이 컴포넌트는 그것이 확정되기 전에도 혼자 선다.
  • Utility 자리에 서는 버튼은 button.md가 소유한다. AdminHeader는 자기 버튼을 따로 만들지 않는다.
  • 읽지 않은 수 배지는 notification-badge.md가, 권한 표시는 badge.md가 소유한다.
  • 아이콘의 Line과 Fill 선택 규칙은 icon.md가 소유한다.
  • 구성 요소를 부르는 이름은 vocabulary.md를 따른다. 로고와 Utility를 감싸는 요소는 실제 시각 Surface를 갖는 Container다.

AppHeader와의 경계

겉모습이 닮아 보여도 서로 다른 컴포넌트다. 셋이 갈린다.

가르는 축 Admin Header App Header
쓰는 자리 PC의 관리자 웹. lg(1024px)까지만 대응한다 모바일 화면. 375px이 기준이다
제목 갖지 않는다. 화면의 이름은 본문의 맨 위 줄이 말한다 필수다. h1으로 그리며 감출 때도 지우지 않는다
가로 범위 좌측 메뉴의 오른쪽에서 시작한다 화면 가로 전체를 쓴다

제목을 갖지 않는 것이 가장 큰 차이다. 관리자 웹은 왼쪽에 늘 선 메뉴가 어느 화면인지 이미 알리고 있고, 본문의 맨 위 줄이 경로와 이름을 다시 말한다. 헤더까지 이름을 말하면 한 화면에 같은 이름이 세 번 선다.

높이 56px이 같은 것은 두 헤더가 같은 규칙을 공유한다는 뜻이 아니다. 둘 다 Control을 담는 Container이고 그 안에 32~40px 버튼이 서야 한다는 조건이 같아서 값이 같아졌을 뿐이다.

Anatomy

  1. Container: 모든 내부 요소를 감싸며 높이와 좌우 여백, 배경과 아래 경계선을 소유한다.
  2. Logo: 필수 요소다. 시스템을 알리는 그림이며 누르면 첫 화면으로 간다.
  3. Utility: 필수 요소다. 알림·설정·조직도 셋이 서로 붙어 한 덩이로 선다.
  4. 로그인한 사람: 필수 요소다. 이름과 아이디, 권한 Badge를 한 묶음으로 갖는다.
  5. 로그아웃: 필수 요소다. 로그인한 사람의 오른쪽에 선다.

자리의 고정 순서는 Leading inset(선택) → Logo → Utility → 로그인한 사람 → 로그아웃이며 뒤의 셋은 오른쪽 묶음 안에 든다.

선택 요소는 둘뿐이다. 왼쪽 모서리를 비우는 Leading inset과 알림 버튼 안의 읽지 않은 수 배지다.

Properties

  • logoElement: 필수다. 시스템을 알리는 그림이다. 높이는 헤더가 정하고 폭은 그림의 비율이 정한다.
  • systemName: 필수다. 로고 그림의 대체 텍스트가 아니라 로고 링크의 이름이다. 환경설정이 소유하는 시스템명이 온다.
  • logoHref: 로고를 눌렀을 때 가는 첫 화면이다. 기본값 #.
  • user: 필수다. { name, id, role } 셋을 받는다. 인증이 소유하는 값이다.
  • unreadCount: 읽지 않은 알림 개수다. 주지 않으면 배지가 서지 않는다. 없을 때 0을 넘기지 않는다 — 배지가 0으로 선다.
  • onUserClick: 로그인한 사람을 누를 때 할 일이다. 주지 않으면 누를 수 없는 글자로 남는다.
  • leadingInset: false | true, 기본값 false. 왼쪽 모서리를 헤더 바깥이 쓰고 있을 때 켠다.
  • utilityTooltip: Utility 버튼을 감싸 이름을 띄우는 자리다. 주지 않으면 버튼이 그대로 선다.
  • State: 헤더 자체는 상태를 갖지 않는다. Hover, Pressed와 Focus visible은 Utility 버튼과 로고 링크, 누를 수 있을 때의 로그인한 사람이 갖는다.

Utility 넷은 Property가 아니다. 이름과 순서를 컴포넌트가 가지며 쓰는 쪽이 바꿔 끼울 수 없다. 까닭은 아래 「Utility 넷은 컴포넌트가 갖는다」가 갖는다.

높이

56px 한 값으로 고정한다. 읽지 않은 수 배지가 있든 없든, 로그인한 사람을 누를 수 있든 없든 같다.

interaction.md의 공통 Control Height 중 XXLarge와 값이 같지만 그 규칙을 따르는 것은 아니다. 헤더는 Control이 아니라 Control을 담는 Container이며 값이 같은 것은 우연이다.

높이를 내용에 맡기지 않는 이유는 화면 이동 때문이다. 관리자 화면은 헤더와 좌측 메뉴를 그대로 두고 본문만 갈아 끼우므로, 헤더가 늘었다 줄었다 하면 그 아래 본문 전체가 위아래로 밀린다.

  • 좌우 여백은 16px이다. interaction.md의 「화면 좌우 여백」을 쓰지 않는다 — 그 token의 default는 모바일 구간의 값이고 wide는 태블릿 분기점부터 쓰는 값인데, 관리자 웹은 lg까지만 대응하므로 그 축에 들지 않는다. 헤더 자신의 값이다.
  • 본문이 길어져도 이 줄은 눌리지 않는다. 높이를 양보하지 않는 것이 규칙의 일부다.
  • 아래 1px oe-border-secondary 선은 늘 있다. AppHeader처럼 스크롤에 따라 색을 바꾸지 않는다 — 관리자 웹은 본문이 자기 안에서 스크롤하고 헤더 아래로 들어가지 않으므로, 가려지는 순간이라는 것이 없다.

로고의 높이는 헤더가 정한다

로고는 28px이다. 56px 안에서 위아래로 14px씩 남는다. 폭은 받은 그림의 비율이 정한다.

  • 화면이 크기를 직접 적지 않는다. 화면마다 적게 두면 헤더마다 값이 갈린다. AppHeader가 좌우 자리의 아이콘 크기를 자기가 정하는 것과 같은 규칙이다.
  • 크기를 바꿀 때는 이 줄과 admin-header.tsx의 LOGO_CLASS 한 곳만 고친다.
  • 그림은 쓰는 쪽이 넣는다. 테마 설정에서 등록하는 값이므로 컴포넌트가 기본 그림을 갖지 않는다.

링크의 이름을 그림에 맡기지 않는다. 무엇이 들어올지 쓰는 쪽이 정하는 자리이므로 systemName을 받아 링크에 직접 단다. 대체 텍스트가 빈 그림이 들어와도 링크에 이름이 없어지지 않는다.

로고를 누르면 첫 화면으로 간다. 그 화면은 아직 만들지 않았으므로 logoHref의 기본값이 자리 표시 링크(#)다.

Utility 넷은 컴포넌트가 갖는다

알림·설정·조직도·로그아웃 넷이며 이름과 순서를 이 컴포넌트가 갖는다. 자리를 열지도 목록을 받지도 않는다(2026-10-06 결정. docs/process/open-questions.md의 「관리자 레이아웃에서 뽑은 네 초안」에서 옮겨 왔다).

이 넷은 화면마다 달라지는 내용이 아니라 관리자 웹이 한 시스템으로 읽히기 위해 어느 화면에서나 같은 것이 같은 자리에 서야 하는 묶음이다. 자리를 열거나 목록을 받으면 화면마다 순서와 개수가 갈릴 수 있고, 그 어긋남을 컴포넌트가 막을 길이 없다.

bottom-navigation.md가 항목 목록을 받는 것과 반대 방향의 결정이다. 그쪽은 항목이 제품마다 다르고 폭을 균등하게 나누는 규칙만 컴포넌트가 가지면 되는데, 여기는 항목 자체가 규칙이다.

  • 로그아웃만 셋과 다른 자리에 선다. 나가는 동작이라 로그인한 사람과 붙어 읽혀야 하고, 셋과 같은 덩이에 넣으면 보는 일과 나가는 일이 한 덩이가 된다.
  • 셋은 서로 붙여 한 덩이로 만든다. 아이콘만 있는 버튼이 한 도구 모음으로 서는 자리의 규칙이며 interaction.md의 「나란히 선 버튼 사이」가 소유한다. 버튼 상자가 아이콘보다 큰 정사각형이라 버튼 자체의 여백이 이미 셋을 갈라 놓는다.
  • 누르면 무엇이 열리는지는 아직 정하지 않았다. 열 것이 정해지면 그때 누르는 길을 받는다.
  • 시스템마다 넷이 달라지는 사례가 실제로 확인되면 자리를 열지 않고 목록을 받는 쪽으로 넓힌다. 순서와 개수의 규칙을 컴포넌트가 계속 갖기 위해서다.

툴팁은 밖에서 받는다

Utility는 아이콘만 있는 버튼이므로 이름을 띄우는 툴팁이 붙는다. 그 툴팁은 컴포넌트가 갖지 않고 utilityTooltip으로 받는다.

공용 Tooltip이 아직 시스템에 없기 때문이다. 후보는 sandbox의 화면 후보를 썼고, packages/ui의 컴포넌트가 화면 후보에 의존할 수는 없다. 그래서 감싸는 자리만 밖에 열어 두었다.

  • 주지 않으면 버튼이 그대로 선다. 이름은 aria-label이 늘 갖고 있으므로 툴팁이 없어도 그 버튼이 무엇인지 화면 낭독기는 읽는다. 툴팁이 이름의 유일한 길이 아니다.
  • 툴팁을 주는 화면은 좌측 메뉴가 쓰는 것과 같은 구현을 넘긴다. 한 화면 안에서 툴팁이 두 벌로 갈리지 않게 한다.
  • 공용 Tooltip이 들어오면 이 Property는 사라지고 헤더가 직접 감싼다. 그때까지의 임시 이음매다.

왼쪽 모서리

좌측 메뉴가 접히면 헤더가 왼쪽 끝까지 늘어나고, 그 모서리는 헤더 바깥에 고정된 여닫기 버튼이 쓴다. leadingInset을 켜면 그만큼을 비워 로고가 그 버튼 위에 겹치지 않게 한다.

  • 비우는 폭은 36px이다. 여닫기 버튼의 32px 네모(공통 Control Height의 Small)에 4px을 더한 값이며, Container의 gap 8px이 뒤에 더해져 버튼과 로고 사이가 12px로 남는다. 같은 값으로 두면 둘이 붙어 보이고, 더 벌리면 로고가 왼쪽 여백선에서 눈에 띄게 멀어진다.
  • 폭을 쓰는 쪽에 맡기지 않는다. 그 자리에 서는 것은 헤더 바깥의 버튼이지만, 비울 폭은 헤더가 자기 여백과 함께 계산해야 하는 값이다. 자리를 열어 두면 36px이 화면으로 넘어가 화면마다 값이 갈린다.
  • 비운 자리는 빈 칸이므로 화면 낭독기에 읽히지 않는다.
  • 여닫기 버튼 자체는 이 컴포넌트가 갖지 않는다. 화면에 하나뿐이고 왼쪽 맨 위 한 자리를 지켜야 하므로, 레일 안과 헤더 안에 따로 두면 접을 때 하나가 사라지고 다른 하나가 생겨서 유지되는 것이 아니라 새로 만들어지는 것처럼 보인다. 그 버튼은 Side Navigation이 확정될 때 그쪽으로 간다.
  • 현재 상태는 data-leading-inset으로 드러난다.

폭

관리자 웹은 lg(1024px)까지만 대응한다. 최소 폭이 1024px이고 그보다 좁아지면 화면을 다시 짜지 않고 가로로 스크롤한다. 규칙은 quality.md가 소유한다.

  • 이 헤더는 태블릿과 모바일 구간을 설계하지 않는다. 좁은 폭에서 Utility를 접어 넣거나 로고를 줄이는 동작이 없다.
  • 내용이 양 끝에 붙고 가운데가 비어 있으므로, 폭이 늘어나도 비는 자리만 넓어진다. 로고와 오른쪽 묶음의 모습은 어느 폭에서나 같다.
  • 좌우 끝이 만날 만큼 좁아지는 폭은 대응 구간 밖이다.

Guidelines

관리자 웹의 맨 윗줄에만 쓰기

  • 관리자 화면마다 직접 세우지 않고 관리자 레이아웃이 한 번 세운다. 그래야 헤더를 한 번 고칠 때 화면마다 찾아다니지 않는다.
  • 한 화면에 하나만 둔다.
  • 모바일 화면에는 쓰지 않는다. 그 자리는 app-header.md가 맡는다.

무엇을 넘기고 무엇을 넘기지 않기

  • 넘기는 것은 밖이 소유하는 값뿐이다. 로고 그림과 시스템명은 환경설정이, 로그인한 사람은 인증이, 읽지 않은 개수는 알림이 소유한다.
  • 권한에 따라 목록과 통계의 범위가 갈리는 화면은 헤더에 선 사람과 그 범위가 같은 사람을 가리켜야 하므로 user를 직접 넘긴다.
  • 읽지 않은 것이 없으면 unreadCount를 넘기지 않는다. 0을 넘기면 배지가 0으로 선다.
  • Utility 넷은 넘기지 않는다. 바꿔 끼울 수 있는 값이 아니다.

로그인한 사람을 선으로 가르지 않기

  • 아이콘 셋과 로그인한 사람 사이는 여백만으로 갈라 둔다. 헤더 전체를 세로로 자르는 선은 나누는 힘이 너무 세서, 성격이 다를 뿐 같은 오른쪽 묶음인 둘을 서로 다른 영역처럼 보이게 했다.
  • 12px 여백이면 둘이 다른 성격이라는 것은 이미 읽힌다.

로그인한 사람을 누를 수 있게 만드는 자리

  • 제품에서는 누를 일이 없다. 기본은 누를 수 없는 글자다.
  • 권한에 따라 화면이 갈리는 자리에서 그 권한을 갈아 끼워 보려고 onUserClick을 넘긴다.
  • 누를 수 있게 만들면 그 묶음의 접근 가능한 이름이 「이름 권한. 눌러서 할 일」이 된다. 이름만 읽히면 눌러서 무엇이 되는지 전달되지 않는다.

Specification

값은 admin-header.tsx가 소유한다.

Container

  • 높이 56px, 좌우 16px, 자리 사이 8px.
  • 면은 oe-background-primary, 아래 1px oe-border-secondary.
  • 화면 위에 머문다(sticky). 본문보다 위에 서고 왼쪽 모서리에 고정된 여닫기 버튼보다는 아래다 — 헤더가 그 버튼을 덮으면 접은 메뉴를 다시 펼 길이 없다.

Logo

  • 높이 28px, 폭은 그림의 비율. 뒤에 8px을 더 둔다.
  • Focus는 interaction.md의 유형 3을 쓰고 모서리는 2px이다. 그림이 거의 네모라 큰 모서리를 주면 Focus 선이 그림과 어긋나 보인다.

Utility

  • 공용 Button의 ghost를 tone="neutral"로, 크기는 Small(32px)로 쓴다. 헤더 전용 버튼을 따로 만들면 tone과 Hover, Focus 규칙이 두 벌로 갈린다.
  • 아이콘은 20px이다. 버튼이 가져오는 크기 단계의 16px을 쓰지 않고 헤더가 자기 자리 안에서 정한다. 32px 네모 안에서 16px은 작게 읽히고, 왼쪽 모서리의 여닫기 버튼도 같은 20px이라 버튼 상자가 같은데 그림만 작으면 크기 차이가 의도가 아니라 어긋난 것으로 보인다.
  • 셋 사이에 간격을 두지 않는다. 로그아웃은 오른쪽 묶음의 4px 간격을 쓴다.
  • 이름은 aria-label이 갖는다. 읽지 않은 개수가 있으면 「알림, 읽지 않음 N개」가 된다 — 모양만으로는 낭독기가 읽지 않은 것이 있다는 사실에 닿지 못한다.
  • 읽지 않은 수 배지는 알림 버튼 안에서 아이콘 오른쪽에 나란히 선다. 아이콘 모서리에 얹지 않으므로 자리를 좌표로 잡을 일이 없고, 버튼이 갖고 있는 gap이 둘 사이를 벌린다. 배지가 들어오면 그 버튼만 넓어지는데, 셋 가운데 알림만 넓어지는 것이 신호의 일부다.
  • 배지는 테두리를 두지 않는다(stroke={false}). 아이콘에 얹히지 않아 배경과 겹치는 자리가 없다.

로그인한 사람

  • 이름 14px font-medium oe-foreground-primary, 아이디 12px oe-foreground-tertiary, 권한은 neutral tonal Badge.
  • 자기 왼쪽에 12px을 둔다. 오른쪽 묶음의 4px에 더해지는 값이다.
  • 권한 Badge는 1px 내려앉는다. 글자와 가운데를 맞추면 배지가 위로 올라 보이고 2px을 내리면 이번에는 내려가 보인다. 여백 대신 옮기는 이유는 가운데 정렬이 여백만큼 다시 끌어올려 절반만 내려가기 때문이다.
  • onUserClick을 받으면 모서리가 공통 Control Radius이고 Hover에 oe-interaction-hover-subtle, Focus는 유형 3이다. 좌우로 4px을 내어 주면서 같은 값을 바깥으로 당겨, 여백이 생겨도 이름의 시작점과 권한의 끝점이 누를 수 없는 상태와 같은 자리에 남는다.
  • span에 role="button"을 주므로 Enter와 Space를 직접 받는다. native button이 아니라 브라우저가 대신 눌러 주지 않는다.

현재 정의하지 않은 항목

  • Utility를 눌렀을 때 열리는 것. 알림 목록과 설정, 조직도가 무엇으로 열리는지(팝오버·레이어·화면 이동) 정하지 않았다. 지금은 누르는 길을 받지도 않는다.
  • 로그인한 사람을 눌렀을 때 열리는 메뉴. 제품의 계정 메뉴를 만들지 않았다. onUserClick은 권한을 갈아 끼워 보는 자리에만 쓴다.
  • 여러 시스템을 오가는 자리. 로고 옆에서 시스템을 바꾸는 선택을 두지 않았다.
  • 검색. 헤더에 전역 검색을 두지 않았다. 지금 검색은 좌측 메뉴 안에 있다.
  • 태블릿과 모바일 폭. 관리자 웹이 lg까지만 대응하므로 설계하지 않았다.
  • 공용 Tooltip. 시스템에 없어 Utility의 툴팁을 밖에서 받는다. 들어오면 utilityTooltip은 사라진다.