Tighten the samples index metadata and filter/tile UX behavior.

Make tags real, sort dropdowns alphabetically with no duplicates, keep classes out of the description text, and use explicit Pinned/Unpinned text values while preserving preview-image launch behavior.

PR: BUILD_PR_SAMPLES_METADATA_TAG_NORMALIZATION_AND_FILTER_BAR_UX

Author: ToolboxAid

docs/dev/reports/samples_metadata_and_filter_bar_strategy.txt

@@ -3,14 +3,13 @@ Samples metadata + filter/tile UX strategy
 Goals:
 - convert tags into real metadata
 - keep class as a broad category
-- surface class values clearly
-- sort class filter values alphabetically
+- keep classes separate from description text
+- sort dropdown values alphabetically with no duplicates
 - keep search on the same row as Phase/Class/Tag
-- move pin affordance to preview top-right if cleanly supported
-- use green for pinned state
+- use explicit Pinned/Unpinned text instead of colored pin icons
+- preserve preview image launch behavior
+- preserve hover zoom behavior
 
 Preserve:
 - current accepted page shell
-- preview image launch behavior
-- hover zoom behavior
 - shared header/body consistency

docs/operations/dev/codex_commands.md

@@ -19,11 +19,12 @@ Rules:
 Required work:
 1. Normalize sample metadata so tags are real descriptive tags instead of duplicates of class values.
 2. Keep/assign a clear class value for each sample.
-3. Include/display the class list for each sample.
-4. Ensure class filter values are sorted alphabetically.
-5. Put search on the same row as Phase, Class, and Tag.
-6. Move the pin affordance to the top-right over the preview image if the current tile structure allows it cleanly.
-7. Make the pinned visual state green instead of red.
-8. Preserve preview image launch behavior and hover zoom.
-9. Keep filtering and pinning behavior working.
-10. Keep the change narrow, testable, and behavior-focused rather than redesigning the page.
+3. If classes are shown for each sample, show them outside the description text.
+4. Do NOT append classes/tags/phase metadata into the sample description body.
+5. Ensure class filter values are sorted alphabetically and contain no duplicates.
+6. Ensure tag filter values are sorted alphabetically and contain no duplicates.
+7. Put search on the same row as Phase, Class, and Tag.
+8. Use explicit `Pinned` / `Unpinned` text values instead of a red/green icon treatment.
+9. Preserve preview image launch behavior and hover zoom.
+10. Keep filtering and pinning behavior working.
+11. Keep the change narrow, testable, and behavior-focused rather than redesigning the page.

docs/operations/dev/commit_comment.txt

@@ -1,5 +1,5 @@
-Normalize samples metadata and tighten samples index filter/tile UX.
+Tighten the samples index metadata and filter/tile UX behavior.
 
-Convert tags into real descriptive tags, surface class values clearly, alphabetize class filter options, align search with Phase/Class/Tag, and move the pin affordance to the preview top-right with a green pinned state.
+Make tags real, sort dropdowns alphabetically with no duplicates, keep classes out of the description text, and use explicit Pinned/Unpinned text values while preserving preview-image launch behavior.
 
 PR: BUILD_PR_SAMPLES_METADATA_TAG_NORMALIZATION_AND_FILTER_BAR_UX

docs/pr/BUILD_PR_SAMPLES_METADATA_TAG_NORMALIZATION_AND_FILTER_BAR_UX.md

@@ -6,55 +6,66 @@ Improve `/samples/index.html` sample discovery by normalizing metadata and tight
 ## Single PR Purpose
 Fix the samples metadata and filter/tile behavior in one focused pass:
 - make tags real tags instead of duplicated class values
-- expose the sample class list clearly
-- sort classes alphabetically
+- expose the sample class list correctly
+- sort dropdown values alphabetically with no duplicates
 - align search on the same row as Phase / Class / Tag
-- move the pin affordance to the top-right over the preview image if allowed by the current tile structure
-- use green instead of red when pinned
+- restore pin behavior using explicit text values instead of colored icons
+- keep preview image as the launch link with hover zoom
 
 ## Metadata Rules
 ### Class
 - each sample must have a clear class value
 - class values should be broad categories
