0
# @keystone-ui/core
1
2
@keystone-ui/core is a foundational design system library that provides core UI primitives, theming capabilities, and layout components for building KeystoneJS applications. Built on React and Emotion, it offers a comprehensive set of components with responsive design support, accessibility features, and a complete theme system.
3
4
## Package Information
5
6
- **Package Name**: @keystone-ui/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @keystone-ui/core`
10
11
## Core Imports
12
13
```typescript
14
import { Box, Text, Stack, Core, useTheme } from "@keystone-ui/core";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { Box, Text, Stack, Core, useTheme } = require("@keystone-ui/core");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { Core, Box, Text, Stack, ThemeProvider } from "@keystone-ui/core";
27
28
// Import the default theme from its specific location
29
// Note: The default theme is not exported from the main package entry point
30
// You need to import it directly from the themes directory
31
import { theme } from "@keystone-ui/core/themes/default";
32
33
// Or create your own theme following this structure
34
const customTheme = {
35
spacing: { medium: 16, large: 24 },
36
colors: { neutral100: '#f5f5f5', neutral700: '#6b7280' },
37
radii: { medium: 8 },
38
typography: { fontSize: { large: '1.125rem' }, fontWeight: { bold: 700 } }
39
};
40
41
function App() {
42
return (
43
<ThemeProvider theme={theme}>
44
<Core>
45
<Stack gap="medium">
46
<Box padding="large" background="neutral100" rounding="medium">
47
<Text size="large" weight="bold">Welcome</Text>
48
<Text color="neutral700">
49
This is a simple example using @keystone-ui/core components.
50
</Text>
51
</Box>
52
</Stack>
53
</Core>
54
</ThemeProvider>
55
);
56
}
57
```
58
59
## Architecture
60
61
@keystone-ui/core is built around several key architectural principles:
62
63
- **Polymorphic Components**: Most components support an `as` prop allowing you to change the underlying element or component
64
- **Responsive Design**: Components accept responsive prop values as arrays or objects that map to breakpoints
65
- **Theme Integration**: All components automatically consume theme values through React Context
66
- **Emotion CSS-in-JS**: Built on Emotion for performant, dynamic styling with excellent TypeScript support
67
- **Design System Foundation**: Complete design token system including colors, spacing, typography, and breakpoints
68
69
## Capabilities
70
71
### Layout Components
72
73
Fundamental layout primitives for building flexible, responsive interfaces with consistent spacing and alignment.
74
75
```typescript { .api }
76
// Core layout component with comprehensive styling props
77
function Box(props: BoxProps): JSX.Element;
78
79
// Flexible vertical/horizontal layout with gaps and dividers
80
function Stack(props: StackProps): JSX.Element;
81
82
// Horizontal layout with wrapping support
83
function Inline(props: InlineProps): JSX.Element;
84
85
interface BoxProps {
86
// Color props
87
background?: ResponsiveProp<keyof Theme['palette']>;
88
foreground?: ResponsiveProp<keyof Theme['palette']>;
89
90
// Spacing props
91
margin?: ResponsiveProp<keyof Theme['spacing']>;
92
padding?: ResponsiveProp<keyof Theme['spacing']>;
93
94
// Border radius props
95
rounding?: ResponsiveProp<keyof Theme['radii']>;
96
97
// Layout props
98
width?: ResponsiveProp<string | number>;
99
height?: ResponsiveProp<string | number>;
100
textAlign?: ResponsiveProp<'left' | 'right' | 'center' | 'justify'>;
101
102
// Polymorphic as prop
103
as?: ElementType;
104
}
105
```
106
107
[Layout Components](./layout-components.md)
108
109
### Typography Components
110
111
Typography components with theme-integrated styling and semantic heading support.
112
113
```typescript { .api }
114
// Text component with typography controls
115
function Text(props: TextProps): JSX.Element;
116
117
// Generic heading component
118
function Heading(props: HeadingProps): JSX.Element;
119
120
// Specific heading level components
121
function H1(props: BoxProps): JSX.Element;
122
function H2(props: BoxProps): JSX.Element;
123
function H3(props: BoxProps): JSX.Element;
124
function H4(props: BoxProps): JSX.Element;
125
function H5(props: BoxProps): JSX.Element;
126
function H6(props: BoxProps): JSX.Element;
127
128
interface TextProps extends BoxProps {
129
leading?: keyof Theme['typography']['leading'];
130
size?: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';
131
tracking?: keyof Theme['typography']['tracking'];
132
color?: keyof Theme['palette'];
133
weight?: keyof Theme['typography']['fontWeight'];
134
}
135
```
136
137
[Typography Components](./typography-components.md)
138
139
### Theme System
140
141
Complete theming system with React Context, design tokens, and responsive utilities.
142
143
```typescript { .api }
144
// Theme context provider
145
function ThemeProvider(props: { theme: Theme; children: ReactNode }): JSX.Element;
146
147
// Hook to access current theme
148
function useTheme(): Theme;
149
150
// React context for theme
151
const ThemeContext: React.Context<{ theme: Theme }>;
152
153
// Default theme object
154
const theme: Theme;
155
156
// Responsive utilities hook
157
function useMediaQuery(): {
158
mq: (styles: any) => any;
159
minBreak: (key: keyof Theme['breakpoints']) => string;
160
maxBreak: (key: keyof Theme['breakpoints']) => string;
161
};
162
```
163
164
[Theme System](./theme-system.md)
165
166
### Core Application Wrapper
167
168
Application wrapper component that provides global styles and normalization.
169
170
```typescript { .api }
171
// Root application wrapper with global styles
172
function Core(props: CoreProps): JSX.Element;
173
174
interface CoreProps {
175
children: ReactNode;
176
includeNormalize?: boolean;
177
optimizeLegibility?: boolean;
178
}
179
```
180
181
[Core Application Wrapper](./core-wrapper.md)
182
183
### Utility Components and Functions
184
185
Accessibility helpers, utility functions, and additional UI components.
186
187
```typescript { .api }
188
// Screen reader only content component
189
function VisuallyHidden(props: { children?: ReactNode; as?: ElementType }): JSX.Element;
190
191
// Visual separator component
192
function Divider(props: DividerProps): JSX.Element;
193
194
// Centering layout component
195
function Center(props: CenterProps): JSX.Element;
196
197
// Link component with theme integration
198
function Link(props: { as?: ElementType }): JSX.Element;
199
200
// Polymorphic component helper
201
function forwardRefWithAs<DefaultElementType extends ElementType, BaseProps>(
202
render: (props: BaseProps & { as?: ElementType }, ref: React.Ref<any>) => ReactNode
203
): CompWithAsProp<BaseProps, DefaultElementType>;
204
205
interface DividerProps extends MarginProps {
206
color?: ResponsiveProp<keyof Theme['palette']>;
207
orientation?: 'horizontal' | 'vertical';
208
}
209
210
interface CenterProps extends BoxProps {
211
fillView?: boolean;
212
}
213
```
214
215
[Utility Components](./utility-components.md)
216
217
### Emotion Integration
218
219
Re-exported Emotion functions for consistent CSS-in-JS usage across the ecosystem.
220
221
```typescript { .api }
222
// CSS styling function
223
function css(template: TemplateStringsArray, ...args: any[]): SerializedStyles;
224
225
// JSX pragma for emotion
226
function jsx(type: any, props: any, ...children: any[]): any;
227
228
// CSS keyframes for animations
229
function keyframes(template: TemplateStringsArray, ...args: any[]): Keyframes;
230
231
// Global CSS styles component
232
function Global(props: { styles: any }): JSX.Element;
233
234
// Render prop for dynamic class names
235
function ClassNames(props: { children: (cx: any) => ReactNode }): JSX.Element;
236
237
// CSS normalization styles for consistent cross-browser rendering
238
const normalize: SerializedStyles;
239
```
240
241
[Emotion Integration](./emotion-integration.md)
242
243
### State Management Hooks
244
245
Utilities for managing component state in controlled/uncontrolled patterns.
246
247
```typescript { .api }
248
// Hook for controlled/uncontrolled component patterns
249
function useManagedState<V, E = ChangeEvent>(
250
controlledValue: V | undefined,
251
defaultValue: V,
252
onChange: ManagedChangeHandler<V, E> | undefined
253
): [V, ManagedChangeHandler<V, E>];
254
255
type ManagedChangeHandler<V = string, E = ChangeEvent> = (value: V, event: E) => void;
256
257
// Utility functions
258
function devWarning(condition: boolean, message: string): void;
259
function makeId(...args: (string | number | null | undefined)[]): string;
260
function useId(idFromProps?: string | null): string | undefined;
261
```
262
263
[State Management](./state-management.md)
264
265
## Types
266
267
```typescript { .api }
268
// Main theme type derived from default theme
269
type Theme = typeof theme;
270
271
// Responsive prop type for breakpoint-aware values
272
type ResponsiveProp<T> = T | readonly (T | null)[];
273
274
// Component prop types
275
type ColorProps = {
276
background?: ResponsiveProp<keyof Theme['palette']>;
277
foreground?: ResponsiveProp<keyof Theme['palette']>;
278
};
279
280
type RadiiProps = {
281
rounding?: ResponsiveProp<keyof Theme['radii']>;
282
roundingBottom?: ResponsiveProp<keyof Theme['radii']>;
283
roundingLeft?: ResponsiveProp<keyof Theme['radii']>;
284
roundingRight?: ResponsiveProp<keyof Theme['radii']>;
285
roundingTop?: ResponsiveProp<keyof Theme['radii']>;
286
};
287
288
type MarginProps = {
289
margin?: ResponsiveProp<keyof Theme['spacing']>;
290
marginTop?: ResponsiveProp<keyof Theme['spacing']>;
291
marginRight?: ResponsiveProp<keyof Theme['spacing']>;
292
marginBottom?: ResponsiveProp<keyof Theme['spacing']>;
293
marginLeft?: ResponsiveProp<keyof Theme['spacing']>;
294
marginY?: ResponsiveProp<keyof Theme['spacing']>;
295
marginX?: ResponsiveProp<keyof Theme['spacing']>;
296
};
297
298
type PaddingProps = {
299
padding?: ResponsiveProp<keyof Theme['spacing']>;
300
paddingTop?: ResponsiveProp<keyof Theme['spacing']>;
301
paddingRight?: ResponsiveProp<keyof Theme['spacing']>;
302
paddingBottom?: ResponsiveProp<keyof Theme['spacing']>;
303
paddingLeft?: ResponsiveProp<keyof Theme['spacing']>;
304
paddingY?: ResponsiveProp<keyof Theme['spacing']>;
305
paddingX?: ResponsiveProp<keyof Theme['spacing']>;
306
};
307
308
type BoxProps = ColorProps & RadiiProps & MarginProps & PaddingProps & {
309
textAlign?: ResponsiveProp<'left' | 'right' | 'center' | 'justify' | 'start' | 'end'>;
310
height?: ResponsiveProp<string | number>;
311
width?: ResponsiveProp<string | number>;
312
};
313
```