개발

개발 (Develop)

코드에서 디자인 토큰을 사용하는 방법 문서예요. CSS 변수로 제공되는 PatternFly 토큰을 활용하고 다크 테마, 마이그레이션, React 토큰까지 다뤄요.

출처: 문서

본문

코드에서 토큰 사용하기 (Using tokens in code)

PatternFly 토큰은 Figma에서 내보내져 코드에서 사용할 수 있도록 CSS 변수로 변환됩니다. 모든 토큰 파일은 core HTML 리포지토리에서 찾을 수 있어요.

토큰은 의미적으로 명명되어 있으며, 그 기능을 더 잘 전달하고 의미가 있습니다. 코드에서 토큰을 사용할 때는 항상 자신의 요구에 가장 잘 맞는 의미적(semantic) 토큰을 사용해야 해요. 예를 들어 색상 토큰을 선택할 때는 hex 값이 아니라 그 기능을 기준으로 선택하세요.

사용 사례에 맞는 의미적 토큰이 없다면 base 토큰을 대신 사용할 수 있지만, 드물게 사용하세요. Palette 토큰은 사용하지 마세요. 그것들은 토큰 시스템의 기반이며, 항상 사용하기에 더 나은 base 또는 semantic 토큰이 있을 거예요.

모든 디자인 토큰 보기.

다크 테마 지원 (Dark theme support)

토큰 시스템은 기본적으로 라이트 테마와 다크 테마를 모두 지원합니다. 다크 테마를 활성화하려면 애플리케이션의 <html> 태그에 pf-[version]-theme-dark 클래스(예: pf-v6-theme-dark)를 추가하기만 하면 됩니다. 그러면 다크 테마가 활성화될 때 제품이 자동으로 다크 테마 토큰을 가져와 시각적 스타일을 적절히 조정합니다.

자세한 내용은 다크 테마 핸드북을 참조하세요.

토큰으로 마이그레이션 (Migrate to tokens)

토큰을 지원하기 위해 PatternFly의 전역 CSS 변수 시스템이 업데이트되었습니다. 모든 PatternFly 컴포넌트와 확장에서 변수 이름이 업데이트되었어요. 토큰 시스템으로 마이그레이션하려면 PatternFly 6으로 업그레이드해야 합니다.

제품에서 PatternFly 컴포넌트를 커스터마이즈하거나 CSS override를 사용한다면, CSS 변수 이름을 적절한 의미적 토큰에 맞게 수동으로 업데이트해야 해요. 특정 CSS 변수에 대한 일대일 권장 사항은 없으므로, 사용 사례에 가장 적절한 토큰을 직접 선택해야 합니다.

마이그레이션하면서 토큰을 고를 때 이 권장 사항과 주의사항을 참조하세요:

의미적 토큰만 사용해야 한다는 점을 기억하세요. Palette와 base 토큰은 의미적 토큰에 값을 제공하지만, 일반적으로 그 외에는 사용해서는 안 됩니다. Palette와 base 토큰은 숫자로 끝나지만 의미적 토큰은 그렇지 않아요. 그러니 숫자로 끝나는 토큰은 절대 사용하지 마세요.
옛날 값에서 시작해 거꾸로 작업하지 마세요. 예를 들어 "파란색"인 것이 많지만, 목적에 맞는 올바른 토큰을 고르는 것이 중요합니다. 게다가 PatternFly 6은 완전히 새로운 모습을 가지므로, 예전에 "파란색"이었던 것이 더 이상 파란색이 아닐 수도 있어요!
의미적 토큰의 명명 계층을 이해하세요. 토큰 이름의 구조를 기억하세요:
```
--pf-t--[scope]--[component]--[property]--[concept]--[variant]--[state]
```
각 세그먼트에 대해 다음을 고려하세요:
- Prefix: --pf-t-는 CSS 변수가 토큰임을 나타냅니다.
- Scope: global 또는 chart입니다.
- Component: 무엇에 적용하고 있나요? 예: background, text, icon, border, box-shadow, motion, 또는 spacer.
- Property: 적용하고 있는 속성은 무엇인가요? 예: color, size, radius, 또는 width.
- Concept: primary, status, nonstatus, action 같은 개념과 연관되어 있나요?
- Variant: 어떤 변형이 필요한가요? 보통 다음을 포함합니다:
  - 크기 (xs, sm, md, lg, xl, 2xl)
  - 상태 (danger, warning, success, info)
  - 일부 text와 icon 색상의 경우 on-은 특정 배경 위에서 사용할 접근 가능한(accessible) 색상을 의미합니다.
