Table
목록 하나를 줄과 칸으로 세우는 표입니다. 한 줄이 한 건이고 열 구성은 쓰는 화면이 정하며, 줄 높이와 칸 여백·머리줄·구분선·고른 줄의 표현을 Table이 소유합니다.
🚩 Playground
Density와 바깥 테두리, 줄 상태를 조합해 실제 목록에서 확인합니다. 정렬 머리글은 눌러 방향이 바뀝니다.
Appearance
Row
Content
Anatomy
Table을 구성하는 실제 요소와 문서에서 사용하는 명칭입니다. 이름은 shadcn을 따르고 괄호 안이 HTML 요소입니다. 선택 요소는 Extended anatomy에 둡니다.
Basic anatomy
- 1.Table (table)
- 2.Table header (thead)
- 3.Table head (th)
- 4.Table body (tbody)
- 5.Table row (tr)
- 6.Table cell (td)
Extended anatomy
- 7.Table caption (caption)(Optional)
- 8.Sort button (button)(Optional)
- 9.Table footer (tfoot)(Optional)
- 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
Normal · 12/10px · Default
Spacious · 20/12px
Properties · Bordered
바깥 테두리와 모서리를 Table이 스스로 두를지 정합니다. 기본값은 거짓이며, 표 밖 상자가 이미 두르는 자리에서 선이 두 겹이 되지 않게 합니다.
False · Default
True
Properties · Column border
칸 사이에 세로선을 그릴지 정합니다. 기본값은 거짓이며, 줄과 열 두 축이 모두 뜻을 갖는 표가 켭니다. 마지막 칸의 오른쪽에는 선을 두지 않습니다.
False · Default
True
Properties · Striped
짝수 줄에 면을 깔아 줄을 가로로 따라가게 합니다. 기본값은 거짓이며, 줄이 많고 아무것도 강조되지 않는 읽기 위주 표가 켭니다. 고른 줄이 있는 표에는 쓰지 않습니다 — 짝수 줄에 hover가 걸린 면이 고른 줄과 두 테마 모두 채널 차 3으로 겹쳐 선택이 흐려집니다. 아래 예시는 그 규칙대로 선택이 없는 표입니다.
False · Default
True · 선택이 없는 읽기 위주 표
Properties · Alignment
머리글과 칸을 왼쪽·가운데·오른쪽에 붙입니다. 기본값은 Start이며, End는 줄끼리 자릿수를 견주는 열(금액·수량·합계)이 쓰고 그래서 tabular-nums를 함께 갖습니다. 숫자라고 모두 End는 아닙니다 — 한 줄에서 하나만 읽는 번호·날짜는 Center나 Start입니다. Center는 글자가 아니라 컨트롤이 든 열(체크박스·badge·버튼)이 쓰는 자리입니다.
Start · Default
Center · 컨트롤 열
End · tabular-nums
Properties · Sort
정렬 머리글은 칸 전체가 아니라 글자만 버튼입니다. 두 방향 화살표를 늘 함께 세우고 걸린 방향만 brand 색을 가져갑니다.
Sortable · null
Ascending · asc
Descending · desc
Not sortable
Properties · State
줄의 상태입니다. Interactive는 포인터와 키보드로 모두 닿고, 고른 줄에는 hover 면을 덧칠하지 않습니다.
Default
Interactive · Hover와 Focus를 실제로 확인한다
Selected · hover 면을 덧칠하지 않는다
Muted
Properties · Empty
값이 없을 때 세우는 한 줄입니다. 열 수는 쓰는 화면이 주고 여백과 색은 Table이 갖습니다.
고를 줄이 있는 표 · 전체 선택
TableEmpty · colSpan 3 · 전체 선택이 없다
Guidelines
현재 확정한 Table의 사용 범위입니다.
상태를 표 밖에 두기
고른 줄
정렬 걸린 머리글
- 고른 줄, 정렬 기준, 지금 페이지는 화면이 들고 Table은 받아 그립니다.
- 같은 조건을 표 위의 필터와 표 아래의 페이지 이동이 함께 쓰므로, 상태가 표 안으로 들어가면 표 밖의 조작이 그 값을 읽을 수 없습니다.
정렬 방향 고르기
Do
길이가 제각각인 글은 왼쪽, 자릿수를 견주는 숫자는 오른쪽, 컨트롤이 든 칸은 가운데에 붙이세요.
Don’t
길이가 제각각인 글을 가운데로 두지 마세요.
- 가운데로 두면 줄마다 시작점이 달라져 눈이 매번 글자 앞을 다시 찾습니다.
- 사용자가 적어 넣는 값은 길이를 예상할 수 없으므로 왼쪽입니다. 제목, 내용, 점포명, 사람이 적어 넣는 메모가 그것입니다.
- 글자가 아니라 컨트롤이 든 칸은 가운데입니다. 체크박스, badge, 버튼처럼 칸 안의 것이 자기 폭을 갖고 줄마다 그 폭이 같으면, 가운데에 두어야 그 열이 한 줄로 섭니다.
- 머리글과 값은 같은 변에 붙입니다. 한 열의 머리글과 값이 다른 변에 붙으면 그 열이 두 열처럼 보입니다.
빈 상태 두기
Do
값이 없으면 TableEmpty를 세우세요.
Don’t
TableBody를 비워 두지 마세요.
- 머리줄만 남으면 조건에 맞는 것이 없는 것인지 아직 불러오는 중인지 갈리지 않습니다.
- 고를 줄이 없으면 머리줄의 전체 선택을 그리지 않습니다. 열과 폭은 남기고 체크박스만 뺍니다 — 「목록이 비었다」와 「고를 수 있는 줄이 하나도 없다」는 다른 조건이어서 표가 아니라 화면이 판단합니다.
- colSpan에는 그 표가 실제로 그린 열 수를 줍니다. Table이 스스로 세면 조건부 열이 있는 표에서 셈이 틀립니다.
Property map
현재 확정한 Table 속성입니다.
| Property | Values | Default |
|---|---|---|
| Table.density | condensed | normal | spacious | normal |
| Table.bordered | false | true | false |
| Table.columnBorder | false | true | false |
| Table.striped | false | true | false |
| TableHead.align | start | center | end | start |
| TableHead.width | number (px) | undefined |
| TableHead.sort | asc | desc | null | undefined |
| TableHead.onSort | () => void | undefined |
| TableRow.interactive | false | true | false |
| TableRow.muted | false | true | false |
| TableRow.selected | false | true | false |
| TableCell.align | start | center | end | start |
| TableEmpty.colSpan | number | required |
명세 문서
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
- Table
- Table header
- Table head (열 머리글)
- Table body
- Table row
- Table cell
Extended anatomy는 선택 요소를 표시한다.
- Table caption (Optional)
- Sort button (Optional) — Table head 안에서 머리글 글자만 버튼이 된다
- Table footer (Optional)
- 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, 기본값startwidth: 이 열의 폭(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>에 직접 적는 것이 아니라 머리에 넘기는 값이다.
- 본문의 머리가 그리는 제목이 그 자리면 page-header.md의
- 보이는 제목이 없으면
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-secondary1px이다. 머리줄은 회색 면과 굵은 글자로 이미 값 줄과 갈리므로, 선까지 진하게 두면 같은 것을 두 번 말하면서 표에서 가장 진한 선이 값이 아닌 자리에 생긴다. - 마지막 줄에는 아래 선을 두지 않는다. 표를 바닥으로 두를 때 그 경계와 겹쳐 두 겹이 된다.
columnBorder인 표의 세로선도oe-border-secondary1px이며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를 깐다. 값은 Lightneutral-50, Darkneutral-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). 표 아래 한 줄에 서는 별개 요소이며 따로 둘 값이 있어 이번에 함께 올리지 않았다. - 열 폭을 사람이 끌어 바꾸는 것, 머리줄을 스크롤에 붙여 두는 것, 열을 고정하는 것.