웹 개발 AI 활용 첫 단계, 시안 전에 요구 글 한 장
AI 코딩 도구에 화면을 부탁할 때 가장 먼저 흔들리는 것은 코드보다 요구다. "예쁜 꽃집 페이지"라고만 쓰면 도구는 칸의 수, 순서, 강조할 정보를 스스로 정한다. 그 결과가 마음에 들지 않으면 어디를 고칠지 말하기도 어렵다. 그래서 그림보다 글 한 장을 먼저 쓴다.
요구 글에는 세 가지만 적는다. 페이지가 할 일 한 줄, 화면에 들어갈 칸 목록, 좁은 화면에서 칸이 쌓이는 순서다. 칸 목록은 머리글, 대표 사진, 추천 꽃 세 장, 영업시간, 찾아오는 길 정도로 충분하다. 색이나 글꼴은 나중에 바꿔도 구조가 흔들리지 않으므로 처음에는 비워 둔다.
좁은 화면 순서를 먼저 적는 데는 이유가 있다. MDN은 좁은 화면용 한 줄 배치를 먼저 만들고, 화면이 넓다는 것을 확인한 뒤 여러 열 배치를 더하는 방식을 모바일 우선이라고 부른다. 요구 글에 휴대폰 순서가 있으면 AI가 넓은 화면을 줄이는 대신 좁은 화면을 넓히는 쪽으로 코드를 쓰도록 이끌 수 있다.
시안 그림을 AI 코딩 도구에 넘기는 법
시안(완성 전 화면을 그린 그림)은 손그림 사진이어도 되고, 디자인 도구에서 내보낸 이미지여도 된다. Claude Code 공식 문서는 이미지를 넣는 방법으로 창에 끌어다 놓기, 복사한 이미지를 붙여 넣기, 이미지 경로를 알려 주기 세 가지를 적는다. 윈도에서는 붙여 넣기 단축키가 Alt+V로 안내되어 있다. 같은 문서에는 "이 디자인 시안에 맞는 CSS를 만들어 달라"는 요청 예시도 있다.
- 연습 폴더를 만들고 요구 글을
brief.md로 저장한다. 잘 됐으면 폴더에 그 파일 하나가 보인다. - 시안 이미지를 같은 폴더에
mockup.png로 둔다. 잘 됐으면 탐색기 미리보기에서 칸 배치가 보인다. - AI 코딩 도구를 그 폴더에서 열고 아래 요청을 그대로 붙여 넣는다. 잘 됐으면 도구가 코드를 쓰기 전에 화면 칸을 목록으로 되돌려 준다.
brief.md의 요구와 mockup.png 시안을 함께 본다.
코드는 아직 쓰지 말고, 시안에서 읽은 칸 이름과 순서를 목록으로 먼저 보여 줘.
좁은 화면에서는 brief.md에 적힌 순서대로 한 줄로 쌓는다.코드를 받기 전에 칸 목록부터 돌려받는 이유는 오해를 일찍 찾기 위해서다. 시안의 사진 세 장을 도구가 광고 배너로 읽었다면 이 목록에서 바로 드러난다. Claude Code에는 파일을 읽고 계획만 내놓은 뒤 승인 전까지 고치지 않는 plan mode도 있다. 처음 쓰는 분이라면 이 모드로 시작하면 마음이 편하다.
요구 글은 할 일 한 줄, 칸 목록, 좁은 화면 순서 세 줄로 시작한다. 시안을 넘긴 뒤에는 코드보다 칸 목록을 먼저 돌려받는다. 목록이 요구 글과 다르면 그 자리에서 고치고 다음 단계로 간다.
자주 막히는 곳은 이미지가 대화에 들어가지 않는 경우다. 붙여 넣기가 안 되면 이미지 경로를 문장에 적는 방법으로 바꾼다. 시안 속 글자가 작아 도구가 칸 이름을 틀리게 읽으면, 칸 이름을 요구 글에 적어 두고 "이름은 brief.md를 따른다"는 한 줄을 붙인다. 어떤 도구를 쓸지 아직 정하지 않았다면 클로드 코드·코덱스·커서 비교에서 고르는 기준을 먼저 볼 수 있다.
반응형 디자인 AI에 맡길 때, viewport 한 줄과 좁은 화면부터
반응형 디자인(화면 크기에 따라 배치가 바뀌는 웹 페이지 설계)을 AI에게 맡길 때는 몇 가지 조건을 미리 적어 주는 편이 결과를 맞추기 쉽다. 먼저 붙일 조건은 문서 머리에 들어가는 viewport 메타 태그다. MDN은 이 태그가 모바일 브라우저에게 화면 폭을 기기 폭에 맞추라고 알려 준다고 설명하고, 문서 머리에 항상 넣으라고 권한다. web.dev가 안내하는 형태는 아래 한 줄이다.
<meta name="viewport" content="width=device-width, initial-scale=1">이 한 줄이 빠지면 휴대폰에서 PC용 화면이 통째로 작게 줄어 보일 수 있다. AI가 만든 HTML을 받으면 <head> 안에 이 줄이 있는지부터 본다. 줄이 있는데도 글자가 작게 보인다면 다른 원인이므로, 그때는 CSS의 고정 폭을 찾는다.
그다음 조건은 배치 방법이다. MDN은 반응형 사이트가 유연한 그리드 위에 세워지며, Flexbox와 CSS Grid 같은 배치 방법은 기본적으로 반응형이라고 적는다. 그래서 요청에 "고정 픽셀 폭 대신 Grid나 Flexbox로"라는 조건을 넣으면 화면마다 폭을 따로 맞추는 코드를 줄일 수 있다. 미디어 쿼리(화면 폭 같은 조건을 시험해 CSS를 골라 적용하는 문법)는 넓은 화면에서만 열을 늘리는 자리에 둔다.
AI에 반응형 코드를 맡길 때 붙일 조건
브레이크포인트(배치가 바뀌는 화면 폭 기준)를 어떻게 정할지도 조건으로 적는다. web.dev는 기기 종류나 제품·브랜드·운영체제 이름으로 브레이크포인트를 정하지 말고, 내용이 배치를 정하게 하라고 쓴다. AI에게 "아이폰용, 갤럭시용"처럼 기기 이름으로 부탁하면 이 권고와 반대 방향의 코드가 나오기 쉽다. 아래 요청은 앞 단계 칸 목록을 확인한 뒤 붙여 넣는 예시다.
확인한 칸 목록으로 index.html과 style.css를 만들어 줘.
조건:
1. head에 viewport 메타 태그를 넣는다.
2. 기본 CSS는 좁은 화면용 한 줄 배치로 쓴다.
3. 넓은 화면 배치는 min-width 미디어 쿼리 안에서만 더한다.
4. 브레이크포인트는 기기 이름이 아니라 추천 꽃 카드가 좁아져 읽기 어려워지는 폭으로 정하고, 그 이유를 주석으로 남긴다.
5. 고정 width 대신 CSS Grid를 쓴다.받은 CSS가 아래 모양에 가까우면 조건이 지켜진 것이다. 숫자는 이 글의 가상 예시에서 정한 값이며, 실제 값은 카드 내용 길이를 보고 정한다.
.flowers {
display: grid;
grid-template-columns: 1fr;
gap: 1rem;
}
@media (min-width: 48rem) {
.flowers {
grid-template-columns: repeat(3, 1fr);
}
}- 받은 파일을 연습 폴더에 저장하고 브라우저로
index.html을 연다. 잘 됐으면 넓은 창에서 추천 꽃 카드가 세 줄로 놓인다. - 브라우저 창 폭을 천천히 줄인다. 잘 됐으면 카드가 한 줄로 쌓이고 가로 스크롤바가 생기지 않는다.
- 사진이 많은 페이지라면 이미지 처리 방식을 묻는다. MDN은 큰 이미지 하나를 줄여 쓰면 필요보다 큰 파일을 받게 되고,
picture요소와img의srcset·sizes속성으로 풀 수 있다고 적는다.
자주 막히는 곳은 창을 줄였는데 가로 스크롤바가 생기는 경우다. 대개 어떤 칸에 고정 폭이 남아 있거나 긴 주소가 줄바꿈되지 않는 경우라서, AI에게 "가로 스크롤을 만드는 요소를 찾아 줘"라고 따로 묻는 편이 빠르다. 넓은 화면에서 카드 폭이 지나치게 늘어나 보이면 바깥 상자에 최대 폭을 주는 조건을 더한다.
인용 — web.devDon't define breakpoints based on device classes, or any product, brand name, or operating system.
우리말 뜻: 기기 분류나 제품·브랜드 이름, 운영체제를 기준으로 브레이크포인트를 정하지 말라. 내용이 배치를 정하게 하라는 문장이 뒤에 이어진다.
프론트엔드 AI 활용, 접근성 기준을 숫자로 건네기
화면이 시안처럼 보여도 누구나 쓸 수 있는 화면이라는 뜻은 아니다. 웹 접근성(장애가 있거나 다른 환경을 쓰는 사람도 페이지를 쓸 수 있게 하는 것) 기준은 W3C의 WCAG(웹 콘텐츠 접근성 지침)에 숫자로 적혀 있다. 지금 판인 WCAG 2.2는 2024년 12월 12일 자 W3C 권고안이다. AI에게 "접근성 좋게"라고 부탁하는 대신 이 숫자를 조건으로 건네면 결과를 확인할 기준이 생긴다.
이 글에서 조건으로 쓰는 항목은 셋이다. 1.4.10 Reflow는 세로로 스크롤하는 내용을 320 CSS 픽셀 폭에서, 가로로 스크롤하는 내용을 256 CSS 픽셀 높이에서 두 방향 스크롤 없이 볼 수 있게 하라는 기준이다. 1.4.3 대비 기준은 본문 글자의 명암 대비를 4.5:1 이상, 큰 글자는 3:1 이상이 되게 한다. 2.5.8 Target Size (Minimum)는 포인터로 누르는 대상이 24×24 CSS 픽셀 이상이 되게 하는 AA 등급 기준이다. 세 기준 모두 예외 조항이 있으므로 원문 예외를 함께 읽는다.
접근성 조건을 붙인 요청과 axe 자동 점검
앞 단계 코드를 받은 뒤 아래 요청을 붙여 넣는다. 숫자는 위 기준에서 그대로 옮겼다.
지금 index.html과 style.css를 아래 기준으로 점검하고, 고칠 곳만 고쳐 줘.
1. 화면 폭 320 CSS 픽셀에서 가로 스크롤 없이 모든 내용을 볼 수 있다.
2. 본문 글자 대비는 4.5:1 이상, 큰 글자는 3:1 이상이다.
3. 버튼과 링크처럼 누르는 대상은 24×24 CSS 픽셀 이상이다.
고친 곳마다 어느 기준 때문인지 한 줄씩 적어 줘.AI의 점검 답만 믿지 않도록 자동 점검 도구도 붙인다. Playwright 공식 문서의 접근성 테스트 예시는 @axe-core/playwright 패키지를 쓴다. 테스트 파일 안에서 페이지를 연 뒤 검사 결과의 위반 목록이 비어 있는지 확인하는 구조다.
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('첫 화면 접근성 자동 점검', async ({ page }) => {
await page.goto('http://localhost:8000/');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});잘 됐으면 테스트가 통과하고, 위반이 있으면 어떤 규칙에 걸렸는지 목록이 나온다. 다만 같은 문서는 자동 테스트가 모든 종류의 WCAG 위반을 찾지는 못하며, 많은 접근성 문제는 직접 써 봐야 드러난다고 적는다. 자동 점검이 통과해도 키보드 탭 키로 링크를 차례로 옮겨 다녀 보는 확인은 사람이 한다.
자주 막히는 곳은 AI가 대비 기준을 맞추려고 시안 색을 크게 바꿔 버리는 경우다. 그럴 때는 "브랜드 색은 두고 글자 색만 바꾼다"처럼 바꿔도 되는 범위를 요청에 적는다. 더 자세한 점검 항목은 웹 접근성 실전 체크리스트에서 이어 볼 수 있다.
웹 개발 AI 활용, Playwright로 화면을 찍어 비교
AI에게 수정을 여러 번 맡기다 보면 한 곳을 고치면서 다른 곳의 배치가 틀어지는 일이 생긴다. 눈으로 매번 모든 화면 폭을 확인하기는 어렵다. Playwright(브라우저를 코드로 열고 조작하는 테스트 도구)의 화면 비교 기능을 쓰면 기준 화면을 저장해 두고 바뀐 곳을 찾을 수 있다.
Playwright 공식 설치 안내의 조건은 Node.js 22.x, 24.x, 26.x 최신판과 Windows 11 이상, Windows Server 2019 이상 또는 WSL이다. 설치와 실행, 결과 보고서 열기는 아래 명령으로 안내되어 있다. 설치 명령은 질문 몇 개를 묻고 기본 설정 파일과 예시 테스트를 만든다.
npm init playwright@latest
npx playwright test
npx playwright show-report
휴대폰과 PC 화면을 한 번에 찍는 설정
Playwright 에뮬레이션 문서는 devices 목록의 기기 설정으로 사용자 에이전트, 화면 크기, viewport, 터치 지원 같은 브라우저 동작을 흉내 낸다고 설명한다. 설정 파일의 projects에 PC용과 휴대폰용을 나란히 두면 같은 테스트를 두 화면에서 돌릴 수 있다. PC용 viewport 예시 값 1280×720도 같은 문서에 있다.
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{ name: 'pc', use: { viewport: { width: 1280, height: 720 } } },
{ name: 'phone', use: { ...devices['iPhone 13'] } },
],
});기기 설정에 viewport를 따로 덮어쓰고 싶다면 순서에 주의한다. 문서는 기기 설정이 자기 viewport를 갖고 있으므로 devices를 펼친 뒤에 viewport를 적으라고 한다. 순서를 바꾸면 직접 적은 값이 기기 값에 덮여 사라진다.
화면 비교 테스트는 아래처럼 쓴다. 연습 폴더에서 python -m http.server 8000처럼 로컬 서버를 켜 두고 실행하는 예시다.
import { test, expect } from '@playwright/test';
test('꽃집 첫 화면 모양', async ({ page }) => {
await page.goto('http://localhost:8000/');
await expect(page).toHaveScreenshot({ maxDiffPixels: 100, threshold: 0.1 });
});- 처음
npx playwright test를 실행한다. 공식 문서는 첫 실행에서 기준 스크린숏을 만든다고 설명한다. 이때 "스냅숏이 없어 실제 화면을 쓴다"는 뜻의 오류 문장이 나오는데, 기준 화면이 없어서 생긴 메시지다. - 같은 명령을 한 번 더 실행한다. 잘 됐으면 두 프로젝트(pc, phone) 모두 통과한다. 다음 실행부터 기준 화면과 비교하기 때문이다.
- AI에게 수정을 맡긴 뒤 다시 실행한다. 바뀐 곳이 있으면 실패하고,
npx playwright show-report로 기준·새 화면·차이를 열어 본다. - 바뀐 화면이 의도한 결과라면 아래 명령으로 기준 화면을 새로 만든다.
npx playwright test --update-snapshotsmaxDiffPixels와 threshold는 차이를 얼마나 너그럽게 볼지 정하는 값이다. 값을 크게 잡을수록 작은 배치 틀어짐을 놓칠 수 있으므로, 처음에는 문서 예시 값에서 시작하고 이유 없이 늘리지 않는다.
Playwright 화면 비교가 매번 실패할 때
코드를 바꾸지 않았는데 비교가 실패한다면 실행 환경을 먼저 본다. 공식 문서는 브라우저 렌더링이 운영체제, 버전, 설정, 하드웨어, 전원 상태 등에 따라 달라질 수 있다고 적는다. 그래서 기준 화면을 만든 환경과 같은 환경에서 테스트를 돌리라고 권한다. 한 PC에서 만든 기준 화면을 다른 PC에서 비교하면 글꼴 렌더링 차이만으로 실패할 수 있다.
또 하나는 시계, 날짜, 무작위 추천처럼 실행할 때마다 바뀌는 칸이다. 이런 칸이 화면에 있으면 매번 다른 그림이 나온다. 연습 페이지에서는 바뀌는 칸을 빼고 기준 화면을 만들거나, AI에게 "테스트 때는 고정 값을 쓰는 방법"을 물어 따로 처리한다.
화면 비교가 익숙해지면 앞 단계의 axe 점검 테스트와 같은 폴더에 두고 한 번에 돌린다. 화면 폭 320 CSS 픽셀 프로젝트를 하나 더 만들면 Reflow 기준을 매번 확인하는 데도 쓸 수 있다. 회사 코드처럼 밖으로 보내기 어려운 코드라면 로컬 LLM으로 코딩 보조 쓰기처럼 PC 안에서 도는 모델로 같은 순서를 시험해 볼 수 있다.
AI가 만든 코드를 고치게 할 때도 테스트 결과를 그대로 넘기면 대화가 짧아진다. "phone 프로젝트에서 추천 꽃 카드 줄이 밀렸다"처럼 실패한 프로젝트 이름과 칸 이름을 함께 적는다. 차이 이미지를 대화에 넣는 것도 공식 문서에 적힌 이미지 넣기 방법으로 할 수 있다.
자주 묻는 것
AI가 시안 이미지만 보고 바로 완성 코드를 만들 수 있나?
Claude Code 공식 문서에는 시안 이미지를 넣고 그에 맞는 CSS를 요청하는 예시가 있다. 다만 이 글은 완성도를 실측하지 않았다. 칸 이름과 순서처럼 이미지에서 잘못 읽기 쉬운 정보는 요구 글로 따로 주고, 코드 전에 칸 목록을 돌려받는 순서를 권한다.
브레이크포인트는 몇 픽셀로 정해야 하나?
공식 문서가 정해 둔 하나의 값은 없다. web.dev는 기기나 제품 이름 대신 내용이 배치를 정하게 하라고 쓴다. 카드나 표가 좁아져 읽기 어려워지는 폭을 창을 줄여 가며 찾고, 그 폭을 미디어 쿼리 기준으로 삼는다.
axe 자동 점검을 통과하면 접근성은 끝인가?
아니다. Playwright 문서는 자동 테스트가 모든 WCAG 위반을 찾지는 못하며, 많은 문제는 직접 확인해야 드러난다고 적는다. 키보드로 이동해 보기, 확대해서 읽어 보기 같은 확인은 사람이 한다.
화면 비교 테스트가 처음에 실패하는 것은 정상인가?
첫 실행은 기준 스크린숏을 만드는 단계라서 기준이 없다는 메시지가 나온다. 두 번째 실행부터 비교가 시작된다. 의도한 변경 뒤에는 --update-snapshots로 기준을 새로 만든다.
정리 — 맡기는 범위를 좁히고 단계마다 확인한다
웹 개발에 AI를 쓸 때는 한 번에 완성본을 받기보다, 요구 글과 시안으로 칸을 맞추고, 좁은 화면부터 반응형 코드를 받고, 접근성 숫자를 조건으로 붙인 뒤, 화면 비교로 바뀐 곳을 찾는 순서가 고치기 편하다. viewport 한 줄과 내용 기준 브레이크포인트는 반응형 요청의 기본 조건이다. WCAG 2.2의 숫자와 Playwright의 비교 기능은 AI의 답을 사람이 확인하는 기준이 된다.
처음에는 가상 페이지 하나로 다섯 단계를 끝까지 한 번 돌려 보는 것으로 충분하다. 막히는 단계가 어디인지 알면 다음 페이지에서는 그 단계의 요청만 다듬으면 된다. 따라 하다 안 되는 단계가 있으면 그 단계의 "잘 됐으면" 줄과 실제 화면을 나란히 놓고 비교해 보시면 원인을 좁히기 쉽다.
참고 자료
- MDN Web Docs. Responsive web design — viewport 메타 태그, 미디어 쿼리, 모바일 우선, 유연한 그리드, srcset·sizes(2026-11-14 확인). developer.mozilla.org
- web.dev. Responsive web design basics — initial-scale=1이 든 viewport 태그와 기기 이름으로 브레이크포인트를 정하지 말라는 설명(2026-11-14 확인). web.dev
- W3C. Web Content Accessibility Guidelines (WCAG) 2.2 — 2024-12-12 권고안, 1.4.10 Reflow 320·256 CSS 픽셀, 1.4.3 대비 4.5:1·3:1(2026-11-14 확인). w3.org
- W3C WAI. Understanding SC 2.5.8 Target Size (Minimum) — 누르는 대상 24×24 CSS 픽셀, AA 등급(2026-11-14 확인). w3.org
- Playwright. Installation — 설치·실행·보고서 명령과 Node.js·Windows 조건(2026-11-14 확인). playwright.dev
- Playwright. Emulation — devices 설정과 viewport 지정 순서(2026-11-14 확인). playwright.dev
- Playwright. Visual comparisons — 첫 실행 기준 화면, --update-snapshots, 환경별 렌더링 차이, maxDiffPixels(2026-11-14 확인). playwright.dev
- Playwright. Accessibility testing — @axe-core/playwright 예시와 자동 검사의 한계(2026-11-14 확인). playwright.dev
- Claude Code Docs. Common workflows — 이미지 넣는 방법, 시안으로 CSS 요청 예시, plan mode(2026-11-14 확인). code.claude.com