테마 | Surflane

원칙

data-theme으로 테마를 고르세요. 속성이 없으면 시스템 설정을 따르고, <html>에 light나 dark를 두면 그 테마로 고정됩니다.
첫 화면을 그리기 전에 테마를 정하세요. 저장한 선택을 쿠키처럼 서버에서 읽어야 다른 테마가 잠깐 비치지 않습니다.
범위 테마는 미리보기에만 쓰세요. data-theme 아래에서 토큰이 모두 다시 해석되므로, 끼워 넣은 미리보기에는 맞지만 한 페이지에 테마를 둘 두는 데는 맞지 않습니다.
색상과 채도만 바꾸고 밝기는 두세요. 빌더는 단계마다 밝기를 지키므로 글자 대비가 기본 팔레트와 거의 같고, 결과는 대비 보고서에 나옵니다.
상태색은 그대로 두세요. 강조색 테마는 주요 작업, 체크된 컨트롤, 진행, 포커스의 색을 바꾸지만, 성공, 위험, 주의는 제 의미를 지킵니다.

테마 선택

data-theme은 <html>에 두거나, 아무 요소에 두어 그 아래에만 테마를 적용하세요. 값은 light 또는 dark입니다.

<html data-theme="light">
  <body>
    <!-- A dark preview inside the light page -->
    <section data-theme="dark">…</section>
  </body>
</html>

전환 애니메이션은 모션에서 다룹니다. 선택을 저장하는 일은 앱이 맡습니다.

shadcn/ui

shadcn.css는 --background, --primary, --radius 같은 shadcn/ui 변수를 Surflane 토큰에 연결합니다. 그러면 shadcn 컴포넌트가 범위 영역을 포함한 모든 테마를 따릅니다.

@import 'tailwindcss';
@import '@surflane/design-tokens/tokens.css' layer(components);
@import '@surflane/design-tokens/themes/slate.css' layer(components);
@import '@surflane/design-tokens/themes/accent-cyan.css' layer(components);
@import '@surflane/design-tokens/themes/radius-default.css' layer(components);
@import '@surflane/design-tokens/shadcn.css' layer(components);
@import '@surflane/design-tokens/tailwind.css';

/* In your shadcn CSS, keep @theme inline. Delete the :root and .dark
   color blocks and the @custom-variant dark line. */

테마 빌더

중립색 톤, 강조색, 모서리 크기를 고르세요. 미리보기, 대비 보고서, 아래 CSS가 고른 값을 따릅니다.

중립색

배경, 선, 텍스트의 모든 회색에 톤을 입힙니다. 단계마다 밝기는 고정됩니다.

중립색 색상

248°

톤 강도

1.0×

강조색

기본 버튼과 체크된 컨트롤을 채우고, 진행을 표시하고, 포커스 링과 호버한 링크에 색을 입힙니다. 성공 상태는 자기 색을 유지합니다.

강조색 색상

210°

강조색 채도

0.120

모서리

모든 모서리 토큰의 크기를 조정합니다. 버튼, 배지, 스위치는 가장 큰 컨트롤 높이의 절반을 모서리로 써서 알약 모양이 되고, 작게 줄이면 큰 것부터 모서리가 드러납니다.

Acme Platformplatform-core

검토가 필요한 배포 2개

다음 릴리스 시간 전에 승인하세요.

프로덕션으로 자동 승격담당자에게 알림

서비스	환경	소요 시간 (초)	상태
checkout-api	production	184	운영 중
search-indexer	staging	412	검토 필요
report-builder	development	96	실패

대비 보고서

두 테마의 글자 조합을 글자 최소 기준 4.5:1로 잽니다.

현재 테마의 텍스트 조합 대비
조합	다크	라이트	상태
시트 위 본문 `--surf-ink-body / --surf-canvas`	11.35:1	14.65:1	통과
시트 위 보조 텍스트 `--surf-ink-muted / --surf-canvas`	8.31:1	10.05:1	통과
크롬 위 제목 `--surf-ink / --surf-chrome`	15.57:1	15.57:1	통과
들어간 면 위 보조 텍스트 `--surf-ink-muted / --surf-surface`	9.40:1	9.44:1	통과
강조색 위 텍스트 `--surf-on-brand / --surf-brand`	9.87:1	9.87:1	통과
시트 위 포커스와 호버한 링크 `--surf-brand-ink / --surf-canvas`	8.73:1	16.58:1	통과

CSS

토큰과 함께 불러오세요. surflane.themes 레이어에 있어 불러오는 순서와 상관없고, 범위 data-theme 영역도 그대로 동작합니다.

