컴포넌트 스타일링

컴포넌트를 감싸거나 클래스를 덮어쓰지 않고, 정해진 방법으로 스타일을 조정합니다. 값은 항상 토큰으로 지정하면 테마나 브랜드가 바뀌어도 알맞게 유지됩니다.

개요

커스텀하는 방법은 두 가지이며, 목적에 따라 고릅니다.

• 인스턴스 하나만 조정 — color·bg·padding·textStyle 같은 style prop과 sx를 사용합니다.
• 전역·테마로 조정 — 컴포넌트가 노출하는 CSS 변수를 재정의합니다.

두 방법은 작동하는 환경이 다릅니다. style prop은 빌드 시 Panda가 코드를 컴파일하는 환경(모노레포에서 소스로 사용할 때)에서만 적용되고, CSS 변수는 순수 CSS라 패키지로 설치한 환경에서도 작동합니다. 자세한 범위는 아래 적용 범위 절에 정리되어 있습니다.

1. style prop 과 sx

컴포넌트는 Panda의 style prop을 그대로 받습니다(모노레포에서 소스로 사용할 때). prop으로 넘긴 값은 그 인스턴스에만 적용됩니다.

// 기본
<Text variant="body-md">보조 설명</Text>

// 색상·여백만 덮어쓰기 (값은 role-based 토큰)
<Text variant="body-md" color="neutral.text.low" marginTop="8">
  보조 설명
</Text>

<Button variant="primary" bg="critical.fill.base" paddingX="16">
  삭제
</Button>

색상 토큰의 slot(text·surface·fill·border …)은 적용하는 CSS 속성에 맞춰 고릅니다. 자세한 선택 규칙은 원칙의 role · slot · level을 참고하세요.

태그 변경 (as)

컴포넌트는 기본 HTML 태그로 렌더됩니다. as prop을 주면 보이는 스타일은 그대로 두고 실제 태그만 바꿉니다. 예를 들어 제목처럼 보이는 텍스트를 실제 <h2> 같은 시맨틱 태그로 내보내 접근성·SEO를 지킬 때 사용합니다.

// 스타일은 title-lg 그대로, 실제 태그만 <h2> 로 렌더
<Text as="h2" variant="title-lg">섹션 제목</Text>

복합 오버라이드 (sx)

조건부 상태(_hover·_disabled), 반응형, 중첩처럼 단일 prop으로 표현하기 어려우면 sx를 사용합니다.

<Button
  variant="secondary"
  sx={{
    _hover: { bg: 'primary.surface.high' },
    marginTop: '8',
    paddingX: { base: '12', md: '20' }, // 반응형: base=모바일, md 이상=데스크톱
  }}
/>

css prop은 Emotion의 JSX css와 이름·런타임이 충돌하기 때문에 지원하지 않습니다.

우선순위

컴포넌트 기본값은 style prop과 sx로 조정합니다. 같은 속성을 여러 곳에서 지정하면 대체로 나중에 지정한 값이 적용되지만, 항상 보장되지는 않습니다.

확실하게 덮어써야 하는 값은 CSS 변수로 지정하세요.

2. CSS 변수

컴포넌트의 스타일 값은 CSS 변수(디자인 토큰)로 노출됩니다. 이 변수를 재정의하면 해당 컴포넌트 전부가 바뀝니다. 순수 CSS라 패키지로 설치한 환경에서도 작동합니다.

/* md 크기 버튼의 좌우 padding 전부 바꾸기 */
:root {
  --ids-spacing-button-size-md-padding-x: 20px;
}

/* 특정 영역에만 적용하려면 그 스코프에 선언합니다 */
.my-section {
  --ids-spacing-button-size-md-padding-x: 20px;
}

• 컴포넌트 전용 변수를 바꾸면 그 컴포넌트만 바뀝니다.
• 베이스 토큰(예: --ids-spacing-12)을 바꾸면 그 값을 사용하는 모든 곳이 바뀌니 주의합니다.
• 제품·브랜드 단위의 시각 차이도 이 변수를 테마별로 재정의하는 방식입니다. 제품별 테마를 참고하세요.

컴포넌트가 어떤 변수를 노출하는지는 각 컴포넌트 문서에서 확인할 수 있습니다.

적용 범위

같은 커스텀이라도 소스(모노레포)로 사용할 때와 패키지로 설치해 사용할 때 되는 범위가 다릅니다.

패키지 소비자는 이미 컴파일된 styles.css를 사용하므로, 새 클래스가 필요한 style prop은 적용되지 않습니다. 정해진 prop을 사용하고, 세부는 CSS 변수로 조정합니다. 패키지 사용 시 import '@mildang/design-system/styles.css'를 한 번 넣어야 스타일이 나옵니다.

권장 사항