L&D platform page standard (The Forge)

Purpose: Define how internal L&D courses present on the Brainforge Platform when a track is implemented as app routes—without prescribing a visual redesign of existing pages. The live reference is the Quickstart track, implemented under the foundation slug: overview UI, module redirect behavior, and lesson layout.

Audience: L&D authors, platform engineers, and anyone running ld-course-builder Mode D (wire course to platform).

Related: course-authoring-playbook.md (vault authoring) · NORTH-STARS.md (pedagogy) · Quickstart implementation under apps/platform/src/app/(main)/learning/foundation/

Last updated: 2026-04-17

1. Principles

No deviation from the Quickstart UI pattern for new tracks unless product explicitly approves a redesign. Reuse the same component hierarchy, spacing, and layout proportions as apps/platform/src/app/(main)/learning/foundation/FoundationOverviewClient.tsx (overview) and apps/platform/src/app/(main)/learning/foundation/[slug]/[lessonSlug]/page.tsx (lesson page).
Vault remains source of truth for markdown. Platform code maps slugs to files; authors edit README.md and lesson-*.md in the vault tree.
Module “landing” is not a separate bespoke page today: the module route is a redirect entry point to the first lesson, and the intro lesson renders module copy from modules/{NN}-{slug}/README.md (see below).

2. Course overview page standard

The course overview is custom per track in code (Quickstart uses FoundationOverviewClient). Layout intent:

Region	Content
Breadcrumbs	Trail to internal Learning home → track name (current segment is the track, not the lesson).
Hero	Course title, short description, primary CTA consistent with Quickstart.
Stat chips	e.g. audience, duration, level — same chip idiom as Quickstart.
“What you’ll learn”	Bulleted outcomes (can mirror course `README.md`).
Main columns	Left: curriculum timeline by phase (phase badge, description, module list with duration and status). Right (sticky on large screens): progress, track details, and all modules list mirroring Quickstart’s right rail.
Responsive	On small viewports, columns stack; sticky behavior matches Quickstart (see QA).

When a new track is wired to the Platform, it must also be registered in the shared learning navigation surfaces:

apps/platform/src/components/Sidebar.tsx under Learning & Development
apps/platform/src/app/(main)/learning/LearningAreaSubnav.tsx if the track should appear in the top-level learning area tabs

Wireframe (course overview)

[breadcrumbs: Learning & Development > {Track name}]

{course title}
{short description / hero copy}

[ stat chip: audience ] [ stat chip: duration ] [ stat chip: type / level ]

What you’ll learn
- {outcome 1}
- {outcome 2}
…

+-----------------------------------------------------------------------+
| [left column]                          | [right column — sticky lg+] |
| PHASE 1 — {label}                      | Progress                    |
| {phase description}                    | {bar / % if applicable}     |
|   M1 — {module}  [Start here]  30 min  | Details                     |
|   M2 — {module}              30 min    | {audience, time, …}        |
| PHASE 2 — {label}                      | All modules                 |
| …                                      | {compact list / links}      |
+-----------------------------------------------------------------------+

Do not invent a new overview anatomy for internal tracks unless explicitly chartered; clone the Quickstart structure and swap data.

3. Module page standard

Rule	Detail
Route shape	`{trackBase}/{moduleSlug}` — e.g. `/learning/foundation/m1-cursor-github-setup`.
Behavior	HTTP redirect to the first lesson for that module (see `apps/platform/src/app/(main)/learning/foundation/[slug]/page.tsx`).
Canonical UX	The intro lesson page is the module “home.” There is no separate module-only template in production today.
Intro body source	`modules/{NN}-{module-slug}/README.md`. The lesson renderer loads the module README for the intro lesson so authors maintain one file (see lesson page implementation: `readFoundationModuleReadme` + intro branch).
Future	A dedicated module overview page is out of scope unless leadership decides otherwise; this doc should be updated if that changes.

Wireframe (module route — user never sees a standalone template)

GET {trackBase}/{moduleSlug}
  -> 302/redirect  ->  {trackBase}/{moduleSlug}/{firstLessonSlug}

The rendered first screen matches the lesson page wireframe (section 4) with intro content from the module README.

4. Lesson page standard

Stable pattern used by Quickstart (breadcrumbs, optional previous link, optional video, markdown body, sticky sidebar).

Block	Behavior
Breadcrumbs	Same component/trail as overview (`FoundationTrackBreadcrumbs` for Quickstart).
Optional previous link	Row linking to the previous lesson (label + href from spine navigation).
Optional video	If the lesson body contains a Zoom Clips URL, the first such link is extracted and rendered in `LearningLessonVideoEmbed`; that line is stripped from markdown (see `extractFirstZoomClipsUrl` / `stripFirstZoomClipLine`).
Markdown body	Rendered in the shared markdown component with vault link resolution (`CertificationsMarkdown` + knowledge link root).
Intro lesson title	For the intro lesson, the module title from nav may be passed as a leading title; body comes from module README.
Sticky sidebar	Right column (sticky on `lg+`): module progress, lesson list for the course, Next / end-of-module behavior (`LearningLessonSidebar`).
Layout	Main column + sidebar; `flexDirection` column on `xs`, row on `lg` (matches Quickstart).

