ADR-0016: 색과 곡률, 표면 처리를 참조 디자인에 맞춘다

상태

Accepted

날짜

2026-08-13

맥락

토큰 값은 Spartan 생성기가 넣은 기본값을 그대로 쓰고 있었습니다. zinc 팔레트에 순백 배경, 무채색 --primary, 10px 반경입니다. 검증된 조합이지만 이 표준을 쓰는 화면이 다른 shadcn 계열 사이트와 구분되지 않습니다.

작성자가 운영하는 블로그(Astro)의 디자인을 참조 대상으로 삼기로 했습니다. 이미 만족스럽게 사용 중인 시각 언어이므로 취향을 재발명하지 않아도 되고, 실제 운영에서 겪은 문제와 그 대응이 코드에 남아 있어 근거를 함께 가져올 수 있습니다.

토큰 이름과 구조는 Spartan 체계를 유지합니다. helm 컴포넌트가 이미 토큰을 경유하므로 값만 교체하면 화면 전체가 따라옵니다.

결정

색은 값만 교체합니다

:root의 토큰 값을 교체하고 컴포넌트 코드는 건드리지 않습니다. 컴포넌트마다 색을 직접 지정하는 방식은 디자인 시스템과 토큰 3.4절이 금지하는 임의 색상값 기재가 되며, 같은 색이 여러 파일에 흩어집니다.

토큰	라이트	다크
`--background`	`#fefefe`	`#18181b`
`--foreground`	`#1a1a1a`	`#f4f4f5`
`--primary`	`#2563eb`	`#60a5fa`
`--border` · `--input`	`#e4e4e7`	`#3f3f46`

라이트 배경에서 순백을 피합니다. 채도가 있는 색을 얹었을 때 더 선명하게 보이고 장시간 읽을 때 눈이 덜 부십니다.

--card는 배경과 같은 색이며 경계로 구분합니다. 표면을 밝기로 쌓지 않는 것이 참조 디자인의 방식입니다.

텍스트 위계를 세 단계로 늘립니다. 참조 디자인이 본문·보조·삼차의 세 단계를 쓰는데 우리는 두 단계였습니다. 실측 결과 우리 --muted-foreground가 참조 디자인의 삼차 단계와 대비까지 일치했으므로(라이트 양쪽 4.32:1), 중간 단계 하나만 추가합니다.

--foreground-secondary라는 이름을 쓰는 이유는 Spartan의 --secondary가 버튼 변형용 배경이며 --secondary-foreground와 쌍을 이루기 때문입니다. 텍스트 위계와 역할이 다릅니다.

곡률은 기준값 하나로 조정합니다

--radius를 0.625rem에서 1rem으로 올립니다. Spartan 프리셋이 이 값에 배수를 곱해 sm부터 4xl까지를 만들므로, 기준값 하나를 바꾸면 체계 전체가 따라옵니다.

토큰	계산값	참조 디자인의 대응
`--radius-sm`	9.6px	배지 10px
`--radius-lg`	16px	유리 알약 16px
`--radius-xl`	22.4px	커버 이미지 20px
`--radius-2xl`	28.8px	카드 28px

모서리는 corner-shape: superellipse(1.6)으로 그립니다. 원호는 직선에서 곡선으로 넘어가는 지점이 눈에 띄는데 초타원은 곡률이 연속이라 그 꺾임이 없습니다. 반경이 클수록 차이가 드러나므로 기본값으로 둡니다.

corner-shape는 아직 Baseline이 아닙니다. @supports로 감싸므로 미지원 브라우저에서는 선언이 무시되어 일반 원호로 그려지며 레이아웃과 크기는 달라지지 않습니다. 완전한 원이 필요한 자리는 corner-round로 되돌립니다.

상단 바의 불투명도는 토큰이 정합니다

참조 디자인은 라이트에서 75% 반투명에 블러를 걸고 다크에서는 불투명으로 처리했습니다. 코드 주석에 "스크롤 시 밝아지고 버벅여서"라는 사유가 남아 있습니다.

원인을 계산했습니다. 다크 배경 위로 흰 요소가 지나갈 때 툴바의 밝기 상승은 다음과 같습니다.

불투명도	밝기 상승
75%	800%
85%	370%
95%	87%

문제는 다크 모드 자체가 아니라 75%라는 수치였습니다. 라이트 65%, 다크 85%로 두어 양쪽 모두 반투명을 유지합니다.

bg-background/85 같은 알파 유틸리티를 쓰지 않고 --toolbar 토큰을 새로 둡니다. 알파 유틸리티는 라이트와 다크에 같은 값이 적용되고, dark: 변형은 사용자가 모드를 고르기 전에 .dark 클래스가 없어 작동하지 않습니다. 판단의 원본이 color-scheme이므로 그것을 읽는 light-dark()를 써야 합니다.

