# 시작하기 (/docs)



`@coldsurfers/surf-ui` 은 토큰 값 · 컴파일된 CSS · React 컴포넌트를 한 패키지에 담습니다.
설치하고 import 두 줄이면 COLDSURF 의 색 · 타이포 · 컴포넌트가 그대로 붙습니다.

**범용 UI 킷은 아닙니다.** 오픈소스로 공개하지만 COLDSURF 서비스에 맞춘 기본값(accent · paper ·
cover 톤)이 처음부터 들어 있습니다 — 그 결이 맞으면 그대로 쓰고, 아니면 토큰만 갈아끼웁니다.
목표가 "누구나 쓸 수 있게 범용화" 가 아니라 **"재활용 가능한 것을 잘 옮기는 것"** 이라서입니다.

## 설치 [#설치]

`@coldsurfers` 스코프는 GitHub Packages 에 있습니다. `.npmrc` 에 레지스트리를 적습니다.

```ini title=".npmrc"
@coldsurfers:registry=https://npm.pkg.github.com
```

```bash
pnpm add @coldsurfers/surf-ui
```

## 쓰기 [#쓰기]

CSS 배선은 **없습니다**. 진입점이 `styles.css` 를 직접 물고 오고, `.css.ts` 는 이 레포에서
컴파일해 내보내므로 소비자 쪽에 vanilla-extract 번들러 플러그인도 필요 없습니다.

```ts title="app/entry.tsx"
import { vars } from '@coldsurfers/surf-ui'
import { spacing } from '@coldsurfers/surf-ui/tokens'
import { Button } from '@coldsurfers/surf-ui/primitives'
```

<Callout type="warn">
  `styles.css` 는 한 장입니다(`cssCodeSplit: false`). `Button` 하나를 쓰는 소비자도 DS CSS 전량을
  뭅니다 — 배선 없이 끝나는 대신 치르는 값입니다.
</Callout>

## 진입점 [#진입점]

`exports` 맵에 있는 경로가 곧 API 입니다. 여기 없는 경로는 열리지 않습니다.

| 진입점                                | 무엇                                               |
| ---------------------------------- | ------------------------------------------------ |
| `@coldsurfers/surf-ui`             | `vars` 계약 · `@layer` 이름과 순서 · `media`            |
| `.../tokens`                       | 토큰 **값**. React 도 CSS 도 물지 않는 순수 데이터             |
| `.../primitives`                   | React 컴포넌트 — Button · Chip · Field · Modal · …   |
| `.../cards`                        | 카드 조립체 — ConcertCard · ArticleCard · LeadFeature |
| `.../layout`                       | Page · Container · PageBanner                    |
| `.../sprinkles`                    | 원자 유틸. **JS 38 kB** 라 배럴에서 갈라 두었다                |
| `.../style-utils`                  | `.css.ts` 저작 헬퍼                                  |
| `.../motion`                       | 모션 유틸 클래스                                        |
| `.../native` · `.../tokens/native` | React Native 표면                                  |
| `.../styles.css`                   | 컴파일된 CSS 한 장                                     |

## 미리보기는 실물이다 [#미리보기는-실물이다]

문서의 미리보기는 **실제로 발행되는 패키지를 import 해서** 그립니다. 그림도, 복사한 코드도
아닙니다. `exports` 맵에 없는 경로는 이 사이트도 열지 못하므로, 사이트가 빌드된다는 것 자체가
계약이 살아 있다는 증거입니다.


---

# 에이전트로 쓰기 (/docs/mcp)



이 사이트의 모든 페이지는 HTML 과 함께 **평문 사본**을 굽습니다. 사본에는 미리보기 대신 예제
원본이, props 표 대신 DS 소스 타입에서 뽑은 표가, 토큰 표 대신 발행된 값이 그대로 펼쳐져
있습니다. 에이전트가 읽는 것과 사람이 보는 것이 같은 데이터입니다.

## 한 줄로 시작 [#한-줄로-시작]

에이전트에게 이 단락을 그대로 붙여 넣습니다.

```txt
https://design.coldsurf.io/llms.txt 를 읽고 UI 는 @coldsurfers/surf-ui 로 짜줘.
컴포넌트를 쓰기 전에 그 페이지의 .txt 에서 props 와 예제를 확인해.
```

## 무엇을 읽히나 [#무엇을-읽히나]

| 주소                                 | 무엇                      | 언제                   |
| ---------------------------------- | ----------------------- | -------------------- |
| [`/llms.txt`](/llms.txt)           | 색인. 링크가 아래 `.txt` 로 갑니다 | 에이전트가 링크를 따라갈 수 있을 때 |
| [`/llms-full.txt`](/llms-full.txt) | 사이트 전체를 한 파일로           | 컨텍스트에 통째로 넣을 때       |
| `/llms/components/button.txt`      | 페이지 하나                  | 지금 쓰는 컴포넌트만 필요할 때    |

페이지 머리의 **복사** 버튼이 그 페이지의 사본을 클립보드에 담고, `Open ▾` 이 같은 사본을
ChatGPT · Claude 에 열어 줍니다.

## MCP [#mcp]

`@coldsurfers/design-system-mcp` 는 위 사본에 **목록 · 검색 · 경로 검증**을 얹은
[MCP](https://modelcontextprotocol.io) 서버입니다. 다른 데이터가 아닙니다. 레지스트리 설정은
[시작하기](/docs) 와 같습니다.

<Tabs items="['Claude Code', 'Claude Desktop · Cursor']">
  <Tab value="Claude Code">
    ```bash
    claude mcp add coldsurf-ds -- npx -y @coldsurfers/design-system-mcp
    ```
  </Tab>

  <Tab value="Claude Desktop · Cursor">
    ```json title="mcp.json"
    {
      "mcpServers": {
        "coldsurf-ds": {
          "command": "npx",
          "args": ["-y", "@coldsurfers/design-system-mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

| 툴               | 하는 일                                    |
| --------------- | --------------------------------------- |
| `discover_docs` | 카테고리 구조와 문서 수. 먼저 부릅니다                  |
| `list_docs`     | 제목 · 경로 · 한 줄 설명. `category` 로 좁힙니다     |
| `get_doc`       | 본문 하나 — 예제 코드 · props 표 · 토큰 값이 들어 있습니다 |

<Callout>
  패키지는 문서 사본을 들고 있지 않고 이 사이트를 읽어옵니다. 번들했다면 발행 시점에 얼어붙어
  소비자가 옛 문서를 최신인 줄 알고 읽습니다 — &#x2A;*틀린 문서보다 나쁜 건 틀린 줄 모르는 문서입니다.**
</Callout>

## 소비 레포의 AGENTS.md [#소비-레포의-agentsmd]

매번 프롬프트를 붙이지 않으려면 소비 레포의 `AGENTS.md`(또는 `CLAUDE.md`)에 적어 둡니다.

```md title="AGENTS.md"
## UI

- 컴포넌트 · 토큰은 `@coldsurfers/surf-ui` 를 쓴다. 문서: https://design.coldsurf.io/llms.txt
- 컴포넌트를 쓰기 전에 `/llms/<경로>.txt` 에서 props 와 예제를 확인한다. 추측하지 않는다.
- 색 · 여백은 리터럴 대신 토큰(`vars` · `--surf-*`)을 쓴다.
```


---

# Tailwind CSS (/docs/tailwind)



`@coldsurfers/tailwind4-theme` 는 토큰을 Tailwind v4 의 `@theme` 로 옮긴 **CSS 한 장**입니다.
JS 는 없고, Tailwind 를 안 쓰는 소비자는 설치를 안 해 0 바이트입니다 — DS 의 `exports` 에
올리지 않고 패키지를 가른 이유입니다.

## 설치 [#설치]

`@coldsurfers` 스코프는 GitHub Packages 에 있습니다. 레지스트리 설정은 [시작하기](/docs) 와 같습니다.

```bash
pnpm add -D @coldsurfers/tailwind4-theme
```

`tailwindcss@4` 와 `@coldsurfers/surf-ui` 이 peer 입니다. **값의 정본은 DS 쪽**이고 이
패키지는 그 값을 `var()` 로 참조만 하므로, 변수 시트를 반드시 같이 물어야 합니다.

## 배선 [#배선]

<Tabs items="['토큰만', 'DS 컴포넌트까지']">
  <Tab value="토큰만">
    Tailwind 로 화면을 짜면서 색 · 간격만 우리 값으로 맞출 때입니다.

    ```css title="app/global.css"
    @import "tailwindcss";
    @import "@coldsurfers/surf-ui/tokens.css";
    @import "@coldsurfers/tailwind4-theme";
    ```

    `tokens.css` 는 무레이어 `:root` 한 장입니다 — 리셋도 컴포넌트 CSS 도 들어 있지 않습니다.
    레이어 밖이라 캐스케이드 다툼도 없고, 그래서 이 조합은 **import 순서를 타지 않습니다**.
  </Tab>

  <Tab value="DS 컴포넌트까지">
    `Button` · `ConcertCard` 같은 primitives 를 같이 쓸 때입니다.

    ```css title="app/global.css"
    @import "@coldsurfers/surf-ui/styles.css";
    @import "tailwindcss";
    @import "@coldsurfers/tailwind4-theme";
    ```

    `styles.css` 가 `tokens.css` 의 이름과 값을 전부 품고 있으므로 둘을 같이 물 필요는 없습니다.

    <Callout type="warn">
      **`styles.css` 가 `tailwindcss` 보다 먼저여야 합니다.** 레이어 순서는 이름이 *처음 등장한*
      순서로 굳고, 나중 선언이 그걸 되돌리지 못합니다. 실측(v4.3.3):

      ```
      tailwind 먼저 → base · components · utilities · ds-reset · ds-tokens · ds-components · ds-utilities
      DS 먼저      → base · ds-reset · ds-tokens · ds-components · components · ds-utilities · utilities
      ```

      앞쪽에서는 `ds-components` 가 Tailwind `utilities` 를 이깁니다 — `p-4` 로 컴포넌트 여백을
      덮으려 해도 먹지 않습니다.
    </Callout>
  </Tab>
</Tabs>

<Callout>
  `@layer …;` 선언을 손으로 적지 않습니다. `styles.css` 의 첫 줄이 [순서 계약](/docs/foundations/layers)을
  직접 발행합니다 — 적어야 할 건 import 순서 하나뿐입니다.
</Callout>

## 무엇이 열리는가 [#무엇이-열리는가]

`@theme` 는 Tailwind 네임스페이스에 이름을 얹을 뿐입니다. **값은 여기 없습니다** — 아래 표의
"정본" 이 값을 갖습니다.

| 네임스페이스                            | 유틸                                         | 정본                                  |
| --------------------------------- | ------------------------------------------ | ----------------------------------- |
| `--color-*`                       | `bg-bg` · `text-heading` · `border-border` | [색](/docs/foundations/colors)       |
| `--color-cover-*`                 | `bg-cover-forest` · `text-cover-plum`      | [색](/docs/foundations/colors)       |
| `--color-paper-*`                 | `bg-paper-warm`                            | [색](/docs/foundations/colors)       |
| `--radius-*`                      | `rounded-lg` · `rounded-full`              | [색](/docs/foundations/colors)       |
| `--spacing-*`                     | `p-4` · `gap-2.5` · `mt-14`                | [여백](/docs/foundations/spacing)     |
| `--text-*`                        | `text-sm` · `text-3xs`                     | [타이포](/docs/foundations/typography) |
| `--text-{그룹}-{크기}`                | `text-display-md` · `text-eyebrow-sm`      | [타이포](/docs/foundations/typography) |
| `--leading-*` · `--font-weight-*` | `leading-relaxed` · `font-regular`         | [타이포](/docs/foundations/typography) |
| `--font-*`                        | `font-sans` · `font-serif` · `font-mono`   | [타이포](/docs/foundations/typography) |
| `--breakpoint-*`                  | `tablet:p-8` · `desktop:p-10`              | [계약과 레이어](/docs/foundations/layers) |

```tsx
<article className="rounded-xl border border-border bg-surface p-6">
  <p className="text-eyebrow-md font-mono uppercase text-muted">now playing</p>
  <h2 className="text-display-md font-serif text-heading">Slowdive</h2>
  <p className="text-sm leading-relaxed text-body">Souvlaki, 1993</p>
</article>
```

`uppercase` 를 직접 적은 게 실수가 아닙니다 — 아래 "안 넘어오는 것" 을 보세요.

## 좌표계가 둘이 됩니다 [#좌표계가-둘이-됩니다]

Tailwind 기본 스케일은 지워지지 않습니다. 우리 이름이 **덮어쓴 자리만** 바뀌고 나머지는 그대로
살아 있어서, 같은 뜻의 이름이 둘씩 생깁니다.

<Callout type="warn">
  * `sm:` · `md:` · `lg:` 가 그대로입니다. `tablet:`(768px)과 `md:`(48rem)은 값이 같지만 이름이
    둘입니다 — 팀에서 하나로 정해 씁니다
  * 스케일 밖 값도 조용히 컴파일됩니다. `p-9` 는 `calc(var(--spacing) * 9)` 로 떨어집니다 —
    4px 격자를 벗어난 걸 Tailwind 가 막아주지 않습니다
  * `font-bold`(700)는 Tailwind 기본값입니다. 토큰의 무게는 `light` · `regular` · `medium` ·
    `semibold` 넷뿐입니다
</Callout>

## 안 넘어오는 것 [#안-넘어오는-것]

* **`textTransform`.** eyebrow 는 대문자 변환이 스타일의 일부지만 `--text-*` 네임스페이스로는
  크기 · 행간 · 자간까지만 표현됩니다. `uppercase` 는 직접 적습니다
* **`sprinkles` · `vars` · 컴포넌트 recipe.** JS 쪽 계약이라 CSS 한 장에 담기지 않습니다.
  `.css.ts` 를 직접 쓰는 소비자는 [계약과 레이어](/docs/foundations/layers)로 갑니다

## 이름에 `4` 가 붙은 이유 [#이름에-4-가-붙은-이유]

Tailwind major 마다 `@theme` 규약이 갈립니다. 이름에 major 를 박아 두면 v5 용을 **나란히** 낼 수
있습니다 — 기존 소비자를 깨지 않고. (선례: `@seed-design/tailwind4-theme`)


---

# Button (/docs/components/button)



```tsx
import { Button } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <Button>취향 이어보기</Button>
      <Button variant="accent">티켓 예매</Button>
      <Button variant="secondary">저장</Button>
      <Button variant="outline">공유</Button>
      <Button variant="ghost">읽기 →</Button>
      <Button variant="danger">탈퇴하기</Button>
    </>
  )
}
```

variant 는 여섯입니다. `primary` 는 ink 필, `accent` 는 주 행동 파랑, `secondary` 는 회색 면(저장 · 프로필),
`outline` 은 흰 배경 + 테두리, `ghost` 는 무테 텍스트 액션, `danger` 는 statusDanger 필입니다.

시안 v3 `v3/Button` 과는 이렇게 맞춥니다. `Kind=primary` 는 `accent`, `Kind=secondary` 는 `secondary`,
`Kind=ink` 는 `primary` 이고 셋 다 `size="lg"` 입니다. `Kind=google` 은 `primary` 에 `leadingIcon` 으로
G 마크를 넣은 것이라 variant 를 따로 두지 않습니다.

<Callout type="warn">
  **`danger` 는 색이 아니라 뜻으로 고릅니다.** 되돌릴 수 없는 액션 — 탈퇴 · 영구 삭제 — 의
  자리입니다. 눈에 띄게 하려고 고르는 것이 아니라 *되돌릴 수 없음*을 말하려고 고릅니다.
  그래서 주 액션인 `accent` 와 나란히 서지 않습니다. 한 화면에 둘이 같이 필요하다면 둘 중
  하나는 주 액션이 아닙니다.
</Callout>

## 크기와 아이콘 [#크기와-아이콘]

```tsx
import { Button } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <Button size="sm">sm</Button>
      <Button size="md">md</Button>
      <Button size="cta" variant="accent">
        cta
      </Button>
      <Button size="lg" variant="accent">
        lg
      </Button>
      <Button variant="ghost" trailingIcon="→">
        읽기
      </Button>
    </>
  )
}
```

<Callout>
  **size 는 넷입니다 — 더 늘리지 않습니다.** `lg` 는 시안 v3 의 알약 48(굵게)입니다. 시안 컨트롤 높이는 다섯 종이지만 그대로 받으면
  `size` 가 7종이 됩니다. 그건 추상화가 아니라 목록입니다. variant 를 늘리기 전에
  *이 축이 이 컴포넌트의 것인가* 를 먼저 묻습니다.
</Callout>

## 모서리 · 앞 아이콘 · 비활성 [#모서리--앞-아이콘--비활성]

```tsx
import { Button } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <Button size="cta" variant="accent" shape="pill">
        내 동네로 정하기
      </Button>
      <Button size="cta" variant="outline" shape="pill" leadingIcon="✓">
        내 동네
      </Button>
      <Button size="cta" variant="accent" disabled>
        잠김
      </Button>
    </>
  )
}
```

`shape="pill"` 은 크기와 상관없이 알약 모서리입니다. 높이와 모서리는 따로 움직이므로 `size` 에
섞지 않습니다. `leadingIcon` 은 라벨 앞, `trailingIcon` 은 라벨 뒤 슬롯입니다.

`disabled` 는 모든 variant 에서 흐려지고(`opacity: 0.4&#x60;) hover 가 걸리지 않습니다. **"이미 됐다"를
보여주는 자리에 `disabled` 를 쓰지 않습니다** — 저장됨 같은 상태는 흐리지 않고 선명하게 서야 합니다.

그 자리의 누름 가드는 &#x2A;*소비처가 합니다.** `Button` 은 `aria-disabled` 를 따로 읽지 않아서, 붙여도
클릭이 그대로 들어오고 hover 도 걸립니다. `onClick` 을 넘기지 않거나 핸들러 안에서 막습니다.

## 라우팅 CTA 는 `asChild` [#라우팅-cta-는-aschild]

버튼처럼 보이지만 실제로는 이동이면 `<button>` 이 아니라 `<a>` 여야 합니다.
`asChild` 는 자기 엘리먼트 대신 자식에 스타일을 입힙니다.

```tsx
<Button variant="accent" size="cta" asChild>
  <Link to="/this-weekend">이번 주말 보기</Link>
</Button>
```

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `variant?` | `'primary' \| 'secondary' \| 'ghost' \| 'accent' \| 'outline' \| 'danger'` | — | — |
| `size?` | `'sm' \| 'md' \| 'cta' \| 'lg'` | — | — |
| `shape?` | `'rounded' \| 'pill'` | — | — |
| `leadingIcon?` | `ReactNode` | — | — |
| `trailingIcon?` | `ReactNode` | — | — |
| `asChild?` | `boolean` | — | — |

그 밖의 `ButtonHTMLAttributes<HTMLButtonElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Callout (/docs/components/callout)



```tsx
import { Callout } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div style={{ display: 'grid', gap: 12, width: '100%' }}>
      <Callout action={<a href="#terms">현행 보기 →</a>}>지난 버전을 보고 있습니다.</Callout>
      <Callout icon="📍">
        대학로를 내 동네로 정하려면 로그인이 필요합니다. 로그인하면 대학로 페이지로 돌아와 바로
        저장합니다.
      </Callout>
      <Callout tone="success">저장했습니다.</Callout>
      <Callout tone="warning">예매 마감이 한 시간 남았습니다.</Callout>
      <Callout tone="danger" role="alert">
        로그인에 실패했습니다.
      </Callout>
    </div>
  )
}
```

## Toast 와 갈리는 지점은 수명이다 [#toast-와-갈리는-지점은-수명이다]

토스트는 1.6초 뒤 사라지는 **액션 결과**고, Callout 은 조건이 유지되는 동안 지면에 서 있는
**상태**입니다. 둘을 한 축으로 묶지 않습니다.

## `role` 을 붙여주지 않는다 [#role-을-붙여주지-않는다]

같은 상자가 스크린리더에 읽혀야 할 때(소셜 로그인 콜백 실패)와 읽히면 방해일 때(정적 안내)가
있는데, 그건 DS 가 알 수 없는 맥락입니다. `...rest` 로 통과만 시킵니다.

```tsx
<Callout tone="danger" role="alert">로그인에 실패했습니다</Callout>
```

## 앞 아이콘은 `icon` [#앞-아이콘은-icon]

`icon` 은 본문과 한 덩어리입니다. 본문이 두 줄로 넘어가도 아이콘은 첫 줄 옆에 서고, 액션과 따로
접히지 않습니다. 장식이라 스크린리더에서는 숨깁니다.

## `margin` 을 소유하지 않는다 [#margin-을-소유하지-않는다]

상자가 앞뒤 무엇과 서는지는 지면이 압니다. 바깥 여백은 소비처가 줍니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `tone?` | `'accent' \| 'success' \| 'warning' \| 'danger'` | — | 기본 `accent`. status 3종은 글자까지 톤색이 되고 `accent` 만 중립 글자다(#34 D-4). |
| `icon?` | `ReactNode` | — | 본문 앞 아이콘. 장식이라 스크린리더에서 숨긴다. |
| `action?` | `ReactNode` | — | 오른쪽 끝 액션(링크·버튼). 폭이 모자라면 본문 아래로 접힌다. |

그 밖의 `HTMLAttributes<HTMLDivElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Checkbox (/docs/components/checkbox)



```tsx
import { Checkbox } from '@coldsurfers/surf-ui/primitives'
import { useState } from 'react'

export default function Example() {
  const [agreed, setAgreed] = useState(true)

  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <Checkbox checked={agreed} onChange={(e) => setAgreed(e.target.checked)}>
        이용약관에 동의합니다
      </Checkbox>
      <Checkbox disabled>마케팅 수신 (비활성)</Checkbox>
    </div>
  )
}
```

네이티브 `<input type="checkbox">` 를 시각적으로만 감춥니다. 접근성·키보드·폼 제출·
react-hook-form 은 전부 네이티브에 그대로 위임하고, 칠하는 것만 가져옵니다.

`ref` 는 내부 실제 `<input>` 을 노출합니다 — `{ focus, blur }` 만 노출하면 RHF 의
`defaultValues` 가 깨집니다.

라벨 텍스트 색은 강제하지 않고 **부모에서 상속**합니다. 라이트 폼이든 다크 밴드든 감싼 문맥을
따릅니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `children?` | `ReactNode` | — | 체크박스 우측 라벨/설명 슬롯. |
| `containerClassName?` | `string` | — | 감싸는 `<label>` 추가 클래스(그리드 배치·간격 등). |

그 밖의 `Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Chip (/docs/components/chip)



```tsx
import { Chip } from '@coldsurfers/surf-ui/primitives'
import { useState } from 'react'

const FILTERS = ['오늘', '이번 주', '이번 달']

export default function Example() {
  const [picked, setPicked] = useState('오늘')

  return (
    <>
      {FILTERS.map((label) => (
        <Chip key={label} active={picked === label} onClick={() => setPicked(label)}>
          {label}
        </Chip>
      ))}
      <Chip size="lg" active>
        공연
      </Chip>
      <Chip size="lg">전시</Chip>
      <Chip as="span" size="sm">
        슈게이즈
      </Chip>
    </>
  )
}
```

quick chip · section chip · filter · genre 태그가 전부 이 하나입니다.
상호작용이면 기본 `button`, 라벨이면 `as="span"`, 라우팅 링크면 `asChild` 입니다.

`size="lg"` 는 시안 v3 `v3/Chip` 입니다. 테두리 없는 회색 알약(38)이고 주제 · 동네를 고르는 줄에 씁니다.

## `active` 의 시각 언어는 여기가 정본이다 [#active-의-시각-언어는-여기가-정본이다]

선택된 칩은 **잉크 바탕 + 흰 글자**입니다(`selectedFill` · `selectedText`). 2026-09-28 부터 `accent` 파랑이
정본이었는데, 시안 v3(Figma 1455:250)가 파랑을 주 행동 하나에만 남기면서 2026-10-17 에 잉크로 돌아왔습니다.

## 필터 칩은 링크여야 한다 [#필터-칩은-링크여야-한다]

필터된 면이 색인되려면 크롤 가능한 `<a href>` 여야 합니다. 그래서 필터 맥락의 기본 사용법은
`asChild` 입니다.

```tsx
<Chip asChild active={picked === '오늘'}>
  <Link to="?when=today">오늘</Link>
