Activity

1. johnnyhuy

   self-assigned this

   on Apr 21, 2026
2. johnnyhuy commented on Aug 17, 2026

   

   johnnyhuy

   on Aug 17, 2026

   ContributorAuthor

   More actions

   PRD #87 — Homepage Onboarding + Support Docs

   Problem Statement

   A first-time visitor to the Developer Portal lands on the homepage and sees a catalog-first layout: search bar, popular templates, recent entities, system health, quick links. Onboarding, support, and API reference are present but tucked away:

   • A single one-line Alert "Getting Started?" banner (line 591 in HomePage.tsx) that just points at /docs.
   • A small "Getting Started" sidebar card at the bottom-right with four emoji-prefixed buttons (line 991), buried under the health card and quick links panel.
   • No dedicated surface for support (how do I get help?), no obvious jump-to-API-reference for someone who already knows what they want.
   • The sidebar nav (Root.tsx) has Home / Catalog / APIs / Docs / Self-Service — fine for returners, no onboarding affordance for first-use.

   The result: a developer who arrives via a shared link or onboarding email has to hunt to figure out what the portal is for, where to start, or where to get unstuck.

   Solution

   Reorient the homepage around a first-use orientation flow without removing the catalog surfaces. Three new homepage affordances, plus tighter integration with existing routes:

   1. "Start here" onboarding panel — a prominent 3-card panel directly below the hero, each card a single concrete first action ("Create your first service", "Browse the docs index", "Register an existing repo"). Replaces the one-line Alert.
   2. "Support & reference" quick-access grid — a single section linking to: TechDocs index, API explorer, support contact / FAQ entity, and the "How to get help" doc.
   3. Surfaced entity docs on the homepage — when TechDocs entities exist, show 2–4 highlighted docs from the catalog as cards (e.g. most-recently-updated or tagged onboarding). Falls back gracefully if there are none.

   The existing catalog-overview, templates, recent-entities, health, and quick-links panels stay where they are. The homepage becomes: Hero → Onboarding → Catalog overview → Templates + recent → Support + Health sidebar. Catalog remains first-class but is no longer the only first impression.

   User Stories

   1. As a first-time developer visiting the portal, I want a clear "start here" panel on the homepage, so that I know what my first action should be within 5 seconds of landing.
   2. As a first-time developer, I want one-click access to "Create your first service" from the homepage, so that I can scaffold a project without learning navigation first.
   3. As a first-time developer, I want to see the top 2–4 onboarding docs surfaced on the homepage, so that I don't have to dig through /docs to find the entry points.
   4. As a developer who already knows what they want, I want quick links to TechDocs, API explorer, and support, so that I can jump straight there without scrolling through catalog stats.
   5. As a developer who's stuck, I want a clear "Get help" link on the homepage, so that I know where to ask questions when something breaks.
   6. As a returning developer, I want the existing catalog overview, templates, and recent-entity panels to stay where they are, so that my muscle memory isn't broken.
   7. As a portal admin, I want onboarding content to be driven by entity metadata (tags like onboarding, support, getting-started) rather than hard-coded text, so that updating content doesn't require a frontend PR.
   8. As a portal admin, I want the "highlighted docs" surface to be filterable by tag, so that I can curate which docs appear without changing component code.
   9. As a portal admin, I want the onboarding panel to be theme-aware (GitHub Light/Dark + Legacy), so that it doesn't break the brand work from PR fix: GitHub theme and catalog view padding gaps #91.
   10. As a developer on mobile, I want the onboarding cards to stack to a single column gracefully, so that I don't get horizontal scroll on small screens.
   11. As an accessibility-focused developer, I want every onboarding/support link to have descriptive aria-label, so that screen readers can navigate the homepage efficiently.
   12. As a returning user, I want the homepage hero search to keep working, so that my search-first workflow isn't regressed.

   Implementation Decisions

   • Module to modify: the homepage component (currently a single ~1057-line HomePage.tsx). Splitting into sub-components is out of scope for this PRD — keep it as one file but extract a clear section API (e.g. <OnboardingSection />, <SupportSection />, <HighlightedDocsSection />) so future work can lift them out.
   • New "start here" panel sits between the hero and the existing quick-actions grid. Three cards: Create, Browse docs, Register existing. Each card uses the same CardActionArea pattern as the existing quick-actions, so visual consistency is automatic.
   • New "Support & reference" panel sits in the right sidebar below the existing "Quick Links" panel, OR replaces it (decision: replace — quick links becomes the support surface, since current quick links are mostly catalog-adjacent and better surfaced as a single support grid). Discuss with user.
   • "Highlighted docs" panel uses the existing catalogApi.getEntities({ filter: [{ kind: 'component', 'metadata.tags': 'onboarding' }] }) pattern. Fetches at most 4, renders as a grid of cards (title, owner avatar, link to /docs/{namespace}/{kind}/{name}). Skeleton-loaders and an empty-state "No onboarding docs tagged yet" message (with a hint about the onboarding tag) are required.
   • Entity-driven content: the homepage reads entity tags rather than hard-coded labels. The 3 onboarding cards are derived from routes that already exist (/self-service, /docs, /catalog-import). The "highlighted docs" cards are derived from catalog entities tagged onboarding or getting-started.
   • No new routes. All onboarding/support destinations are existing routes (/self-service, /docs, /catalog-import, /api-docs, /explore, /notifications).
   • No new sidebar items (the sidebar is fine; this PRD is about the homepage itself, not nav).
   • No new dependencies. All required components (Card, CardActionArea, Grid, Skeleton, Chip, Avatar) are already imported in the current homepage.
   • Theme compatibility: the new sections must render correctly under all three registered themes (brand-light, brand-dark, default) and not regress the theme/padding fixes from PR fix: GitHub theme and catalog view padding gaps #91. Use the same theme.palette.* lookups, no hard-coded hex.
   • Data loading: the existing fetchAllData effect already runs catalogApi.getEntities for components/systems/etc. Extend it to also fetch entities tagged onboarding / getting-started. Reuse the same loading/empty/error pattern.
   • Out of scope (in this PRD): rewriting the hero, restructuring the sidebar nav, building a new onboarding authoring tool, integrating with any third-party help-desk (Slack, Jira).

   Testing Decisions

   • What makes a good test: assert user-visible behaviour (sections render, links navigate, cards appear when entities exist, empty-state appears when they don't). Do NOT assert implementation details like the exact useState shape or the order of Promise.all calls.
   • Modules to test: the homepage component (Playwright component test under packages/app/src/components/home/HomePage.test.tsx, if/where it exists) plus a screenshot/regression test if the repo has one.
   • Prior art: the existing homepage already tests the catalog-stats loading state via Skeletons; the same Skeleton pattern is the precedent for empty/loading states in the new sections.
   • Manual QA checklist:
     • Land on / with no onboarding-tagged entities → "highlighted docs" shows empty-state, not a broken layout.
     • Land on / with ≥1 onboarding-tagged entity → card(s) render and link to /docs/....
     • Switch themes (GitHub Light / Dark / Legacy) → all new sections honour the theme.
     • Resize to mobile (≤600px) → onboarding cards stack vertically; no horizontal scroll.
   • No backend changes, so no backend test coverage required.

   Out of Scope

   • Replacing the existing sidebar (Root.tsx) navigation.
   • Building a CMS-style onboarding authoring tool.
   • Adding new support channels (Slack, Jira Service Desk, etc.).
   • Any change to the catalog-import flow or scaffolder templates — that's covered by PRD Package reusable software templates and starter structures #88.
   • Localisation / i18n.
   • Personalisation ("show me docs I haven't read") — that needs user-history wiring.

   Further Notes

   • PR fix: GitHub theme and catalog view padding gaps #91 (fix/theme-and-catalog-padding) touches the same HomePage.tsx file (indirectly via EntityPage.tsx + grid-fix.css). Land fix: GitHub theme and catalog view padding gaps #91 first so the new sections inherit the fixed Grid spacing.
   • The two new homepage sections should not duplicate the existing Getting Started sidebar card — consolidate into one onboarding card grid in the main column and drop the sidebar card.
   • Source notes for this PRD: Weekly Notes/2024 - Week 43.md, Weekly Notes/2024 - Week 46.md, Notes/2024-11-29 - Revamp Velo Homepage.md (user's Obsidian vault; not in this repo).
3. johnnyhuy

   added

   enhancementNew feature or requestNew feature or request

   on Aug 17, 2026
4. johnnyhuy

   added 2 commits that reference this issue on Aug 18, 2026

   feat: homepage onboarding flow and AI-native software templates

   ...

   8e0ecab

   feat: homepage onboarding flow and AI-native software templates (#96)

   ...

   5321b9b
5. johnnyhuy

   closed this as completedin #96on Aug 24, 2026