# qufox-design > qufox 디자인 시스템 — 사람과 AI가 함께 쓰는 단일 진실원(SSOT). 토큰(CSS 변수) + qf-* 컴포넌트 클래스. 이 인덱스는 웹(design.qufox.com) 기준입니다. 두 채널의 산출물은 동일합니다. ## 리소스 - [작업 규칙 (Claude)](./CLAUDE.md) — AI 작업 규칙, 금지 - [에이전트 가이드](https://design.qufox.com/AGENTS.md) — 도구중립 + 적용 5단계 - [토큰 (CSS 변수)](https://design.qufox.com/tokens.css) — 다크 기본 + 라이트 - [토큰 (JSON, 기계가독)](https://design.qufox.com/tokens.json) — 키-값 + light 오버라이드 - [컴포넌트 매니페스트](https://design.qufox.com/components.json) — 클래스, 변형, 필요토큰, a11y, 예제 - [컴포넌트 CSS](https://design.qufox.com/components.css) — qf-* / qf-m-* / qf-doc-* - [아이콘 CSS](https://design.qufox.com/icons.css) — .qf-icon 크기·stroke (스프라이트와 함께 로드) - [아이콘 스프라이트](https://design.qufox.com/icons.svg) — qf-i-* (use href, 심볼에 paint 구움) - [예제](./examples/) — 복붙 가능한 소비 패턴 ## 새 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 허용). 프로덕션은 고정 스냅샷을 핀하세요 — `https://design.qufox.com/vN.M.P/tokens.css`(발행 목록 `/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`에서 확인합니다. ## 규칙 요약 - raw hex/px/box-shadow 금지 → `var(--token)` 사용 - 접근성 대비 AA 4.5:1 / 포커스 가시 / 터치 44px - 데스크톱 `qf-*`, 모바일 `qf-m-*` - 컴포넌트 layer = generic | chat | mobile. 비-채팅 앱은 generic만 채택(chat 제외)