처음 배우는 디자인 시스템

이 단계에서는 무엇을 하나요?

지금까지 정한 디자인을 AI가 읽을 수 있게 모아요. 기준 화면, 토큰 목록, 사용 규칙을 연결하는 단계예요.

그림·토큰·설명은 맡은 일이 달라요

토큰이 16이라고 해서 어디를 16만큼 띄울지까지 정해지지는 않아요. “카드 안쪽 여백에 이 토큰을 사용한다”처럼 적용 위치도 적어야 해요.

1. 자료를 한 프로젝트 폴더에 모아요

프로젝트 폴더는 앱의 코드와 자료를 함께 두는 폴더예요. 아래 이름은 실습용 예시예요. 같은 역할의 파일이 이미 있다면 기존 파일과 위치를 사용하세요.

폴더는 누가 만드나요?

1. 작업할 프로젝트 폴더는 직접 정해요. 이미 앱을 만들고 있다면 그 폴더를 Codex에서 열어요. 새 작업이라면 폴더 하나를 만들거나 도구에서 새 프로젝트를 시작해 그 위치를 열어요.
2. 그 안의 하위 폴더와 문서는 AI에게 만들도록 요청해요. 아래 표의 폴더를 전부 손으로 만들 필요는 없어요. AI가 실제로 생성한 위치를 확인하면 돼요.
3. 원본 자료는 접근할 수 있게 전달해요. 화면 이미지·사진·아이콘·토큰 파일을 작업 폴더에 넣거나 AI에게 첨부해요. 실제 자료 없이 빈 폴더만 만든 상태와 구분하세요.

2. DESIGN.md에 화면을 만드는 기준을 적어요

1. 기준 화면을 지정해요. 실제 프레임 링크 또는 이미지 위치, 기준 너비를 적어요.
2. 토큰 목록의 위치를 적어요. 같은 값을 계속 복사하기보다 어느 목록이 현재 기준인지 정해요.
3. 배치 규칙을 적어요. 요소 순서, 화면 좌우·카드 안쪽 여백, 긴 내용 처리 방법을 적어요.
4. 부품과 상태를 연결해요. 사용할 버튼 종류와 처리 중·실패 때의 동작을 적어요.
5. 미정 항목을 남겨요. 원본과 문서가 다르면 어느 쪽을 따를지도 확인해요.

문서 내용의 예

# 앱 디자인 기준

## 기준 자료
- 기준 화면: [실제 Figma 프레임 링크 또는 이미지 위치]
- 토큰 목록: [실제 파일 위치]
- 부품 설명: [실제 파일 위치 또는 이 문서의 해당 항목]
- 기준 너비: 390 CSS px. 360 / 390 / 430에서도 확인한다.

## 공통 배치
- 화면 콘텐츠는 좌우 16 CSS px 여백 안에 배치한다.
- 활동 카드에는 제목, 시간·장소, 행동 버튼을 위에서 아래로 배치한다.
- 긴 제목은 줄바꿈하고 카드 높이를 내용에 맞춰 늘린다.
- 작은 화면에서도 글자와 버튼이 가로로 잘리지 않도록 한다.
- 색과 간격에는 확정한 토큰을 연결해서 사용한다.

## 부품 사용
- 같은 역할의 버튼은 같은 코드 컴포넌트를 사용한다.
- 문구가 다르다는 이유만으로 새 버튼을 만들지 않는다.
- 처리 중에는 진행 상태를 표시하고 중복 요청을 막는다.
- 실패하면 입력 내용을 유지하고 재시도 방법을 알린다.

## 아직 결정할 것
- [확인하지 못한 값·상태·자료]

## 변경 기록
- [날짜 / 바뀐 기준 / 이유 / 적용할 화면]

3. 부품의 사용 설명을 상황으로 적어요

CONTRACT.md에는 “이 부품을 어떤 조건으로 어떻게 쓰는지”를 적어요. 파일 이름은 이 실습의 약속이며 필수 표준 이름은 아니에요.

실제 사용 장면을 떠올리면 무엇을 정해야 하는지 더 쉬워져요. 아래 세 가지는 사용 규칙의 예시예요. 본인 앱의 기획에 맞춰 조정하고, 실제 코드 위치와 설정값 이름은 구현 후 확인해서 적어요.

## 신청 버튼