</Chip>
```

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `as?` | `'button' \| 'span'` | — | — |
| `active?` | `boolean` | — | — |
| `size?` | `'sm' \| 'md' \| 'lg'` | — | — |
| `asChild?` | `boolean` | — | 자기 엘리먼트 대신 자식(라우터 `Link`)에 스타일을 입힌다 — `Button`·`Skeleton` 과 같은 규율(#39 D-6). 필터 칩은 **크롤 가능한 `<a href>` 여야** 필터된 면이 색인되므로 (`GigChip`·`new-feed` 가 그 이유를 주석에 남겼다) 이쪽이 필터 맥락의 기본 사용법이다. |


---

# CoverBlock (/docs/components/cover-block)



```tsx
import { CoverBlock } from '@coldsurfers/surf-ui/primitives'
import { COVER_TONES } from '@coldsurfers/surf-ui/tokens'

export default function Example() {
  return (
    <>
      {COVER_TONES.map((tone) => (
        <CoverBlock
          key={tone}
          tone={tone}
          style={{ width: 120, height: 120, display: 'grid', placeItems: 'center' }}
        >
          {tone}
        </CoverBlock>
      ))}
    </>
  )
}
```

높이는 소비처가 정합니다(ConcertCard 190/160 · ArticleCard 200/150). 여기가 책임지는 건
색면뿐입니다.

## 기본은 `note` 입니다 [#기본은-note-입니다]

`tone` 을 안 주면 **기다림의 면**(`note`)이 섭니다 — 「아직 그림이 없다」는 상태의 면이고,
`Skeleton`(API 대기)과 같은 값(`color.surfaceHover`)을 읽습니다. 이미지가 오는 중이든, 없든,
실패했든 한 밝기로 서게 하려는 것입니다. 공연 카드(`ConcertCard`)는 이 면 하나만 씁니다.

`note` 위에 서는 것들은 `currentColor` 로 잉크를 물고, 어두운 6톤 위에서는 종이를 뭅니다 —
면이 글자색까지 정하므로 소비처가 톤을 한 번 더 받을 일이 없습니다.

## 팔레트 6톤은 편집 표지가 씁니다 [#팔레트-6톤은-편집-표지가-씁니다]

커버 팔레트는 **스킴을 타지 않는 불변 scale** 입니다. 항상 어두운 필 위에 paper 텍스트가
올라가는 에디토리얼 커버(`ArticleCard` · `LeadFeature`)의 바닥색이라, 다크 스킴이 살아 있던
때에도 뒤집지 않았습니다. 거긴 색 다양성이 곧 편집 디자인인 자리입니다.

색면이 아닌 다른 표면(아바타 원 등)도 같은 팔레트를 쓰므로 `coverTone` 을 재수출합니다.

```ts
import { coverToneFor } from '@coldsurfers/surf-ui/tokens'

const tone = coverToneFor(issue.slug) // 같은 id 는 항상 같은 색
```

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `tone?` | `'forest' \| 'wine' \| 'navy' \| 'moss' \| 'steel' \| 'plum' \| 'note'` | — | 색면 톤. **기본은 `note`** — 지향점이 그쪽이라 기본값이 그쪽이다. `note` 는 **아직 그림이 없다**는 상태의 면이다 — 이미지가 오는 중이거나, 없거나, 실패했다. `Skeleton`(API 대기)과 같은 값을 읽으므로 기다림이 한 밝기로 선다. 팔레트 6톤은 **편집 표지**가 쓴다(`ArticleCard`·`LeadFeature`). 거긴 로딩 면이 아니라 색 다양성이 곧 편집 디자인인 자리라 `coverToneFor` 로 흩는다. 공연 카드는 이 축을 안 쓴다 — 그쪽은 면이 하나다. |

그 밖의 `HTMLAttributes<HTMLDivElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Eyebrow (/docs/components/eyebrow)



```tsx
import { Eyebrow } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div style={{ display: 'grid', gap: 8 }}>
      <Eyebrow size="md" tone="accent">
        This week&rsquo;s pick
      </Eyebrow>
      <Eyebrow size="sm">Live · 이번 주 홍대</Eyebrow>
      <Eyebrow size="xs" tone="subtle">
        Issue 07
      </Eyebrow>
    </div>
  )
}
```

카테고리와 PICK 은 `accent`, LIVE 와 ISSUE 는 `muted` 가 기본 짝입니다.

크기는 `editorialType.eyebrow` 슬롯에 대응합니다 — `xs`(10px) · `sm`(11px) · `md`(12px).
tracking 은 크기마다 다릅니다: 0.18em · 0.20em · 0.26em.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `size?` | `'xs' \| 'sm' \| 'md'` | — | — |
| `tone?` | `'muted' \| 'subtle' \| 'accent'` | — | — |

그 밖의 `HTMLAttributes<HTMLParagraphElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Field (/docs/components/field)



```tsx
import { Field } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div style={{ display: 'grid', gap: 12, width: '100%', maxWidth: 420 }}>
      <Field placeholder="아티스트나 장르 하나…" trailing="↵" />
      <Field placeholder="비활성" disabled />
    </div>
  )
}
```

`trailing` 은 우측 슬롯입니다 — ↵ 힌트나 작은 버튼이 들어갑니다.

포커스되면 테두리가 accent 1.5px 로 바뀝니다(라이트 표면).

`tone="dark"` 는 다크 밴드(`color.strong`) 위에 앉히는 변형입니다. 기본은 라이트 표면입니다.

`ref` 는 내부 실제 `<input>` 을 그대로 노출합니다 — react-hook-form 의 `defaultValues` 호환입니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `trailing?` | `ReactNode` | — | — |
| `containerClassName?` | `string` | — | — |
| `tone?` | `'light' \| 'dark'` | — | 깔린 표면. `dark` 는 다크 밴드(`color.strong`) 위 — 기본은 라이트 표면. |

그 밖의 `InputHTMLAttributes<HTMLInputElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Modal (/docs/components/modal)



```tsx
import { Button, Modal } from '@coldsurfers/surf-ui/primitives'
import { useRef, useState } from 'react'

export default function Example() {
  const [open, setOpen] = useState(false)
  const triggerRef = useRef<HTMLButtonElement>(null)

  return (
    <>
      <Button ref={triggerRef} onClick={() => setOpen(true)}>
        모달 열기
      </Button>
      <Modal
        open={open}
        onClose={() => setOpen(false)}
        label="예매를 취소할까요?"
        triggerRef={triggerRef}
        panelClassName="preview-modal-panel"
      >
        <p style={{ margin: 0, fontWeight: 500 }}>예매를 취소할까요?</p>
        <p style={{ margin: '8px 0 16px', color: 'var(--surf-text-secondary)' }}>
          취소한 자리는 바로 다른 사람에게 넘어갑니다.
        </p>
        <div style={{ display: 'flex', gap: 8, justifyContent: 'flex-end' }}>
          <Button variant="ghost" onClick={() => setOpen(false)}>
            돌아가기
          </Button>
          <Button variant="accent" onClick={() => setOpen(false)}>
            취소하기
          </Button>
        </div>
      </Modal>
    </>
  )
}
```

행동은 `useDialogBehavior` 가, 마크업만 Modal 이 듭니다. 오버레이가 `role="dialog"` 를 들고,
오버레이 클릭은 `dismissible` 일 때만 닫습니다.

## `document.body` 로 portal 한다 [#documentbody-로-portal-한다]

<Callout tone="warning">
  `fixed inset-0` 은 overflow 클리핑만 면해줄 뿐입니다. `position: sticky` · `transform` ·
  `filter` 를 가진 조상이 있으면 그 조상이 stacking context 를 만들어, 오버레이의 `z-index` 가
  페이지가 아니라 **그 조상 안에서만** 유효해집니다. 실제로 sticky 레일 위에서 티켓이 모달 위로
  올라온 사고가 있었습니다.
</Callout>

대신 표면 오버라이드를 인라인으로 주입하는 서브트리 안에서는 그 값을 못 받습니다. 팔레트는
문제없습니다 — 스킴이 하나뿐이라 `:root` 가 곧 light 입니다. 바닥색이 필요하면 소비처가 직접
줍니다.

전면 시트처럼 백드롭/패널 구조가 아닌 표면은 이 컴포넌트 대신 훅만 씁니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `open` | `boolean` | — | — |
| `onClose` | `() => void` | — | — |
| `label` | `string` | — | 다이얼로그 `aria-label`. |
| `dismissible?` | `boolean` | — | false 면 Escape·백드롭 클릭을 무시한다(처리 중 잠금). 기본 true. |
| `triggerRef?` | `RefObject<HTMLElement \| null>` | — | 닫힌 뒤 포커스를 되돌릴 트리거. |
| `placement?` | `'center' \| 'bottom' \| 'top' \| 'sheet'` | — | 패널이 서는 자리. 기본 `center`. center 가운데 (기본) — 확인 다이얼로그 top 위쪽 — 커맨드팔레트. 오프셋(`margin-top`)은 소비처가 준다 bottom 아래 붙는 시트 — 오버레이 여백이 0이라 화면 모서리까지 닿는다 sheet 모바일 `bottom` · 데스크탑 `center` — `Sheet` 가 쓴다 `overlayClassName` 보다 **앞에** 붙으므로 소비처가 여전히 덮을 수 있다. |
| `overlayClassName?` | `string` | — | 오버레이 추가 클래스 — 배경(`bg-black/50`). 정렬은 `placement` 가 든다. |
| `panelClassName?` | `string` | — | 패널 추가 클래스 — 폭(`max-w-sm`)·여백. |
| `children` | `ReactNode` | — | — |


---

# Note (/docs/components/note)



```tsx
import { Note } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <Note meta="9월 20일 19:00">언니네 이발관 단독공연</Note>
      <Note meta="어제 저장함" tone="muted">
        Slowdive 첫 내한
      </Note>
      <Note>메타 없이 한 줄만</Note>
    </>
  )
}
```

메타 11px ↔ 헤드라인 14px, 차이 3px, 무게는 둘 다 medium 하나입니다. 위계를 *크기*가 아니라
**여백과 순서**로 만드는 규율이 여기서 가장 압축돼 있습니다.

`meta` 는 시각·수치·출처처럼 헤드라인을 *놓을 자리*를 말하는 줄이라 mono 입니다. 없으면
안 그립니다.

## 슬롯이 둘뿐인 이유 [#슬롯이-둘뿐인-이유]

배치가 아니라 **타이포 묶음**입니다. 자유로운 `ReactNode` 배치를 열면 부르는 쪽이 매번 두 줄의
크기·무게를 다시 정하게 되고, 그럼 이 컴포넌트가 막으려던 드리프트가 그대로 돌아옵니다.
링크·`<time>` 으로 감싸는 건 되지만 다른 서식을 얹는 자리는 아닙니다.

여러 장을 쌓는 패널은 여기 없습니다 — 배경이 그라디언트든 `surface2` 든 호출자가 정하는
축이고, 그 껍데기는 `<div>` 한 겹이라 추출할 중복이 없습니다.

## 값은 랜딩 정본 그대로입니다 [#값은-랜딩-정본-그대로입니다]

`apps/im-coldsurf` 랜딩의 알림 패널이 이 톤의 정본이고 나머지 표면이 그쪽으로 옮겨 가는
중이라, &#x2A;*정본이 픽셀 하나도 움직이면 안 됩니다.** 그래서 눈금 밖 리터럴 넷(radius 14 ·
padding 16/18/22 · 헤드라인 15px)을 접지 않고 슬롯 안에 그대로 뒀습니다.

반응형 축도 정본을 따라 `desktop`(1024) 하나입니다 — 정본이 "태블릿 시안이 없으므로 중간
단을 만들지 않는다"고 못박아 뒀습니다. 여기서 `tablet`(768)을 쓰면 정본이 일부러 안 만든
중간 단이 생깁니다.

## `tone` 기본값이 `accent` 인 이유 [#tone-기본값이-accent-인-이유]

정본이 그렇습니다. 「accent 글자는 *누를 것*에만」 규율의 **명시적 예외 자리**입니다 — 노트의
메타 한 줄은 그 규율이 처음부터 인정한 유일한 채도 자리입니다. 읽는 글로 쓰는 노트는
`tone="muted"` 로 내립니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `meta?` | `ReactNode` | — | 위 한 줄 — 시각·수치·출처처럼 헤드라인을 *놓을 자리*를 말한다. 없으면 안 그린다. |
| `tone?` | `'accent' \| 'muted'` | — | 메타 줄의 색. 기본 `accent`. |
| `children` | `ReactNode` | — | 아래 한 줄 — 이 카드가 말하려는 것. |

그 밖의 `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Popover (/docs/components/popover)



```tsx
import { Chip, POPOVER_MENU_CLS, Popover } from '@coldsurfers/surf-ui/primitives'

const LINKS = ['TAPE', 'MIND', 'DEV']

export default function Example() {
  return (
    <Popover
      role="menu"
      menuClassName={POPOVER_MENU_CLS}
      trigger={({ open, toggle }) => (
        <Chip active={open} onClick={toggle}>
          카테고리 ▾
        </Chip>
      )}
    >
      {({ close }) =>
        LINKS.map((label) => (
          <button
            key={label}
            type="button"
            role="menuitem"
            onClick={close}
            style={{
              display: 'block',
              width: '100%',
              padding: '8px 14px',
              border: 0,
              background: 'none',
              textAlign: 'left',
              cursor: 'pointer',
            }}
          >
            {label}
          </button>
        ))
      }
    </Popover>
  )
}
```

그룹 칩이 쓰던 open 상태 · 바깥클릭/Escape 닫기 · 위치잡기 · 뷰포트
maxHeight 를 한 어휘로 수렴합니다.

위치잡기는 `createPortal(document.body)` + `position: fixed` 한 전략으로 통일했습니다 —
어떤 `overflow` · `transform` 조상 안에서도 클립되지 않습니다.

트리거는 `inline-flex` 앵커로 감싸 측정하므로, 트리거 컴포넌트에 `forwardRef` 를 강제하지
않습니다.

## 닫히는 조건 [#닫히는-조건]

바깥 mousedown · Escape · **앵커를 품은 스크롤러**의 스크롤(capture) · resize 시 재측정입니다.

스크롤에서 닫는 근거는 「스크롤했다」가 아니라 \*\*「앵커가 움직였다」\*\*입니다 — 메뉴는 `fixed` 라
앵커 rect 로 잡은 좌표가 어긋나야 닫을 이유가 생깁니다. 그래서 판정이 한 줄입니다: &#x2A;이
스크롤러가 앵커를 품고 있나.*

| 스크롤 출처          | 앵커를 품나            | 결과 |
| --------------- | ----------------- | -- |
| 페이지(`document`) | O                 | 닫힘 |
| 앵커를 감싼 스크롤 패널   | O                 | 닫힘 |
| 메뉴 내부(긴 옵션 목록)  | X (body 로 portal) | 유지 |
| 옆에 놓인 가로 칩 줄    | X                 | 유지 |

마지막 줄이 이 판정을 좁힌 이유입니다. 「메뉴 밖 스크롤이면 전부 닫기」였을 땐, 팝오버 아래
가로 칩 줄이 관성으로 굴러가는 중에 트리거를 누르면 &#x2A;*열리자마자 닫혔습니다.**

## 표면은 소비처가 든다 [#표면은-소비처가-든다]

메뉴 박스 장식 전체가 `menuClassName` 입니다. 기본 표면을 원하면 `POPOVER_MENU_CLS` 를 섞습니다.

```tsx
<Popover menuClassName={cx(POPOVER_MENU_CLS, myMenu)} …>
```

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `trigger` | `(props: { open: boolean; toggle: () => void; }) => ReactNode` | — | 트리거 — `open`/`toggle` 을 받아 칩·버튼 등을 렌더. |
| `children` | `(props: { close: () => void; }) => ReactNode` | — | 팝오버 본문 — `close` 로 항목 선택 시 닫는다. |
| `role?` | `'menu' \| 'listbox'` | — | 메뉴 컨테이너의 접근성 role. |
| `offset?` | `number` | — | 트리거 하단과 메뉴 사이 간격(px). 기본 6. |
| `className?` | `string` | — | 앵커 span 추가 클래스(정렬 등). |
| `menuClassName?` | `string` | — | 메뉴 박스 클래스 — 표면 장식 전체를 소비처가 든다. 기본 표면을 원하면 `cx(POPOVER_MENU_CLS, '…')` 로 조합한다. |


---

# ReactionBar (/docs/components/reaction-bar)



```ts
import { ReactionBar } from '@coldsurfers/surf-ui/primitives'
```

```tsx
import { ReactionBar } from '@coldsurfers/surf-ui/primitives'
import { useState } from 'react'

const BASE = [
  { id: 'go', label: '🔥 갈래', count: 22 },
  { id: 'hmm', label: '🤔 고민', count: 9 },
  { id: 'pricey', label: '💸 비싸', count: 4 },
]

export default function Example() {
  const [mine, setMine] = useState<string | null>('go')
  const items = BASE.map((r) => ({ ...r, count: r.count + (r.id === mine ? 1 : 0) }))

  return (
    <ReactionBar
      aria-label="이 공연 어때요"
      items={items}
      value={mine}
      onChange={setMine}
      style={{ width: '100%', maxWidth: 360 }}
    />
  )
}
```

같은 폭 버튼 N개에 라벨과 개수를 붙입니다(Figma `1028:400`). 기본은 하나만 켜지고, 켠 것을 다시 누르면 `onChange(null)` 입니다.

## 여러 개 [#여러-개]

`multiple` 이면 칸마다 따로 켜고 끕니다(🔥 갈래 + 💸 비싸 = 가고 싶은데 비싸). `value` 는 켠 id 배열, `onChange(id, on)` 은 누른 칸과 켜질지를 넘깁니다 — 서버에 칸 하나씩 켜고 끄는 요청을 보내기 좋은 모양입니다.

```tsx
import { ReactionBar } from '@coldsurfers/surf-ui/primitives'
import { useState } from 'react'

const BASE = [
  { id: 'go', label: '🔥 갈래', count: 22 },
  { id: 'hmm', label: '🤔 고민', count: 9 },
  { id: 'pricey', label: '💸 비싸', count: 4 },
]