이 제약은 앞으로 모든 반투명 표면에 동일하게 적용됩니다.

종이 질감은 선택 항목입니다

body에 paper-grain 클래스를 붙였을 때만 켜집니다. 기본값은 꺼짐입니다.

본 저장소는 규범집이므로 적용 대상 화면의 성격이 고정되어 있지 않습니다. 읽는 화면에는 어울리지만 표와 폼이 빽빽한 업무 화면에서는 작은 글자의 가독성을 떨어뜨립니다.

층위는 z-index: 60입니다. 상단 바(40) 위에는 얹되 오버레이(CDK 기본 1000) 아래에 두어 모달과 시트는 질감 없는 표면을 유지합니다. 참조 디자인의 9999를 그대로 쓰면 모달 위에도 덮이는데, 그쪽은 오버레이가 검색 하나뿐이라 드러나지 않았던 부분입니다.

검토한 대안

토큰 값을 유지하고 컴포넌트에 색을 직접 적용

구분	내용
장점	기존 팔레트를 쓰는 화면과 새 팔레트를 쓰는 화면이 공존할 수 있습니다
단점	같은 색이 여러 파일에 흩어지고, 어느 화면이 어느 계보인지 규칙이 따로 필요합니다
기각 사유	디자인 시스템과 토큰 3.4절의 임의 색상값 금지와 충돌합니다. helm 이 이미 토큰을 경유하고 있어 값 교체만으로 목적이 달성됩니다

표면 색만 교체하고 `--primary`는 무채색 유지

구분	내용
장점	버튼의 인상이 바뀌지 않아 변경 범위가 좁습니다
단점	링크·강조·활성 표시·포커스 링이 참조 디자인과 달라집니다
기각 사유	참조 디자인에서 파랑이 강조의 중심입니다. 그것을 빼면 색을 가져오는 의미가 남지 않습니다

따뜻한 종이색 배경 (`#f5f2eb`)

구분	내용
장점	참조 디자인의 원래 값이며 종이 느낌이 가장 강합니다
단점	노란 기운이 뚜렷해 화면 성격에 따라 과합니다
기각 사유	작성자가 확인 후 `#fefefe`를 선택했습니다. 배경이 중성이 되면서 경계와 표면의 warm 계보도 함께 중성으로 정리했습니다

종이 질감을 전역 기본으로 적용

구분	내용
장점	별도 설정 없이 모든 화면이 같은 질감을 갖습니다
단점	업무 화면의 가독성과 성능을 표준이 일방적으로 결정하게 됩니다
기각 사유	본 저장소는 화면 성격이 고정되지 않은 규범집입니다. 판단을 프로젝트에 남깁니다

결과

토큰 값 교체만으로 화면 전체의 인상이 바뀝니다. 컴포넌트 코드는 한 줄도 수정하지 않았습니다.

감수하는 사항은 다음과 같습니다.

참조 디자인의 색을 그대로 쓰지 못한 곳이 있습니다. --warning 라이트를 L 0.55에서 0.545로 낮췄고, --destructive 다크는 참조 값(#f87171) 대신 기존 값을 유지했습니다. 둘 다 접근성 6절의 4.5:1 기준에 걸렸습니다. 참조 디자인의 다크 삼차 텍스트는 3.67:1로 기준 미달입니다.
corner-shape를 보는 사용자와 못 보는 사용자가 갈립니다. 미지원 브라우저에서는 일반 원호로 보입니다. 같은 화면이 기기마다 다르게 보이는 것을 ADR-0014에서 배제했으나, 그때는 글꼴 폴백이라 자간과 줄바꿈까지 달라지는 문제였고 여기서는 모서리 곡률만 달라집니다.
종이 질감을 켜면 대비 여유가 줄어듭니다. 실측으로 라이트에서 0.24, 다크에서 0.63 하락합니다. 4.5:1을 겨우 넘는 색은 질감을 켠 화면에서 기준 아래로 내려갑니다.
질감 레이어가 QHD 기준 약 14MB를 점유합니다. 상단 바가 backdrop-filter를 쓰는 화면에서는 합성이 두 겹이 됩니다. 실제 스크롤 성능은 측정하지 않았으며, 문제가 드러나면 클래스를 떼는 것이 첫 번째 대응입니다.
light-dark() 제약이 넓어집니다. 모드별로 다른 값이 필요한 모든 속성이 토큰을 거쳐야 합니다. opacity처럼 색이 아닌 속성은 light-dark()를 쓸 수 없어 prefers-color-scheme과 :root.dark를 각각 다뤄야 합니다.

폰트는 바꾸지 않았습니다. ADR-0014의 결정을 그대로 유지합니다.