# 잼쿠봇 채팅 오버레이 커스텀 CSS 설명서 (LLM용)

이 문서는 사용자가 잼쿠봇 채팅 오버레이의 **커스텀 CSS**를 만들어 달라고 할 때 AI가 읽는 설명서다.
사람용 안내는 https://jamkubot.com/docs/features/chat-overlay/custom-css 에 있다.

## 0. 먼저 알아 둘 것

- 잼쿠봇 채팅 오버레이는 치지직 방송의 채팅·후원·구독을 OBS 브라우저 소스에 띄우는 웹 페이지다.
- 사용자는 대시보드 **위젯 · 미니게임 › 채팅 오버레이**에서 템플릿과 옵션(글꼴·색·테두리·장식·등장 효과 등)을 고르고,
  그 위에 **커스텀 CSS** 탭의 입력 칸에 CSS를 덧입힌다(설정은 모양·채팅 표시·후원·구독·TTS·커스텀 CSS 탭으로 나뉜다). 저장하면 OBS에 바로 반영되고, 오른쪽 미리보기는 저장 전에도 바로 바뀐다.
- 사용자가 만질 수 있는 것은 **CSS뿐**이다. HTML·JavaScript를 넣거나 요소를 추가할 수 없다.
  꾸밈 요소가 더 필요하면 `::before`·`::after`, `background-image`, 아래의 장식 요소(`.co-deco-a`·`.co-deco-b`)를 쓴다.
- CSS는 기본 스타일시트 **뒤에** `<style>` 하나로 붙는다. 같은 특이도면 커스텀 CSS가 이긴다.
- 길이는 **20,000자까지**다.

## 1. 답하는 방법

1. 사용자가 원하는 모양을 아직 말하지 않았으면 먼저 물어본다: 분위기(귀여움·깔끔함·게임풍 등), 주 색상, 말풍선 모양,
   닉네임 표시 방식, 후원·구독 카드 모양, 움직임(등장 효과), 지금 쓰는 템플릿.
2. **옵션으로 되는 것은 옵션을 먼저 안내한다.** 글꼴·글자 크기·줄간격·글자 색·외곽선·배경 색과 불투명도·테두리 두께와 색·
   장식 모양과 색·등장 효과·정렬·쌓이는 방향·닉네임 색은 대시보드 옵션이다(2장 표). CSS는 옵션으로 안 되는 모양에만 쓴다.
3. 가장 가까운 템플릿을 고르라고 권한 뒤 그 템플릿 위에 덧입히는 CSS를 만든다. 템플릿마다 그리는 방식이 다르므로(4장)
   템플릿을 모르면 물어보거나 `body[data-template="…"]` 로 범위를 좁혀 둔다.