- 쓰는 곳: 신청 화면 아래의 주요 행동 버튼.
- 기본 모습: 기존 주요 버튼 스타일을 사용하고 “신청하기”를 표시한다.
- 누르면: 신청 처리를 시작하고 “신청 처리 중…”으로 문구를 바꾼다.
- 처리 중: 다시 눌러도 요청을 추가로 실행하지 않는다.
- 성공하면: 기획에서 정한 신청 완료 안내를 보여준다.
- 실패하면: 입력한 내용을 유지하고 오류 문구와 재시도 방법을 보여준다.
- 다시 시도할 수 있으면: 문구를 “신청하기”로 돌리고 버튼을 누를 수 있게 한다.
- 확인: 결과가 늦게 나올 때 여러 번 눌러도 신청 결과가 중복되지 않는지 본다.

## 이름 입력창

- 구성: “이름”이라는 항목 이름 + 입력하는 칸 + 필요한 경우 오류 문구.
- 처음 화면을 열면: 입력이 비어 있어도 오류부터 보여주지는 않는다.
- 이름 없이 신청하면: 신청 처리를 시작하지 않고 입력창 아래에 “이름을 입력해 주세요”를 표시한다.
- 공백만 입력한 경우도 이름을 적지 않은 것으로 본다.
- 오류 모습: 정한 오류 테두리와 안내 문구를 함께 사용한다. 빨간색만으로 알리지 않는다.
- 입력 중: 다른 항목에 이미 적은 내용은 그대로 유지한다.
- 이름을 적고 다시 신청하면: 이 항목의 오류를 해제하고 다음 조건을 확인한다.
- 확인: 빈칸·공백만 입력·이름 입력의 세 경우를 각각 시험한다.

## 활동 카드

- 구성: 활동 제목 + 시간·장소 + 모집 상태 + 상세 보기 경로 + 신청 버튼.
- 모집 중이면: “모집 중”을 표시하고 신청 버튼을 사용할 수 있게 한다.
- 마감되면: 상태를 “모집 마감”으로 바꾸고 신청 버튼을 비활성화한다.
- 마감 이유: 버튼 근처에 “신청 기간이 끝났어요”를 표시한다.
- 상세 정보: 마감됐어도 활동 제목의 상세 보기 경로는 사용할 수 있게 한다.
- 제목이 길면: 줄바꿈하고 카드 높이를 내용에 맞춰 늘린다.
- 여러 카드: 같은 카드 컴포넌트를 사용하고 제목·일정·모집 상태만 다르게 전달한다.
- 확인: 모집 중/마감 두 경우와 긴 제목을 넣고, 상세 보기와 신청 동작을 따로 눌러 본다.

4. AI가 먼저 읽을 자료를 연결해요

문서를 저장한 다음에는 AI가 실제로 읽었는지 확인해요. Codex에서는 AGENTS.md에 읽을 자료와 작업 규칙을 적어둘 수 있어요. Claude Code를 쓴다면 CLAUDE.md로 안내해요.

AI에게 자료 정리부터 요청하기

현재 열어 둔 프로젝트 폴더 안에 필요한 하위 폴더와 문서를 실제로 생성하고 디자인 자료를 정리해줘. 아직 화면 구현은 시작하지 마.
기존 폴더·파일이 있으면 그대로 사용하고, 없을 때만 만들어줘.
원본 자료가 없으면 빈 폴더를 자료가 준비된 것으로 표시하지 말고 필요한 파일을 알려줘.

1. 기준 화면, 토큰 목록, 사진·아이콘 원본, 기획 문서의 실제 위치를 찾아줘.
2. Figma 링크가 있다면 실제로 읽을 수 있는지 확인해줘.
   읽지 못한 자료는 추측하지 말고 “읽지 못함”으로 표시해줘.
3. 확정한 토큰과 디자인을 바꾸지 말고 docs/DESIGN.md에 사용 규칙을 정리해줘.
4. 반복되는 버튼 하나의 구성·종류·상태·동작을 docs/CONTRACT.md에 정리해줘.
   아직 코드가 없으면 코드 경로와 Prop 이름은 확정하지 마.
5. AGENTS.md에 UI 작업 전 위 자료를 읽고 기존 토큰·부품을 재사용하도록 안내해줘.
6. 같은 역할의 문서가 이미 있다면 기존 파일을 사용하고 위치를 알려줘.