Wireframe (lesson page)

[breadcrumbs]

[ optional: < Previous — {label} ]

[ optional: video embed — Zoom Clip ]

{lesson markdown content card}

+----------------------------+------------------+
| Main column                | Sidebar (sticky) |
|                            | Progress         |
|                            | Course content   |
|                            | {modules/lessons}
|                            | Next → …         |
+----------------------------+------------------+

5. Required platform metadata (typed config contract)

Each course that gets a platform implementation should have a small TypeScript contract (constants + types) colocated with that track’s nav—patterned after Quickstart, not necessarily one global file for all future tracks.

5.1 Suggested types

Authors and Mode D use this as the checklist of fields to fill. Engineers map them to the overview client and lesson spine.

/** Phase / group for the curriculum timeline (Quickstart-style). */
export type LdCoursePhaseType = "required" | "optional";
 
export interface LdPlatformModuleRef {
  /** Stable id for routes and progress, e.g. m1-cursor-github-setup */
  id: string;
  /** Display label, e.g. M1 — Cursor + GitHub Setup */
  label: string;
  /** Shown in chips / timeline, e.g. 30 min */
  duration: string;
  /** Optional: highlight first module */
  isStartHere?: boolean;
}
 
export interface LdPlatformPhase {
  id: string;
  badge: string;
  label: string;
  description: string;
  type: LdCoursePhaseType;
  modules: LdPlatformModuleRef[];
}
 
/**
 * Typed course config for a single L&D track on the platform.
 * Keep in sync with vault: programs/courses/{courseSlug}/
 */
export interface LdCoursePlatformConfig {
  /** Kebab-case folder under knowledge/.../programs/courses/ */
  courseSlug: string;
  /** Base path for this track’s routes (see section 7 for path consistency) */
  routeBase: string;
  /** Full course title for hero / metadata */
  title: string;
  /** Short name for breadcrumbs / nav */
  shortTitleForBreadcrumbs: string;
  audience: string;
  /** e.g. ~4 hours */
  durationSummary: string;
  /** e.g. Self-paced, Async-first */
  courseTypeLabel?: string;
  /** Ordered phases for the left column */
  phases: LdPlatformPhase[];
  /** Module order as slugs — must match vault module folders and nav builders */
  moduleOrder: string[];
  /** Map module id -> duration string (chips / timeline) */
  moduleDurations: Record<string, string>;
  /** Bullets for “What you’ll learn” on overview */
  whatYoullLearn: string[];
  /** Optional link to certification rubric (vault URL or app route) */
  certificationRubricHref?: string;
}

5.2 Engineering notes

Lesson spine (prev/next, first lesson per module) should be derived from the same ordered data as the vault—typically a generateStaticParams companion and a navigation builder (Quickstart: foundationLessonNavigation.ts).
Slug lists must stay consistent: moduleOrder, per-module lesson files, and redirect targets.

6. Authoring-to-platform mapping

Vault artifact	Platform use
Course `README.md`	Overview copy: title, description, outcomes, “what you’ll learn,” duration, audience.
Module `README.md`	Intro lesson body for that module (first lesson in the module).
`lesson-{N}-{slug}.md`	Subsequent lesson bodies; first Zoom Clips link → embedded video.
`certification-rubric.md`	Linked from overview or sidebar when `certificationRubricHref` (or equivalent) is set.

Quickstart additionally maps legacy monolithic module files in some code paths; new courses should standardize on per-lesson files + module README per the course authoring playbook.

7. QA checklist (before shipping a new track)

8. Route base paths (documentation note)

The learning tracks should use the public /learning/... route family consistently.

Location	Path pattern (example)
`foundationNav.ts` — `FOUNDATION_BASE`	`/learning/foundation`
Track breadcrumbs first link	`/learning/courses`
Track overview / lesson routes	`/learning/{trackId}/...`

Guidance: New tracks should follow the same public route shape unless there is an explicit migration or compatibility requirement.

9. Reference implementation (Quickstart)

Concern	Primary files
Overview UI	`apps/platform/src/app/(main)/learning/foundation/FoundationOverviewClient.tsx`
Module redirect	`apps/platform/src/app/(main)/learning/foundation/[slug]/page.tsx`
Lesson page	`apps/platform/src/app/(main)/learning/foundation/[slug]/[lessonSlug]/page.tsx`
Nav + slugs + markdown path maps	`apps/platform/src/lib/foundationNav.ts`
Lesson ordering / prev-next	`apps/platform/src/lib/foundationLessonNavigation.ts`

10. Workflow pointer

To turn authored vault content into platform routes without changing Quickstart’s existing UI, use ld-course-builder Mode D — Wire course to platform (see .cursor/skills/ld-course-builder/SKILL.md), which reads this document and scaffolds config + route wiring patterned after Quickstart.

Brainforge Knowledge

Explorer

platform-page-standard