[IanMayo]

Summary

This is Round 4 of the onboarding work, following #49 (merged). It applies the product owner's change of 22 Oct 2026, which supersedes the 17 Oct decision that the walkthroughs start folded in the playground and in blog embeds. The walkthroughs are where a new user gains an overall understanding, so they now start open and stand out. SRD: CAP-25, OUT-05, NFR-09, NFR-13, CON-06, DEV-07, DEV-10.

Round 4: open by default, and a guidance accent

Open by default everywhere it appears

• Browser: the panel is open on first load in /demo, in the playground and in any blog embed that includes it.
  • At 1200 px and above it sits in the right-hand column. Below that it is at the top of the side column.
  • The playground used to force the panel folded on load (folds.setOpen("panel-tour", false)). That line is removed.
  • The reader can still fold it. Where folded panels are remembered (the playground and /demo, in the browser), a reader who folded it stays folded. Blog embeds remember nothing, so they start open every time.
  • The forced fold never shipped to main, so no stored state needs migrating.
• VS Code: the first activation after install opens Open and explore a serial on the Get Started page (workbench.action.openWalkthrough, debrief.debrief#explore). This happens once only.
  • The code is openOnFirstRun in vscode/src/walkthroughs.ts.
  • The global-state flag debrief.walkthrough.openedOnInstall is set before the page is asked for. So later starts never reopen it, and neither does a start after the page failed to open; a failure is logged.

A distinct accent (the "guidance accent")

• The colour: the theme's link colour, --vscode-textLink-foreground. Where a theme has none, --vscode-focusBorder is used instead.
  • The playground's theme.css now maps --vscode-textLink-foreground from VS Code's own values: Dark Modern #4daafc, Light Modern #005fb8.
  • In host.css the colour is --debrief-guide-accent, and the tint is color-mix of that colour over the panel background.
• Where it is applied:
  • a 3 px edge on the panel, running the full height of the column on wide screens;
  • a heading bar tinted with the accent (14% over the side bar's background);
  • step numbers in the accent, and the next step's number as a disc of the accent with the panel's background as its text;
  • the folded tab, which carries the edge and the tint.
• Contrast: measured and tested at WCAG AA (4.5:1) or better in both themes. The lowest ratio is 6.55:1 in dark and 5.02:1 in light, across 32 heading and step texts each, open and folded, in both the column and the side column.
• Data colours (the red and blue tracks and palette.ts) are unchanged. check:theme passes.
• VS Code's Get Started page is VS Code's own and follows VS Code's theme. The accent applies to the browser panel.

Docs

• The walkthroughs guide: open by default, the first-run walkthrough, the accent.
• Try Debrief.
• The blog post 2026-10-22-first-hour.md, including both of its images, regenerated from the test.
• The style guide's Theme table gains a "Guidance accent" row.
• docs/delivery-plan.md has a dated 22 Oct entry superseding the 17 Oct "folded elsewhere" decision, and the earlier entries are cross-referenced.

Check	Test
Open on first load in the playground (right-hand column at 1400 px)	play.mjs → openOnFirstLoad
Open on first load in /demo, dark and light, at 1366 px	play.mjs accentOn → openOnFirstLoad
Open on first load in the first hour post's embed (side column), with the edge	onboarding.mjs playTourInThePost
A reader who folded it stays folded after a reload	playTours starts from the fold made in play.mjs; tote.mjs remembered-folds check
The accent comes from the theme variable: edge, tinted bar, step numbers, next-step disc and folded tab, in light and dark, at 1366 and 900 px	onboarding.mjs guidanceAccent (computed styles compared with --vscode-textLink-foreground resolved in the page)
Contrast is at least 4.5:1 for heading and step text	guidanceAccent (WCAG ratio, alpha composited)
VS Code opens the walkthrough on first activation, and not on the next	test/integration/walkthroughs.ts firstRunWalkthrough; unit tests in walkthroughs.test.ts

A real second launch is not possible here: VS Code does not write its storage between launches under test. So the integration check for "not on the second" re-runs activation's first-run check against the same globalState, and confirms that no Get Started tab reopens.

Blog post (DEV-02, DEV-03, DEV-05)

• A post is needed, and it is in this pull request: site/docs/blog/posts/2026-10-22-first-hour.md (updated: the walkthroughs open by default, the first-run walkthrough in VS Code, the accent, and refreshed images)
• No post is needed, because:

Guides (DEV-07 to DEV-10)

• User-facing text follows the style guide's language section (check:language clean)
• Any new or changed interaction follows, or extends, an interaction model (guides/interaction-models/walkthroughs.md)
• Guides updated in this pull request where the change needs it: walkthroughs, Try Debrief, and the style guide's Theme (Guidance accent)

Sensitivity (DEV-05)

• The post, screenshots, sample data and guides contain nothing sensitive: unclassified sample data only, no real exercise or deployment data, organisations by initial only

Screenshots

/demo at 1366 px, dark and light:

The playground at 1366 px, dark and light:

Folded tab at 1366 px, and the side column at 900 px (dark, taken while Python was still loading):

The first hour post's embedded demo:

VS Code, on the first activation after install:

Test plan

Run on this branch's head:

• vscode: typecheck clean; vitest 643 passed (20 files); check:theme and check:language clean.
• VS Code integration (npm run test:integration under xvfb, VS Code 1.141.0): passed, including the new first-activation check.
• npm run test:play, 3 runs green in a row: 617 s, 599 s and 607 s. The speed run took 32 actions in 12.2, 11.8 and 12.6 s.
• scripts/build_site.sh (mkdocs --strict): clean.
• No Python or schema changes, so pytest and ruff were not rerun.

https://claude.ai/code/session_018c8QiHtanE5rfymqfArUYT

---

Generated by Claude Code

Site preview

Live preview: https://debrief.github.io/fuudee/pr-preview/pr-50/ (updated for 3c0e347; it can take a minute to appear). It is kept after this pull request closes; all previews.

The first hour: walkthroughs, and a web demo to try them in (blog/posts/2026-10-22-first-hour.md)

Walkthroughs (guides/interaction-models/walkthroughs.md)

Theme (guides/style-guide/theme.md)

Try Debrief (try.md)

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://debrief.github.io/fuudee/pr-preview/pr-50/
Built to branch gh-pages at 2026-10-22 21:31 UTC. Preview will be ready when the GitHub Pages deployment is complete.