테마 커스터마이징

@lh-ui/react의 디자인 토큰은 모두 @lh-ui/share/theme에서 오며, 이 라이브러리는 토큰 사본을 갖지 않습니다. 테마 커스터마이징은 결국 이 CSS 커스텀 프로퍼티들을 덮어쓰는 것입니다.

토큰 계층

스타일 우선순위가 낮은 것부터:

theme.css — @lh-ui/share가 배포하는 기본 토큰(--lh-primary-color 등)
theme-dark.css — 다크 변수(theme.css와 상호 배타적, 둘 중 하나 선택)
LhConfigProvider의 themeVars — 감싼 요소에 매달리는 캐스케이드 변수
컴포넌트 themeVars 프로퍼티 — 컴포넌트 루트 요소에 매달려 모든 상위를 덮어씀

ConfigProvider로 커스터마이징

가장 권장하는 방식: 앱 루트에서 themeVars를 전달하며, 키 이름에 --lh- 접두사를 붙이지 않습니다 (내부에서 자동으로 붙음):

import { LhConfigProvider } from '@lh-ui/react'

export default function App() {
  return (
    <LhConfigProvider
      themeVars={{
        'primary-color': '#722ed1',
        'bg-color': '#faf9f7',
        'border-radius-base': '6px',
      }}
    >
      <YourApp />
    </LhConfigProvider>
  )
}

변수는 감싼 요소의 style="--lh-primary-color: #722ed1; ..."로 렌더링되어 아래로 캐스케이드됩니다.

사용 가능 토큰

키	설명
`primary-color`	주색
`gold-color` / `vermilion-color` / `jade-color`	국풍 전용 색 (금황 / 주사 / 비취)
`bg-color` / `text-color` / `border-color`	중성색
`bg-pattern`	문양 배경 URL (예: `var(--lh-pattern-willow)`)
`bg-pattern-opacity` / `bg-pattern-color`	문양 투명도와 색상
`decoration-color`	장식색

단일 컴포넌트 커스터마이징

테마를 지원하는 모든 컴포넌트는 themeVars를 직접 받을 수 있으며, 자기 자신에게만 영향을 줍니다:

<LhButton themeVars={{ 'primary-color': '#13c2c2' }}>청록 버튼</LhButton>

componentTheme로 컴포넌트 이름별로 일괄 설정할 수도 있습니다 (키 이름은 패밀리의 다른 라이브러리와 공통):

<LhConfigProvider
  componentTheme={{
    button: { 'primary-color': '#722ed1' },
    input: { 'border-color': '#d9d9d9' },
  }}
>
  <YourApp />
</LhConfigProvider>

우선순위: 컴포넌트 자체 props > componentTheme[컴포넌트명] > 전역 themeVars.

배경 문양

국풍 문양 배경은 기본적으로 꺼져 있습니다. patternComponents 허용 목록으로 켜며, 허용 목록에 있는 컴포넌트에만 전역 문양이 적용됩니다:

<LhConfigProvider
  themeVars={{ 'bg-pattern': 'var(--lh-pattern-willow)' }}
  patternComponents={['dialog', 'card']}
>
  <YourApp />
</LhConfigProvider>

컴포넌트가 bgPattern 프로퍼티로 직접 전달한 문양은 허용 목록의 제한을 받지 않습니다.

sx 간편 레이아웃

일부 컴포넌트는 sx 프로퍼티를 지원하며, 자주 쓰는 레이아웃 스타일을 객체로 작성합니다 (의미론은 emotion / MUI의 sx와 같음):

<LhButton sx={{ marginTop: 2, width: '100%' }} block>
  전체 너비 버튼
</LhButton>

런타임 전환

테마 전환의 본질은 CSS 변수를 바꾸는 것이므로 완전히 동적일 수 있습니다:

import { useState } from 'react'
import { LhConfigProvider } from '@lh-ui/react'

function App() {
  const [primary, setPrimary] = useState('#1677ff')
  return (
    <LhConfigProvider themeVars={{ 'primary-color': primary }}>
      <input type="color" onChange={(e) => setPrimary(e.target.value)} />
      <YourApp />
    </LhConfigProvider>
  )
}

CSS 변수의 타입 단언

소스에서 style="{ { '--lh-primary-color': x } }"는 TypeScript에서 에러를 냅니다 (CSSProperties에 커스텀 프로퍼티 키가 없음). 이 라이브러리는 cssVarsStyle() 유틸리티로 키 이름 변환과 단언을 통일 처리하며, 컴포넌트 내부에 이미 캡슐화되어 있어 사용자가 신경 쓸 필요가 없습니다.

토큰 계층​

ConfigProvider로 커스터마이징​

사용 가능 토큰​

단일 컴포넌트 커스터마이징​

배경 문양​

sx 간편 레이아웃​

런타임 전환​