# Phase 9: Weight Classification and Visualization - Context

**Gathered:** 2026-03-16
**Status:** Ready for planning

<domain>
## Phase Boundary

Users can classify each item within a setup as base weight, worn, or consumable (same item can differ across setups). Setup detail view shows weight subtotals by classification and a donut chart for weight distribution, toggleable between category and classification breakdowns. Side-by-side comparison, ranking, and impact preview are separate phases.

</domain>

<decisions>
## Implementation Decisions

### Classification UI
- Click-to-cycle badge on each item card within a setup — clicks cycle through base weight → worn → consumable → base weight
- Follows the StatusBadge pattern from Phase 8 (pill badge, click interaction)
- Default classification is "base weight" when an item is added to a setup
- Badge always visible on every item card in the setup (not hidden for default)
- Muted gray color scheme for all classification badges (bg-gray-100 text-gray-600), consistent with Phase 8 status badges
- Classification stored on `setup_items` join table (already decided in prior phases)

### Weight subtotals display
- Summary section below the setup sticky bar, always visible when setup has items
- Card with columns layout: Base | Worn | Consumable | Total — each as a labeled column with weight value
- Sticky bar keeps its existing simple stats (item count, total weight, total cost)
- Summary card is a separate visual element, not inline text

### Chart placement & style
- Donut chart sits inside the summary card alongside the weight subtotals — chart + numbers as one visual unit
- Pill toggle above the chart for switching between "Category" and "Classification" views (same style as weight unit selector)
- Total weight displayed in the center of the donut hole (e.g., "2.87kg")
- Hover tooltips show segment name, weight (in selected unit), and percentage
- Chart library: **Recharts** (PieChart + Pie with innerRadius for donut shape)

### Claude's Discretion
- Summary card exact layout (chart left/right, column arrangement)
- Chart color palette for segments (should work with both category and classification views)
- Minimum item threshold for showing chart vs a placeholder message
- Donut chart sizing and proportions
- Tooltip styling
- Keyboard accessibility for classification cycling
- Animation on chart transitions between category/classification views

</decisions>

<code_context>
## Existing Code Insights

### Reusable Assets
- `StatusBadge` (`src/client/components/StatusBadge.tsx`): Click-to-cycle pattern with popup — direct pattern reference for classification badge
- `formatWeight()` in `src/client/lib/formatters.ts`: Handles unit conversion, reuse for subtotals and chart tooltips
- `useWeightUnit()` hook: Gets current weight unit setting for display
- `getSetupWithItems()` in `src/server/services/setup.service.ts`: Fetches setup items with category joins — needs to include classification field
- `syncSetupItems()`: Delete-all + re-insert pattern — needs to preserve classification values

### Established Patterns
- Settings stored as key/value strings in SQLite `settings` table
- React Query for server data, Zustand for UI-only state (panels/dialogs)
- Pill badges: blue-50/blue-400 for weight, green-50/green-500 for price, gray-50/gray-600 for metadata
- Weight unit pill toggle in TotalsBar — same pattern for chart category/classification toggle
- Click-outside + Escape dismiss pattern for popups (CategoryPicker, StatusBadge)

### Integration Points
- `setup_items` table (`src/db/schema.ts`): Add `classification` column with default "base"
- `getSetupWithItems()`: Include classification in query results
- `syncSetupItems()`: Must handle classification when syncing (preserve during re-insert)
- Setup detail page (`src/client/routes/setups/$setupId.tsx`): Add summary card section, classification badges on ItemCards, donut chart
- `ItemCard` component: Needs optional `classification` prop and badge (only rendered in setup context)
- Setup routes (`src/server/routes/setups.ts`): API needs to accept/return classification data
- Test helper (`tests/helpers/db.ts`): Update CREATE TABLE for setup_items to include classification column

</code_context>

<specifics>
## Specific Ideas

No specific requirements — user gave clear structural decisions. Standard gear app patterns apply (LighterPack-style classification).

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 09-weight-classification-and-visualization*
*Context gathered: 2026-03-16*