3.3 KiB
3.3 KiB
마크업 개발자 지침 (Nuxt 프로젝트)
적용 대상:
**/*.vue파일 최종 업데이트: 2026-04-11
역할과 범위
- 담당: 시맨틱 마크업, 레이아웃·타이포·간격, 반응형, 접근성, 정적 UI 상태(열림/닫힘 등은 props·emit으로 연결만).
- 기본적으로 다루지 않음:
server/API, Pinia 스토어 설계, 복잡한 비즈니스 로직, 인증·권한. 필요 시 프론트 담당과 역할을 나눈다. - 공통 컴포넌트는
app/components/에 두고, 라우트 단위 화면은app/pages/에 둔다.
Vue SFC 작성 순서
<template>— 구조·의미·접근성을 먼저 완성한다.<script setup lang="ts">— 표시에 필요한 최소한의 props, 간단한 로컬 상태만.<style>— Tailwind 위주이면 빈 블록이거나 예외적인 오버라이드만.
HTML·접근성
- 제목 계층(
h1~h6)을 건너뛰지 않는다. 페이지당h1은 한 번(또는 프로젝트 합의에 따름). - 인터랙션 가능한 요소는 버튼은
<button>, 이동은<NuxtLink>(또는a).div에 클릭 이벤트만 붙이지 않는다. - 폼:
label과input을for/id로 연결한다. 에러 메시지는aria-describedby등으로 연관 짓는다. - 장식용 이미지는
alt="", 의미 있는 이미지는 구체적인alt문구. - 키보드만으로 주요 플로우가 동작하는지 확인한다.
Tailwind CSS (@nuxtjs/tailwindcss)
- 유틸리티 우선: 커스텀 CSS는 디자인 토큰·컴포넌트 예외가 아니면 최소화한다.
- 반복되는 패턴은
@apply남용보다 작은 Vue 컴포넌트로 추출하는 것을 우선한다. - 모바일 퍼스트: 기본 클래스는 작은 화면 기준,
sm:md:lg:등으로 확장한다. - 색·간격·폰트는 가능하면 프로젝트
tailwind.config에 정의된 테마 값을 쓴다(임의 hex 남발 지양).
Nuxt에서 자주 쓰는 것
- 내부 링크:
<NuxtLink to="/path">(일반<a href>는 외부·메일·다운로드 등에). - 이미지 최적화가 필요하면
<NuxtImg>/<NuxtPicture>사용을 검토한다(프로젝트 설정에 따름). - 클라이언트 전용 UI(브라우저 API, hydration mismatch 위험)는
<ClientOnly>로 감싸되, 가능하면 SEO·접근을 해치지 않도록 대체 콘텐츠를 둔다. - 메타·제목: 화면별로
useHead사용 시, 문구·구조는 마크업 담당이 정하고 구현은 합의된 패턴을 따른다.
에셋
- 정적 파일은
public/; 빌드에 포함되는 소형 에셋은app/assets/. - 경로는 절대 URL 하드코딩보다 프로젝트에서 정한 방식(환경 변수, 설정)을 따른다.
협업·품질
- 기존 페이지·컴포넌트의 클래스 순서·네이밍·들여쓰기를 맞춘다.
- 디자인 시안과의 1px 단위 맞춤보다 유지보수 가능한 구조·접근성을 우선한다(단, 팀 기준이 있으면 그에 따름).
- 변경 범위는 한 PR·한 커밋 단위로 작게 유지한다.
Git 커밋 (팀 공통 규칙과 일치)
Conventional Commits, 제목 본문은 한글.
feat: 로그인 폼 마크업 및 반응형 적용
fix: 모바일 헤더 겹침 수정
style: 버튼 컴포넌트 간격 조정