Design: /reflect daily reflection page

Date: 2026-07-01 Status: Approved (design)

Summary

A dedicated, standalone page where a learner can come to reflect on their learning journey at any time, independent of any chapter. It reuses the existing ReflectionBeat component (write a short reflection, then generate a shareable card) but feeds it its own track-agnostic "learning journey" prompt bank.

v1 is deliberately simple: one shared bank, no level dropdown. The seam for a future beginner/intermediate/senior dropdown is documented but not built (YAGNI).

Goals

• A calm, minimal page at /reflect for open-ended journey reflection.
• A separate prompt bank that is about the learner (progress, struggles, motivation, growth), not about a specific Python or AI concept.
• A nav entry ("Reflect") so it is discoverable.
• Maximum reuse of ReflectionBeat; no new card/share logic.

Non-goals (v1)

• Level dropdown (beginner / intermediate / senior). Designed-for-later, not built.
• Localization of the page or bank (English only for now, matching how-ai-works).
• Persistence / streaks / "daily" tracking. It is a reflection space, not a journal store.

Architecture

Four small pieces. The existing ReflectionBeat does all the real work.

1. New prompt bank — docs/.vitepress/theme/lib/reflectionPrompts.js

Add a new track reflect to the PROMPTS object with a single journey bank. Resolved through the existing promptsFor(chapter, track) helper, so no new plumbing is needed.

reflect: {
  journey: [
    { q: 'What pushed you to start learning to code?' },
    { q: 'What is something that finally clicked for you recently?' },
    { q: 'What is the hardest part of learning for you right now?' },
    { q: 'What kind of developer do you want to become?' },
    { q: 'What is one win from this week you are proud of?' },
    { q: 'When you get stuck, what gets you unstuck?' },
    { q: 'What is a skill you have now that you did not have a month ago?' },
    { q: 'What would make today feel like a good day of learning?' },
    { q: 'What is one habit that has helped your progress the most?' },
    { q: 'What do you want to understand better than you do today?' },
    { q: 'What advice would you give the version of you who just started?' },
    { q: 'What keeps you going when learning feels slow?' },
  ],
},

Style rules (consistent with the file's existing banks and project memory): no right-or-wrong questions, self-contained, short, shareable, no em-dashes, no charged/sensitive words, no presumptuous "you already know X" framing.

2. ReflectionBeat extension — docs/.vitepress/theme/components/ReflectionBeat.vue

Backward-compatible changes only. Existing chapter beats are unaffected.

• Add a track entry:

  reflect: { label: 'DAILY REFLECTION', base: 'reflect' },

• Make the chapter prop optional (required: false, default: ''). It is only used for the share/card URL and the download filename; the bank comes from promptsFor(chapter, track) which still resolves correctly for reflect/journey.
• Make the share/card destination degrade cleanly when there is no real chapter sub-page. docsUrl should point at the track base (docs.scrimba.com/reflect) rather than .../reflect/journey (which is not a real page):

  const docsUrl = computed(() =>
    props.chapter ? `${docsHost}/${trackCfg.value.base}/${props.chapter}`
                  : `${docsHost}/${trackCfg.value.base}`
  )

  (Note: cardUrl already points at the base, so for reflect both the footer line on the card and the copy-to-clipboard share string land on /reflect.)
• Download filename: fall back when chapter is empty so the file is not named my-take--portrait.png:

  a.download = `my-take-${props.chapter || 'reflection'}-${format.value}.png`

No template or styling changes. The component still renders identically; only the derived URLs/filename and the new track label change.

3. The page — docs/reflect.md

A minimal standalone page. Frontmatter hides the chrome that would make it feel like a chapter:

---
title: Daily Reflection
sidebar: false
aside: false
prev: false
next: false
---

<div class="reflect-hero">
  <p class="reflect-eyebrow">Daily Reflection</p>
  <h1 class="reflect-title">Take a moment to reflect</h1>
  <p class="reflect-lead">A quiet space to think about where you are in your
  learning journey. Pick a prompt, write a few honest lines, and share it if you want to.</p>
</div>

<ReflectionBeat track="reflect" chapter="journey" />

• The hero is plain markup styled with a small scoped-ish block (a <style> in the page or reuse of existing vp tokens) kept minimal: eyebrow, title, one lead line.
• No CTAs / promo (per project rule). The ReflectionBeat card's own "connect with us" socials are the only outward links, which is existing behavior.
• chapter="journey" selects the bank; track="reflect" sets the kicker/label and share URL.

4. Nav — docs/.vitepress/config.ts

Add a nav entry next to Docs:

nav: [
  { text: 'Home', link: '/' },
  { text: 'Docs', link: '/docs', activeMatch: '^/(docs|python/(?!playground)|how-ai-works)' },
  { text: 'Reflect', link: '/reflect' },
  { text: 'Search', link: '#search' },
],

/reflect is not under /python/ or /how-ai-works/, so it inherits no sidebar (intended — it is a clean standalone page).

Data flow

1. Page mounts <ReflectionBeat track="reflect" chapter="journey" />.
2. bank resolves via promptsFor('journey', 'reflect') → the journey bank.
3. Component picks a random prompt; user writes (<=180 chars), hits "Create card".
4. Card canvas renders with kicker "DAILY REFLECTION" and footer URL docs.scrimba.com/reflect.
5. User can change prompt, download the card (PNG), or copy the share string.

Future extension (not in v1): level dropdown

When levels are wanted, add a thin wrapper component (e.g. DailyReflection.vue) that owns a level ref and selects among reflect.journey-beginner / -intermediate / -senior banks, passing the chosen bank to ReflectionBeat via its existing :prompts override prop. The page swaps <ReflectionBeat ... /> for <DailyReflection />. No ReflectionBeat changes required for that step.

Testing / verification

• pnpm dev, visit /reflect: page renders with hero + reflection card, no sidebar/aside.
• Prompt comes from the journey bank; "Change question" cycles within it.
• Create a card: kicker reads "DAILY REFLECTION", footer URL is docs.scrimba.com/reflect.
• Download produces my-take-journey-*.png; copy share string ends with /reflect.
• Regression: open an existing chapter (e.g. /how-ai-works/agents) and confirm its ReflectionBeat is unchanged (kicker, URL, filename all still chapter-based).
• Nav shows "Reflect" and routes correctly.

Files touched

• docs/.vitepress/theme/lib/reflectionPrompts.js (new bank)
• docs/.vitepress/theme/components/ReflectionBeat.vue (optional chapter, reflect track, URL/filename fallback)
• docs/reflect.md (new page)
• docs/.vitepress/config.ts (nav entry)