Core Components

1---
2name: core-components
3description: Core component library and design system patterns. Use when building UI, using design tokens, or working with the component library.
4---
5 
6# Core Components
7 
8## Design System Overview
9 
10Use components from your core library instead of raw platform components. This ensures consistent styling and behavior.
11 
12## Design Tokens
13 
14**NEVER hard-code values. Always use design tokens.**
15 
16### Spacing Tokens
17 
18```tsx
19// CORRECT - Use tokens
20<Box padding="$4" marginBottom="$2" />
21 
22// WRONG - Hard-coded values
23<Box padding={16} marginBottom={8} />
24```
25 
26| Token | Value |
27|-------|-------|
28| `$1` | 4px |
29| `$2` | 8px |
30| `$3` | 12px |
31| `$4` | 16px |
32| `$6` | 24px |
33| `$8` | 32px |
34 
35### Color Tokens
36 
37```tsx
38// CORRECT - Semantic tokens
39<Text color="$textPrimary" />
40<Box backgroundColor="$backgroundSecondary" />
41 
42// WRONG - Hard-coded colors
43<Text color="#333333" />
44<Box backgroundColor="rgb(245, 245, 245)" />
45```
46 
47| Semantic Token | Use For |
48|----------------|---------|
49| `$textPrimary` | Main text |
50| `$textSecondary` | Supporting text |
51| `$textTertiary` | Disabled/hint text |
52| `$primary500` | Brand/accent color |
53| `$statusError` | Error states |
54| `$statusSuccess` | Success states |
55 
56### Typography Tokens
57 
58```tsx
59<Text fontSize="$lg" fontWeight="$semibold" />
60```
61 
62| Token | Size |
63|-------|------|
64| `$xs` | 12px |
65| `$sm` | 14px |
66| `$md` | 16px |
67| `$lg` | 18px |
68| `$xl` | 20px |
69| `$2xl` | 24px |
70 
71## Core Components
72 
73### Box
74 
75Base layout component with token support:
76 
77```tsx
78<Box
79  padding="$4"
80  backgroundColor="$backgroundPrimary"
81  borderRadius="$lg"
82>
83  {children}
84</Box>
85```
86 
87### HStack / VStack
88 
89Horizontal and vertical flex layouts:
90 
91```tsx
92<HStack gap="$3" alignItems="center">
93  <Icon name="user" />
94  <Text>Username</Text>
95</HStack>
96 
97<VStack gap="$4" padding="$4">
98  <Heading>Title</Heading>
99  <Text>Content</Text>
100</VStack>
101```
102 
103### Text
104 
105Typography with token support:
106 
107```tsx
108<Text
109  fontSize="$lg"
110  fontWeight="$semibold"
111  color="$textPrimary"
112>
113  Hello World
114</Text>
115```
116 
117### Button
118 
119Interactive button with variants:
120 
121```tsx
122<Button
123  onPress={handlePress}
124  variant="solid"
125  size="md"
126  isLoading={loading}
127  isDisabled={disabled}
128>
129  Click Me
130</Button>
131```
132 
133| Variant | Use For |
134|---------|---------|
135| `solid` | Primary actions |
136| `outline` | Secondary actions |
137| `ghost` | Tertiary/subtle actions |
138| `link` | Inline actions |
139 
140### Input
141 
142Form input with validation:
143 
144```tsx
145<Input
146  value={value}
147  onChangeText={setValue}
148  placeholder="Enter text"
149  error={touched ? errors.field : undefined}
150  label="Field Name"
151/>
152```
153 
154### Card
155 
156Content container:
157 
158```tsx
159<Card padding="$4" gap="$3">
160  <CardHeader>
161    <Heading size="sm">Card Title</Heading>
162  </CardHeader>
163  <CardBody>
164    <Text>Card content</Text>
165  </CardBody>
166</Card>
167```
168 
169## Layout Patterns
170 
171### Screen Layout
172 
173```tsx
174const MyScreen = () => (
175  <Screen>
176    <ScreenHeader title="Page Title" />
177    <ScreenContent padding="$4">
178      {/* Content */}
179    </ScreenContent>
180  </Screen>
181);
182```
183 
184### Form Layout
185 
186```tsx
187<VStack gap="$4" padding="$4">
188  <Input label="Name" {...nameProps} />
189  <Input label="Email" {...emailProps} />
190  <Button isLoading={loading}>Submit</Button>
191</VStack>
192```
193 
194### List Item Layout
195 
196```tsx
197<HStack
198  padding="$4"
199  gap="$3"
200  alignItems="center"
201  borderBottomWidth={1}
202  borderColor="$borderLight"
203>
204  <Avatar source={{ uri: imageUrl }} size="md" />
205  <VStack flex={1}>
206    <Text fontWeight="$semibold">{title}</Text>
207    <Text color="$textSecondary" fontSize="$sm">{subtitle}</Text>
208  </VStack>
209  <Icon name="chevron-right" color="$textTertiary" />
210</HStack>
211```
212 
213## Anti-Patterns
214 
215```tsx
216// WRONG - Hard-coded values
217<View style={{ padding: 16, backgroundColor: '#fff' }}>
218 
219// CORRECT - Design tokens
220<Box padding="$4" backgroundColor="$backgroundPrimary">
221 
222 
223// WRONG - Raw platform components
224import { View, Text } from 'react-native';
225 
226// CORRECT - Core components
227import { Box, Text } from 'components/core';
228 
229 
230// WRONG - Inline styles
231<Text style={{ fontSize: 18, fontWeight: '600' }}>
232 
233// CORRECT - Token props
234<Text fontSize="$lg" fontWeight="$semibold">
235```
236 
237## Component Props Pattern
238 
239When creating components, use token-based props:
240 
241```tsx
242interface CardProps {
243  padding?: '$2' | '$4' | '$6';
244  variant?: 'elevated' | 'outlined' | 'filled';
245  children: React.ReactNode;
246}
247 
248const Card = ({ padding = '$4', variant = 'elevated', children }: CardProps) => (
249  <Box
250    padding={padding}
251    backgroundColor="$backgroundPrimary"
252    borderRadius="$lg"
253    {...variantStyles[variant]}
254  >
255    {children}
256  </Box>
257);
258```
259 
260## Integration with Other Skills
261 
262- **react-ui-patterns**: Use core components for UI states
263- **testing-patterns**: Mock core components in tests
264- **storybook**: Document component variants
265