0
# Core Application Wrapper
1

2
The Core component serves as the root application wrapper that provides global styles, CSS normalization, and foundational theme integration for KeystoneJS applications.
3

4
## Capabilities
5

6
### Core Component
7

8
Root application wrapper component that applies global styles, CSS normalization, and theme-based foundational styling to the entire application.
9

10
```typescript { .api }
11
/**
12
 * Root application wrapper with global styles and normalization
13
 * @param props - Core configuration and children props
14
 * @returns JSX element providing global application foundation
15
 */
16
function Core(props: CoreProps): JSX.Element;
17

18
interface CoreProps {
19
  /** Child components of the application */
20
  children: ReactNode;
21
  /** Whether to include CSS normalization styles */
22
  includeNormalize?: boolean;
23
  /** Whether to optimize text rendering with CSS properties */
24
  optimizeLegibility?: boolean;
25
}
26
```
27

28
**Default Values:**
29
- `includeNormalize`: `true`
30
- `optimizeLegibility`: `true`
31

32
**Usage Examples:**
33

34
```typescript
35
import { Core, ThemeProvider, theme } from "@keystone-ui/core";
36

37
// Basic setup with default options
38
function App() {
39
  return (
40
    <ThemeProvider theme={theme}>
41
      <Core>
42
        <div>Your application content</div>
43
      </Core>
44
    </ThemeProvider>
45
  );
46
}
47

48
// Custom configuration
49
function App() {
50
  return (
51
    <ThemeProvider theme={theme}>
52
      <Core 
53
        includeNormalize={false}
54
        optimizeLegibility={false}
55
      >
56
        <div>Your application content</div>
57
      </Core>
58
    </ThemeProvider>
59
  );
60
}
61

62
// Typical KeystoneJS setup
63
function KeystoneApp() {
64
  return (
65
    <ThemeProvider theme={theme}>
66
      <Core>
67
        <header>Navigation</header>
68
        <main>
69
          <h1>Dashboard</h1>
70
          <p>Application content here</p>
71
        </main>
72
        <footer>Footer content</footer>
73
      </Core>
74
    </ThemeProvider>
75
  );
76
}
77
```
78

79
## Global Styles Applied
80

81
### CSS Normalization
82

83
When `includeNormalize` is `true` (default), Core applies normalize.css v8.0.1 to ensure consistent styling across browsers. This includes:
84

85
- Consistent margins and padding reset
86
- Standardized form element styling
87
- Cross-browser typography normalization
88
- Focus outline removal (replaced with theme-based focus styles)
89

90
**Note:** The normalization styles are also available as a standalone export if needed:
91

92
```typescript
93
import { normalize } from "@keystone-ui/core";
94
// normalize is an Emotion CSS object containing normalize.css v8.0.1
95
```
96

97
### Base Typography Styles
98

99
Core applies foundational typography styles using theme values:
100

101
```css
102
html {
103
  font-size: initial !important; /* Respects user font-size preferences */
104
}
105

106
body {
107
  background-color: theme.colors.background;
108
  color: theme.colors.foreground;
109
  font-size: 1rem;
110
  font-weight: theme.typography.fontWeight.regular;
111
  line-height: theme.typography.leading.base;
112
  font-family: theme.typography.fontFamily.body;
113
}
114
```
115

116
### Link Styling
117

118
Default link colors from the theme:
119

120
```css
121
a {
122
  color: theme.colors.linkColor;
123
}
124

125
a:hover {
126
  color: theme.colors.linkHoverColor;
127
}
128
```
129

130
### Box Model Reset
131

132
Universal box-sizing and border defaults:
133

134
```css
135
*, ::before, ::after {
136
  box-sizing: border-box;
137
  border-width: 0;
138
  border-style: solid;
139
  border-color: theme.colors.border;
140
}
141
```
142

143
### Text Rendering Optimization
144

145
When `optimizeLegibility` is `true` (default), applies text rendering optimizations:
146

147
```css
148
body {
149
  text-rendering: optimizeLegibility;
150
  -webkit-font-smoothing: antialiased;
151
  -moz-osx-font-smoothing: grayscale;
152
}
153
```
154

155
## Integration with Theme System
156

157
Core automatically consumes theme values through the `useTheme` hook, ensuring that global styles reflect the current theme configuration:
158

159
```typescript
160
import { Core, ThemeProvider } from "@keystone-ui/core";
161

162
const customTheme = {
163
  ...theme,
164
  colors: {
165
    ...theme.colors,
166
    background: '#f8f9fa',
167
    foreground: '#2d3748'
168
  },
169
  typography: {
170
    ...theme.typography,
171
    fontFamily: {
172
      ...theme.typography.fontFamily,
173
      body: 'Inter, system-ui, sans-serif'
174
    }
175
  }
176
};
177

178
// Custom theme values will be applied globally by Core
179
<ThemeProvider theme={customTheme}>
180
  <Core>
181
    <App />
182
  </Core>
183
</ThemeProvider>
184
```
185

186
## Best Practices
187

188
### Application Structure
189

190
Place Core as close to the root as possible, typically inside ThemeProvider:
191

192
```typescript
193
// ✓ Recommended structure
194
<ThemeProvider theme={theme}>
195
  <Core>
196
    <Router>
197
      <App />
198
    </Router>
199
  </Core>
200
</ThemeProvider>
201

202
// ✗ Avoid nesting Core deeply
203
<ThemeProvider theme={theme}>
204
  <Router>
205
    <App>
206
      <Core>
207
        <Content />
208
      </Core>
209
    </App>
210
  </Router>
211
</ThemeProvider>
212
```
213

214
### CSS Reset Considerations
215

216
If your application already includes a CSS reset or normalization library:
217

218
```typescript
219
// Disable built-in normalization
220
<Core includeNormalize={false}>
221
  <App />
222
</Core>
223
```
224

225
### Performance Considerations
226

227
Text rendering optimization can impact performance on some devices:
228

229
```typescript
230
// Disable for performance-critical applications
231
<Core optimizeLegibility={false}>
232
  <App />
233
</Core>
234
```
235

236
### Server-Side Rendering
237

238
Core is fully compatible with server-side rendering and will apply styles consistently across client and server:
239

240
```typescript
241
// SSR-compatible setup
242
import { renderToString } from 'react-dom/server';
243

244
const html = renderToString(
245
  <ThemeProvider theme={theme}>
246
    <Core>
247
      <App />
248
    </Core>
249
  </ThemeProvider>
250
);
251
```
252

253
## Relationship to Other Components
254

255
Core provides the foundation that all other @keystone-ui/core components build upon:
256

257
- **Theme Integration**: Ensures theme values are available globally
258
- **Typography Base**: Provides font family and sizing foundation for Text and Heading components  
259
- **Color Foundation**: Establishes default text and background colors
260
- **Box Model**: Sets up consistent box-sizing for layout components
261
- **Focus Management**: Establishes focus ring styles used by interactive components
262

263
Core should always be used in conjunction with ThemeProvider to provide complete functionality.