List

구조는 당근 SEED List(Apache-2.0)를 따른다 — 목록(List) · 한 줄(List Item) · 목록 제목(List Header) · 줄 사이 선(ListDivider). 값은 groo 토큰이고, SEED 와 다른 자리는 맨 아래 "SEED 와 다른 점" 에 적었다(2026-10-01 사용자 결정).

수치 원본은 list.yaml(목록 · 한 줄)과 list-header.yaml(목록 제목)이다. 수치 표 자리([표: …])와 그림 자리([그림: …])는 사이트가 그 파일로 그린다 — GitHub 에서는 그 파일 · 그림 코드로 가는 링크로 보인다.

직접 골라 보기제목 링크 복사

줄의 종류 · 앞 · 뒤 · 맞춤 · 강조 · 상태를 고르면 스펙대로 그린 줄과 그 코드가 바뀐다. 실제로 눌러 볼 수 있다.

import { Globe, ChevronRight } from "lucide-react"
import { List, ListButtonItem } from "@/components/ui/list"

<List>
  <ListButtonItem
    prefix={<Globe />}
    title="기본 통화"
    detail="새 거래에 먼저 들어가요"
    suffix={<>대한민국 원<ChevronRight /></>}
    onClick={open}
  />
</List>

Anatomy제목 링크 복사

한 줄은 두 층이다 — 바탕 층(누름 · 호버 · 강조 바탕)과 콘텐츠 층(앞 · 본문 · 뒤). 누르면 바탕 층은 안쪽으로 들어와 둥글어지고, 콘텐츠 층만 2px 거리로 준다(기초 Feedback v104 — "목록 줄은 콘텐츠만").

부위

Properties제목 링크 복사

줄의 종류제목 링크 복사

같은 모양이 하는 일에 따라 넷으로 나뉜다.

• 보기만 하는 줄(ListItem) — 누르지 않는다. 키-값 · 안내 줄.
• 누르는 줄(ListButtonItem) — 줄 전체가 버튼. 화면을 옮기면 오른쪽 화살표를 단다.
• 링크 줄(ListLinkItem) — 줄 전체가 링크. 다른 페이지 · 바깥 주소로 간다.
• 컨트롤 줄(ListSwitchItem · ListCheckItem · ListRadioItem) — 줄 전체가 라벨이라 줄 어디를 눌러도 끼운 스위치 · 체크 · 라디오가 바뀐다.

모든 줄에 공통인 값(상태마다 바뀌는 값은 아래 State):

공통

Align제목 링크 복사

맞춤의 기본은 가운데(center)다 — 앞 · 뒤가 본문의 세로 가운데에 선다. 제목이 두 줄을 넘거나 설명이 길면 위(top)로 맞춘다. 한 목록 안에서는 줄마다 맞춤을 섞지 않는다.

맞춤

Highlight제목 링크 복사

새 알림처럼 주목이 필요한 줄은 바탕을 옅은 브랜드 색(bg-brand-weak)으로 바꾼다(highlighted). 바탕만 바뀐다 — 점 · 왼쪽 막대는 두지 않는다(사용자 결정, SEED 와 같다). 읽음 · 안 읽음처럼 상태를 알리는 자리는 제목 · 설명의 글로도 알 수 있게 쓴다.

강조 줄을 올리거나 누르면 바탕이 bg-brand-weak-pressed 로 짙어지고, 그동안만 설명 · 값 글자를 한 단계 짙은 fg-neutral-muted 로 바꾼다 — fg-neutral-subtle 은 짙은 강조 바탕 위에서 4.32:1 로 글자 기준(4.5:1)에 모자란다(사용자 결정). 제목 · 화살표는 그대로다.

강조

강조 — 올리거나 누를 때

State제목 링크 복사

누르는 줄 · 컨트롤 줄은 호버 · 포커스 · 누름 · 비활성을 가진다. 보기만 하는 줄은 상태가 없고(누를 것이 없다), 링크 줄은 막지 않는다 — 갈 수 없는 곳이면 줄을 빼거나 누르는 줄로 바꿔 막는다.

모드 때문에 누를 수 없는 줄은 보기 줄 색 — 순서 바꾸기 모드처럼 화면의 모드가 잠시 줄 누르기를 거둔 줄(카테고리의 부모 줄)은 막힌 줄(disabled)이 아니라 보기만 하는 줄이다 — 누름 · 호버 · 포커스가 없고, 제목 · 설명 · 타일은 보통 줄의 색 그대로다. 줄이 고장 나 못 쓰는 것이 아니라 지금 모드에서 할 일이 다를 뿐이라 fg-disabled 로 흐리지 않는다. 앱은 PListParentItem.readOnly(누름 · 포커스 없음 · 보통 줄 색 — 누를 일이 없는 "막힌 줄" 과 다르다), 웹은 누르지 않는 줄(보기만 하는 줄의 짜임)로 같은 모습이다(2026-10-25 I-20 앱).

상태마다 enabled 에서 바뀌는 값:

호버 hovered

포커스 focused

누름 pressed

비활성 disabled

모션

합계에 안 드는 줄제목 링크 복사

예정(아직 빠지지 않은 돈) · 환불(취소된 돈) 거래처럼 화면의 합계에 들지 않는 줄은 불투명도로 흐리지 않는다 — 줄 전체를 흐리면 그 줄을 가르는 단서인 배지까지 흐려진다. 대신 이렇게 둔다(사용자 결정 2026-10-03).

