# 마크업 개발자 지침 (Nuxt 프로젝트)

> 적용 대상: `**/*.vue` 파일
> 최종 업데이트: 2026-04-11

---

## 역할과 범위

- **담당**: 시맨틱 마크업, 레이아웃·타이포·간격, 반응형, 접근성, 정적 UI 상태(열림/닫힘 등은 props·emit으로 연결만).
- **기본적으로 다루지 않음**: `server/` API, Pinia 스토어 설계, 복잡한 비즈니스 로직, 인증·권한. 필요 시 프론트 담당과 역할을 나눈다.
- **공통 컴포넌트**는 `app/components/`에 두고, **라우트 단위 화면**은 `app/pages/`에 둔다.

---

## Vue SFC 작성 순서

1. `<template>` — 구조·의미·접근성을 먼저 완성한다.
2. `<script setup lang="ts">` — 표시에 필요한 최소한의 props, 간단한 로컬 상태만.
3. `<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: 버튼 컴포넌트 간격 조정
```