Playground로 바로 이동
Components

Table

목록 하나를 줄과 칸으로 세우는 표입니다. 한 줄이 한 건이고 열 구성은 쓰는 화면이 정하며, 줄 높이와 칸 여백·머리줄·구분선·고른 줄의 표현을 Table이 소유합니다.

명세 문서 보기

🚩 Playground

Density와 바깥 테두리, 줄 상태를 조합해 실제 목록에서 확인합니다. 정렬 머리글은 눌러 방향이 바뀝니다.

제목처리상태금액
1024에어컨이 멈췄습니다접수2026-09-241,250,000
1023포스 영수증이 두 장씩 나옵니다처리완료2026-09-23320,000
1022간판 조명 교체 요청전환2026-09-2384,000

Appearance

Density
Bordered
Column border
Striped

Row

Interactive

Content

Caption
Footer
Empty

Anatomy

Table을 구성하는 실제 요소와 문서에서 사용하는 명칭입니다. 이름은 shadcn을 따르고 괄호 안이 HTML 요소입니다. 선택 요소는 Extended anatomy에 둡니다.

  1. 1.Table (table)
  2. 2.Table header (thead)
  3. 3.Table head (th)
  4. 4.Table body (tbody)
  5. 5.Table row (tr)
  6. 6.Table cell (td)
  1. 7.Table caption (caption)(Optional)
  2. 8.Sort button (button)(Optional)
  3. 9.Table footer (tfoot)(Optional)
  4. 10.Table empty (td)(Optional)

Structure map

Container — 가로 스크롤 상자 (div)
└─ Table (table)
   ├─ Table caption (caption) (Optional)
   ├─ Table header (thead)
   │  └─ Table row (tr)
   │     └─ Table head (th)
   ├─ Table body (tbody)
   │  ├─ Table row (tr)
   │  │  └─ Table cell (td)
   │  └─ Table empty (td) (Optional)
   └─ Table footer (tfoot) (Optional)

Properties · Density

칸 여백 세 단계입니다. 행 높이와 칸 여백에는 토큰이 없고 Table이 자기 값을 가집니다.

Condensed · 12/8px

NO점포명
1024강남역점
1023서초점

Normal · 12/10px · Default

NO점포명
1024강남역점
1023서초점

Spacious · 20/12px

NO점포명
1024강남역점
1023서초점

Properties · Bordered

바깥 테두리와 모서리를 Table이 스스로 두를지 정합니다. 기본값은 거짓이며, 표 밖 상자가 이미 두르는 자리에서 선이 두 겹이 되지 않게 합니다.

False · Default

NO점포명
1024강남역점
1023서초점

True

NO점포명
1024강남역점
1023서초점

Properties · Column border

칸 사이에 세로선을 그릴지 정합니다. 기본값은 거짓이며, 줄과 열 두 축이 모두 뜻을 갖는 표가 켭니다. 마지막 칸의 오른쪽에는 선을 두지 않습니다.

False · Default

NO점포명
1024강남역점
1023서초점

True

NO점포명
1024강남역점
1023서초점

Properties · Striped

짝수 줄에 면을 깔아 줄을 가로로 따라가게 합니다. 기본값은 거짓이며, 줄이 많고 아무것도 강조되지 않는 읽기 위주 표가 켭니다. 고른 줄이 있는 표에는 쓰지 않습니다 — 짝수 줄에 hover가 걸린 면이 고른 줄과 두 테마 모두 채널 차 3으로 겹쳐 선택이 흐려집니다. 아래 예시는 그 규칙대로 선택이 없는 표입니다.

False · Default

NO점포명금액
1강남역점4,820,000
2서초점3,910,000
3판교점3,640,000
4합정점2,870,000
5왕십리점2,405,000
6구로디지털단지점1,980,000

True · 선택이 없는 읽기 위주 표

NO점포명금액
1강남역점4,820,000
2서초점3,910,000
3판교점3,640,000
4합정점2,870,000
5왕십리점2,405,000
6구로디지털단지점1,980,000

Properties · Alignment

머리글과 칸을 왼쪽·가운데·오른쪽에 붙입니다. 기본값은 Start이며, End는 줄끼리 자릿수를 견주는 열(금액·수량·합계)이 쓰고 그래서 tabular-nums를 함께 갖습니다. 숫자라고 모두 End는 아닙니다 — 한 줄에서 하나만 읽는 번호·날짜는 Center나 Start입니다. Center는 글자가 아니라 컨트롤이 든 열(체크박스·badge·버튼)이 쓰는 자리입니다.

Start · Default

점포명
강남역점
서초점

Center · 컨트롤 열

처리상태
접수
처리완료

End · tabular-nums

금액
1,250,000
320,000

Properties · Sort

정렬 머리글은 칸 전체가 아니라 글자만 버튼입니다. 두 방향 화살표를 늘 함께 세우고 걸린 방향만 brand 색을 가져갑니다.

Sortable · null

2026-09-24

Ascending · asc

2026-09-24

Descending · desc

2026-09-24

Not sortable

등록일
2026-09-24

Properties · State

줄의 상태입니다. Interactive는 포인터와 키보드로 모두 닿고, 고른 줄에는 hover 면을 덧칠하지 않습니다.

Default

제목
에어컨이 멈췄습니다

Interactive · Hover와 Focus를 실제로 확인한다

제목
에어컨이 멈췄습니다

Selected · hover 면을 덧칠하지 않는다

제목
에어컨이 멈췄습니다

Muted

제목
에어컨이 멈췄습니다

Properties · Empty

값이 없을 때 세우는 한 줄입니다. 열 수는 쓰는 화면이 주고 여백과 색은 Table이 갖습니다.

고를 줄이 있는 표 · 전체 선택

NO제목
1024에어컨이 멈췄습니다
1023포스 영수증이 두 장씩 나옵니다

TableEmpty · colSpan 3 · 전체 선택이 없다

NO제목
데이터가 없습니다.

Guidelines

