From bce52150a51b64156530a94edc3c6bac61722517 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Mon, 13 Jul 2026 18:30:38 +0200 Subject: [PATCH] docs(design): Sync the HTML prototype with the shipped course UI The UI reached its stable milestone (student catalogue, instructor authoring, error pages), so the browsable prototype in docs/design/mockups catches up with the app in one pass, per the sync-at-stable-milestones policy: - css/base.css realigned with the app stylesheet (explicit skip-link focus, Markdown textarea, inline action forms, roster table styles). - dashboard.html now mirrors the shipped dashboard: the aspirational stats row and progress bars give way to the enrollment cards with status and date. - Nine new snapshots: courses, course, lesson (Markdown output with demoted headings, ADR-0014), the four instructor pages, and the styled error page; index.html lists them all. - course-pages-explained.md documents the batch in the study-doc tradition, one noticing point per page. --- docs/design/mockups/course-pages-explained.md | 45 +++++++ docs/design/mockups/course.html | 68 ++++++++++ docs/design/mockups/courses.html | 58 ++++++++ docs/design/mockups/css/base.css | 43 ++++++ docs/design/mockups/dashboard.html | 45 ++----- docs/design/mockups/error.html | 49 +++++++ docs/design/mockups/index.html | 34 ++++- .../mockups/instructor-course-editor.html | 125 ++++++++++++++++++ docs/design/mockups/instructor-courses.html | 61 +++++++++ .../mockups/instructor-lesson-editor.html | 67 ++++++++++ docs/design/mockups/instructor-students.html | 83 ++++++++++++ docs/design/mockups/lesson.html | 62 +++++++++ 12 files changed, 706 insertions(+), 34 deletions(-) create mode 100644 docs/design/mockups/course-pages-explained.md create mode 100644 docs/design/mockups/course.html create mode 100644 docs/design/mockups/courses.html create mode 100644 docs/design/mockups/error.html create mode 100644 docs/design/mockups/instructor-course-editor.html create mode 100644 docs/design/mockups/instructor-courses.html create mode 100644 docs/design/mockups/instructor-lesson-editor.html create mode 100644 docs/design/mockups/instructor-students.html create mode 100644 docs/design/mockups/lesson.html diff --git a/docs/design/mockups/course-pages-explained.md b/docs/design/mockups/course-pages-explained.md new file mode 100644 index 0000000..81b5862 --- /dev/null +++ b/docs/design/mockups/course-pages-explained.md @@ -0,0 +1,45 @@ +# The course and instructor mockups, explained + +Unlike the original four mockups (which preceded the Thymeleaf templates), +these nine pages were added *after* the course UI shipped: they are the +shipped templates frozen as static HTML with sample data, so the prototype +stays a faithful, browsable snapshot of the real interface. The sync happens +at stable UI milestones only, not per merged pull request. + +What each page snapshots, and the one thing worth noticing on it: + +- **courses.html** (student catalogue): each `course-card` carries the + "You are enrolled" marker inside `course-card__meta`, the state the + controller computes per card. +- **course.html** (course detail): shown in the just-enrolled state, so the + success alert (`role="status"`) and the "Quit this course" form are both + visible. Enroll/quit are POST forms, never links: they change state. +- **lesson.html**: the `
` holds what `MarkdownRenderer` outputs. + The instructor authored `# Why lists matter`, but it arrives as an `h2`: + headings are demoted one level at render time so the page keeps exactly + one `h1` (RGAA 9.1, [ADR-0014](../../adr/0014-demote-markdown-headings-in-lesson-rendering.md)). +- **dashboard.html** (updated): the earlier stats-and-progress concept is + gone; the shipped dashboard lists the student's active enrollments with + status and enrollment date. Stats may return later; the mockup tracks what + is real. +- **instructor-courses.html**: the authoring entry point lists all statuses + (Draft, Published, Archived), unlike the student catalogue. +- **instructor-course-editor.html**: one page hosts the edit form, the + publication lifecycle actions (only the transitions the current status + allows are rendered), and lesson management. The per-lesson buttons carry a + `visually-hidden` suffix ("Move up: Loops without tears") so a screen + reader hears which lesson each button acts on, while sighted users read + the row. +- **instructor-lesson-editor.html**: `textarea.form__input` is the Markdown + editor; the hint reminds authors that output is sanitized (ADR-0013). +- **instructor-students.html**: the roster uses the `.table` block with a + `visually-hidden` caption; the Remove action only renders for enrollments + that can still be dropped. +- **error.html**: the styled 404 that replaced the Whitelabel page; 403 and + 500 use the same skeleton with different copy. + +Shared wiring on every page, inherited from the app templates: skip link +targeting `main#main` with `tabindex="-1"` (explicit focus move), one `h1`, +`aria-current="page"` on the active nav entry, and role-aware nav (the +Instructor entry appears only on instructor pages, where an instructor is +logged in). diff --git a/docs/design/mockups/course.html b/docs/design/mockups/course.html new file mode 100644 index 0000000..4e119fe --- /dev/null +++ b/docs/design/mockups/course.html @@ -0,0 +1,68 @@ + + + + + + Course — learn-dev + + + + + + + + + +
+
+ learn-dev + +
+
+ +
+

