Design standards for the Help Center

All contributors

This page is the canonical reference for how the StandShare Help Center is written, structured, and styled. Anyone editing pages in this site — staff, volunteers, or contractors — should follow these conventions so the Help Center stays consistent.

The Help Center is built with Docusaurus 3 and organized around the Diátaxis framework: Getting Started, How-To, Reference, Explanation, and Changelog. It takes visual and structural inspiration from two best-in-class documentation sites:

• Stripe Docs — task-oriented layout, dual entry points (by capability and by role), minimal landing page, answer-first posture.
• Laravel Docs — persistent left sidebar, right-side "On this page" table of contents, generous whitespace, clear heading hierarchy.

We adapt selectively. StandShare docs serve non-technical users — volunteers, parents, and venue staff — not developers. Anything that would feel like API reference or framework jargon is out.

Voice and tone

• Plain language. No jargon. Users are volunteers and parents, not engineers. If a term is unavoidable, link it to the Glossary.
• Mobile-first. Many users read these pages from their phone at a concession stand. Short paragraphs, clear headings, tap-sized buttons in screenshots.
• Problem-focused, then solution. Lead with the pain ("You need to record a shift but the worker didn't show up"), then the fix.
• Action-oriented. Guide users to do things, not just to understand them.
• Warm but professional. Community-serving, not corporate. Never condescending.
• Tagline: Earned, Not Estimated.

Page structure

Every Help Center page follows this shape:

1. Frontmatter — title, description, and (where applicable) sidebar_position.
2. H1 page title — matches the frontmatter title.
3. Role badge line — one or more badges indicating who this page is for (see below).
4. Short intro paragraph — one or two sentences stating what the user will accomplish.
5. H2 sections — the main body. Use numbered lists for steps, never bullets.
6. H3 subsections — only when an H2 section has more than one clear phase.
7. Next Steps section — every page ends with a ## Next Steps H2 suggesting 2–3 logical next pages.

tip

If a page needs a fourth heading level (H4), that's usually a sign the page is doing too much. Consider splitting it into two pages and cross-linking.

Typography

Element	Font	Size	Weight	Line height
H1	Figtree	1.75rem	700	1.3
H2	Figtree	1.35rem	600	1.3
H3	Figtree	1.1rem	600	1.3
Body	Plus Jakarta Sans	1rem	400	1.6
Code	system mono	0.95em	400	—

Fonts are loaded from Google Fonts via the @graditipro/standshare-brand package. The CSS variables are --brand-font-heading and --brand-font-body.

Color

The Help Center uses the StandShare brand palette. Do not introduce new colors in page content — use these tokens.

Token	Hex	Use
--brand-navy	#0F2D46	Primary text, navbar
--brand-blue	#1F4FD8	Links, primary buttons
--brand-green	#1E6A57	Success states, tip admonitions
--brand-gold	#C8A951	Accents, warning admonitions
--brand-gray	#6B7280	Secondary text
--brand-concrete	#F3F4F6	Page background

Layout

Element	Value
Content max-width	750px
Left sidebar width	260px
Right "On this page" TOC	Docusaurus default, sticky
Page background	#F3F4F6 (concrete)
Content card background	#FFFFFF, 8px radius, 2rem padding

Dark mode is disabled site-wide. The brand Header and Footer components do not support it. Do not add dark-mode CSS to new components.

Role badges

Every page must have at least one role badge at the top, between the H1 and the first paragraph, indicating who the page is for.

<span class="badge badge--family">Family</span>

Available badge classes:

Class	Label	Use
badge badge--family	Family	Pages for Family Leads
badge badge--coordinator	Coordinator	Pages for Event Coordinators
badge badge--admin	Admin	Pages for Organization Administrators
badge badge--guest	Guest	Pages for Guest Workers
badge badge--all	All	Pages that apply to every role

A page can carry more than one badge if the same workflow applies to multiple roles (e.g., "Check compliance status" applies to Admin and Family Lead). Put each badge in its own <span>, separated by a space.

Callouts (admonitions)

Use Docusaurus admonitions for callouts. Four variants:

:::tip
Use for non-obvious shortcuts, power-user advice, and "you probably didn't know this" hints.
:::

:::info
Use for neutral contextual information the reader should notice but doesn't need to act on.
:::

:::warning
Use for gotchas, things that can be undone but are annoying to fix, and compliance reminders.
:::

:::danger
Use sparingly — for destructive actions, data loss, or anything that can't be undone.
:::

Do not nest admonitions. Do not use admonitions as a styling trick to make ordinary text stand out — they lose meaning when overused.

Numbered steps

Procedural instructions are always numbered lists, not bullets. Each step is one action.

Good:

1. Sign in to StandShare.
2. Click **Events** in the left nav.
3. Click **New Event**.

Bad:

- Sign in to StandShare, then click Events, then click New Event.

Use bold for UI element names (**New Event**, **Settings > Users**), but never for emphasis in prose — that's what the sentence is for.

Links

• Internal links use relative paths: [Family Quick Start](/docs/getting-started/family-quickstart).
• Cross-link generously. Every page should link to at least one other related page in its Next Steps section.
• Never paste raw URLs into prose. Always use link syntax with descriptive text. "Click here" (as link text) is banned — the link text should describe the destination.

Screenshots

• Use a consistent browser frame (title bar + chrome) around every product screenshot.
• Annotate important UI elements with numbered callouts that match a numbered list in the surrounding text.
• Store screenshots next to the page that references them, not in a global images folder.
• Descriptive filenames: create-event-step3-assign-families.png, not screenshot1.png.
• Capture at 2× / retina so images stay sharp on high-DPI displays.
• Mobile screenshots where a workflow is meaningfully different on phone vs. desktop.

Search

The Help Center uses @easyops-cn/docusaurus-search-local — a fully local search index, no external service, no tracking. The keyboard shortcut is Cmd+K on Mac and Ctrl+K on Windows/Linux.

When writing, use headings and descriptive page titles that match how users would phrase a search. Users searching for "settle an event" should find the settlement guide even if the official product term is "settlement".

What we don't copy from Stripe or Laravel

Pattern	Why not
Dark mode	Disabled site-wide; brand doesn't support it.
Language / version switchers	Not applicable for a single-version end-user product.
API reference integration	Lives in the platform repo's OpenAPI spec, not here.
Code sandbox embeds	This is end-user documentation, not developer documentation.
Marketing-style hero on every page	The landing page has a hero. Interior pages are answer-first.

Checklist for new pages

Before merging a new Help Center page, verify:

• Frontmatter has title and description.
• H1 matches the frontmatter title.
• Role badge line is present immediately after the H1.
• Intro paragraph is one or two sentences.
• Procedural steps use numbered lists, not bullets.
• UI element names are wrapped in **bold**.
• At least two cross-links to related pages.
• ## Next Steps section at the bottom with 2–3 links.
• Screenshots (if any) use the consistent browser frame and live next to the page.
• Page reads cleanly on a 375px-wide mobile viewport.
• pnpm --filter @standshare/docs-site build passes locally.

Next Steps

• How the Help Center is organized — the Diátaxis framework and why we use it.
• Glossary — shared vocabulary for the whole site.
• Contribute or submit feedback — report a gap or suggest a change.