4. 결과는 **```css 코드 블록 하나**로 준다. 주석은 한국어로 짧게 단다.
5. 끝에 붙여 넣는 곳을 알려 준다: 대시보드 › 위젯 · 미니게임 › 채팅 오버레이 › **커스텀 CSS** 탭의 입력 칸에 붙여 넣고 위쪽 **저장**.
   미리보기에서 먼저 확인하고, 마음에 안 들면 **되돌리기**로 저장 전 상태로 돌아갈 수 있다고 덧붙인다.
6. 사용자가 이미 커스텀 CSS를 갖고 있으면 그 CSS를 고친 **전체본**을 준다(덧붙일 조각만 주면 겹쳐서 헷갈린다).

## 2. 대시보드 옵션과 CSS 변수

옵션 값은 `:root` 의 CSS 변수로 들어온다. 색·크기를 CSS에 직접 박기보다 이 변수를 쓰면 사용자가 나중에 옵션으로 색을 바꿔도 따라간다.

| 옵션 | 변수 | 값 |
| --- | --- | --- |
| 글꼴 | `--co-font` | 글꼴 목록 중 하나 + 프리텐다드 폴백 |
| 글자 크기 | `--co-size` | px. `body` 의 `font-size`. 나머지 치수는 거의 em 이라 이 값에 비례한다 |
| 줄간격 | `--co-lh` | 숫자(1~2.5) |
| 글자 색 | `--co-text` | 색 |
| 외곽선 두께·색, 그림자 | `--co-stroke` | `text-shadow` 값(외곽선을 그림자 16개로 그린다) 또는 `none` |
| 배경 색 + 불투명도 | `--co-bg` | `rgba()` |
| 테두리 두께 | `--co-bw` | px |
| 테두리 색 | `--co-bc` | 색. `--co-bc-soft` 는 80% 불투명도 |
| 이모티콘 크기 | `--co-emoji` | em |
| 후원 강조 색 | `--co-don` | 색. `--co-don-text`(카드에서 읽히는 금액 글자색), `--co-don-tint`(카드 물들임 rgba) |
| 큰 후원 색 | `--co-don-big` | 색. `--co-don-big-text`, `--co-don-big-tint` |
| 구독 강조 색 | `--co-sub` | 색. `--co-sub-text`, `--co-sub-tint` |
| 장식 모양·색 | `--co-deco-img` | `url("data:image/svg+xml,…")` 또는 `none`. `--co-deco-soft` 는 장식 색 62% |
| 큰 후원 반짝이 | `--co-spark-img` | 큰 후원 색으로 그린 반짝이 그림 |
| (카드 색) | `--co-card-bg`·`--co-card-text`·`--co-card-sub` | 후원·구독 카드 면·글자·흐린 글자. 채팅 배경을 따라 정해진다 |

템플릿 CSS가 정하는 배치 변수(커스텀 CSS에서 `body { … }` 로 덮어써도 된다):
`--co-gap`(줄 사이 간격), `--co-pad`(말풍선 안쪽 여백), `--co-radius`(말풍선 모서리), `--co-card-radius`(카드 모서리),
`--co-card-ring`(카드 바깥 테두리 그림자), `--co-card-shadow`(카드 그림자).

움직임 방향 변수: `--co-dir`(아래에서 위로 쌓이면 1, 위에서 아래로면 -1), `--co-sx`(오른쪽 정렬이면 -1, 아니면 1),
`--co-ox`·`--co-oy`(변형 기준점).

줄마다 붙는 인라인 변수(`style` 속성): `--co-name`(그 줄 닉네임 색), `--co-name-on`(닉네임 색 면 위에 올릴 글자색, 흰색 또는 진한 회색),
`--co-delay`(장식 움직임 시작 지연, 음수 초). 인라인이라 덮어쓰려면 `!important` 가 필요하다.

카드마다 붙는 변수: `--co-accent`(후원·큰 후원·구독 강조 색), `--co-accent-text`(읽히는 강조 글자색), `--co-card-tint`(물들임 색).

그 밖의 옵션(변수 없이 동작): 뱃지 표시, 닉네임 표시, 닉네임을 윗줄에(`.co-nametop`), 닉네임 색(닉네임마다 다르게/한 가지 색),
스트리머·매니저 색 따로, 봇·명령어 채팅 표시, 이모티콘 그림/무시, 링크 가리기, 숨길 시청자, 최대 표시 개수, 사라지는 시간,
가장자리 흐리게, 후원·구독 표시, 큰 후원 기준 금액, TTS.

## 3. HTML 구조

```html
<html>
<body data-template="sticker" data-align="left" data-direction="up" data-anim="pop"
      data-shadow="1" data-edge="0" data-card="light" data-deco="1" data-deco-shape="heart" data-motion="1">
  <div id="co-list" class="co-list">          <!-- 화면 전체를 덮는 창. overflow:hidden, 오래된 줄은 위로 잘려 나간다 -->
    <div id="co-track" class="co-track">      <!-- 줄 묶음. 새 줄이 들어올 때 스크립트가 transform 으로 미끄러뜨린다 -->

      <!-- 채팅 한 줄 -->
      <div class="co-msg co-chat co-nametop co-has-head co-new" data-role="viewer" data-sub="1"
           style="--co-name:#ff6f9c; --co-name-on:#ffffff; --co-delay:-1.2s">
        <span class="co-head">
          <span class="co-badges"><img class="co-badge" src="…"></span>
          <span class="co-name">쿠키러버</span>
        </span>
        <span class="co-text">안녕하세요 <img class="co-emoji" src="…"></span>
        <i class="co-deco co-deco-a"></i><i class="co-deco co-deco-b"></i>
      </div>

      <!-- 후원 (큰 후원이면 co-big 과 반짝이 두 개가 붙는다) -->
      <div class="co-msg co-donation co-big">
        <div class="co-card">
          <div class="co-card-top">
            <svg class="co-ico">…</svg>
            <span class="co-name">후원천사</span>
            <span class="co-amount">50,000</span><span class="co-unit">치즈</span>
            <span class="co-kind">영상 후원</span>          <!-- 영상 후원일 때만 -->
          </div>
          <div class="co-text">맛있는 거 사 드세요!</div>   <!-- 메시지가 있을 때만 -->
        </div>
        <i class="co-deco co-deco-a"></i><i class="co-deco co-deco-b"></i>
        <i class="co-spark co-spark-a"></i><i class="co-spark co-spark-b"></i>
      </div>

      <!-- 구독 -->
      <div class="co-msg co-sub">
        <div class="co-card">
          <div class="co-card-top">
            <svg class="co-ico">…</svg>
            <span class="co-name">정기구독</span>
            <span class="co-meta">6개월 구독</span>
            <span class="co-kind">티어 1</span>
          </div>
        </div>
        <i class="co-deco co-deco-a"></i><i class="co-deco co-deco-b"></i>
      </div>

    </div>
  </div>
  <div id="co-notice"></div>  <!-- 연결 오류 안내. 꾸미지 않는다 -->