export default function Example() {
  const [mine, setMine] = useState<string[]>(['go', 'pricey'])
  const items = BASE.map((r) => ({ ...r, count: r.count + (mine.includes(r.id) ? 1 : 0) }))

  return (
    <ReactionBar
      multiple
      aria-label="이 공연 어때요"
      items={items}
      value={mine}
      onChange={(id, on) => setMine((prev) => (on ? [...prev, id] : prev.filter((k) => k !== id)))}
      style={{ width: '100%', maxWidth: 360 }}
    />
  )
}
```

숫자를 올리는 일(낙관적 갱신)은 소비처가 `items` 로 넘깁니다. `fieldset` 이라 `disabled` 하나로 안의 버튼이 함께 꺼지고, 이름은 `aria-label` 로 붙입니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `multiple?` | `boolean` | — | — |
| `value` | `string \| readonly string[] \| null` | — | — |
| `onChange` | `((id: string \| null) => void) \| ((id: string, on: boolean) => void)` | — | — |
| `items` | `readonly ReactionItem[]` | — | — |
| `disabled?` | `boolean` | — | — |
| `form?` | `string` | — | — |
| `name?` | `string` | — | — |
| `defaultChecked?` | `boolean` | — | — |
| `defaultValue?` | `string \| number \| readonly string[]` | — | — |
| `suppressContentEditableWarning?` | `boolean` | — | — |
| `suppressHydrationWarning?` | `boolean` | — | — |
| `accessKey?` | `string` | — | — |
| `autoCapitalize?` | `"off" \| "none" \| "on" \| "sentences" \| "words" \| "characters" \| (string & {})` | — | — |
| `autoFocus?` | `boolean` | — | — |
| `className?` | `string` | — | — |
| `contentEditable?` | `Booleanish \| "inherit" \| "plaintext-only"` | — | — |
| `contextMenu?` | `string` | — | — |
| `dir?` | `string` | — | — |
| `draggable?` | `Booleanish` | — | — |
| `enterKeyHint?` | `'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'` | — | — |
| `hidden?` | `boolean` | — | — |
| `id?` | `string` | — | — |
| `lang?` | `string` | — | — |
| `nonce?` | `string` | — | — |
| `slot?` | `string` | — | — |
| `spellCheck?` | `Booleanish` | — | — |
| `style?` | `CSSProperties` | — | — |
| `tabIndex?` | `number` | — | — |
| `title?` | `string` | — | — |
| `translate?` | `'yes' \| 'no'` | — | — |
| `radioGroup?` | `string` | — | — |
| `role?` | `AriaRole` | — | — |
| `about?` | `string` | — | — |
| `content?` | `string` | — | — |
| `datatype?` | `string` | — | — |
| `inlist?` | `any` | — | — |
| `prefix?` | `string` | — | — |
| `property?` | `string` | — | — |
| `rel?` | `string` | — | — |
| `resource?` | `string` | — | — |
| `rev?` | `string` | — | — |
| `typeof?` | `string` | — | — |
| `vocab?` | `string` | — | — |
| `autoCorrect?` | `string` | — | — |
| `autoSave?` | `string` | — | — |
| `color?` | `string` | — | — |
| `itemProp?` | `string` | — | — |
| `itemScope?` | `boolean` | — | — |
| `itemType?` | `string` | — | — |
| `itemID?` | `string` | — | — |
| `itemRef?` | `string` | — | — |
| `results?` | `number` | — | — |
| `security?` | `string` | — | — |
| `unselectable?` | `'off' \| 'on'` | — | — |
| `popover?` | `'' \| 'auto' \| 'manual' \| 'hint'` | — | — |
| `popoverTargetAction?` | `'toggle' \| 'show' \| 'hide'` | — | — |
| `popoverTarget?` | `string` | — | — |
| `inert?` | `boolean` | — | — |
| `inputMode?` | `'none' \| 'search' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal'` | — | Hints at the type of data that might be entered by the user while editing the element or its contents |
| `is?` | `string` | — | Specify that a standard HTML element should behave like a defined custom built-in element |
| `exportparts?` | `string` | — | — |
| `part?` | `string` | — | — |
| `aria-activedescendant?` | `string` | — | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| `aria-atomic?` | `Booleanish` | — | Indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute. |
| `aria-autocomplete?` | `'none' \| 'list' \| 'inline' \| 'both'` | — | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| `aria-braillelabel?` | `string` | — | Defines a string value that labels the current element, which is intended to be converted into Braille. |
| `aria-brailleroledescription?` | `string` | — | Defines a human-readable, author-localized abbreviated description for the role of an element, which is intended to be converted into Braille. |
| `aria-busy?` | `Booleanish` | — | — |
| `aria-checked?` | `boolean \| "true" \| "false" \| "mixed"` | — | Indicates the current "checked" state of checkboxes, radio buttons, and other widgets. |
| `aria-colcount?` | `number` | — | Defines the total number of columns in a table, grid, or treegrid. |
| `aria-colindex?` | `number` | — | Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. |
| `aria-colindextext?` | `string` | — | Defines a human readable text alternative of aria-colindex. |
| `aria-colspan?` | `number` | — | Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. |
| `aria-controls?` | `string` | — | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` | — | Indicates the element that represents the current item within a container or set of related elements. |
| `aria-describedby?` | `string` | — | Identifies the element (or elements) that describes the object. |
| `aria-description?` | `string` | — | Defines a string value that describes or annotates the current element. |
| `aria-details?` | `string` | — | Identifies the element that provides a detailed, extended description for the object. |
| `aria-disabled?` | `Booleanish` | — | Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. |
| `aria-dropeffect?` | `'none' \| 'link' \| 'copy' \| 'execute' \| 'move' \| 'popup'` | — | **deprecated.** Indicates what functions can be performed when a dragged object is released on the drop target. |
| `aria-errormessage?` | `string` | — | Identifies the element that provides an error message for the object. |
| `aria-expanded?` | `Booleanish` | — | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. |
| `aria-flowto?` | `string` | — | Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. |
| `aria-grabbed?` | `Booleanish` | — | **deprecated.** Indicates an element's "grabbed" state in a drag-and-drop operation. |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "dialog" \| "grid" \| "listbox" \| "menu" \| "tree"` | — | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-hidden?` | `Booleanish` | — | Indicates whether the element is exposed to an accessibility API. |
| `aria-invalid?` | `boolean \| "true" \| "false" \| "grammar" \| "spelling"` | — | Indicates the entered value does not conform to the format expected by the application. |
| `aria-keyshortcuts?` | `string` | — | Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. |
| `aria-label?` | `string` | — | Defines a string value that labels the current element. |
| `aria-labelledby?` | `string` | — | Identifies the element (or elements) that labels the current element. |
| `aria-level?` | `number` | — | Defines the hierarchical level of an element within a structure. |
| `aria-live?` | `'off' \| 'assertive' \| 'polite'` | — | Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. |
| `aria-modal?` | `Booleanish` | — | Indicates whether an element is modal when displayed. |
| `aria-multiline?` | `Booleanish` | — | Indicates whether a text box accepts multiple lines of input or only a single line. |
| `aria-multiselectable?` | `Booleanish` | — | Indicates that the user may select more than one item from the current selectable descendants. |
| `aria-orientation?` | `'horizontal' \| 'vertical'` | — | Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. |
| `aria-owns?` | `string` | — | Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship. |
| `aria-placeholder?` | `string` | — | Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format. |
| `aria-posinset?` | `number` | — | Defines an element's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | — | Indicates the current "pressed" state of toggle buttons. |
| `aria-readonly?` | `Booleanish` | — | Indicates that the element is not editable, but is otherwise operable. |
| `aria-relevant?` | `'text' \| 'additions' \| 'additions removals' \| 'additions text' \| 'all' \| 'removals' \| 'removals additions' \| 'removals text' \| 'text additions' \| 'text removals'` | — | Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. |
| `aria-required?` | `Booleanish` | — | Indicates that user input is required on the element before a form may be submitted. |
| `aria-roledescription?` | `string` | — | Defines a human-readable, author-localized description for the role of an element. |
| `aria-rowcount?` | `number` | — | Defines the total number of rows in a table, grid, or treegrid. |
| `aria-rowindex?` | `number` | — | Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. |
| `aria-rowindextext?` | `string` | — | Defines a human readable text alternative of aria-rowindex. |
| `aria-rowspan?` | `number` | — | Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. |
| `aria-selected?` | `Booleanish` | — | Indicates the current "selected" state of various widgets. |
| `aria-setsize?` | `number` | — | Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. |
| `aria-sort?` | `'none' \| 'ascending' \| 'descending' \| 'other'` | — | Indicates if items in a table or grid are sorted in ascending or descending order. |
| `aria-valuemax?` | `number` | — | Defines the maximum allowed value for a range widget. |
| `aria-valuemin?` | `number` | — | Defines the minimum allowed value for a range widget. |
| `aria-valuenow?` | `number` | — | Defines the current value for a range widget. |
| `aria-valuetext?` | `string` | — | Defines the human readable text alternative of aria-valuenow for a range widget. |
| `children?` | `ReactNode` | — | — |
| `dangerouslySetInnerHTML?` | `{ __html: string \| TrustedHTML; }` | — | — |
| `onCopy?` | `ClipboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onCopyCapture?` | `ClipboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onCut?` | `ClipboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onCutCapture?` | `ClipboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onPaste?` | `ClipboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onPasteCapture?` | `ClipboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onCompositionEnd?` | `CompositionEventHandler<HTMLFieldSetElement>` | — | — |
| `onCompositionEndCapture?` | `CompositionEventHandler<HTMLFieldSetElement>` | — | — |
| `onCompositionStart?` | `CompositionEventHandler<HTMLFieldSetElement>` | — | — |
| `onCompositionStartCapture?` | `CompositionEventHandler<HTMLFieldSetElement>` | — | — |
| `onCompositionUpdate?` | `CompositionEventHandler<HTMLFieldSetElement>` | — | — |
| `onCompositionUpdateCapture?` | `CompositionEventHandler<HTMLFieldSetElement>` | — | — |
| `onFocus?` | `FocusEventHandler<HTMLFieldSetElement>` | — | — |
| `onFocusCapture?` | `FocusEventHandler<HTMLFieldSetElement>` | — | — |
| `onBlur?` | `FocusEventHandler<HTMLFieldSetElement>` | — | — |
| `onBlurCapture?` | `FocusEventHandler<HTMLFieldSetElement>` | — | — |
| `onChangeCapture?` | `ChangeEventHandler<HTMLFieldSetElement, Element>` | — | — |
| `onBeforeInput?` | `InputEventHandler<HTMLFieldSetElement>` | — | — |
| `onBeforeInputCapture?` | `InputEventHandler<HTMLFieldSetElement>` | — | — |
| `onInput?` | `InputEventHandler<HTMLFieldSetElement>` | — | — |
| `onInputCapture?` | `InputEventHandler<HTMLFieldSetElement>` | — | — |
| `onReset?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onResetCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSubmit?` | `SubmitEventHandler<HTMLFieldSetElement>` | — | — |
| `onSubmitCapture?` | `SubmitEventHandler<HTMLFieldSetElement>` | — | — |
| `onInvalid?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onInvalidCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoad?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoadCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onError?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onErrorCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onKeyDown?` | `KeyboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onKeyDownCapture?` | `KeyboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onKeyPress?` | `KeyboardEventHandler<HTMLFieldSetElement>` | — | **deprecated.** |
| `onKeyPressCapture?` | `KeyboardEventHandler<HTMLFieldSetElement>` | — | **deprecated.** |
| `onKeyUp?` | `KeyboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onKeyUpCapture?` | `KeyboardEventHandler<HTMLFieldSetElement>` | — | — |
| `onAbort?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onAbortCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onCanPlay?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onCanPlayCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onCanPlayThrough?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onCanPlayThroughCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onDurationChange?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onDurationChangeCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onEmptied?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onEmptiedCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onEncrypted?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onEncryptedCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onEnded?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onEndedCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoadedData?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoadedDataCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoadedMetadata?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoadedMetadataCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoadStart?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onLoadStartCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onPause?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onPauseCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onPlay?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onPlayCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onPlaying?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onPlayingCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onProgress?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onProgressCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onRateChange?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onRateChangeCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSeeked?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSeekedCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSeeking?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSeekingCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onStalled?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onStalledCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSuspend?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSuspendCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onTimeUpdate?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onTimeUpdateCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onVolumeChange?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onVolumeChangeCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onWaiting?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onWaitingCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onAuxClick?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onAuxClickCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onClick?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onClickCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onContextMenu?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onContextMenuCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onDoubleClick?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onDoubleClickCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onDrag?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragEnd?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragEndCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragEnter?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragEnterCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragExit?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragExitCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragLeave?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragLeaveCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragOver?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragOverCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragStart?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDragStartCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDrop?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onDropCapture?` | `DragEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseDown?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseDownCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseEnter?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseLeave?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseMove?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseMoveCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseOut?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseOutCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseOver?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseOverCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseUp?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onMouseUpCapture?` | `MouseEventHandler<HTMLFieldSetElement>` | — | — |
| `onSelect?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onSelectCapture?` | `ReactEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchCancel?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchCancelCapture?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchEnd?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchEndCapture?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchMove?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchMoveCapture?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchStart?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onTouchStartCapture?` | `TouchEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerDown?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerDownCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerMove?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerMoveCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerUp?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerUpCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerCancel?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerCancelCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerEnter?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerLeave?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerOver?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerOverCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerOut?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onPointerOutCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onGotPointerCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onGotPointerCaptureCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onLostPointerCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onLostPointerCaptureCapture?` | `PointerEventHandler<HTMLFieldSetElement>` | — | — |
| `onScroll?` | `UIEventHandler<HTMLFieldSetElement>` | — | — |
| `onScrollCapture?` | `UIEventHandler<HTMLFieldSetElement>` | — | — |
| `onScrollEnd?` | `UIEventHandler<HTMLFieldSetElement>` | — | — |
| `onScrollEndCapture?` | `UIEventHandler<HTMLFieldSetElement>` | — | — |
| `onWheel?` | `WheelEventHandler<HTMLFieldSetElement>` | — | — |
| `onWheelCapture?` | `WheelEventHandler<HTMLFieldSetElement>` | — | — |
| `onAnimationStart?` | `AnimationEventHandler<HTMLFieldSetElement>` | — | — |
| `onAnimationStartCapture?` | `AnimationEventHandler<HTMLFieldSetElement>` | — | — |
| `onAnimationEnd?` | `AnimationEventHandler<HTMLFieldSetElement>` | — | — |
| `onAnimationEndCapture?` | `AnimationEventHandler<HTMLFieldSetElement>` | — | — |
| `onAnimationIteration?` | `AnimationEventHandler<HTMLFieldSetElement>` | — | — |
| `onAnimationIterationCapture?` | `AnimationEventHandler<HTMLFieldSetElement>` | — | — |
| `onToggle?` | `ToggleEventHandler<HTMLFieldSetElement>` | — | — |
| `onBeforeToggle?` | `ToggleEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionCancel?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionCancelCapture?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionEnd?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionEndCapture?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionRun?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionRunCapture?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionStart?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |
| `onTransitionStartCapture?` | `TransitionEventHandler<HTMLFieldSetElement>` | — | — |


---

# RowAction (/docs/components/row-action)



```ts
import { RowAction } from '@coldsurfers/surf-ui/primitives'
```

```tsx
import { RowAction } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <RowAction>예매 ↗</RowAction>
      <RowAction>알림</RowAction>
      <RowAction asChild>
        <a href="#row-action">보기</a>
      </RowAction>
    </>
  )
}
```

높이 32 · r8 · 키커색 14% 면에 키커색 글자입니다. 잉크 면에선 sky, 밝은 면에선 blue 가 됩니다.

화면의 **주 행동 하나**는 `Button variant="accent"` 로 두고, 반복되는 행동(`예매 ↗` · `알림` · `보기`)은
이걸 씁니다. 진한 파랑이 여러 개면 무엇을 눌러야 할지 흐려집니다.

링크면 `asChild` 로 자식 `<a>` · 라우터 `Link` 에 스타일을 입힙니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `asChild?` | `boolean` | — | 자기 엘리먼트 대신 자식(라우터 `Link` · `<a>`)에 스타일을 입힌다. |

그 밖의 `ButtonHTMLAttributes<HTMLButtonElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Sheet (/docs/components/sheet)



```ts
import { Sheet } from '@coldsurfers/surf-ui/primitives'
```

```tsx
import { MediaRow } from '@coldsurfers/surf-ui/cards'
import { Button, Sheet } from '@coldsurfers/surf-ui/primitives'
import { useRef, useState } from 'react'

const TIERS = [
  ['VIP석', '189,000원'],
  ['R석', '164,000원'],
  ['S석', '134,000원'],
  ['A석', '104,000원'],
  ['B석', '79,000원'],
  ['시야제한석', '59,000원'],
]

export default function Example() {
  const [open, setOpen] = useState(false)
  const triggerRef = useRef<HTMLButtonElement>(null)

  return (
    <>
      <Button ref={triggerRef} onClick={() => setOpen(true)}>
        시트 열기
      </Button>
      <Sheet
        open={open}
        onClose={() => setOpen(false)}
        label="인터스텔라 필름콘서트 고르기"
        triggerRef={triggerRef}
        head={
          <MediaRow
            cover="인"
            kicker="일 10.11 · 14:00"
            title="인터스텔라 필름콘서트"
            meta="경희대 평화의전당"
          />
        }
        footer={
          <Button variant="accent" onClick={() => setOpen(false)}>
            놀유니버스에서 예매 ↗
          </Button>
        }
      >
        <dl>
          {TIERS.map(([label, value]) => (
            <div key={label} style={{ display: 'flex', justifyContent: 'space-between' }}>
              <dt>{label}</dt>
              <dd>{value}</dd>
            </div>
          ))}
        </dl>
      </Sheet>
    </>
  )
}
```

판매처 · 날짜 · 고르기처럼 지면에 펴기 긴 것을 담습니다(Figma `1028:381`). 화면 폭이 1024 아래면 아래에 붙고(위만 r28 · 손잡이 · safe-area), 위면 가운데 모달(최대 560)이 됩니다.

세 칸입니다 — 머리(손잡이 + `head`) · 내용(`children`) · 아래(`footer`). 머리와 아래는 고정이고 내용만 구릅니다. `head` 에는 「무엇을 고른 건지」 한 줄(보통 `MediaRow`), `footer` 에는 늘 보여야 하는 주 행동을 넣습니다. 모바일은 화면 위 56 을 어둡게 남겨 눌러서 닫을 자리를 둡니다.

모바일에선 머리를 잡고 끌어내려 닫습니다 — 80 넘게 내리거나 빠르게 튕기면 닫히고, 아니면 제자리로 돌아갑니다. 머리 안 링크 위에서도 끌립니다 — 6 넘게 내려와야 끌기로 보고, 그 전에 떼면 탭이라 링크로 갑니다. 열 때 올라오고(데스크탑은 떠오르고) 닫을 때 내려갑니다. `open` 을 false 로 바꿔도 퇴장이 끝날 때까지 마지막 내용을 그린 채로 두니, 소비처가 내용을 같이 비워도 됩니다. 움직임 줄이기 설정에선 애니메이션 없이 바로 열고 닫습니다.

Escape · 스크롤 잠금 · focus trap · portal · 면 모드는 [`Modal`](/docs/components/modal) 과 같습니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `head?` | `ReactNode` | — | 머리 — 「무엇을 고른 건지」. 보통 `MediaRow`. 고정이고, 모바일에선 잡고 끌어내리는 자리다. |
| `footer?` | `ReactNode` | — | 아래 — 늘 보이는 주 행동(반응 줄 · 예매 버튼). 고정. |
| `className?` | `string` | — | 패널 추가 클래스. |

그 밖의 `Omit<ModalProps, 'placement' | 'panelClassName' | 'overlayClassName'>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Skeleton (/docs/components/skeleton)



```tsx
import { Skeleton } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: 16, alignItems: 'flex-start' }}>
      <Skeleton width={96} aspectRatio="3 / 4" radius="lg" />
      <div style={{ display: 'grid', gap: 8, flex: 1, maxWidth: 260 }}>
        <Skeleton width="60%" height="1rem" />
        <Skeleton width="90%" height="0.75rem" />
        <Skeleton width="40%" height="0.75rem" />
      </div>
    </div>
  )
}
```

## 치수는 단일값 props 로만 받는다 [#치수는-단일값-props-로만-받는다]

`@media` 분기가 필요하면 `className` 으로 밉니다. 인라인 `style` 은 미디어쿼리를 못 담고,
그걸 담으려면 CSS 변수 배선이나 sprinkles 축 확장이 따라오는데 둘 다 이 컴포넌트 밖의
결정입니다.

## `aria-hidden` 은 기본으로 붙는다 [#aria-hidden-은-기본으로-붙는다]

자리표시자는 스크린리더가 읽을 내용이 아니고, 실측상 소비처가 가장 자주 빠뜨린 것이 이 한
줄입니다. 로딩 상태를 알려야 하면 그건 이 컴포넌트가 아니라 `role="status"` 를 가진 바깥
컨테이너의 몫입니다.

## 이미 치수를 가진 스타일과 합성할 때 [#이미-치수를-가진-스타일과-합성할-때]

```tsx
<Skeleton asChild>
  <div className={styles.poster} />
</Skeleton>
```

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `width?` | `string \| number` | — | CSS `width`. `'80%'` · `'5rem'` · `48` 처럼 단일값만. |
| `height?` | `string \| number` | — | CSS `height`. |
| `aspectRatio?` | `string` | — | CSS `aspect-ratio` — 포스터(`'3 / 4'`)·커버(`'4 / 3'`) 자리. |
| `radius?` | `'sm' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| 'none' \| 'md' \| 'full'` | — | `vars.radius` 키. 기본 `none` — 각진 바가 텍스트 줄의 기본 꼴이다. |
| `tone?` | `'neutral' \| 'onCover'` | — | 기본 `neutral`. 어두운 커버 위에 얹는 자리만 `onCover`. |
| `asChild?` | `boolean` | — | 자식 엘리먼트에 스타일만 입힌다. |

그 밖의 `ComponentPropsWithRef<'div'>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Spinner (/docs/components/spinner)



```tsx
import { Spinner } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <Spinner />
      <Spinner size={20} />
      <Spinner label="공연을 더 불러오는 중" />
    </>
  )
}
```

light 트랙 링 + `accent` 270° 아크가 돕니다. 무한스크롤 푸터가 홈입니다.

`label` 이 없으면 스피너만 그리고, 스크린리더에는 "불러오는 중" 을 줍니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `size?` | `number` | — | 지름(px). 기본은 `SPINNER_SPEC.size` — Figma 로더 값. |
| `label?` | `string` | — | 있으면 스피너 아래 muted 라벨을 렌더. 없으면(기본) 스피너만(Figma `라벨 표시` off). |

그 밖의 `HTMLAttributes<HTMLDivElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# StatPill (/docs/components/stat-pill)



```ts
import { StatPill } from '@coldsurfers/surf-ui/primitives'
```

```tsx
import { StatPill } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <StatPill icon="👁" value="1,204" />
      <StatPill icon="🔥" value="31" tone="hot" />
      <StatPill value="목 18:00 배달" />
    </>
  )
}
```

조회 `👁 1,204` · 반응 `🔥 31` 같은 숫자 하나를 붙입니다(Figma `1028:210`). 숫자는 Geist 고정폭이라 바뀌어도 칩 폭이 덜 흔들립니다.

무엇을 세는지는 모릅니다 — 포맷한 문자열을 `value` 로 넘깁니다. `tone="hot"` 은 주황 틴트입니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `icon?` | `ReactNode` | — | — |
| `value` | `ReactNode` | — | — |
| `tone?` | `'neutral' \| 'hot'` | — | — |

그 밖의 `HTMLAttributes<HTMLSpanElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Toast (/docs/components/toast)



```tsx
import { Button, ToastProvider, useToast } from '@coldsurfers/surf-ui/primitives'

function Trigger() {
  const toast = useToast()

  return (
    <>
      <Button onClick={() => toast.show('저장했습니다')}>기본</Button>
      <Button variant="outline" onClick={() => toast.show('저장했습니다', 'success')}>
        success
      </Button>
      <Button variant="outline" onClick={() => toast.show('저장하지 못했습니다', 'error')}>
        error
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.show('대학로를 내 동네로 정했습니다', 'success', {
            description: '설정에서 바꾸거나 해제할 수 있습니다.',
            action: { label: '홈으로', onPress: () => {} },
          })
        }
      >
        두 줄 + 액션
      </Button>
    </>
  )
}

export default function Example() {
  return (
    <ToastProvider>
      <Trigger />
    </ToastProvider>
  )
}
```

`ToastProvider` 를 앱 루트에 한 번 세우고, 어디서든 `useToast().show(...)` 로 부릅니다.

## 색이 한 쌍인 이유 [#색이-한-쌍인-이유]

`bg-text` / `text-bg` 한 쌍입니다. 스킴이 뒤집히면 pill 도 같이 뒤집혀서 **어느 표면에 얹혀도
바닥과 반대색**이 됩니다. warm-paper 표면에선 ink pill + paper 글씨, 다크 표면에선 그 반대입니다.
표면마다 색을 따로 주지 않는 이유입니다.

## provider 가 없으면 no-op [#provider-가-없으면-no-op]

`show` 는 조용히 아무것도 하지 않습니다 — 컴포넌트를 격리 렌더해도 throw 하지 않습니다.

## API [#api]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `show` | `(message: string, tone?: ToastTone, options?: ToastOptions) => void` | — | 메시지를 띄우고 1.6s(액션이 있으면 4s) 뒤 자동으로 사라진다. 연속 호출 시 타이머 리셋. |

```tsx
const toast = useToast()
toast.show('저장했습니다', 'success')
```

연속 호출하면 타이머가 리셋됩니다.

## 둘째 줄과 액션 [#둘째-줄과-액션]

```tsx
toast.show('대학로를 내 동네로 정했습니다', 'success', {
  description: '설정에서 바꾸거나 해제할 수 있습니다.',
  action: { label: '홈으로', onPress: () => navigate({ to: '/' }) },
})
```

`description` 이 있으면 알약이 두 줄 상자로 바뀝니다. `action` 은 토스트 안에서 끝나는 한 걸음이고,
누르면 토스트가 닫힙니다. 액션이 있으면 손을 옮길 시간을 주려고 4초 섭니다. 토스트 바탕은 여전히
누를 수 없고(아래 화면을 가로막지 않는다) 액션 버튼만 누를 수 있습니다.


---

# 색 (/docs/foundations/colors)



## 정본은 Figma 다 [#정본은-figma-다]

값과 이름은 Figma `3sIMxSgWyp7RYonfhAAZIc` 의 변수 컬렉션 `surf-ui / color` 가 정본입니다.
이름은 그대로 옮깁니다 — `bg/base` → `vars.color.bgBase` → `--surf-bg-base`.

<Callout tone="warning">
  색은 **닫힌 축**입니다. spacing · radius · fontSize 같은 스케일은 소비자가 덮을 수 있지만,
  color · layout · shape · cover 는 COLDSURF 고정값입니다.
</Callout>

## 면은 두 벌이다 — ink · light [#면은-두-벌이다--ink--light]

기본은 **light** 입니다. 어느 요소든 `data-surface="ink"` 를 달면 그 안은 **ink** 값이 됩니다.
한 페이지 안에서 섞습니다 — 홈은 히어로가 ink, 아래 묶음이 light 입니다.
ink 안에서 다시 밝은 면을 열 땐 `data-surface="light"` 입니다. OS 다크모드와는 무관합니다.

```tsx
<section data-surface="ink">…히어로…</section>
<section>…아래 묶음 (light)…</section>
```

### light [#light]

| 토큰 | 값 |
| --- | --- |
| `--surf-bg-base` | `#ffffff` |
| `--surf-bg-alt` | `#f1f1f1` |
| `--surf-surface-raised` | `#ffffff` |
| `--surf-panel-fill` | `#eef3ff` |
| `--surf-panel-line` | `rgba(255, 255, 255, 0)` |
| `--surf-row-fill` | `#ffffff` |
| `--surf-line-divider` | `#e6e6e6` |
| `--surf-state-hover` | `rgba(17, 17, 17, 0.06)` |
| `--surf-state-pressed` | `rgba(10, 15, 26, 0.08)` |
| `--surf-text-primary` | `#111111` |
| `--surf-text-secondary` | `#6b6b6b` |
| `--surf-text-tertiary` | `#9ca3af` |
| `--surf-text-on-media` | `#ffffff` |
| `--surf-kicker` | `#2563ff` |
| `--surf-action-tint-fill` | `rgba(37, 99, 255, 0.14)` |
| `--surf-action-tint-text` | `#2563ff` |
| `--surf-action-primary` | `#2457ff` |
| `--surf-action-primary-hover` | `#1c47e0` |
| `--surf-action-on-primary` | `#ffffff` |
| `--surf-action-primary-top` | `#2457ff` |
| `--surf-action-primary-bottom` | `#2457ff` |
| `--surf-action-primary-line` | `transparent` |
| `--surf-action-primary-shadow` | `transparent` |
| `--surf-selected-fill` | `#111111` |
| `--surf-selected-text` | `#ffffff` |
| `--surf-glow` | `rgba(37, 99, 255, 0.28)` |
| `--surf-overlay` | `#111111` |
| `--surf-status-success` | `#1f7a3a` |
| `--surf-status-success-bg` | `rgba(31, 122, 58, 0.14)` |
| `--surf-status-warning` | `#9a5a12` |
| `--surf-status-warning-bg` | `rgba(154, 90, 18, 0.14)` |
| `--surf-status-danger` | `#b8221c` |
| `--surf-status-danger-bg` | `rgba(184, 34, 28, 0.14)` |

