Contributing to the Docs

This site is a VitePress docsite, themed from design-system/DESIGN.md, gated behind Cloudflare Access. Drop a markdown file into a category folder and it appears in the sidebar. Need richer than markdown? Inline Vue lives in the same file. Need a fully standalone artifact? Drop it in public/.

InternalAudience: OnRamp engineersStack: VitePress + Vue + DESIGN.md tokens

5

Categories

3

Tiers of fidelity

~30s

To add a markdown doc

0

Config edits required

Quick start

# from the repo root
bun install
bunx vitepress dev docs --port 5199
# → http://localhost:5199

There's also a Docs entry in .claude/launch.json for the Claude Code preview tooling.

Drop-in workflow. Create docs/<category>/my-doc.md, add a title: and order: to its frontmatter, restart the dev server, and it's in the nav + sidebar. No config.mts edits.

Pick a tier of fidelity

Pick the lowest tier that fits — higher tiers add maintenance cost.

Tier 1 — Markdown

Plain markdown, fenced code, mermaid, frontmatter. The default for most docs.

---
title: My Doc
order: 3
---

# My Doc

Short intro paragraph.

## A section

- Lists
- `inline code`
- Tables, fenced code, mermaid all work natively

​```python
def hello(): return "world"
​```

​```mermaid
flowchart LR
    A[Start] --> B[Done]
​```

Use it for: runbooks, RFCs, architecture notes, dev-setup guides — anything that reads top-to-bottom.

Tier 2 — Inline Vue

The .md file is compiled as a Vue template. You can write <script setup> at the top, declare reactive refs, and put v-show / v-if / @click on inline HTML. The page still lives in the docsite shell — sidebar, search, dark mode, theme all keep working.

---
title: My Interactive Doc
order: 3
---

<script setup>
import { ref } from 'vue'
const tab = ref(1)
</script>

<div class="my-doc">

# My Interactive Doc

<button @click="tab = 1" :class="{ active: tab === 1 }">Tab A</button>
<button @click="tab = 2" :class="{ active: tab === 2 }">Tab B</button>

<div v-show="tab === 1">

## Tab A

Normal markdown — lists, `code`, fenced ```mermaid``` blocks all render.

</div>

<div v-show="tab === 2">

## Tab B

More markdown content here.

</div>

</div>

<style>
.my-doc button.active { background: var(--color-primary); color: #fff; }
</style>

Two Tier 2 gotchas — read these first

1. Markdown inside HTML needs blank lines. To get markdown processed inside a <div> (e.g. a Vue v-show panel), separate it from the tags with blank lines. Otherwise the content is treated as raw HTML and stays unrendered.

2. <style> blocks in a .md are GLOBAL, not scoped. Wrap the page in a single <div class="my-page">…</div> and prefix every selector with .my-page so the styles don't leak to other pages.

Use it for: phase tabs, filterable tables, comparison toggles, anything that benefits from interactivity. See architecture/prismatic-decoupling.md for the worked example.

Tier 3 — Standalone HTML (escape hatch)

A full .html file in docs/public/ is served at the site root, bypassing the VitePress shell. Reach for this only when the content shouldn't live in the shell.

Genuine use cases:

• A customer-facing security document destined for our customers' security teams that intentionally doesn't follow the OnRamp design system.
• A single-file artifact you want to share/print outside the site.
• Content that depends on heavy libs the docsite build shouldn't carry.

Tradeoffs you accept:

• Not indexed by the docsite's local search.
• Not in the sidebar / nav.
• You build your own page chrome (header, footer, navigation).
• Theming is your responsibility — DESIGN.md tokens are still available via /tokens.css, but standalone HTML is also the right place to not track the design system on purpose.

How to add one:

1. Copy .agents/skills/docs/references/html-mock-template.html to docs/public/<name>.html.
2. The template <link>s /tokens.css (the live DESIGN.md token set). For a customer-facing doc that should ignore OnRamp branding, drop the link.
3. Optionally link to it from a category page with the themed .doc-cta-card / .doc-cta-button helpers in theme/custom.css.

If you find yourself wanting Tier 3 for an internal interactive doc (tabs, filters, diagrams) — use Tier 2 instead. You'll get the same interactivity and keep search, sidebar, and dark mode.

Categories

Every category is a top-level folder under docs/. Drop a .md in and it appears.

Folder	Sidebar label	Goes here
architecture/	Architecture	System/design docs.
design-system/	Design System	DESIGN.md tokens, style guidance.
proposals/	Proposals & RFCs	Design proposals/RFCs. Copy proposals/_template.md.
runbooks/	Runbooks & Guides	Operational runbooks.
dev-setup/	Dev Setup	New-machine / dev-environment setup.

Add a new category

Add one row to CATEGORIES in config.mts and create the matching folder with at least one .md (otherwise it's skipped):

const CATEGORIES = [
  { dir: 'architecture', label: 'Architecture' },
  // ...
  { dir: 'my-new-cat', label: 'My New Category' },
]

Mermaid diagrams

Fenced ```mermaid blocks render client-side. The theme cleans up after failures so a single broken diagram can't pollute other pages.

Semicolons break sequenceDiagram text. ; is a statement separator in mermaid's sequence grammar. Inside any sequenceDiagram message or Note, use —, ,, or <br/> instead.

Note over X: token validated; identity locked    ❌ parse error
Note over X: token validated, identity locked    ✓

Design tokens

The docsite imports the live DESIGN.md token set. Use the CSS variables for every color, font, and radius — never hardcode brand hex.

/* available globally on every page */
color: var(--color-primary);          /* #893eff */
background: var(--vp-c-bg-soft);      /* dark-mode aware surface */
border-radius: var(--radius-lg);      /* 16px */
font-family: var(--font-body);

Variable family	Source	Use for
--color-primary, --color-brand-*, --color-purple-50..950 (+ pink/green/red/orange/black ramps)	design-system/generated/tokens.css (from DESIGN.md)	Brand, accents, tints.
--vp-c-bg, --vp-c-bg-soft, --vp-c-bg-alt, --vp-c-text-1, --vp-c-text-2, --vp-c-divider, --vp-c-brand-1	VitePress + theme overrides	Surfaces and text — dark-mode aware. Prefer these for chrome.
--radius-xs..xl, --font-body	DESIGN.md	Shape and type.

See /design-system/ in the sidebar for the palette and full token list.

Run locally / build / deploy

bunx vitepress dev docs --port 5199    # dev w/ HMR
bunx vitepress build docs              # production build — catches dead links

The build is dependency-free (bunx resolves VitePress on demand). The deploy build command is just bunx vitepress build with docs as the root.

Dev-server restart needed for new files/categories. The nav + sidebar are generated by a filesystem scan at config-load time. HMR covers content edits live, but a newly added file or category only shows up after the dev server restarts (or in a fresh build).

See also

• For Claude Code agents: the docs skill — same content, agent-targeted.
• Tokens source of truth: design-system/DESIGN.md. Hand-edit; generated artifacts flow from it.
• VitePress docs: vitepress.dev for the framework itself (Vue in markdown, frontmatter, custom theme).