Riebeckite
Menu
Color mode

Design Tokens

このページは テーマ作成の詳細 の一部で、Design Token（Color / Typography / Layout）と Semantic Token の使い方を扱います。

10. Design Tokens

Theme の中心となるのが Semantic Design Token です。

Component や Plugin は、

text
このThemeの黒
このThemeの灰色

のような Theme 固有の値を参照するのではなく、

text
本文色
背景色
Accent
Border

という意味を参照します。

Diagram source
text
flowchart LR
    UI["Component / Plugin"]
    Token["--rb-color-ink"]
    ThemeA["Theme A<br/>#202020"]
    ThemeB["Theme B<br/>#d8dee9"]
 
    UI --> Token
    ThemeA --> Token
    ThemeB --> Token

これによって Theme を交換しても Component を変更する必要がありません。

11. Color Tokens

主な Color Token は次のとおりです。

Token CSS Variable
paper --rb-color-paper
ink --rb-color-ink
muted --rb-color-muted
accent --rb-color-accent
border --rb-color-border
borderStrong --rb-color-border-strong
surface --rb-color-surface
surfaceHover --rb-color-surface-hover
overlay --rb-color-overlay
danger --rb-color-danger
success --rb-color-success
codeBackground --rb-color-code-background

12. Typography Tokens

Token CSS Variable
bodyFont --rb-font-body
headingFont --rb-font-heading
monoFont --rb-font-mono

13. Layout Tokens

Token CSS Variable
pageMaxWidth --rb-layout-page-max
articleMaxWidth --rb-layout-article-max
sidebarWidth --rb-layout-sidebar
contentGap --rb-layout-gap

CSS では次のように定義します。

css
@layer base {
  :is(:root, .rb-theme-root)
  [data-theme-name="example"] {
    --rb-color-paper: #fafafa;
    --rb-color-ink: #202020;
    --rb-color-accent: #555;
 
    --rb-font-body:
      system-ui, sans-serif;
 
    --rb-layout-article-max: 48rem;
  }
}

Token 名と CSS Variable 名が完全に同じとは限りません。

たとえば、

text
borderStrong
  → --rb-color-border-strong
 
surfaceHover
  → --rb-color-surface-hover
 
codeBackground
  → --rb-color-code-background

のように kebab-case へ変換されます。

14. Semantic Token を使う

Plugin や Component でも Semantic Token を利用してください。

css
/* Good */
 
.rr-example {
  color:
    var(--rb-color-ink);
 
  background:
    var(--rb-color-surface);
}

次のように Theme 固有の色を直接指定することは避けます。

css
/* Avoid */
 
.rr-example {
  color: #171717;
  background: #f6efe2;
}

後者では Theme を交換しても Plugin の色が変わりません。

Plugin 固有の意味を持つ Token が必要なら、

text
--rr-*

を Plugin 側で定義できます。

必要に応じて、

css
--rr-example-background:
  var(--rb-color-surface);

のように --rb-* を fallback として利用できます。

History

