1
2
3
4
5
6
화면을 이루는 레이아웃 · 색 · 선 · 컴포넌트가 스타일마다 어떻게 달라지는가.
같은 카드 하나를 여섯 스타일로 그려 비교하고, 그 차이를 그대로 에이전트 지시문으로 옮긴다. 접근성과 다크/라이트 모드까지.
모호한 지시
"좀 더 예쁘게 / 요즘 느낌으로" — 에이전트는 플랫인지 글래스인지 브루탈인지 추측한다.
정확한 지시
"Neobrutalism 톤으로 — 3px 검정 테두리, 하드 오프셋 그림자, 라운드 0, 고채도 단색" — 한 번에 맞춘다.
각 슬라이드는 이렇게 읽는다
부록 ①(컴포넌트 도감)이 "부품 이름"이라면, 이 도감은 "그 부품을 칠하는 화풍"이다.
화면을 나누는 골격
그리드, 영역(헤더/사이드/메인/푸터), 반응형 분기점. 스타일과 무관하게 먼저 정해진다.
스타일을 숫자로
색/간격/라운드/그림자/타이포 값. "스타일"의 정체는 결국 이 토큰들의 조합이다.
토큰을 입은 부품
버튼/카드/입력창 등. 부록 ①의 부품들이 ②의 토큰을 입어 최종 모습이 된다.
12 컬럼 그리드
넓은 화면을 12등분해 컴포넌트를 칸에 맞춘다. 카드 3개 = 4칸씩, 본문+사이드 = 8+4. 숫자로 말하면 에이전트가 정확히 배치한다.
간격(gutter) / 여백
8pt 그리드 — 모든 간격을 8의 배수(8/16/24/32)로. 들쭉날쭉함이 사라지고 리듬이 생긴다.
최대 폭(max-width)
본문은 무한정 늘리지 않는다. 읽는 글은 65~75자, 컨테이너는 1100~1280px에서 멈추고 가운데 정렬.
같은 카드 1~6번이 폭에 따라 1 → 2 → 3열로 재배치
모바일 우선(mobile-first)
좁은 화면을 기본으로 짜고, 넓어질 때 칸을 늘린다. 거꾸로보다 깨짐이 적다.
분기점(breakpoint)
관습값 — sm 640 / md 768 / lg 1024 / xl 1280px. 폭이 이 선을 넘으면 열 수/사이드바 노출이 바뀐다.
컨테이너 쿼리
화면이 아니라 "그 컴포넌트가 놓인 칸의 폭"에 반응. 카드가 어디에 들어가도 알아서 접힌다.
토큰이란
색/간격/라운드/그림자/글꼴 같은 값에 이름을 붙인 것. --space-4, --radius-md, --color-primary처럼.
원시 → 의미 토큰
원시값(blue-600)을 의미(primary, danger)로 한 번 더 감싼다. 다크모드/리브랜딩 때 의미 토큰만 바꾸면 끝.
왜 에이전트에게 중요한가
토큰으로 말하면 "예쁘게"가 재현 가능한 명세가 된다. 일관성/테마 전환/유지보수가 공짜로 따라온다.
/* 원시 팔레트 */
--blue-600:#2563eb; --gray-900:#0f172a;
/* 간격 — 8pt 스케일 */
--space-1:4px; --space-2:8px;
--space-4:16px; --space-6:24px;
/* 라운드 / 그림자 */
--radius-md:8px; --radius-full:999px;
--shadow-md:0 4px 12px rgba(0,0,0,.1);
/* 의미 토큰(이 줄만 다크모드서 교체) */
--color-primary:var(--blue-600);
--color-surface:#fff;
--color-text:var(--gray-900);역할별 색(semantic)
중립(neutral) 한 줄 — 배경/테두리/본문 회색 스케일. 화면 면적의 대부분은 이 무채색이 채운다.
60 / 30 / 10 규칙
바탕 60% (중립) / 보조 30% / 강조 10%. 강조색을 아껴 써야 버튼/CTA가 눈에 들어온다.
상태(state) 변종
버튼 하나에도 hover/active/disabled/focus 색이 필요. 보통 기본색의 명도를 ±10% 조정해 만든다.
명도 스케일
각 색은 50~900 명암 단계로. 라이트는 600 전후, 다크모드는 400 전후를 주조로 쓰면 대비가 산다.
TYPE SCALE — 한 배율(예: 1.25)로 키운다
제목 H1 40
소제목 H2 30
강조 본문 22
본문 16~18 — 읽기 편한 행간 1.5, 한 줄 65~75자.
캡션 13 — 보조 정보
위계(hierarchy)
크기/굵기/색의 대비로 "먼저 읽을 것"을 정한다. 3~4단계면 충분.
행간/자간/줄폭
본문 line-height 1.5, 줄폭은 측정값(measure) 65~75자. 한글은 word-break: keep-all로 어절 보존.
8pt 간격 스케일
padding/margin/gap을 4·8·16·24·32로 통일. 임의값(13px, 19px) 금지 → 정렬이 저절로 맞는다.
왜 쓰나
색/간격/컴포넌트/접근성 규칙이 이미 검증돼 있다. "이 시스템 따르라"는 한 줄이 토큰 수백 개를 대신한다.
고르는 법
플랫폼/생태계에 맞춰 — 구글앱=Material, 애플=HIG, 윈도우=Fluent, 엔터프라이즈=Carbon/Ant, React 빠른 제작=shadcn/ui.
에이전트에게
"shadcn/ui + Tailwind로, 컴포넌트는 그 레지스트리에서 가져와 토큰만 우리 브랜드 색으로."
유틸리티 우선(utility-first)
CSS 파일을 새로 쓰는 대신, 미리 정의된 작은 클래스(p-4, rounded-lg, bg-blue-600)를 조합해 마크업에서 바로 스타일링한다.
// 간격 p-4=16px, 색 bg-blue-600 → 팔레트
<button class="px-4 py-2 rounded-lg
bg-blue-600 text-white font-semibold
hover:bg-blue-700 focus:ring-2
/* 반응형: 기본 1열 → md 2열 */
md:px-6 lg:text-lg">
결제하기
</button>장점
단점 / 주의
npm 의존성이 아니다
CLI가 컴포넌트 소스 코드를 내 저장소로 복사한다. 그 파일을 내가 소유하고 자유롭게 고친다. 접근성은 Radix UI, 스타일은 Tailwind 토큰이 담당.
# 필요한 컴포넌트만 골라 내 코드로
npx shadcn@latest add button card dialog
✔ components/ui/button.tsx ← 내가 소유
✔ components/ui/card.tsx
✔ components/ui/dialog.tsx (Radix 기반)
# 테마: CSS 변수로 색/라운드/다크모드장점
단점 / 주의
| 이 도감의 개념 | Tailwind CSS | shadcn/ui |
|---|---|---|
| 디자인 토큰 | theme 설정 + CSS 변수(색/라운드/그림자) | CSS 변수 테마를 그대로 사용 |
| 8pt 간격 스케일 | p-1/2/4/6 = 4/8/16/24px | 컴포넌트가 이 간격 클래스로 조립됨 |
| 타입 스케일 | text-sm/base/lg/xl/2xl | 동일 스케일로 위계 표현 |
| 반응형 분기점 | sm:/md:/lg:/xl: 접두사 | 블록이 이미 반응형으로 설계 |
| 다크/라이트 | dark: variant + .dark 클래스 | 의미 CSS 변수 교체로 자동 전환 |
| 화풍(스타일) | 유틸 조합 / 테마 프리셋 | Themes/tweakcn로 토큰 세트 교체 |
| 컴포넌트(부록①) | 직접 유틸로 조립 | 레지스트리에서 add 해 소유 |
| 접근성 | 직접 챙겨야 함(포커스/ARIA) | Radix로 기본 탑재 |
| 스타일 | 색 | 선/테두리 | 그림자 | 라운드 | 접근성 |
|---|---|---|---|---|---|
| Flat | 솔리드 채도 | 얇은 1px | 없음/약함 | 작게 4~8 | 좋음 |
| Material | primary 위계 | 거의 없음 | elevation | 4 | 좋음(가이드 내장) |
| Neumorphism | 저채도 단일톤 | 없음 | 이중(밝/어둠) | 크게 12~20 | 취약(저대비) |
| Glassmorphism | 반투명+배경색 | 옅은 흰선 | 부드럽게+blur | 중간 12~16 | 주의(대비/성능) |
| Neobrutalism | 고채도 원색 | 두꺼운 검정 | 하드 오프셋 | 0 | 대비 좋음/요란 |
| Minimal/Swiss | 무채색+1강조 | 최소 | 없음 | 0~4 | 좋음 |
의미 토큰만 교체
--color-surface/text/border 값을 다크용으로 바꾸면 컴포넌트는 그대로 따라온다.
순검정 금지
배경은 #000이 아니라 #15171c 같은 짙은 회색. 텍스트도 순백 대신 #e5e7eb로 눈부심을 줄인다.
다크 전용 보정
그림자 대신 표면 밝기로 높이 표현. 강조색은 한 단계 밝게(600→400). 이미지/그림자 대비 재확인.
자동 전환
prefers-color-scheme로 OS 설정 따라가기 + 수동 토글 둘 다 제공.
WCAG 명암비 기준
본문 텍스트 4.5:1 이상(AA), 큰 글자/아이콘 3:1 이상. 저대비 스타일(뉴모/글래스)일수록 따로 확인.
색만으로 정보 전달 금지
"빨강=오류"를 색으로만 주지 않는다. 아이콘/라벨/텍스트를 함께 — 색각 이상 사용자 배려.
상태별 대비 유지
disabled/placeholder도 너무 흐리지 않게. hover/focus에서 대비가 깨지지 않는지 확인.
다크모드 재검증
라이트에서 통과해도 다크에서 떨어질 수 있다. 두 테마 모두 측정.
시맨틱 HTML 우선
button/nav/main/label 같은 의미 태그를 div 대신. 스크린리더와 키보드가 공짜로 동작한다. 부족할 때만 ARIA로 보강.
키보드 전용 통과
Tab으로 모든 동작 도달, 순서는 시각 순서와 일치. 모달은 포커스 가두기(trap) + ESC 닫기.
포커스 링 살리기
outline:none 금지. 보이는 포커스 표시(2px 링, 3:1 대비). 미니멀/뉴모처럼 경계가 옅을수록 더 또렷이.
터치 타깃 / 대체텍스트
누르는 영역 최소 44×44px. 이미지 alt, 폼 입력엔 연결된 label, 아이콘 버튼엔 aria-label.
목적 있는 움직임
상태 변화/연속성/피드백을 알릴 때만. 장식용 과한 애니메이션은 피로를 준다.
짧고 자연스럽게
전환 150~300ms, ease-out 계열. UI는 빠르게, 큰 영역일수록 약간 길게.
마이크로 인터랙션
hover 살짝 밝게, press 눌림, 토글 슬라이드, 로딩 스켈레톤 — 작은 반응이 품질감을 만든다.
접근성: 모션 줄이기
전정기관 민감 사용자를 위해 prefers-reduced-motion을 존중 — 큰 이동/패럴랙스는 끄고 페이드로 대체.
@media (prefers-reduced-motion: reduce){
* { animation:none; transition:none; }
}실제 웹사이트 — 무드/스타일 찾기
영감/콘셉트 — 디자이너 작업물
앱/제품 UI 패턴 — 화면 단위
컴포넌트/시스템 레퍼런스
지시 템플릿(붙여 쓰기)
# 1. 레이아웃
대시보드 셸 — 좌측 고정 사이드바, 상단 KPI 3,
본문 차트+표 8:4. max-width 1280, 8pt 그리드.
# 2. 스타일/토큰
Flat 베이스. primary #2563eb, 중립 회색 스케일,
radius 8 통일, elevation 2단계, 60/30/10 배분.
# 3. 컴포넌트
버튼 pill·hover 한 단계 밝게, 카드 lv1 그림자.
# 4. 테마
light/dark 의미 토큰, prefers-color-scheme + 토글.
# 5. 접근성
명암비 AA, 포커스 링, 키보드 전 기능, 터치 44px.레이아웃 → 토큰 → 컴포넌트 순으로 분리하고, 스타일은 이름 + 값으로 못박는다.
다크/라이트와 접근성(AA·포커스·키보드)은 옵션이 아니라 기본 명세에 넣는다.
레이아웃 · 화풍 · 토큰 · 다크모드 · 접근성 · 모션 — 각 장의 "예시 보기" 링크로 실제 사례를 바로 확인하며 에이전틱 코딩 지침으로 쓰세요.