#2 - feat: note detail page prototype — kitchen sink - ldraney/pal-e-docs-playground

forgejo_admin commented

2026-03-27 06:55:35 +00:00

Author

Contributor

PR #2 Review

DOMAIN REVIEW

Tech stack: Vanilla HTML/CSS/JS playground -- no build tools, no npm, no frameworks. 6 HTML pages, 1 shared CSS file, 1 JS file (Mermaid CDN import only). This is a design prototype for pal-e-docs note rendering, intended for mobile-first validation before SvelteKit port.

Positive findings:

Design tokens via CSS custom properties -- all colors, spacing, fonts, radii, shadows, and transitions are tokenized in :root. No hardcoded hex values in component styles. This is exactly what the issue asked for.
Mobile-first architecture -- single @media (min-width: 600px) breakpoint. Sidebars hidden on mobile with hamburger toggle. Board uses scroll-snap for mobile column swiping. Correct pattern.
Atkinson Hyperlegible font with proper preconnect and display=swap -- matches issue requirement.
Universal block renderer -- note.html demonstrates heading, paragraph, code, table, list, and Mermaid blocks. The @route/@data/@api/@components HTML comments serve as SvelteKit port contracts. Excellent documentation practice.
Board is separate from block rendering (own page, own layout) -- matches the "board is the ONE exception" architecture note.
Mermaid loaded only where needed -- app.js included only on note.html and note-project.html, not globally. Good performance decision.
Hamburger button only appears on pages with sidebars, and has proper aria-label. Good accessibility.
SVG graph with legend, semantic edge types (solid=parent-child, dashed=reference), and type-colored nodes. Well-structured static prototype.
Three-panel layout on desktop (left sidebar, content, right sidebar) with sticky positioning. Clean implementation.

BLOCKERS

None. This is a playground prototype with no user input, no auth, no backend, and no build system. The BLOCKER criteria (tests, input validation, secrets, auth DRY) do not apply to static HTML prototypes. Test coverage is validated through visual review on device, which the Test Plan correctly specifies.

NITS

Missing :root closing brace (app.css line 68-70). The :root { block opens at line 4 but is never closed with }. The --shadow-sm declaration at line 68 is the last token inside :root, then the RESET section begins at line 73 with *, *::before, *::after. Browsers error-recover here and it works, but it is a structural bug that will break if the CSS is ever parsed by a strict tool or linter. Add } after line 68.
Undefined CSS variables --col-todo, --col-in_progress, --col-done. These are referenced in note-board.html (lines 52, 71, 108) and note-project.html (lines 139-141) but never defined in app.css. The comment at line 44 says /* Column status colors */ followed by an empty block. The board column dots and progress bar segments will render with no background color. Add definitions like:
```
--col-todo: #dc2626;
--col-in_progress: #2563eb;
--col-done: #28a745;
```
data-type mismatch in notes.html. Almost every note card has data-type="sop" regardless of actual note type. Lines 55-56 (convention badge, sop data-type), 59-60 (convention badge, sop data-type), 67-68 (doc badge, sop data-type), 71-72 (project-page badge, sop data-type). Since data-type drives the left-border color via CSS attribute selectors, all cards except the last one render with the wrong border color. Fix each data-type to match the displayed badge.
Dead CSS: .note-card-row defined twice (app.css lines 775 and 799). The first definition (flexbox) is completely overridden by the second (grid). Lines 775-792 are dead code. Remove the first block.
Dead CSS: .note-card-header and .note-card-tags styled then hidden. Defined at lines 475/483, restyled at 715/716, then globally hidden at lines 795/796 with display: none. Three rounds of styling for elements that are never shown. Remove the definitions at 475/483 and 715/716, keep only the display: none at 795/796 (or remove all four if these elements are also removed from HTML).
note.html line 265: wrong block class. The "Related" list uses class="block block--paragraph" but contains a <ul>. Should be class="block block--list" for semantic and visual consistency with the other list blocks.
Inconsistent nav across pages. index.html, notes.html, note-board.html, and graph.html lack the hamburger button. This is correct for pages without sidebars, but note-board.html could arguably benefit from a sidebar for board navigation on mobile. Minor -- note for SvelteKit port.

