스타일링 - ThunderPhone

위젯은 기본 제공 라이트 및 다크 테마가 적용된 글래스모피즘 바 형태로 렌더링됩니다. 사용자 지정은 세 가지 수준에서 가능합니다. 일반 옵션에는 props를 사용하고, 테마에는 CSS 사용자 지정 속성을 사용하며, 완전한 제어에는 CSS 클래스 재정의를 사용합니다.

이러한 스타일링 옵션은 ThunderPhoneWidget React 컴포넌트와 ThunderPhone.mount() CDN 메서드로 렌더링되는 사전 구축 위젯에 적용됩니다. 완전히 사용자 지정된 UI가 필요하면 대신 헤드리스 훅을 사용합니다.

테마

theme prop은 위젯의 색상 구성을 제어합니다. 위젯 루트에 tp--light 또는 tp--dark 클래스를 적용합니다.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
/>

테마	클래스	설명
`'light'`	`tp--light`	어두운 텍스트가 있는 밝은 배경입니다. 기본값입니다.
`'dark'`	`tp--dark`	밝은 텍스트가 있는 어두운 배경입니다.

두 테마 모두 배경 흐림 효과와 은은한 투명도를 적용한 글래스모피즘 바 디자인을 사용합니다.

CSS 사용자 지정 속성

위젯은 개별 클래스를 수정하지 않고 색상을 변경할 수 있도록 재정의 가능한 CSS 사용자 지정 속성(변수)을 제공합니다. 이러한 속성은 .tp-widget 루트에 적용되는 테마 클래스(.tp--light 또는 .tp--dark)로 정의됩니다.

속성	기본값(라이트)	기본값(다크)	설명
`--tp-accent`	`#000`	`#fff`	강조 색상: 시작 버튼, 파형 막대, 연결 중 점, 연결됨 상태 텍스트입니다. `primaryColor` prop에서 인라인으로 설정됩니다.
`--tp-bg`	`rgba(255, 255, 255, 0.82)`	`rgba(15, 15, 15, 0.85)`	바 배경(반투명이며 `--tp-glass`로 흐리게 처리됨)입니다.
`--tp-surface`	`rgba(0, 0, 0, 0.04)`	`rgba(255, 255, 255, 0.07)`	음소거 버튼 배경입니다.
`--tp-surface-hover`	`rgba(0, 0, 0, 0.07)`	`rgba(255, 255, 255, 0.12)`	음소거 버튼 호버 배경입니다.
`--tp-border`	`rgba(0, 0, 0, 0.08)`	`rgba(255, 255, 255, 0.1)`	바 및 버튼 테두리입니다.
`--tp-border-hover`	`rgba(0, 0, 0, 0.14)`	`rgba(255, 255, 255, 0.18)`	호버 시 테두리 색상입니다.
`--tp-text`	`rgba(0, 0, 0, 0.88)`	`rgba(255, 255, 255, 0.95)`	기본 텍스트(제목, 에이전트 이름)입니다.
`--tp-text-2`	`rgba(0, 0, 0, 0.5)`	`rgba(255, 255, 255, 0.55)`	보조 텍스트(부제목, 상태 줄, 통화 타이머)입니다.
`--tp-glass`	`blur(32px) saturate(180%)`	`blur(32px) saturate(180%)`	바에 유리 효과를 만드는 `backdrop-filter`입니다.
`--tp-shadow`	3계층 그림자 스택	3계층 그림자 스택	바의 `box-shadow`(링 + 근거리 + 원거리 계층)입니다.
`--tp-shadow-hover`	3계층 그림자 스택	3계층 그림자 스택	호버 시 높이감을 위해 선언되었으며, 현재 어떤 규칙에도 적용되지 않습니다.
`--tp-glow`	`inset 0 1px 0 0 rgba(255,255,255,0.5)`	`inset 0 1px 0 0 rgba(255,255,255,0.06)`	바 그림자 위에 겹쳐지는 내부 상단 하이라이트입니다.
`--tp-connected`	`#059669`	`#34d399`	연결 상태 표시기 색상(상태 점)입니다.
`--tp-error`	`#dc2626`	`#fb7185`	오류 상태 텍스트 색상입니다.
`--tp-end-bg`	`rgba(239, 68, 68, 0.08)`	`rgba(251, 113, 133, 0.12)`	통화 종료 버튼 배경입니다.
`--tp-end-color`	`#ef4444`	`#fb7185`	통화 종료 버튼 아이콘 색상입니다.
`--tp-end-border`	`rgba(239, 68, 68, 0.12)`	`rgba(251, 113, 133, 0.15)`	통화 종료 버튼 테두리입니다.
`--tp-end-hover`	`rgba(239, 68, 68, 0.14)`	`rgba(251, 113, 133, 0.2)`	통화 종료 버튼 호버 배경입니다.
`--tp-idle-opacity`	`0.4`	`0.3`	유휴 상태 흐리게 표시를 위해 선언되었으며, 현재 어떤 규칙에도 적용되지 않습니다.