마지막에 자료 / 실제 위치 / 읽기 성공 여부 / 아직 필요한 정보 표를 보여줘.

필요할 때: Google DESIGN.md 형식으로 정리하기

Google Labs는 AI에게 시각적 기준을 전달하는 공개 DESIGN.md 형식을 제공해요. 직접 쓰는 설명 문서와 특정 도구가 검사하는 정식 형식은 구분하세요. 먼저 내용을 확정하고, 해당 도구를 쓸 때 그 버전의 명세에 맞추면 돼요.

YAML은 이름과 값을 구조적으로 적는 표기이고, lint는 정해진 형식에 맞는지 검사하는 일이에요. 형식 검사를 통과해도 실제 화면이 잘 만들어졌다는 뜻은 아니에요.

공식 저장소 · 현재 형식 명세

이 단계에서는 무엇을 하나요?

7장에서 정리한 자료로 대표 화면 하나를 브라우저에서 실행되는 코드로 만들어요. 반복되는 버튼·카드를 재사용하도록 정리하고, 실제 동작 하나를 연결해요.

1. 가진 디자인을 읽을 수 있게 전달해요

이미지에는 원래 요소 이름이나 정확한 간격 값이 들어 있지 않을 수 있어요. 추정한 부분은 따로 확인하고 결정하세요. Figma 링크도 연결과 권한이 있어야 읽을 수 있어요.

2. 기존 프로젝트와 실행 방법부터 확인해요

Codex나 Claude Code에서 자료를 모아 둔 프로젝트 폴더를 열어요. 이미 코드가 있다면 같은 앱을 새로 만들지 말고 현재 프로젝트를 사용해요.

첫 요청: 자료와 현재 상태 확인

이 프로젝트의 기획·DESIGN.md·부품 설명과 기준 화면을 먼저 읽어줘.
이번에는 [화면 이름] 하나만 구현할 거야.

아직 코드를 수정하지 말고 아래를 정리해줘.
- 실제로 읽은 디자인 자료와 읽지 못한 자료
- 기존 프로젝트를 실행하는 방법
- 토큰 코드와 공통 컴포넌트의 실제 위치
- 지금 재사용할 수 있는 것 / 아직 만들어야 하는 것
- 구현 전에 내가 결정해야 하는 항목

기존 코드가 없다면 화면 하나를 실행하는 데 필요한 최소 구성을 제안해줘.
설치가 필요하면 프로그램 이름·이유·설치 방법을 먼저 알려줘.

3. 조사한 값과 확정한 기준을 구분해요

화면에서 뽑은 값은 조사 결과예요. 비슷한 초록 두 개를 합칠지, 서로 다른 역할로 유지할지는 직접 결정해야 해요.

값이 아직 정리되지 않았다면

기준 화면에서 색·글자·간격·모서리·반복 부품을 조사해줘.
항목 / 확인한 값 / 어느 화면의 어느 요소인지 / 근거를 표로 보여줘.
이미지에서 추정한 값과 실제 자료에서 읽은 값을 구분해줘.
아직 값을 합치거나 디자인·코드를 바꾸지 마.

그다음 같은 역할인데 다른 값인 항목을 찾아
합칠 후보 / 유지할 차이 / 내가 결정할 항목으로 제안해줘.
내가 선택한 기준만 다음 작업에 반영해줘.

4. 토큰을 화면 코드에 연결해요

Figma Variable은 Figma 안의 값이에요. 웹에서는 코드가 읽을 수 있는 값이 필요해요. 같은 이름·역할을 맞춰 옮기고 화면이 그 값을 참조하도록 연결해요.

Figma와 코드 사이의 자동 반영은 별도의 연결을 구성했을 때 가능해요. 지금은 어느 쪽을 변경하고 다른 쪽에 어떻게 반영할지 정해 관리하면 돼요.

5. 화면 하나를 구현하고 실행해요

기준을 적용해서 화면 만들기

확정한 DESIGN.md와 토큰 목록으로 [화면 이름] 하나를 구현해줘.

1. 현재 프로젝트의 실행 방식과 파일 구조를 유지해줘.
2. 토큰과 Button·Card 등 공통 컴포넌트가 있으면 먼저 재사용해줘.
3. 코드가 없다면 이 화면에 필요한 토큰과 반복 부품부터 만들어줘.
   승인한 이름·값과 실제 코드의 대응표를 남겨줘.
   새로운 디자인 값은 임의로 추가하지 마.