-- class options presented in the UI must be sorted alphabetically
+- class filter options presented in the UI must be sorted alphabetically
+- class filter options must not contain duplicates
 
 ### Tags
 - tags must be meaningful descriptive labels, not copies of class values
 - tags should reflect capabilities, behaviors, systems, or topics in the sample
-- examples:
-  - physics
-  - collision
-  - parallax
-  - networking
-  - debug
-  - editor
-  - tilemap
-  - input
-  - particles
-  - replay
+- tag filter options must be sorted alphabetically
+- tag filter options must not contain duplicates
 - tag filtering must use the real tag values
 
-### Class List Visibility
-- include/display the class list for each sample
-- keep it readable and clearly distinct from tags
+### Class List Display
+- class information may be shown in a dedicated class area/list for each sample if needed
+- do NOT append or inject the class list into the main sample description text
+- the sample description must remain a human-readable description only
+
+## Description Rule
+Do NOT include classes in the description text.
+
+Example of what must NOT happen:
+`Phase 03 | Classes: ... | Tags: ...` appended into the description body.
+
+Keep:
+- sample title
+- human-readable description
+
+Separate from description if shown elsewhere:
+- phase
+- classes
+- tags
 
 ## Filter Bar UX Rules
 - search must be on the same line as:
   - Phase
   - Class
   - Tag
+- dropdown options must be alphabetically sorted
+- dropdown options must not contain duplicates
 - keep the filter bar compact and readable
 - preserve existing functionality
 - do not redesign the entire page
 
-## Tile UX Rules
-### Pin
-- move pinned control/indicator to the top-right over the preview image if the tile structure allows it cleanly
-- pin should look like a pin, not a generic button
-- pinned visual state should change from red to green
-- preserve pinning behavior and pinned list behavior
+## Pin UX Rules
+- do NOT use a colored icon for pin/unpin state
+- pinned/unpinned must show explicit text values:
+  - `Pinned`
+  - `Unpinned`
+- pinning behavior and pinned list behavior must be preserved/restored
+- if placement over the preview image is retained, the text treatment must remain readable and clean
 
-### Preview Image
+## Preview Image Rules
 - keep preview image as the launch anchor
 - preserve hover zoom behavior
 - do not break launch behavior
@@ -64,14 +75,14 @@ Fix the samples metadata and filter/tile behavior in one focused pass:
 - no inline `style=""`
 - no JS-generated styling
 - keep scope limited to `/samples/index.html` and directly related sample metadata/rendering/filter dependencies
-- preserve the accepted page shell and shared header/body consistency
+- preserve the current accepted page shell and shared header/body consistency
 
 ## Acceptance
 - tags are real descriptive tags, not class duplicates
-- class values/lists are clearly available and class filter options are alphabetical
+- class/tag dropdown values are alphabetical and contain no duplicates
+- classes are not appended into the description text
 - search is on the same line as Phase / Class / Tag
-- pinned control is top-right over the preview image when allowed
-- pinned state uses green, not red
-- preview image remains the launch anchor with hover zoom
+- pin state shows `Pinned` / `Unpinned` text, not red/green icon treatment
+- preview image remains the launch link with hover zoom
 - filtering and pinning continue to work
 - change is visually and functionally testable

samples/assets/icons/pin-monocolor.svg

@@ -64,23 +64,40 @@
 }
 
 .sample-pin-label {
-  position: absolute;
-  top: 8px;
-  right: 8px;
-  z-index: 2;
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  min-width: 32px;
-  min-height: 32px;
-  border-radius: 999px;
-  border: 1px solid rgba(34, 197, 94, 0.75);
-  background: rgba(15, 23, 42, 0.72);
+  min-width: 1.15em;
+  min-height: 1.15em;
+  margin-right: 8px;
+  padding: 0;
   cursor: pointer;
   user-select: none;
+  font-size: 1.15em;
+  color: rgb(239, 68, 68);
 }
 
 .sample-pin-toggle:checked + .sample-pin-label {
-  background: rgba(34, 197, 94, 0.35);
-  border-color: rgba(34, 197, 94, 0.95);
+  color: rgb(34, 197, 94);
+}
+
+.sample-title-row {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.sample-pin-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  background-color: currentColor;
+  -webkit-mask-image: url("./assets/icons/pin-monocolor.svg");
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  -webkit-mask-size: contain;
+  mask-image: url("./assets/icons/pin-monocolor.svg");
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
 }