</body>
</html>
```

### 클래스

| 선택자 | 뜻 |
| --- | --- |
| `.co-msg` | 채팅·후원·구독 한 줄 전체. `position: relative` |
| `.co-chat` · `.co-donation` · `.co-sub` | 종류별 한 줄 |
| `.co-donation.co-big` | 큰 후원(사용자가 정한 금액 이상) |
| `.co-chat[data-role="streamer"]` · `[data-role="manager"]` · `[data-role="viewer"]` | 보낸 사람 역할 |
| `.co-chat[data-sub="1"]` | 구독자(구독 뱃지가 있음) |
| `.co-nametop` | '닉네임을 윗줄에' 옵션이 켜진 줄 |
| `.co-has-head` | 닉네임이나 뱃지가 있는 줄(닉네임 표시를 끄고 뱃지도 없으면 안 붙는다) |
| `.co-head` | 뱃지 + 닉네임 묶음. 기본은 인라인, `.co-nametop` 이면 블록 |
| `.co-badges` · `.co-badge` | 뱃지 묶음과 뱃지 그림(`img`) |
| `.co-name` | 닉네임. 기본 색은 `var(--co-name)` |
| `.co-text` | 채팅 내용(`white-space: pre-wrap`). 카드 안에서는 후원 메시지 |
| `.co-emoji` | 치지직 이모티콘 그림(`img`, 높이 `var(--co-emoji)`) |
| `.co-card` · `.co-card-top` | 후원·구독 카드와 첫 줄 |
| `.co-ico` | 카드 첫 줄의 치즈·별 아이콘(`svg`, `currentColor`) |
| `.co-amount` · `.co-unit` | 후원 금액(예: `2,000`)과 `치즈` |
| `.co-meta` | 구독 개월 수(예: `6개월 구독`) |
| `.co-kind` | 영상 후원 표시·구독 티어. 앞에 `· ` 를 `::before` 로 붙인다 |
| `.co-deco-a` · `.co-deco-b` | 모서리 장식 두 개(빈 `i` 요소, `position: absolute`, 배경이 `var(--co-deco-img)`) |
| `.co-spark-a` · `.co-spark-b` | 큰 후원 반짝이(빈 `i` 요소) |
| `.co-new` | 막 들어온 줄 — 등장 효과가 이 클래스에 걸려 있다 |
| `.co-out` | 사라지는 줄(사라지는 시간 옵션). 0.5초 뒤 지워진다 |
| `.co-list` · `.co-track` | 목록 창과 줄 묶음 |

### body 속성

| 속성 | 값 |
| --- | --- |
| `data-template` | 템플릿(4장) |
| `data-align` | `left` · `center` · `right` |
| `data-direction` | `up`(새 줄이 아래에 붙고 위로 밀림) · `down`(새 줄이 위에 붙음) |
| `data-anim` | 등장 효과 `none` · `fade` · `slide` · `pop` · `bounce` · `jelly` · `blur` · `swing` · `side` |
| `data-shadow` | 그림자 옵션 `0` · `1` |
| `data-edge` | 가장자리 흐리게 `0` · `1` |
| `data-card` | 카드 면이 밝으면 `light`, 어두우면 `dark` |
| `data-deco` | 장식 사용 `0` · `1` |
| `data-deco-shape` | 장식 모양 `none` · `sparkle`(반짝이) · `heart`(하트) · `star`(별) · `clover`(클로버) · `flower`(꽃) · `ribbon`(리본) · `cloud`(구름) · `paw`(발바닥) |
| `data-motion` | 살랑살랑 움직이기(장식·반짝이 계속 움직임) `0` · `1` |

## 4. 템플릿별 그리는 방식

같은 클래스라도 템플릿마다 그리는 방식이 다르다. 덮어쓸 때는 아래에서 그 템플릿이 쓰는 속성을 확인하고
`body[data-template="…"]` 를 붙여 같은 특이도 이상으로 쓴다.

| 키 | 이름 | 그리는 방식 |
| --- | --- | --- |
| `sticker` | 스티커 | `.co-chat` 에 `background: var(--co-bg)`, `border`, 흰 바깥 테 `box-shadow: 0 0 0 .15em #fff`. 모서리 1.15em. 윗줄 닉네임은 `.co-head` 가 닉네임 색 알약으로 위 테두리에 걸친다(`position: absolute`) |
| `jelly` | 젤리 | `.co-chat` 에 배경·테두리 + 안쪽 흰 테(`inset` 그림자). **`.co-chat::before` 를 광택 점으로 쓴다.** 모서리 1.5em. 닉네임 알약이 위 테두리에 걸친다 |
| `stitch` | 스티치 | `.co-chat` 에 배경·테두리 + 안쪽 바느질 점선(`outline: dashed` + 음수 `outline-offset`). 닉네임 알약은 말풍선 안 첫 줄 |
| `memo` | 메모지 | `.co-chat` 에 배경 + 줄 노트(`background-image` 1px 선) + 테두리. **`.co-chat::after`·`.co-card::after` 를 마스킹 테이프로 쓴다.** 윗줄 닉네임은 종이 위에 붙은 탭(`position: absolute; bottom: 100%`) |
| `window` | 미니 창 | `.co-chat` 에 배경·테두리 + 오른쪽 아래로 밀린 단색 그림자. 윗줄 닉네임이면 `.co-head` 가 제목줄(`display: flex`, 아래 테두리)이고 **`.co-head::after` 가 창 단추 점 세 개**, `.co-text` 가 본문(블록, 안쪽 여백) |
| `pixel` | 픽셀 | 모서리가 깎인 도트 테두리를 **`box-shadow` 네 방향**으로 그린다(`border` 없음, `margin: var(--co-bw)`). 모서리 0. 닉네임은 네모 알약 |
| `outline` | 외곽선 | 배경 없음. 글자에 `text-shadow: var(--co-stroke)` 외곽선. 장식은 `.co-deco-a` 하나가 채팅 끝에 인라인으로 붙는다 |
| `bubble` | 말풍선 | `.co-chat` 에 배경·테두리, 모서리 .85em |
| `tag` | 이름표 | `.co-chat` 이 세로 flex. `.co-head` 가 닉네임 색 알약, **`.co-text` 가 말풍선**(배경·테두리) |
| `band` | 띠 | 줄마다 화면 폭 전체를 채우는 반투명 띠(`.co-list` 안쪽 여백 0, 줄 간격 2px) |

