새 브랜드 추가하기
새 제품을 위한 디자인 시스템을 Rebar 에 추가하는 절차예요. 시스템 폴더를 만들고, 토큰 값을 고치고, 검증하면 끝이에요.
새 시스템은 같은 계열의 기존 시스템을 복사해서 시작해요. 토큰 이름은 같은 계열의 모든 시스템이 같아야 하므로, 처음부터 만드는 것보다 복사한 뒤 값만 바꾸는 편이 안전해요. 새 시스템도 건축 자재의 이름을 붙여요.
| 만들 시스템 | 원본 | 도구 |
|---|---|---|
| SEED 계열 (모바일 중심, Clay 와 같은 컴포넌트) | brands/clay | pnpm new-brand — 아래 절차 |
| Atlassian 계열 (업무 도구, Steel 과 같은 컴포넌트) | brands/steel | derive-brand.ts — Atlassian 계열 시스템 만들기 |
아래 절차는 SEED 계열 기준이에요.
시스템 폴더 만들기
저장소 루트에서 아래 명령을 실행해요. <id> 는 영문 소문자로 시작하고 소문자·숫자·하이픈만 쓸 수 있어요.
pnpm new-brand marble --name "Marble"brands/marble/ 폴더가 생기고 brand.yaml 의 id, name, nameEn, description 이 채워져요. product(이 시스템을 쓰는 제품 이름)는 직접 고쳐요. 원본은 기본값이 clay 이고, 다른 시스템을 바탕으로 만들고 싶다면 --from <id> 를 붙여요.
pnpm new-brand marble --name "Marble" --from clay색 고치기
brands/marble/color.yaml 에서 브랜드의 인상을 가장 크게 좌우하는 부분부터 바꿔요.
$color.palette.*— 원시 색. 보통 브랜드 색 계열(예:orange-*)의 100~1000 단계를 새 색으로 바꿔요.$color.bg.brand-*,$color.fg.brand*,$color.stroke.brand-*— 브랜드 시맨틱이 어떤 팔레트를 가리킬지 정해요.theme-light와theme-dark값을 둘 다 채워요.
$color.bg.brand-solid:
values:
theme-light: $color.palette.blue-600
theme-dark: $color.palette.blue-500메타·폰트·별칭 고치기
brands/marble/brand.yaml 에서 이름과 제품(product), 설명, 폰트(font.sans, font.mono), shadcn 별칭을 확인해요. 별칭은 대부분 시맨틱 토큰을 가리키므로 색을 바꿨다면 그대로 둬도 돼요.
그 밖의 토큰 (선택)
모서리(radius.yaml), 간격(dimension.yaml), 글자 크기(font-size.yaml) 등도 필요하면 바꿔요. 예를 들어 $radius.r2 를 키우면 모든 버튼과 입력 필드가 더 둥글어져요.
토큰을 추가하거나 지우지 마세요. 같은 계열의 모든 시스템은 토큰 목록이 같아야 공용 컴포넌트가 동작해요. 새 토큰이 꼭 필요하다면 같은 계열의 모든 시스템에 함께 추가해야 해요.
검증하고 빌드하기
pnpm tokens:build # 검증 + 빌드
pnpm tokens:check # 검증만빌드는 아래 규칙을 검사하고, 하나라도 어기면 실패해요.
| 규칙 | 실패 예 |
|---|---|
brand.yaml 의 id 가 폴더 이름과 같아요 | [marble] brand.yaml 의 id(clay)가 폴더 이름과 다름 |
name, description, font.sans, font.mono 가 있어요 | [marble] brand.yaml 에 description 없음 |
| 토큰 파일 9개(color, dimension, radius, font-size, font-weight, line-height, duration, timing-function, shadow)가 모두 있어요 | 파일 없음: brands/marble/shadow.yaml |
색 토큰은 theme-light·theme-dark, 나머지는 default 값이 있어요 | [marble] $color.bg.brand-solid 에 theme-dark 값 없음 |
참조($color.palette.…)가 실제로 있고 순환하지 않아요 | [marble] 참조 $color.palette.blue-650 를 찾을 수 없음 |
| shadcn 별칭이 모두 정의돼 있어요 | [marble] brand.yaml shadcn.ring 없음 |
| 토큰 목록이 같은 계열의 다른 시스템과 같아요 | [marble] $radius.r7 는 clay 에 없는 토큰 |
또 fg.on-* 와 bg.*-solid 조합의 명도 대비가 3:1 미만이면 경고를 보여줘요. 경고는 빌드를 막지 않지만, 접근성을 위해 꼭 확인해 주세요.
문서 사이트에서 확인하기
pnpm devhttp://localhost:5173/?brand=marble 로 열거나 상단 선택기에서 새 시스템을 고르면, 모든 컴포넌트 예제와 Foundations 문서가 새 토큰으로 그려져요. 컴포넌트 페이지를 돌아보며 대비와 인상을 확인해요.
배포하면 registry 에 marble-theme 아이템이 자동으로 생겨서, 사용하는 프로젝트에서 바로 설치할 수 있어요.
pnpm dlx shadcn@latest add <site>/r/marble-theme.jsonAtlassian 계열 시스템 만들기
Atlassian 계열은 packages/tokens/scripts/derive-brand.ts 로 기존 시스템(보통 steel)을 복제해 브랜드 색만 바꾼 새 시스템을 만들어요. Forge 도 이렇게 만들었어요. 원본 팔레트 단계마다 OKLCH 밝기를 맞춰 새 색의 팔레트를 만들고, 경로에 --roles 단어(brand, selected …)가 들어간 시맨틱 토큰만 새 팔레트로 바꿔요. 링크·포커스 링·정보 색 같은 나머지 토큰과 간격·모서리·글자·그림자는 그대로 복사돼요.
node scripts/derive-brand.ts \
--from steel --to granite \
--name "Granite" --product "애크미 어드민" \
--color "#0f766e" \
--source blue --prefix brand-teal --roles brand \
--vivid-step 700 --dark-vivid-step 400옵션 전체와 Forge 를 만든 실제 명령은 Steel 과 Forge 에 정리했어요. 만든 뒤에는 저장소 루트에서 pnpm tokens:build 로 검증하고, 문서 사이트의 /steel?brand=<id> 에서 확인해요.
Steel 토큰 다시 가져오기
Steel 자체의 토큰(brands/steel/*.yaml)은 packages/tokens/scripts/import-atlassian.ts 가 @atlaskit/tokens 패키지에서 생성해요. 기본으로 최신 Jira 모습(FY27 "Finesse")의 오버라이드 테마를 덮어쓰고, --no-finesse 를 주면 기본 Atlassian 테마만 써요.
npm pack @atlaskit/tokens && tar xzf atlaskit-tokens-*.tgz
node packages/tokens/scripts/import-atlassian.ts ./package steel # Finesse 포함
node packages/tokens/scripts/import-atlassian.ts ./package steel --no-finesse # 기본 테마만자세한 변환 규칙은 토큰 동기화 를 참고해요.