현재 확정한 Table의 사용 범위입니다.

상태를 표 밖에 두기

고른 줄

제목
에어컨이 멈췄습니다

정렬 걸린 머리글

2026-09-24
  • 고른 줄, 정렬 기준, 지금 페이지는 화면이 들고 Table은 받아 그립니다.
  • 같은 조건을 표 위의 필터와 표 아래의 페이지 이동이 함께 쓰므로, 상태가 표 안으로 들어가면 표 밖의 조작이 그 값을 읽을 수 없습니다.

정렬 방향 고르기

점포명처리상태
강남역점접수
서초점처리완료
점포명처리상태
강남역점접수
서초점처리완료

Do

길이가 제각각인 글은 왼쪽, 자릿수를 견주는 숫자는 오른쪽, 컨트롤이 든 칸은 가운데에 붙이세요.

Don’t

길이가 제각각인 글을 가운데로 두지 마세요.

  • 가운데로 두면 줄마다 시작점이 달라져 눈이 매번 글자 앞을 다시 찾습니다.
  • 사용자가 적어 넣는 값은 길이를 예상할 수 없으므로 왼쪽입니다. 제목, 내용, 점포명, 사람이 적어 넣는 메모가 그것입니다.
  • 글자가 아니라 컨트롤이 든 칸은 가운데입니다. 체크박스, badge, 버튼처럼 칸 안의 것이 자기 폭을 갖고 줄마다 그 폭이 같으면, 가운데에 두어야 그 열이 한 줄로 섭니다.
  • 머리글과 값은 같은 변에 붙입니다. 한 열의 머리글과 값이 다른 변에 붙으면 그 열이 두 열처럼 보입니다.

빈 상태 두기

제목
데이터가 없습니다.
제목

Do

값이 없으면 TableEmpty를 세우세요.

Don’t

TableBody를 비워 두지 마세요.

  • 머리줄만 남으면 조건에 맞는 것이 없는 것인지 아직 불러오는 중인지 갈리지 않습니다.
  • 고를 줄이 없으면 머리줄의 전체 선택을 그리지 않습니다. 열과 폭은 남기고 체크박스만 뺍니다 — 「목록이 비었다」와 「고를 수 있는 줄이 하나도 없다」는 다른 조건이어서 표가 아니라 화면이 판단합니다.
  • colSpan에는 그 표가 실제로 그린 열 수를 줍니다. Table이 스스로 세면 조건부 열이 있는 표에서 셈이 틀립니다.

Property map

현재 확정한 Table 속성입니다.

PropertyValuesDefault
Table.densitycondensed | normal | spaciousnormal
Table.borderedfalse | truefalse
Table.columnBorderfalse | truefalse
Table.stripedfalse | truefalse
TableHead.alignstart | center | endstart
TableHead.widthnumber (px)undefined
TableHead.sortasc | desc | nullundefined
TableHead.onSort() => voidundefined
TableRow.interactivefalse | truefalse
TableRow.mutedfalse | truefalse
TableRow.selectedfalse | truefalse
TableCell.alignstart | center | endstart
TableEmpty.colSpannumberrequired

명세 문서

docs/system/components/table.md

Table

packages/ui/src/table.tsx

목록 하나를 줄과 칸으로 세우고, 줄 높이와 칸 여백, 머리줄과 구분선, 고른 줄과 더 볼 것이 없는 줄의 표현을 소유한다.

역할과 경계

  • Table은 한 줄이 한 건인 목록을 세운다. 어떤 열을 어떤 순서로 두는지는 쓰는 화면이 정하고, Table은 모든 목록이 같아야 하는 것만 갖는다. 줄 높이와 칸 여백, 머리줄의 면, 줄을 가르는 선, 포인터를 얹었을 때의 면, 고른 줄과 더 볼 것이 없는 줄이 그것이다.
  • Table은 값을 담는 그릇이고 목록의 상태는 화면이 든다. 무엇이 골라졌는지, 어느 열로 정렬했는지, 몇 번째 페이지인지를 Table이 기억하지 않는다. 같은 조건을 표 위의 필터와 표 아래의 페이지 이동이 함께 쓰므로, 상태가 표 안에 들어가면 표 밖의 조작이 그 값을 읽을 수 없다.
  • native <table>을 그대로 쓴다. 줄과 칸의 관계, 머리글과 값의 연결, 화면 읽기 도구가 「3행 2열」을 말하는 것은 브라우저가 이미 아는 것이다. Base UI 1.7.0에는 표 primitive가 없고 필요하지도 않다.
  • 머리줄은 정렬만 갖는다. 오름·내림 두 방향을 고르는 것이 TableHead가 갖는 유일한 조작이고, 어떤 값만 볼지 고르는 일은 표 밖의 필터 영역이 갖는다. 정렬은 걸러 낸 목록을 보는 방식이라 표 안에서 끝나지만, 필터는 표 위 요약과 표 아래 페이지 이동이 같은 조건을 함께 읽으므로 표 안으로 들어가면 그 둘이 값을 읽을 수 없다. 머리줄에서 필터를 제공하는 길은 필터 영역과의 상호작용을 먼저 정의한 뒤에 확정한다 — 한 축이 두 자리에 서면 어느 쪽이 값을 들고, 한쪽에서 고른 것이 다른 쪽에 어떻게 보이며, 초기화가 둘을 함께 푸는지가 그 정의다.
  • 줄 수가 적고 값마다 이름이 붙는 「이름: 값」 목록은 Table이 아니다. 열 머리글이 모든 줄에 같은 뜻으로 서야 표가 된다.
  • 카드를 격자로 늘어놓고 고르는 자리는 select-box.md가 담당한다. 비교하는 값이 여럿이어도 줄과 칸으로 맞물리지 않으면 표가 아니다.
  • 페이지 이동은 Table이 갖지 않는다. 표 아래 한 줄에 서는 별개 요소이며 아직 확정이 아니다.

Anatomy

  1. Table
  2. Table header
  3. Table head (열 머리글)
  4. Table body
  5. Table row
  6. Table cell