꾸민 템플릿(앞의 6개)과 이름표에서 닉네임 알약 면은 `var(--co-name)`, 알약 글자는 `var(--co-name-on)` 이다.
후원·구독 카드(`.co-card`)는 그 템플릿 말풍선과 같은 테두리·모서리에 `var(--co-card-bg)` 면, `inset 0 0 0 100em var(--co-card-tint)` 로 강조색을 옅게 덮는다.

## 5. 움직임

- **등장 효과**는 `.co-msg.co-new` 에 `animation` 으로 걸려 있다(예: `body[data-anim="pop"] .co-msg.co-new { animation: co-in-pop .46s ease-out backwards; }`).
  직접 만든 등장 효과는 `body[data-anim] .co-msg.co-new { animation: 내이름 .5s ease-out backwards; }` 처럼 쓴다.
  **`fill-mode` 는 반드시 `backwards`** — `both`·`forwards` 면 끝난 뒤에도 값을 붙잡아 사라질 때(`.co-out`)의 전환이 안 먹는다.
  사용자가 대시보드 등장 효과를 '없음'으로 두면 `data-anim="none"` 이니, 그때도 쓰고 싶으면 `[data-anim]` 으로 고른다.
- **사라질 때**는 `.co-out` 에 `opacity: 0`(+ 효과별 `transform`·`filter`)과 `.co-msg` 의 `transition: opacity .5s, transform .5s, filter .5s` 로 사라진다.
  0.5초 뒤 요소가 지워지므로 그보다 긴 퇴장은 잘린다.