사용자 지정 속성 재정의

primaryColor prop을 통해 강조 색상을 설정합니다.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#e11d48"
/>

--tp-accent는 primaryColor prop에서 인라인 스타일로 설정되므로, --tp-accent의 스타일시트 재정의는 적용되지 않습니다. prop으로 강조 색상을 변경하십시오. 다른 모든 사용자 지정 속성은 CSS에서 재정의할 수 있습니다.

CSS로 다른 사용자 지정 속성을 재정의합니다. 스타일시트 순서와 관계없이 기본값을 정의하는 테마 클래스보다 규칙의 우선순위를 높이려면 두 클래스 선택자(.tp-widget.tp--light / .tp-widget.tp--dark)를 사용하십시오.

.tp-widget.tp--light {
  --tp-bg: rgba(0, 0, 0, 0.9);
  --tp-text: rgba(255, 255, 255, 0.95);
  --tp-text-2: rgba(255, 255, 255, 0.55);
  --tp-border: rgba(255, 255, 255, 0.15);
}

CSS 클래스

모든 위젯 클래스에는 기존 스타일과의 충돌을 방지하기 위해 tp- 접두사가 붙습니다.

클래스	요소	설명
`.tp-widget`	루트 래퍼	고정 위치 컨테이너입니다(`position: fixed`, `position` prop으로 설정한 모서리, `z-index: 9999`). 테마 클래스와 기본 글꼴 설정을 포함하며, 자체적인 시각적 장식은 없습니다.
`.tp--light` / `.tp--dark`	테마 수정자	테마와 함께 `.tp-widget`에 적용되며, 모든 `--tp-*` 사용자 정의 속성을 정의합니다.
`.tp-bar`	바	글래스모피즘 필 자체입니다. 배경, 배경 흐림, 테두리, `99px` 반경 및 그림자를 포함합니다. 너비는 `300px`입니다.
`.tp-meta`	텍스트 블록	모든 텍스트를 담는 컨테이너입니다 — 대기 중에는 제목과 부제목, 통화 중에는 에이전트 이름과 상태를 표시합니다.
`.tp-name`	기본 레이블	대기 중에는 `title` prop을 표시하고, 통화 중에는 연결된 에이전트의 이름을 표시합니다(`title`로 대체 가능).
`.tp-sub`	부제목	대기 중에 표시되는 “현재 이용 가능” 문구입니다.
`.tp-start`	대기 중 통화 버튼	원형 강조 시작 버튼(42px)입니다. 배경으로 `--tp-accent`를 사용합니다.
`.tp-dot`	연결 점	연결 중에 바 왼쪽에 표시되는 맥동 강조 점입니다.
`.tp-wave` / `.tp-wave--idle`	파형	5개 막대로 구성된 파형입니다. `--idle`은 느린 호흡 애니메이션을 추가하며, 통화 중에는 막대가 오디오에 반응합니다.
`.tp-button`	통화 중 버튼	통화 중 제어 버튼의 기본 스타일입니다(42px, 12px 둥근 모서리).
`.tp-button-group`	버튼 행	통화 중 음소거 및 통화 종료 버튼을 감쌉니다.
`.tp-button--start`	연결 버튼 변형	통화가 시작되는 동안 표시되는 강조 색상 변형입니다.
`.tp-button--mute`	음소거 전환	통화 중 마이크를 음소거하거나 음소거 해제합니다. `--tp-surface`를 사용합니다.
`.tp-button--end`	통화 종료 버튼	전화를 끊습니다. `--tp-end-*` 팔레트를 사용합니다.
`.tp-button--loading`	로딩 수정자	연결 중 버튼을 흐리게 표시합니다.
`.tp-icon` / `.tp-spin`	아이콘	버튼 아이콘 크기를 지정하며, `tp-spin`은 연결 스피너에 애니메이션을 적용합니다.
`.tp-status`	통화 중 상태 블록	연결 중/연결됨/오류 상태에서 상태 줄을 감쌉니다.
`.tp-status__text`	상태 줄	연결 상태 텍스트(예: “연결 중…”) 또는 통화 타이머입니다. 상태에 따라 `.tp-status--connected`(강조 색상) 또는 `.tp-status--error`(오류 색상)를 적용합니다.
`.tp-status__name`	에이전트 이름 슬롯	상태 블록의 일부이지만 현재 바 레이아웃에서는 렌더링되지 않습니다 — 대신 에이전트 이름은 `.tp-name`에 표시됩니다.
`.tp-status__dot`	상태 점	맥동하는 연결 상태 점 스타일입니다(`--tp-connected` 사용).

예시

Props를 통한 사용자 지정 강조 색상

