0
# Token Presenters
1

2
Visual presentation components for different types of design tokens including colors, typography, spacing, animations, and more. The system includes 15 built-in presenters and supports custom presenter extensions for specialized token types.
3

4
## Capabilities
5

6
### TokenPreview Component
7

8
Main component for rendering individual design tokens with appropriate visual presentation based on the token type.
9

10
```typescript { .api }
11
/**
12
 * Renders a design token with appropriate visual presentation
13
 * @param props - Token and presenter configuration
14
 * @returns JSX element with token visualization
15
 */
16
function TokenPreview(props: TokenPreviewProps): JSX.Element;
17

18
interface TokenPreviewProps {
19
  /** Token data to display */
20
  token: Token;
21
  /** Custom presenter components to override defaults */
22
  presenters?: PresenterMapType;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { TokenPreview, Token, TokenPresenter } from "storybook-design-token";
30

31
const colorToken: Token = {
32
  name: "primary-blue",
33
  value: "#0066cc",
34
  rawValue: "$primary-blue",
35
  presenter: TokenPresenter.COLOR,
36
  sourceType: TokenSourceType.SCSS,
37
  sourcePath: "./tokens/colors.scss"
38
};
39

40
// Basic token preview
41
<TokenPreview token={colorToken} />
42

43
// With custom presenter override
44
<TokenPreview 
45
  token={colorToken}
46
  presenters={{ "Color": MyCustomColorPresenter }}
47
/>
48
```
49

50
### Built-in Presenter Components
51

52
#### Color and Visual Presenters
53

54
Visual presentation for color values, opacity, and gradients.
55

56
```typescript { .api }
57
/** Displays color swatches with hex/rgb values */
58
function ColorPresenter(props: PresenterProps): JSX.Element;
59

60
/** Shows opacity values with visual transparency examples */
61
function OpacityPresenter(props: PresenterProps): JSX.Element;
62
```
63

64
#### Typography Presenters
65

66
Font-related token presentations showing actual typeface examples and measurements.
67

68
```typescript { .api }
69
/** Displays font family names with sample text */
70
function FontFamilyPresenter(props: PresenterProps): JSX.Element;
71

72
/** Shows font sizes with scaled text examples */
73
function FontSizePresenter(props: PresenterProps): JSX.Element;
74

75
/** Demonstrates font weights with visual examples */
76
function FontWeightPresenter(props: PresenterProps): JSX.Element;
77

78
/** Visualizes line height with text examples */
79
function LineHeightPresenter(props: PresenterProps): JSX.Element;
80

81
/** Shows letter spacing with text examples */
82
function LetterSpacingPresenter(props: PresenterProps): JSX.Element;
83
```
84

85
#### Layout and Spacing Presenters
86

87
Visual representations for spacing, borders, shadows, and layout properties.
88

89
```typescript { .api }
90
/** Displays spacing values with visual boxes */
91
function SpacingPresenter(props: PresenterProps): JSX.Element;
92

93
/** Shows border styles and properties */
94
function BorderPresenter(props: PresenterProps): JSX.Element;
95

96
/** Visualizes border radius with rounded shapes */
97
function BorderRadiusPresenter(props: PresenterProps): JSX.Element;
98

99
/** Displays shadow effects with examples */
100
function ShadowPresenter(props: PresenterProps): JSX.Element;
101
```
102

103
#### Animation and Motion Presenters
104

105
Presentation for animation-related tokens including timing and easing functions.
106

107
```typescript { .api }
108
/** Shows animation properties with live previews */
109
function AnimationPresenter(props: PresenterProps): JSX.Element;
110

111
/** Visualizes easing functions with curve examples */
112
function EasingPresenter(props: PresenterProps): JSX.Element;
113
```
114

115
#### Asset Presenters
116

117
Presentation for media assets including images and SVG icons.
118

119
```typescript { .api }
120
/** Renders SVG icons with metadata */
121
function SvgPresenter(props: PresenterProps): JSX.Element;
122

123
/** Displays image assets with dimensions */
124
function ImagePresenter(props: PresenterProps): JSX.Element;
125

126
/** Fallback presenter for undefined or empty tokens */
127
function EmptyPresenter(props: PresenterProps): JSX.Element;
128
```
129

130
### Custom Presenter Development
131

132
Create custom presenter components for specialized token types or unique presentation requirements.
133

