kandev/docs/plans/sidebar-task-focus/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-08-26	complete	../../specs/ui/requirements/sidebar-task-focus.md	../../specs/ui/system-design/sidebar-task-focus.md

Implementation Plan: Sidebar Task Focus

Overview

Strengthen the active task treatment in the shared sidebar row so the current task remains easy to identify when a user assigns it a custom color. The work is one sequential frontend slice: update the shared row presentation, then prove the desktop sidebar and mobile task-switcher surfaces.

Scope

In scope

• Add a stronger theme-aware active-row surface with only top and bottom active-task borders.
• Preserve the existing task-color marker when a color is assigned, with no default left marker for uncolored tasks, and preserve all activation semantics.
• Verify the shared treatment in desktop and mobile task switchers.

Out of scope

• Task-color picker or persistence changes.
• Active-task state, task/session data, or API changes.
• New mobile navigation or task-row interaction patterns.

Technical approach

• Update taskItemRowClassName in apps/web/components/task/task-item.tsx so the existing isSelected state adds the active surface and horizontal borders. Keep SelectionBar conditional on an assigned task color and keep the multi-selection ring unchanged.
• Keep TaskRowItem and MobileTaskList data flow unchanged because both already reach the shared TaskItem with active-task state.
• Extend the existing desktop sidebar-open Playwright flow and mobile sidebar task-action flow to assert the active row's visible state and preserve the mobile no-overflow check.

Tests

• apps/web/components/task/task-item.test.tsx remains a focused regression check for the shared row's existing state and action behavior. No React component test is added solely for static class markup.
• The desktop E2E flow maps to AC-UI-SIDEBAR-TASK-FOCUS-001.1 and AC-UI-SIDEBAR-TASK-FOCUS-001.2, with its uncolored active-row assertion covering AC-UI-SIDEBAR-TASK-FOCUS-001.5.
• The mobile E2E flow maps to AC-UI-SIDEBAR-TASK-FOCUS-001.3 and AC-UI-SIDEBAR-TASK-FOCUS-001.4, with the uncolored active-row flow also covering AC-UI-SIDEBAR-TASK-FOCUS-001.5.

E2E tests

• apps/web/e2e/tests/task/sidebar-task-open.spec.ts shall assert the active row's data-active state, background, top-and-bottom-only borders, and no leading marker when opening an uncolored task.
• apps/web/e2e/tests/task/mobile-sidebar-task-actions.spec.ts shall assert the same active treatment inside the mobile task sheet for colored and uncolored tasks, and keep its document-horizontal-overflow assertion.

Work orders

• Task 01: Strengthen active sidebar task focus — complete

Verification results

• Red E2E: the new desktop assertion failed on the previous bg-primary/10 class, confirming the browser contract before implementation.
• cd apps && pnpm --filter @kandev/web test -- components/task/task-item.test.tsx — 49 tests passed.
• cd apps/web && pnpm run typecheck — passed.
• cd apps/web && pnpm e2e:run --project chromium tests/task/sidebar-task-open.spec.ts — 2 tests passed.
• cd apps/web && pnpm e2e:run --project mobile-chrome tests/task/mobile-sidebar-task-actions.spec.ts -- --grep "active task" — 1 test passed.

Background-only comparison variant

• Red desktop E2E failed on the existing active ring, confirming the new background-only contract before the production change.
• Desktop sidebar E2E — 2 tests passed.
• Mobile active-task E2E — 1 test passed.
• Typecheck, lint, focused unit tests (49 passed), and specification checks passed.

Risks

• A class-order change could allow the generic hover background to hide the active surface. Keep the active hover class in the same active branch.
• Removing the active ring must not remove the separate multi-selection ring. Keep the multi-selection utility independent and verify both states.
• The shared row is mounted in more than one responsive surface. Run both desktop and mobile E2E projects against a fresh production build.

Top-and-bottom border comparison variant

• The active row keeps the primary-tinted background and custom marker, with a 1px primary-accent border on the top and bottom edges only.
• Desktop E2E first failed on the expected missing top border, then passed after adding the horizontal border utilities.

Conditional marker refinement

• Red desktop E2E first failed because an uncolored active row still rendered the default left marker.
• SelectionBar now renders only for a supported, explicitly assigned task color. Uncolored active rows use the background and horizontal borders only.
• Desktop sidebar E2E — 2 tests passed, including the uncolored active-row assertion.
• Mobile active-task E2E — 2 tests passed for colored and uncolored rows, including the no-horizontal-overflow assertion.
• Focused unit tests (49 passed), typecheck, lint, and specification checks passed.