Extended anatomy는 선택 요소를 표시한다.

  1. Table caption (Optional)
  2. Sort button (Optional) — Table head 안에서 머리글 글자만 버튼이 된다
  3. Table footer (Optional)
  4. Table empty (Optional)

이름은 shadcn을 따르고 대응은 아래 표가 밝힌다. vocabulary.md의 「업계 명칭을 쓰고 대응표로 역할을 밝힌다」가 정한 방식이다. 후보 파일은 TableHead를 <thead>로, TableHeaderCell을 <th>로 썼는데 그 이름을 그대로 두면 앞으로 shadcn에서 무엇을 가져올 때마다 같은 이름이 다른 요소를 가리킨다.

이름 HTML 요소 data-slot 후보 파일의 이름
Table <table> table Table
TableHeader <thead> table-header TableHead
TableHead <th> table-head TableHeaderCell
TableBody <tbody> table-body TableBody
TableFooter <tfoot> table-footer 없음
TableRow <tr> table-row TableRow
TableCell <td> table-cell TableCell
TableCaption <caption> table-caption 없음
TableEmpty <tr> 안의 <td> table-empty 없음

가로 스크롤 상자는 Table이 자기 안에 세우는 <div>이며 별도 이름도 data-slot도 갖지 않아 위 번호에 들지 않는다 — 고를 이름이 없으니 Studio의 번호 범례에도 자리가 없고, Structure map이 담는 것으로 갈음한다. 관리자 화면은 lg(1024px)까지만 대응하고 그보다 좁아지면 가로로 스크롤하는데, 열이 여럿인 표는 그 폭에서도 넘치므로 화면 전체가 아니라 표만 자기 안에서 스크롤되어야 한다.

Properties

Table

  • density: condensed | normal | spacious, 기본값 normal. 칸 여백이 각각 px-3 py-2·px-3 py-2.5·px-5 py-3이다. 저장소의 표 열세 곳에서 실제로 쓰이던 여백을 셋으로 모은 것이다. 행 높이와 칸 여백, 표 글자 크기에는 토큰이 없다 — interaction.md의 「공통 Control Height」는 값을 입력받거나 고르는 컨트롤 줄 전용이라 빌려 쓰지 않고, 표가 자기 값을 갖는다. 그 값은 아래 Specification이 적는다. 세 낱말을 고른 까닭은 바로 아래에 적는다
  • 세 낱말은 Primer(GitHub)의 cellPadding 한 벌(condensed·normal·spacious)을 그대로 가져온 것이다. 셋을 출처 하나로 가리킬 수 있어야 이름이 서로를 설명한다. 디자인 체계 열다섯 곳을 열어 보니 이 축은 density(MUI X DataGrid: compact·standard·comfortable), size(IBM Carbon·Fluent UI·Ant Design·MUI Material Table), 숫자 단계(Radix Themes: "1"·"2"·"3"), boolean 하나(Polaris IndexTable의 condensed, Bootstrap 5.3의 .table-sm)로 갈리고, 축이 아예 없는 곳도 넷이다(shadcn/ui·Base UI·Atlassian·Geist). property 이름은 MUI X와 같은 density로 두고, 값 셋을 그대로 쓸 수 있는 유일한 곳인 Primer에서 셋을 함께 가져왔다. size로 가지 않는 것은 이 저장소의 사이즈 property 이름이 size가 아니라 controlSize이기 때문이고(Button·Input·Chip·Switch·Toggle Button·Select), 숫자 단계는 어느 쪽이 좁은지 이름이 말하지 않는다
  • 좁히는 단계를 compact라 부르지 않는 것은 이 저장소에서 compact가 20px 한 값으로 못 박힌 낱말이기 때문이다(interaction.md의 「Compact」). 이 단계는 높이가 아니라 칸 여백이므로 이름을 달리 둔다
  • 넓히는 단계를 relaxed라 부르지 않는 것은 그 낱말이 위 열다섯 곳 어디에도 없고, Tailwind에서 leading-relaxed(줄 높이)로 굳어 다른 뜻을 끌고 오기 때문이다. 업계가 넓히는 단계에 쓰는 낱말은 comfortable(MUI X)과 spacious(Primer) 둘이고, 그 가운데 Primer 쪽을 받았다
  • 가운데 단계를 regular라 부르지 않는 것은 이 저장소에서 regular가 36px 컨트롤 높이의 낱말이기 때문이다 — controlSize의 한 값이고 토큰은 oe-control-regular다. 표가 그 이름을 쓰면 바로 위에서 금지한 「공통 Control Height를 빌려 쓰지 않는다」를 이름이 되돌려 부른다. normal로 두면 그 오해가 끊긴다
  • bordered: false | true, 기본값 false. 참이면 바깥 테두리와 interaction.md의 「공통 Control Radius」를 표가 스스로 두른다. 기본을 거짓으로 두는 것은 지금 화면들이 표 밖 상자로 두르고 있어, 참으로 두면 테두리가 두 겹이 되기 때문이다
  • columnBorder: false | true, 기본값 false. 참이면 칸 사이에 세로선을 그린다. 색은 줄을 가르는 선과 같고, 마지막 칸의 오른쪽에는 그리지 않는다 — 그 자리는 합칠 짝이 없어 감싼 상자의 바깥 테두리와 1px 두 줄로 나란히 선다
  • striped: false | true, 기본값 false. 참이면 tbody의 짝수 줄에 oe-background-alternate 면을 깔아 줄을 가로로 따라가게 한다. 읽기 위주 표가 켠다 — 줄이 많고 아무것도 강조되지 않는 표다. 고른 줄이 있는 표에는 쓰지 않는다(아래 「줄무늬를 켤 표 고르기」의 숫자 표). interactive와는 함께 쓸 수 있다. 참이면 <table>에 data-striped가 남는다
  • 가로 스크롤 상자는 bordered와 무관하게 늘 Table이 갖는다

