A design system in a box.
hip-ui.tngl.io/docs/introduction
Footer
+1510
-123
+64
-117
.cursor/rules/hip-component.mdc
+64
-117
.cursor/rules/hip-component.mdc
···
6
6
7
7
## Component Creation Process
8
8
9
-
To create a new hip component follow these steps:
10
-
11
-
1. **Research phase**: First ask if there is documentation for a headless component to look at (e.g., React Aria Components docs) Check https://component.gallery/ for similar implementation
12
-
2. **Component implementation**: Create the component in `packages/hip-ui/src/components/[component-name]/index.tsx`
13
-
3. **Config creation**: Create a config file `[component-name]-config.ts` in the same directory
14
-
4. **Register config**: Import and add the config to `packages/hip-ui/src/cli/install.tsx` in the `COMPONENT_CONFIGS` array
15
-
5. **Build**: Run the build command to compile the component
16
-
6. **Install**: Run `pnpm hip install --all` in the apps/docs directory
17
-
7. **Documentation**: Generate an `.mdx` page with examples in `apps/docs/src/docs/components/[component-name].mdx`
18
-
8. **Examples**: Create example files in `apps/docs/src/examples/[component-name]/` directory
9
+
1. **Component implementation**: Create in `packages/hip-ui/src/components/[component-name]/index.tsx`
10
+
2. **Config creation**: Create `[component-name]-config.ts` with all dependencies
11
+
3. **Register config**: Add to `packages/hip-ui/src/cli/install.tsx` COMPONENT_CONFIGS array
12
+
4. **Documentation**: Create `.mdx` in `apps/docs/src/docs/components/[category]/[component-name].mdx`
13
+
5. **Examples**: Create examples in `apps/docs/src/examples/[component-name]/`
19
14
20
15
## Component Structure
21
16
···
29
24
### Component File Structure
30
25
31
26
```typescript
32
-
"use client"; // Add this for client components that use React hooks or interactivity
27
+
"use client"; // Required for React hooks, interactions, or react-aria-components
33
28
34
29
import * as stylex from "@stylexjs/stylex";
35
30
import { ComponentFromAria } from "react-aria-components";
36
-
// Import theme tokens and utilities
37
-
import { ui, uiColor } from "../theme/semantic-color.stylex";
31
+
import { breakpoints } from "../theme/media-queries.stylex"; // Use breakpoints, not mediaQueries
32
+
import { ui } from "../theme/semantic-color.stylex";
38
33
import { spacing } from "../theme/spacing.stylex";
39
-
import { radius } from "../theme/radius.stylex";
40
-
import { shadow } from "../theme/shadow.stylex";
41
-
import { fontFamily, fontSize, fontWeight } from "../theme/typography.stylex";
42
-
import { animationDuration } from "../theme/animations.stylex";
43
-
import { Size, StyleXComponentProps } from "../theme/types";
44
-
// Import other hip components if needed
45
-
import { Flex } from "../flex";
46
-
import { Grid } from "../grid";
34
+
import { StyleXComponentProps } from "../theme/types";
47
35
48
-
// Define styles using stylex.create
49
36
const styles = stylex.create({
50
37
base: {
51
-
// Use theme tokens, not hardcoded values
52
38
padding: spacing["4"],
53
-
borderRadius: radius["md"],
54
-
backgroundColor: ui.bg,
55
-
color: ui.text,
39
+
[breakpoints.sm]: { padding: spacing["6"] }, // Responsive styles
56
40
},
57
41
});
58
42
59
-
// Export interface extending StyleXComponentProps
60
-
export interface ComponentProps extends StyleXComponentProps<AriaComponentProps> {
61
-
size?: Size;
62
-
variant?: ComponentVariant;
63
-
}
43
+
export interface ComponentProps extends StyleXComponentProps<AriaComponentProps> {}
44
+
45
+
export const Component = ({ style, ...props }: ComponentProps) => {
46
+
return <AriaComponent {...stylex.props(styles.base, style)} {...props} />;
47
+
};
48
+
49
+
// For composite components with subcomponents, export both individual and namespace:
50
+
export const ComponentRoot = ({ style, ...props }: ComponentRootProps) => { /* ... */ };
51
+
export const ComponentSection = ({ style, ...props }: ComponentSectionProps) => { /* ... */ };
64
52
65
-
// Export component
66
-
export const Component = ({ style, size, variant, ...props }: ComponentProps) => {
67
-
return (
68
-
<AriaComponent
69
-
{...stylex.props(styles.base, style)}
70
-
data-size={size}
71
-
{...props}
72
-
/>
73
-
);
53
+
export const Component = {
54
+
Root: ComponentRoot,
55
+
Section: ComponentSection,
74
56
};
75
57
```
76
58
···
83
65
name: "component-name",
84
66
filepath: "./index.tsx",
85
67
hipDependencies: [
86
-
// List ALL theme files and other hip components used
68
+
// List ALL theme files used (only what's imported)
87
69
"../theme/spacing.stylex.tsx",
88
-
"../theme/radius.stylex.tsx",
89
70
"../theme/semantic-color.stylex.tsx",
90
-
"../theme/typography.stylex.tsx",
91
-
"../theme/shadow.stylex.tsx",
92
-
"../theme/animations.stylex.tsx",
71
+
"../theme/media-queries.stylex.tsx", // If using breakpoints
93
72
"../theme/types.ts",
94
-
// Other hip components if imported
95
-
"../flex/index.tsx",
96
73
],
97
74
dependencies: {
98
-
// External npm packages required
99
-
"react-aria-components": "^1.13.0",
75
+
"react-aria-components": "^1.13.0", // Only if used
100
76
},
101
77
};
102
78
```
···
105
81
106
82
### Styling
107
83
108
-
- **Always use theme tokens** - Never hardcode colors, spacing, radius, shadows, or typography values
109
-
- Use `semantic-color.stylex.tsx` for colors (`ui.*`, `uiColor.*`, `uiInverted.*`)
110
-
- Use `spacing.stylex.tsx` for all spacing values
111
-
- Use `radius.stylex.tsx` for border radius values
112
-
- Use `shadow.stylex.tsx` for box shadows
113
-
- Use `typography.stylex.tsx` for font styles
114
-
- Use `animations.stylex.tsx` for transitions and animations
115
-
- **Layout components**: Prefer `Flex` and `Grid` components over CSS for layout
116
-
- **Size handling**: For composite components, use `SizeContext` to propagate size to child components. Only apply `size` prop to the root element
84
+
- **Always use theme tokens** - Never hardcode values
85
+
- Use `semantic-color.stylex.tsx` for colors (`ui.*`, `uiColor.*`)
86
+
- Use `spacing.stylex.tsx`, `radius.stylex.tsx`, `typography.stylex.tsx`, etc. for all values
87
+
- **Responsive styles**: Use `breakpoints` from `media-queries.stylex.tsx` (not `mediaQueries`)
88
+
- Prefer `Flex` and `Grid` components over CSS for layout
89
+
- Use `SizeContext` to propagate size to child components in composite components
117
90
118
91
### TypeScript
119
92
120
93
- Always extend `StyleXComponentProps<BaseProps>` for component props
121
94
- Use `stylex.StyleXStyles` for style props (never `className` or React `style`)
122
-
- Export clear TypeScript interfaces with JSDoc comments for complex props
123
-
- Use `data-*` attributes for conditional styling based on props (e.g., `data-size={size}`)
124
-
125
-
### React Aria Components
126
-
127
-
- When using React Aria Components, extend the appropriate Aria component props
128
-
- Preserve accessibility features from React Aria Components
129
-
- Use React Aria's built-in hooks and state management when appropriate
130
-
- Follow React Aria Component patterns for composition (e.g., `DialogTrigger`, `Dialog`, `Modal`, `ModalOverlay`)
131
-
132
-
### Icons
133
-
134
-
- Use icons from `lucide-react` exclusively
135
-
- Import icons as needed: `import { IconName } from "lucide-react";`
136
-
- When used in a hip component the size does not need to be set
95
+
- Export TypeScript interfaces with JSDoc comments for complex props
96
+
- Use `data-*` attributes for conditional styling (e.g., `data-size={size}`)
137
97
138
98
### Component Composition
139
99
140
-
- **Reuse existing components** - Prefer composing with existing hip components rather than redefining functionality
141
-
- For composite components with multiple parts (e.g., Card, CardHeader, CardBody), export all related components from the same file
142
-
- Use React Context (like `SizeContext`) for sharing props down the component tree when appropriate
100
+
- For composite components (e.g., Footer, Card), export both:
101
+
1. Individual components: `export const FooterRoot = ...`
102
+
2. Namespace object: `export const Footer = { Root: FooterRoot, ... }`
103
+
- This allows both `Footer.Root` and `FooterRoot` usage patterns
104
+
- Export all related subcomponents from the same file
143
105
144
-
### Client Components
106
+
### React Aria & Icons
145
107
146
-
- Add `"use client"` directive at the top of files that:
147
-
- Use React hooks (`useState`, `useEffect`, etc.)
148
-
- Handle user interactions
149
-
- Use React Context
150
-
- Import from `react-aria-components` (most components need this)
108
+
- Extend appropriate Aria component props when using React Aria Components
109
+
- Use icons from `lucide-react` exclusively (size handled automatically)
110
+
- Add `"use client"` directive for hooks, interactions, or react-aria-components
151
111
152
112
## Documentation Structure
153
113
154
-
### MDX File Template
114
+
### MDX File
115
+
116
+
Place in `apps/docs/src/docs/components/[category]/[component-name].mdx` (e.g., `navigation/footer.mdx`)
155
117
156
118
```mdx
157
119
---
158
120
title: ComponentName
159
-
description: Brief description of what the component does.
121
+
description: Brief description.
160
122
---
161
123
162
-
import { PropDocs } from "../../lib/PropDocs";
163
-
import { Example } from "../../lib/Example";
164
-
import { Basic } from "../../examples/component-name/basic";
165
-
import { FeatureExample } from "../../examples/component-name/feature";
124
+
import { PropDocs } from '../../../lib/PropDocs'
125
+
import { Example } from '../../../lib/Example'
126
+
import { Basic } from '../../../examples/component-name/basic'
166
127
167
128
<Example src={Basic} />
168
129
169
130
## Installation
170
131
171
-
Run the following command to add the component to your project.
172
-
173
-
(Use triple backticks with bash language tag for the installation command)
132
+
```bash
133
+
pnpm hip install component-name
134
+
```
174
135
175
136
## Props
176
-
177
-
This component is built using [React Aria ComponentName](link-to-docs).
178
137
179
138
<PropDocs components={["ComponentName", "SubComponent"]} />
180
139
···
182
141
183
142
### Feature Name
184
143
185
-
Description of the feature.
186
-
187
144
<Example src={FeatureExample} />
188
-
189
-
## Related Components
190
-
191
-
- [RelatedComponent](/docs/components/related-component) - Description
192
145
```
193
146
194
147
### Example Files
195
148
196
-
- Create example files in `apps/docs/src/examples/[component-name]/`
197
-
- Start with `basic.tsx` showing the simplest usage
198
-
- Create additional examples for each major feature (variants, sizes, states, etc.)
149
+
- Create in `apps/docs/src/examples/[component-name]/`
150
+
- Start with `basic.tsx` for simplest usage
199
151
- Use imports from `@/components/[component-name]`
200
-
- Keep examples focused and minimal
152
+
- Use StyleX styles (not inline styles) - import spacing/theme tokens as needed
201
153
202
-
## Testing Checklist
154
+
## Checklist
203
155
204
-
Before considering a component complete:
205
-
206
-
- [ ] Component follows StyleX patterns with theme tokens
207
-
- [ ] TypeScript interfaces are properly defined
208
-
- [ ] All dependencies listed in config file
209
-
- [ ] Config added to `install.tsx` COMPONENT_CONFIGS array
210
-
- [ ] `"use client"` directive added if needed
211
-
- [ ] Component works with `SizeContext` if size is supported
212
-
- [ ] Basic example created
213
-
- [ ] MDX documentation file created with proper structure
214
-
- [ ] Related components listed in documentation
215
-
- [ ] Component builds successfully
216
-
- [ ] Component installs via `pnpm hip install`
156
+
- [ ] Component uses theme tokens (no hardcoded values)
157
+
- [ ] TypeScript interfaces with JSDoc comments
158
+
- [ ] Config file lists all dependencies
159
+
- [ ] Registered in `install.tsx` COMPONENT_CONFIGS
160
+
- [ ] `"use client"` added if needed
161
+
- [ ] Basic example and MDX docs created
162
+
- [ ] Uses `breakpoints` (not `mediaQueries`) for responsive styles
163
+
- [ ] Composite components export both individual and namespace patterns
+2
packages/hip-ui/src/cli/install.tsx
+2
packages/hip-ui/src/cli/install.tsx
···
40
40
import { emptyStateConfig } from "../components/empty-state/empty-state-config.js";
41
41
import { fileDropZoneConfig } from "../components/file-drop-zone/file-drop-zone-config.js";
42
42
import { flexConfig } from "../components/flex/flex-config.js";
43
+
import { footerConfig } from "../components/footer/footer-config.js";
43
44
import { formConfig } from "../components/form/form-config.js";
44
45
import { gridConfig } from "../components/grid/grid-config.js";
45
46
import { hoverCardConfig } from "../components/hover-card/hover-card-config.js";
···
135
136
aspectRatioConfig,
136
137
colorSwatchConfig,
137
138
fileDropZoneConfig,
139
+
footerConfig,
138
140
formConfig,
139
141
tableConfig,
140
142
sliderConfig,
+15
-6
pnpm-workspace.yaml
+15
-6
pnpm-workspace.yaml
···
3
3
- packages/*
4
4
5
5
catalog:
6
-
"@react-stately/utils": 3.10.8
7
-
"@react-types/overlays": 3.9.2
8
-
"@stylexjs/stylex": 0.17.0
9
-
"@types/node": 24.9.1
10
-
"@types/react": 19.2.0
11
-
"@types/react-dom": 19.2.0
6
+
'@react-stately/utils': 3.10.8
7
+
'@react-types/overlays': 3.9.2
8
+
'@stylexjs/stylex': 0.17.0
9
+
'@types/node': 24.9.1
10
+
'@types/react': 19.2.0
11
+
'@types/react-dom': 19.2.0
12
12
change-case: 5.4.4
13
13
dedent: 1.7.0
14
14
eslint: 9.38.0
···
21
21
react-stately: 3.42.0
22
22
typescript: 5.9.3
23
23
vitest: 3.2.4
24
+
25
+
ignoredBuiltDependencies:
26
+
- core-js
27
+
28
+
onlyBuiltDependencies:
29
+
- '@parcel/watcher'
30
+
- '@swc/core'
31
+
- esbuild
32
+
- unrs-resolver