/* Surflane theme: slate, accent cyan, radius default */
@layer surflane.tokens, surflane.themes, surflane.base, surflane.components, surflane.sizes;
@layer surflane.themes {
  :root,
  [data-theme='dark'],
  [data-theme='light'] {
    --surf-radius-sm: 6px;
    --surf-radius-md: 10px;
    --surf-radius-lg: 16px;
    --surf-radius-sheet: 20px;
    --surf-control-radius: 8px;
    --surf-radius-pill: 22px;
  }
  :root,
  [data-theme='dark'] {
    --surf-chrome: oklch(0.2368845 0.00973297 248.23792711);
    --surf-canvas: oklch(0.27850211 0.01320057 253.03643104);
    --surf-surface: oklch(0.2368845 0.00973297 248.23792711);
    --surf-code-bg: oklch(0.2050126 0.00860311 247.9381172);
    --surf-hover: oklch(0.31355761 0.01463569 251.36854651);
    --surf-selected: oklch(0.37866351 0.01730498 248.2836448);
    --surf-line: oklch(0.37866351 0.01730498 248.2836448);
    --surf-ink-muted: oklch(0.81668066 0.0183769 253.3626611);
    --surf-ink-body: oklch(0.91321146 0.017061 242.44074644);
    --surf-ink: oklch(0.9781762 0.0034179 247.8580546);
    --surf-on-brand: oklch(0.2368845 0.00973297 248.23792711);
    --surf-grid-minor: oklch(0.2368845 0.00973297 248.23792711);
    --surf-grid-major: oklch(0.37866351 0.01730498 248.2836448);
    --surf-guide: oklch(0.37866351 0.01730498 248.2836448);
    --surf-brand: oklch(0.82 0.12 210);
    --surf-brand-tint: oklch(0.82 0.12 210 / 0.25098039);
    --surf-brand-ink: oklch(0.82 0.12 210);
  }
  :root[data-theme='light'],
  [data-theme='light'] {
    --surf-chrome: oklch(0.9781762 0.0034179 247.8580546);
    --surf-canvas: oklch(1 0 0);
    --surf-surface: oklch(0.9781762 0.0034179 247.8580546);
    --surf-code-bg: oklch(0.95972296 0.00515149 247.87778139);
    --surf-hover: oklch(0.95972296 0.00515149 247.87778139);
    --surf-selected: oklch(0.93531009 0.01353396 240.96010253);
    --surf-line: oklch(0.93531009 0.01353396 240.96010253);
    --surf-ink-muted: oklch(0.37866351 0.01730498 248.2836448);
    --surf-ink-body: oklch(0.27850211 0.01320057 253.03643104);
    --surf-ink: oklch(0.2368845 0.00973297 248.23792711);
    --surf-brand-ink: oklch(0.2368845 0.00973297 248.23792711);
    --surf-on-brand: oklch(0.2368845 0.00973297 248.23792711);
    --surf-grid-minor: oklch(0.95972296 0.00515149 247.87778139);
    --surf-grid-major: oklch(0.93531009 0.01353396 240.96010253);
    --surf-guide: oklch(0.91321146 0.017061 242.44074644);
    --surf-brand: oklch(0.82 0.12 210);
    --surf-brand-tint: oklch(0.82 0.12 210 / 0.30196078);
  }
  @media (prefers-color-scheme: light) {
    :root:not([data-theme='dark']):not([data-theme='light']) {
      --surf-chrome: oklch(0.9781762 0.0034179 247.8580546);
      --surf-canvas: oklch(1 0 0);
      --surf-surface: oklch(0.9781762 0.0034179 247.8580546);
      --surf-code-bg: oklch(0.95972296 0.00515149 247.87778139);
      --surf-hover: oklch(0.95972296 0.00515149 247.87778139);
      --surf-selected: oklch(0.93531009 0.01353396 240.96010253);
      --surf-line: oklch(0.93531009 0.01353396 240.96010253);
      --surf-ink-muted: oklch(0.37866351 0.01730498 248.2836448);
      --surf-ink-body: oklch(0.27850211 0.01320057 253.03643104);
      --surf-ink: oklch(0.2368845 0.00973297 248.23792711);
      --surf-brand-ink: oklch(0.2368845 0.00973297 248.23792711);
      --surf-on-brand: oklch(0.2368845 0.00973297 248.23792711);
      --surf-grid-minor: oklch(0.95972296 0.00515149 247.87778139);
      --surf-grid-major: oklch(0.93531009 0.01353396 240.96010253);
      --surf-guide: oklch(0.91321146 0.017061 242.44074644);
      --surf-brand: oklch(0.82 0.12 210);
      --surf-brand-tint: oklch(0.82 0.12 210 / 0.30196078);
    }
  }
}

프리셋 파일

프리셋마다 파일이 있습니다. 토큰과 함께 중립색, 강조색, 모서리 파일을 골라 불러오세요.

@import '@surflane/design-tokens/tokens.css';
@import '@surflane/design-tokens/themes/slate.css';
@import '@surflane/design-tokens/themes/accent-cyan.css';
@import '@surflane/design-tokens/themes/radius-default.css';

코드로 만드는 테마

createTheme은 직접 정한 입력으로 같은 값을 돌려주고, themeCss는 그 값을 CSS로 바꿉니다.

import { createTheme, themeCss } from '@surflane/design-tokens/theme-builder'

const theme = createTheme({
  neutral: { hue: 248, chroma: 1 },
  accent: { hue: 210, chroma: 0.12 },
  radius: 1,
})
const css = themeCss(theme)

원칙