TableHead

  • TableHead.align: start | center | end, 기본값 start
  • width: 이 열의 폭(px). 주지 않은 열이 남는 폭을 나눠 갖는다
  • sort: asc | desc | null, 기본값 없음. 값을 주면 머리글이 버튼이 되고 양방향 화살표를 세우며 걸린 방향만 brand 색이다. 정렬할 수 있지만 이 열이 기준이 아니면 null을 주고, 아예 주지 않은 열은 정렬하지 않는 열이다. 이 열의 값을 골라 거르는 조작은 TableHead가 받지 않는다
  • onSort: 정렬 기준을 이 열로 옮기거나 방향을 뒤집는다. sort와 onSort 가운데 하나만 와도 정렬하는 열로 본다

TableRow

  • interactive: false | true, 기본값 false. 줄 전체가 그 건의 상세로 가는 길이 된다. 포인터가 손가락으로 바뀌고 면이 생기며, 키보드로도 닿는다 — tabIndex=0과 Enter·Space, focus-visible 링을 함께 갖는다(quality.md의 keyboard navigation·visible focus). 칸 안의 체크박스나 버튼에서 누른 키는 줄까지 올라가지 않는다
  • muted: false | true, 기본값 false. 목록에는 남되 여기서 더 볼 것이 없는 줄이다. 글자를 한 단계 옅게 한다
  • selected: false | true, 기본값 false. 중립 면으로 표시하고 brand를 쓰지 않는다(interaction.md의 「선택 상태」). 고른 줄에는 포인터를 얹어도 hover 면을 덧칠하지 않는다. Table.striped와 함께 쓰지 못하며 그 자리에서는 개발 중에 console.error로 알린다 — 던지지 않는 것은 화면 하나가 표 하나 때문에 흰 화면이 되는 쪽이 더 나쁘기 때문이다

TableCell

  • TableCell.align: start | center | end, 기본값 start. end는 줄끼리 자릿수를 견주는 열(금액, 수량, 합계)이 쓴다. 그 열은 자리가 어긋나면 안 되므로 tabular-nums를 함께 갖는다. 숫자라고 모두 end가 아니다 — 한 줄에서 하나만 읽는 값(번호, 날짜)은 center나 start이고 tabular-nums만 그 칸에 준다. 숫자가 아닌 값을 오른쪽에 붙이는 자리는 className으로 normal-nums를 덮는다
  • 줄 끝에 버튼이 서는 조작 열은 end가 아니라 className으로 오른쪽에 붙인다. end로 두면 글자에 tabular-nums가 걸린다

TableEmpty

  • colSpan: 이 줄이 덮을 열 수. Table이 스스로 세지 않는다 — 까닭은 아래 「현재 정의하지 않은 항목」에 있다. 여백과 색은 Table이 갖는다

TableHeader·TableBody·TableFooter·TableCaption은 시각과 동작을 정하는 Property를 따로 받지 않고 각 요소의 속성만 받는다. 넷의 표현은 아래 Specification이 갖는다.

Guidelines

상태를 표 밖에 두기

고른 줄, 정렬 기준, 지금 페이지는 화면이 든다. Table은 그 값을 받아 그릴 뿐이다.

  • 고른 줄은 화면이 번호 목록으로 들고 selected로 내린다. 머리줄의 「이 페이지 전체 선택」과 표 밖의 일괄 동작이 같은 목록을 읽어야 한다.
  • 정렬은 화면이 { key, direction }을 들고 해당 열에 sort를, 모든 정렬 열에 onSort를 내린다. 기준이 아닌 열에는 null을 준다 — 그래야 그 열도 정렬할 수 있다는 것이 누르기 전에 보인다.
  • 정렬은 조건이 아니라 걸러 낸 목록을 보는 방식이므로 조회를 거치지 않고 곧바로 반영한다.

열 폭을 정하기

  • 폭은 열이 정하고 내용에 맡기지 않는다. 내용을 따르면 페이지를 옮길 때마다 글자 수에 따라 열 경계가 움직여서, 같은 자리를 훑던 눈이 매번 열을 다시 찾는다.
  • 폭은 그 열에 들어올 수 있는 가장 긴 값을 기준으로 정한다. 값의 길이가 제각각인 열 하나만 width를 비워 남는 폭을 가져가게 두는 것이 기본이다.
  • 열이 많아 폭의 합이 담을 영역보다 넓어지면 마지막 열이 잘려 오른쪽에 여백이 없는 것처럼 보인다. 합을 영역 폭 안에 둔다.

정렬 방향 고르기

  • 값의 길이가 제각각인 글은 start로 왼쪽에 붙인다. 가운데로 두면 줄마다 시작점이 달라져 눈이 매번 글자 앞을 다시 찾는다.
  • 사용자가 적어 넣는 값은 길이를 예상할 수 없으므로 start다. 제목, 내용, 점포명, 사람이 적은 메모가 그것이다. 값의 가짓수가 정해진 열이어도 그 길이가 갈리면(「기타」와 「마케팅 및 프로모션」) 같이 start다.
  • 글자가 아니라 컨트롤이 든 칸은 center다. 체크박스, badge, 버튼처럼 칸 안의 것이 자기 폭을 갖고 줄마다 그 폭이 같으면, 가운데에 두어야 그 열이 한 줄로 선다. 왼쪽에 붙이면 칸 여백만큼 안쪽으로 들어가 열 폭의 절반이 비고, 오른쪽에 붙이면 옆 열의 글자와 맞붙는다. 컨트롤 열은 그 컨트롤 폭에 칸 여백만 더해 width를 준다.
  • 값이 짧고 길이가 고른 글자 열(번호, 날짜)은 center로 둘 수 있다. 상태처럼 badge로 서는 열은 위 컨트롤 규칙을 따른다.
  • 한 칸에 두 값을 두 줄로 담는 열은 두 줄의 길이가 갈리면 start다(이름과 소속). 값이 짧아도 위아래 두 줄의 왼쪽 축이 서야 한 덩어리로 읽힌다. 두 줄이 모두 자리 수가 고정된 값이면(날짜와 시각) 위의 「짧고 길이가 고른 글자 열」대로 center로 둘 수 있고, 그때는 두 줄이 같은 가운데 축에 서게 한다 — 한 줄에만 조건부 표시가 붙는 칸은 반대쪽에 같은 폭을 비워 두어야 아랫줄과 중심이 어긋나지 않는다.
  • 자릿수를 견주는 숫자 열은 end로 오른쪽에 붙인다. tabular-nums가 함께 걸려 줄마다 자리가 어긋나지 않는다. 숫자라고 모두 end는 아니다 — 위의 「한 줄에서 하나만 읽는 값」을 함께 본다.
  • 머리글과 값의 정렬을 어긋나게 두지 않는다. 한 열의 머리글과 값이 다른 변에 붙으면 그 열이 두 열처럼 보인다.