samples/index.css

@@ -32,6 +32,11 @@ <h1>Samples Hub</h1>
   </details>
 
   <main class="page-shell">
+    <section class="content-section">
+      <h2>Pinned Samples</h2>
+      <div id="samples-pinned-list" class="card-grid"></div>
+    </section>
+
     <section class="content-section">
       <h2>Filter Samples</h2>
       <p>Filter by phase, engine class, tag, or free-text search.</p>
@@ -62,11 +67,6 @@ <h2>Filter Samples</h2>
       <p id="samples-phase-filter-status" aria-live="polite"></p>
     </section>
 
-    <section class="content-section">
-      <h2>Pinned Samples</h2>
-      <div id="samples-pinned-list" class="card-grid"></div>
-    </section>
-
     <section class="content-section">
       <h2>All Phases and Samples</h2>
       <div id="samples-phase-list"></div>

samples/index.html

@@ -87,7 +87,9 @@ function buildSampleRows(metadata, pinnedSet) {
       }
       const titleText = normalize(sample?.title) || "Untitled";
       const phaseInfo = phaseInfoMap.get(phase);
-      const title = normalize(sample?.indexLabel) || `Sample ${id} - ${titleText}`;
+      const explicitLabel = normalize(sample?.indexLabel);
+      const titleAlreadyPrefixed = new RegExp(`^sample\\s+${id}\\s*-`, "i").test(titleText);
+      const title = explicitLabel || (titleAlreadyPrefixed ? titleText : `Sample ${id} - ${titleText}`);
       const description = normalize(sample?.description) || "No description available.";
       const href = normalize(sample?.href) || `./phase-${phase}/${id}/index.html`;
       const tags = asArray(sample?.tags).map((tag) => normalizeTag(tag)).filter(Boolean);
@@ -191,27 +193,26 @@ function buildSampleCard(sample) {
   pinLabel.setAttribute("for", pinInputId);
   pinLabel.setAttribute("title", sample.pinned ? "Unpin" : "Pin");
   pinLabel.setAttribute("aria-label", sample.pinned ? "Unpin sample" : "Pin sample");
-  pinLabel.textContent = "??";
+  pinLabel.innerHTML = `<span class="sample-pin-icon" aria-hidden="true"></span>`;
 
   previewWrap.appendChild(launch);
-  previewWrap.appendChild(pinInput);
-  previewWrap.appendChild(pinLabel);
 
   const title = document.createElement("h3");
-  title.innerHTML = `<a class="sample-title-link" href="${escapeHtml(sample.href)}">${escapeHtml(sample.title)}</a>`;
+  title.className = "sample-title-row";
+  title.appendChild(pinInput);
+  title.appendChild(pinLabel);
+  const titleLink = document.createElement("a");
+  titleLink.className = "sample-title-link";
+  titleLink.href = sample.href;
+  titleLink.textContent = sample.title;
+  title.appendChild(titleLink);
 
   const description = document.createElement("p");
   description.textContent = sample.description;
 
-  const meta = document.createElement("p");
-  const classLabel = sample.classTokens.length > 0 ? sample.classTokens.map((token) => token.label).join(", ") : "none";
-  const tagLabel = sample.tags.length > 0 ? sample.tags.join(", ") : "none";
-  meta.textContent = `Phase ${sample.phase} | Classes: ${classLabel} | Tags: ${tagLabel}`;
-
-  card.appendChild(previewWrap);
   card.appendChild(title);
+  card.appendChild(previewWrap);
   card.appendChild(description);
-  card.appendChild(meta);
   return card;
 }
 
@@ -339,4 +340,4 @@ export async function initSamplesIndex() {
 
 if (typeof window !== "undefined" && typeof document !== "undefined") {
   initSamplesIndex();
-}
+}