Guide content system — authoring reference

For Dori (CONTENT-1). Built against .planning/phases/v4.21-phase-2-content-overhaul/UI-SPEC.md (Desi, CONTENT-UISPEC-1). Every pattern below is copy-pasteable — no design decisions left open.

P1 — Page template

Every content page: # Title → one-sentence lede → hero <GuideFigure> → ## Section task sections → ## Keep going related cards → prev/next pager (automatic from sidebar order).

P2 — Lede

Just write it — the first paragraph after the H1 is styled automatically.

# Habits & streaks

Habits turn a goal into something you do — not something you mean to do.

P3 — Section headings

Plain ## / ### — the section rule and TOC entry are automatic.

## Create a habit

P4 — Screenshot figure (GuideFigure)

<GuideFigure
  src="/assets/dashboard_desktop.png"
  alt="Habits dashboard on desktop"
  variant="browser"
  label="app.objectuve.com · Today's practice"
  caption="Your habits for today, each with a one-tap check-in ring." />

• variant: browser (desktop/web captures, full width, chrome bar) · phone (portrait app captures, capped ~300px, device bezel — use this for every phone screenshot, never plain) · plain (diagrams/wide art, default if omitted).
• alt is required — the component logs a dev warning if it's empty.
• label only matters for variant="browser"; defaults to app.objectuve.com if omitted.
• caption is optional; omit the attribute entirely if you don't have one (don't pass caption="").
• Images live in guide_site/public/assets/ — reference them as /assets/<file>.png.

P5 — Numbered steps

Wrap a normal ordered list in a guide-steps div. Bold the lead clause of each step.

<div class="guide-steps">

1. **Tap the + on the Dashboard or Goals tab.** Choose **Habit** as the type.
2. **Name it and set a pattern.** Daily, a few days a week, or your own schedule.
3. **Save.** It lands in **Today's practice**, ready for its first check-in.

</div>

P6 — Callouts

::: tip Coach
Start with one habit, not five. A single streak you keep beats a wall of broken ones.
:::

::: info
Your streak is information, not a threat — a rest day is part of the practice.
:::

::: warning Heads up
Streak freezes are limited. Spend them on the days that really need it.
:::

::: danger Careful
Erasing your data can't be undone. Export first if you want a copy.
:::

::: details Every recurrence pattern
| Pattern | How it works |
|---|---|
| **Daily** | Due every day |
:::

Roughly one Coach callout per page; never open a section with a callout — lead with a sentence.

P7 — Reference table

Plain markdown table. Keep it to ≤2–3 columns so it reads without horizontal scroll at 390px; put denser tables inside a ::: details block.

| What you do | What happens to your streak |
|---|---|
| Check in on a scheduled day | +1 day |
| Miss a day with a freeze available | Held — the freeze covers it |

P8 — Related cards (GuideCards / GuideCard)

## Keep going

<GuideCards>
  <GuideCard title="Mood check-in" href="/mood-check-in" tint="accent"
    body="Log how today felt in a single tap — it takes two seconds." />
  <GuideCard title="Achievements, XP & ranks" href="/achievements-xp-and-ranks" tint="gold"
    body="Every check-in earns XP — see how streaks climb the ranks." />
</GuideCards>

• tint: one of primary / accent / gold / success / muted. Each card in a row should use a different tint — never repeat one in the same grid.
• Heading is "Keep going" for feature pages, "See also" for reference pages (Settings, Notifications).
• 1–2 cards is normal; the grid wraps to 2 columns at ≥640px on its own.
• icon is optional — a default glyph is supplied per tint if you omit it.

P9 — Inline UI labels & keys

**Settings → Appearance**
<span class="guide-nowrap">Settings <span aria-hidden="true">→</span> Appearance</span>

Press <kbd>?</kbd> anywhere in the app to see what each streak symbol means.

Use the guide-nowrap span only if a Label → Path breaks awkwardly mid-line; plain **bold** is fine otherwise.

P10 — Breadcrumb + pager

