Responsive Sidebar Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make both the app and admin sidebars responsive with a compact phase (shrink) and a collapsed phase (hamburger overlay).

Architecture: CSS-only responsive behavior using CSS variables, media queries, and transitions. Minimal HTML additions (hamburger button + backdrop div). Class toggle on <body> for collapsed state, same pattern as existing user menu.

Tech Stack: CSS custom properties, media queries, Hiccup templates, hx-on:click for toggle.

Design doc: docs/plans/2026-03-14-responsive-sidebar-design.md

Convert hardcoded 300px to CSS variable and add smooth transitions.

Files:

Modify: resources/app/public/css/style.css:29-43 (.sidebar rules)
Modify: resources/app/public/css/style.css:249-258 (.content rules)

Step 1: Replace hardcoded sidebar width with CSS variable

In style.css, add --sidebar-width: 300px to the existing :root (there isn't one yet, so add it at the top of the file, after the reset). Then update .sidebar and .content to use it:

/* After the reset block (line 2) */
:root {
  --sidebar-width: 300px;
}

In .sidebar (line 29), change:

width: 300px;

to:

width: var(--sidebar-width);
transition: width 0.2s ease;

In .content (line 249), change:

margin-left: 300px; /* Space for fixed sidebar */

to:

margin-left: var(--sidebar-width);
transition: margin-left 0.2s ease;

Step 2: Verify the app still renders identically

Start the system if not running, open the app in the browser, confirm the sidebar is 300px and everything looks normal.

Step 3: Commit

git add resources/app/public/css/style.css
git commit -m "refactor: use CSS variable for app sidebar width"

Shrink sidebar from 300px to 220px between 1024px–1279px.

Files:

Modify: resources/app/public/css/style.css (add media query at end of sidebar section)

Step 1: Add the compact breakpoint media query

Add after the sidebar/content CSS section (after line ~258):

/* Responsive sidebar — compact */
@media (max-width: 1279px) {
  :root {
    --sidebar-width: 220px;
  }
}

Step 2: Verify

Resize the browser window to ~1100px wide. Sidebar should smoothly shrink to 220px. All nav items ("Document Management" is longest) should still be readable without clipping. Above 1280px it should be 300px.

Step 3: Commit

git add resources/app/public/css/style.css
git commit -m "feat: shrink app sidebar to 220px on smaller viewports"

Hide sidebar below 1024px, add hamburger button and backdrop styles.

Files:

Modify: resources/app/public/css/style.css (add collapsed media query and toggle styles)

Step 1: Add the collapsed breakpoint and toggle styles

Add after the compact media query:

/* Responsive sidebar — collapsed */
@media (max-width: 1023px) {
  :root {
    --sidebar-width: 0px;
  }

  .sidebar {
    transform: translateX(-100%);
    width: 300px;
  }

  .content {
    margin-left: 0;
  }

  .sidebar-toggle {
    display: flex;
  }

  /* Open state */
  body.sidebar-open .sidebar {
    transform: translateX(0);
  }

  body.sidebar-open .sidebar-backdrop {
    display: block;
  }
}

/* Sidebar toggle button — hidden by default, shown below 1024px */
.sidebar-toggle {
  display: none;
  position: fixed;
  top: 16px;
  left: 16px;
  z-index: 200;
  background: #161b22;
  border: 1px solid #30363d;
  color: #c9d1d9;
  padding: 8px;
  border-radius: 6px;
  cursor: pointer;
  align-items: center;
  justify-content: center;
  font-size: 20px;
  line-height: 1;
}

.sidebar-toggle:hover {
  background: #21262d;
}

/* Sidebar backdrop — hidden by default */
.sidebar-backdrop {
  display: none;
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.5);
  z-index: 99;
}

Note: sidebar gets width: 300px (full width) in collapsed mode so it overlays at its natural size. The --sidebar-width: 0px drives the content margin. The sidebar's own transition handles the slide animation. The sidebar z-index: 100 is already higher than the backdrop's z-index: 99.

Step 2: Verify CSS only (no HTML yet)

Resize below 1024px. Sidebar should disappear. Content should take full width. The hamburger button won't appear yet (HTML not added), but the layout shouldn't break.