줄을 길로 쓰기

  • 줄 전체가 그 건의 상세로 가는 자리면 interactive를 준다. 줄 안의 글자 하나만 링크로 두지 않는다 — 누르는 자리가 좁아지고, 실제로 열리는 단위는 줄이다.
  • 줄 안에 따로 눌리는 것(체크박스, 옮겨 간 건의 번호)이 있으면 그 칸에서 onClick의 번짐을 막는다. 키보드는 Table이 이미 막는다.
  • muted는 「목록에는 남지만 여기서 할 일이 끝난 줄」에만 쓴다. 읽을 수 없게 만드는 표시가 아니라 뒤로 한 단계 물러나는 표시다.

표에 이름 붙이기

  • 표는 이름을 갖는다. 화면 읽기 도구가 표 목록을 훑을 때 이름이 없는 표는 「표」로만 읽힌다.
  • 기본 길은 aria-labelledby다. 표 밖에 보이는 제목이 이미 있으면 그 제목에 id를 주고 표에 aria-labelledby를 건다. 같은 글을 TableCaption으로 한 번 더 쓰지 않는다 — 제목이 바뀔 때 두 곳이 어긋나고, <caption>은 가로 스크롤 상자 안에 있어 열이 넘치면 이름도 함께 옆으로 빠져나간다.
    • 본문의 머리가 그리는 제목이 그 자리면 page-header.md의 titleId로 id를 준다. 화면 코드가 <h1>에 직접 적는 것이 아니라 머리에 넘기는 값이다.
  • 보이는 제목이 없으면 TableCaption을 세운다. 감출 자리는 화면이 sr-only를 준다.
  • aria-label은 제목이 화면에 없고 caption을 세울 자리도 없을 때 쓴다. 눈으로 보는 이름과 읽어 주는 이름이 갈리므로 마지막 길이다. 보이는 제목이 있는데 그 제목에 id가 없어 이 길을 쓰고 있었다면, id가 생기는 날 aria-labelledby로 옮긴다 — 점주의 소리 목록이 2026-10-06에 그 길을 지났다.
  • 이름이 둘 다 없는 표를 두지 않는다. 표가 둘 이상인 화면에서는 각 표에 자기 제목이 있어야 한다 — 페이지 제목 하나를 둘이 함께 가리키면 두 표의 이름이 같아진다.
  • TableCaption은 이름 말고도 쓸 자리가 있다. 표 아래에 단위·집계 기준·조회 시각을 밝히는 한 줄이 그것이며, 그때는 감추지 않는다.

빈 상태 두기

  • 값이 없을 때 TableBody를 비워 두지 않고 TableEmpty를 세운다. 머리줄만 남으면 조건에 맞는 것이 없는 것인지 아직 불러오는 중인지 갈리지 않는다.
  • colSpan에는 그 표가 실제로 그린 열 수를 준다. 조건에 따라 열이 붙고 빠지는 표라면 그 셈도 함께 따라야 한다.
  • 빈 상태에서도 머리줄은 그대로 선다. 열 경계가 사라지면 목록이 돌아올 때 표가 다시 그려지는 것으로 보인다. 다만 고를 줄이 없으면 전체 선택을 그리지 않는다 — 표가 아니라 화면이 판단한다. 없는 줄을 겨냥하는 조작이라 눌러도 아무 일이 없고, 「목록이 비었다」와 「고를 수 있는 줄이 하나도 없다」는 다른 조건이어서(전환된 건만 남은 페이지) 표는 둘 다 알 수 없다. 열과 폭은 남기고 체크박스만 뺀다.
  • 정렬 머리글은 빈 상태에서도 남긴다. 정렬은 조건이 바뀌어도 이어지는 보기 방식이고, 선택은 지금 있는 줄만 가리키기 때문이다.

바깥 테두리를 누가 두르는지 정하기

  • 표만 선으로 두르는 자리는 bordered를 쓴다.
  • 표 위아래 줄까지 한 상자로 묶는 자리는 화면이 두르고 bordered를 주지 않는다. 둘 다 두르면 선이 두 겹이 된다.
  • 칸 사이의 세로선(columnBorder)은 줄과 열 두 축이 모두 뜻을 갖는 표가 켠다. 주간 근무표처럼 칸이 좌표인 표가 그것이다. 한 줄이 한 건인 목록은 켜지 않는다 — 그 표에서 뜻을 나르는 것은 줄이고, 세로선은 읽을 것이 없는 경계를 하나 더 그린다.
  • 폭을 「내용 + 칸 여백」으로 딱 맞춘 열은 세로선이 그 1px을 먹는다. 체크박스 열처럼 남는 자리가 없는 열에 columnBorder를 켤 때는 width를 1px 늘려 잡는다.
  • striped와 세로선과 줄 사이 선을 함께 켜지 않는다. 면과 선이 넷이 되면 표가 격자로 무거워져 값이 아니라 칸 경계가 먼저 읽힌다. 줄무늬가 줄을 가로로 이어 주는 자리에서는 세로선이 그 흐름을 칸으로 끊는다.