• 제목 · 금액만 fg-neutral-subtle(흰 바탕 5.50 · 다크 6.09) — 훑어볼 때 합계에 드는 줄과 갈린다.
• 환불된 금액은 취소선을 긋는다. 취소선은 보조 기술이 읽지 않으므로 뜻은 배지 글("환불됨")이 말한다.
• 상태 Badge("예정" · "환불됨" · "기록만" — weak neutral)는 보통 대비 그대로다(6.58 · 5.93).
• 앞 타일 · 설명 줄은 보통 줄과 같다. 누름 · 호버 · 포커스도 보통 줄과 같다(막힌 줄이 아니다).

Prefix제목 링크 복사

앞 붙이개는 줄이 무엇인지 먼저 알린다.

• 아이콘 22(fg-neutral) — 설정 · 메뉴 줄.
• 타일 40(모서리 12) — 색이 뜻을 가진 내용 줄(거래 · 카테고리 · 알림 종류). 바탕은 카테고리 색의 옅은 바탕(chart-{색}-weak, v111), 아이콘 20 은 그 색이다. 아이콘이 없는 카테고리는 태그 아이콘(lucide tag) 하나로 그린다 — 빈 칸 · 첫 글자를 넣지 않는다. 이체 줄은 회색(chart-gray-weak + chart-gray)이다 — 카테고리가 아니라 돈의 이동이다. 크기를 바꾸면 모서리도 크기 × 0.3 으로.
• 로고 타일 40(Logo Tile) — 은행 · 증권 · 카드 · 코인 · 금 같은 물건 줄(자산 · 계좌 관리). 기관 색 + 첫 글자, 그림이 있으면 덮는다. 막힌 줄에서도 그대로다.
• 카드 그림 56(Image Frame 의 카드 그림) — 카드 혜택 목록처럼 카드 자체가 줄인 자리. 폭 56 · 카드 비율.
• 아바타(Avatar — 한 줄이면 36, 이름 + 설명 두 줄이면 42) · 체크 · 라디오(컨트롤 줄 — 24).

Suffix제목 링크 복사

• 값 글자(16 · fg-neutral-subtle) — 지금 고른 값(기본 통화 "대한민국 원").
• 오른쪽 화살표(18 · fg-neutral-subtle) — 화면을 옮기는 줄에만.
• 스위치 32 · 체크 24 · 라디오 24 — 컨트롤 줄. 스위치는 제목 16 줄이라 32 다(Switch 스펙).
• 작은 버튼 · 금액 — 금액은 16 / 22 · 700 · 고정폭 숫자(DESIGN.md Typography 의 "글자 역할" R13). 색은 지출 · 이체 fg-neutral, 수입만 fg-brand("+" 와 함께) — 금액을 빨갛게 칠하지 않는다. 빨강은 증감(▲) 한 뜻이다(2026-10-16 사용자 결정 — 글자 역할 D1). 합계에 안 드는 줄(예정 · 환불)은 아래처럼 fg-neutral-subtle.

바탕이 보이는 줄 끝 버튼은 상자 끝을 끝선에 맞춘다 — neutralWeak · neutralOutline 처럼 상자가 보이는 버튼은 줄의 값 끝과 같은 끝선(화면 여백 24)에 상자 끝이 온다. 글 끝을 끝선에 맞추려고 14 를 번지게 하는 것은 상자가 안 보이는 글 버튼(ghost · List Header 동작)뿐이다 — 상자가 보이는 버튼을 번지게 하면 상자가 화면 여백을 먹고 줄 값과 끝선이 어긋난다(2026-10-31).

