# sonia-ui — AI용 전체 레퍼런스
> 창선(ckdtjs505)의 모든 앱·웹이 함께 쓰는 디자인 시스템. 이 파일 하나만 읽으면 sonia-ui로 화면을 만들 수 있다.
> 자동 생성 파일(scripts/build-llms.ts). 값은 src/tokens에서 온다.
## 1. AI가 지킬 규칙
1. **색은 역할 이름으로만.** `#58A6FF`, `rgba(...)`, `text-blue-500` 같은 값을 쓰지 않는다. `bg-primary` / `var(--color-primary)`처럼 역할로 쓴다. 투명도가 필요하면 `color-mix(in srgb, var(--color-primary) 20%, transparent)` 또는 Tailwind `bg-primary/20`.
2. **간격·모서리·글자는 이름 단계로만.** 간격 `0 xs s md lg xl xxl hg`, 모서리 `xs sm md lg xl pill`, 글자 `hero-lg hero display title heading body caption label stat micro overline`.
3. **버튼·카드·태그·입력창은 `sn-*` 클래스를 먼저 쓴다.** 새로 만들지 말고 조합한다.
4. **테마는 `` 하나.** 다크 모드를 따로 만들지 않는다(`dark:` 변형, `prefers-color-scheme` 분기 금지). 모든 색이 테마를 따라가므로 저절로 된다.
5. **값을 바꾸고 싶으면 프로젝트에서 덮지 말고 sonia-ui의 `src/tokens`·`src/styles`를 고친다.** 그래야 모든 앱이 같이 바뀐다.
6. **뜻이 있는 색(우선순위·캘린더·차트 계열색·성공/경고)**만 프로젝트가 따로 정할 수 있다. 그때도 밝기는 ``로 나눈다.
7. 기존 프로젝트에 붙일 때는 원래 CSS 변수를 sonia-ui 변수에 연결한다(예: `--bg: var(--color-background)`). 하드코딩된 색은 역할로 바꾼다.
## 2. 어떤 입구를 쓰나
| 프로젝트 | 가져올 것 | 한 줄 |
|---|---|---|
| 아무 HTML (설치 없이) | CDN | `` + `` |
| Tailwind v4 (Vite·Next) | `sonia-ui/tailwind.css` | CSS에 `@import "tailwindcss"; @import "sonia-ui/tailwind.css";` |
| Tailwind 없는 웹 (Next·Vite·번들러) | `sonia-ui/base.css` | `import "sonia-ui/base.css"` |
| 변수만 필요 | `sonia-ui/themes.css` | `import "sonia-ui/themes.css"` |
| 테마 고르기 UI | `sonia-ui/theme.js` | `import "sonia-ui/theme.js"` 후 `` |
| React Native (Expo) | `sonia-ui/native` | `import { ThemeProvider, getTheme, Box, Text } from "sonia-ui/native"` |
| JS에서 값이 필요 | `sonia-ui/tokens` | `import { getTheme, themeList, toCssVars } from "sonia-ui/tokens"` |
| 테마 목록(JSON) | `sonia-ui/themes.json` | `[{ id, name, scheme }]` |
설치: `npm i github:ckdtjs505/sonia-ui` (Expo는 `@shopify/restyle react-native-safe-area-context`도). TS 소스로 배포되므로 Next는 `next.config`에 `transpilePackages: ["sonia-ui"]`, Jest는 `transformIgnorePatterns` 허용 목록에 `sonia-ui`.
글꼴: `` (없으면 시스템 글꼴).
## 3. 설치 레시피
### 아무 HTML (복사해서 바로)
```html