줄무늬를 켤 표 고르기

줄무늬는 읽기 위주 표의 것이다. 줄이 많고 눈으로 가로로 따라가야 하는데 아무것도 강조되지 않는 표가 켠다. 손이 닿는 표에서는 hover와 선택이 이미 줄을 가르고 있어 줄무늬가 보탤 것이 없다.

고른 줄이 있는 표에는 쓰지 않는다. 면 밝기 하나로 네 상태를 갈라야 하는데 그만큼 벌릴 자리가 없다. 아래는 두 테마에서 실제로 그려진 화소를 읽어 얻은 sRGB 값이다(세 채널이 같은 회색조다) — 빌드본을 띄우고 포인터를 얹은 뒤 캡처한 PNG의 그 줄 화소를 읽었다. oe-background-primary 위에서 잰 값이다. 알파를 손으로 합성해 얻은 값을 적지 않는다 — 브라우저가 올림하는 자리에서 1만큼 어긋난다(Dark의 「홀수 줄 + hover」가 그 자리다).

상태 Light Dark
홀수 줄 255 23
짝수 줄(줄무늬) 250 30
홀수 줄 + hover 247 35
짝수 줄 + hover 242 41
고른 줄 245 38

짝수 줄에 hover가 걸린 것과 고른 줄이 겹친다 — 두 테마 모두 채널 차 3이다. 고른 줄에는 hover를 얹지 않으므로 「고르고 hover」는 없지만, 옆줄을 지나가는 포인터가 고른 줄과 같은 색을 만든다. 선택이 흐려지는 것은 받을 수 없다.

표시를 하나 더 붙여 네 단계를 벌리는 길도 없다. interaction.md의 「선택 상태와 Hover·Pressed」가 경계가 없는 목록 행은 면을 채워 선택을 알리도록 이미 정했으므로 줄 왼쪽에 막대를 세우는 길은 그 문장과 어긋나고, 같은 절이 선택된 상태에 Hover와 Pressed를 중첩하지 않도록 정했으므로 고른 줄에 다른 표시를 얹어 벌릴 수도 없다.

interactive와는 함께 쓸 수 있다. 그 자리에서 부딪치는 것은 「hover 걸린 홀수 줄 ↔ 그냥 짝수 줄」 하나(Light 247 ↔ 250, Dark 35 ↔ 30)이고, hover는 포인터를 따라다니므로 사람이 어디를 짚고 있는지 스스로 안다. 고정된 두 면이 같은 값이 되는 것과 다르다.

막는 방식은 개발 중 경고다. Table이 striped를 내리고 TableRow가 selected와 겹친 자리에서 console.error로 알린다. 던지지 않는 것은 화면 하나가 표 하나 때문에 흰 화면이 되는 쪽이 더 나쁘기 때문이며, 경고를 무시한 화면에서도 선택은 살아 있다 — 줄무늬 선택자가 고른 줄을 뺀다.

다른 화면의 표를 가까운 단계로 모으기

저장소에는 이 표 말고도 표를 가진 화면이 열네 곳이다(2026-10-01 기준). 그 가운데 상권 메인 하나는 이미 이 API로 섰고, 손으로 지은 나머지 열세 곳의 칸 여백이 여섯 갈래(px-3 py-2·px-3 py-2.5·px-3 py-3·px-4 py-2.5·px-4 py-3·px-5 py-3)와 글자 크기 두 갈래(text-sm·text-xs)로 갈려 있다. 아래 표는 그 열세 곳이다. 갈아탈 때는 자기 여백을 그대로 옮기지 말고 세 단계 가운데 가까운 것으로 모은다. 이번에는 갈아타지 않고 이 API가 그것들을 받을 수 있는지만 적는다.

여백 화면 이 API에서
px-3 py-2 재고 관리 2, 세금계산서, 표 셀 편집, 주간 근무표 density="condensed" 그대로
px-3 py-2.5 연차 관리 density="normal" 그대로
px-5 py-3 청구 대시보드, 청구 조회 density="spacious" 그대로
px-4 py-3 근태·급여, 러닝 기록, 재고 관리, VOC, 엑셀 내보내기의 몸 칸 단계가 없다. className으로 덮는다
px-4 py-2.5 엑셀 내보내기의 머리 칸 단계가 없다. className으로 덮는다
px-3 py-3 연차 관리, 주간 근무표의 일부 칸 단계가 없다. className으로 덮는다
py-1 · 좌우 여백 없음 AI 업무 도우미 단계가 없다. 표가 아니라 카드 안의 「이름: 값」 목록이므로 갈아탈 자리가 아니다
px-1 py-1 표 셀 편집의 편집 중인 칸 여백 갈래로 세지 않는다. 입력이 칸을 채우므로 칸이 아니라 그 안의 Input이 높이를 정한다
  • 세 단계가 여섯 갈래 가운데 셋을 그대로 받고, 그 셋으로 선 화면이 일곱 곳이다(여백이 두 갈래인 화면은 양쪽에 센다). 나머지는 className으로 여백을 덮어야 하며, 네 번째 단계를 더하지 않는다 — px-4 py-3은 condensed와 spacious 사이의 값이고, 단계를 화면 수만큼 늘리면 단계가 있다는 뜻이 사라진다. 갈아탈 때 셋 가운데 가까운 것으로 모으는 것이 맞다.
  • text-xs는 표가 담는 값의 크기가 아니다. 기본은 text-sm이고, 12px은 값에 딸린 부가 정보(시각, 경과, 소속)의 크기다. 그 부가 정보는 칸 안의 <span>이 자기 크기를 갖고, Table 계열에는 className으로 글자 크기를 주지 않는다. 표 글자를 text-xs로 쓰던 화면은 갈아탈 때 어느 것이 값이고 어느 것이 부가 정보인지 갈라 적는다.
  • 손으로 지은 열세 곳은 badge·체크박스 열을 모두 왼쪽에 붙이고 있고, 금액·수량 열도 세 곳이 왼쪽이다. align은 갈아탈 때 처음 붙는 것이므로 그때 위 「정렬 방향 고르기」로 함께 맞춘다 — 지금 className으로 고치면 갈아탈 때 두 번 만지게 된다.
  • 열 정의 배열을 받는 길은 두지 않았다. 까닭은 아래 「현재 정의하지 않은 항목」에 있다.