### ink [#ink]

| 토큰 | 값 |
| --- | --- |
| `--surf-bg-base` | `#101010` |
| `--surf-bg-alt` | `#101010` |
| `--surf-surface-raised` | `#181818` |
| `--surf-panel-fill` | `#181818` |
| `--surf-panel-line` | `rgba(255, 255, 255, 0.08)` |
| `--surf-row-fill` | `rgba(255, 255, 255, 0.05)` |
| `--surf-line-divider` | `rgba(255, 255, 255, 0.08)` |
| `--surf-state-hover` | `rgba(255, 255, 255, 0.06)` |
| `--surf-state-pressed` | `rgba(255, 255, 255, 0.1)` |
| `--surf-text-primary` | `#f3f5f7` |
| `--surf-text-secondary` | `#9a9a9a` |
| `--surf-text-tertiary` | `rgba(154, 154, 154, 0.6)` |
| `--surf-text-on-media` | `#ffffff` |
| `--surf-kicker` | `#9ec2ff` |
| `--surf-action-tint-fill` | `rgba(158, 194, 255, 0.14)` |
| `--surf-action-tint-text` | `#9ec2ff` |
| `--surf-action-primary` | `#2563ff` |
| `--surf-action-primary-hover` | `#1d4fd8` |
| `--surf-action-on-primary` | `#ffffff` |
| `--surf-action-primary-top` | `#3a6dff` |
| `--surf-action-primary-bottom` | `#1a3a9e` |
| `--surf-action-primary-line` | `rgba(158, 194, 255, 0.25)` |
| `--surf-action-primary-shadow` | `rgba(37, 99, 255, 0.25)` |
| `--surf-selected-fill` | `#f3f5f7` |
| `--surf-selected-text` | `#101010` |
| `--surf-glow` | `rgba(37, 99, 255, 0.28)` |
| `--surf-overlay` | `#101010` |
| `--surf-status-success` | `#5fd08a` |
| `--surf-status-success-bg` | `rgba(95, 208, 138, 0.14)` |
| `--surf-status-warning` | `#f0b45a` |
| `--surf-status-warning-bg` | `rgba(240, 180, 90, 0.14)` |
| `--surf-status-danger` | `#ff6b63` |
| `--surf-status-danger-bg` | `rgba(255, 107, 99, 0.14)` |

### 읽는 글자의 하한 [#읽는-글자의-하한]

글자색은 `textPrimary` · `textSecondary` · `textTertiary` 셋입니다. &#x2A;*읽는 글자의 하한은
`textSecondary`** 이고, `textTertiary` 는 플레이스홀더 · 비활성 — 읽히지 않아도 되는 것 — 에만 씁니다.

## cover — 지형 색면 [#cover--지형-색면]

카드 커버의 바닥색입니다. 테마가 아니라 **데이터(id)로 고르는 색**이라 면을 타지 않습니다.

| 토큰 | 값 |
| --- | --- |
| `--cover-forest` | `#1f3a44` |
| `--cover-wine` | `#4a2f42` |
| `--cover-navy` | `#2c3e4e` |
| `--cover-moss` | `#26305c` |
| `--cover-steel` | `#1e2a44` |
| `--cover-plum` | `#382c4c` |

## shape — 부품 치수 [#shape--부품-치수]

Figma `surf-ui / shape`. 부품의 모서리 · 고정 크기 · 글자 크기입니다.

| 토큰 | 값 |
| --- | --- |
| `--surf-radius-panel` | `20px` |
| `--surf-radius-sheet` | `28px` |
| `--surf-radius-sheet-map` | `24px` |
| `--surf-radius-poster` | `16px` |
| `--surf-radius-row` | `12px` |
| `--surf-radius-row-action` | `8px` |
| `--surf-radius-pill` | `9999px` |
| `--surf-size-row-action-height` | `32px` |
| `--surf-size-date-block-width` | `52px` |
| `--surf-size-date-block-height` | `62px` |
| `--surf-size-thumb` | `52px` |
| `--surf-type-kicker` | `11px` |
| `--surf-type-card-head` | `16px` |
| `--surf-type-row-title` | `15px` |
| `--surf-type-body` | `14px` |
| `--surf-type-meta` | `12px` |

## layout — 폭 두 벌 [#layout--폭-두-벌]

Figma `surf-ui / layout`. 기본은 mobile, `1024px` 이상은 desktop 값입니다.

| 토큰 | 값 |
| --- | --- |
| `--surf-layout-gutter` | `20px` |
| `--surf-layout-content-width` | `350px` |
| `--surf-layout-section-y` | `56px` |
| `--surf-layout-repeat-gap` | `12px` |
| `--surf-layout-hero-poster-height` | `300px` |
| `--surf-layout-hero-decision-width` | `350px` |
| `--surf-layout-hero-column-gap` | `20px` |
| `--surf-layout-type-hero-title` | `36px` |
| `--surf-layout-type-tile-title` | `18px` |

| 토큰 | 값 |
| --- | --- |
| `--surf-layout-gutter` | `64px` |
| `--surf-layout-content-width` | `1312px` |
| `--surf-layout-section-y` | `96px` |
| `--surf-layout-repeat-gap` | `24px` |
| `--surf-layout-hero-poster-height` | `660px` |
| `--surf-layout-hero-decision-width` | `500px` |
| `--surf-layout-hero-column-gap` | `56px` |
| `--surf-layout-type-hero-title` | `56px` |
| `--surf-layout-type-tile-title` | `22px` |

## radius [#radius]

| 토큰 | 값 |
| --- | --- |
| `--radius-none` | `0` |
| `--radius-sm` | `2px` |
| `--radius-md` | `4px` |
| `--radius-lg` | `8px` |
| `--radius-xl` | `12px` |
| `--radius-2xl` | `16px` |
| `--radius-3xl` | `24px` |
| `--radius-full` | `9999px` |


---

# 계약과 레이어 (/docs/foundations/layers)



배럴(`@coldsurfers/surf-ui`)이 갖는 건 **계약과 순서** 둘입니다. 값 자체는
`./tokens` 서브패스에 있습니다.

## `vars` — 이름을 타입으로 승격한다 [#vars--이름을-타입으로-승격한다]

```ts
import { vars } from '@coldsurfers/surf-ui'

style({ color: vars.color.accent, padding: vars.space['4'] })
```

토큰 밖의 색을 쓰면 **타입 에러**입니다. 규율의 강제 주체가 문서나 감사 스크립트가 아니라
`tsc` 로 옮겨갑니다.

이름을 손으로 적지 않습니다 — 변수 이름은 `tokenVarName` 이 계산하고, 그 규칙의 정본은
`cssVarPrefix` 표 하나뿐입니다.

## 캐스케이드 순서 [#캐스케이드-순서]

```
properties · theme · base · ds-reset · ds-tokens · ds-components · components · ds-utilities · utilities
```

`properties` · `theme` · `base` · `components` · `utilities` 는 **Tailwind 가 발행하는
레이어 이름**입니다. Tailwind 와 함께 쓰는 소비자를 위해 순서에 미리 끼워 둡니다.

| 레이어             | 무엇                                   |
| --------------- | ------------------------------------ |
| `ds-reset`      | 엘리먼트 기본값. 무엇에든 져야 하므로 가장 약하다         |
| `ds-tokens`     | 토큰 · 테마 수준 전역 선언                     |
| `ds-components` | 컴포넌트 스타일 — `.css.ts` 의 `style()` 대부분 |
| `ds-utilities`  | 원자 유틸. 컴포넌트를 이겨야 override 로 쓸 수 있다   |

<Callout tone="warning">
  `base`(Tailwind preflight)가 `ds-components` 보다 **앞**이어야 합니다. 뒤로 밀리면 컴포넌트의
  padding · border 가 전부 지워집니다. Tailwind 를 안 쓰면 그 넷은 빈 레이어라 무해합니다.
</Callout>

## 순서 선언은 CSS 가 아니라 vanilla-extract 가 발행한다 [#순서-선언은-css-가-아니라-vanilla-extract-가-발행한다]

`@layer …;` 한 줄을 `styles.css` 에 직접 넣었더니 &#x2A;*lightningcss 가 minify 하면서 Tailwind
이름 넷을 지워버렸습니다.** 그러면 `base` 가 `ds-components` 뒤로 밀려 컴포넌트가 깨집니다.
minifier 를 신뢰할 수 없으니 선언을 VE 로 옮겼고, 여러 청크가 각자 중복 선언합니다
(`@layer a,b,c;` 는 이름이 있으면 no-op 이라 안전합니다).

## 컴포넌트 스타일을 쓸 때 [#컴포넌트-스타일을-쓸-때]

`.css.ts` 를 직접 쓰는 소비자는 `inComponentsLayer` 로 감쌉니다.

```ts
import { inComponentsLayer } from '@coldsurfers/surf-ui'
import { style } from '@vanilla-extract/css'

export const card = style(inComponentsLayer({ padding: '1rem' }))
```

## 반응형 [#반응형]

```ts
import { media } from '@coldsurfers/surf-ui'

style({ '@media': { [media.tablet]: { padding: '2rem' } } })
```


---

# 레이아웃 (/docs/foundations/layout)



```ts
import { Container, Page, PageBanner } from '@coldsurfers/surf-ui/layout'
```

셋은 `./layout` 진입점에 있습니다 — 배럴(`.`)에는 없습니다.

## Container — 가로축 [#container--가로축]

```tsx
import { Container } from '@coldsurfers/surf-ui/layout'

export default function Example() {
  return (
    <div style={{ width: '100%', background: 'var(--surface-2)' }}>
      <Container
        as="header"
        style={{ paddingBlock: 12, borderBottom: '1px dashed var(--surf-line-divider)' }}
      >
        COLDSURF
      </Container>
      <Container as="main" style={{ paddingBlock: 12 }}>
        헤더 로고와 본문이 같은 세로선에 선다 — 지면 배경은 그 선 밖까지 간다
      </Container>
    </div>
  )
}
```

`margin-inline: auto` · 최대폭 · gutter 셋이 전부입니다. 지면 배경은 이 선 밖까지 가고,
콘텐츠만 안쪽으로 들어옵니다.

gutter 는 [여백 스케일](/docs/foundations/spacing)의 `space-6`, tablet 이상에서 `space-16`
입니다. 최대폭 `1440px` 만 스케일 밖 리터럴입니다 — 토큰에 `maxWidth` 축이 없고, *한 표면의
최대 폭*은 레이아웃 결정이라 스케일로 일반화할 게 없습니다. 다른 폭이 필요하면 `className`
으로 덮습니다(유틸은 `ds-utilities` 라 컴포넌트를 이깁니다).

이 컴포넌트가 생긴 이유는 재사용이 아니라 **드리프트**입니다. 소비 앱은 같은 값을 16곳에서
각자 상수로 다시 선언하고 있었습니다 — 주석까지 복붙된 채로. 정렬 축은 하나여야 하는데
사본이 16개였습니다.

`as` 로 여는 태그 목록이 좁은 것도 같은 이유입니다. gutter 는 **정렬축이지 의미가 아니라서**
어떤 태그에도 붙지만, `ElementType` 으로 활짝 열면 `<button>` 에 gutter 를 붙이는 것까지
타입이 통과합니다. 넓히는 건 minor 지만 좁히는 건 major 입니다.

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `as?` | `'div' \| 'section' \| 'main' \| 'aside' \| 'header' \| 'footer'` | — | 렌더할 태그. gutter 는 **정렬축이지 의미가 아니라서** 어떤 태그에도 붙는다 — 한 표면 안에서 같은 세로선에 서는 것들이 `<section>`(본문 한 덩이)·`<div>`(묶음만)· `<main>`(문서 본체)로 갈린다. 기본값을 `<div>` 로 두고 시맨틱이 필요한 쪽만 올린다. 목록을 좁게 연 이유: 넓히는 건 minor 지만 좁히는 건 major 다. `ElementType` 으로 활짝 열면 `<button>` 에 gutter 를 붙이는 것도 타입이 통과한다 — 그건 정렬축이 아니다. |

그 밖의 `HTMLAttributes<HTMLElement>` 속성은 루트 엘리먼트로 그대로 통과한다.

## Page — 세로축 [#page--세로축]

```tsx
import { Page } from '@coldsurfers/surf-ui/layout'

export default function Example() {
  return (
    // 실제 표면에선 min-height 가 100vh 다 — 미리보기라 style 로 낮춘다.
    <Page
      mode="light"
      name="docs"
      style={{ minHeight: 220, width: '100%', border: '1px dashed var(--surf-line-divider)' }}
    >
      <div style={{ padding: 12, borderBottom: '1px dashed var(--surf-line-divider)' }}>
        SiteHeader
      </div>
      <Page.Content style={{ padding: 12 }}>본문 — 남은 높이를 전부 먹는다</Page.Content>
      <div style={{ padding: 12, borderTop: '1px dashed var(--surf-line-divider)' }}>
        SiteFooter
      </div>
    </Page>
  )
}
```

`min-height: 100vh` 세로 스택과 `Page.Content` 의 `flex: 1` 은 **짝으로만** 성립합니다.
한쪽만 있으면 아무 효과가 없습니다. 콘텐츠가 짧은 표면(404 · 해지 완료)에서 푸터가 화면
중간에 떠 있지 않게 하는 것, 그 하나를 위해 둘이 갈라지는 자리를 없앤 컴포넌트입니다.

헤더 · 푸터는 슬롯 래퍼 없이 **그냥 자식으로** 놓습니다. 그 내용물(라우터 · 세션 · i18n ·
계측)은 앱의 것이고, DS 가 그 자리에 `<div>` 한 겹을 더 두면 아무것도 안 하는 이름이 공개
계약에 오릅니다.

### `mode` 는 필수다 — 화면마다 ink 인지 light 인지 [#mode-는-필수다--화면마다-ink-인지-light-인지]

`mode` 는 `data-surface` 로 나가 그 안의 색을 면 값으로 바꿉니다. context 로도 내려가서
`Modal` · `Popover` 처럼 `document.body` 로 나가는 오버레이가 같은 면으로 뜨고, 부품은
`useSurfaceMode()` 로 `tone` prop 없이 면을 압니다. ink 페이지면 `<body>` 도 ink 가 됩니다 —
짧은 페이지 아래 · 오버스크롤 바운스 색이 새지 않습니다.

`mode="auto"` 는 OS 를 따릅니다 — OS 가 다크면 ink, 아니면 light. 토글은 없습니다. 서버는 OS 를
모르므로 `useSurfaceMode()` 가 `auto` 를 돌려주는 자리에서는 색을 JS 로 가르지 말고 CSS
(`@media (prefers-color-scheme: dark)`)로 가릅니다.

배경 · 글자색을 칠하는 건 여전히 앱의 `className` 입니다 — 표면 정책은 값이 아니라 제품 결정입니다.

### `name` 은 마커일 뿐이다 [#name-은-마커일-뿐이다]

`data-page` 로 나가고 DS 는 해석하지 않습니다. 화면별로 바닥색을 덮을 때만 줍니다.

```css
body:has([data-page='tonight']) {
  background: var(--paper-warm);
}
```

모드와 나눈 이유: 한 속성이 둘을 겸하면 이름을 다는 순간 면 스코프가 꺼집니다.

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `mode` | `'ink' \| 'light' \| 'auto'` | — | 이 페이지의 면 — `ink` · `light` · `auto`. **필수다.** 화면마다 한 번 명시한다. `auto` 는 OS 가 다크면 ink, 아니면 light 다(`prefers-color-scheme`). 토글은 없다. `data-surface` 로 나가 그 안의 색 토큰을 해당 면 값으로 바꾸고(`css/theme.css.ts`), context 로 내려가 포털 오버레이(`Modal` · `Popover`)와 `useSurfaceMode()` 를 읽는 부품이 같은 면을 받는다. ink 면이면 `<body>` 도 ink 스코프를 받는다(`Page.css.ts`) — 짧은 페이지 아래·오버스크롤 바운스 색. |
| `name?` | `string` | — | 화면 이름 — `data-page` 로 나가는 앱의 표식이다. DS 는 해석하지 않는다. 쓰임: 소비 앱이 `body:has([data-page="…"])` 로 화면별 바닥색을 덮는다. 그 규칙이 있는 화면에만 준다. 모드와 나눈 이유: 한 속성이 둘을 겸하면 이름을 다는 순간 면 스코프가 꺼진다. |

그 밖의 `HTMLAttributes<HTMLDivElement>` 속성은 루트 엘리먼트로 그대로 통과한다.

## 왜 둘을 안 합쳤나 [#왜-둘을-안-합쳤나]

축이 직교하기 때문입니다. `Container` 는 가로(정렬선 · 최대폭), `Page` 는 세로(뷰포트 높이 ·
면 모드)입니다. 합치면 지면 배경까지 최대폭에서 잘려 넓은 화면 양옆에 다른 색 띠가
생기고, 표면당 하나뿐인 `Page` 로는 페이지 안 여러 덩이를 같은 선에 세울 수 없습니다.

그래서 `Container` 는 `Page` 밖에서도 씁니다 — 헤더 · 푸터도 같은 축으로 서야 로고와 콘텐츠가
정렬됩니다.

## PageBanner [#pagebanner]

```tsx
import { PageBanner } from '@coldsurfers/surf-ui/layout'
import { Button } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div style={{ width: '100%' }}>
      <PageBanner>
        {/* 밴드 안의 배치는 소비처가 정한다 — DS 가 드는 건 바닥 · 셸 · 타이포뿐이다. */}
        <div
          style={{
            display: 'flex',
            flexWrap: 'wrap',
            gap: 16,
            alignItems: 'center',
            justifyContent: 'space-between',
          }}
        >
          <div>
            <PageBanner.Title>새 공연 뜨면 알려드릴게요</PageBanner.Title>
            <PageBanner.Body>스팸 없이.</PageBanner.Body>
          </div>
          <Button>알림 받기</Button>
        </div>
      </PageBanner>
    </div>
  )
}
```

지면을 다 읽은 자리에서 색이 뒤집혀 "본문이 끝났고 여기부터는 요구" 라는 걸 글자 없이 알리는
풀블리드 밴드입니다. 안에서 `Container` 를 쓰므로 밴드 콘텐츠도 본문과 같은 세로선에 섭니다.

**레이아웃은 소비처의 것입니다.** DS 가 드는 건 바닥 · 셸 · 타이포 셋뿐이고 그 안의 배치는
`children` 이 정합니다. `align` 축을 열지 않은 이유는 실측입니다 — 소비처 둘의 정렬이 서로
다르지만 각 정렬의 실사용이 1곳씩이라 추출할 중복이 없었습니다. `Modal` 이 `placement` 를 연
건 5 소비처 중 4곳이 같은 두 줄을 복붙하고 있었기 때문이고, 여기는 그 조건이 성립하지 않습니다.

`PageBanner.Title` 이 `<h2>` 인 것도 자리에서 나옵니다 — 밴드는 지면 본문 다음에 서는 한
덩이라 문서 제목(`<h1>`) 아래 형제가 맞습니다.

## 여기 없는 것 [#여기-없는-것]

|                               | 왜                                                                |
| ----------------------------- | ---------------------------------------------------------------- |
| `Page.Header` · `Page.Footer` | `<div>` 한 겹이라 두지 않습니다. chrome 은 `Page` 의 자식으로 놓습니다               |
| `Section`                     | 소비처 34곳 중 그대로 맞는 건 3곳이었습니다. 나머지는 DS 가 준 걸 도로 지우는 className 을 답니다 |
| `Bar.Left` · `Bar.Right`      | 소비처가 아직 하나뿐이라 보류입니다. 두 번째가 생기면 엽니다                               |
| 헤더 · 푸터 **내용물**               | 라우터 · 세션 · i18n · 계측을 뭅니다. 앱의 것입니다                               |


---

# 누름 (/docs/foundations/press)



```tsx
import { Button } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <>
      <Button size="sm">sm</Button>
      <Button size="md">md</Button>
      <Button size="cta" variant="accent">
        cta
      </Button>
      <Button size="lg" variant="accent">
        lg
      </Button>
      <Button variant="ghost" trailingIcon="→">
        읽기
      </Button>
    </>
  )
}
```

위 버튼을 눌러 보세요. 투명도(`BUTTON_SPEC.pressedOpacity`)에 더해 &#x2A;*살짝 줄어듭니다.**
값은 `PRESS_SPEC` 하나라 웹 `:active` 와 RN 스프링이 같은 비율로 줄어듭니다.

| 크기      | 비율   | 쓰는 곳                                                                              |
| ------- | ---- | --------------------------------------------------------------------------------- |
| `large` | 0.97 | `PinCard` · `cta`·`lg` 버튼 — 넓은 면은 조금만 줄여야 흔들려 보이지 않는다                             |
| `small` | 0.94 | `sm`·`md` 버튼 · `IconButton` · `Chip` · `RowAction` · `ReactionBar` · `TextButton` |

동작 줄이기 설정(`prefers-reduced-motion` · iOS/Android 접근성)이면 두 레인 다 줄이지 않습니다.

## 직접 만든 버튼에 붙이기 [#직접-만든-버튼에-붙이기]

웹은 `@coldsurfers/surf-ui/style-utils` 의 `pressable` 을 스타일에 펼칩니다. 돌아오는 애니메이션은
`transition` 에 `scale` 을 더해야 붙습니다.

```ts
import { pressable } from '@coldsurfers/surf-ui/style-utils'

export const myButton = style({ transition: 'scale 150ms', ...pressable('small') })
```

`pressable` 은 `@media` 하나를 돌려줍니다. 받는 규칙에 이미 `@media` 가 있으면 덮어쓰므로 `style([a, b])` 로 합칩니다.


---

# 여백 (/docs/foundations/spacing)



키는 `4px × N` 입니다 — Tailwind 수치 스케일과 같은 좌표계입니다.

| 토큰 | 값 |
| --- | --- |
| `--spacing-0` | `0` |
| `--spacing-1` | `0.25rem` |
| `--spacing-2` | `0.5rem` |
| `--spacing-3` | `0.75rem` |
| `--spacing-4` | `1rem` |
| `--spacing-5` | `1.25rem` |
| `--spacing-6` | `1.5rem` |
| `--spacing-7` | `1.75rem` |
| `--spacing-8` | `2rem` |
| `--spacing-10` | `2.5rem` |
| `--spacing-12` | `3rem` |
| `--spacing-14` | `3.5rem` |
| `--spacing-16` | `4rem` |
| `--spacing-20` | `5rem` |
| `--spacing-24` | `6rem` |
| `--spacing-1-5` | `0.375rem` |
| `--spacing-2-5` | `0.625rem` |
| `--spacing-3-5` | `0.875rem` |

## 반 눈금이 있는 이유 [#반-눈금이-있는-이유]

`1.5` · `2.5` · `3.5` · `7` · `14` · `20` · `24` 는 **빈 눈금을 메운 것**입니다. 실측에서
spacing 유틸 2,045건 중 388건(19%)이 스케일 밖이었고, 그중 336건이 이 일곱 단계에 몰려 있었습니다.

<Callout>
  **이건 "이름에 값을 적어 넣는" 문제가 아닙니다.** [fontSize](/docs/foundations/typography) 는
  `13` · `15` 같은 숫자 키를 거부하고 `sm` · `base` 로 접었습니다 — 거기선 이름이 *역할*이고 숫자가
  드리프트였습니다. 반면 spacing 은 **처음부터 수치 좌표계**였고, 빠진 눈금을 채우는 건 새 명명
  철학이 아니라 같은 격자의 완성입니다.
</Callout>

잔여 52건(`0.5` · `9` · `11` · `18` · `28` · `32` · `60`)은 승격하지 않습니다 —
`style()` 리터럴로 남습니다.

## sprinkles [#sprinkles]

여백을 유틸로 쓸 땐 `sprinkles` 진입점입니다.

```ts
import { sprinkles } from '@coldsurfers/surf-ui/sprinkles'

sprinkles({ paddingY: '20', gap: '4' })
```

<Callout tone="warning">
  `sprinkles` 는 &#x2A;*배럴에 없습니다.** 런타임 맵이 JS 38 kB(gzip 5.7 kB)라, 배럴에서 재수출하면
  `vars` 한 줄 쓰려고 `.` 을 연 소비처까지 그걸 뭅니다(실측: `index.js` 3.2 → 41.2 kB).
