Standards for writing and maintaining Hyperframes documentation. Based on patterns from Remotion, Stripe, Tailwind CSS, and Astro.
## Core Principles
1.**One-sentence intro rule** — Every page opens with a single sentence telling the reader what this page helps them do or understand. No preamble, no history.
2.**Outcome before implementation** — Show what the code produces (rendered result, terminal output, file structure) before showing the code itself.
3.**Show, don't tell** — Use concrete examples with realistic values. Never use `foo`/`bar`/`baz`. Prefer a working HTML snippet over a description of what to write.
4.**Two content modes** — Guides build narratives with progressive complexity. References enable scanning with standardized structure. Never mix them.
5.**No dead ends** — Every page links forward (next steps), backward (prerequisites), and sideways (related concepts). Readers should never reach a page with nowhere to go.
## Page Structure
### Guides (concepts/, guides/)
```
Title
├── One-sentence purpose statement
├── What this looks like (output, demo, or visual)
├── Minimal working example
├── Deeper explanation with progressive complexity
├── Common patterns / best practices
├── Warnings and pitfalls (sparingly)
└── Next steps (cards or links to related pages)
```
### Reference pages (reference/)
```
Title
├── One-sentence definition
├── Complete attribute/API table
├── Detailed section per item (type, default, description, example)
├── Rules and constraints
└── Related pages
```
### Package pages (packages/)
```
Title
├── One-line description + install command
├── When to use this package (and when NOT to)
├── Key features list
├── Minimal usage example with expected output
├── Configuration reference
└── Related packages
```
## Writing Style
- **Second person, active voice, imperative mood**: "Use X to do Y." Not "The developer should consider using X."
- **Present tense**: "The runtime manages media playback." Not "The runtime will manage..."
- **Be direct**: "This breaks rendering." Not "This may potentially cause issues with the rendering pipeline."
- **Prerequisites at point of need**: State requirements where they matter, not in a wall at the top.
- **Conversational but precise**: Friendly tone, exact technical details.
## Code Examples
### Always annotate code blocks
```mdx
```html index.html
<div data-composition-id="root" ...>
```
```
The filename after the language tag tells readers where the code goes.
### Use numbered comments for multi-step code
```javascript
// 1. Create a paused timeline
consttl=gsap.timeline({paused:true});
// 2. Add animations
tl.from("#title",{opacity:0,y:-50,duration:1},0);
// 3. Register the timeline
window.__timelines["my-video"]=tl;
```
### Show expected output
After CLI commands, show what the user should see:
