Opensquad Dashboard Design

Opensquad Dashboard Design — Visual Office Workflow

Design and improve the opensquad dashboard's 2D virtual office through a structured workflow with visual verification. Every change is screenshot-verified before completion.

Workflow

Follow these 6 phases in order. Do NOT skip phases or implement without diagnosis.

Phase 7 — FULL SPRITE REVIEW is an optional audit phase triggered only when the user explicitly requests a full sprite audit (e.g. "faz o full sprite review", "revisa todos os sprites"). When triggered, it replaces phases 1–6 for that session — skip directly to 7.1 INVENTORY.

Phase 1: UNDERSTAND

• Read the user's request carefully
• Identify what they want: layout change, new furniture, atmosphere fix, specific problem
• If the request is ambiguous, ask ONE clarifying question before proceeding
• Do NOT start implementing — move to Phase 2

Phase 2: DIAGNOSE

Take a screenshot of the current dashboard state before any changes.

Auto-detect dashboard URL:

1. Check dashboard/vite.config.ts for server.port
2. Check dashboard/package.json scripts for --port flags
3. Fallback: http://localhost:5173 (Vite default)

Take screenshot via Playwright CLI (Bash tool, NOT MCP Playwright tools):

npx playwright screenshot --browser chromium "URL" "/tmp/dashboard-before.png" --viewport-size "1400x900"

If npx playwright screenshot is unavailable, use a small inline Playwright script.

If URL is unreachable: tell the user to run cd dashboard && npm run dev.

Analyze the screenshot:

• Identify visible problems (empty zones, depth issues, floating sprites, poor framing)
• Emphasize problems related to the user's specific request
• Present findings to the user WITH the screenshot image

Phase 3: PLAN

Based on diagnosis, propose an action plan:

• List specific changes grouped by file/area
• Group related changes together (independent groups can be parallelized)
• Ask clarifying questions if the diagnosis revealed ambiguity
• WAIT for explicit user approval before proceeding to Phase 4

Phase 4: IMPLEMENT

Group changes by independence:

• Group A: RoomBuilder.ts (furniture placement, layout)
• Group B: assetKeys.ts + copy new asset files to dashboard/public/assets/
• Group C: palette.ts (colors, constants)
• Group D: AgentSprite.ts (animations, badges)

Dispatch subagents in parallel for independent groups. Each subagent receives:

• Description of changes to make
• The critical rules from the "Quick Reference" section below
• Instruction: read .claude/skills/opensquad-dashboard-design/reference.md if you need the asset catalog or code examples

Respect dependencies: assets copied first → keys registered in assetKeys.ts → placement in RoomBuilder.ts → visual adjustments.

Phase 5: VERIFY

Layer 1 — Screenshot:

npx playwright screenshot --browser chromium "URL" "/tmp/dashboard-after.png" --viewport-size "1400x900"

Layer 2 — Automated quality checklist:

• No large empty zones visible
• Wall decorated (at least 1 item per wall section)
• Plants in corners (minimum 4)
• Lounge zone exists with seating + table + rug (if applicable)
• Depth sorting correct (lower objects render on top of higher ones)
• Sprite variety (max 2 identical items visible)
• Camera frames the room well with breathing room
• No hyperactive flickering or distracting animations

Layer 3 — User approval: Present to the user:

1. The after-screenshot
2. Summary of what changed
3. Checklist results (pass/fail per item)

Ask: "O resultado ficou como esperado? Posso finalizar ou quer ajustes?"

• User approves → DONE
• User wants adjustments → Phase 6

Phase 6: LOOP

• Collect the user's specific feedback
• Create a NEW focused plan addressing only the points raised
• Return to Phase 4 (IMPLEMENT)
• Then Phase 5 (VERIFY)
• Repeat until user approves

Phase 7: FULL SPRITE REVIEW

Triggered only on explicit user request. Replaces phases 2–6 for this session.

7.1 INVENTORY

Read dashboard/src/office/RoomBuilder.ts and dashboard/src/office/AgentSprite.ts in full. Build a structured list of every sprite currently placed in the scene:

For each sprite, record:

• Key — the asset key string (e.g. furniture_monstera, desk_black_idle)
• Type — furniture | desk | avatar | decoration
• File + line — where in the code it is placed
• Scale — the .setScale() value (or 1 if not set)
• Depth — the .setDepth() value
• Position — the (x, y) expression in code (e.g. MARGIN / 2, roomW - 40)
• Origin — the .setOrigin(x, y) value (or (0.5, 0.5) if not set)
• Alpha — the .setAlpha() value (or 1 if not set)

Do NOT skip any sprite. Include sprites inside loops (e.g. per-agent desk sprites). For AgentSprite.ts, record only the four Image objects per agent: avatar, deskTable, desk, and coffeeMug. Exclude Graphics and Text objects — these are not sprites and are evaluated separately only if a white-background artifact is suspected.

7.2 SCREENSHOT

Auto-detect the dashboard URL (same logic as Phase 2):

1. Check dashboard/vite.config.ts for server.port
2. Check dashboard/package.json scripts for --port flags
3. Fallback: http://localhost:5173

Take screenshot via Playwright CLI:

npx playwright screenshot --browser chromium "URL" "/tmp/sprite-review-before.png" --viewport-size "1400x900"

If npx playwright screenshot is unavailable, use a small inline Playwright script.

If URL is unreachable, tell the user to run cd dashboard && npm run dev and wait for confirmation before continuing.

Present the screenshot to the user and say: "Capturei o estado atual. Iniciando avaliação de cada sprite..."

7.3 EVALUATE

For every sprite in the inventory, evaluate 4 criteria against the screenshot. Assign PASS, FAIL, or UNCERTAIN to each.

Criterion 1 — Size Compare visual scale against neighboring elements in the screenshot:

• Avatar must not appear larger than the desk it sits at
• Plants/flowers must not visually dominate the scene (overshadow desks or avatars)
• Wall decorations must fit within the visible wall strip (not spill onto the floor)
• Accessories (mugs, backpacks, cushions) must be proportionally small relative to desks

Criterion 2 — Transparent Background Look for a visible white or solid-colored box surrounding the sprite in the screenshot:

• PASS: sprite renders cleanly with transparent surroundings
• FAIL: visible bounding box or white halo around the sprite
• Fix approach: inspect the Phaser code around that sprite for setTint, setAlpha, Graphics rectangles drawn immediately before the sprite, or incorrect filterMode. Fix is always in the code — PNG files are already transparent.

Criterion 3 — Semantic Position Apply these lightweight rules per sprite category:

Criterion 4 — Unwanted Overlap Check if a sprite visually covers another in a way that breaks scene logic:

• Plant rendered over an avatar's face → FAIL
• Rug floating visually above a couch → FAIL
• Two identical sprites stacked at the same pixel position → FAIL
• Desk partially clipped by a wall decoration → FAIL
• No scene-breaking overlaps visible → PASS