</Callout>

반응형 축은 `mobile` · `tablet` · `desktop` 세 조건을 갖습니다.

```ts
sprinkles({ paddingX: { mobile: '4', desktop: '10' } })
```


---

# 타이포 (/docs/foundations/typography)



## font family [#font-family]

| 키       | 쓰임                                      |
| ------- | --------------------------------------- |
| `sans`  | 본문 · UI. 한국어 권위 + Latin 보조(Pretendard)  |
| `serif` | 헤드라인 · 매거진 마스트헤드(Instrument Serif)      |
| `mono`  | 메타 · 라벨 · 코드. 매거진 콜로폰 톤(JetBrains Mono) |

## text style — 역할 하나로 고른다 [#text-style--역할-하나로-고른다]

크기 · 행간 · 자간을 따로 고르는 대신 **역할 이름 하나**를 고릅니다.

```tsx
import { text } from '@coldsurfers/surf-ui'
import { sprinkles } from '@coldsurfers/surf-ui/sprinkles'

export default function Example() {
  return (
    <div style={{ display: 'grid', gap: 16, width: '100%' }}>
      <h2 className={text('heading', { weight: 'semibold' })}>이번 주말, 홍대</h2>
      <h3 className={text('title', { weight: 'medium' })}>금요일 밤의 라인업</h3>

      <p className={text('body')}>
        크기 하나가 아니라 역할 하나를 고릅니다. 행간과 자간이 그 역할에 맞게 같이 따라오므로, 같은
        자리에 선 글자는 지면이 달라도 같은 리듬으로 읽힙니다.
      </p>

      {/* 램프는 색을 묶지 않는다 — 같은 역할이 표면에 따라 다른 색을 입는 건 정상이다. */}
      <p className={`${text('bodySm')} ${sprinkles({ color: 'textSecondary' })}`}>
        보조 문장은 한 단 아래에서 같은 규칙을 따릅니다.
      </p>

      <div style={{ display: 'flex', gap: 12, alignItems: 'baseline', flexWrap: 'wrap' }}>
        <span className={text('label', { weight: 'medium' })}>라벨</span>
        <span className={`${text('labelSm')} ${sprinkles({ color: 'textSecondary' })}`}>
          21:00 입장
        </span>
        <span className={`${text('micro')} ${sprinkles({ color: 'textTertiary' })}`}>ISSUE 07</span>
      </div>
    </div>
  )
}
```

```ts
import { text } from '@coldsurfers/surf-ui'

text('body')
text('label', { weight: 'medium' })
```

| 이름        | fontSize | lineHeight | letterSpacing | 자리            |
| --------- | -------- | ---------- | ------------- | ------------- |
| `heading` | `2xl`    | `tight`    | `tight`       | 섹션 제목         |
| `title`   | `xl`     | `snug`     | `normal`      | 카드 · 블록 제목    |
| `body`    | `base`   | `relaxed`  | `normal`      | 읽는 본문         |
| `bodySm`  | `sm`     | `normal`   | `normal`      | 보조 본문 · UI 문장 |
| `label`   | `xs`     | `snug`     | `normal`      | 라벨 · 메타       |
| `labelSm` | `2xs`    | `snug`     | `normal`      | 좁은 라벨 · 수치    |
| `micro`   | `3xs`    | `snug`     | `normal`      | 마이크로 라벨       |

**왜 합성인가.** 크기만 토큰이고 행간 · 자간을 호출부가 각자 정하면 같은 역할의 글자가 지면마다
다르게 섭니다. 실측에서 `fontSize` 가 들어간 `sprinkles` 호출 478건에 구별되는 조합이 46가지였고,
그중 대다수가 `lineHeight` 를 비운 채였습니다 — 비우면 상속값이 들어오니 *정해진 적 없는 행간*이
화면에 서는 셈입니다.

**`fontWeight` 는 묶지 않습니다.** 같은 크기에 굵기가 2\~3종씩 붙어서, 이름에 넣으면 7단계가
21개가 됩니다. 그건 램프가 아니라 목록입니다. 색도 같은 이유로 밖에 둡니다.

<Callout>
  램프 밖 크기가 필요하면 덮지 말고 escape hatch 를 씁니다 — `sprinkles({ fontSize: 'lg' })`.
  램프 위에 크기만 덮으면 행간 · 자간이 그 크기에 맞지 않은 채 남습니다. `lg`(18px)에 단계를 주지
  않은 것도 같은 이유입니다 — 실사용 8건이 `body` 와 `title` 사이에 흩어져 역할이 서지 않았습니다.
</Callout>

`text()` 는 `ds-components` 레이어라, 호출자가 얹는 `sprinkles` 유틸이 &#x2A;*항상 이깁니다.**
바닥을 램프로 깔고 한 속성만 유틸로 덮는 것이 성립합니다.

## font size [#font-size]

**rem 단일 축**입니다. 값은 전부 16px root 기준 정수 px 등가입니다. px 로 직접 적지 않는 이유는
사용자의 브라우저 기본 글자 크기 설정을 따라가야 해서입니다.

| 토큰 | 값 |
| --- | --- |
| `--font-size-3xs` | `0.625rem` |
| `--font-size-2xs` | `0.6875rem` |
| `--font-size-xs` | `0.75rem` |
| `--font-size-sm` | `0.875rem` |
| `--font-size-base` | `1rem` |
| `--font-size-lg` | `1.125rem` |
| `--font-size-xl` | `1.25rem` |
| `--font-size-2xl` | `1.5rem` |
| `--font-size-3xl` | `1.875rem` |
| `--font-size-4xl` | `2.25rem` |
| `--font-size-5xl` | `3rem` |
| `--font-size-6xl` | `3.75rem` |

`3xs` · `2xs` 는 라벨 축입니다. 실측에서 9~~11px 사용의 uppercase 41~~68% · tracking 69~~88% ·
mono 지배가 12px 위와 뚜렷하게 갈렸고, 파일당 1~~2종만 쓰여 **역할이 실재**했습니다.

반면 12.5~~17px 은 한 파일이 3~~5종을 섞어 쓰는 드리프트라 단계를 늘리지 않고 기존 네 단계
(`xs` · `sm` · `base` · `lg`)로 접었습니다.

<Callout>
  **이름에 값을 적어 넣지 않습니다.** `13` · `15` 같은 숫자 키를 거부한 이유는 하나입니다 — 토큰의
  값을 바꿀 때 사용처를 전부 고쳐야 하면 간접화가 0 이라 그건 토큰이 아닙니다.
</Callout>

## line height [#line-height]

| 토큰 | 값 |
| --- | --- |
| `--line-height-tight` | `1.2` |
| `--line-height-snug` | `1.4` |
| `--line-height-normal` | `1.6` |
| `--line-height-relaxed` | `1.75` |

## font weight [#font-weight]

| 토큰 | 값 |
| --- | --- |
| `--font-weight-light` | `300` |
| `--font-weight-regular` | `400` |
| `--font-weight-medium` | `500` |
| `--font-weight-semibold` | `600` |
| `--font-weight-bold` | `700` |
| `--font-weight-black` | `900` |

## letter spacing [#letter-spacing]

**본문·UI 축**입니다. 세 단계뿐이고, 크기가 아니라 역할로 고릅니다.

| 토큰 | 값 |
| --- | --- |
| `--letter-spacing-none` | `0` |
| `--letter-spacing-normal` | `-0.02em` |
| `--letter-spacing-tight` | `-0.03em` |

```tsx
import { sprinkles } from '@coldsurfers/surf-ui/sprinkles'

const SENTENCE = '서울의 공연을 하나의 지면에서 발견합니다'

export default function Example() {
  return (
    <div style={{ display: 'grid', gap: 24, width: '100%' }}>
      {/* 본문 — 한글은 0 에 두면 헐렁하다. 같은 문장을 두 줄로 나란히 둬야 차이가 보인다. */}
      <div style={{ display: 'grid', gap: 6 }}>
        <p className={sprinkles({ fontSize: 'base', color: 'textPrimary', letterSpacing: 'none' })}>
          {SENTENCE}
        </p>
        <p
          className={sprinkles({ fontSize: 'base', color: 'textPrimary', letterSpacing: 'normal' })}
        >
          {SENTENCE}
        </p>
        <span
          className={sprinkles({ fontSize: '2xs', fontFamily: 'mono', color: 'textSecondary' })}
        >
          위 none · 아래 normal
        </span>
      </div>

      {/* 헤드라인 — 큰 글자는 더 조여야 같은 무게로 읽힌다. */}
      <h3
        className={sprinkles({
          fontSize: '3xl',
          fontWeight: 'semibold',
          color: 'textPrimary',
          lineHeight: 'tight',
          letterSpacing: 'tight',
        })}
      >
        이번 주말, 홍대
      </h3>

      {/* mono — 격자가 곧 리듬이라 조이지 않는다. */}
      <code className={sprinkles({ fontSize: 'sm', fontFamily: 'mono', letterSpacing: 'none' })}>
        2026-09-11 · 21:00 · KRW 25,000
      </code>
    </div>
  )
}
```

`sprinkles({ letterSpacing })` 로 얹거나, `.css.ts` 에서 `vars.letterSpacing.normal` 을 읽습니다.
어느 쪽이든 같은 `--letter-spacing-*` 변수를 가리킵니다.

이 축이 왜 필요했는지: 아래 `editorialType` 3그룹만 `letterSpacing` 을 갖고 있어서, 본문·UI 는
브라우저 기본값(0)이었습니다. Pretendard 로 한글을 0 에 두면 글자가 느슨하게 벌어져 같은
크기에서 라틴보다 헐렁하게 읽힙니다. 그래서 소비처가 자기 CSS 로 이 자리를 메우고 있었습니다.

큰 글자는 더 조여야 같은 무게로 읽히므로 24px 이상 헤드라인은 `tight` 로 갑니다. mono 는
`none`(0) 입니다 — 고정폭 글리프는 격자가 곧 리듬이라, 조이면 코드·수치가 뭉칩니다.

<Callout tone="warning">
  **`editorialType` 의 자간과 겹쳐 쓰지 않습니다.** 저쪽은 크기까지 묶은 합성 슬롯(clamp display ·
  uppercase eyebrow)이고 이쪽은 어느 크기에든 얹는 단일 속성입니다. 합성 슬롯을 쓰는 자리에서는
  그쪽 값이 이미 자간을 정하므로 이 토큰을 덧대지 않습니다.
</Callout>

## text box [#text-box]

알약 · 칩처럼 **상자 안 한 줄 글자**를 눈으로 가운데에 세울 때 씁니다.

```tsx
<span className={pill}>
  <span className={sprinkles({ display: 'block', textBox: 'cap' })}>새 11</span>
</span>
```

`textBox: 'cap'` 은 글자 상자를 대문자 높이에서 기준선까지 자릅니다(`text-box: trim-both cap alphabetic`).
Pretendard 는 위 여백이 아래보다 커서, 상자만 flex 로 가운데 두면 글자가 0.5–1px 뜹니다.
패딩 1px 로 메우면 크기가 바뀔 때마다 다시 재야 합니다.

<Callout tone="warning">
  **flex · grid 상자 자신에는 먹지 않습니다.** 안쪽 블록 한 겹에 겁니다. 지원하지 않는
  브라우저(Firefox)에서는 자르지 않은 원래 상자로 남습니다 — 깨지지는 않습니다.
</Callout>

## editorial type [#editorial-type]

매거진 톤의 합성 타이포 슬롯입니다. `eyebrow` · `display` · `caption` 세 그룹이 있고,
`letterSpacing` 과 `lineHeight` 만 자기 값을 갖습니다 — 크기는 위 `fontSize` 를 읽습니다.

그 슬롯을 컴포넌트로 쓰는 쪽이 [Eyebrow](/docs/components/eyebrow) 입니다.


---

# AnimatedTabBar (/docs/native/animated-tab-bar)



```tsx
import { AnimatedTabBar } from '@coldsurfers/surf-ui/native/AnimatedTabBar'
import { TabBar, useTabBarHeight } from '@coldsurfers/surf-ui/native/TabBar'

function Screen() {
  const [visible, setVisible] = useState(true)
  const tabBarHeight = useTabBarHeight()

  return (
    <View style={{ flex: 1 }}>
      <ScrollView contentContainerStyle={{ paddingBottom: tabBarHeight }}>
        {/* ... */}
      </ScrollView>

      <AnimatedTabBar visible={visible}>
        {TABS.map(({ key, label, Icon }) => (
          <TabBar.Item
            key={key}
            label={label}
            active={key === selected}
            onPress={() => setSelected(key)}
            renderIcon={({ color, size, strokeWidth }) => (
              <Icon color={color} size={size} strokeWidth={strokeWidth} />
            )}
          />
        ))}
      </AnimatedTabBar>
    </View>
  )
}
```