1 changesCollapseExpand
1 + ---
2 + title: Design Tokens
3 + sidebar:
4 + label: Design Tokens
5 + order: 30
6 + ---
7 + # Design Tokens
8 +
9 + このページは [テーマ作成の詳細](../theme-system.ja.md) の一部で、Design Token（Color / Typography / Layout）と Semantic Token の使い方を扱います。
10 +
11 + ## 10. Design Tokens
12 +
13 + Theme の中心となるのが Semantic Design Token です。
14 +
15 + Component や Plugin は、
16 +
17 + ```text id="9vwkwf"
18 + このThemeの黒
19 + このThemeの灰色
20 + ```
21 +
22 + のような Theme 固有の値を参照するのではなく、
23 +
24 + ```text id="zfg9dh"
25 + 本文色
26 + 背景色
27 + Accent
28 + Border
29 + ```
30 +
31 + という**意味**を参照します。
32 +
33 + ```mermaid id="e6x8ou"
34 + flowchart LR
35 + UI["Component / Plugin"]
36 + Token["--rb-color-ink"]
37 + ThemeA["Theme A<br/>#202020"]
38 + ThemeB["Theme B<br/>#d8dee9"]
39 +
40 + UI --> Token
41 + ThemeA --> Token
42 + ThemeB --> Token
43 + ```
44 +
45 + これによって Theme を交換しても Component を変更する必要がありません。
46 +
47 +
48 + ## 11. Color Tokens
49 +
50 + 主な Color Token は次のとおりです。
51 +
52 + | Token | CSS Variable |
53 + | --- | --- |
54 + | `paper` | `--rb-color-paper` |
55 + | `ink` | `--rb-color-ink` |
56 + | `muted` | `--rb-color-muted` |
57 + | `accent` | `--rb-color-accent` |
58 + | `border` | `--rb-color-border` |
59 + | `borderStrong` | `--rb-color-border-strong` |
60 + | `surface` | `--rb-color-surface` |
61 + | `surfaceHover` | `--rb-color-surface-hover` |
62 + | `overlay` | `--rb-color-overlay` |
63 + | `danger` | `--rb-color-danger` |
64 + | `success` | `--rb-color-success` |
65 + | `codeBackground` | `--rb-color-code-background` |
66 +
67 +
68 + ## 12. Typography Tokens
69 +
70 + | Token | CSS Variable |
71 + | --- | --- |
72 + | `bodyFont` | `--rb-font-body` |
73 + | `headingFont` | `--rb-font-heading` |
74 + | `monoFont` | `--rb-font-mono` |
75 +
76 +
77 + ## 13. Layout Tokens
78 +
79 + | Token | CSS Variable |
80 + | --- | --- |
81 + | `pageMaxWidth` | `--rb-layout-page-max` |
82 + | `articleMaxWidth` | `--rb-layout-article-max` |
83 + | `sidebarWidth` | `--rb-layout-sidebar` |
84 + | `contentGap` | `--rb-layout-gap` |
85 +
86 + CSS では次のように定義します。
87 +
88 + ```css id="u6csj3"
89 + @layer base {
90 + :is(:root, .rb-theme-root)
91 + [data-theme-name="example"] {
92 + --rb-color-paper: #fafafa;
93 + --rb-color-ink: #202020;
94 + --rb-color-accent: #555;
95 +
96 + --rb-font-body:
97 + system-ui, sans-serif;
98 +
99 + --rb-layout-article-max: 48rem;
100 + }
101 + }
102 + ```
103 +
104 + Token 名と CSS Variable 名が完全に同じとは限りません。
105 +
106 + たとえば、
107 +
108 + ```text id="avjyrb"
109 + borderStrong
110 + → --rb-color-border-strong
111 +
112 + surfaceHover
113 + → --rb-color-surface-hover
114 +
115 + codeBackground
116 + → --rb-color-code-background
117 + ```
118 +
119 + のように kebab-case へ変換されます。
120 +
121 +
122 + ## 14. Semantic Token を使う
123 +
124 + Plugin や Component でも Semantic Token を利用してください。
125 +
126 + ```css id="0ld7xq"
127 + /* Good */
128 +
129 + .rr-example {
130 + color:
131 + var(--rb-color-ink);
132 +
133 + background:
134 + var(--rb-color-surface);
135 + }
136 + ```
137 +
138 + 次のように Theme 固有の色を直接指定することは避けます。
139 +
140 + ```css id="5tkz4j"
141 + /* Avoid */
142 +
143 + .rr-example {
144 + color: #171717;
145 + background: #f6efe2;
146 + }
147 + ```
148 +
149 + 後者では Theme を交換しても Plugin の色が変わりません。
150 +
151 + Plugin 固有の意味を持つ Token が必要なら、
152 +
153 + ```text id="fbfuw6"
154 + --rr-*
155 + ```
156 +
157 + を Plugin 側で定義できます。
158 +
159 + 必要に応じて、
160 +
161 + ```css id="8qr5yn"
162 + --rr-example-background:
163 + var(--rb-color-surface);
164 + ```
165 +
166 + のように `--rb-*` を fallback として利用できます。
167 +