스타일 커스터마이징 가이드라인

디자인 시스템 컴포넌트의 스타일을 커스터마이징하는 방법과 권장사항을 안내합니다.

✅ 권장하는 방법

디자인 시스템 기본 사용 (최우선)

디자인 시스템의 기본 스타일을 그대로 사용하는 것을 강력히 권장합니다
일관성 있는 디자인과 유지보수성을 보장합니다

📋 커스텀 스타일링 방법

모든 컴포넌트에서 Style Props와 sx 두 가지 방법을 지원합니다.

1. Style Props

Panda CSS의 style props를 직접 사용하는 방법입니다.

특징

사용성이 좋습니다
모든 컴포넌트에서 지원합니다
color prop과 같이 컴포넌트별 고유 prop과 이름이 겹칠 수 있습니다
- 예: Button의 color="impact" vs Style Props의 color="red.500"
- 컴포넌트의 고유 prop이 우선순위가 높습니다
styled-system을 쓰면 CSS 속성을 props로 관리해서, 컴포넌트를 빠르게 만들 수 있다

사용 예시

// Text 컴포넌트 - Style Props 사용
<Text bg="red.500" color="white">
  Custom Styled Text
</Text>

// Button 컴포넌트 - 컴포넌트 고유 prop 사용 (우선순위 높음)
<Button color="impact">
  Button with design system color
</Button>

참고 문서

2. sx

css.raw()를 사용해서 스타일 객체를 전달하는 방법입니다.

특징

사용을 권장하지 않습니다 - 꼭 필요한 경우에만 사용하세요
현재는 root 요소에만 적용됩니다
createStyleContext가 자동으로 지원하는 부분은 무시됩니다

변경 사항: `panda` prop → `sx` prop

기존 panda prop이 sx prop으로 변경되었습니다
여러 panda css 속성을 한번에 넘기기 위해 지원하던 prop이었습니다
원래는 css prop을 사용하는게 정석이지만, emotion의 css와 충돌 이슈로 인하여 sx prop으로 결정했습니다
논의 쓰레드

사용법

Panda CSS merge style 문서 참고
Panda CSS의 css 함수를 쓰면 raw를 사용하지 않고 넘길 수 있지만, sx prop을 사용할 때는 반드시 .raw()를 사용해야 합니다

import { css } from '@mildang/styled-system/css';

const cardStyles = css.raw({
  bg: 'red',
  color: 'white'
})

function Card({ title, description, sx }) {
  return (
    // merge the `cardStyles` with the `sx` passed in
    <div className={css(cardStyles, sx)}>
      <h1>{title}</h1>
      <p>{description}</p>
    </div>
  )
}

// usage
function Demo() {
  return (
    <Card
      title="Hello World"
      description="This is a card component"
      // use `css.raw(...)` to ensure Panda extracts the style object
      sx={css.raw({ bg: 'blue' })}
    />
  )
}