+ You are enrolled in this course. +

+ +

Python for curious minds

+

By demo-teacher

+ +

Loops, lists, and a taste of the standard library.

+ +
+
+ +
+
+ +
+

Lessons

+
    +
  1. Lists in five minutes
    2. +
  2. Loops without tears
    3. +
+
+ +

Back to all courses

+
+ +
+
+

learn-dev, an interactive programming learning platform.

+

Source on GitHub

+
+
+ + diff --git a/docs/design/mockups/courses.html b/docs/design/mockups/courses.html new file mode 100644 index 0000000..b212d17 --- /dev/null +++ b/docs/design/mockups/courses.html @@ -0,0 +1,58 @@ + + + + + + Courses — learn-dev + + + + + + + + + +
+
+ learn-dev + +
+
+ +
+

Courses

+ + +
+ +
+
+

learn-dev, an interactive programming learning platform.

+

Source on GitHub

+
+
+ + diff --git a/docs/design/mockups/css/base.css b/docs/design/mockups/css/base.css index 27af86e..7f617e1 100644 --- a/docs/design/mockups/css/base.css +++ b/docs/design/mockups/css/base.css @@ -136,6 +136,12 @@ code { top: 0; } +/* The skip link moves focus onto main (tabindex="-1"); no ring on a + non-interactive landmark (WCAG 2.4.7 applies to interactive controls) */ +main:focus { + outline: none; +} + /* ---------- Site header ---------- */ .site-header { @@ -410,6 +416,43 @@ code { padding: 0.6em 0.8em; } +/* Markdown editors and long descriptions */ +textarea.form__input { + min-height: 8rem; + resize: vertical; +} + +/* Action buttons that sit inside a line of text or a list item */ +.form--inline { + display: inline; +} + +/* ---------- Data tables (e.g. the course roster) ---------- */ + +.table { + width: 100%; + border-collapse: collapse; + background: var(--color-surface); + border: 1px solid var(--color-border); + border-radius: var(--radius); +} + +.table th, +.table td { + text-align: left; + padding: var(--space-2) var(--space-3); + border-bottom: 1px solid var(--color-border); +} + +.table th { + font-family: var(--font-display); + font-size: var(--font-size-sm); +} + +.table tr:last-child td { + border-bottom: 0; +} + .form__input:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 1px; diff --git a/docs/design/mockups/dashboard.html b/docs/design/mockups/dashboard.html index d43905b..1823f82 100644 --- a/docs/design/mockups/dashboard.html +++ b/docs/design/mockups/dashboard.html @@ -19,6 +19,7 @@