원칙

토큰만 쓰는 규칙과 role-based 컬러 선택법, 컴포넌트 커스터마이즈 방법

@mildang/design-system의 모든 스타일 값은 토큰으로 표현합니다. 아래 원칙을 지키면 코드를 바꾸지 않아도 테마 교체, 다크 모드, 브랜드 분기가 자동으로 반영됩니다.

아래 예제는 소스(Panda)로 사용할 때의 문법입니다.
패키지를 설치해 사용할 때는 토큰을 CSS 변수로 참조하며, 컴포넌트를 커스텀하는 방법은 컴포넌트 스타일링에 환경별로 정리돼 있습니다.

1. 토큰만 쓴다

색상·간격·타이포그래피·radius·shadow를 raw 값(hex·rgb·px)으로 직접 사용하지 않습니다. 토큰을 거치지 않은 값은 테마가 바뀌어도 그대로여서, 다른 브랜드나 다크 모드에서 어긋납니다.

tsx

// 지양: raw 값
<Box style={{ color: '#161d29', padding: '8px' }} />

// 권장: 토큰
<Box color="neutral.text.base" padding="8" />

2. 색상은 role · slot · level 로 고른다

색상 토큰은 세 축의 조합입니다.

tsx

{role}.{slot}.{level}        예: neutral.text.base

role (역할)

role	뜻
`neutral`	중립. 본문·면·테두리의 기본
`primary`	주요 행동
`brand`	브랜드 강조
`inverse`	짙은 배경 위에 사용하는 반전 면
`positive`·`critical`·`warning`·`info`	상태. 성공·위험·주의·정보

slot (용도)

어떤 CSS 속성에 적용하느냐에 따라 slot이 정해집니다. 이 표가 role-based 토큰의 핵심입니다.

CSS 속성	slot
`color` (텍스트)	`text`
`color` (아이콘) · SVG `fill`·`stroke`	`icon`
`color` (구분선·divider)	`border`
`backgroundColor` (일반 면)	`surface`
`backgroundColor` (강조 면)	`fill`
`borderColor`·`outlineColor`	`border`
`boxShadow`	`border` (alpha는 `ghostBg`)
gradient · `backgroundImage` · alpha 토큰	`ghostBg`

level (강도)

low → base → high → highest 순으로 강해지며, 기본은 base입니다. 더 낮은 lowest도 드물게 사용합니다.

tsx

<Text color="neutral.text.base" />
<Text color="neutral.text.low" />                        {/* 보조 텍스트 */}
<Box bg="neutral.surface.high" borderColor="neutral.border.low" />
<Button bg="primary.fill.base" />                        {/* 강조 면은 surface 대신 fill */}

{role}.fg.*는 없습니다. 텍스트는 text, 아이콘은 icon을 사용합니다. .fg.는 일부 컴포넌트 전용 토큰에만 있어, role 경로로 쓰면 타입 에러 없이 무시됩니다.

3. 컴포넌트는 정해진 방법으로 커스텀한다

컴포넌트의 모양은 클래스를 임의로 덮어쓰지 않고 정해진 방법으로 조정합니다.

형태는 variant·size 같은 옵션으로 고릅니다.
세부는 style prop·sx(소스) 또는 CSS 변수(패키지)로 조정합니다.
className은 최후의 수단입니다.

자세한 방법과 환경별 차이는 컴포넌트 스타일링을 참고하세요.

4. 간격은 spacing 토큰을 쓴다

padding·margin·gap에는 spacing 토큰을 사용합니다. '8px' 같은 raw px 값은 사용하지 않으며, 0 역시 토큰({spacing.0})으로 지정합니다. padding 영역을 음수 margin으로 상쇄하는 보정 방식은 지양합니다. 실제 여백을 개발자가 직접 계산해야 하는 부담이 생기기 때문입니다. 자세한 규칙은 Spacing 문서에서 확인할 수 있습니다.

5. 레거시 토큰은 쓰지 않는다

레거시 컬러 토큰 (common.1~12, success.7, *.gradient.* 등). 신규 코드는 role-based 토큰만 사용합니다.
레거시 textStyle 이름 (h1~h6, body1-R, subtitle* 등). 신규 이름(body-sm, title-lg …)만 사용합니다. 계열 선택 규칙은 Typography 문서에 정리돼 있습니다.