Refactor H5P skill page layout to enhance readability and structure; implement step markers for improved user navigation

Author: alekswebnet

src/assets/site.css

@@ -574,27 +574,27 @@ tbody th a:hover code { text-decoration: underline; }
 .footer-links a { color: var(--muted); text-decoration: none; }
 .footer-links a:hover { color: var(--text); text-decoration: underline; }
 
-/* The h5p-author skill's files, /h5p/skill/: whole addresses, which give way on a phone. */
-.skill-files a { overflow-wrap: anywhere; }
+/* The H5P pages, the build page and the skill's: one wide column, its prose at --measure, and its
+   sections as steps. */
+:is(.build, .skill) { max-width: var(--page-width); }
+.build-brand { margin-bottom: 1.25rem; font-size: 0.9375rem; }
+/* A longer heading than the docs' package names, so it gives way on a phone. */
+:is(.build, .skill) .docs-header h1 { font-size: clamp(1.75rem, 1.2rem + 3vw, 2.25rem); }
+/* Prose keeps a line a reader can follow; the source, the lists and what plays take the whole width. */
+:is(.build, .skill) p:not(.status) { max-width: var(--measure); }
 
 /* H5P build page, /h5p/build/ */
 .build {
-  max-width: var(--page-width);
   --ok: var(--live);
   --bad: var(--t-tag);
   /* Masked, like the preview pane's icons, so they take a color like text does. */
   --icon-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m5 12.5 4.5 4.5L19 7.5'/%3E%3C/svg%3E");
   --icon-alert: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3' stroke-linecap='round'%3E%3Cpath d='M12 5v8.5M12 18.5v.01'/%3E%3C/svg%3E");
 }
