Skip to content

Commit cc4940d

Browse files
segunadebayosegunadebayo
committed
docs: claude guide
1 parent d5fdd78 commit cc4940d

File tree

2 files changed

+272
-2
lines changed

2 files changed

+272
-2
lines changed

‎.claude/docs/documentation-patterns.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# Ark UI - Documentation Patterns
2+
3+
This guide covers patterns for writing component documentation in the Ark UI website.
4+
5+
## Documentation Structure
6+
7+
Component documentation is located in `website/src/content/pages/components/` with this standard structure:
8+
9+
```markdown
10+
---
11+
id: component-name
12+
title: Component Name
13+
description: Brief description
14+
---
15+
16+
<ComponentPreview id="ComponentName" />
17+
18+
## Anatomy
19+
20+
<Anatomy id="component-name" />
21+
22+
## Examples
23+
24+
<Example id="basic" />
25+
26+
### Feature Example
27+
28+
Description of what this demonstrates.
29+
30+
<Example id="example-name" />
31+
32+
## Guides (if applicable)
33+
34+
### Advanced Pattern
35+
36+
Non-interactive guides with code snippets.
37+
38+
## API Reference
39+
40+
### Props
41+
42+
<ComponentTypes id="component-name" />
43+
44+
### Context
45+
46+
<ContextType id="component-name" />
47+
48+
## Accessibility (if applicable)
49+
50+
<KeyBindingsTable id="component-name" />
51+
```
52+
53+
## Key Principles
54+
55+
### Examples vs Guides
56+
57+
**Examples Section** - Interactive demos with `<Example id="..." />`:
58+
- Show component behavior through working demos
59+
- Framework-agnostic (shown for all frameworks via tabs)
60+
- Each example has a brief description
61+
62+
**Guides Section** - Non-interactive implementation guidance:
63+
- CSS styling patterns and animations
64+
- Integration guides (Next.js, Remix, router setup)
65+
- Advanced configuration and type safety patterns
66+
- Performance optimizations
67+
68+
### When to Use Guides Instead of Examples
69+
70+
Move content to Guides if it contains:
71+
72+
1. **CSS code blocks** - Animation keyframes, styling patterns, CSS variables
73+
2. **Router integration** - Framework-specific router setup
74+
3. **Framework integration** - Next.js Image, dynamic imports
75+
4. **Prop explanations** - Code snippets without interactive behavior
76+
5. **Advanced patterns** - Type safety, custom object mapping
77+
6. **Styling requirements** - Required CSS or structural requirements
78+
79+
## Common Patterns
80+
81+
### Root Provider
82+
83+
```markdown
84+
### Root Provider
85+
86+
The `useComponentName` hook gives you programmatic access to the component's state and methods.
87+
88+
<Example id="root-provider" />
89+
90+
> If you're using the `RootProvider` component, you don't need to use the `Root` component.
91+
```
92+
93+
### Field Integration
94+
95+
```markdown
96+
### Field
97+
98+
The `Field` component helps manage form-related state and accessibility attributes.
99+
100+
<Example id="with-field" />
101+
```
102+
103+
### Controlled State
104+
105+
```markdown
106+
### Controlled State
107+
108+
To create a controlled component, manage the state using the `value` and `onValueChange` props:
109+
110+
<Example id="controlled" />
111+
```
112+
113+
## Guide Section Patterns
114+
115+
### CSS Variables
116+
117+
```markdown
118+
### Available height and width
119+
120+
The following CSS variables are exposed to the `Component.Positioner`:
121+
122+
\`\`\`css
123+
--reference-width: <pixel-value>;
124+
--available-width: <pixel-value>;
125+
--available-height: <pixel-value>;
126+
\`\`\`
127+
```
128+
129+
### CSS Animations
130+
131+
```markdown
132+
### Animate Content Size
133+
134+
Use the `--height` CSS variable to animate content:
135+
136+
\`\`\`css
137+
@keyframes slideDown {
138+
to { height: var(--height); }
139+
}
140+
\`\`\`
141+
```
142+
143+
### Framework Integration
144+
145+
```markdown
146+
### Next.js Image Integration
147+
148+
Here's an example using `next/image`:
149+
150+
\`\`\`tsx
151+
import { Component } from '@ark-ui/react/component'
152+
import { getImageProps } from 'next/image'
153+
// ...
154+
\`\`\`
155+
```
156+
157+
### Router Integration
158+
159+
```markdown
160+
### Router Controlled Tabs
161+
162+
Control active state based on URL:
163+
164+
- Set `value` prop to current URL path
165+
- Listen to `onValueChange` and update URL
166+
167+
\`\`\`tsx
168+
// Remix Router example
169+
\`\`\`
170+
```
171+
172+
## Formatting
173+
174+
### Code Blocks
175+
176+
Specify language for syntax highlighting:
177+
178+
```markdown
179+
\`\`\`tsx
180+
// TypeScript code
181+
\`\`\`
182+
183+
\`\`\`css
184+
/* CSS code */
185+
\`\`\`
186+
```
187+
188+
### Notes and Warnings
189+
190+
```markdown
191+
> Note: This requires rendering the component within a `Portal`.
192+
193+
> If you're using the `RootProvider` component, you don't need to use the `Root` component.
194+
```
195+
196+
### Keyboard Keys
197+
198+
```markdown
199+
Press <kbd>Enter</kbd> or <kbd>Escape</kbd> to close.
200+
```
201+
202+
## Example Naming Conventions
203+
204+
Use kebab-case, descriptive IDs:
205+
206+
- `basic` - Simple usage
207+
- `controlled` - Controlled state
208+
- `root-provider` - RootProvider usage
209+
- `with-field` - Field integration
210+
- `lazy-mount` - Lazy mounting
211+
- `initial-focus` - Focus control
212+
- `links` - Rendering as links
213+
214+
## Documentation Checklist
215+
216+
- [ ] Frontmatter includes id, title, description
217+
- [ ] ComponentPreview at top
218+
- [ ] Anatomy section present
219+
- [ ] Examples start with basic
220+
- [ ] Example IDs match example filenames (kebab-case)
221+
- [ ] Guides contain non-interactive content only
222+
- [ ] API Reference includes ComponentTypes and ContextType
223+
- [ ] Accessibility section if applicable
224+
- [ ] Examples ordered simple to complex
225+
226+
## Common Mistakes
227+
228+
❌ Don't include CSS examples in Examples section
229+
✅ Move CSS examples to Guides
230+
231+
❌ Don't include router integration in Examples
232+
✅ Move integration guides to Guides
233+
234+
❌ Don't write generic descriptions
235+
✅ Write specific descriptions explaining props/features
236+
237+
❌ Don't use code blocks without `<Example>` tags in Examples
238+
✅ Use `<Example>` tags or move to Guides
239+
240+
## Adding to Showcase
241+
242+
Add projects/design systems built with Ark UI to `website/src/content/showcases.json`:
243+
244+
1. **Get image** (1200x630 dimensions):
245+
- Download OG image: `curl -sL "<og-image-url>" -o website/public/images/<name>.png`
246+
- Or capture screenshot with Playwright using `networkidle` and `viewport: { width: 1200, height: 630 }`
247+
248+
2. **Add entry** to `showcases.json`:
249+
```json
250+
{
251+
"title": "Project Name",
252+
"description": "Brief description (50-60 chars)",
253+
"url": "https://project.com/",
254+
"image": "/images/<name>.png"
255+
}
256+
```
257+
258+
3. **Clean up** temp files in `/tmp` if created
259+
260+
## File References
261+
262+
```
263+
website/src/content/pages/components/{component}.mdx - Documentation
264+
packages/react/src/components/{component}/examples/ - React examples
265+
packages/solid/src/components/{component}/examples/ - Solid examples
266+
packages/vue/src/components/{component}/examples/ - Vue examples
267+
packages/svelte/src/lib/components/{component}/examples/ - Svelte examples
268+
website/src/content/showcases.json - Showcase entries
269+
website/public/images/ - Showcase images
270+
```

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ This guide is split into focused documents for better navigation:
1010
- **[Overview](@.claude/docs/overview.md)** - Project overview, architecture, and available components
1111
- **[Development](@.claude/docs/development.md)** - Development workflows, commands, and processes
1212
- **[Component Patterns](@.claude/docs/component_patterns.md)** - Component development patterns, examples, and testing
13-
- **[Framework Patterns](@.claude/docs/framework_patterns.md)** - Framework-specific patterns and advanced
14-
implementations
13+
- **[Framework Patterns](@.claude/docs/framework_patterns.md)** - Framework-specific patterns and advanced implementations
14+
- **[Documentation Patterns](@.claude/docs/documentation-patterns.md)** - Website documentation structure, Examples vs Guides, and writing guidelines
1515

1616
## Quick Start
1717

0 commit comments

Comments
 (0)