SOP COMPLIANCE

Branch named after issue: 1-note-detail-prototype matches issue #1
PR body follows template: Summary, Changes, Test Plan, Related sections present
Related references plan slug: No plan slug -- PR body references project-pal-e-docs note instead. Caller confirmed no plan slug, so this is acceptable for a standalone playground ticket.
No secrets committed: Verified -- no credentials, API keys, tokens, or .env files
No unnecessary file changes: All 8 files are directly related to the issue scope
Commit messages are descriptive: 4 commits with clear feat/fix prefixes and meaningful descriptions
PR body includes Closes #1

PROCESS OBSERVATIONS

Deployment frequency: This is the first real PR for this repo (main branch had only README.md). Establishes the playground as a living prototype. Good DORA pattern -- small, reviewable, shippable increment.
Change failure risk: Low. Static HTML with no backend, no state, no user input. The undefined CSS variables (nit #2) and data-type mismatches (nit #3) are visual bugs only.
Documentation quality: The @route/@data/@api/@components HTML comments are a standout practice. They serve as a contract for the SvelteKit port -- every page documents its route, data dependencies, API calls, and component decomposition. This makes the playground genuinely useful as a port specification, not just a visual mockup.
Port readiness: The CSS is well-structured for copy-paste to SvelteKit. Design tokens, component-scoped classes, and the Svelte component comments in CSS sections make the handoff path clear.

VERDICT: APPROVED

The nits (unclosed :root, missing column color variables, data-type mismatches, dead CSS) are all fixable in a follow-up. None affect the core purpose: validating note rendering design on mobile before SvelteKit port. The prototype is well-architected with clean separation of concerns, excellent documentation annotations, and a solid mobile-first foundation.

## PR #2 Review ### DOMAIN REVIEW **Tech stack:** Vanilla HTML/CSS/JS playground -- no build tools, no npm, no frameworks. 6 HTML pages, 1 shared CSS file, 1 JS file (Mermaid CDN import only). This is a design prototype for pal-e-docs note rendering, intended for mobile-first validation before SvelteKit port. **Positive findings:** - **Design tokens via CSS custom properties** -- all colors, spacing, fonts, radii, shadows, and transitions are tokenized in `:root`. No hardcoded hex values in component styles. This is exactly what the issue asked for. - **Mobile-first architecture** -- single `@media (min-width: 600px)` breakpoint. Sidebars hidden on mobile with hamburger toggle. Board uses scroll-snap for mobile column swiping. Correct pattern. - **Atkinson Hyperlegible font** with proper `preconnect` and `display=swap` -- matches issue requirement. - **Universal block renderer** -- `note.html` demonstrates heading, paragraph, code, table, list, and Mermaid blocks. The `@route`/`@data`/`@api`/`@components` HTML comments serve as SvelteKit port contracts. Excellent documentation practice. - **Board is separate** from block rendering (own page, own layout) -- matches the "board is the ONE exception" architecture note. - **Mermaid loaded only where needed** -- `app.js` included only on `note.html` and `note-project.html`, not globally. Good performance decision. - **Hamburger button** only appears on pages with sidebars, and has proper `aria-label`. Good accessibility. - **SVG graph** with legend, semantic edge types (solid=parent-child, dashed=reference), and type-colored nodes. Well-structured static prototype. - **Three-panel layout** on desktop (left sidebar, content, right sidebar) with sticky positioning. Clean implementation. ### BLOCKERS **None.** This is a playground prototype with no user input, no auth, no backend, and no build system. The BLOCKER criteria (tests, input validation, secrets, auth DRY) do not apply to static HTML prototypes. Test coverage is validated through visual review on device, which the Test Plan correctly specifies. ### NITS 1. **Missing `:root` closing brace** (`app.css` line 68-70). The `:root {` block opens at line 4 but is never closed with `}`. The `--shadow-sm` declaration at line 68 is the last token inside `:root`, then the RESET section begins at line 73 with `*, *::before, *::after`. Browsers error-recover here and it works, but it is a structural bug that will break if the CSS is ever parsed by a strict tool or linter. Add `}` after line 68. 2. **Undefined CSS variables `--col-todo`, `--col-in_progress`, `--col-done`**. These are referenced in `note-board.html` (lines 52, 71, 108) and `note-project.html` (lines 139-141) but never defined in `app.css`. The comment at line 44 says `/* Column status colors */` followed by an empty block. The board column dots and progress bar segments will render with no background color. Add definitions like: ```css --col-todo: #dc2626; --col-in_progress: #2563eb; --col-done: #28a745; ``` 3. **`data-type` mismatch in `notes.html`**. Almost every note card has `data-type="sop"` regardless of actual note type. Lines 55-56 (convention badge, sop data-type), 59-60 (convention badge, sop data-type), 67-68 (doc badge, sop data-type), 71-72 (project-page badge, sop data-type). Since `data-type` drives the left-border color via CSS attribute selectors, all cards except the last one render with the wrong border color. Fix each `data-type` to match the displayed badge. 4. **Dead CSS: `.note-card-row` defined twice** (`app.css` lines 775 and 799). The first definition (flexbox) is completely overridden by the second (grid). Lines 775-792 are dead code. Remove the first block. 5. **Dead CSS: `.note-card-header` and `.note-card-tags` styled then hidden**. Defined at lines 475/483, restyled at 715/716, then globally hidden at lines 795/796 with `display: none`. Three rounds of styling for elements that are never shown. Remove the definitions at 475/483 and 715/716, keep only the `display: none` at 795/796 (or remove all four if these elements are also removed from HTML). 6. **`note.html` line 265: wrong block class**. The "Related" list uses `class="block block--paragraph"` but contains a `<ul>`. Should be `class="block block--list"` for semantic and visual consistency with the other list blocks. 7. **Inconsistent nav across pages**. `index.html`, `notes.html`, `note-board.html`, and `graph.html` lack the hamburger button. This is correct for pages without sidebars, but `note-board.html` could arguably benefit from a sidebar for board navigation on mobile. Minor -- note for SvelteKit port. ### SOP COMPLIANCE - [x] Branch named after issue: `1-note-detail-prototype` matches issue #1 - [x] PR body follows template: Summary, Changes, Test Plan, Related sections present - [ ] Related references plan slug: No plan slug -- PR body references `project-pal-e-docs` note instead. Caller confirmed no plan slug, so this is acceptable for a standalone playground ticket. - [x] No secrets committed: Verified -- no credentials, API keys, tokens, or .env files - [x] No unnecessary file changes: All 8 files are directly related to the issue scope - [x] Commit messages are descriptive: 4 commits with clear feat/fix prefixes and meaningful descriptions - [x] PR body includes `Closes #1` ### PROCESS OBSERVATIONS - **Deployment frequency:** This is the first real PR for this repo (main branch had only README.md). Establishes the playground as a living prototype. Good DORA pattern -- small, reviewable, shippable increment. - **Change failure risk:** Low. Static HTML with no backend, no state, no user input. The undefined CSS variables (nit #2) and data-type mismatches (nit #3) are visual bugs only. - **Documentation quality:** The `@route`/`@data`/`@api`/`@components` HTML comments are a standout practice. They serve as a contract for the SvelteKit port -- every page documents its route, data dependencies, API calls, and component decomposition. This makes the playground genuinely useful as a port specification, not just a visual mockup. - **Port readiness:** The CSS is well-structured for copy-paste to SvelteKit. Design tokens, component-scoped classes, and the Svelte component comments in CSS sections make the handoff path clear. ### VERDICT: APPROVED The nits (unclosed `:root`, missing column color variables, data-type mismatches, dead CSS) are all fixable in a follow-up. None affect the core purpose: validating note rendering design on mobile before SvelteKit port. The prototype is well-architected with clean separation of concerns, excellent documentation annotations, and a solid mobile-first foundation.

2026-03-27 06:50:37 +00:00

Summary

Multi-page playground prototype for pal-e-docs: note detail, notes list, board, project page, graph
Kitchen-sink rendering: headings, code blocks, tables, callouts, type-colored cards
Mobile-first design validation before SvelteKit port

Changes

index.html: Landing page scaffold and updates
note.html: Note detail page prototype — full block rendering kitchen sink
notes.html: Notes list page with type-colored cards
note-board.html: Board view prototype
note-project.html: Project page prototype
graph.html: Knowledge graph visualization
app.css: Universal design system — typography, layout, block styles
app.js: Shared navigation and interaction logic

Test Plan

Review on phone (mobile-first validation)
Verify layout, typography, and content block rendering
Confirm navigation between pages works
Approve design direction for SvelteKit port

Review Checklist

No secrets committed
No unnecessary file changes
Commit messages are descriptive

project-pal-e-docs — the project this work belongs to

Closes #1

## Summary - Multi-page playground prototype for pal-e-docs: note detail, notes list, board, project page, graph - Kitchen-sink rendering: headings, code blocks, tables, callouts, type-colored cards - Mobile-first design validation before SvelteKit port ## Changes - `index.html`: Landing page scaffold and updates - `note.html`: Note detail page prototype — full block rendering kitchen sink - `notes.html`: Notes list page with type-colored cards - `note-board.html`: Board view prototype - `note-project.html`: Project page prototype - `graph.html`: Knowledge graph visualization - `app.css`: Universal design system — typography, layout, block styles - `app.js`: Shared navigation and interaction logic ## Test Plan - [ ] Review on phone (mobile-first validation) - [ ] Verify layout, typography, and content block rendering - [ ] Confirm navigation between pages works - [ ] Approve design direction for SvelteKit port ## Review Checklist - [x] No secrets committed - [x] No unnecessary file changes - [x] Commit messages are descriptive ## Related Notes - `project-pal-e-docs` — the project this work belongs to Closes #1

forgejo_admin added 4 commits

feat: scaffold playground with initial landing page d7c9bfe3bc

Follows convention-frontend-css: Atkinson Hyperlegible, #fafafa bg, mobile-first.
Landing page placeholder while note detail prototype is built.

Refs: forgejo_admin/pal-e-docs-playground#1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: kitchen-sink note detail prototype — mobile-first d98d017d16

Three-panel note detail page with all 6 block types:
- Headings with anchor links, paragraphs, code blocks,
  tables, ordered/unordered lists, Mermaid diagrams
- Left sidebar: recently modified, projects, hierarchy tree
- Right sidebar: TOC, backlinks, children
- Nav bar with brand, links, search, auth

CSS follows pal-e-playground philosophy:
- Mobile-first: base styles = 390px phone, single breakpoint at 600px
- Zero hardcoded hex outside :root tokens
- All colors via var(--token)
- Atkinson Hyperlegible, #fafafa bg, max-width 48rem
- Svelte prop signatures in CSS comments
- Data contract comment in HTML (@route, @data, @api)

Refs: forgejo_admin/pal-e-docs-playground#1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: multi-page playground — universal block renderer, type-colored cards, graph 2266820be8

6 pages with working navigation:
- Dashboard (activity-first, recent notes, projects, in-progress)
- Notes list (recency-sorted, filter pills for active types)
- Note detail (universal block renderer — all 6 block types)
- Project page (architecture diagram, board progress, repos table)
- Board (kanban columns — the one note type with its own renderer)
- Graph (parent-child edges + type-colored nodes)

Design decisions:
- Block types (heading, paragraph, code, table, list, mermaid) map 1:1
  to Svelte components. BlockRenderer dispatches by block_type.
- Note types are a badge property on NoteLayout, NOT separate components.
  Board is the only exception (KanbanBoard renderer).
- Active types in filter pills: sop, convention, doc, project-page, board.
  Plan/phase are legacy, not featured.
- No callouts — not a real block type in the backend.
- Cards: type-colored left border, badge + time top row, title below.
- Mobile hamburger toggle for sidebar on note/project pages.

CSS guide compliance:
- Mobile-first, single @media (min-width: 600px) breakpoint
- Zero hardcoded hex outside :root tokens (rem not px)
- Svelte component signatures in CSS comments
- Data contract comments (@route, @data, @api) on every page

Refs: forgejo_admin/pal-e-docs-playground#1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: remove dead callout CSS — not a real block type 6adae3fc0a

Callout blocks were removed from HTML in previous commit but CSS
remained as dead code. Cleaned up.

Refs: forgejo_admin/pal-e-docs-playground#1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>