<Callout title="미리보기가 없는 이유">
  reanimated 는 워클릿을 babel 플러그인으로 변환하는데, turbopack 은 &#x2A;*`node_modules` 를
  babel 대상에서 뺍니다.** 이 사이트가 무는 워클릿은 DS 의 `dist` 안, 즉 `node_modules` 에
  있어서 기본 배선이 닿지 않습니다. 그래서 이 표면만 코드로 설명합니다 —
  [#119](https://github.com/coldsurfers/public/issues/119) 에서 뚫을 방법을 재고 있습니다.
</Callout>

## [`TabBar`](/docs/native/tab-bar) 와 왜 나뉘어 있나 [#tabbar-와-왜-나뉘어-있나]

의존 하나 때문입니다. reanimated 애니메이션 스타일은 `Animated.*` 에만 먹어서, 위치와 이동을
면이 같이 들면 &#x2A;*면 자체가 reanimated 를 뭅니다.** 그러면 움직일 일이 없는 소비처도 그 의존을
집니다. 그래서 움직이는 축만 여기로 뺐습니다.

자리를 `position: 'absolute'` 로 잡는 것도 여기입니다 — 슬라이드하려면 레이아웃 흐름에서
빠져 있어야 하고, 그건 *이동의 조건* 이지 면의 성질이 아닙니다.

## 그래서 화면이 아래 여백을 직접 잡아야 한다 [#그래서-화면이-아래-여백을-직접-잡아야-한다]

탭바가 흐름에서 빠져 있으니 자리를 비워 주지 않습니다. `useTabBarHeight()` 로 받아
스크롤 콘텐츠의 `paddingBottom` 에 넣습니다. 안 넣으면 마지막 항목이 탭바에 가립니다.

## 숨김은 언마운트가 아니다 [#숨김은-언마운트가-아니다]

`visible={false}` 는 아래로 **밀어** 숨깁니다(150ms). 언마운트가 아니라 이동이라
되돌아올 때 아이템 상태가 남아 있습니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `visible?` | `boolean` | — | false 면 아래로 밀어 숨긴다. 언마운트가 아니라 이동이라 되돌아올 때 상태가 남는다. |
| `children` | `ReactNode` | — | `TabBar.Item` 들. |

아이템은 그대로 [`TabBar.Item`](/docs/native/tab-bar) 을 씁니다.


---

# Getting Started (/docs/native/getting-started)



`@coldsurfers/surf-ui/native` 는 React Native 앱을 위한 별도 구현입니다.
웹 `primitives` 와 **같은 prop 계약**을 따르지만 스타일 엔진이 다릅니다 — 웹은 vanilla-extract,
이쪽은 `@emotion/native` 입니다.

## 왜 구현이 둘인가 [#왜-구현이-둘인가]

웹 레인의 산출물은 CSS 파일과 클래스 이름 문자열입니다. RN 에는 그 둘을 받을 곳이 없습니다 —
`className` 도 스타일시트도 없습니다. 그래서 공유선은 **토큰 값과 prop 계약**까지고,
스타일은 플랫폼마다 따로 씁니다.

값이 갈리지 않게 묶는 자리가 `contract/` 입니다. 축(`ButtonVariant`), 공통 props,
치수 표(`CONCERT_CARD_BARE_SPEC`)를 여기 올리고 양쪽 구현이 그걸 읽습니다.

## 설치 [#설치]

```bash
pnpm add @coldsurfers/surf-ui
```

peer 는 쓰는 표면만큼만 필요합니다. 전부 optional 이라 웹만 쓰는 소비처는 하나도 안 깝니다.

| 무엇을 쓰면                             | 무엇이 필요한가                                            |
| ---------------------------------- | --------------------------------------------------- |
| 전부                                 | `@emotion/native` · `react-native`                  |
| `TabBar` · `AnimatedTabBar`        | `react-native-safe-area-context`                    |
| `AnimatedTabBar` · `PullToRefresh` | `react-native-reanimated` · `react-native-worklets` |
| `PullToRefresh`                    | `react-native-gesture-handler`                      |
| `Spinner` · `PullToRefresh`        | `react-native-svg`                                  |

## import 경로 [#import-경로]

배럴(`/native`)과 표면별 진입점(`/native/TabBar`) 둘 다 열려 있습니다.

```tsx
import { Button, Text } from '@coldsurfers/surf-ui/native'
import { TabBar } from '@coldsurfers/surf-ui/native/TabBar'
```

무거운 peer 를 무는 표면은 &#x2A;*진입점으로 여는 편이 낫습니다.** 배럴은 `PullToRefresh` 까지
끌고 오므로, 탭바만 쓰는 화면도 gesture-handler 를 번들에 들입니다.

## 색은 훅으로 받는다 [#색은-훅으로-받는다]

RN 에는 CSS 변수가 없습니다. 웹에서 `var(--surf-action-primary)` 한 줄로 끝나던 색 참조를
[`useScheme()`](/docs/native/scheme) 이 대신합니다.

```tsx
const scheme = useScheme()
<View style={{ backgroundColor: scheme.surface }} />
```

## 축은 웹부터 늘린다 [#축은-웹부터-늘린다]

새 variant 나 size 가 필요하면 &#x2A;*웹에서 먼저 엽니다.** 여기서 먼저 늘리면 계약이 갈라집니다.

예외는 **웹에 짝이 생길 수 없는 표면** 하나뿐입니다 — [`TabBar`](/docs/native/tab-bar) ·
[`AnimatedTabBar`](/docs/native/animated-tab-bar) · [`PullToRefresh`](/docs/native/pull-to-refresh)
셋이 그렇습니다. 하단 탭 크롬과 당겨서 새로고침은 웹에 대응하는 면이 없습니다.

<Callout title="문서의 미리보기는 진짜 RN 코드입니다">
  이 사이트는 `react-native` 를 `react-native-web` 으로 별칭 걸어 native 컴포넌트를 그대로
  그립니다. 그래서 그려진다는 것 자체가 그 조합이 실제 앱에서 선다는 증거입니다.

  다만 `PullToRefresh` 와 `AnimatedTabBar` 는 미리보기가 없습니다 — reanimated 의 워클릿
  변환이 babel 플러그인인데, turbopack 은 `node_modules` 를 babel 대상에서 빼기 때문입니다.
  이 사이트가 무는 워클릿은 DS 의 `dist` 안, 즉 `node_modules` 에 있습니다
  ([#119](https://github.com/coldsurfers/public/issues/119)).
</Callout>


---

# IconButton (/docs/native/icon-button)



```tsx
import { IconButton } from '@coldsurfers/surf-ui/native/IconButton'
import { nativeSpacing } from '@coldsurfers/surf-ui/tokens/native'
import { Bookmark, Heart, Share2, X } from 'lucide-react'
import { View } from 'react-native'

export default function Example() {
  return (
    <View
      style={{
        flexDirection: 'row',
        alignItems: 'center',
        gap: nativeSpacing[3],
        padding: nativeSpacing[5],
      }}
    >
      <IconButton label="닫기">
        <X size={20} />
      </IconButton>
      <IconButton label="공유" variant="outline">
        <Share2 size={20} />
      </IconButton>
      <IconButton label="담기" variant="accent">
        <Bookmark size={20} color="white" />
      </IconButton>
      <IconButton label="좋아요" variant="primary" size="sm">
        <Heart size={18} color="white" />
      </IconButton>
    </View>
  )
}
```

`Button` 과 **같은 variant 축**을 씁니다. 색 어휘를 하나 더 만들면 같은 `outline` 이
두 컴포넌트에서 다른 뜻이 될 수 있습니다.

## 크기 축이 `Button` 과 다른 이유 [#크기-축이-button-과-다른-이유]

`Button` 의 `sm`·`md`·`cta` 는 *라벨이 있는 컨트롤의 높이* 입니다. 여기는 **손가락이 닿는
정사각** 이라 축이 다릅니다.

|           | 한 변 |
| --------- | --- |
| `sm`      | 36  |
| `md` (기본) | 44  |

44 는 시안 치수가 아니라 iOS HIG 의 최소 터치 타깃입니다 — 접근성 하한이라 기본값입니다.

## `label` 이 필수인 이유 [#label-이-필수인-이유]

아이콘만 있어 스크린 리더가 읽을 이름이 없습니다. `accessibilityLabel` 로 들어갑니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `variant?` | `'primary' \| 'secondary' \| 'ghost' \| 'accent' \| 'outline' \| 'danger'` | — | — |
| `size?` | `'sm' \| 'md'` | — | — |
| `label` | `string` | — | 스크린 리더용 이름. 아이콘만 있어 라벨이 없으므로 필수. |
| `children` | `ReactNode` | — | — |

그 밖의 `ComponentPropsWithRef<typeof TouchableOpacity>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Masonry · PinCard (/docs/native/masonry)



```tsx
import { Masonry } from '@coldsurfers/surf-ui/native/Masonry'
import { PinCard } from '@coldsurfers/surf-ui/native/PinCard'

function Feed() {
  return (
    <Masonry
      items={pins}
      keyOf={(pin) => pin.id}
      paddingHorizontal={16}
      header={<FeedHeader />}
      footer={isFetchingNextPage ? <Spinner /> : null}
      onEndReached={() => hasNextPage && fetchNextPage()}
      renderItem={(pin) => (
        <PinCard poster={pin.poster} title={pin.title} meta={pin.source} onPress={() => open(pin)} />
      )}
    />
  )
}
```

<Callout title="그리드 미리보기가 없는 이유">
  FlashList v2 는 react-native-web 에서 열 폭을 재지 못해 셀이 폭 0 으로 섭니다. 카드 한 장은 아래에서 그립니다.
</Callout>

웹 [`Masonry`](/docs/patterns/masonry) 와 간격(열 12 · 줄 16)이 같습니다 — `MASONRY_SPEC`.
다른 점은 배치입니다. 웹은 추정 높이로 놓고, 여기는 FlashList `masonry` 가 **재서** 놓으므로
`heightOf` 가 없습니다. 화면 밖 카드는 그리지 않습니다.

## 스크롤을 소유한다 [#스크롤을-소유한다]

다른 `ScrollView` 안에 넣으면 가상화가 꺼집니다. 위 콘텐츠는 `header`, 다음 쪽 스피너는 `footer`,
다음 쪽 받기는 `onEndReached` 로 줍니다. 바텀시트 안이면 시트의 스크롤을 `renderScrollComponent` 로
줍니다 — `@gorhom/bottom-sheet` 5.2 는 `useBottomSheetScrollableCreator()` 가 그 값을 만듭니다.

끝에 이어 붙는 목록만 다룹니다. 앞에 끼워 넣어도 보던 자리를 붙잡는 FlashList
`maintainVisibleContentPosition` 은 꺼 두었습니다 — 켜 두면 먼 아래에서 맨 위로(`scrollToTop`)가
몇 pt 못 미쳐 멈춥니다.

## 설치 [#설치]

소비처가 `@shopify/flash-list` ≥2 (New Architecture) 를 들고 있어야 합니다. JS 전용이라 네이티브 빌드는
필요 없습니다. 배럴(`/native`)에는 없고 `@coldsurfers/surf-ui/native/Masonry` 로만 엽니다 —
FlashList 없는 소비처도 배럴을 열 수 있게.

## PinCard [#pincard]

```tsx
import { PinCard } from '@coldsurfers/surf-ui/native/PinCard'
import { View } from 'react-native'
import { samplePins } from './pin-samples'

export default function Example() {
  const [first, second] = [samplePins[0], samplePins.at(-1)]
  return (
    <View style={{ flexDirection: 'row', gap: 12, padding: 16, alignItems: 'flex-start' }}>
      {[first, second].map((pin) =>
        pin ? (
          <View key={pin.id} style={{ flex: 1 }}>
            <PinCard poster={pin.poster} title={pin.title} meta={pin.meta} />
          </View>
        ) : null,
      )}
    </View>
  )
}
```

웹 `PinCard` 와 치수가 같습니다 — `PIN_CARD_SPEC`. 포스터가 도착하면 페이드인하고, 누르는 동안
살짝 줄어듭니다. 동작 줄이기 설정이면 둘 다 끕니다. 한 번 받은 포스터 비율은 기억해 두어,
카드가 재활용돼도 3:4 에서 덜컥 늘어나지 않습니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `items` | `readonly T[]` | — | — |
| `keyOf` | `(item: T) => string` | — | 항목의 고유 키 — 재활용 · 배치의 열쇠. |
| `renderItem` | `(item: T) => ReactElement \| null` | — | — |
| `columnCount?` | `number` | — | 기본 2. |
| `header?` | `ReactNode` | — | 그리드 위 — 화면 머리 · 위 콘텐츠. |
| `footer?` | `ReactNode` | — | 그리드 아래 — 다음 쪽 스피너 · 「더 불러오기」. |
| `paddingHorizontal?` | `number` | — | 그리드 좌우 여백. 기본 0. |
| `ref?` | `Ref<FlashListRef<T>>` | — | — |

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `poster?` | `string \| null` | — | 포스터 주소. 없으면 3:4 회색 자리에 `fallback`. |
| `title` | `string` | — | — |
| `meta?` | `string \| null` | — | 출처 한 줄 — 도메인 · `@올린 사람`. |
| `fallback?` | `string` | — | 포스터가 없을 때 회색 자리 안 글자. 기본 `title`. |
| `action?` | `ReactNode` | — | 포스터 오른쪽 아래 — 보통 담기 ＋. 안쪽 `Pressable` 이 터치를 먼저 받아 카드 누름과 갈린다. |
| `onPress?` | `(() => void)` | — | 같은 함수를 넘기면 `memo` 가 리렌더를 끊는다. |


---

# PullToRefresh (/docs/native/pull-to-refresh)



```tsx
import { PullToRefresh } from '@coldsurfers/surf-ui/native/PullToRefresh'
import { useAnimatedRef } from 'react-native-reanimated'

function Feed() {
  const scrollableRef = useAnimatedRef<Animated.FlatList<Event>>()

  return (
    <PullToRefresh
      scrollableRef={scrollableRef}
      onRefresh={() => Promise.all([refetchFeed(), refetchBanner()])}
      onHapticFeedback={() => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)}
    >
      {(scrollableProps) => (
        <Animated.FlatList data={events} renderItem={renderEvent} {...scrollableProps} />
      )}
    </PullToRefresh>
  )
}
```

<Callout title="미리보기가 없는 이유">
  reanimated 의 워클릿 변환이 babel 플러그인인데, turbopack 은 `node_modules` 를 babel 대상에서
  뺍니다. 이 사이트가 무는 워클릿은 DS 의 `dist` 안에 있어서 기본 배선이 닿지 않습니다
  ([#119](https://github.com/coldsurfers/public/issues/119)).

  뚫리더라도 제스처는 **마우스로 흉내 내면 감각이 거짓**이라, 이 표면은 실기기에서 보는 편이
  맞습니다.
</Callout>

## RN 기본 `RefreshControl` 을 왜 안 쓰나 [#rn-기본-refreshcontrol-을-왜-안-쓰나]

그건 iOS `UIRefreshControl` · Android `SwipeRefreshLayout` 이 그리는 **네이티브 뷰**라
자식도 커스텀 인디케이터도 받지 않습니다. 색 채널(`tintColor`/`colors`)만 열려 있어서
색을 맞춰 봐야 모양은 플랫폼 것 그대로입니다. 그래서 당김 감지부터 이쪽이 합니다.

## 스크롤러를 감싸지 않고 돌려주는 이유 [#스크롤러를-감싸지-않고-돌려주는-이유]

화면마다 스크롤러가 다릅니다 — 피드는 `SectionList`, 목록 화면은 `FlatList` 입니다.
어느 쪽을 쓸지는 소비처가 정하고, 여기서는 거기 꽂을 props 만 넘깁니다.

받은 props 는 &#x2A;*그대로 펼쳐 넣어야 합니다.**

| props                     | 왜                                                     |
| ------------------------- | ----------------------------------------------------- |
| `ref`                     | 안 달면 "지금 맨 위인가"를 알 수 없어 스크롤 중간에서도 당김이 걸립니다            |
| `bounces: false`          | iOS 네이티브 바운스가 켜져 있으면 네이티브가 밀어 올린 만큼 틈에 더해져 두 배로 움직입니다 |
| `overScrollMode: 'never'` | Android 글로우/스트레치도 같은 이유                               |

## `scrollableRef` 를 소비처가 만드는 이유 [#scrollableref-를-소비처가-만드는-이유]

여기서 만들어 children 인자로만 주면, 소비처가 scroll-to-top 같은 다른 용도와 합치려고
렌더마다 새 콜백 ref 를 쓰게 됩니다. 그러면 React 가 매 렌더 `ref(null)` → `ref(node)` 를
돌려 당김 판정이 흔들립니다.

## Android 에는 오버스크롤 바운스가 없다 [#android-에는-오버스크롤-바운스가-없다]

스크롤 오프셋이 음수로 내려가지 않으므로 "오프셋이 마이너스면 당김" 이라는 iOS 식 판정이
통째로 안 먹습니다. 그래서 오프셋이 아니라 **제스처의 이동량**을 재고, 오프셋은 "지금 맨
위인가"를 가르는 데만 씁니다.

## `onRefresh` 는 promise 를 돌려주면 된다 [#onrefresh-는-promise-를-돌려주면-된다]

promise 가 끝날 때까지 인디케이터가 떠 있습니다. 화면이 여러 쿼리로 쪼개져 있으면
`Promise.all` 로 묶어 넘깁니다. 최소 노출 시간은 **같이** 기다립니다 — 순차로 기다리면
느린 응답에 그만큼이 그대로 얹힙니다.

실패는 삼킵니다. 네트워크가 죽으면 늘 나는 경로라 여기서 안 삼키면 unhandled rejection 이
됩니다. 인디케이터는 닫히고, 에러 표시는 소비처의 몫입니다.

## `onHapticFeedback` 은 왜 콜백인가 [#onhapticfeedback-은-왜-콜백인가]

DS 가 `expo-haptics` 를 물면 Expo 를 쓰지 않는 소비처까지 그걸 깔아야 합니다. 무엇을 어떤
세기로 울릴지도 화면의 맥락이라 소비처가 정합니다. 그래서 **시점만 여기가 알고, 울리는 건
소비처가** 합니다.

<Callout type="warn">
  성공 · 실패를 가리지 않고 불립니다. "요청이 끝났다"는 신호지 "성공했다"는 신호가 아닙니다.
</Callout>

## 절대 위치 헤더가 있으면 `topInset` [#절대-위치-헤더가-있으면-topinset]

헤더가 콘텐츠 위에 떠 있는 화면에서 0 에 열면 인디케이터 스트립이 헤더 뒤에 가립니다.
헤더 높이를 넘기면 그 아래에서 열립니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `scrollableRef` | `PullToRefreshScrollableRef` | — | 스크롤러 ref — **소비처가 만들어 넘긴다**(`useAnimatedRef`). 여기서 만들어 children 인자로만 주면 소비처가 scroll-to-top 같은 다른 용도와 합치려고 렌더마다 새 콜백 ref 를 쓰게 되고, 그러면 React 가 매 렌더 `ref(null)` → `ref(node)` 를 돌려 당김 판정이 흔들린다. |
| `onRefresh` | `() => Promise<unknown>` | — | 새로고침 본체. **promise 를 돌려주면 그게 끝날 때까지** 인디케이터가 떠 있는다 — 화면이 여러 쿼리로 쪼개져 있으면 `Promise.all` 로 묶어 넘기면 된다. |
| `onHapticFeedback?` | `(() => void)` | — | 새로고침이 끝난 순간 한 번 불린다 — haptic 을 물릴 자리다. 여기서 DS 가 직접 울리지 않는 건 계약 때문이다. `expo-haptics` 를 물면 Expo 를 쓰지 않는 소비처까지 그걸 깔아야 한다. 무엇을 어떤 세기로 울릴지도 화면의 맥락이라 소비처의 몫이다. 성공·실패를 가리지 않고 불린다 — "요청이 끝났다"는 신호지 "성공했다"는 신호가 아니다. |
| `children` | `(scrollableProps: PullToRefreshScrollableProps) => ReactNode` | — | 스크롤러를 그리는 자리. 받은 props 를 그대로 펼쳐 넣어야 한다. |
| `enabled?` | `boolean` | — | false 면 당김을 아예 받지 않는다(스크롤은 그대로). |
| `topInset?` | `number` | — | 인디케이터 스트립이 열리기 시작하는 y. 절대 위치 헤더가 콘텐츠 위에 떠 있는 화면에서 0 에 열면 스트립이 헤더 뒤에 가려진다 — 헤더 높이를 넘기면 그 아래에서 열린다. |

### 스크롤러에 펼쳐 넣는 props [#스크롤러에-펼쳐-넣는-props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `ref` | `PullToRefreshScrollableRef` | — | — |
| `bounces` | `false` | — | iOS 네이티브 바운스를 끈다 — 켜두면 네이티브가 밀어 올린 만큼 이 틈에 더해져 두 배로 움직인다. |
| `overScrollMode` | `"never"` | — | Android 글로우/스트레치도 같은 이유로 끈다. |


---

# useScheme (/docs/native/scheme)



```tsx
import { useScheme } from '@coldsurfers/surf-ui/native/scheme'
import { Text } from '@coldsurfers/surf-ui/native/Text'
import { nativeRadius, nativeSpacing } from '@coldsurfers/surf-ui/tokens/native'
import { View } from 'react-native'

/** 색을 훅에서 받아 스타일에 직접 넣는다 — RN 엔 CSS 변수가 없다. */
const SLOTS = [
  'bgBase',
  'surfaceRaised',
  'lineDivider',
  'textPrimary',
  'textSecondary',
  'actionPrimary',
] as const

export default function Example() {
  const scheme = useScheme()

  return (
    <View style={{ gap: nativeSpacing[2], padding: nativeSpacing[5] }}>
      {SLOTS.map((slot) => (
        <View
          key={slot}
          style={{ flexDirection: 'row', alignItems: 'center', gap: nativeSpacing[3] }}
        >
          <View
            style={{
              width: 32,
              height: 32,
              borderRadius: nativeRadius.sm,
              borderWidth: 1,
              borderColor: scheme.lineDivider,
              backgroundColor: scheme[slot],
            }}
          />
          <Text textStyle="bodySm">{slot}</Text>
          <Text textStyle="labelSm" tone="subtle">
            {scheme[slot]}
          </Text>
        </View>
      ))}
    </View>
  )
}
```

색 **객체**를 돌려줍니다. 스타일에 직접 넣으면 됩니다.

## 왜 훅인가 [#왜-훅인가]

웹에서는 `var(--surf-surface-raised)` 한 줄이면 끝납니다 — 값이 어디서 오는지 컴포넌트가 몰라도 됩니다.
RN 에는 그 간접층이 없어서, 누군가는 색을 **읽어다 넘겨야** 합니다. 그 자리가 이 훅입니다.

## 스킴이 하나뿐인데 왜 훅 모양인가 [#스킴이-하나뿐인데-왜-훅-모양인가]

지금 `useScheme()` 은 상수 하나를 돌려줍니다. ink(dark) 스킴을 폐기하면서 뒤집을 축이
사라졌기 때문입니다.

그래도 훅 모양을 남겨 둔 건 호출부가 이미 이 경계를 쓰고 있어서입니다. 스킴이 다시 생기면
**이 파일 한 곳만** 되돌리면 됩니다. 소비처가 `nativeColor.light` 를 직접 읽고 있었다면
그때 전부를 고쳐야 합니다.

<Callout type="warn">
  그래서 &#x2A;*색을 `nativeColor.light` 에서 직접 읽지 마세요.** 지금은 같은 값이지만, 그 순간
  되돌릴 자리가 한 곳에서 여러 곳으로 늘어납니다.
</Callout>

## 슬롯 [#슬롯]

표면 · 텍스트 · 상태 색이 한 객체에 있습니다. 전체 값은
[Foundations › Colors](/docs/foundations/colors) 가 정본입니다 — 웹과 같은 팔레트입니다.

`Text` 의 `tone` 축에 없는 색(`statusDanger` 등)이 필요하면 여기서 읽어 `style` 로 넣습니다.

```tsx
<Text textStyle="labelSm" style={{ color: scheme.statusDanger }}>
  @ 가 없습니다.
</Text>
```


---

# TabBar (/docs/native/tab-bar)



```tsx
import { TabBar } from '@coldsurfers/surf-ui/native/TabBar'
import { Text } from '@coldsurfers/surf-ui/native/Text'
import { House, Search, Tickets, UserRound } from 'lucide-react'
import { useState } from 'react'
import { View } from 'react-native'

const TABS = [
  { key: 'feed', label: '피드', Icon: House },
  { key: 'events', label: '이벤트', Icon: Tickets },
  { key: 'search', label: '검색', Icon: Search },
  { key: 'my', label: '나의 창꼬', Icon: UserRound },
]

export default function Example() {
  const [selected, setSelected] = useState('feed')

  return (
    <>
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
        <Text textStyle="body" tone="muted">
          {TABS.find((tab) => tab.key === selected)?.label}
        </Text>
      </View>

      <TabBar>
        {TABS.map(({ key, label, Icon }) => (
          <TabBar.Item
            key={key}
            label={label}
            active={key === selected}
            onPress={() => setSelected(key)}
            renderIcon={({ color, size, strokeWidth }) => (
              <Icon color={color} size={size} strokeWidth={strokeWidth} aria-hidden />
            )}
          />
        ))}
      </TabBar>
    </>
  )
}
```

**웹에 짝이 없는 표면**입니다. 이건 면(chrome)이지 네비게이션도 배치도 아닙니다.

## 무엇을 들고 무엇을 안 드는가 [#무엇을-들고-무엇을-안-드는가]

| 여기                                                    | 여기가 아닌 곳                                                                |
| ----------------------------------------------------- | ----------------------------------------------------------------------- |
| 색 · 테두리 · 높이(safe-area 포함) · 아이템 배치 · 라벨 서식 · 활성 tint | 라우터 배선 · route → 아이콘 매핑 · 햅틱 → **소비처**                                  |
|                                                       | 화면 하단 고정 · 숨김 애니메이션 → [`AnimatedTabBar`](/docs/native/animated-tab-bar) |

**위치를 정하지 않는 이유는 의존입니다.** reanimated 애니메이션 스타일은 `Animated.*` 에만
먹으므로, 위치와 이동을 한 컴포넌트가 들면 이 파일이 reanimated 를 물게 됩니다. 그러면
애니메이션을 안 쓰는 소비처까지 그 의존을 집니다. 여기 의존은 emotion 과
safe-area-context 둘뿐입니다.

## 아이콘을 노드가 아니라 함수로 받는 이유 [#아이콘을-노드가-아니라-함수로-받는-이유]

색 · 크기 · 굵기는 활성 여부에서 나오는 **이 면의 계약**이고, 무엇을 그릴지는 소비처의 것입니다.
노드로 받으면 소비처가 tint 를 알아야 하고, 그러면 색 계약이 밖으로 샙니다.

```tsx
renderIcon={({ color, size, strokeWidth }) => (
  <House color={color} size={size} strokeWidth={strokeWidth} />
)}
```

활성 상태는 채움 아이콘 세트가 아니라 **굵기와 accent 색**으로 말합니다 (1.5 → 2.5).

## 높이는 `useTabBarHeight()` 에서 읽는다 [#높이는-usetabbarheight-에서-읽는다]

`AnimatedTabBar` 로 띄우면 탭바가 레이아웃에서 빠져 자리를 비워 주지 않습니다. 화면이
자기 콘텐츠 아래 여백을 이 값으로 잡아야 합니다.

```tsx
const tabBarHeight = useTabBarHeight()
<ScrollView contentContainerStyle={{ paddingBottom: tabBarHeight }} />
```

인셋을 상수로 박지 않습니다 — 홈 인디케이터 높이는 기기마다 다르고 0 인 기기(SE · iPad)도
있어서, 박으면 그런 기기에서 탭바 아래가 빈 채로 남습니다.

화면 전체가 이 여백을 져야 하면 직접 계산하는 대신
[`AppScreen`](/docs/screens/app-screen) 의 `offsetBottom="tabBar"` 를 씁니다.

<Callout type="warn" title="위 미리보기의 높이는 실기기 높이가 아닙니다">
  브라우저에서는 `Platform.OS === 'web'` 이라 아래 여백이 0 입니다. 실기기에서는 iOS 가
  홈 인디케이터 인셋만큼, Android 가 12 만큼 더 큽니다.

  그리고 `useSafeAreaInsets()` 를 부르므로 앱 루트에 `SafeAreaProvider` 가 있어야 합니다.
</Callout>

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | `TabBar.Item` 들. |

그 밖의 `ViewProps` 속성은 루트 엘리먼트로 그대로 통과한다.

### `TabBar.Item` [#tabbaritem]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `label` | `string` | — | — |
| `active?` | `boolean` | — | — |
| `renderIcon` | `(state: { color: string; size: number; strokeWidth: number; }) => ReactNode` | — | 아이콘을 그리는 자리. 색·크기·굵기는 이 면이 정해 넘긴다 — 위 「무엇을 들고 무엇을 안 드는가」. |

그 밖의 `TouchableOpacityProps` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# TextInput (/docs/native/text-input)



```tsx
import { useScheme } from '@coldsurfers/surf-ui/native/scheme'
import { Text } from '@coldsurfers/surf-ui/native/Text'
import { TextInput } from '@coldsurfers/surf-ui/native/TextInput'
import { nativeSpacing } from '@coldsurfers/surf-ui/tokens/native'
import { useState } from 'react'
import { View } from 'react-native'

export default function Example() {
  const scheme = useScheme()
  const [email, setEmail] = useState('')
  const invalid = email.length > 0 && !email.includes('@')

  return (
    <View style={{ gap: nativeSpacing[2], padding: nativeSpacing[5] }}>
      <Text textStyle="labelSm" tone="muted">
        이메일
      </Text>
      <TextInput
        value={email}
        onChangeText={setEmail}
        invalid={invalid}
        placeholder="you@coldsurf.io"
        autoCapitalize="none"
        keyboardType="email-address"
      />
      {/* 에러 문구는 `Text` 의 톤 축에 없다 — 스킴에서 직접 읽는다. */}
      {invalid ? (
        <Text textStyle="labelSm" style={{ color: scheme.statusDanger }}>
          @ 가 없습니다.
        </Text>
      ) : null}
    </View>
  )
}
```

웹은 `Field` 가 라벨 · 에러 · 입력을 한 묶음으로 들지만, RN 판은 **입력만** 듭니다.

## 왜 `Field` 가 아닌가 [#왜-field-가-아닌가]

라벨과 에러의 조판은 폼 레이아웃의 문제고, 그건 화면마다 다릅니다. 지금 소비처가 하나라
묶어 두면 그 화면의 조판이 계약이 됩니다. 두 번째 소비처가 같은 조판을 요구할 때 올립니다.

그래서 `invalid` 는 **테두리 색만** 바꿉니다. 메시지를 어디에 어떻게 그릴지는 소비처의 몫입니다.

## ref 는 좁히지 않는다 [#ref-는-좁히지-않는다]

내부 `TextInput` 인스턴스가 그대로 나옵니다. 다음 칸으로 포커스를 넘기는 게 가장 흔한 경로입니다.

```tsx
const next = useRef<RNTextInput>(null)
<TextInput returnKeyType="next" onSubmitEditing={() => next.current?.focus()} />
```

`useImperativeHandle` 로 `focus` 만 열지 않은 이유는 공개 패키지라서입니다. 소비처가
`measure`·`isFocused` 중 무엇을 쓸지 아직 모르는데, **좁힌 핸들을 넓히는 것보다 넓은 걸
좁히는 쪽이 major** 입니다. 두 번째 소비처가 축을 말할 때 좁힙니다.

## 포커스 테두리는 로컬 상태다 [#포커스-테두리는-로컬-상태다]

RN 에는 `:focus` 가 없어 누군가 상태를 들어야 합니다. 그 상태가 필요한 곳이 이 컴포넌트
하나뿐이라 컨텍스트로 올리지 않았습니다. `onFocus`/`onBlur` 를 넘겨도 그대로 불립니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `invalid?` | `boolean` | — | 있으면 테두리를 danger 색으로. 메시지 렌더는 소비처의 몫. |

그 밖의 `ComponentPropsWithRef<typeof RNTextInput>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# ArticleCard (/docs/patterns/article-card)



```ts
import { ArticleCard } from '@coldsurfers/surf-ui/cards'
```

```tsx
import { ArticleCard } from '@coldsurfers/surf-ui/cards'

export default function Example() {
  return (
    <div
      style={{
        width: '100%',
        display: 'grid',
        gap: 20,
        gridTemplateColumns: 'repeat(auto-fit, minmax(170px, 1fr))',
      }}
    >
      <ArticleCard
        tone="forest"
        category="TAPE"
        title="여름의 리버브"
        excerpt="테이프 딜레이가 남긴 잔향만 모아 들었다."
        meta="7.15 · 24분"
      />
      <ArticleCard
        tone="plum"
        category="MIND"
        title="공연장에서 혼자 서 있기"
        excerpt="같이 갈 사람이 없어서 못 간 공연 목록."
        meta="7.11"
      />
    </div>
  )
}
```

`CoverBlock` 과 `Eyebrow` 를 안에서 조립합니다 — 소비처가 그 둘을 따로 import 하지 않습니다.

`thumbnailUrl` 이 없으면 tone 색면만 노출합니다. 없는 이미지를 회색 박스로 흉내 내지 않는 건
**데이터 정직성** 쪽 결정입니다 — 색면은 그 자체로 카드의 표지입니다.

폭은 소비처가 정합니다. 카드는 `width: 100%` 라 그리드 칸을 그대로 채웁니다.

## 클릭은 소비처가 감싼다 [#클릭은-소비처가-감싼다]

라우터를 물지 않습니다. `next/link` 든 `react-router` 든 카드 바깥에서 감쌉니다.

```tsx
<Link href={`/magazine/${post.slug}`}>
  <ArticleCard {...post} />
</Link>
```

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `tone` | `'forest' \| 'wine' \| 'navy' \| 'moss' \| 'steel' \| 'plum'` | — | — |
| `thumbnailUrl?` | `string` | — | 실제 썸네일 URL. 있으면 tone 색면 위에 채워 얹고, 없으면 색면만 노출(데이터 정직성). |
| `category` | `string` | — | 카테고리 eyebrow — `TAPE` · `MIND` · `DEV`. |
| `title` | `string` | — | — |
| `excerpt` | `string` | — | — |
| `meta` | `string` | — | `7.15 · 24분` · `7.11`. |

그 밖의 `HTMLAttributes<HTMLElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# ConcertCard (/docs/patterns/concert-card)



```ts
import { ConcertCard, ConcertCardSkeleton } from '@coldsurfers/surf-ui/cards'
```

```tsx
import { ConcertCard } from '@coldsurfers/surf-ui/cards'
import { Button } from '@coldsurfers/surf-ui/primitives'
import { sprinkles } from '@coldsurfers/surf-ui/sprinkles'

export default function Example() {
  return (
    <div
      style={{
        width: '100%',
        display: 'grid',
        gap: 20,
        gridTemplateColumns: 'repeat(auto-fit, minmax(170px, 1fr))',
      }}
    >
      <ConcertCard.Framed
        initial="ㅅ"
        matchLabel="96% 취향"
        title="Silica Gel"
        meta="롤링홀 · 서울 · 7.24 금"
        footer={
          // `footer` 는 슬롯이라 서식을 소비처가 준다 — 그 서식은 `sprinkles` 에서 온다.
          // 색을 `var(--surf-text-secondary)` 로 손으로 박으면 토큰이 바뀌는 날 이 자리가 안 따라온다.
          <p className={sprinkles({ margin: '0', marginTop: '1', color: 'textSecondary' })}>
            좋아한 아티스트와 같은 결
          </p>
        }
        coverAction={<Button size="sm">담기</Button>}
      />
      <ConcertCard.Bare
        initial="ㅁ"
        title="Mid-Air Thief"
        meta="7.26 일"
        footer={<p className={sprinkles({ margin: '0', color: 'textSecondary' })}>무신사 개러지</p>}
        reserveTitleLines
      />
      {/* 같은 섀시, 비율만 다르다. 공연 포스터는 세로로 인쇄되므로 칸이 세로로 설 수 있는
          자리에서는 `portrait` 이 위아래를 안 자른다 — 기본 `landscape` 와 나란히 두면
          잘리는 정도가 바로 보인다. */}
      <ConcertCard.Bare
        initial="ㅎ"
        coverRatio="portrait"
        title="HYUKOH"
        meta="8.15 금"
        footer={<p className={sprinkles({ margin: '0', color: 'textSecondary' })}>올림픽홀</p>}
        reserveTitleLines
      />
      {/* `initial` 도 `footer` 도 없다 — 이 섀시는 포스터가 없으면 note 면만 남기고,
          공연장 줄을 아무 데도 안 그린다. 평평한 `ConcertCardProps` 에서는 둘 다 통과했다. */}
      <ConcertCard.Cover eyebrow="INDIE ROCK" title="Parannoul" meta="7.30 수 · 무신사 개러지" />
      {/* 작은 칸은 문이 다르다. `size` 플래그가 아니라 문 이름이 크기를 말하고,
          `footer` 는 이쪽에만 있다. */}
      <ConcertCard.CoverCompact
        title="Oohyo"
        meta="8.02 토"
        footer="예스24 라이브홀"
        coverAction={<Button size="sm">담기</Button>}
      />
      {/* 위와 같은 그림, 더 큰 칸. 여러 열 그리드처럼 칸이 넓은 자리에서 세로 포스터가 덜 잘린다. */}
      <ConcertCard.CoverLarge
        title="Jambinai"
        meta="8.09 토"
        footer="무신사 개러지"
        coverAction={<Button size="sm">담기</Button>}
      />
    </div>
  )
}
```

도메인은 이름에만 남았습니다. props 는 `title` · `meta` · `initial` 이라 이 컴포넌트는 공연
스키마를 모릅니다 — 날짜 포맷도, 공연장 이름 조합도 소비처가 문자열로 만들어 줍니다.

커버는 **두 겹**입니다. 바닥은 `note` 면 위에 옅은 이니셜이고 언제나 카드가 그립니다. 그 위를
포스터가 덮는데, 카드가 채우면 `posterUrl` 이고 소비처가 채우면 `cover` 슬롯입니다. 덮을 게
없으면(포스터 부재 · 로드 실패) 바닥이 그대로 드러납니다.

바닥 색면에 `tone` 축이 &#x2A;*없습니다.** 예전엔 6톤을 id 로 흩었는데, 그 면이 뜻하는 건 「아직
그림이 없다」라서 `Skeleton`(API 대기)과 밝기가 갈리면 안 됩니다 — 둘 다 `note` 입니다.
색 다양성이 곧 편집인 자리(`ArticleCard` · `LeadFeature`)는 여전히 6톤을 씁니다.

## 섀시 세 벌 [#섀시-세-벌]

| 문                          | `variant`                  | 모양                                   | 쓰는 자리                       |
| -------------------------- | -------------------------- | ------------------------------------ | --------------------------- |
| `ConcertCard.Framed`       | `framed`(기본)               | 테두리 · 배경이 있는 액자                      | 목록 표면                       |
| `ConcertCard.Bare`         | `bare`                     | 섀시 없이 포스터 + 아래 3줄. 비율은 `coverRatio`  | 트렌딩 레일 · 담은 공연 그리드 · 목록 그리드 |
| `ConcertCard.Cover`        | `cover`                    | 세로 커버 한 장에 eyebrow · 제목을 얹고 아래 메타 1줄 | 날짜 피드                       |
| `ConcertCard.CoverCompact` | `cover` + `size="compact"` | 같은 커버, 날짜 · 제목 · 공연장 셋 다 커버 안        | 레일                          |
| `ConcertCard.CoverLarge`   | `cover` + `size="large"`   | `CoverCompact` 와 같은 그림, 더 큰 칸        | 여러 열 그리드                    |

**문은 다섯인데 섀시는 셋입니다.** 커버만 크기로 갈라 냈습니다 — 이유는 [아래](#커버만-문이-셋인-이유).

`framed` 전용 축(`matchLabel`) 과 `cover` 전용 축(`eyebrow` · `size`)이 갈리는 건 시안에 그
자리가 없어서입니다.

### 문은 둘, 하나는 관대하고 하나는 정확합니다 [#문은-둘-하나는-관대하고-하나는-정확합니다]

한 줄이 두 가지로 써집니다. 가리키는 컴포넌트가 같아서 렌더 결과도 같습니다.

```tsx
<ConcertCard variant="cover" initial="ㅍ" title="Parannoul" meta="7.30 수" />
<ConcertCard.Cover title="Parannoul" meta="7.30 수" />
```

`variant` 문은 &#x2A;*관대합니다.** 평평한 `ConcertCardProps` 가 세 섀시의 축을 합집합으로 들고
있어서 안 먹는 prop 이 타입을 통과합니다 — `cover` 에 `matchLabel` 을 주거나 `framed` 에
`size` 를 줘도 조용히 무시될 뿐입니다. 그중 `initial` 은 반대로 걸립니다. `cover` 섀시는 그
자모를 아무 데도 안 그리는데 타입상 **필수**라, 위 첫 줄처럼 쓰지도 않을 글자를 지어내야 합니다.

정적 프로퍼티 문은 &#x2A;*정확합니다.** 그 섀시가 그리는 것만 받고 나머지는 컴파일 에러입니다 —
`FramedConcertCardProps` · `BareConcertCardProps` · `CoverConcertCardProps` ·
`CoverCompactConcertCardProps` 가 각 문이 받는 것의 전부이고 자동완성도 그만큼만 제안합니다.
`ConcertCard.Cover` 에는 `initial` 자리도 `footer` 자리도 없습니다.

**둘은 공존합니다.** `variant` 문은 없어지지 않습니다 — 그 축은 native 레인이 같이 읽는
계약(`ConcertCardVariant`)이고, 문 이름을 바꾸면 발행된 패키지에서 major 입니다. 기존 코드는
그대로 두고, &#x2A;*새 코드는 정확한 쪽으로 옵니다.**

### 커버만 문이 셋인 이유 [#커버만-문이-셋인-이유]

`size` 는 크기 플래그처럼 생겼지만 **슬롯이 갈리는 축**입니다 — `full` 밖에서만 `footer` 가
그려지고, `meta` 가 커버 밖에서 안으로 옮겨 갑니다. 한 문에 플래그로 두면 `full` 쪽에서
`footer` 가 `initial` 과 똑같은 병에 걸립니다. **넘길 수 있는데 아무것도 안 그리는 prop** 이요.

크기를 문 이름에 박으면 그 병이 성립하지 않습니다. 플래그가 바깥에서 사라지기 때문입니다.

`CoverCompact` 와 `CoverLarge` 사이는 슬롯이 같아 **진짜 크기 축**입니다. 그런데도 문으로
나눈 건 커버 문만 플래그를 되받으면 규율이 반쪽이 되기 때문입니다 — 「커버는 문으로 고른다」
하나만 외우면 되게 둡니다.

```tsx
<ConcertCard.Cover footer="예스24 라이브홀" … />         // 컴파일 에러 — 이 섀시는 안 그린다
<ConcertCard.CoverCompact footer="예스24 라이브홀" … />  // 이쪽이 그린다
```

### `cover` 의 크기 축 [#cover-의-크기-축]

정적 프로퍼티 문에는 이 축이 **없습니다** — 크기가 문 이름에 박혀 있습니다. 아래 표는
`variant="cover"` 문이 쓰는 `size` prop 이고, 오른쪽 열이 그 짝인 문입니다.

| `size`     | 문                          | 높이        | 글이 서는 자리                                        |
| ---------- | -------------------------- | --------- | ----------------------------------------------- |
| `full`(기본) | `ConcertCard.Cover`        | 430 / 500 | 제목만 커버 위. 메타는 **커버 밖** 한 줄                      |
| `compact`  | `ConcertCard.CoverCompact` | 290 / 300 | 날짜(`meta`) → 제목 → 공연장(`footer`) **셋 다 커버 안** 하단 |
| `large`    | `ConcertCard.CoverLarge`   | 420 / 460 | `compact` 와 같다 (여백만 24)                         |

`compact` · `large` 는 스크림이 카드 전체 높이에 걸립니다. 받쳐줄 글이 세 줄이고 우상단 담기 버튼까지
얹히기 때문입니다. `full` 은 제목 한 줄만 받치면 되므로 하단에만 깝니다.

`footer` 는 `full` 에서만 안 그려집니다 — 커버 아래에 메타 한 줄만 두는 섀시이기 때문입니다.
`variant` 문에서는 그게 조용한 무시로 끝나고, `ConcertCard.Cover` 에서는 컴파일 에러입니다.

<Callout tone="info">
  높이 290 / 300 은 기본값이지 상한이 아닙니다. 더 큰 칸이 필요한 그리드는 축을 하나 더 여는
  대신 `className` 으로 덮습니다. 칸 크기는 그리드의 사정이지 카드의 축이 아닙니다.
</Callout>

`reserveTitleLines` 는 **그리드에서만** 켭니다. 카드가 가로로 줄지어 설 때 제목 줄 수가 다른
이웃끼리 날짜 · 공연장 줄이 어긋나기 때문입니다. 레일에서는 시안이 1줄 제목 기준이라 켜면 제목
아래 빈 줄이 생깁니다. `framed` 는 자체 `minHeight` 로 항상 예약하므로 이 prop 을 보지 않습니다.

### `bare` 의 커버 비율 축 [#bare-의-커버-비율-축]

`coverRatio` 는 `bare` 섀시만 봅니다 — `framed` · `cover` 는 자기 비율을 갖습니다.

| `coverRatio`    | 비율  | 포스터가 잘리는 정도 | 쓰는 자리       |
| --------------- | --- | ----------- | ----------- |
| `landscape`(기본) | 4:3 | 가장 많이       | 트렌딩 레일      |
| `square`        | 1:1 | 중간          | 폭이 좁은 레일    |
| `portrait`      | 3:4 | **안 잘린다**   | 여러 열 목록 그리드 |

공연 포스터는 세로로 인쇄됩니다. 가로 · 정사각 칸에 넣으면 `object-fit: cover` 가 위아래를
잘라 제목 줄이나 출연자 이름이 사라집니다 — 칸이 세로로 설 수 있는 자리라면 `portrait` 이
원본을 그대로 보여 줍니다.

임의 비율을 받지 않고 &#x2A;*축으로 가둡니다.** 커버는 카드 정체성이라 지면마다 다른 비율이
생기면 같은 카드로 안 보입니다. 값을 늘리기 전에 묻습니다 — 새 지면이 생겼나, 아니면 한
자리가 취향으로 다르고 싶은 건가.

## 슬롯 둘 [#슬롯-둘]

`footer` 는 meta 아래(매칭 근거 줄 등), `coverAction` 은 커버 위 담기 버튼 자리입니다. 자리와
정렬만 카드가 정하고 내용물은 소비처가 줍니다.

그래서 &#x2A;*서식도 소비처가 줍니다.** 위 예시의 `footer` 는 `sprinkles({ color: 'muted' })` 로
색을 읽습니다 — `var(--surf-text-secondary)` 를 인라인 `style` 에 손으로 박으면 토큰이 바뀌는 날 그 자리가
안 따라옵니다. 커버의 `compact`·`large` 만은 카드가 `coverVenue` 래퍼로 서식을 주는데, 그 비대칭은
아직 남아 있습니다.

<Callout tone="warning">
  카드 전체가 `Link` 안에 있으면 `coverAction` 의 버튼이 `preventDefault` 로 내비게이션을
  막아야 합니다. 카드는 클릭을 모릅니다.
</Callout>

## ConcertCardSkeleton [#concertcardskeleton]

```tsx
import { ConcertCard, ConcertCardSkeleton } from '@coldsurfers/surf-ui/cards'

export default function Example() {
  return (
    <div
      style={{
        width: '100%',
        display: 'grid',
        gap: 20,
        gridTemplateColumns: 'repeat(auto-fit, minmax(170px, 1fr))',
      }}
    >
      {/* 문 이름이 짝이다 — 스켈레톤과 실카드를 같은 이름으로 부르면 치수가 어긋날 자리가 없다. */}
      <ConcertCardSkeleton.Framed />
      <ConcertCard.Framed initial="ㅎ" title="HYUKOH" meta="예스24 라이브홀 · 8.2 토" />
      <ConcertCardSkeleton.CoverCompact />
      <ConcertCard.CoverCompact title="Oohyo" meta="8.02 토" footer="예스24 라이브홀" />
    </div>
  )
}
```

같은 섀시(라운드 · 테두리 · 커버 면)라 로드 전후에 지면이 튀지 않습니다. `CoverBlock` 을
재사용하므로 면이 실카드와 **정확히 같은 소스**에서 나옵니다.

면에 축이 없습니다 — 스켈레톤이 뜻하는 것도 「아직 그림이 없다」라 `Skeleton`(막대들)과 같은
`note` 입니다.

### 문 이름이 짝입니다 [#문-이름이-짝입니다]

실카드의 문 다섯과 **1:1** 입니다 — `ConcertCardSkeleton.Framed` · `.Bare` · `.Cover` ·
`.CoverCompact` · `.CoverLarge`. 같은 이름으로 부르면 섀시도 치수도 어긋날 자리가 없습니다.

```tsx
<ConcertCardSkeleton.CoverLarge />   // 로딩
<ConcertCard.CoverLarge … />         // 로드 완료 — 같은 420/460
```

플래그(`variant` · `size`)도 그대로 삽니다. 다만 그쪽은 짝을 **소비처가 기억해야** 합니다 —
카드만 `size="large"` 로 바꾸고 스켈레톤을 `framed` 에 두면 타입은 통과하고 화면이 로드
순간에 280 → 460 으로 튑니다. 새 코드는 문으로 오는 편이 낫습니다.

`reserveTitleLines` 와 `coverRatio` 는 `bare` 섀시만 봅니다 — 그래서 `ConcertCardSkeleton.Bare`
에만 열려 있습니다. &#x2A;*둘 다 실카드와 같은 값을 넘겨야 합니다.** 커버 비율이 어긋나면 같은 폭에서
높이가 크게 달라지는데(`landscape` 4:3 ↔ `portrait` 3:4 는 약 1.78배), 그러면 로드되는 순간
그리드가 통째로 밀립니다 — 이 컴포넌트가 막으려던 바로 그 점프입니다.

```tsx
<ConcertCardSkeleton.Bare coverRatio="portrait" reserveTitleLines />  // 로딩
<ConcertCard.Bare coverRatio="portrait" reserveTitleLines … />        // 로드 완료 — 같은 3:4
```

커버 스켈레톤은 치수를 옮겨 적지 않고 &#x2A;*실카드의 `coverCover` recipe 를 그대로 가리킵니다.**
실카드에 크기가 또 붙어도 자동으로 따라옵니다.

[`Skeleton`](/docs/components/skeleton) 과는 다른 물건입니다. 그쪽은 치수를 받는 **축**이고,
이쪽은 카드 모양에 고정된 **사본**입니다. 축으로 이 카드를 흉내 내려면 소비처가 커버 비율 ·
제목 줄 수 · 본문 간격을 다시 적어야 하고, 그 사본이 실카드와 어긋나는 순간을 아무도 못
잡습니다.

## Props [#props]

아래 표는 `variant` 문 — **세 섀시의 축을 합친 목록**입니다. 어느 섀시가 무엇을 보는지는
「섀시 세 벌」 이 말하고, 정적 프로퍼티로 들어가면 타입이 그만큼만 남깁니다.

| 문                          | props 타입                       | 합집합에서 빠지는 것                                                                       |
| -------------------------- | ------------------------------ | --------------------------------------------------------------------------------- |
| `ConcertCard.Framed`       | `FramedConcertCardProps`       | `eyebrow` · `size` · `coverRatio` · `reserveTitleLines`                           |
| `ConcertCard.Bare`         | `BareConcertCardProps`         | `matchLabel` · `eyebrow` · `size`                                                 |
| `ConcertCard.Cover`        | `CoverConcertCardProps`        | `initial` · `footer` · `size` · `matchLabel` · `coverRatio` · `reserveTitleLines` |
| `ConcertCard.CoverCompact` | `CoverCompactConcertCardProps` | `initial` · `size` · `matchLabel` · `coverRatio` · `reserveTitleLines`            |
| `ConcertCard.CoverLarge`   | `CoverLargeConcertCardProps`   | `initial` · `size` · `matchLabel` · `coverRatio` · `reserveTitleLines`            |

다섯 다 `cards` 진입점에서 함께 나갑니다. `CoverLargeConcertCardProps` 는 `CoverCompact` 쪽의
별칭입니다 — 둘이 받는 것이 글자 그대로 같고, 그래도 이름을 두는 건 문↔타입 짝을 깨지 않기
위해서입니다.

`CoverCompactConcertCardProps` 는 키 목록을 다시
적지 않고 `CoverConcertCardProps` 에 `footer` 를 얹은 것입니다 — 두 벌로 적으면 커버 축이
하나 늘 때 한쪽만 따라옵니다.

이름을 `ConcertCardBareProps` 로 못 둔 건 그 이름이 계약(`contract/concert-card.ts`)에서
*두 구현이 공유하는 props* 라는 다른 뜻으로 이미 쓰이고 있어서입니다 — 넷을 통째로 형용사
먼저로 뒀습니다.

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `cover?` | `ReactNode` | — | **포스터 층**을 소비처가 채운다 — 주면 `posterUrl` 대신 이게 선다. 커버는 두 겹이다. 바닥은 `note` 면 + 옅은 이니셜이고 **그건 언제나 카드가 그린다.** 이 슬롯은 그 위를 덮는 층이라, 여기서 아무것도 안 그리면(포스터 부재·로드 실패) 바닥이 그대로 드러난다. 그래서 `initial` 과 **같이** 준다 — 둘은 다른 층이라 겹치지 않는다. 여는 이유는 **상태**다. 로드 실패를 잡으려면 `useState` 가 필요한데 이 엔트리는 훅도 `'use client'` 도 없는 서버 안전 모듈이다 — 들기 시작하면 `cards` 가 통째로 클라이언트 전용이 되고, `primitives` 배럴이 `Toast` 로 겪은 RSC 사고를 그대로 반복한다. 그래서 자리만 카드가 정하고 내용물은 소비처가 준다(`coverAction` 과 같은 규율). ⚠️ 공유 계약(`ConcertCardBareProps`)이 아니라 **웹 props 에만** 있다. native 는 이 자리를 안 그리므로 공유로 올리면 「있는데 안 먹는 prop」이 하나 더 생긴다(`footer` 가 이미 앓은 병). |
| `matchLabel?` | `string` | — | 취향 매치 라벨 — `96% 취향`. 없으면 미노출. **`framed` 전용** (시안의 `bare` 엔 자리가 없다). |
| `eyebrow?` | `string` | — | 커버 좌상단 라벨 — 시안의 장르 자리(`INDIE ROCK`). 없으면 미노출. **`cover` 전용**. |
| `size?` | `'full' \| 'compact' \| 'large'` | — | 커버 카드의 크기. 기본 `full`. **`cover` 전용**. `full` — 세로 커버 한 장(430/500)에 eyebrow·담기·제목을 얹고, **메타는 커버 밖** 1줄. `compact` — 작은 칸(290/300)이라 셋을 다 커버 안에 넣는다: 날짜(`meta`) → 제목 → 공연장(`footer`). 스크림이 카드 전체 높이에 걸려 글이 포스터 위에서 읽힌다. `large` — `compact` 와 같은 그림, 더 큰 칸(420/460 · 여백 24). 여러 열 그리드용. ⚠️ `full` 에서만 `footer` 가 안 그려진다 — 커버 아래에 메타 한 줄만 두는 섀시라서다. 그 비대칭이 **이 문에만 남아 있다.** 정적 프로퍼티 문에는 이 축이 없다 — 크기가 문 이름 (`ConcertCard.Cover` · `.CoverCompact` · `.CoverLarge`)에 박혀 있고, `full` 쪽은 `footer` 를 타입에서 아예 안 연다. 여기 남긴 건 `variant` 문이 쓰던 축이라서다(빼면 major). |
| `variant?` | `'framed' \| 'bare' \| 'cover'` | — | `framed`(기본) — 테두리·배경 있는 액자 카드(`/live-events`·`/nearby`·`/gig-guide`). `bare` — 시안 dice.fm 리스킨(Figma `931:32`·`931:259`): 섀시 없이 4:3 포스터 블록 + 그 아래 3줄 텍스트. `/`(트렌딩 레일)·`/@<handle>`(담은 공연 그리드)이 쓴다. `cover` — 시안 날짜 피드 리스킨(Figma `1093:171`·`1093:576`): 세로 커버 한 장에 eyebrow·담기· 제목을 **얹고** 커버 아래엔 메타 1줄. `/live-events/new` 와 그 날짜 상세가 쓴다. 작은 칸(레일)은 같은 섀시의 `size="compact"`, 여러 열 그리드는 `size="large"` — 축은 `ConcertCardSize`. ⚠️ native 는 `bare` 만 구현한다 — 그래서 그쪽엔 이 prop 이 아예 없다. |

그 밖의 `ConcertCardBareProps, CardDomProps` 속성은 루트 엘리먼트로 그대로 통과한다.

### ConcertCardSkeleton [#concertcardskeleton-1]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `variant?` | `'framed' \| 'bare' \| 'cover'` | — | `ConcertCard` 의 같은 이름 prop 과 짝 — 섀시가 어긋나면 로드 전후가 튄다. |
| `size?` | `'full' \| 'compact' \| 'large'` | — | `ConcertCard` 의 같은 이름 prop 과 짝 — **`cover` 전용**. 어긋나면 높이가 튄다. |
| `reserveTitleLines?` | `boolean` | — | `ConcertCard` 의 같은 이름 prop 과 짝 — 제목 자리 높이를 실카드와 맞춘다. |
| `coverRatio?` | `'landscape' \| 'square' \| 'portrait'` | — | `ConcertCard` 의 같은 이름 prop 과 짝 — **`bare` 전용**. 어긋나면 커버 높이가 튄다. 실카드와 **같은 값을 넘겨야 한다.** `portrait`(3:4) 카드 자리에 기본값 `landscape`(4:3) 스켈레톤을 깔면 같은 폭에서 커버 높이가 약 1.78배 달라져, 로드되는 순간 그리드가 통째로 아래로 밀린다. |

그 밖의 `HTMLAttributes<HTMLDivElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# LeadFeature (/docs/patterns/lead-feature)



```ts
import { LeadFeature } from '@coldsurfers/surf-ui/cards'
```

```tsx
import { LeadFeature } from '@coldsurfers/surf-ui/cards'

export default function Example() {
  return (
    <div style={{ width: '100%', maxWidth: 720 }}>
      <LeadFeature
        tone="moss"
        eyebrow="THIS WEEK'S PICK"
        title="한여름의 소극장 투어"
        excerpt="에어컨이 약한 공연장 다섯 곳을 골랐다. 그래도 갔다."
        byline="tomwaters · 7월 3주"
        cta="읽기 →"
      />
    </div>
  )
}
```

시안의 `THIS WEEK'S PICK` 자리입니다. tablet 이상에서 커버와 텍스트가 2단으로 갈리고,
모바일에서는 세로로 쌓입니다.

`ArticleCard` 와 무엇이 다른가 — **지면에서의 자리**입니다. 아티클 카드는 목록의 한 칸이라
제목이 `<h3>` 이지만, 리드 피처는 그 목록 위에 한 장으로 서므로 `<h2>` 입니다. 같은 재료로
같은 크기의 카드를 두 개 만든 게 아닙니다.

`eyebrow` · `cta` 는 선택입니다. 없으면 그 줄 자체가 사라집니다 — 빈 자리를 남기지 않습니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `tone` | `'forest' \| 'wine' \| 'navy' \| 'moss' \| 'steel' \| 'plum'` | — | — |
| `thumbnailUrl?` | `string` | — | 실제 커버 URL. 있으면 tone 색면 위에 채워 얹고, 없으면 색면만 노출(데이터 정직성). |
| `eyebrow?` | `string` | — | 상단 eyebrow — `THIS WEEK'S PICK`. |
| `title` | `string` | — | — |
| `excerpt` | `string` | — | — |
| `byline` | `string` | — | `tomwaters · 7월 3주`. |
| `cta?` | `string` | — | 액션 라벨 — `읽기 →`. 없으면 미노출. |

그 밖의 `HTMLAttributes<HTMLElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Masonry (/docs/patterns/masonry)



```tsx
import { Masonry, PinCard, pinCardHeight } from '@coldsurfers/surf-ui/cards'
import { Button } from '@coldsurfers/surf-ui/primitives'
import { useState } from 'react'
import { type SamplePin, samplePins } from './pin-samples'

/** 다음 쪽 흉내 — 같은 핀을 새 키로 한 쪽 더. */
const pageOf = (page: number): SamplePin[] =>
  samplePins.map((pin) => ({ ...pin, id: `${pin.id}-${page}` }))

export default function Example() {
  const [pages, setPages] = useState(1)
  const items = Array.from({ length: pages }, (_, page) => pageOf(page)).flat()
  return (
    <div style={{ width: 360, display: 'grid', gap: 16 }}>
      <Masonry
        items={items}
        keyOf={(pin) => pin.id}
        heightOf={(pin) => pinCardHeight(pin.ratio ?? undefined, !!pin.meta)}
        renderItem={(pin) => (
          <PinCard poster={pin.poster ?? undefined} meta={pin.meta} fallback={pin.title}>
            <a href={`#${pin.id}`}>{pin.title}</a>
          </PinCard>
        )}
      />
      <Button variant="outline" onClick={() => setPages((n) => n + 1)}>
        다음 쪽 붙이기
      </Button>
    </div>
  )
}
```

항목을 가장 낮은 열에 차례로 놓습니다. 다음 쪽이 붙어도 이미 놓인 카드는 다른 열로 옮기지 않습니다 —
CSS `column-count` 와 다른 점입니다. 쪽은 따로 그리지 말고 이어 붙인 `items` 하나로 넘기세요 — 쪽 사이에 빈칸이 남지 않습니다.

높이는 그려진 칸이면 실측으로, 아직 안 그려진 칸만 `heightOf`(열 폭 = 1)로 칩니다. 핀 카드면 `pinCardHeight` 를 쓰고, 비율을 모르면 `undefined` 를 넘겨도 됩니다.

「다음 쪽 붙이기」를 눌러 보세요 — 새 칸은 아래에서 살짝 떠오르고, `PinCard` 포스터는 3:4 자리에서 받은 비율로 옮겨 갑니다. 동작 줄이기 설정이면 둘 다 바로 바뀝니다.

간격(열 12 · 줄 16)은 `MASONRY_SPEC` 이 정본이라 native 와 같습니다.

## native [#native]

RN 판은 [Native › Masonry · PinCard](/docs/native/masonry) — FlashList v2 위에 서고 높이를 재서 놓습니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `items` | `readonly T[]` | — | 쪽을 이어 붙인 전체 — 다음 쪽이 오면 뒤에 붙여 넘긴다. |
| `keyOf` | `(item: T) => string` | — | 항목의 고유 키 — 놓인 열 · 잰 높이를 기억하는 열쇠다. |
| `heightOf` | `(item: T) => number` | — | 열 폭 = 1 기준 높이 추정 — 아직 안 그려진 칸에만 쓴다. 핀 카드면 `pinCardHeight`. |
| `renderItem` | `(item: T) => ReactNode` | — | — |
| `columnCount?` | `number` | — | 기본 2. 바뀌면 처음부터 다시 놓는다. |


---

# MediaRow (/docs/patterns/media-row)



```ts
import { MediaRow } from '@coldsurfers/surf-ui/cards'
```

```tsx
import { MediaRow } from '@coldsurfers/surf-ui/cards'
import { StatPill } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div
      data-surface="ink"
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 8,
        width: '100%',
        maxWidth: 390,
        padding: 20,
        borderRadius: 24,
        background: 'var(--surf-bg-base)',
      }}
    >
      <MediaRow
        cover="모"
        kicker="토 10.10 · 12:00"
        title="모보 페스티벌"
        meta="파주 · 아시아출판문화정보센터"
        footer={
          <>
            88,000원
            <StatPill value="2TM" />
          </>
        }
        aside={
          <>
            <StatPill icon="🔥" value="31" tone="hot" />
            <StatPill icon="👁" value="80" />
          </>
        }
      />
      <MediaRow
        selected
        cover="인"
        kicker="일 10.11 · 14:00"
        title="인터스텔라 필름콘서트"
        meta="경희대 평화의전당"
        footer={
          <>
            69,000~원
            <StatPill value="놀유니버스 외 2" />
          </>
        }
        aside={<StatPill icon="👁" value="17" />}
      />
      <MediaRow
        dimmed
        cover="V"
        kicker="일 10.11 · 17:00"
        title="V.O.S 콘서트"
        meta="용인포은아트홀"
      />
    </div>
  )
}
```

[`PickRow`](/docs/patterns/pick-card) 에 썸네일을 더한 줄입니다(Figma `1028:331`). 시각 키커 · 제목 · 장소 · 아래 줄(`footer`) · 오른쪽 칸(`aside`)이 섭니다.

고른 줄은 `selected`, 고른 뒤 나머지는 `dimmed` 입니다. 포스터가 없으면 `cover`(보통 이니셜)가 색면 위에 섭니다.

줄을 눌러 시트를 열거나 이동하려면 `asChild` 로 `button` · 라우터 `Link` 를 넘깁니다 — **그 자식의 글이 제목**이 되고 나머지가 둘레에 그려집니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `title?` | `ReactNode` | — | `asChild` 면 비우고 자식 링크의 글로 준다. |
| `posterUrl?` | `string` | — | — |
| `cover?` | `ReactNode` | — | 포스터가 없을 때 색면 위 글자 — 보통 이니셜. |
| `kicker?` | `ReactNode` | — | 제목 위 Geist 키커 — `토 10.10 · 12:00`. |
| `meta?` | `ReactNode` | — | 제목 아래 — 장소. |
| `footer?` | `ReactNode` | — | 맨 아래 줄 — 가격 · 판매처 칩. |
| `aside?` | `ReactNode` | — | 오른쪽 칸 — 보통 `StatPill`. |
| `selected?` | `boolean` | — | — |
| `dimmed?` | `boolean` | — | — |
| `asChild?` | `boolean` | — | 자기 엘리먼트 대신 자식(`button` · 라우터 `Link`)에 줄을 입힌다. |

그 밖의 `Omit<HTMLAttributes<HTMLElement>, 'title'>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# PickCard (/docs/patterns/pick-card)



