토큰
토큰 (Tokens)
디자인 토큰은 애플리케이션 또는 웹사이트에서 디자인 결정을 관리하는 플랫폼에 독립적인(platform-agnostic) 방식이에요. 근본적인/원자적인 시각적 스타일을 기술하는 속성들의 모음이며, 각 속성은 키-값 쌍이에요.
출처: 문서
본문
개요
디자인 토큰은 애플리케이션 또는 웹사이트에서 디자인 결정을 관리하는 플랫폼 중립적인 방법이에요. 근본적이거나 원자적인 시각적 스타일을 설명하는 속성들의 모음이며, 각 속성은 키-값 쌍이에요.
Chakra의 디자인 토큰은 W3C Token Format의 영향을 크게 받았어요.
디자인 토큰은 다음 속성들로 구성돼요.
value: 토큰의 값. 유효한 CSS 값이면 무엇이든 될 수 있어요.description: 토큰을 어떤 용도로 쓸 수 있는지에 대한 (선택) 설명
토큰 정의하기
토큰은 시스템 설정의 theme 키 아래에 정의해요.
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
tokens: {
colors: {
primary: { value: "#0FEE0F" },
secondary: { value: "#EE0F0F" },
},
fonts: {
body: { value: "system-ui, sans-serif" },
},
},
},
})
export const system = createSystem(defaultConfig, config)
토큰 값은
value키를 가진 객체 안에 중첩해야 해요. 이렇게 해야 향후description같은 추가 속성을 지원할 수 있어요.
별도 파일에서 토큰 정의하기
토큰 집합이 커지면 토큰을 각자의 파일로 옮기고 시스템 설정으로 import할 수 있어요. 각 토큰은 해당 파일에서 이미 { value: ... } 형태로 작성돼 있어야 해요.
export const colors = {
brand: {
500: { value: "#0066cc" },
},
}
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
import { colors } from "./colors"
const config = defineConfig({
theme: { tokens: { colors } },
})
export const system = createSystem(defaultConfig, config)
토큰 사용하기
토큰을 정의한 뒤에는 Chakra CLI를 실행해 테마 타입을 생성해요. 이렇게 하면 에디터에서 토큰에 대한 자동 완성이 제공돼요. postinstall, CI, 모노레포에서 typegen을 실행하는 방법은 CLI 문서를 참고하세요.
npx @chakra-ui/cli typegen ./src/theme.ts
컴포넌트에서 토큰을 사용하는 예시를 볼게요.
<Box color="primary" fontFamily="body">
Hello World
</Box>
토큰 참조 문법
Chakra UI는 border, padding, box-shadow 같은 CSS 속성의 복합 값 안에서 디자인 토큰을 참조할 수 있게 해 줘요. {path.to.token} 형태의 토큰 참조 문법을 통해 이를 구현해요.
완전한 토큰 경로를 사용하는 게 중요해요. 예를 들어
red.300대신colors.red.300으로 참조해야 해요.
다음은 토큰 참조 문법을 border와 p(padding) 속성 양쪽에 적용한 예시예요.
<Box
border="1px solid {colors.red.300}"
p="{spacing.4} {spacing.6} {spacing.8} {spacing.10}"
boxShadow="{spacing.4} {spacing.2} {spacing.2} {colors.red.300}"
/>
토큰 중첩
토큰은 중첩해서 토큰의 계층 구조를 만들 수 있어요. 관련 토큰을 함께 그룹화하고 싶을 때 유용해요.
중첩 토큰의 기본 값을 정의하려면
DEFAULT키를 사용하세요.
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
const config = defineConfig({
theme: {
tokens: {
colors: {
red: {
DEFAULT: { value: "#EE0F0F" },
100: { value: "#EE0F0F" },
},
},
},
},
})
export default createSystem(defaultConfig, config)
<Box
// 👇🏻 This will use the `DEFAULT` value
bg="red"
color="red.100"
>
Hello World
</Box>
토큰 종류
defineTokens는 타입 헬퍼예요. 인자를 그대로 반환하는 항등 함수라서 자동 완성과 타입 안전성만 제공하며, 런타임에서 값을 변형하거나 재구성하지 않아요. 토큰은 반드시{ value: ... }형태로 작성돼 있어야 해요.defineTokens({...})가 원시 값을 알아서 감싸 주지는 않아요.
Colors (색상)
색상은 의미를 가지며 콘텐츠의 목적을 돕고, 정보의 계층이나 상태 같은 것을 전달해요. 주로 문자열 값 또는 다른 토큰에 대한 참조로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
colors: {
red: {
100: { value: "#fff1f0" },
},
},
})
export default createSystem({
theme: { tokens },
})
Gradients (그라디언트)
그라디언트 토큰은 두 가지 이상의 색상 사이의 부드러운 전환을 나타내요. 값은 문자열 또는 복합 값으로 정의할 수 있어요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
gradients: {
// string value
simple: { value: "linear-gradient(to right, red, blue)" },
// composite value
primary: {
value: { type: "linear", placement: "to right", stops: ["red", "blue"] },
},
},
})
export default createSystem({
theme: { tokens },
})
Sizes (사이즈)
사이즈 토큰은 요소의 너비와 높이를 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
sizes: {
sm: { value: "12px" },
},
})
export default createSystem({
theme: { tokens },
})
사이즈 토큰은 주로
width,height,minWidth,maxWidth,minHeight,maxHeight속성에 사용돼요.
Spacing (스페이싱)
스페이싱 토큰은 요소의 마진과 패딩을 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
spacing: {
gutter: { value: "12px" },
},
})
export default createSystem({
theme: { tokens },
})
스페이싱 토큰은 주로
margin,padding,gap,{top,right,bottom,left}속성에 사용돼요.
Fonts (폰트)
폰트 토큰은 텍스트 요소의 폰트 패밀리를 나타내요. 값은 문자열 또는 문자열 배열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
fonts: {
body: { value: "Inter, sans-serif" },
heading: { value: ["Roboto Mono", "sans-serif"] },
},
})
export default createSystem({
theme: { tokens },
})
폰트 토큰은 주로
font-family속성에 사용돼요.
Font Sizes (폰트 크기)
폰트 크기 토큰은 텍스트 요소의 크기를 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
fontSizes: {
sm: { value: "12px" },
},
})
export default createSystem({
theme: { tokens },
})
폰트 크기 토큰은 주로
font-size속성에 사용돼요.
Font Weights (폰트 굵기)
폰트 굵기 토큰은 텍스트 요소의 굵기를 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
fontWeights: {
bold: { value: "700" },
},
})
export default createSystem({
theme: { tokens },
})
폰트 굵기 토큰은 주로
font-weight속성에 사용돼요.
Letter Spacings (자간)
자간 토큰은 텍스트 요소에서 글자 사이의 간격을 나타내요. 값은 문자열로 정의돼요.
const tokens = defineTokens({
letterSpacings: {
wide: { value: "0.1em" },
},
})
export default createSystem({
theme: { tokens },
})
자간 토큰은 주로
letter-spacing속성에 사용돼요.
Line Heights (줄 높이)
줄 높이 토큰은 텍스트 한 줄의 높이를 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
lineHeights: {
normal: { value: "1.5" },
},
})
export default createSystem({
theme: { tokens },
})
줄 높이 토큰은 주로
line-height속성에 사용돼요.
Radii (반경)
반경 토큰은 테두리의 반지름을 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
radii: {
sm: { value: "4px" },
},
})
export default createSystem({
theme: { tokens },
})
반경 토큰은 주로
border-radius속성에 사용돼요.
Borders (테두리)
테두리는 UI 요소를 둘러싸는 선이에요. 문자열 값 또는 복합 값으로 정의할 수 있어요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
borders: {
// string value
subtle: { value: "1px solid red" },
// string value with reference to color token
danger: { value: "1px solid {colors.red.400}" },
// composite value
accent: { value: { width: "1px", color: "red", style: "solid" } },
},
})
export default createSystem({
theme: { tokens },
})
테두리 토큰은 주로
border,border-top,border-right,border-bottom,border-left,outline속성에 사용돼요.
Border Widths (테두리 굵기)
테두리 굵기 토큰은 테두리의 너비를 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
borderWidths: {
thin: { value: "1px" },
thick: { value: "2px" },
medium: { value: "1.5px" },
},
})
export default createSystem({
theme: { tokens },
})
Shadows (그림자)
그림자 토큰은 요소의 그림자를 나타내요. 값은 문자열 또는 복합 값을 포함하는 단일 또는 다중 값으로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
shadows: {
// string value
subtle: { value: "0 1px 2px 0 rgba(0, 0, 0, 0.05)" },
// composite value
accent: {
value: {
offsetX: 0,
offsetY: 4,
blur: 4,
spread: 0,
color: "rgba(0, 0, 0, 0.1)",
},
},
// multiple string values
realistic: {
value: [
"0 1px 2px 0 rgba(0, 0, 0, 0.05)",
"0 1px 4px 0 rgba(0, 0, 0, 0.1)",
],
},
},
})
export default createSystem({
theme: { tokens },
})
그림자 토큰은 주로
box-shadow속성에 사용돼요.
Easings (이징)
이징 토큰은 애니메이션이나 트랜지션의 이징 함수를 나타내요. 값은 문자열 또는 cubic bezier를 나타내는 값 배열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
easings: {
// string value
easeIn: { value: "cubic-bezier(0.4, 0, 0.2, 1)" },
// array value
easeOut: { value: [0.4, 0, 0.2, 1] },
},
})
export default createSystem({
theme: { tokens },
})
이징 토큰은 주로
transition-timing-function속성에 사용돼요.
Opacity (투명도)
투명도 토큰은 요소의 투명도를 설정하는 데 도움을 줘요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
opacity: {
50: { value: 0.5 },
},
})
export default createSystem({
theme: { tokens },
})
투명도 토큰은 주로
opacity속성에 사용돼요.
Z-Index (Z-색인)
이 토큰 종류는 요소가 z축에서 위치하는 깊이를 나타내요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
zIndex: {
modal: { value: 1000 },
},
})
export default createSystem({
theme: { tokens },
})
z-index 토큰은 주로
z-index속성에 사용돼요.
Assets (에셋)
에셋 토큰은 url 또는 svg 문자열을 나타내요. 값은 문자열 또는 복합 값으로 정의돼요.
type CompositeAsset = { type: "url" | "svg"; value: string }
type Asset = string | CompositeAsset
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
tokens: {
assets: {
logo: {
value: { type: "url", value: "/static/logo.png" },
},
checkmark: {
value: { type: "svg", value: "<svg>...</svg>" },
},
},
},
})
export default createSystem({
theme: { tokens },
})
에셋 토큰은 주로
background-image속성에 사용돼요.
Durations (지속 시간)
지속 시간 토큰은 애니메이션이나 애니메이션 사이클이 완료되는 데 걸리는 시간(밀리초)을 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
durations: {
fast: { value: "100ms" },
},
})
export default createSystem({
theme: { tokens },
})
지속 시간 토큰은 주로
transition-duration과animation-duration속성에 사용돼요.
Animations (애니메이션)
애니메이션 토큰은 키프레임 애니메이션을 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
animations: {
spin: {
value: "spin 1s linear infinite",
},
},
})
export default createSystem({
theme: { tokens },
})
애니메이션 토큰은 주로
animation속성에 사용돼요.
Aspect Ratios (종횡비)
종횡비 토큰은 요소의 가로세로 비율을 나타내요. 값은 문자열로 정의돼요.
import { defineTokens } from "@chakra-ui/react"
const tokens = defineTokens({
aspectRatios: {
"1:1": { value: "1 / 1" },
"16:9": { value: "16 / 9" },
},
})
export default createSystem({
theme: { tokens },
})