- 새 줄이 들어오면 스크립트가 **`.co-track` 의 `transform`·`transition` 을 직접 바꿔** 위 줄들을 미끄러뜨린다.
  `.co-track` 에 `transform`·`transition` 을 쓰지 않는다.
- 장식(`.co-deco`)·반짝이(`.co-spark`)의 계속 움직임은 `body[data-motion="1"]` 아래 `animation` 이고 시작 지연은 `var(--co-delay)` 다.
- 계속 도는 애니메이션은 `transform`·`opacity` 만 바꾼다. `filter`·`box-shadow` 를 계속 바꾸면 OBS 에서 무거워진다.

## 6. 반드시 지킬 것

- **OBS 브라우저 소스는 Chromium 103 이다.** 다음은 쓰지 않는다: `:has()`, CSS 중첩(`&`), `@container`·컨테이너 단위,
  개별 변형 속성 `translate`·`rotate`·`scale`(→ `transform` 을 쓴다), `color-mix()`, 상대 색 문법(`rgb(from …)`), `lh`·`rlh` 단위,
  `@scope`, `text-wrap: balance`, `:popover-open`, 뷰 전환. `@layer` 도 쓰지 않는다(레이어에 넣은 규칙은 기본 CSS 에 진다).
  써도 되는 것: `:is()`·`:where()`·`:not()`(여러 개), CSS 변수, `clamp()`·`min()`·`max()`, flex `gap`, `aspect-ratio`, `inset`, `@keyframes`, `mask-image`(`-webkit-` 접두어를 같이 쓴다).
- **배경은 투명해야 한다.** `html`·`body`·`.co-list`·`.co-track` 에 배경을 칠하지 않는다(방송 화면을 가린다).
- 클래스·구조는 바꿀 수 없다. 없는 요소를 전제로 쓰지 않는다.
- 템플릿이 이미 쓰는 가상 요소(젤리 `.co-chat::before`, 메모지 `.co-chat::after`·`.co-card::after`, 미니 창 `.co-head::after`)를
  덮으면 그 꾸밈이 바뀐다. 다른 템플릿에서는 `.co-chat::before`·`::after` 를 자유롭게 써도 된다(장식 요소는 `i` 라서 겹치지 않는다).