4. 기준 디자인의 글자·사진·아이콘을 배치해줘.
   원본 파일이 없으면 대체하기 전에 알려줘.
5. 기준 너비는 390 CSS px로 보고 360 / 390 / 430에서도 가로로 잘리지 않게 해줘.
   긴 제목은 줄바꿈하고 콘텐츠 높이는 내용에 맞춰 늘어나게 해줘.
6. 아직 없는 기능은 동작하는 척하지 말고 이번 구현 범위와 구분해줘.

완료하면 실행 주소, 바꾼 파일, 토큰·부품 코드 위치,
직접 확인한 결과와 내가 확인해야 할 항목을 알려줘.

1. AI가 알려준 실행 주소를 브라우저에서 열어요. localhost나 127.0.0.1은 보통 내 컴퓨터에서 시험하는 주소예요. 공유용 공개 주소와 구분해요.
2. 하얀 화면이나 오류가 나오면 그 상태부터 알려 해결해요. 화면이 떠야 원본과 비교할 수 있어요.
3. 기준 너비에서 원본과 나란히 보고 글자·색·간격·카드 모서리를 비교해요.
4. 360 / 390 / 430 너비로 바꿔 보아요. 방법을 모르면 현재 브라우저에서 확인할 절차나 너비별 캡처를 AI에게 요청해요.

6. 버튼의 실제 동작 하나를 연결해요

모양을 만든 다음에는 어떤 상태를 거쳐 어떤 결과가 나와야 하는지 하나만 연결해요. 먼저 기획에서 정한 동작과 현재 저장·요청 방식이 있는지 확인해요.

예: 신청 버튼의 상태와 동작

신청 화면의 버튼에 기획에서 정한 신청 동작을 연결해줘.
디자인과 기존 토큰·Button 컴포넌트는 유지해줘.

- 필수 입력이 빠졌으면 누락된 항목과 수정 방법을 알려준다.
- 요청하는 동안 “신청 처리 중…”을 표시한다.
- 처리 중 다시 눌러도 요청이 중복으로 실행되지 않도록 한다.
- 성공하면 기획에서 정한 완료 상태를 보여준다.
- 실패하면 입력 내용을 유지하고 다시 시도할 수 있게 한다.

먼저 현재 저장·요청 방식이 실제로 있는지 확인해줘.
없다면 서버나 저장 방식을 임의로 정하지 말고 필요한 결정을 알려줘.
실습용 성공·실패 모형으로 확인한다면 실제 신청과 분명히 구분해줘.
완료 후 정상·누락·연속 클릭·실패를 직접 확인할 순서를 알려줘.

7. 같은 모습과 같은 부품 재사용을 확인해요

재사용 여부 확인 요청

방금 만든 화면을 DESIGN.md와 부품 설명에 맞춰 확인해줘.
화면 요소 / 사용하는 토큰 / 재사용 부품 / 실제 코드 위치를 표로 보여줘.

같은 부품을 화면 안에 새로 만든 부분과
이름만 같고 값은 직접 입력한 부분이 있는지 찾아줘.
실행해서 확인한 것과 코드만 읽고 판단한 것을 구분해줘.
규칙이 없어 판단할 수 없는 항목은 “결정 필요”로 남겨줘.

연결 도구는 필요할 때 선택해요

이 도구를 모두 설치해야 실습할 수 있는 것은 아니에요. 작은 화면 하나를 만들고 같은 기준을 재사용하는지 확인하는 것부터 시작하세요.

Figma MCP 공식 설명 · Code Connect 공식 설명

이 단계에서는 무엇을 하나요?

AI가 “완료”라고 말한 화면을 원본과 비교하고 직접 눌러 보아요. 문제를 기록해 수정한 뒤 같은 조건으로 다시 확인해요.

1. 같은 조건으로 놓고 비교해요