위젯에 브랜드를 적용하는 가장 간단한 방법입니다.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="light"
  primaryColor="#059669"
  title="Talk to support"
/>

CSS를 통한 사용자 지정 색상

전체 색상을 제어하려면 사용자 지정 속성을 재정의합니다. 강조 색상은 CSS가 아니라 primaryColor prop에서 가져온다는 점을 기억하세요.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#059669"
/>

/* Emerald theme for everything else */
.tp-widget.tp--light {
  --tp-bg: rgba(236, 253, 245, 0.85);
  --tp-text: rgba(6, 78, 59, 0.95);
  --tp-text-2: rgba(4, 120, 87, 0.8);
  --tp-border: rgba(5, 150, 105, 0.2);
}

사용자 지정 크기

바, 버튼, 텍스트 크기를 조정하여 위젯을 더 크거나 작게 만듭니다.

/* Wider bar */
.tp-bar {
  width: 340px;
}

/* Larger buttons (42px by default) */
.tp-start,
.tp-button {
  width: 56px;
  height: 56px;
}

/* Larger text */
.tp-name {
  font-size: 16px;
}

.tp-sub,
.tp-status__text {
  font-size: 14px;
}

텍스트 레이블 숨기기

위젯의 모든 텍스트는 .tp-meta에 있습니다. 파형과 버튼만 남기려면 전체를 숨깁니다.

.tp-meta {
  display: none;
}

또는 개별 요소를 숨길 수 있습니다.

/* Hide only the idle "Available now" subtitle */
.tp-sub {
  display: none;
}

/* Hide only the in-call status line (connection state / timer) */
.tp-status {
  display: none;
}

유휴 레이블은 .tp-status가 아니라 .tp-name/.tp-sub에 있습니다. .tp-status만 숨겨도 위젯이 유휴 상태일 때 제목은 계속 표시됩니다.

테마별 재정의

테마 클래스를 사용하여 특정 테마를 대상으로 지정합니다.

/* Only affect dark theme */
.tp--dark .tp-start {
  box-shadow: 0 0 20px rgba(255, 255, 255, 0.25);
}

/* Only affect light theme */
.tp-widget.tp--light {
  --tp-bg: rgba(255, 255, 255, 0.95);
}

className을 사용한 범위 지정

React 컴포넌트를 사용할 때 className prop을 전달하여 특정 위젯 인스턴스에 재정의 범위를 지정합니다.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  className="support-widget"
/>

그런 다음 CSS에서 해당 클래스를 대상으로 지정합니다.

.support-widget.tp--dark {
  --tp-bg: rgba(30, 30, 46, 0.9);
}

.support-widget .tp-name {
  font-weight: 700;
}

이렇게 하면 동일한 페이지에서 서로 다른 스타일의 위젯 인스턴스를 여러 개 사용할 수 있습니다. 각 인스턴스의 primaryColor prop을 통해 고유한 강조 색상을 지정합니다(CSS는 --tp-accent를 재정의할 수 없습니다. 인라인으로 설정되기 때문입니다).

완전히 사용자 지정된 UI

CSS 재정의만으로 충분하지 않다면 헤드리스 훅을 사용하여 완전히 제어할 수 있습니다. 모든 HTML과 스타일링은 직접 제공하고, useThunderPhone이 음성 세션을 처리합니다. 이 훅은 파형과 같은 오디오 반응형 시각화를 구축할 수 있도록 audioLevelRef도 제공합니다.

import { useThunderPhone } from '@thunderphone/widget'

function MyWidget() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  return (
    <div className="my-totally-custom-widget">
      {/* Your own buttons, animations, layouts -- anything */}
      <button onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}>
        {phone.state === 'connected' ? 'Hang up' : 'Call us'}
      </button>
      {phone.audio}
    </div>
  )
}

오디오 반응형 애니메이션, 사용자 지정 레이아웃 또는 기존 컴포넌트 라이브러리와의 통합이 필요한 경우 헤드리스 훅이 적합합니다. 빠른 테마 조정에는 CSS 재정의와 사용자 지정 속성이 더 적합합니다.

​테마

​CSS 사용자 지정 속성

​사용자 지정 속성 재정의

​CSS 클래스

​예시

​Props를 통한 사용자 지정 강조 색상

​CSS를 통한 사용자 지정 색상

​사용자 지정 크기

​텍스트 레이블 숨기기

​테마별 재정의

​className을 사용한 범위 지정

​완전히 사용자 지정된 UI

테마

CSS 사용자 지정 속성

사용자 지정 속성 재정의

CSS 클래스

예시

Props를 통한 사용자 지정 강조 색상

CSS를 통한 사용자 지정 색상

사용자 지정 크기

텍스트 레이블 숨기기

테마별 재정의

className을 사용한 범위 지정

완전히 사용자 지정된 UI