0
# Typography Components
1

2
Typography components with theme-integrated styling, semantic heading support, and responsive design capabilities. All typography components extend from Box and inherit its styling props.
3

4
## Capabilities
5

6
### Text Component
7

8
Primary text component with theme-based typography controls including size, weight, color, and spacing.
9

10
```typescript { .api }
11
/**
12
 * Text component with typography controls and Box styling
13
 * @param props - Text styling and content props
14
 * @returns JSX element with typography styles applied
15
 */
16
function Text(props: TextProps): JSX.Element;
17

18
interface TextProps extends BoxProps {
19
  /** Line height from theme leading scale */
20
  leading?: keyof Theme['typography']['leading'];
21
  /** Font size preset */
22
  size?: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';
23
  /** Letter spacing from theme tracking scale */
24
  tracking?: keyof Theme['typography']['tracking'];
25
  /** Text color from theme palette */
26
  color?: keyof Theme['palette'];
27
  /** Font weight from theme fontWeight scale */
28
  weight?: keyof Theme['typography']['fontWeight'];
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { Text } from "@keystone-ui/core";
36

37
// Basic text with theme styling
38
<Text size="large" weight="bold" color="neutral900">
39
  Important heading text
40
</Text>
41

42
// Paragraph text with custom spacing
43
<Text 
44
  leading="loose" 
45
  tracking="base" 
46
  marginBottom="medium"
47
>
48
  This is a paragraph with comfortable line height and spacing.
49
</Text>
50

51
// Small caption text
52
<Text 
53
  size="xsmall" 
54
  color="neutral600" 
55
  weight="medium"
56
  tracking="tight"
57
>
58
  Caption or helper text
59
</Text>
60

61
// Responsive text sizing
62
<Text size={["small", "medium", "large"]}>
63
  Responsive text that grows with screen size
64
</Text>
65
```
66

67
### Heading Component
68

69
Generic heading component that supports different heading types with theme-based styling.
70

71
```typescript { .api }
72
/**
73
 * Generic heading component with theme-integrated styles
74
 * @param props - Heading type and styling props
75
 * @returns JSX element with heading styles applied
76
 */
77
function Heading(props: HeadingProps): JSX.Element;
78

79
interface HeadingProps extends BoxProps {
80
  /** Heading type determining visual style */
81
  type?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
82
}
83

84
/** Array of valid heading types */
85
const HeadingTypes: readonly ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
import { Heading } from "@keystone-ui/core";
92

93
// Heading with specific type
94
<Heading type="h2" marginBottom="medium">
95
  Section Title
96
</Heading>
97

98
// Heading as different element but with h3 styling
99
<Heading as="h1" type="h3">
100
  Page title with h3 visual style
101
</Heading>
102

103
// Heading with custom spacing
104
<Heading 
105
  type="h4" 
106
  marginTop="large" 
107
  marginBottom="small"
108
>
109
  Subsection Heading
110
</Heading>
111
```
112

113
### Specific Heading Components
114

115
Semantic heading components (H1-H6) that automatically apply appropriate heading styles from the theme.
116

117
```typescript { .api }
118
/**
119
 * H1 heading component with theme h1 styles
120
 * @param props - Box styling props
121
 * @returns JSX element with h1 styles
122
 */
123
function H1(props: BoxProps): JSX.Element;
124

125
/**
126
 * H2 heading component with theme h2 styles
127
 * @param props - Box styling props
128
 * @returns JSX element with h2 styles
129
 */
130
function H2(props: BoxProps): JSX.Element;
131

132
/**
133
 * H3 heading component with theme h3 styles
134
 * @param props - Box styling props
135
 * @returns JSX element with h3 styles
136
 */
137
function H3(props: BoxProps): JSX.Element;
138

139
/**
140
 * H4 heading component with theme h4 styles
141
 * @param props - Box styling props
142
 * @returns JSX element with h4 styles
143
 */
144
function H4(props: BoxProps): JSX.Element;
145

146
/**
147
 * H5 heading component with theme h5 styles
148
 * @param props - Box styling props
149
 * @returns JSX element with h5 styles
150
 */
151
function H5(props: BoxProps): JSX.Element;
152

153
/**
154
 * H6 heading component with theme h6 styles
155
 * @param props - Box styling props
156
 * @returns JSX element with h6 styles
157
 */
158
function H6(props: BoxProps): JSX.Element;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { H1, H2, H3, H4, H5, H6 } from "@keystone-ui/core";
165

166
// Semantic heading hierarchy
167
<article>
168
  <H1 marginBottom="large">Article Title</H1>
169
  
170
  <H2 marginTop="xlarge" marginBottom="medium">Section Title</H2>
171
  <H3 marginTop="large" marginBottom="small">Subsection Title</H3>
172
  
173
  <H4 marginTop="medium" marginBottom="small">Sub-subsection</H4>
174
  <H5 marginTop="small" marginBottom="xsmall">Minor Heading</H5>
175
  <H6 marginTop="small" marginBottom="xsmall">Caption Heading</H6>
176
</article>
177

178
// Headings with custom elements
179
<H2 as="legend">Form Section Legend</H2>
180
<H3 as="summary">Details Summary</H3>
181

182
// Headings with additional styling
183
<H1 
184
  textAlign="center" 
185
  padding="large" 
186
  background="neutral50"
187
  rounding="medium"
188
>
189
  Featured Title
190
</H1>
191
```
192