Step 3: Commit

git add resources/app/public/css/style.css
git commit -m "feat: hide app sidebar below 1024px with overlay styles"

Task 4: App Layout — Add Hamburger Button and Backdrop

Add the toggle button and backdrop div to the Hiccup template.

Files:

Modify: src/com/getorcha/app/ui/layout.clj:220-229 (base function body)

Step 1: Add hamburger button and backdrop to the body

In layout.clj, in the base function, modify the body to add the hamburger button and backdrop. The hamburger should only render when the sidebar is shown (authenticated). Add them inside the [:body ...] form, before .app-container:

Change lines 221-228 from:

[:div.app-container
 (when show-sidebar? (nav router active-nav identity tenants))
 [:main.content
  (when (and is-super-admin?
             current-tenant-name
             (not= "Orcha" current-tenant-name))
    (super-admin-banner current-tenant-name))
  content]]

to:

(when show-sidebar?
  [:button.sidebar-toggle
   {:hx-on:click "document.body.classList.toggle('sidebar-open')"
    :aria-label "Toggle navigation"}
   [:iconify-icon {:icon :lucide:menu}]])
(when show-sidebar?
  [:div.sidebar-backdrop
   {:hx-on:click "document.body.classList.remove('sidebar-open')"}])
[:div.app-container
 (when show-sidebar? (nav router active-nav identity tenants))
 [:main.content
  (when (and is-super-admin?
             current-tenant-name
             (not= "Orcha" current-tenant-name))
    (super-admin-banner current-tenant-name))
  content]]

Note: backdrop uses .remove not .toggle so clicking backdrop always closes.

Step 2: Verify the full collapsed flow

Resize below 1024px. The hamburger button should appear top-left. Click it — sidebar slides in from left, backdrop appears. Click backdrop — sidebar slides out, backdrop disappears.

Step 3: Also verify that navigating closes the sidebar

Click a nav link while sidebar is open. The page reload naturally removes the sidebar-open class since it's a full page navigation. This works for free.

Step 4: Commit

git add src/com/getorcha/app/ui/layout.clj
git commit -m "feat: add hamburger toggle and backdrop for collapsed app sidebar"

Admin already uses --sidebar-width: 240px. Add transition and compact breakpoint.

Files:

Modify: resources/admin/public/css/style.css:38-49 (.admin-sidebar)
Modify: resources/admin/public/css/style.css:112-119 (.admin-content)

Step 1: Add transitions to admin sidebar and content

In .admin-sidebar (line 38), add:

transition: width 0.2s ease, transform 0.2s ease;

In .admin-content (line 112), add after overflow-x: hidden;:

transition: margin-left 0.2s ease;

Step 2: Add compact breakpoint

Add before the existing @media (max-width: 768px) block (line 1236):

/* Responsive admin sidebar — compact */
@media (max-width: 1279px) {
  :root {
    --sidebar-width: 200px;
  }
}

Step 3: Verify

Resize admin to ~1100px. Sidebar should narrow to 200px. Nav items still fit.

Step 4: Commit

git add resources/admin/public/css/style.css
git commit -m "feat: add compact phase for admin sidebar at 200px"

Replace the existing 768px media query with 1024px collapsed behavior.

Files:

Modify: resources/admin/public/css/style.css:1236-1265 (existing @media (max-width: 768px))

Step 1: Update the existing 768px breakpoint to 1024px and add toggle styles

Replace the existing @media (max-width: 768px) block at line 1236 with:

/* Responsive admin sidebar — collapsed */
@media (max-width: 1023px) {
  :root {
    --sidebar-width: 0px;
  }

  .admin-sidebar {
    transform: translateX(-100%);
    width: 240px;
  }

  .admin-content {
    margin-left: 0;
    padding: 20px;
  }

  .sidebar-toggle {
    display: flex;
  }

  /* Open state */
  body.sidebar-open .admin-sidebar {
    transform: translateX(0);
  }

  body.sidebar-open .sidebar-backdrop {
    display: block;
  }

  .page-header {
    flex-direction: column;
    gap: 16px;
    align-items: flex-start;
  }

  .dashboard-toolbar {
    flex-direction: column;
    align-items: flex-start;
  }

  .toolbar-filters {
    flex-direction: column;
    align-items: flex-start;
    width: 100%;
  }

  .tenant-filter {
    width: 100%;
  }
}