-.build-brand { margin-bottom: 1.25rem; font-size: 0.9375rem; }
-/* A longer heading than the docs' package names, so it gives way on a phone. */
-.build .docs-header h1 { font-size: clamp(1.75rem, 1.2rem + 3vw, 2.25rem); }
-/* Prose keeps a line a reader can follow; the source, the lists and what plays take the whole width. */
-.build p:not(.status) { max-width: var(--measure); }
-
-/* The steps are a timeline: a marker for each, on a rail that runs on to the next. A step the page
-   hides, as the files of a source that names none, is not on it, and the rail ends at the last shown. */
-.build .step {
+/* The steps are a timeline, on this page and the skill's: a marker for each, on a rail that runs on
+   to the next. A step the page hides, as the files of a source that names none, is not on it, and
+   the rail ends at the last shown. How a step stands, done or wrong, is the build page's alone. */
+.step {
   --marker: 2rem;
   --indent: calc(var(--marker) + 1rem);
   /* How the step stands, which the rules under these set from what the page says of it. */
@@ -605,7 +605,7 @@ tbody th a:hover code { text-decoration: underline; }
   position: relative;
   padding: 0 0 1.5rem var(--indent);
 }
-.build .docs-header + .step { margin-top: 2.5rem; }
+.docs-header + .step { margin-top: 2.5rem; }
 /* The source is JSON, every file it names is chosen, the build is ready: the step is done. */
 .build .step:is(
   :has(#source-state[data-state="ok"]),
@@ -626,7 +626,7 @@ tbody th a:hover code { text-decoration: underline; }
 }
 
 /* The rail, from under a step's marker to the next one's. It is a border, which forced colors keep. */
-.build .step::before {
+.step::before {
   content: "";
   position: absolute;
   top: calc(var(--marker) + 0.5rem);
@@ -637,14 +637,14 @@ tbody th a:hover code { text-decoration: underline; }
   transition: border-color 0.2s, opacity 0.3s, scale 0.3s ease-out;
 }
 /* None from the last step shown: it is drawn down to a step as that one joins. */
-.build .step:not(:has(~ .step:not([hidden])))::before { opacity: 0; }
+.step:not(:has(~ .step:not([hidden])))::before { opacity: 0; }
 /* A step that joins the others, the files or the play, comes in. */
 #files-step, #play-step { transition: opacity 0.3s ease-out, translate 0.3s ease-out; }
 @starting-style {
   #files-step, #play-step { opacity: 0; }
 }
 
-.build .step h2 {
+.step h2 {
   display: flex;
   align-items: center;
   min-height: var(--marker);
@@ -752,16 +752,20 @@ tbody th a:hover code { text-decoration: underline; }
 .build .status[data-state="building"] { border-left-color: var(--focus); background: var(--tint); }
 .build .status[data-state="ready"] { border-left-color: var(--ok); }
 .build .status[data-state="error"] { border-left-color: var(--bad); }
-/* The problems, the notes and the files, a row each. */
-.build .messages, .build .file-list {
+/* The problems, the notes and the files, a row each; on the skill page, its addresses. */
+.build .messages, .build .file-list, .skill-files {
   padding: 0;
   border: 1px solid var(--border);
   border-radius: var(--radius);
   background: var(--raised);
   list-style: none;
 }
-.build .messages li, .build .file-list li { margin: 0; padding: 0.55rem 0.85rem; overflow-wrap: anywhere; }
-.build .messages li + li, .build .file-list li + li { border-top: 1px solid var(--border); }
+.build .messages li, .build .file-list li, .skill-files li { margin: 0; padding: 0.55rem 0.85rem; overflow-wrap: anywhere; }
+.build .messages li + li, .build .file-list li + li, .skill-files li + li { border-top: 1px solid var(--border); }
+/* A whole address in the site's mono font, and what the file is, muted, after it. */
+.skill-files { color: var(--muted); }
+.skill-files li { font-size: 0.875rem; }
+.skill-files a { font-family: var(--mono); font-size: 0.9375em; }
 /* A file's name, then whether it is chosen: at the row's end where both fit on a line, under the name where they do not. */
 .build .file-list li {
   position: relative;
@@ -793,7 +797,7 @@ tbody th a:hover code { text-decoration: underline; }
 .player-box h5p-player { display: block; }
 
 @media (max-width: 480px) {
-  .build .step { --marker: 1.75rem; --indent: calc(var(--marker) + 0.75rem); }
+  .step { --marker: 1.75rem; --indent: calc(var(--marker) + 0.75rem); }
   .step-marker { font-size: 0.8125rem; }
   /* The last step has no rail beside it, so on a phone what plays takes the column's whole width. */
   .player-box { margin-left: calc(-1 * var(--indent)); }
@@ -807,7 +811,7 @@ tbody th a:hover code { text-decoration: underline; }
 
 /* What moves, only where motion is not asked to be reduced: the rail drawn down, a step coming up, the ring turning. */
 @media (prefers-reduced-motion: no-preference) {
-  .build .step:not(:has(~ .step:not([hidden])))::before { scale: 1 0; }
+  .step:not(:has(~ .step:not([hidden])))::before { scale: 1 0; }
   @starting-style {
     #files-step, #play-step { translate: 0 0.5rem; }
   }

src/h5p/skill/index.njk

@@ -34,16 +34,19 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; o
     </p>
   </header>
 
-  <section aria-labelledby="first-heading">
-    <h2 id="first-heading">Read first</h2>
-    <ul class="skill-files">
+  {#- The sections are steps, in the order a chat reads them, drawn as the build page's timeline
+      (site.css). The lists are drawn without bullets, and Safari then reads one as a list only if
+      it is told. -#}
+  <section class="step" aria-labelledby="first-heading">
+    <h2 id="first-heading"><span class="step-marker"><span class="step-number">1</span></span> Read first</h2>
+    <ul class="skill-files" role="list">
       <li><a href="{{ base }}SKILL.md">{{ base }}SKILL.md</a>: the skill's steps</li>
     </ul>
   </section>
 
-  <section aria-labelledby="named-heading">
-    <h2 id="named-heading">The files it names</h2>
-    <ul class="skill-files">
+  <section class="step" aria-labelledby="named-heading">
+    <h2 id="named-heading"><span class="step-marker"><span class="step-number">2</span></span> The files it names</h2>
+    <ul class="skill-files" role="list">
       {%- for path in skill.named %}
       <li><a href="{{ base }}{{ path }}">{{ base }}{{ path }}</a>
         {%- if path == "references/authoring.md" %}: the brief, read once
@@ -52,27 +55,27 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; o
     </ul>
   </section>
 
-  <section aria-labelledby="types-heading">
-    <h2 id="types-heading">A content type's file</h2>
+  <section class="step" aria-labelledby="types-heading">
+    <h2 id="types-heading"><span class="step-marker"><span class="step-number">3</span></span> A content type's file</h2>
     <p>
       One per content type: its notes, an example and its fields. Read the file of the type the
       source is written in, and those of the parts it holds, such as H5P.AdvancedText or H5P.Image.
     </p>
-    <ul class="skill-files">
+    <ul class="skill-files" role="list">
       {%- for path in skill.types %}
       <li><a href="{{ base }}{{ path }}">{{ base }}{{ path }}</a></li>
       {%- endfor %}
     </ul>
   </section>
 
-  <section aria-labelledby="bundles-heading">
-    <h2 id="bundles-heading">To build where npm cannot be reached</h2>
+  <section class="step" aria-labelledby="bundles-heading">
+    <h2 id="bundles-heading"><span class="step-marker"><span class="step-number">4</span></span> To build where npm cannot be reached</h2>
     <p>
       The build tool, which runs with Node and nothing installed, and a bundle per content type:
       the libraries a build of that type reads. Fetch the tool and the bundle of the source's own
       type, as step 3 of <code>SKILL.md</code> says.
     </p>
-    <ul class="skill-files">
+    <ul class="skill-files" role="list">
       {%- for file in skill.bundles %}
       <li><a href="{{ bundlesBase }}{{ file }}">{{ bundlesBase }}{{ file }}</a>
         {%- if file == "h5p-author.mjs" %}: the build tool{% endif %}</li>