UNCERTAIN rule: If you cannot determine PASS or FAIL from the screenshot alone (e.g. the sprite is partially hidden, or the position rule doesn't clearly apply), mark it UNCERTAIN and note the specific question. You will ask the user about all UNCERTAIN sprites together in 7.4, before proceeding to 7.5.

Invisible sprite rule: If a sprite from the inventory is not visible in the screenshot at all (e.g. a per-agent desk sprite outside the visible viewport), mark all four criteria UNCERTAIN with note: "sprite not visible in screenshot."

7.4 DOCUMENT

Write the evaluation results to /tmp/sprite-review.md in this exact format:

# Sprite Review — YYYY-MM-DD HH:MM

## Summary
- Total sprites: N
- PASS: N | FAIL: N | UNCERTAIN: N

## Results

### furniture_monstera (RoomBuilder.ts:112)
- Tamanho: PASS
- Fundo: PASS
- Posição: FAIL — planta posicionada sobre mesa de trabalho (x=320, y=180). Mover para canto.
- Sobreposição: FAIL — sobrepõe avatar do agente "Writer". Ajustar x/y.
- **Fix needed:** reposition to corner (x=MARGIN/2, y=deskAreaBottom - 20)

### avatar_Jesse_blink (AgentSprite.ts:87)
- Tamanho: UNCERTAIN — parece grande, mas pode ser intencional
- Fundo: PASS
- Posição: PASS
- Sobreposição: PASS

If there are any UNCERTAIN sprites, present them to the user now with a concise question for each one. Wait for the user's answer, update the report, then proceed to 7.5.

7.5 FIX

Group all FAIL sprites by fix type and dispatch subagents in parallel:

Groups A and B run in parallel. Group C runs after A and B complete (white-background causes may span both files).

Each subagent receives:

1. The list of sprite keys it must fix, with specific FAIL reasons from /tmp/sprite-review.md
2. The Quick Reference section from this skill (depth sorting, origin conventions, layout constants)
3. Instruction: read .claude/skills/opensquad-dashboard-design/reference.md for the asset catalog and code examples
4. The rule: never hardcode pixel values — always use relative expressions (MARGIN / 2, roomW / N, deskAreaBottom - offset)

If a group has no failing sprites, skip it.

7.6 RE-REVIEW

After subagents complete, take a new screenshot:

npx playwright screenshot --browser chromium "URL" "/tmp/sprite-review-iter-N.png" --viewport-size "1400x900"

(Increment N each iteration: iter-1.png, iter-2.png, etc.)

Re-evaluate only the sprites that previously had FAIL or UNCERTAIN status. Do not re-evaluate sprites that already passed.

Update /tmp/sprite-review.md with the new results.

Stuck detection: If the same sprite fails the same criterion for the 2nd consecutive iteration, do NOT dispatch another subagent blindly. Instead, pause and report to the user:

"O sprite <key> continua falhando no critério <criterion> após 2 tentativas. [Descrição concisa do problema]. O que devo fazer?"

Wait for the user's answer, then continue.

Loop: If any sprites still FAIL after re-evaluation, return to 7.5 FIX with only the remaining failures. Continue until all sprites are PASS.

7.7 APPROVE

When all sprites reach PASS status:

1. Present the final screenshot (/tmp/sprite-review-iter-N.png or /tmp/sprite-review-before.png if no iterations were needed)
2. Show a summary of what was fixed:
   • List each sprite that was corrected, with before/after description
   • List sprites that passed without changes
3. Show the final checklist with all items as PASS

Ask: "Todos os sprites passaram na revisão. O resultado ficou como esperado? Posso finalizar ou quer ajustes?"

• User approves → DONE
• User wants adjustments → collect feedback, return to 7.5 FIX with a new targeted plan, then proceed through 7.6 RE-REVIEW before returning to 7.7

Quick Reference

Key Files

Layout Constants (palette.ts)

TILE = 32 // Base grid unit (px) CELL_W = 96 // 3 tiles — desk cell width CELL_H = 96 // 3 tiles — desk cell height MARGIN = 96 // 3 tiles — room edge padding WALL_H = 96 // 3 tiles — wall strip height

Depth Sorting

Y-based painter's algorithm — objects lower on screen render on top:

Wall decorations: setDepth(0) — behind everything Rugs: setDepth(-0.5) — below furniture, above floor Floor furniture: setDepth(y) — Y position Agent desk: setDepth(y) — Y position Avatar: setDepth(y + 1) — on top of desk Name badge: setDepth(y + 99/101) — always on top

Rule: anything closer to the bottom of the screen gets a higher depth value.

Sprite Placement

// WALL DECORATIONS — anchor to bottom of wall, depth 0 scene.add.image(x, WALL_H, key).setOrigin(0.5, 1).setDepth(0);

// FLOOR ITEMS — anchor to bottom of sprite, depth = Y scene.add.image(x, y, key).setOrigin(0.5, 1).setDepth(y);

// UNDER FURNITURE (rugs) — depth = -0.5 scene.add.image(x, y, key).setOrigin(0.5, 0.5).setDepth(-0.5);

Origin conventions:

• Wall items: setOrigin(0.5, 1) — bottom-center anchored to wall base
• Floor items: setOrigin(0.5, 1) — bottom-center for correct Y-sorting
• Rugs/carpets: setOrigin(0.5, 0.5) — center-anchored

Relative positioning — never hardcode pixels:

• roomW / 2 for centered items
• MARGIN / 2 for corner items
• roomW / N for evenly spaced wall decorations
• deskAreaBottom + offset for lounge zone items

Visual Density

Important Rules

• NEVER create pixel art from scratch — always use existing assets from dashboard/public/assets/ or the asset pack in temp/pixel-assets/town/
• Every new sprite must be registered in assetKeys.ts (FURNITURE_KEYS + FURNITURE_PATHS)
• Consult reference.md (.claude/skills/opensquad-dashboard-design/reference.md) for the full asset catalog, code examples, and detailed technical guidance during implementation