Also add the toggle button and backdrop base styles (outside any media query, near the admin sidebar section):

/* Admin sidebar toggle button — hidden by default */
.sidebar-toggle {
  display: none;
  position: fixed;
  top: 16px;
  left: 16px;
  z-index: 200;
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  color: var(--color-text);
  padding: 8px;
  border-radius: 6px;
  cursor: pointer;
  align-items: center;
  justify-content: center;
  font-size: 20px;
  line-height: 1;
}

.sidebar-toggle:hover {
  background: var(--color-bg);
}

/* Admin sidebar backdrop — hidden by default */
.sidebar-backdrop {
  display: none;
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.3);
  z-index: 99;
}

Step 2: Update the other 768px media queries

The file has two more @media (max-width: 768px) blocks (at lines ~1542 and ~1671). Leave those as-is — they handle form and grid layout, not sidebar.

Step 3: Commit

git add resources/admin/public/css/style.css
git commit -m "feat: collapse admin sidebar below 1024px with overlay styles"

Task 7: Admin Layout — Add Hamburger Button and Backdrop

Add the toggle button and backdrop div to the admin Hiccup template.

Files:

Modify: src/com/getorcha/admin/ui/layout.clj:38-41 (base function body)

Step 1: Add hamburger and backdrop to admin body

In layout.clj, modify the [:body.admin-body ...] form. Change lines 38-41 from:

[:body.admin-body
 (ui/sidebar path)
 [:main.admin-content
  content]

to:

[:body.admin-body
 [:button.sidebar-toggle
  {:hx-on:click "document.body.classList.toggle('sidebar-open')"
   :aria-label "Toggle navigation"}
  [:iconify-icon {:icon :lucide:menu}]]
 [:div.sidebar-backdrop
  {:hx-on:click "document.body.classList.remove('sidebar-open')"}]
 (ui/sidebar path)
 [:main.admin-content
  content]

Step 2: Verify the full collapsed flow in admin

Resize below 1024px. Hamburger appears. Click — admin sidebar slides in with light backdrop. Click backdrop — closes. Nav links work (full page reload clears state).

Step 3: Commit

git add src/com/getorcha/admin/ui/layout.clj
git commit -m "feat: add hamburger toggle and backdrop for collapsed admin sidebar"

Task 8: Visual QA and Edge Cases

Final verification across both apps.

Files: None (testing only)

Step 1: Test app sidebar at all breakpoints

≥ 1280px: Sidebar 300px, no hamburger, normal layout
1024–1279px: Sidebar 220px, smooth transition, all nav text readable
< 1024px: Sidebar hidden, hamburger visible, overlay works, backdrop dismisses

Step 2: Test admin sidebar at all breakpoints

Same checks as above but with 240px → 200px → collapsed.

Step 3: Test unauthenticated pages (app only)

Login page should have no sidebar, no hamburger button. The existing .app-container:not(:has(.sidebar)) .content rule should still work.

Step 4: Test super-admin banner (app only)

With super-admin mode active, verify the banner and border still look correct at compact and collapsed widths.

Step 5: Test footer (app only)

Footer should remain properly positioned at all breakpoints. It uses position: fixed; left: 0; right: 0 so it should be fine.

Step 6: Commit (if any fixes were needed)

git add <fixed-files>
git commit -m "fix: responsive sidebar edge cases"

Responsive Sidebar Implementation Plan

Task 1: App Sidebar — CSS Variables and Transitions

Task 2: App Sidebar — Compact Phase Media Query

Task 3: App Sidebar — Collapsed Phase CSS

Task 4: App Layout — Add Hamburger Button and Backdrop

Task 5: Admin Sidebar — CSS Variables and Compact Phase

Task 6: Admin Sidebar — Collapsed Phase CSS

Task 7: Admin Layout — Add Hamburger Button and Backdrop

Task 8: Visual QA and Edge Cases