Specification

행 높이와 칸 여백, 표 글자 크기에는 토큰이 없다. 표가 자기 값을 갖고 그 값을 여기에 적는다. 컨트롤 줄의 높이 scale(CONTROL_HEIGHTS)은 값을 입력받거나 고르는 요소가 나란히 설 때 높이를 맞추기 위한 것이라 표의 줄에 빌려 쓰지 않는다.

자리 condensed normal spacious
칸 좌우 여백 12px 12px 20px
칸 위아래 여백 8px 10px 12px
머리 행 높이(한 줄) 36px 40px 44px
  • 줄 높이는 칸 여백과 그 안의 내용이 정한다. 고정값을 두지 않는 것은 한 칸에 두 줄을 담는 열(날짜와 시각, 이름과 소속)이 있어서다. 위 표의 머리 행 높이는 14px 글자 한 줄(줄 높이 20px)에 위아래 여백을 더한 값이다.
  • 표 글자는 14px이며 whitespace-nowrap이다. 한 칸 안에서 줄이 넘어가면 그 줄만 높아져 옆 줄과 어긋난다.
  • 열 폭은 table-fixed다. 폭은 각 열의 width가 정하고, 정하지 않은 열이 남는 폭을 나눠 갖는다.
  • 줄을 가르는 선과 머리줄의 아래 선은 같은 oe-border-secondary 1px이다. 머리줄은 회색 면과 굵은 글자로 이미 값 줄과 갈리므로, 선까지 진하게 두면 같은 것을 두 번 말하면서 표에서 가장 진한 선이 값이 아닌 자리에 생긴다.
  • 마지막 줄에는 아래 선을 두지 않는다. 표를 바닥으로 두를 때 그 경계와 겹쳐 두 겹이 된다.
  • columnBorder인 표의 세로선도 oe-border-secondary 1px이며 thead·tbody·tfoot의 칸에 함께 걸린다. 맞닿는 칸끼리는 border-collapse가 두 선을 한 줄로 합치고, 마지막 칸의 오른쪽 선은 그리지 않는다 — 합칠 짝이 없어 바깥 테두리와 두 줄로 나란히 선다. TableEmpty의 colSpan 칸은 첫 칸이면서 마지막 칸이라 이 규칙에서 저절로 빠진다.
  • TableCaption은 표 아래에 선다. <table>이 caption-bottom을 들어 그렇게 되며, CSS의 caption-side 기본값은 top이라 두지 않으면 표 위에 선다. 보이는 caption은 이름이 아니라 단위·집계 기준·조회 시각을 밝히는 한 줄로 쓰이므로(위 「표에 이름 붙이기」) 값 아래에 와야 하고, 감춘 caption(sr-only)에는 서는 자리가 뜻이 없어 그 자리에서는 달라지는 것이 없다. shadcn의 Table도 뿌리에 같은 class를 둔다.
  • TableCaption은 sr-only를 기본으로 두지 않는다. 표 밖에 보이는 제목이 이미 있는 화면과 없는 화면이 갈리므로 감출지는 화면이 정한다. 여백은 density를 따르고 글자는 oe-foreground-secondary다.
  • Table에 준 class는 <table>에 붙고 가로 스크롤 상자에는 붙지 않는다. 상자는 표의 폭과 스크롤만 갖고 표의 생김새를 갖지 않으므로, 상자 쪽을 고쳐야 하는 자리는 표를 감싸는 화면이 맡는다.
  • 머리줄과 TableFooter는 oe-background-secondary 면과 font-medium을 쓰고, 머리글 글자는 oe-foreground-secondary다. 둘 다 값이 아니라 표의 틀이므로 같은 면을 쓴다. TableFooter는 위에 선을 하나 그어 값 줄과 갈린다.
  • 고른 줄은 oe-background-secondary를 깐다. 고른 줄에는 포인터를 얹어도 hover를 덧칠하지 않는다.
  • 포인터를 얹은 줄의 hover는 배경색이 아니라 겹이다. oe-interaction-hover-subtle을 background-image로 얹는 oe-hover-layer-subtle을 쓴다(규칙은 packages/tokens/src/styles.css가 갖는다). background-image는 background-color 위에 그려지므로 그 아래 면을 지우지 않고 「그 아래 면에 +Δ」로 읽히며, 줄무늬와 명세도를 다투지 않는다. hover:bg-…로 배경색을 갈아치우면 짝수 줄에서 둘 가운데 한쪽이 사라진다.
  • 겹의 색은 등록한 사용자 지정 속성 --oe-hover-layer-color가 든다. 브라우저는 background-image를 전이하지 않으므로 (transition-property에 background-image를 적어도 중간값 없이 끝값으로 뛴다 — none → gradient든 투명 gradient → gradient든 같다) 겹을 그대로 켜고 끄면 hover가 번지지 않고 딱 켜진다. @property로 <color>라 알려 둔 속성은 전이되고 linear-gradient()가 그 값을 읽으므로 그려지는 겹이 함께 번진다. 그래서 줄의 전이 대상에 그 속성 이름을 적는다 — 줄은 transition-[background-color,color,--oe-hover-layer-color]이며 background-color는 고른 줄과 줄무늬가, color는 muted가 쓴다. transition-colors 단축은 그 이름을 덮지 않으므로 그것만 두면 hover의 150ms 번짐이 사라진다.
  • striped인 표는 tbody의 짝수 줄에 oe-background-alternate를 깐다. 값은 Light neutral-50, Dark neutral-850이며 두 테마에서 background-primary와 background-secondary 사이에 선다(tokens.md). 선택자는 [&_tbody>tr:not([data-selected]):nth-child(even)]이다 — tbody>tr로 좁혀 머리줄과 TableFooter에는 새지 않고, TableRow가 고른 줄에만 data-selected를 남기므로 값이 아니라 속성의 있음·없음으로 고른 줄을 뺀다([data-selected="false"]는 아무것도 맞히지 못한다).
  • 더 볼 것이 없는 줄은 글자를 oe-foreground-tertiary로 한 단계 내린다. 색은 줄에 걸고 칸에 걸지 않는다 — 칸이 자기 색을 가지면 줄에 걸린 이 처리가 칸에 가려진다.
  • 정렬 머리글은 칸 전체가 아니라 글자만 버튼이다. 칸 전체를 버튼으로 두면 열이 넓을 때 이름에서 한참 떨어진 빈 자리도 눌려서, 어디를 눌러 정렬한 것인지 되짚기 어렵다. 화살표는 두 방향을 늘 함께 세우고 2px씩 겹치며, 걸린 방향만 oe-brand-foreground-primary를 가져가고 나머지는 oe-foreground-disabled다. aria-sort는 ascending·descending·none이다.
  • 빈 상태는 위아래 여백 40px에 글자를 가운데로 두고 oe-foreground-tertiary를 쓴다. 좌우 여백은 density를 따른다.
  • 가로 스크롤 막대는 손잡이만 보인다. 규칙은 packages/tokens/src/styles.css의 oe-scrollbar-bare가 갖는다.

