0
# Doc Block Components
1

2
Embeddable React components for displaying design tokens in Storybook documentation pages and stories. Perfect for design system documentation and token showcases with flexible configuration options.
3

4
## Capabilities
5

6
### DesignTokenDocBlock Component
7

8
Main component for embedding design token documentation in Storybook docs pages. Automatically discovers and displays tokens from the specified category with customizable presentation options.
9

10
```typescript { .api }
11
/**
12
 * Main doc block component for embedding in Storybook docs pages
13
 * @param props - Configuration options for the doc block
14
 * @returns JSX element containing the token documentation
15
 */
16
function DesignTokenDocBlock(props: DesignTokenDocBlockProps): JSX.Element;
17

18
interface DesignTokenDocBlockProps {
19
  /** Name of the token category to display */
20
  categoryName: string;
21
  /** Maximum height of the container in pixels (default: 600) */
22
  maxHeight?: number;
23
  /** Whether to show the token value column (default: true) */
24
  showValueColumn?: boolean;
25
  /** Display type for tokens */
26
  viewType: TokenViewType;
27
  /** Array of token names to filter by */
28
  filterNames?: string[];
29
  /** Map of token names to usage examples */
30
  usageMap?: Record<string, string[]>;
31
  /** Theme override for styling */
32
  theme?: string;
33
  /** Enable search functionality (default: true) */
34
  showSearch?: boolean;
35
  /** Number of items per page for pagination */
36
  pageSize?: number;
37
  /** Custom presenter components */
38
  presenters?: PresenterMapType;
39
}
40

41
type TokenViewType = "table" | "card";
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import { DesignTokenDocBlock } from "storybook-design-token";
48

49
// Basic usage in Storybook docs
50
<DesignTokenDocBlock
51
  categoryName="Colors"
52
  viewType="table"
53
/>
54

55
// Advanced configuration with filtering and custom presenters
56
<DesignTokenDocBlock
57
  categoryName="Typography"
58
  viewType="card"
59
  maxHeight={800}
60
  showSearch={true}
61
  pageSize={20}
62
  filterNames={["primary", "secondary", "accent"]}
63
  usageMap={{
64
    "primary-color": ["background-color: var(--primary-color)", "color: var(--primary-color)"],
65
    "heading-font": ["font-family: var(--heading-font)", "font: var(--heading-font)"]
66
  }}
67
  presenters={{
68
    "CustomColor": MyCustomColorPresenter
69
  }}
70
/>
71

72
// Embedded in MDX documentation
73
export const TokenShowcase = () => (
74
  <DesignTokenDocBlock
75
    categoryName="Spacing" 
76
    viewType="table"
77
    showValueColumn={true}
78
    theme="dark"
79
  />
80
);
81
```
82

83
### Story Parameter Configuration
84

85
Configure the addon behavior at story level using the `designToken` parameter key.
86

87
```typescript { .api }
88
interface StoryParameters {
89
  designToken?: Config;
90
}
91

92
interface Config {
93
  /** Enable search functionality */
94
  showSearch?: boolean;
95
  /** Default selected tab name */
96
  defaultTab?: string;
97
  /** Custom CSS injection */
98
  styleInjection?: string;
99
  /** Items per page */
100
  pageSize?: number;
101
  /** Custom presenter components */
102
  presenters?: PresenterMapType;
103
  /** Visible tab names filter */
104
  tabs?: string[];
105
}
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
// Story with custom configuration
112
export const MyStory = {
113
  parameters: {
114
    designToken: {
115
      showSearch: true,
116
      defaultTab: "Colors",
117
      pageSize: 15,
118
      tabs: ["Colors", "Typography", "Spacing"],
119
      styleInjection: `
120
        .design-token-container { 
121
          border: 1px solid #ccc; 
122
          border-radius: 8px; 
123
        }
124
      `
125
    }
126
  }
127
};
128

129
// Global configuration in preview.js
130
export default {
131
  parameters: {
132
    designToken: {
133
      showSearch: true,
134
      pageSize: 10,
135
      presenters: {
136
        "Color": CustomColorPresenter,
137
        "FontSize": CustomFontSizePresenter
138
      }
139
    }
140
  }
141
};
142
```
143

144
### Custom Presenter Integration
145

146
Extend the visual presentation system with custom presenter components for specialized token types.
147

148
```typescript { .api }
149
interface PresenterMapType {
150
  /** Map of presenter names to React components */
151
  [key: string]: React.FunctionComponent<PresenterProps> | React.ComponentClass<PresenterProps>;
152
}
153

154
interface PresenterProps {
155
  /** Token data to present */
156
  token: Token;
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import React from "react";
164
import { PresenterProps } from "storybook-design-token";
165

166
// Custom presenter component
167
const CustomColorPresenter: React.FC<PresenterProps> = ({ token }) => (
168
  <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
169
    <div
170
      style={{
171
        width: "32px",
172
        height: "32px",
173
        backgroundColor: token.value,
174
        borderRadius: "4px",
175
        border: "1px solid #ccc"
176
      }}
177
    />
178
    <div>
179
      <div style={{ fontWeight: "bold" }}>{token.name}</div>
180
      <div style={{ fontSize: "12px", color: "#666" }}>{token.value}</div>
181
    </div>
182
  </div>
183
);
184

185
// Usage in doc block
186
<DesignTokenDocBlock
187
  categoryName="CustomColors"
188
  viewType="table"
189
  presenters={{
190
    "Color": CustomColorPresenter
191
  }}
192
/>
193
```