```ts
import { PickCard, PickRow } from '@coldsurfers/surf-ui/cards'
```

```tsx
import { PickCard, PickRow } from '@coldsurfers/surf-ui/cards'
import { RowAction } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  const card = (
    <PickCard
      title="오늘 저녁"
      kicker="TODAY · 10.01"
      footer={<a href="#pick-card">18건 모두 ›</a>}
      style={{ width: '100%', maxWidth: 420 }}
    >
      <PickRow
        time="19:30"
        title="까치산 단독공연"
        meta="웨스트브릿지"
        action={<RowAction>예매 ↗</RowAction>}
      />
      <PickRow
        time="20:00"
        title="인디 쇼케이스 「가을 밤」"
        meta="클럽 FF"
        action={<RowAction>예매 ↗</RowAction>}
      />
    </PickCard>
  )

  return (
    <>
      {card}
      <div
        data-surface="ink"
        style={{ padding: 16, borderRadius: 24, background: 'var(--surf-bg-base)' }}
      >
        {card}
      </div>
    </>
  )
}
```

홈의 `오늘 저녁` · `이번 주말` 자리입니다(Figma `821:92`). 패널 안에 머리 한 줄, 줄 낱장, 꼬리 한 줄이 섭니다.

색은 전부 역할 토큰이라 `data-surface="ink"` 안에 넣으면 잉크 면이 됩니다 — 위 두 번째 카드가 그 모습입니다.