1. 기준을 고정해요. 어느 Figma 프레임·이미지와 어느 버전의 토큰을 비교할지 정해요.
2. 너비를 맞춰요. 기준 화면이 390이면 구현 화면도 390 CSS px에서 확인해요. 서로 다른 너비는 줄바꿈과 간격이 다를 수 있어요.
3. 내용과 상태를 맞춰요. 같은 문구·사진·목록 개수·스크롤 위치·버튼 상태로 비교해요.
4. 차이를 적어요. “느낌이 다름”보다 “카드 안 여백이 기준 16인데 실제 24”처럼 어느 요소가 어떻게 다른지 기록해요.
5. 그다음 조작해요. 스크린샷에 보이지 않는 입력·처리 중·실패·키보드 조작을 따로 확인해요.

2. 여섯 가지를 차례로 확인해요

3. 토큰 하나를 바꾸고 연결을 확인해요

같은 값을 복사한 것인지, 공통 값을 실제로 연결했는지 확인하는 실험이에요. 연습용 복사본이나 되돌릴 수 있는 작업 상태에서 해 보세요.

1. 검사할 토큰 하나를 고르고 현재 값을 기록해요. 예: color/primary의 현재 값.
2. 이 토큰을 사용하는 요소를 먼저 찾아요. 주요 버튼 배경이라면 같은 역할의 버튼들이 대상이에요.
3. 토큰 정의의 값 하나만 임시로 바꿔요. 요소마다 값을 따로 수정하지 않아요.
4. 연결된 버튼들이 함께 바뀌는지 보아요. 같은 초록이라도 성공 알림처럼 다른 역할의 요소까지 바뀌어야 하는 것은 아니에요.
5. 원래 값으로 되돌리고 원래 모습도 함께 복원되는지 확인해요.

토큰 연결 검사 요청

공통 토큰 하나가 실제로 재사용되는지 확인해줘.
검사 대상은 [실제 토큰 이름]이야.

1. 현재 값과 사용하는 요소·코드 위치를 먼저 기록해줘.
2. 되돌릴 수 있는 상태에서 토큰 정의의 값 하나만 임시로 바꿔줘.
3. 연결된 요소가 함께 바뀌는지 실행해서 확인해줘.
4. 원래 값으로 복원하고 관련 없는 수정이 남지 않도록 해줘.
5. 원래 값 / 임시 값 / 영향받은 요소 / 복원 결과를 알려줘.

실행하지 못했다면 실행했다고 쓰지 말고 내가 확인할 순서를 알려줘.

4. 이 순서로 직접 눌러 보세요

신청 화면의 확인 예시예요. 본인 앱의 기능에 맞춰 바꾸되 정상일 때와 실패할 때를 모두 확인해요.

5. 읽고 누를 수 있는지도 확인해요

접근성은 더 다양한 사람이 읽고 조작할 수 있게 만드는 일이에요. 자동 검사와 실제 조작을 함께 사용해요.

접근성 확인 요청

이 화면에서 읽기와 조작을 방해하는 문제를 확인해줘.
- 실제 글자색·배경색의 대비
- 버튼·아이콘의 실제 누르는 영역
- 키보드 이동과 포커스 표시
- 아이콘 버튼 이름과 입력창 설명
- 색만으로 전달하는 오류·상태

항목 / 확인 방법 / 실제 결과 / 수정할 부분으로 정리해줘.
자동으로 검사한 것, 직접 조작한 것, 아직 확인하지 못한 것을 구분해줘.
대비나 버튼 크기 몇 개가 통과했다는 이유로 접근성 전체를 통과했다고 쓰지 마.

W3C: 글자 대비 · 24×24 최소 기준과 예외 · 44×44 강화 기준

6. 문제를 정확히 요청하고 다시 확인해요

관찰한 문제를 수정 요청으로 바꾸기

문제를 하나씩 확인하고 수정해줘.

화면: [문제가 있는 화면]
확인 조건: [너비 / 내용 / 상태 / 기기]
기대 결과: [기준 문서의 항목 또는 원본 모습]
실제 결과: [어디가 어떻게 다른지]
자료: [비교 이미지 또는 관련 파일 위치]

먼저 원인이 화면, 공통 부품, 토큰, 사용 규칙 중 어디에 있는지 확인해줘.
기준이 없다면 임의로 결정하지 말고 선택할 내용을 알려줘.
확정한 범위만 수정하고 관련 없는 디자인과 기능은 유지해줘.
같은 조건으로 다시 확인하고, 같은 부품을 쓴 다른 화면의 영향도 알려줘.

“고쳤다”라는 말보다 같은 조건에서 다시 확인한 결과를 남기세요.