# 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

제목

카드

설명

태그
``` ### Tailwind v4 ```css /* app.css */ @import "tailwindcss"; @import "sonia-ui/tailwind.css"; ``` ```html

안녕

설명

``` 테마 선택은 `import "sonia-ui/theme.js"`(클라이언트에서) + ``. ### Next.js (App Router, Tailwind 없이) ```js // app/layout.js import "sonia-ui/base.css"; // next.config.js: transpilePackages: ["sonia-ui"] export default function RootLayout({ children }) { return ( {/* 그리기 전에 저장된 테마 적용 */}