줄 끝 작은 버튼은 누르는 영역 44 가 줄보다 이긴다 — 뒤 붙이개의 작은 버튼(문자 함 줄의 [×] · 기기 줄의 [로그아웃] 같은 줄 끝 동작)은 보이는 상자가 44 보다 작아도 누르는 영역 44 를 지키고, 그 44 안을 누르면 줄이 아니라 버튼이 눌린다. 글 버튼이 줄 여백 쪽으로 번져(블리드) 보이는 글 밖에 놓인 자리도 같다 — 버튼 둘레를 눌렀는데 옆의 줄이 대신 열리면 안 된다. 웹은 Button 의 누르는 영역(::before 44)이 줄 전체를 덮는 누르는 층(누르는 줄 버튼 · 링크의 ::after) 위에 선다 — 뒤 붙이개 안의 버튼 · 링크는 그 층보다 한 단계 위(z-index 1)다. 앱은 줄이 PTouchTargetScope 로 버튼의 넓힌 영역을 이어 받는다 — PButton 이 공용 PTouchTarget 을 써서 스코프가 찾는다(2026-10-24 I-12-1 앱 재검수 · desk-app #470).

제목 뒤 배지는 줄이 바뀌면 앞 틈 없이 — 제목 뒤에 붙인 배지(기본 · 예정 · 기록만)는 제목과 사이 간격으로 띄우고, 제목이 길거나 글자가 커져 배지가 다음 줄 맨 앞에 서면 앞 틈을 두지 않는다 — 배지가 제목 글의 왼쪽 선에 맞는다. 그래서 틈은 배지의 왼쪽 여백이 아니라 제목 · 배지 묶음의 사이 간격으로 준다(웹 flex-wrap 의 gap · 앱 Wrap(spacing) — 줄 맨 앞이면 틈 0). 배지에 왼쪽 여백(웹 ml-* · 앱 앞 Padding)을 달면 두 줄째 맨 앞 배지가 글보다 안으로 들어간다(2026-10-24 I-12-1).

값이 길 때제목 링크 복사

뒤 붙이개는 줄지 않고 본문이 양보한다 — SEED List Item 과 같다(뒤 붙이개 flexShrink 0 · 본문 flexGrow 1). 값이 길어 본문이 눌려도 겹치지 않게 세 가지만 둔다(2026-10-15 사용자 결정 — 구현 세션 질문 Q-001, 안 A · 본문 최소 폭은 2026-10-30 사용자 결정 B 로 바꿨다).

• 본문은 제목의 가장 긴 낱말 폭까지 준다 — 그보다 좁아지지 않는다(min-width: min-content, 제목은 낱말 단위 keep-all). 뒤 여백 10 은 따로다. "장소" 처럼 짧은 제목은 한 줄 그대로 서고, 값이 남은 폭에서 줄을 바꾼다. 옛 규칙(한 글자 1em 까지)은 줄 칸 폼의 긴 글 값 옆 제목을 "장 / 소" 로 쪼갰다(2026-10-30 사용자 결정 B — https://claude.ai/artifact/V9Pd3RcTcrttDKZXzZUFix). 줄 제목은 이름 한두 낱말로 짧게 쓴다. 공백 없는 긴 제목(한 낱말이 줄 안 폭 − 앞 붙이개의 절반을 넘는 것)은 그 절반에서 글자 사이로 끊는다 — 값이 줄의 절반 아래로 밀리지 않게(2026-10-30 구현 검수).
• 제목은 낱말 단위로만 바꾼다(Typography v114 — keep-all + break-word) — 본문이 가장 긴 낱말보다 좁아지지 않으니 글자 사이에서 끊을 일이 없다. 설명은 칸 끝에서 끊는다(overflow-wrap: anywhere) — 평소에는 단어 단위로 바꾸고, 본문 폭이 설명의 낱말 하나보다 좁을 때만 글자 사이에서 끊어 칸 밖으로 넘치지 않는다. 설명을 Tag Group 으로 그리면 그 스펙대로 한 줄 말줄임이다.
• 글 값(이메일 · 계좌번호 · 긴 이름 · 장소)은 줄 끝에서 끊는다 — 본문이 제목 낱말 폭이 된 뒤에도 남는 폭보다 길면 줄 끝에서 줄을 바꾼다. 본문 위로 넘쳐 덮지 않는다. 레시피는 suffix 에 글을 그대로 넘긴 값 글자만 이렇게 다룬다. 값은 줄 수와 상관없이 줄 끝 오른쪽 맞춤이다 — 두 줄 · 세 줄이어도 모든 줄의 오른쪽 끝이 한 줄 값과 같은 세로선에 선다(글 맞춤 end, 꺾쇠가 있는 줄은 꺾쇠 앞이 끝선). 값이 제목 옆에 붙어 줄마다 값 자리가 달라 보이면 안 된다(2026-10-30 사용자 지적). 좁은 줄에서 본문 아래로 내려간 값만 왼쪽 맞춤이다(아래 "큰 글자에서 값을 본문 아래로").

금액 · 화살표 · 스위치 · 작은 버튼은 그대로 한 덩어리다 — 금액은 한 줄로 서고, 본문이 그만큼 눌린다. 값을 줄여 적는 것(억 단위 등)은 그 화면이 정한다. 값을 아래 줄로 내리기(안 B) · 값 종류로 가르기(안 C) · 가운데를 잘라 줄이기(안 D)는 고르지 않았다 — 값 폭으로 가르는 규칙은 없다. 줄 자체가 좁을 때만 아래 "큰 글자에서 값을 본문 아래로" 가 값을 내린다.

본문 · 뒤 붙이개의 폭

큰 글자에서 값을 본문 아래로제목 링크 복사

줄 안 폭이 제목 글자 16개(16em)보다 좁을 때만 값(글 값 · 금액 · 배지)을 본문 아래로 내린다(2026-10-17 사용자 결정 — 03-D 목록 · 카드 · 표 비교 페이지 결정 1 B). 글자를 130 · 200% 로 키우면 긴 값 옆 제목이 한 글자 폭 기둥이 되어 줄 하나가 화면 세 장 길이가 됐다(360 · 200% 웹 1,872 ~ 2,390 · 앱 1,872 ~ 2,318).

• 이것은 Q-001 A 의 예외이고, 기준이 다르다. 내려가는 모양은 위에서 고르지 않은 Q-001 안 B · C(값 폭 · 값 종류로 가르기)와 같지만, 기준은 값의 길이가 아니라 줄 안 폭이다 — 글자 배율 · 화면 폭으로 줄이 좁아질 때만이다. 줄 안 폭이 16em 이상이면 값이 아무리 길어도 위 "값이 길 때"(Q-001 A) 그대로다.
• 줄 안 폭 = 줄 폭 − 좌우 여백(앞 붙이개 · 꺾쇠 단추 자리는 들어간다). em 은 제목 글자(t5) 크기라 글자 배율을 따라 커진다 — 보통 글자에서 256 이라 320 폰(줄 안 272)까지 지금과 같고, 360 폰(줄 안 312)은 글자 약 122% 부터(130% 면 15em) 내려간다. 화면이 고르지 않는다 — 줄이 스스로 잰다(웹 16rem 컨테이너 쿼리 · 앱 LayoutBuilder 로 16 × t5 × 글자 배율, 같은 값).
• 모양 — 제목 · 설명 · 값이 위아래로 쌓이고 제목이 줄 안 폭을 다 쓴다. 값은 설명 아래 4(본문 사이 2 + 2), 본문 칸 안 왼쪽 맞춤이다. 앞 붙이개는 위에 맞춘다. 금액은 쉼표 뒤에서만 줄을 바꾸고(결정 2 B — Typography v114 의 예외, 웹 <wbr> · 앱 U+200B), 글 값(이메일 · 계좌번호)은 Q-001 A 그대로 줄 끝에서 끊는다.
• 목록은 폭이 정해진 부모 안에 둔다(웹) — 줄(li)이 폭을 재는 컨테이너(container-type: inline-size)라, 내용 폭으로 크기를 정하는 부모(inline-block · w-max · w-fit 팝오버 · 가로 flex 의 auto 항목) 안에서는 줄 폭이 0 이 된다. 블록 · 화면 폭 · 폭을 정한 팝오버(알림 380 처럼) · 시트 안에 둔다. 앱은 LayoutBuilder 라 해당 없다(2026-10-22 I-02 웹 검수).
• 뒤 붙이개의 배지는 값 쪽이다 — 금액 옆 상태 배지처럼 뒤 붙이개에 둔 Badge 는 누르지 않는 보이기만 하는 글이라 값과 함께 본문 아래로 내려간다(2026-10-29 I-29 — 앱 splitListSuffix 가 PBadge 를 값으로 가른다, 웹은 버튼 · 링크 · 입력 · 아이콘이 아닌 뒤 붙이개를 값으로 내린다).
• 조작 요소는 줄 끝 그대로 — 화살표 · 스위치 · 체크 · 라디오 · 작은 버튼은 내리지 않는다(2026-10-17 사용자 결정 — 누르는 자리를 옮기지 않는다). 글자 배율 상한(150% 에서 멈추기)은 두지 않는다 — 고르지 않았다.

좁은 줄 — 값을 본문 아래로

Detail제목 링크 복사

설명은 제목 아래 2 떨어져 13 으로 쓴다. 제목만으로 무엇인지 알 수 있으면 두지 않는다. 길어지면 두 줄까지, 그 이상이면 맞춤을 위로 바꾼다. 분류 · 자산 · 시각처럼 여러 메타를 잇는 설명 줄은 Tag Group(t3 · 한 줄 말줄임)이다.

목록 제목(List Header)제목 링크 복사

목록 밖, 바로 위에 두는 제목이다. 두 가지다.

• mediumWeak(기본) — 14 · 500 · fg-neutral-subtle. 줄보다 앞서지 않는다.
• boldSolid — 14 · 700 · fg-neutral. 화면을 크게 나누는 묶음에만.

오른쪽 작은 버튼은 큰 글자에서 오른쪽 동작이 머리 폭의 절반을 넘으면 제목 아래 줄 오른쪽 끝으로 내린다 — 제목은 한 줄 전체 폭으로 읽히고 머리가 버튼 한 줄(36)만큼 높아진다. 평소(100% · 130%)는 한 줄 그대로다. Button 짝의 반 폭 판정과 같고, 카드 머리 · 아코디언 목록 머리 · List Header 가 같은 규칙이다(2026-10-21 사용자 결정 — 03-G 결정 4 A, https://claude.ai/artifact/A3oCdxNvDwkNBPFPE36bmF). 판정 — 동작의 보이는 상자 폭(글 + 좌우 14 · 14)에서 끝 블리드 14(머리 여백으로 내어 걸리는 몫)를 빼고 사이 10 를 더한 값이 머리 안쪽 폭의 절반 이하면 한 줄, 넘으면 내린다. 레시피의 flex 줄바꿈(제목 최소 50%)이 그대로 이 셈이다 — 예: 머리 안쪽 300 이면 오른쪽 버튼 보이는 상자 154 까지 한 줄 · 155 부터 내려간다(카드 머리 · 아코디언 목록 머리 156 / 157 · List Header 는 사이가 10 이라 154 / 155). 결정 페이지(https://claude.ai/artifact/A3oCdxNvDwkNBPFPE36bmF) · 보류 둘 결정 페이지(https://claude.ai/artifact/7ENKeRYQMzFijZHnf5kaP7)의 그림은 상자 폭 ≤ 절반으로 그렸다 — 이 셈과 6 이하로 갈려 그림의 어느 경우도 달라지지 않는다(200% 에서 360 화면 "모두 펼치기" 154 는 한 줄, 320 화면 "전체 보기" 130 은 한 줄 · "모두 펼치기" 는 내려감). 웹 · 앱 모두 이 셈으로 판정한다.

오른쪽에 작은 버튼(도움말 · 전체 보기)을 둘 수 있다 — 글이면 글 버튼(SEED Text Button 14 · 700 · fg-neutral-muted · 보이는 36 · 위아래로 블리드해 줄 높이를 바꾸지 않는다, 2026-10-16 사용자 결정 — 글자 역할 D2). Card 머리 동작과 같은 값이다. 화면 맨 위 제목 · 카드 제목은 목록 제목이 아니다 — 카드 제목은 Card 의 머리(16 / 22 · 700, 2026-10-08)다.

제목 태그 — 목록 제목은 머리말이다(웹 h2 기본 · 앱 headingLevel: 2) — 화면 제목(1) 아래 단계라 카드 제목과 같은 단계다. 카드 · 대화상자 · 시트처럼 자기 제목(2)을 가진 상자 안이면 한 단계 아래(웹 as="h3" · 앱 3)로 내린다. 오른쪽 작은 버튼이 있으면 제목 태그는 제목 글에만 걸고 버튼은 제목 밖(나란한 형제)에 둔다 — 제목을 줄 전체에 걸면 머리말 이름이 "카테고리별 예산 전체 보기" 처럼 버튼 글과 섞여 읽힌다. 앱 PListHeader 가 이미 이렇게 한다(제목 글만 Semantics(header), 버튼은 밖). Card 의 CardTitle · CardAction 과 같은 방식이다(2026-10-22 — 03-D 조사 03D-007 · 02-004 의 웹 짝, I-02 웹 재검수).

목록 제목

목록 제목 — 공통

줄 사이 선(ListDivider)제목 링크 복사

줄 사이 선은 기본으로 두지 않는다 — 줄의 위아래 여백이 줄을 가른다. 촘촘한 목록 · 설명 없는 긴 목록처럼 구분이 필요할 때만 ListDivider(1px · stroke-neutral-subtle)를 넣는다. 줄 폭 전체가 기본이고, 앞 붙이개가 있는 목록은 들일 수 있다(좌우 24). 목록 밖의 구분선은 Divider(같은 색) 다.

하위 줄 — 접는 부모 줄제목 링크 복사

카테고리처럼 부모 · 하위 두 단계로 된 목록에서 줄 자체는 편집을 열고 하위 줄만 접을 때는, 부모 줄 앞에 꺾쇠 단추를 둔다(nest="parent" — 2026-10-10 사용자 결정 7C). 단추는 보이는 상자가 곧 누르는 영역 44 이고, 줄 앞 4 · 단추 뒤 4 를 지나 앞 붙이개가 52 에서 시작한다. 꺾쇠는 lucide chevron-right 20 fg-neutral-subtle — 접혀 있으면 오른쪽, 펼치면 아래로 90° 돈다(300ms — Accordion 과 같다). 이름은 "{카테고리} 하위 카테고리" 로 고정하고 펼침은 aria-expanded 가 알린다 — "접기 · 펼치기" 로 바꾸지 않는다. 하위 줄(nest="child")은 부모의 제목 자리 104(= 4 + 44 + 4 + 타일 40 + 12)에서 시작해 하위 타일이 부모 제목 아래에 선다 — 누름 바탕은 줄 폭 그대로다. 하위가 없는 부모 줄 · 늘 펼쳐 두는 화면(편집 모드)도 꺾쇠 자리를 같은 폭으로 비워 부모 타일이 모두 52 에 선다 — 타일이 두 세로줄(52 · 104)로 정리된다(사용자 결정 17B). 처음 펼침은 화면이 정한다 — 카테고리는 지금처럼 모두 펼친 채 연다(기본 지출 카테고리의 하위는 0 ~ 6개).

늘 펼쳐 두는 화면(편집 모드)은 이름 있는 스위치 collapsible={false} 로 켠다 — 꺾쇠 단추를 그리지 않고(자리는 같은 폭으로 비운다), 하위 줄은 늘 보이며 aria-expanded 를 두지 않는다. Tree View 의 collapsible 과 같은 이름 · 같은 뜻이다. 접을 수 있는 부모 줄(collapsible 기본 true)은 꺾쇠 단추의 이름 expandLabel 이 필수다 — 하위가 없는 줄에도 같은 이름을 준다(하위가 생기면 바로 단추가 선다). 이름을 빠뜨리면 레시피 타입이 막는다 — 이름을 빼서 조용히 늘 펼침이 되던 옛 레시피는 걷었다(2026-10-15 사용자 결정 — 구현 세션 질문 Q-002, 안 B).

이 줄은 편집 대화상자를 여는 줄이라 오른쪽 화살표를 달지 않는다(화살표는 화면을 옮기는 줄에만) — 지금 앱처럼 접힌 부모 줄에 › 가 둘(접힘 · 이동) 생기지 않는다. 여러 단계에서 하나를 고르는 나무는 Tree View 다. 접기를 걷는 안(7B)과 부모 줄 전체를 펼치기로 · 편집은 ⋮(7D)는 고르지 않았다.

단계

펼침

꺾쇠 단추 — 상태

늘 펼침 — collapsible={false}

Guidelines제목 링크 복사

모든 줄을 List 로제목 링크 복사

설정 · 메뉴 · 선택 · 키-값 줄과 거래 · 할 일 · 메모 · 알림 같은 내용 줄을 모두 List 줄로 그린다(사용자 결정). 줄의 여백 · 글자 · 누름 · 구분선은 List 가 정하고, 앞의 타일 · 뒤의 금액처럼 그 화면만의 자리만 화면이 채운다.

목록 제목으로 묶기제목 링크 복사

줄이 많으면 목록 제목으로 묶는다. 같은 묶음은 어느 화면에서나 같은 모양이어야 한다 — "카테고리별 예산" 이 화면마다 다른 크기로 그려지지 않게.

누르는 줄만 누르게제목 링크 복사

화면을 옮기는 줄에만 오른쪽 화살표를 단다. 화살표가 있는데 눌리지 않는 줄, 눌리는데 아무 표시가 없는 줄을 만들지 않는다. 보기만 하는 줄은 호버 · 누름 바탕이 생기지 않는다.

줄 안의 누르는 것은 셋 이하제목 링크 복사

한 줄에 따로 누르는 것(줄 자체 · 작은 버튼)은 셋 이하로 둔다 — 넷 이상은 피한다(SEED List "4개 이상 지양"). 넷째가 필요하면 줄을 나누거나 상세 화면으로 옮기는 쪽을 먼저 본다. 스위치 · 체크 · 라디오를 끼운 줄에는 다른 버튼을 두지 않는다(아래 "스위치 · 체크 · 라디오 줄")(2026-10-22 사용자 결정 5B — https://claude.ai/artifact/SmHD31RQxTjWbfK83nbcym).

줄의 동작은 들어간 화면에제목 링크 복사

목록 줄 끝에는 ⋮(더보기)를 두지 않는다 — 가계부든 카테고리 설정이든 같다. 줄을 누르면 한 단계 들어가고(상세 · 수정), 그 항목의 동작은 들어간 화면에 둔다 — 하나(삭제)면 바닥 왼쪽 [삭제](Button ghost + critical), 여럿이면 머리 오른쪽 ⋮ → Menu(1280 미만 Menu Sheet). 폰의 밀기는 지름길로 남는다. 줄에 ⋮ 를 둘 수 있는 건 콘텐츠가 높은 카드(사진 · 여러 줄 · 버튼이 든 카드)의 머리뿐이고, 데스크톱 데이터 표의 줄은 이 규칙 밖이다(Table) — 규칙 전문은 Menu 의 "줄의 동작"(2026-10-25 사용자 결정).

스위치 · 체크 · 라디오 줄제목 링크 복사

스위치 · 체크 · 라디오를 끼우면 줄 전체가 라벨이 된다 — 줄 어디를 눌러도 바뀐다. 이 줄에는 따로 누르는 버튼을 같이 넣지 않는다. 약관처럼 따로 볼 내용은 제목 안의 링크로 두고, 그 링크를 눌러도 줄의 값이 바뀌지 않게 한다. 줄을 누르면 줄의 콘텐츠가 함께 줄고, 끼운 스위치 · 체크 · 라디오는 따로 줄지 않는다(v104).

하나 고르기 · 여럿 고르기제목 링크 복사

목록에서 하나를 고르면 라디오(24)를 뒤에, 여럿을 고르면 체크(24)를 앞이나 뒤에 둔다(사용자 결정, SEED). 고른 것과 안 고른 것이 모두 보인다. 한 묶음에서 라디오와 체크를 섞지 않고, 하나 고르기는 두 줄 이상이어야 한다.

거래 · 이체 같은 내용 줄의 고르기 모드는 체크(앞) + 앞 타일 + 뒤 값 줄이다 — 체크 다음에 그 줄의 타일을 앞 붙이개 사이만큼 띄워 잇고, 뒤 값(금액)은 보이기만 한다. 줄 어디를 눌러도 체크가 바뀌고 따로 누르는 것은 두지 않는다(위 "스위치 · 체크 · 라디오 줄"). 체크를 뒤에 두는 줄은 지금처럼 뒤 붙이개가 체크 하나다(2026-10-25 07-2 — 웹 ds ListCheckItem 의 markPosition="prefix" + prefix + suffix).

끌 수 없는 켬 — 칸만 막는다제목 링크 복사

체크 줄 가운데 늘 켜져 있어야 하는 줄(숨길 수 없는 기본 캘린더)은 칸만 막힌 켬(Checkbox disabled + checked — 회색 칸 · 회색 체크)으로 두고, 제목 · 앞 붙이개(색 점 · 타일) · 배지는 보통 줄과 같은 색이다(locked). 줄 전체를 막는 disabled 를 쓰지 않는다 — 제목이 회색이면 "꺼진 것" 으로 읽히고, 그 줄의 색 점이 사라진다. 끌 수 없는 까닭은 배지(예: "기본")가 말한다. 줄은 누르지 못하고 포커스에서 빠지며(막힌 칸과 같다), 보조 기술은 "개인, 기본, 체크됨, 사용할 수 없음" 으로 읽는다(2026-10-29 사용자 결정 B — https://claude.ai/artifact/71eeYtuohccHruWQ4YcpQM).

<ListCheckItem locked title={<>개인 <Badge>기본</Badge></>} />

여백을 바꿀 때제목 링크 복사

줄의 여백은 화면에 맞게 바꿀 수 있다 — 단 토큰으로만, 좌우는 24 보다 좁히지 않고, 한 목록 안에서는 줄마다 같게.

카드 안의 목록제목 링크 복사

카드 안에 목록을 넣으면 누름 바탕의 모서리를 카드 모서리에서 카드 가장자리 ~ 바탕 거리를 뺀 값으로 맞춘다(동심 모서리). 기본 10 은 모서리 16 인 카드에 줄을 바로 넣은 경우다 — 바탕이 좌우 6 들어오므로 16 − 6. 카드에 안쪽 여백을 더 두면 그만큼 더 뺀다. 그대로 두면 바탕의 둥근 정도가 카드와 어긋난다. 레시피에서는 목록(List · ListRadioGroup · ListCheckGroup)의 itemRadius 로 바꾼다(SEED 의 itemBorderRadius). 목록을 담은 카드의 머리 · 여백은 Card 의 목록 카드다 — 카드 안 여백은 줄과 같은 24(머리 위 · 좌우 24, 카드 아래 12 + 줄 12 — 2026-10-08).

목록을 두는 바탕제목 링크 복사

목록은 흰 바탕(bg-layer-default)이나 시트 · 대화상자(bg-layer-floating) 위에 둔다. 누름 · 호버 바탕(bg-layer-default-pressed)이 불투명한 색이라, 회색 바탕(bg-layer-basement) 위에서는 바탕과 거의 같아(라이트 1.02:1) 눌러도 보이지 않는다. 그래서 놓이는 바탕에 따라 고른다 — 흰 면(띠 · 카드 · 흰 화면 · 시트 · 대화상자) 위에서는 그대로 두고, 회색 바닥 위에서는 흰 면을 먼저 깐다. 어느 화면이 띠 · 흰 화면 · 카드인지는 DESIGN.md Layout 의 "화면 바탕" 한 곳에 적는다(폰 화면은 이관 때 화면마다 고른다 — 2026-10-22 사용자 결정 3B, https://claude.ai/artifact/KrXqAymDPz1JKL5AWqdwKS).

앞 붙이개 고르기제목 링크 복사

설정 · 메뉴 줄은 아이콘, 색이 뜻을 가진 내용 줄은 타일이다(사용자 결정). 물건(은행 · 카드 · 증권) 줄은 로고 타일이다. 한 묶음 안은 같은 종류로 둔다 — 자산 목록은 로고 타일, 거래 목록은 카테고리 타일. 앞 붙이개가 섞이면 왼쪽 시작선 · 크기가 갈린다(SEED "List 안에서 각 Item 의 정렬이 달라지지 않도록"). 다른 물건이 한 결과에 나오면(거래와 자산을 함께 찾는 검색) 목록 제목(거래 · 자산)으로 묶음을 나눈다(2026-10-22 사용자 결정 6B — https://claude.ai/artifact/SmHD31RQxTjWbfK83nbcym).

값 글 — 빈 값 · 사라진 값 · 기관제목 링크 복사

• "없음" 이 답인 줄(계좌·카드 · 카테고리 · 결제 수단) — "{칸 이름} 없음" fg-placeholder. Select 의 "없음" 선택지와 같은 글이다.
• 꼭 고르는 줄(이체의 보내는 · 받는 계좌) — "없음" 선택지가 없으니 "{칸 이름} 선택" fg-placeholder(Input Button 의 placeholder 글). 저장을 누르면 줄 아래 Field 오류로 알린다.
• 목록에서 사라진 기록 값 — 거래를 고칠 때 이미 지운 계좌 · 카테고리는 기록이니 값을 지우지 않고 "지운 계좌" · "지운 카테고리" 로 보인다. "없음" 으로 보이면 저장되는 값과 말이 어긋난다. 프리셋 · 문자로 채운 값은 기록이 아니므로 비우고 칸 오류로 알린다.
• "{기관} · {이름}" — 상세 값 줄의 꼴이다. 기관과 이름이 같으면 한 번만 쓴다("삼성카드"). 폼 값은 이름만.

코드제목 링크 복사

레시피 recipes/shadcn/components/ui/list.tsx 를 쓴다 — List · ListItem · ListButtonItem · ListLinkItem · ListSwitchItem · ListCheckItem · ListCheckGroup · ListRadioGroup · ListRadioItem · ListDivider · ListHeader · ListTile · ListParentItem. 아래 미리보기는 스펙 값으로 그린 모습이다.

ListParentItem 은 하위 줄을 접는 부모 줄이다 — ListButtonItem 의 속성(title · detail · prefix · suffix · onClick …)에 collapsible(기본 true) · expandLabel(꺾쇠 단추의 고정 이름 — collapsible 이면 필수) · open · defaultOpen · onOpenChange(open) 을 더 받고, 자식(ListButtonItem …)이 하위 줄이 된다. 자식이 없으면 꺾쇠 자리를 비운다. collapsible={false} 는 늘 펼친 편집 화면이다 — 꺾쇠 자리를 비우고 하위 줄을 늘 보이며, expandLabel · open · defaultOpen · onOpenChange 를 받지 않는다. 두 갈래는 유니언 타입이라 collapsible={false} 없이 expandLabel 을 빠뜨리면 타입 오류다({ collapsible?: true; expandLabel: string; open?; defaultOpen?; onOpenChange? } | { collapsible: false }). 꺾쇠 단추(aria-expanded · aria-controls)와 하위 줄 묶음(ul — 104 들임 · 높이 300ms)은 줄이 그린다. 한 목록에 ListParentItem 이 있으면 그 목록의 맨 위 단계 줄은 모두 ListParentItem 이다 — 타일 자리를 맞춘다.

라우터의 링크는 ListLinkItem asChild 의 자식으로 넣는다 — 제목 · 설명은 그 링크 안에 그려진다(<ListLinkItem asChild title="도움말"><Link to="/help" /></ListLinkItem>).

기본제목 링크 복사

import { List, ListItem } from "@/components/ui/list"

<List>
  <ListItem title="가입일" suffix="2026년 3월 2일" />
  <ListItem title="이메일" suffix="[email protected]" />
</List>

누르는 줄제목 링크 복사

import { ChevronRight, Globe, User } from "lucide-react"
import { List, ListButtonItem, ListHeader } from "@/components/ui/list"

<ListHeader id="settings-general">일반</ListHeader>
<List aria-labelledby="settings-general">
  <ListButtonItem prefix={<User />} title="계정" suffix={<ChevronRight />} onClick={openAccount} />
  <ListButtonItem prefix={<Globe />} title="기본 통화" suffix={<>대한민국 원<ChevronRight /></>} onClick={openCurrency} />
</List>

컨트롤 줄제목 링크 복사

import { Bell } from "lucide-react"
import { List, ListSwitchItem } from "@/components/ui/list"

<List>
  <ListSwitchItem
    prefix={<Bell />}
    title="결제 알림"
    detail="결제 예정일 D-1, 결제일 당일 알림"
    checked={on}
    onCheckedChange={setOn}
  />
</List>

하나 고르기 · 여럿 고르기제목 링크 복사

import { ListCheckGroup, ListCheckItem, ListRadioGroup, ListRadioItem } from "@/components/ui/list"

<ListRadioGroup value={currency} onValueChange={setCurrency} aria-label="기본 통화">
  <ListRadioItem value="KRW" title="대한민국 원" detail="KRW" />
  <ListRadioItem value="USD" title="미국 달러" detail="USD" />
</ListRadioGroup>

<ListCheckGroup aria-label="내보낼 항목">
  <ListCheckItem title="거래 내역" defaultChecked />
  <ListCheckItem title="예산" />
</ListCheckGroup>

강조 · 비활성 · 맞춤제목 링크 복사

import { Info } from "lucide-react"
import { List, ListButtonItem, ListItem } from "@/components/ui/list"

<List>
  <ListButtonItem highlighted title="예산 80% 도달" detail="식비 예산의 80%를 썼어요" />
  <ListButtonItem disabled title="주간 리포트" detail="푸시 알림이 꺼져 있어요" />
  <ListItem align="top" prefix={<Info />} title="긴 제목은 두 줄을 넘으면 앞 · 뒤를 위로 맞춘다" detail="설명이 길 때도 같다" />
</List>

하위 줄 — 카테고리제목 링크 복사

import { Tag, Utensils } from "lucide-react"
import { List, ListButtonItem, ListParentItem, ListTile } from "@/components/ui/list"

<List aria-label="지출 카테고리">
  {/* 줄을 누르면 편집, 앞 꺾쇠 단추가 하위 줄을 접는다 — 이름은 고정 */}
  <ListParentItem
    prefix={<ListTile className="bg-chart-orange-weak text-chart-orange"><Utensils /></ListTile>}
    title="식비 · 외식 · 배달음식"
    detail="지출 · 하위 6개"
    onClick={() => editCategory(food.id)}
    expandLabel="식비 · 외식 · 배달음식 하위 카테고리"
    defaultOpen
  >
    {food.children.map((c) => (
      <ListButtonItem key={c.id} prefix={renderTile(c)} title={c.name} detail="지출" onClick={() => editCategory(c.id)} />
    ))}
  </ListParentItem>
  {/* 하위가 없으면 꺾쇠 자리만 비운다 — 타일 · 제목이 같은 자리. 이름은 같이 준다(하위가 생기면 단추가 선다) */}
  <ListParentItem
    prefix={<ListTile className="bg-chart-gray-weak text-chart-gray"><Tag /></ListTile>}
    title="기타"
    detail="지출 · 하위 없음"
    onClick={() => editCategory(etc.id)}
    expandLabel="기타 하위 카테고리"
  />
</List>

하위 줄 — 늘 펼친 편집 화면제목 링크 복사

import { List, ListButtonItem, ListParentItem } from "@/components/ui/list"

<List aria-label="지출 카테고리 편집">
  {/* 늘 펼친 편집 화면 — 꺾쇠 단추 없이 하위 줄이 늘 보인다(Tree View 의 collapsible 과 같은 뜻) */}
  {categories.map((c) => (
    <ListParentItem
      key={c.id}
      collapsible={false}
      prefix={renderTile(c)}
      title={c.name}
      detail={c.children.length ? `지출 · 하위 ${c.children.length}개` : "지출 · 하위 없음"}
      onClick={() => editCategory(c.id)}
    >
      {c.children.map((k) => (
        <ListButtonItem key={k.id} prefix={renderTile(k)} title={k.name} detail="지출" onClick={() => editCategory(k.id)} />
      ))}
    </ListParentItem>
  ))}
</List>

Behavior제목 링크 복사

Accessibility제목 링크 복사

Do / Don't제목 링크 복사

✅ Do제목 링크 복사

• 설정 · 메뉴 · 선택 · 키-값 · 내용 줄을 모두 List 로 그린다.
• 화면을 옮기는 줄에만 오른쪽 화살표를 단다.
• 줄의 동작은 줄을 눌러 들어간 화면에 둔다 — 하나면 바닥 [삭제], 여럿이면 머리 ⋮.
• 컨트롤 줄은 줄 전체가 눌리게 한다.
• 막힌 줄은 제목 · 설명 · 아이콘을 모두 비활성 색으로.
• 끌 수 없는 켬(늘 켜진 체크 줄)은 칸만 막고(locked) 제목 · 앞 붙이개는 그대로 — 까닭은 배지로.
• 줄은 편집 · 하위만 접는 목록은 줄 앞 꺾쇠 단추(44 · 고정 이름 + 펼침 상태)로.
• 늘 펼쳐 두는 편집 화면은 collapsible={false} 로 — 이름 있는 스위치로 켠다.
• 긴 글 값(이메일 · 계좌번호)은 그대로 두고 줄 끝에서 끊기게 둔다 — 본문은 제목의 가장 긴 낱말 폭까지 양보한다.

❌ Don't제목 링크 복사

• 화면마다 줄을 손으로 짜기 — 여백 · 글자 · 누름이 화면마다 갈린다.
• 화살표가 있는데 안 눌리는 줄 · 눌리는데 표시가 없는 줄.
• 컨트롤 줄에 따로 누르는 버튼을 같이 넣기.
• 한 줄에 누르는 것 넷 이상.
• 목록 줄 끝에 ⋮(더보기) — 줄에 ⋮ 를 둘 수 있는 건 콘텐츠가 높은 카드 머리뿐이다.
• 한 묶음에서 라디오 · 체크 섞기.
• 끌 수 없는 켬을 상자 없는 체크 · 줄 전체 막힘으로 그리기 — 못 바꾼다는 것이 안 보이거나, 켜진 것이 꺼진 것처럼 보인다.
• 줄 높이를 줄이려고 스위치 · 체크의 누르는 영역을 자르기.
• 하위를 접는 꺾쇠를 18 · 24 로 작게 · 이름을 "접기 · 펼치기" 로 바꾸기 · 접힌 부모 줄에 › 를 둘 달기.
• expandLabel 을 빼서 늘 펼침을 만들기 — 접는 줄은 이름이 필수다(타입 오류). 늘 펼침은 collapsible={false}.
• 값이 본문 위로 넘쳐 덮게 두기 · 뒤 붙이개에 최대 폭이나 말줄임을 따로 걸기.

Specification제목 링크 복사

list.yaml · list-header.yaml 의 규칙을 하나도 빼지 않고 조건마다 그린다 — 웹 · 앱이 List 를 만들 때 이 값을 그대로 쓴다. 조건이 없는 Base 가 모든 조합에 걸리고, 뒤의 규칙이 앞의 같은 값을 덮는다. 상태는 enabled 에서 바뀌는 값만 적었다.