laantungir/client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
client/plans/sidenav-unification-plan.md
Laan Tungir a8bbbbafb9 rename to client
2026-04-17 16:52:51 -04:00

5.9 KiB
Raw Permalink Blame History

Sidenav Unification Plan

Goal

Create one shared stylesheet for all sidenav sections so typography, spacing, alignment, collapse behavior, and interaction states are consistent across pages and future sidenav additions.

Current Context

Existing shared sidenav section styles

Shared section primitives already exist in www/css/client.css:

  • section container: .sidenavSection
  • section title: .sidenavSectionTitle
  • section list area: .sidenavSectionList
  • toggle icon: .sidenavSectionToggleIcon
  • collapsed behavior: .sidenavSection.collapsed ...
  • left-indent helper used by relay rows: .relayRowIndent

These are currently mixed into broader global styles in www/css/client.css, alongside many non-sidenav rules.

Page-local AI section styles causing drift

AI-specific row/detail styling is currently defined inside www/ai.html, including:

  • #divAiList
  • .aiProviderEntry
  • .aiProviderRow
  • .aiProviderName
  • .aiProviderToggle
  • .aiProviderDetails

Because these styles are local and partially overlap the shared section rules, visual mismatches can happen (font size, left alignment, row rhythm).

Target Architecture

1) New dedicated stylesheet

Add a new file:

This file will be the source of truth for all sidenav section styling.

It should contain:

  • Base section shell styling (container, title, list, collapse transitions)
  • Shared row primitives for list items inside any section
  • Shared indent/alignment primitives
  • Shared typography scale variables for section title, row, and details
  • Optional section variants via classes (not page IDs)

2) Style ownership boundaries

  • Keep page layout and global app shell styles in www/css/client.css
  • Move sidenav section system rules into www/css/sidenav-sections.css
  • Keep only truly section-specific behavior styles local to a page when needed, and only via semantic classes that extend the shared primitives

3) Class-based API for future sections

Define a reusable class contract for section internals:

  • .sidenavSection
  • .sidenavSectionTitle
  • .sidenavSectionList
  • .sidenavRow
  • .sidenavRowName
  • .sidenavRowMeta
  • .sidenavRowToggle
  • .sidenavRowDetails
  • .sidenavRowIndent

AI rows and relay rows should either use these classes directly, or map existing classes to these rules.

Migration Plan

Phase A — Extract and centralize

  1. Create www/css/sidenav-sections.css
  2. Move all section-system selectors from www/css/client.css into the new file:
    • .sidenavSection*
    • shared list/title/collapse transitions
    • indent helper currently represented by .relayRowIndent (rename or alias to shared .sidenavRowIndent)
  3. Keep temporary compatibility aliases during migration (example: .relayRowIndent and .sidenavRowIndent both styled the same)

Phase B — Adopt from pages

  1. Include the new stylesheet in pages that render sidenav sections (at minimum www/ai.html, www/post.html, and other pages with relay/blossom blocks)
  2. Refactor AI section styles in www/ai.html to consume shared row primitives:
    • Replace custom row sizing/alignment values with shared class values
    • Keep only AI-specific behavior styles (if any)

Phase C — Normalize JS-generated rows

  1. Update row creation in www/js/relay-ui.mjs to apply shared row classes:
    • row root gets .sidenavRow
    • name gets .sidenavRowName
    • counts get .sidenavRowMeta
    • status icon container gets .sidenavRowToggle
    • indent element gets .sidenavRowIndent
  2. Preserve current function behavior while changing only class assignment and style source

Phase D — Cleanup and hardening

  1. Remove duplicated page-local overrides once parity is verified
  2. Add comments in www/css/client.css documenting that sidenav sections are owned by www/css/sidenav-sections.css
  3. Validate dark mode, hover state, collapsed state, and responsive behavior across pages

Standards for Future Sidenav Sections

When adding a new section:

  1. Use shared structure:
    • section wrapper with .sidenavSection
    • title with .sidenavSectionTitle
    • list container with .sidenavSectionList
  2. For each row, use shared row classes:
    • .sidenavRow, .sidenavRowName, .sidenavRowMeta, .sidenavRowToggle, .sidenavRowDetails, .sidenavRowIndent
  3. Do not introduce font-size or alignment overrides in page-local <style> unless there is a deliberate and documented variant
  4. If a variant is necessary, add a modifier class in www/css/sidenav-sections.css rather than one-off page styles
  5. Keep icons and spacing aligned by inheriting shared dimensions and line-height

Acceptance Criteria

  • AI, relay, blossom, and future sections share the same baseline font sizing and left-edge alignment
  • Sidenav section title/list/collapse interactions look consistent on all pages using sidenav sections
  • No page-local CSS duplicates base sidenav section system rules
  • JS-generated rows render correctly using shared class contract
  • New section onboarding requires only markup/classes + data logic, not fresh styling rules

Implementation Checklist