토큰 동기화
@atlaskit/tokens 새 버전이 나오면 Steel 토큰을 다시 만들어요.
Steel 의 색·간격·타이포그래피·그림자 토큰은 손으로 쓰지 않고 @atlaskit/tokens 패키지에서 자동으로 생성해요. Atlassian 이 토큰을 바꾸면 아래 순서로 따라갈 수 있어요. 기본으로 최신 FY27 Finesse 테마를 덮어써서 만들어요.
흐름
@atlaskit/tokens (npm)
└─ dist/esm/artifacts/ 원본 raw 토큰 (light / dark 테마)
│ packages/tokens/scripts/import-atlassian.ts
▼
brands/steel/*.yaml Rootage 형식 YAML (palette, color, space, radius, font, shadow, motion …)
│ pnpm tokens:build
▼
packages/tokens/dist/
css/steel.css --ds-* CSS 변수 (:root / .dark)
theme-atlas.css Tailwind 테마 + ds-font-* 유틸
│ docs 빌드 (registry)
▼
/r/steel-theme.json shadcn 테마 아이템brands/steel/brand.yaml 은 생성 대상이 아니에요. 서체, shadcn 별칭, 대비 표 쌍처럼 Steel 이 직접 정하는 값만 담고 있어서 동기화해도 그대로 남아요.
동기화하기
새 패키지 받기
원하는 버전의 @atlaskit/tokens 를 받아 압축을 풀어요. 버전을 빼면 최신 버전을 받아요.
mkdir -p /tmp/atlaskit-tokens && cd /tmp/atlaskit-tokens
npm pack @atlaskit/tokens@latest
tar xzf atlaskit-tokens-*.tgz # → ./packageYAML 다시 만들기
저장소 루트에서 변환 스크립트를 실행해요. 첫 번째 인자는 패키지 경로, 두 번째는 브랜드 ID(기본값 steel)예요.
node packages/tokens/scripts/import-atlassian.ts /tmp/atlaskit-tokens/package steel스크립트는 이렇게 바꿔요.
| 원본 | 결과 |
|---|---|
팔레트 Blue700, DarkNeutral-100A | $color.palette.blue-700, $color.palette.dark-neutral-n100a |
color.*, elevation.surface.* | light / dark 값을 팔레트 참조로 (팔레트에 없으면 hex) |
elevation.shadow.* | Rootage shadow 값 |
space, radius, border.width, font, opacity, motion | 기본값 그대로 |
서체 Atlassian Sans, Charlie, Atlassian Mono | Inter / JetBrains Mono |
atlassian-{light,dark,typography}-finesse | 기본 테마 위에 덮어써요 (--no-finesse 로 끔) |
바뀐 점 확인
git diff --stat brands/steel packages/tokens/dist- 값만 바뀐 경우: 컴포넌트는 토큰 유틸만 쓰기 때문에 그대로 새 값을 따라가요. 문서 사이트(
pnpm dev)에서 라이트·다크를 둘 다 훑어봐요. - 토큰이 새로 생긴 경우: 바로
bg-ds-<새 이름>처럼 쓸 수 있어요. - 토큰이 사라졌거나 이름이 바뀐 경우: 아래처럼 컴포넌트에서 옛 이름을 찾아 바꿔요.
grep -rn "ds-<옛 이름>" apps/docs/registry/steelFinesse 테마
Steel 은 최신 Atlassian 모습(FY27 "Finesse")을 따라요. 변환 스크립트는 @atlaskit/tokens 의 기본 테마(atlassian-light, atlassian-dark, atlassian-typography)를 읽은 뒤, 같은 이름의 *-finesse 오버라이드 테마가 있으면 토큰 이름 기준으로 덮어써요.
# 기본: Finesse 오버라이드 적용
node packages/tokens/scripts/import-atlassian.ts /tmp/atlaskit-tokens/package steel
# Finesse 없이 기본 테마만
node packages/tokens/scripts/import-atlassian.ts /tmp/atlaskit-tokens/package steel --no-finesseFinesse 를 적용하면 이렇게 달라져요.
- 선택 상태(
*.selected)가 파랑에서 중립(진한 중립 글자 + 반투명 중립 배경)으로 바뀌어요. - 작은 제목(
font.heading.medium·small·xsmall·xxsmall)의 굵기가 653 에서 500 으로 바뀌어요. background.neutral.subtle.hovered같은 subtle hover 가 더 옅어져요.
실행이 끝나면 ✓ brands/steel (finesse): … 처럼 적용 여부가 출력돼요.
Forge 다시 만들기
Forge 는 Steel 을 복제해 만든 브랜드라서, Steel 토큰을 다시 만들었다면 Forge 도 다시 만들어야 새 값을 따라가요. brands/forge/color.yaml 맨 위 주석에 적힌 명령을 저장소 루트에서 그대로 실행한 뒤 빌드해요.
head -1 brands/forge/color.yaml # 생성 명령 확인
# node packages/tokens/scripts/derive-brand.ts --force --from steel --to forge ... --roles brand ...
pnpm tokens:build자세한 옵션은 브랜드 에서 볼 수 있어요.
주의할 점
brands/steel/의 생성된 YAML(color.yaml등)은 직접 고치지 않아요. 다음 동기화 때 덮어써져요. 바꿔야 할 값이 있다면brand.yaml이나 변환 스크립트에 규칙으로 넣어요.- Atlassian 은 사용 중단(deprecated) 토큰을 몇 버전 동안 남겨 두다가 지워요. 동기화 전에
@atlaskit/tokens의 CHANGELOG 에서 삭제·이름 변경 항목을 먼저 확인하면 좋아요. - 토큰 패키지는 Apache-2.0 이에요. 버전을 올리면
NOTICE의 출처 표기도 확인해요.