# AGENTS.md — qufox-design > 도구중립 에이전트 가이드입니다. **정본은 `CLAUDE.md`**, 이 문서는 그 요약과 "소비 방법"을 > 담습니다(Cursor / Copilot / Codex 등 비-Claude 에이전트 대응). ## 무엇 qufox 패밀리 사이트 공용 디자인 시스템의 SSOT. **사람 + AI 이중 청중**. 토큰(CSS 변수) + `qf-*` / `qf-m-*` 컴포넌트 클래스 + `components.json` 매니페스트. ## 셋업 / 빌드 / 검증 - `pnpm install` — 초기엔 외부 의존성 없음(무의존 node 빌드). - `pnpm build` — `dist` + 웹 채널(`apps/docs/public`) 조립. - `pnpm verify` — build + 대비/raw-값 점검. - `pnpm dev` — `apps/docs/public` 로컬 미리보기(http://localhost:4321). - `pnpm sync:qufox` — 빌드 산출물을 qufox 벤더 사본으로 동기(qufox에 이미 있는 파일만, 지금은 `icons.svg`). qufox 위치는 `QUFOX_ROOT`로 지정. ## 코드 규칙 - raw hex/px/box-shadow 직접 사용 금지(토큰 레이어 예외) → 전부 `var(--token)`. - 컴포넌트 layer = generic | chat | mobile(채팅은 선택 모듈). 비-채팅 앱은 generic만 채택, chat 제외. generic 은 app-layout/chat 토큰을 쓰지 않습니다(verify 가 차단). - 접근성 AA 4.5:1 / 키보드 포커스 가시 / 모바일 터치 44px. - 폴라이트 한국어, TypeScript strict, Conventional Commits. - 스크린샷은 판단 근거가 된 장면만 저장(폭 ≤800px, 폴더당 10장 안팎). 수치는 §검증 표가 정본, 전수 장면은 하네스로 재생. 큰 PNG 는 저장소를 키워 Flux clone timeout 으로 배포를 멈춘다. ## 이 DS를 새 APP(또는 화면)에 반영하는 법 — 5단계 1. **불러오기** — `tokens.css` + `components.css` + `icons.css`(모바일은 `mobile.css`)를 ``로 로드합니다. 아이콘(`qf-i-*`)을 쓰면 `icons.svg` 스프라이트를 페이지에 인라인하세요(외부 `icons.svg#id` 참조는 브라우저별 currentColor, CSP, 추가 요청 한계가 있습니다. 스프라이트 심볼에 paint가 구워져 있어 `icons.css` 없이도 형태는 렌더되지만, `.qf-icon` 크기·stroke 튜닝을 위해 `icons.css` 로드를 권장합니다). **브랜드 글꼴**(Pretendard Variable 동적 서브셋 + Geist Mono, 자체 호스팅 — `brand/brand.config.json` 의 `fontLink` = `fonts/brand-fonts.css`)은 `` 로 로드하고, 벤더링 시 `fonts/` 폴더를 `tokens.css` 와 같은 디렉터리에 통째로 복사하세요(안의 url 이 상대 경로라 구조만 지키면 됩니다. 웹: `https://design.qufox.com/fonts/brand-fonts.css` — 루트 전용, 동결 스냅샷 `/vN.M.P/` 에는 글꼴이 없습니다). 빠지면 `--font-display`/`--font-mono-family` 슬롯이 비어 시스템 폴백으로만 그려집니다(Windows 에서 라틴은 Segoe UI, 한글은 맑은 고딕으로 섞이고 코드가 넓은 한글 고정폭으로 보이는 원인). 이 CSS 에는 교체 전 폴백(`Pretendard Fallback: …`)의 메트릭 맞춤 면이 들어 있어 글꼴이 늦게 와도 레이아웃이 움직이지 않습니다. 루트(`https://design.qufox.com/{tokens,components,icons,mobile}.css`)는 항상 최신(CORS 허용). 프로덕션은 동결 스냅샷(`/vN.M.P/`)이나 롤링 채널(`/vN/`)을 핀하세요(발행 목록 `/versions.json`), 또는 빌드 산출물 벤더링. Tailwind 프로젝트는 `tailwind-preset` 적용으로 대체할 수 있습니다. 2. **클래스 사용** — 마크업에 `qf-*`(데스크톱) / `qf-m-*`(모바일) 클래스를 쓰고, 색, 간격, radius는 `var(--token)`으로만 지정합니다. 각 컴포넌트는 layer(generic | chat | mobile)를 가지며, 비-채팅 앱은 generic(필요 시 mobile generic)만 채택하고 chat 클래스는 제외합니다. 3. **raw 값 금지** — hex/px/box-shadow를 직접 쓰지 않습니다. 필요한 토큰이 없으면 추가를 제안합니다. 4. **예제 출발** — `examples/`의 복붙 가능한 패턴을 시작점으로 삼습니다. 5. **인터페이스 조회** — 각 컴포넌트의 클래스, 변형, 필요한 토큰, 접근성 주의, layer는 `components.json`에서 확인합니다. ## AI 소비 2채널 (동등) - **웹**: `https://design.qufox.com/llms.txt`, `/llms-full.txt`, `/tokens.json`, `/components.json`, `/components.css` … - **로컬**: 이 repo의 `llms.txt`, `packages/tokens/dist/tokens.json`, `packages/manifest/components.json`, `packages/css/dist/components.css` … 두 채널의 산출물은 byte-identical(단일 SSOT의 두 렌더링). 배경, 보장 방식: `docs/adr/0001`.