134
```typescript { .api }
135
interface PresenterProps {
136
  /** Token data containing all relevant information */
137
  token: Token;
138
}
139

140
interface PresenterMapType {
141
  /** Map of presenter names to React components */
142
  [key: string]: React.FunctionComponent<PresenterProps> | React.ComponentClass<PresenterProps>;
143
}
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
import React from "react";
150
import { PresenterProps } from "storybook-design-token";
151

152
// Custom gradient presenter
153
const GradientPresenter: React.FC<PresenterProps> = ({ token }) => {
154
  return (
155
    <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
156
      <div
157
        style={{
158
          width: "200px",
159
          height: "40px",
160
          background: token.value,
161
          borderRadius: "4px",
162
          border: "1px solid #ddd"
163
        }}
164
      />
165
      <div>
166
        <strong>{token.name}</strong>
167
        <br />
168
        <code style={{ fontSize: "12px", color: "#666" }}>
169
          {token.value}
170
        </code>
171
        {token.description && (
172
          <p style={{ fontSize: "12px", margin: "4px 0 0" }}>
173
            {token.description}
174
          </p>
175
        )}
176
      </div>
177
    </div>
178
  );
179
};
180

181
// Custom dimension presenter for width/height tokens
182
const DimensionPresenter: React.FC<PresenterProps> = ({ token }) => {
183
  const pixelValue = parseInt(token.value.replace(/[^\d]/g, ""));
184
  
185
  return (
186
    <div style={{ display: "flex", alignItems: "center", gap: "12px" }}>
187
      <div
188
        style={{
189
          width: pixelValue > 100 ? "100px" : `${pixelValue}px`,
190
          height: "20px",
191
          backgroundColor: "#e3f2fd",
192
          border: "2px solid #2196f3",
193
          position: "relative"
194
        }}
195
      >
196
        <span style={{
197
          position: "absolute",
198
          top: "-20px",
199
          left: "0",
200
          fontSize: "10px",
201
          color: "#666"
202
        }}>
203
          {token.value}
204
        </span>
205
      </div>
206
      <div>
207
        <strong>{token.name}</strong>
208
        <br />
209
        <span style={{ fontSize: "12px", color: "#666" }}>
210
          {token.description || "Dimension value"}
211
        </span>
212
      </div>
213
    </div>
214
  );
215
};
216

217
// Register custom presenters
218
const customPresenters = {
219
  "Gradient": GradientPresenter,
220
  "Dimension": DimensionPresenter
221
};
222

223
// Use in TokenPreview or DesignTokenDocBlock
224
<TokenPreview 
225
  token={myToken} 
226
  presenters={customPresenters}
227
/>
228
```
229

230
### Presenter System Architecture
231

232
The presenter system automatically selects the appropriate presenter based on the token's `presenter` property, falling back to the `EmptyPresenter` for undefined types.
233

234
```typescript { .api }
235
/** Built-in presenter mapping */
236
const PresenterMap: PresenterMapType = {
237
  [`${TokenPresenter.ANIMATION}`]: AnimationPresenter,
238
  [`${TokenPresenter.BORDER}`]: BorderPresenter,
239
  [`${TokenPresenter.BORDER_RADIUS}`]: BorderRadiusPresenter,
240
  [`${TokenPresenter.COLOR}`]: ColorPresenter,
241
  [`${TokenPresenter.EASING}`]: EasingPresenter,
242
  [`${TokenPresenter.FONT_FAMILY}`]: FontFamilyPresenter,
243
  [`${TokenPresenter.FONT_SIZE}`]: FontSizePresenter,
244
  [`${TokenPresenter.FONT_WEIGHT}`]: FontWeightPresenter,
245
  [`${TokenPresenter.LINE_HEIGHT}`]: LineHeightPresenter,
246
  [`${TokenPresenter.LETTER_SPACING}`]: LetterSpacingPresenter,
247
  [`${TokenPresenter.OPACITY}`]: OpacityPresenter,
248
  [`${TokenPresenter.SHADOW}`]: ShadowPresenter,
249
  [`${TokenPresenter.SPACING}`]: SpacingPresenter,
250
  [`${TokenPresenter.SVG}`]: SvgPresenter,
251
  [`${TokenPresenter.IMAGE}`]: ImagePresenter
252
};
253
```
254

255
**Selection Logic:**
256

257
1. Check if token has a `presenter` property
258
2. Look up presenter in combined map (custom presenters override built-in ones)
259
3. Fall back to `EmptyPresenter` if no match found
260
4. Render the selected presenter component with token data