- 웹 글꼴은 `@import url("https://…");` 로 불러도 된다(https 만). `@import` 는 **커스텀 CSS 맨 위**에 둔다. 대시보드 글꼴 목록에 있으면 옵션이 낫다.
- 그림은 `https://` 주소나 `data:` URI 만 된다. 사용자의 이미지가 필요하면 https 로 공개된 주소를 받으라고 안내한다.
- `.co-msg` 를 `display: none` 으로 숨기면 TTS 는 여전히 읽는다. 채팅을 숨기는 것은 대시보드 필터 옵션(봇·명령어·숨길 시청자)으로 안내한다.
- `!important` 는 인라인 변수(`--co-name` 등)를 덮을 때나 꼭 필요할 때만 쓴다.
- 특이도 참고: 템플릿 규칙은 대부분 `body[data-template="x"] .co-chat`(0,2,1)이고 닉네임 알약은
  `:is(body[data-template="sticker"], …) .co-chat .co-head`(0,3,1) 다. `.co-deco` 기본 규칙은 (0,1,0)이지만 템플릿마다
  `body[data-template="x"] .co-deco-a`(0,2,1)로 위치·크기를 다시 정한다. 같거나 높은 특이도로 쓰면 뒤에 붙는 커스텀 CSS가 이긴다.
- 화면 크기는 OBS 소스 크기(보통 너비 400~500px, 높이 600~1000px)다. 줄은 `max-width: 100%` 이고 긴 글은 줄바꿈된다.

## 7. 예시

스트리머 채팅을 강조:

```css
/* 스트리머 채팅: 글자를 노랗게, 말풍선 테두리를 두껍게 */
.co-chat[data-role="streamer"] .co-text { color: #ffd43b; }
body[data-template="bubble"] .co-chat[data-role="streamer"] { border: 3px solid #ffd43b; }
```

말풍선(`bubble`)에 꼬리 달기:

```css
body[data-template="bubble"] .co-chat::after {
  content: "";
  position: absolute;
  left: 1em;
  bottom: -.32em;
  width: .7em;
  height: .7em;
  background: var(--co-bg);
  transform: rotate(45deg);
  border-radius: 0 0 .15em 0;
}
body[data-align="right"][data-template="bubble"] .co-chat::after { left: auto; right: 1em; }
```

닉네임 뒤에 쌍점, 이모티콘을 조금 크게:

```css
.co-chat:not(.co-nametop) .co-name::after { content: " :"; }
.co-emoji { height: 1.9em; }
```

웹 글꼴 쓰기(`@import` 는 맨 위에 둔다. 글꼴 파일 주소를 직접 쓸 때는 `@font-face`):

```css
@import url("https://fonts.googleapis.com/css2?family=Gaegu:wght@400;700&display=swap");
body { font-family: "Gaegu", var(--co-font); }
```

장식 자리에 내 그림 넣기(대시보드에서 장식 모양을 아무거나 켜 둔 상태에서):

```css
body[data-template] .co-deco-a { background-image: url("https://example.com/my-sticker.png"); --co-deco-size: 1.4em; }
body[data-template] .co-deco-b { display: none !important; }
```

직접 만든 등장 효과:

```css
@keyframes my-drop {
  0% { opacity: 0; transform: translateY(-.8em) rotate(-4deg); }
  60% { opacity: 1; transform: translateY(.1em) rotate(1deg); }
  100% { opacity: 1; transform: none; }
}
body[data-anim] .co-msg.co-new { animation: my-drop .55s ease-out backwards; }
```

후원 카드를 조금 크게, 금액을 더 크게:

```css
.co-donation .co-card { font-size: 1.1em; padding: .7em 1em; }
.co-donation .co-amount { font-size: 1.35em; }
```

## 8. 사용자에게 같이 알려 줄 것

- 붙여 넣는 곳: 대시보드 › 위젯 · 미니게임 › 채팅 오버레이 › **커스텀 CSS** 탭 → 위쪽 **저장**(단축키 Ctrl+S).
- 오른쪽 미리보기에서 예시 채팅이 계속 흘러가니 저장 전에 확인할 수 있다. **채팅 테스트**·**후원 테스트** 버튼은 OBS 화면에 예시를 띄운다(저장된 설정으로 그린다).
- 템플릿을 바꾸면 `body[data-template="…"]` 로 범위를 좁힌 규칙은 더 이상 맞지 않을 수 있다.
- 사람용 안내: https://jamkubot.com/docs/features/chat-overlay/custom-css