현재 정의하지 않은 항목

  • 로딩 상태. 값을 불러오는 동안 무엇을 세울지 정하지 않았다. 빈 상태와 갈라야 하며 — 지금은 둘이 같은 자리에 서면 조건에 맞는 것이 없는 것으로 읽힌다 — 표 하나만으로 정할 수 있는 것이 아니라 화면이 자료를 언제 불러오는지와 함께 정해야 한다.
  • Pressed 상태. interactive인 줄에 Hover와 Focus는 있지만 누르는 동안의 표시는 없다. 줄을 누르면 곧 다른 화면으로 가므로 그 사이의 표시가 눈에 남지 않는다.
  • Disabled 상태. 고를 수 없는 줄, 눌러도 열리지 않는 줄을 표에서 어떻게 알릴지 정하지 않았다. muted는 「할 일이 끝난 줄」이지 「쓸 수 없는 줄」이 아니다.
  • TableEmpty가 열 수를 세지 않는 것. 표가 스스로 세려면 머리줄의 <th> 수를 읽어야 하는데, 조건에 따라 열이 붙고 빠지는 표에서는 그 셈이 틀린다. 틀린 셈은 빈 줄이 표 폭을 덜 덮는 것으로만 드러나 알아채기 어렵다. 그래서 쓰는 화면이 자기 열 수를 준다.
  • 머리줄 필터(<th> 안에서 값을 고르는 것). 저장소의 표 열다섯 곳 모두 필터를 표 밖에 두고 있고 <th> 안에 선 조작은 정렬 버튼과 전체 선택 체크박스뿐이다(2026-10-01 기준. 화면이 늘면 이 셈을 다시 센다 — 「그러니 미뤄도 된다」를 받치는 근거가 이 숫자다). 같은 축이 머리줄과 필터 영역에 함께 서면 값을 누가 들고 한쪽의 조작이 다른 쪽에 어떻게 비치는지부터 정해야 하므로, 필터 영역의 자리가 확정된 뒤에 다시 본다.
  • 선택과 줄무늬를 함께 세우는 길. 위 「줄무늬를 켤 표 고르기」의 숫자 표대로 면 밝기 하나로는 네 상태를 벌릴 수 없고, interaction.md의 「선택 상태와 Hover·Pressed」가 목록 행의 선택을 면으로 알리도록 정해 두어 표시를 하나 더 붙여 벌릴 수도 없다. 그래서 striped와 selected는 지금 함께 쓸 수 없다. 다시 보려면 그 절의 「경계가 없는 목록 행은 면을 채워 알린다」부터 다시 보아야 하므로 표 하나로 정할 수 있는 것이 아니다.
  • 선택·정렬·페이지 이동을 표가 들지 않는 것. 셋 다 화면이 든다. 같은 조건을 표 위의 필터와 표 아래의 페이지 이동이 함께 쓰므로, 상태가 표 안으로 들어가면 표 밖의 조작이 그 값을 읽을 수 없다. 표가 상태를 갖는 길은 그 셋을 함께 갖는 상위 요소가 생길 때 다시 본다.
  • 열 정의 배열을 받는 길(DataTable)을 두지 않은 것. 열마다 머리글·폭·정렬·그리는 법을 객체로 적어 배열로 넘기는 API는 열의 생김새가 자료 모양을 따라갈 때 값을 한다. 이 저장소의 표는 한 칸에 두 값을 두 줄로 담고(날짜와 시각, 이름과 소속) 값 뒤에 조건부 표시를 붙이는 자리가 많아, 그리는 법이 결국 배열 안의 함수로 들어간다. 그러면 JSX로 적은 것보다 읽기 어렵고 열 구성이 화면에서 보이지 않는다. 표를 쓰는 화면이 열세 곳을 넘고 그 가운데 절반 이상이 단순한 값 나열이 되면 다시 본다. 앞 조건은 이미 넘었다 — 2026-10-01 기준 표를 쓰는 화면은 위 「머리줄 필터」가 세는 것과 같은 열다섯 곳이다. 뒤 조건(절반 이상이 단순한 값 나열인지)은 아직 재지 않았고, 새 문턱 숫자는 개발자가 다시 정한다. 그때까지 이 줄은 신호가 아니다.
  • 페이지 이동(Pagination). 표 아래 한 줄에 서는 별개 요소이며 따로 둘 값이 있어 이번에 함께 올리지 않았다.
  • 열 폭을 사람이 끌어 바꾸는 것, 머리줄을 스크롤에 붙여 두는 것, 열을 고정하는 것.