# Pages Tailwind Usage Guide

## Why this exists

`pages` 게시판의 본문은 DB에 저장된 HTML이 런타임에 그대로 출력됩니다.  
Tailwind는 기본적으로 빌드 시점에 소스에서 발견한 클래스만 CSS로 생성하기 때문에, DB 안에만 존재하는 클래스는 누락될 수 있습니다.

그래서 `pages` 전용으로 허용할 Tailwind 클래스를 한곳에 모아 빌드 스캔 대상에 추가했습니다.

## Current safelist location

- Safelist source: [`resources/css/pages-tailwind-safelist.html`](/Volumes/myssd/dev/qditer/qpost/resources/css/pages-tailwind-safelist.html)
- Scan registration: [`resources/css/app.css`](/Volumes/myssd/dev/qditer/qpost/resources/css/app.css)

`app.css`가 Tailwind 입력 파일이고, 여기서 `@source './pages-tailwind-safelist.html';`을 추가해 Pages 전용 클래스를 항상 스캔하도록 했습니다.

## Allowed class range

Pages 콘텐츠에서는 다음 범위를 기준으로 디자인하세요.

- Layout: `block`, `inline-block`, `flex`, `inline-flex`, `grid`, `hidden`, `w-full`, `max-w-*`, `mx-auto`, overflow, position, alignment, grid columns
- Spacing: `p-*`, `px-*`, `py-*`, `pt-*`, `pb-*`, `pl-*`, `pr-*`, `m-*`, `mx-*`, `my-*`, `mt-*`, `mb-*`, `ml-*`, `mr-*`, `gap-*`, `space-y-*`
- Typography: `text-xs` to `text-6xl`, `font-*`, `leading-*`, `tracking-*`, `text-left/center/right/justify`, `whitespace-*`, `break-*`
- Colors: `white`, `black`, `slate`, `gray`, `primary`, `primary-soft`
- UI: `border`, `border-2`, `border-4`, `rounded-*`, `shadow-*`, `opacity-*`, `bg-*`, `divide-*`
- Responsive: `sm:`, `md:`, `lg:`, `xl:`
- Interaction: `hover:`, `focus:`, `focus-visible:`, `transition`, `duration-*`, `ease-*`

## Responsive usage

반응형 클래스는 일반 Tailwind와 동일하게 사용합니다.

- `sm:text-5xl`
- `md:grid-cols-2`
- `lg:grid-cols-3`
- `sm:px-8`
- `lg:py-28`

현재 safelist에는 `sm:`, `md:`, `lg:`, `xl:` 접두사가 포함되어 있습니다.

## Hover and focus

링크, 버튼, 카드에는 아래 패턴을 우선 사용하세요.

- `hover:bg-slate-100`
- `hover:text-slate-900`
- `hover:border-slate-300`
- `focus:outline-none`
- `focus:ring-2`
- `focus:ring-offset-2`
- `focus-visible:ring-2`

## Do not use

다음은 기본적으로 Pages safelist 대상이 아닙니다.

- 임의값 클래스: `w-[837px]`, `text-[37px]`, `bg-[#123456]`
- 과도하게 세밀한 spacing 전체 세트
- 빌드 결과에 없는 새로운 색상 계열을 무분별하게 추가하는 것
- 페이지마다 클래스가 다른 랜덤한 HTML 구조

## How to allow a new class

1. `resources/css/pages-tailwind-safelist.html`에 원하는 클래스를 추가합니다.
2. `npm run build`를 다시 실행합니다.
3. 생성된 CSS에 새 클래스가 포함되는지 확인합니다.

하나의 파일만 수정하면 되므로 허용 범위 관리가 쉽습니다.

## Does safelist change require a build?

네. Tailwind는 빌드 시 CSS를 생성하므로, safelist를 바꾼 뒤에는 `npm run build` 또는 개발 서버 재시작이 필요합니다.

## Rules for AI-generated Pages HTML

Pages HTML을 생성할 때는 다음 규칙을 지켜주세요.

- safelist에 없는 arbitrary value 클래스를 만들지 말 것
- 너무 많은 spacing/색상 변형을 한 번에 사용하지 말 것
- 레이아웃은 `max-w-*`, `mx-auto`, `grid`, `flex`, `gap-*` 중심으로 구성할 것
- 제목은 `text-4xl`, `sm:text-5xl`, `md:text-6xl` 범위 안에서 조합할 것
- 카드와 버튼은 `rounded-2xl`, `border-slate-200`, `hover:bg-slate-100` 같은 기본 패턴을 우선 사용할 것

## Example

```html
<section class="mx-auto max-w-5xl px-6 py-20">
  <div class="space-y-6">
    <h1 class="text-4xl font-extrabold tracking-tight text-slate-900 sm:text-5xl">
      이용약관
    </h1>

    <div class="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
      <article class="rounded-2xl border border-slate-200 bg-slate-50 p-6 shadow-sm transition hover:bg-slate-100">
        <h2 class="text-lg font-bold text-slate-900">항목</h2>
        <p class="mt-3 text-sm leading-6 text-slate-600">
          Pages 콘텐츠용 예시입니다.
        </p>
      </article>
    </div>
  </div>
</section>
```