193
## Typography Theme Structure
194

195
The theme provides comprehensive typography scales that all components utilize:
196

197
### Font Families
198

199
```typescript
200
typography.fontFamily = {
201
  body: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif',
202
  heading: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif',
203
  monospace: 'Consolas, Menlo, Monaco, "Andale Mono", "Ubuntu Mono", monospace'
204
}
205
```
206

207
### Font Sizes
208

209
```typescript
210
typography.fontSize = {
211
  xxxsmall: '0.5rem',   // 8px
212
  xxsmall: '0.6rem',    // ~10px
213
  xsmall: '0.75rem',    // 12px
214
  small: '0.875rem',    // 14px
215
  medium: '1rem',       // 16px
216
  large: '1.125rem',    // 18px
217
  xlarge: '1.25rem',    // 20px
218
  xxlarge: '1.5rem',    // 24px
219
  xxxlarge: '1.875rem', // 30px
220
  xxxxlarge: '2.25rem', // 36px
221
  xxxxxlarge: '3rem',   // 48px
222
  xxxxxxlarge: '4rem'   // 64px
223
}
224
```
225

226
### Font Weights
227

228
```typescript
229
typography.fontWeight = {
230
  light: 300,
231
  regular: 400,
232
  medium: 500,
233
  semibold: 600,
234
  bold: 700,
235
  heavy: 800
236
}
237
```
238

239
### Line Heights (Leading)
240

241
```typescript
242
typography.leading = {
243
  tighter: 1,
244
  tight: 1.2,
245
  base: 1.4,
246
  loose: 1.6,
247
  looser: 1.8
248
}
249
```
250

251
### Letter Spacing (Tracking)
252

253
```typescript
254
typography.tracking = {
255
  tighter: '-0.02em',
256
  tight: '-0.01em',
257
  base: '0em',
258
  loose: '0.01em',
259
  looser: '0.02em'
260
}
261
```
262

263
### Heading Styles
264

265
Each heading type has predefined styles in the theme:
266

267
```typescript
268
headingStyles = {
269
  h1: { color: neutral900, family: heading, size: xxxlarge, weight: heavy, transform: 'none' },
270
  h2: { color: neutral900, family: heading, size: xxlarge, weight: bold, transform: 'none' },
271
  h3: { color: neutral900, family: heading, size: xlarge, weight: bold, transform: 'none' },
272
  h4: { color: neutral900, family: heading, size: large, weight: bold, transform: 'none' },
273
  h5: { color: neutral900, family: heading, size: medium, weight: bold, transform: 'none' },
274
  h6: { color: neutral900, family: heading, size: small, weight: bold, transform: 'uppercase' }
275
}
276
```
277

278
## Responsive Typography
279

280
Typography components support responsive sizing and styling:
281

282
```typescript
283
// Responsive font sizes
284
<Text size={["small", "medium", "large"]}>
285
  Text that scales with breakpoints
286
</Text>
287

288
// Responsive spacing
289
<H1 marginBottom={["medium", "large", "xlarge"]}>
290
  Heading with responsive margins
291
</H1>
292

293
// Responsive alignment
294
<Text textAlign={["left", "center"]}>
295
  Left-aligned on mobile, centered on larger screens
296
</Text>
297
```
298

299
## Accessibility Considerations
300

301
- All heading components maintain semantic HTML structure
302
- Font sizes use relative units (rem) to respect user preferences
303
- Color contrast follows theme color standards
304
- Text components support screen reader requirements through proper markup