Desktop Neighborhoods

The desktop icon field is organized by neighborhood rather than freeform coordinates.

Source of truth

Use src/components/shell/desktopNeighborhoods.ts for:

• group order
• group frame size
• icon padding inside each group
• row and column spacing
• cast-light label and color treatment

Use src/components/shell/Desktop.tsx for:

• which icons exist
• which neighborhood each icon belongs to
• the slot value for placement order inside that neighborhood

Placement convention

Each icon entry should define:

• neighborhood
• slot

slot is zero-based and fills left-to-right, then top-to-bottom using the column count in desktopNeighborhoods.ts.

Examples:

• openFirst uses 2 columns
• workbench uses 3 columns
• afterHours uses 3 columns
• system uses 1 column

So for workbench:

• slot: 0 = first column, first row
• slot: 1 = second column, first row
• slot: 2 = third column, first row
• slot: 3 = first column, second row

Onboarding a new icon

1. Add the icon entry in Desktop.tsx
2. Assign the correct neighborhood
3. Set the next available slot
4. If the neighborhood needs more capacity, update the neighborhood spec in desktopNeighborhoods.ts

Do not add one-off pixel coordinates in Desktop.tsx for a new icon unless the layout model itself is being changed.

Hover behavior

Neighborhood light fields should stay visually stable at rest.

On hover:

• only the hovered icon’s neighborhood gets a local brightness lift
• other neighborhoods should not dim, pulse, or otherwise react

Persistence

Desktop icon positions are persisted in localStorage.

Current key:

• os_icon_pos_v4

The current icon state is mode-aware:

• desktop
• tablet
• mobile

If the neighborhood defaults change in a way that must override older saved layouts, rotate the key and record that change in docs/agent-ops/logs/AGENT_CHANGELOG.md.