- State: 상태는 무엇인가요? 예: default, hover, 또는 clicked.
CSS 변수에 퍼지 매칭/자동완성을 사용하세요. 올바른 토큰 이름을 찾는 데 매우 유용합니다. VSCode에서는 CSS variable autocomplete 플러그인을 추천합니다.
의미적 토큰을 사용하면 다크 테마 스타일링을 공짜로 얻을 수 있어요. 이름에 dark가 포함된 토큰을 발견할 수도 있는데, 그것들을 쓰고 싶은 유혹이 들지 마세요! 그런 토큰들은 기본 의미적 토큰 집합에 다크 테마 값을 적용하는 선택자 안에 존재합니다.
실제로 어떻게 보이는지 테스트하는 데 시간을 투자하세요.
- 다크 테마로 전환해 제대로 보이는지 확인하세요. 이렇게 하면 부적절한 토큰이 자주 드러납니다.
- 커스텀 스타일이 기존 PatternFly 컴포넌트처럼 일치하고 동작해야 한다면, 그 컴포넌트의 스타일과 비교해(라이트와 다크 테마 모두에서) 일치하는지 확인하세요.
- 토큰을 바꿔보고 기대한 대로 변하는지 확인해 보세요.

토큰 선택 (Selecting tokens)

옛 전역 변수는 대부분 의미를 많이 전달하지 못했기 때문에, 옛 전역 변수를 새 디자인 토큰으로 일관되게 매핑하기는 어렵습니다. 반면 디자인 토큰은 의도적인 의미를 담고 있어요. 의미적 토큰이 의미가 명확하도록 명명하려고 노력했지만, 토큰 시스템에 익숙해지기 전에는 사용 사례에 어떤 토큰을 골라야 할지 명확하지 않을 수 있어요.

토큰을 고를 때 무엇을 위해 토큰이 필요한지 보고, 퍼지 매칭을 사용해 적절한 토큰 옵션을 찾아보세요.

다음 시나리오는 (추천하는 VS Code 플러그인 기준) 예시를 제공합니다:

시나리오 1: 커스텀 요소에 disabled 상태를 만들어야 합니다.
- 배경색을 설정하고 싶을 거예요: pft를 입력해 토큰을 얻고, back으로 background를, 그다음 dis로 disabled를 입력하세요.
- 결국 var(--pf-t--global--background--color--disabled--default)를 선택하게 됩니다.
- 다음으로 그 요소의 텍스트 색상을 설정하고 싶을 거예요: pft, 그다음 텍스트 색상에 text, 그다음 ondis를 입력하세요.
- 결국 var(--pf-t--global--text--color--on-disabled)를 얻게 됩니다.
시나리오 2: 간격을 조정해야 합니다.
- spacer가 필요할 거예요: pft를 입력하고, sp로 spacer를 얻은 다음, 원하는 spacer 크기(sm, md 등)를 이어서 입력하세요.
- 결국 var(--pf-t--global--spacer--sm) 같은 것을 얻게 됩니다.

React 토큰 (React tokens)

React 토큰은 CSS 변수의 React 버전이에요. 토큰 변수보다 더 많은 것을 포함하며 제대로 업그레이드하려면 추가 주의가 필요합니다. 최신 토큰은 여기에서 찾을 수 있어요.

React 토큰은 해당 파일에서 직접 가져올 수 있어요:

import t_token_name from '@patternfly/react-tokens/dist/esm/t_token_name'

또는 전체 패키지에서:

import { t_token_name } from '@patternfly/react-tokens'

React 토큰 이름은 CSS 토큰 이름과 비슷하지만 형식이 다릅니다. 이중 하이픈(--) 대신 토큰 세그먼트가 밑줄(_)로 구분됩니다. 또한 --pf-t 접두사는 t로 대체됩니다. 예를 들어 CSS 변수 --pf-t--global--spacer--sm은 React 토큰으로 t_global_spacer_sm이 됩니다.

각 React 토큰은 name, value, var 속성을 저장하는 객체입니다:

const t_global_spacer_sm = {
  "name": "--pf-t--global--spacer--sm",
  "value": "0.5rem",
  "var": "var(--pf-t--global--spacer--sm)"
}

개발