머리 오른쪽(`aside`) · 줄 둘째 줄(`meta`) · 행동(`action`)은 슬롯입니다. 스웰 미터 · 스웰 태그 같은 앱 부품은
소비처가 넣습니다. 여러 장을 3단으로 놓는 그리드도 소비처 몫입니다.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `title` | `ReactNode` | — | 머리 한 줄 — `오늘 저녁`. |
| `kicker?` | `ReactNode` | — | 머리 아래 Geist 키커 — `TODAY · 10.01`. |
| `aside?` | `ReactNode` | — | 머리 오른쪽 슬롯 — 스웰 미터 같은 앱 부품. |
| `footer?` | `ReactNode` | — | 꼬리 한 줄 — `18건 모두 ›` 링크. |

그 밖의 `Omit<HTMLAttributes<HTMLElement>, 'title'>` 속성은 루트 엘리먼트로 그대로 통과한다.

### PickRow [#pickrow]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `time?` | `ReactNode` | — | 제목 앞 Geist 시각 — `19:30` · `토 18:00`. |
| `title` | `ReactNode` | — | — |
| `meta?` | `ReactNode` | — | 둘째 줄 — 장소 · 태그. |
| `action?` | `ReactNode` | — | 오른쪽 행동 — 보통 `RowAction`. |

그 밖의 `Omit<HTMLAttributes<HTMLDivElement>, 'title'>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# PinCard (/docs/patterns/pin-card)



```tsx
import { PinCard } from '@coldsurfers/surf-ui/cards'
import { IconButton } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div style={{ columnCount: 2, columnGap: 12, orphans: 1, widows: 1, width: 360 }}>
      <PinCard
        meta="ticketlink.co.kr"
        fallback="MOBO 인디 뮤직 페스티벌"
        action={
          <IconButton label="담기" variant="secondary" shape="pill" size="sm">
            ＋
          </IconButton>
        }
      >
        <a href="#pin">MOBO 인디 뮤직 페스티벌</a>
      </PinCard>
      <PinCard meta="성수동" fallback="팝업">
        제목만 있는 핀
      </PinCard>
    </div>
  )
}
```

시안 v3 `v3/PinCard`(Figma `1455:263`)입니다. 제목에 링크 하나를 넣으면 그 링크가 카드 전체를 덮고,
`action`(담기 ＋)만 그 위에 뜹니다. `action` 은 링크 밖 형제라 단추를 넣어도 됩니다.

포스터가 없으면 3:4 회색 자리에 `fallback` 을 그립니다. 여러 장은 [`Masonry`](./masonry) 로 놓습니다. RN 판은 `@coldsurfers/surf-ui/native/PinCard`.

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `poster?` | `string` | — | 포스터 주소. 없으면 3:4 회색 자리. |
| `fallback?` | `ReactNode` | — | 포스터가 없을 때 회색 자리 안 글자. |
| `meta?` | `ReactNode` | — | 출처 한 줄 — 도메인 · 장소. |
| `action?` | `ReactNode` | — | 포스터 오른쪽 아래 — 보통 담기 ＋. 링크 밖 형제라 단추를 넣어도 된다. |
| `children` | `ReactNode` | — | 제목. 링크 엘리먼트 하나면 그 링크가 카드 전체를 덮는다. |

그 밖의 `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# PosterThumb (/docs/patterns/poster-thumb)



```ts
import { PosterThumb } from '@coldsurfers/surf-ui/cards'
```

```tsx
import { PosterThumb } from '@coldsurfers/surf-ui/cards'
import { StatPill } from '@coldsurfers/surf-ui/primitives'

export default function Example() {
  return (
    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 120px)', gap: 10 }}>
      <PosterThumb cover="M" badge={<StatPill icon="🔥" value="31" tone="hot" />} />
      <PosterThumb cover="P" badge={<StatPill icon="🔥" value="12" tone="hot" />} />
      <PosterThumb cover="찰" />
    </div>
  )
}
```

3:4 · r12 포스터에 왼쪽 아래 배지 하나입니다(Figma `1028:217`). 폭을 채우므로 칸 폭은 소비처 그리드가 정합니다.

포스터가 없으면 `cover` 가 색면 위에 섭니다. 옆에 제목이 있으면 `alt` 는 비워 둡니다(기본).

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `posterUrl?` | `string` | — | — |
| `cover?` | `ReactNode` | — | — |
| `alt?` | `string` | — | 이미지 대체 글. 옆에 제목이 있으면 비운다(기본). |
| `badge?` | `ReactNode` | — | 왼쪽 아래 — 보통 `StatPill`. |

그 밖의 `HTMLAttributes<HTMLDivElement>` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# AppScreen (/docs/screens/app-screen)



```tsx
import { AppScreen, type AppScreenOffsetBottom } from '@coldsurfers/screens/AppScreen'
import { useScheme } from '@coldsurfers/surf-ui/native/scheme'
import { TabBar, useTabBarHeight } from '@coldsurfers/surf-ui/native/TabBar'
import { Text } from '@coldsurfers/surf-ui/native/Text'
import { House, Search, Tickets, UserRound } from 'lucide-react'
import { useState } from 'react'
import { Pressable, View } from 'react-native'

const TABS = [
  { key: 'feed', label: '피드', Icon: House },
  { key: 'events', label: '이벤트', Icon: Tickets },
  { key: 'search', label: '검색', Icon: Search },
  { key: 'my', label: '나의 창꼬', Icon: UserRound },
]

const OFFSETS: AppScreenOffsetBottom[] = ['tabBar', 'safeArea', 'none']

export default function Example() {
  const [offsetBottom, setOffsetBottom] = useState<AppScreenOffsetBottom>('tabBar')
  const scheme = useScheme()
  const tabBarHeight = useTabBarHeight()

  return (
    <View style={{ flex: 1 }}>
      <AppScreen offsetBottom={offsetBottom}>
        {/* 테두리가 곧 AppScreen 이 비운 자리의 경계다. */}
        <View
          style={{
            flex: 1,
            borderWidth: 1,
            borderColor: scheme.actionPrimary,
            backgroundColor: scheme.panelFill,
            gap: 8,
            padding: 12,
          }}
        >
          <Text textStyle="labelSm" tone="muted">
            offsetBottom = {offsetBottom} · useTabBarHeight() = {tabBarHeight}
          </Text>

          <View style={{ flexDirection: 'row', gap: 6 }}>
            {OFFSETS.map((candidate) => (
              <Pressable
                key={candidate}
                onPress={() => setOffsetBottom(candidate)}
                style={{
                  borderWidth: 1,
                  borderRadius: 8,
                  paddingHorizontal: 10,
                  paddingVertical: 6,
                  borderColor:
                    candidate === offsetBottom ? scheme.actionPrimary : scheme.lineDivider,
                  backgroundColor: candidate === offsetBottom ? scheme.statePressed : scheme.bgBase,
                }}
              >
                <Text textStyle="labelSm">{candidate}</Text>
              </Pressable>
            ))}
          </View>

          <View style={{ flex: 1, justifyContent: 'flex-end' }}>
            <Text textStyle="labelSm" tone="muted">
              콘텐츠 끝 — 이 선이 탭바에 닿으면 여백이 모자란 것이다
            </Text>
          </View>
        </View>
      </AppScreen>

      {/* 흐름 밖이라 자리를 안 비워 준다 — offsetBottom 이 있는 이유. */}
      <View style={{ position: 'absolute', left: 0, right: 0, bottom: 0 }}>
        <TabBar>
          {TABS.map(({ key, label, Icon }) => (
            <TabBar.Item
              key={key}
              label={label}
              active={key === 'feed'}
              renderIcon={({ color, size, strokeWidth }) => (
                <Icon color={color} size={size} strokeWidth={strokeWidth} aria-hidden />
              )}
            />
          ))}
        </TabBar>
      </View>
    </View>
  )
}
```

`offsetBottom` 을 `none` 으로 내려 보세요. 콘텐츠 테두리가 탭바 아래로 들어갑니다 — 이 컴포넌트가
존재하는 이유가 그 한 줄입니다.

## 무엇을 들고 무엇을 안 드는가 [#무엇을-들고-무엇을-안-드는가]

| 여기                                       | 여기가 아닌 곳                                 |
| ---------------------------------------- | ---------------------------------------- |
| 배경색 · safe-area 여백 · 탭바 여백 · Suspense 경계 | 헤더 → react-navigation `options.header`   |
|                                          | 에러 경계 → **소비처**                          |
|                                          | 탭바 자체 → [`TabBar`](/docs/native/tab-bar) |

**에러 경계를 안 드는 이유는 의존입니다.** react-query 경계를 넣으면 이 패키지가 react-query 를
물고, 데이터를 안 읽는 화면까지 그 의존을 집니다. 소비처가 바깥에서 감쌉니다.

## 여백을 두 축으로 가른다 [#여백을-두-축으로-가른다]

```tsx
<AppScreen offsetTop="safeArea" offsetBottom="tabBar">
  <MyList />
</AppScreen>
```

|                | 값                              | 무엇이 되는가                                     |
| -------------- | ------------------------------ | ------------------------------------------- |
| `offsetTop`    | `none` · `safeArea`            | `0` · `insets.top`                          |
| `offsetBottom` | `none` · `safeArea` · `tabBar` | `0` · `insets.bottom` · `useTabBarHeight()` |

`left` · `right` 는 받지 않습니다. 앞판 소비처 22곳에서 한 번도 안 썼습니다 — 있는데 안 먹는
prop 은 거짓말을 합니다.

### 왜 불리언 둘이 아니라 열거형인가 [#왜-불리언-둘이-아니라-열거형인가]

앞판은 `edges: Edges` 와 `withBottomTab: boolean` 을 따로 받았는데 &#x2A;*둘 다 하단을 건드렸습니다.**
조합 넷이 만드는 값이 이랬습니다.

| 앞판                                  | paddingBottom                  |
| ----------------------------------- | ------------------------------ |
| `edges=[]`, `withBottomTab`         | `tabBarHeight - insets.bottom` |
| `edges=['bottom']`, `withBottomTab` | `tabBarHeight`                 |
| `edges=['bottom']`                  | `insets.bottom`                |
| `edges=[]`                          | `0`                            |

`tabBarHeight - insets.bottom` 은 앞판이 탭바 높이를 **상수로 박아서** 생긴 보정식입니다.
[`useTabBarHeight()`](/docs/native/tab-bar) 는 인셋을 포함해 계산하므로 보정이 필요 없고,
넷이 세 값으로 접힙니다.

## 탭바는 `absolute` 로 얹힌다 [#탭바는-absolute-로-얹힌다]

화면이 자기 아래 여백을 직접 잡아야 하는 이유입니다. 탭바를 흐름 안에 넣으면 `offsetBottom` 이
할 일이 없습니다.

```tsx
<View style={{ flex: 1 }}>
  <AppScreen offsetBottom="tabBar">{children}</AppScreen>
  <View style={{ position: 'absolute', left: 0, right: 0, bottom: 0 }}>
    <TabBar>{/* … */}</TabBar>
  </View>
</View>
```

## Suspense [#suspense]

`fallback` 없이 쓰면 정중앙 design-system `Spinner` 가 섭니다.

<Callout type="warn" title="기본 fallback 은 svg 와 reanimated 를 전이로 뭅니다">
  `Spinner` 가 `react-native-svg` · `react-native-reanimated` 를 씁니다. native 레인을 쓰는
  소비처는 보통 이미 들고 있지만, 안 들고 싶으면 `fallback` 을 직접 넘기세요.
</Callout>

<Callout type="warn" title="위 미리보기의 여백은 실기기 여백이 아닙니다">
  브라우저에는 안전 영역이 없어 인셋이 전부 0 입니다. `safeArea` 두 값이 여기서는 `none` 과
  똑같이 보이고, `useTabBarHeight()` 도 `Platform.OS === 'web'` 이라 인셋을 안 탑니다.
  **실기기에서는 홈 인디케이터만큼 더 큽니다** — 자로 재서 시안과 맞추면 안 됩니다.

  스피너도 안 돕니다. 문서 사이트가 reanimated 를 얇은 대역으로 바꿔 두기 때문입니다.
</Callout>

## Props [#props]

| prop | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | — |
| `offsetTop?` | `'none' \| 'safeArea'` | — | 상단 여백. 기본 `'none'` — 헤더는 react-navigation 소관이라 화면 밖이다. |
| `offsetBottom?` | `'none' \| 'safeArea' \| 'tabBar'` | — | 하단 여백. 기본 `'tabBar'`. |
| `fallback?` | `ReactNode` | — | Suspense 폴백. 기본은 정중앙 DS `Spinner`. |

그 밖의 `ViewProps` 속성은 루트 엘리먼트로 그대로 통과한다.


---

# Getting Started (/docs/screens)



`@coldsurfers/screens` 는 **화면 한 장이 어떻게 조립되는가**를 드는 패키지입니다.
[design-system](/docs) 과 별개로 발행되고, 그 위에 얹힙니다.

```
design-system   무엇처럼 보이는가   토큰 · 프리미티브 · 단품
screens         어떻게 조립되는가   safe area · 탭바 여백 · 로딩 경계
```

판별은 한 줄입니다.

> **화면 전체의 배치를 정하면 여기, 그 안의 한 칸이면 design-system.**

그래서 [`TabBar`](/docs/native/tab-bar) 는 단품이라 design-system 에 남고, 그 탭바만큼 아래를
비우는 [`AppScreen`](/docs/screens/app-screen) 은 여기입니다.

## 왜 design-system 안이 아닌가 [#왜-design-system-안이-아닌가]

이 층이 자라면 &#x2A;*내비게이션 프레임워크를 뭅니다.** 화면 헤더는 react-navigation 의
`NativeStackHeaderProps` 를 받는 자리고, 그 축이 design-system 계약에 들어오면 웹 소비자까지
내비게이션 라이브러리를 지게 됩니다.

같은 이유로 `@seed-design/stackflow` 가 `@seed-design/react` 코어 밖에 있습니다. 갈린 기준은
"셸이냐 프리미티브냐" 가 아니라 **프레임워크 의존**입니다.

## 설치 [#설치]

```bash
pnpm add @coldsurfers/screens
```

peer 는 전부 **필수**입니다 — design-system 과 달리 이 패키지는 RN 전용이라 안 쓰는 레인이
없습니다.

| peer                                 | 왜                             |
| ------------------------------------ | ----------------------------- |
| `@coldsurfers/surf-ui`               | 색 · 타이포 · `useTabBarHeight()` |
| `react-native-safe-area-context`     | 인셋                            |
| `@emotion/native` · `@emotion/react` | 스타일 엔진                        |

<Callout type="warn" title="design-system 을 `dependencies` 로 넣지 마세요">
  사본이 둘이 되면 `useScheme()` 이 다른 컨텍스트를 읽습니다. 마이크로프론트엔드로 원격
  번들을 얹는 앱에서는 호스트가 노출한 **한 벌**을 써야 합니다.
</Callout>

## import 경로 [#import-경로]

배럴(`.`)과 표면별 진입점 둘 다 열려 있습니다.

```tsx
import { AppScreen } from '@coldsurfers/screens/AppScreen'
```

**진입점으로 여는 편이 낫습니다.** Metro 는 tree-shaking 을 하지 않아 배럴을 열면 이 패키지가
가진 것이 전부 딸려옵니다. 배럴을 남겨 둔 건 빼면 major 이기 때문입니다.