Nothing to author — GuideBreadcrumb reads the page's group from GROUP_BY_PAGE in .vitepress/theme/GuideBreadcrumb.vue, and the pager follows sidebar order in .vitepress/config.ts. If you add or rename a page, add it to both — GROUP_BY_PAGE and the sidebar — or the breadcrumb/pager will be wrong or missing for that page.

P11 — Feature-status notice (Teams-light)

::: info Teams
Teams is in active development. This page is a quick overview — the full walkthrough lands soon.
:::

Open the Teams page with this, then a short honest overview. No numbered steps, no deep field tables — Phase 4 owns the real walkthrough once v4.19 ships.

P12 — Interactive walkthrough (GuideWalkthrough / GuideStep)

For Codi (INTERACT-1) / Dori (INTERACT-DOCS-1). Built against .planning/phases/v4.21-phase-3-interactivity/UI-SPEC.md (Desi, INTERACT-UISPEC-1). One reusable step-through player, instantiated once per major feature area — never build a bespoke walkthrough.

<GuideWalkthrough title="Build a habit, keep a streak" variant="phone">
  <GuideStep
    src="/assets/create_goal.png"
    alt="Choosing Habit as the goal type, with the recurrence section open"
    caption="Start a new goal and choose Habit — a recurrence section appears." />
  <GuideStep
    src="/assets/dashboard_with_goal.png"
    alt="A new habit in Today's practice with an empty check-in ring"
    caption="Pick a pattern — daily, weekly, custom, or every N days." />
  <!-- …3 more GuideStep… -->
</GuideWalkthrough>

• variant: phone (default, capped ~230px, device bezel) or browser (full width, chrome bar — pass label for the bar text). Matches GuideFigure's framing so it reads as one system.
• Every GuideStep needs alt (required whenever src is set) and caption (one brand-voice sentence — shown beside the frame for whichever step is active).
• GuideStep also takes two optional props, added in v4.26 Phase 5: title (a short per-step headline shown above the caption; omit it and the step falls back to caption-only) and pin (a [x, y] percentage of the phone's 9/19 screen box, for the same animated pin used by the article rail — omit it and no pin renders for that step).
• A GuideStep can render a default slot instead of src for a screen with no capture yet — use sparingly; screenshots are the default per the UI-SPEC's open-question resolution.
• Reader controls the pace: Back / thumbnail filmstrip / Next, plus arrow keys and touch-swipe. No auto-advance, no loop — the last step offers "Start over," never an auto-restart.
• Author at least 2 GuideStep children; the build fails on a missing src asset.

P13 — Stateful demos (GuideCheckinDemo / GuideCoachToneDemo / GuideRankMeter / GuideStreakSimulator)

Four small, self-contained interactive widgets — each teaches one signature interaction better than a screenshot can. No props needed beyond the optional ones shown.

<GuideCheckinDemo habit-name="Morning walk" />

<GuideCoachToneDemo />

<GuideRankMeter />

<GuideStreakSimulator />

• GuideCheckinDemo — tap the ring to check in (fills green, streak +1, "+25 XP" chip); tap again to reset and replay. habit-name is optional (defaults to "Morning walk").
• GuideCoachToneDemo — persona chips + a Gentle⟷Tough slider rewrite a live sample line from the UI-SPEC's persona×tone matrix. No props.
• GuideRankMeter — an XP slider + preset chips (+25 / +50 / +500) recompute the level ring, rank name, and XP-to-next-rank from the shipped ladder (caps at 20,000 = Legacy). No props.
• GuideStreakSimulator (v4.26 Phase 5) — 14 tappable days + Streak/Grace left/XP earned/Verdict stat tiles teach the grace-day rule: one grace day to start, one more per 7 days of streak, two adjacent misses always break it. No props; lives on /habits-and-streaks.
• All four are deterministic and client-only reactive — no network calls, no Date.now().

Voice checklist (every page)

• Second person, action-forward: "Check in each day," not "Users can check in."
• Lede says what the feature is for, not what it is.
• "Coach," never "AI." Streak is information, never a threat.
• Prefer a numbered step or table over a paragraph for anything procedural or comparative.
• Never document a control that isn't shipped — use the P11 pattern + "Coming soon" instead.