토큰 이름 지정 규칙

토큰 이름이 일관되지 않으면 값을 읽지 않고는 토큰의 역할을 예측할 수 없습니다. 명확하고 예측 가능한 이름 지정 규칙은 확장 가능한 토큰 시스템의 기반입니다.

일반적인 패턴은 [category]-[property]-[variant]입니다. 예를 들면 color-text-primary, color-text-secondary, spacing-inset-sm이 있습니다. 각 부분은 의미의 범위를 점진적으로 좁힙니다.

컴포넌트에서는 blue-500 같은 팔레트 이름을 피하십시오. color-action-default, color-feedback-error와 같은 의미 기반 이름을 사용하십시오. 의미 기반 이름을 사용하면 컴포넌트를 업데이트하지 않고도 브랜드 색상을 변경할 수 있습니다.

상태를 끝에 추가하십시오: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. 일관된 상태 접미사를 사용하면 토큰 집합을 예측하기 쉽고 빠짐없이 구성할 수 있습니다.

티셔츠 크기(xs, sm, md, lg, xl) 또는 숫자 스케일(100, 200...900) 중 하나를 선택하여 일관되게 사용하십시오. 숫자 스케일은 중간 값을 추가할 수 있고, 티셔츠 크기는 작은 집합에서 사람이 더 쉽게 이해할 수 있습니다.

여러 브랜드 또는 제품을 사용하는 시스템에서는 토큰에 네임스페이스를 접두사로 추가하십시오: brand-a-color-primary와 brand-b-color-primary를 비교해 보십시오. 네임스페이스는 토큰 집합을 병합할 때 충돌을 방지합니다.

케밥 표기법은 CSS 사용자 지정 속성으로 직접 변환됩니다: color-text-primary는 --color-text-primary가 됩니다. 카멜 표기 토큰은 변환이 필요하지만, 케밥 표기 토큰은 그렇지 않습니다.

좋은 이름은 자체적으로 의미를 설명합니다. spacing-stack-md는 주어진 요소 사이의 세로 간격이 중간 크기라는 의도를 주석 없이 전달합니다. s3 같은 좋지 않은 이름은 의미를 이해하기 위해 별도의 문서가 필요합니다.

토큰을 사용하기 시작한 후 이름을 바꾸면 호환성을 깨는 변경 사항이 됩니다. 사용 중단 별칭을 사용하십시오. 기존 이름을 유지하면서 새 토큰을 참조하도록 만들 수 있습니다. 사용 중단된 토큰을 제거하기 전에 사용하는 쪽에 이전 기간을 제공하십시오.

Style Dictionary의 사용자 지정 규칙이나 CI 스크립트로 토큰 이름을 정적 검사하십시오. 이름 지정 패턴과 일치하지 않는 토큰은 거부하십시오. 자동화된 적용을 사용하면 시스템이 확장될 때 이름 지정 규칙이 점차 달라지는 것을 방지할 수 있습니다.

올바른 이름과 잘못된 이름의 예를 포함한 이름 지정 가이드를 발행하십시오. 시스템을 확장하기 전에 짧은 워크숍을 진행하여 디자인 팀과 엔지니어링 팀이 규칙에 합의하도록 하십시오. 일관성을 유지하려면 문서화뿐 아니라 모두가 공유하는 이해가 필요합니다.

컴포넌트 토큰은 "blue-500"과 같은 팔레트 이름보다 왜 의미 기반 이름을 사용해야 하나요?

범주-속성-변형 패턴, 의미 기반 이름, 상태 접미사, 네임스페이스 접두사를 사용하는 일관된 토큰 명명 규칙은 토큰 시스템을 예측 가능하고 자체 설명적으로 만들며, 컴포넌트 코드를 변경하지 않고도 브랜드 변경에 유연하게 대응할 수 있게 합니다.