Docs

Reference material for the Rafters design system. Each page covers one primitive or one principle. The sidebar groups them by what they do.

Start here

• Design Philosophy. The three pillars behind every decision.
• Cognitive Load Scoring. The model that assigns every component a 0 to 10 score.

Foundations

• Spacing. Rhythm before values.
• Typography. Semantic roles, not utility strings.
• Color. OKLCH, harmony, decisions with reasons attached.
• Radius. Corners as brand personality.
• Shadow. Three tiers, each with a meaning.
• Depth. A fixed stack. No z-index wars.
• Motion. Respond, don't perform.

Editor

• Editor. The block-tree page builder. Start here.
• Architecture. Leaf and composition primitives. The self-contained rule.
• Data Model. Every type, every shape, every field.
• Component. The React surface. Props, controls ref, what's wired.
• Render Path. How a block becomes JSX. Mark order. The data-block-id contract.

Editor primitives

• Canvas. Selection, focus, CRUD. The core.
• Input. Keyboard routing, focus trap, roving tabindex.
• Formatting. Inline marks, slash commands, the format toolbar.
• Palettes. Block library, rule library, fuzzy typeahead.
• Overlays. Context menus, dismissable layers, collision-aware positioning.
• Drag and State. Drag-drop, drop zones, clipboard, history.

Editor data and rules

• Serialization. The EditorSerializer interface. MDX, JSON, composite, blueprint.
• Composites. Manifest, bridge, registry. Pre-built block assemblies.
• Rules. AppliedRule, matching, the runtime gap.

Editor reference

• Behavior Matrix. Per primitive: guarantees, non-guarantees, edge cases, test coverage.
• Known Gaps. The honest list. Where the surface drifts and what the fix looks like.