visual-device-inventory

name	visual-device-inventory
description	Inventory every visible device, motif, control, decoration, and composite subpart in raster mockups before CSS implementation. Use for screenshot-to-code, mockup-to-code, design-comp decomposition, pre-CSS visual audits, ROI evidence sheets, and hash-bound detail-inventory/v1 specialist reports, especially when source-specific details could otherwise be omitted or flattened.

Visual Device Inventory

Create an exhaustive, hash-bound detail-inventory/v1 report before writing CSS. Treat every visible source device as an implementation obligation; do not infer completion from a prose summary.

Use the pack runtime wrapper so commands run with the interpreter selected at installation. Set SKILL_ROOT when the pack uses a non-default destination.

Workflow

1. Identify the source medium and record the source path before interpreting the design.

2. Partition the entire source into ordered, non-empty sections. Include seams or transition bands as sections when they carry visible devices.

3. Sweep each section at high zoom in a fixed order: background, edges/corners, focal object, typography, controls, overlays, decorations, and seams.

4. Add one inventory row per independently reproducible device. Mark a distinctive source motif sourceSpecific: true and assign it critical or high priority.

5. Use kind: composite only when the device must be reproduced as a coordinated unit. Inventory at least two atomic compositeParts, each with its own globally unique id, ROI, specificity, and priority.

6. Draw every ROI in source-image pixel coordinates as {x,y,width,height}. Keep device ROIs inside their section ROI and composite-part ROIs inside their parent device ROI.

7. Generate crops and the contact sheet before implementation:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/visual-device-inventory/scripts/generate_roi_contact_sheet.py" \
     work/detail-inventory.json \
     --root . --output-dir work/device-inventory-evidence
   

8. Validate the report and every referenced image byte, bound, dimension, and SHA-256:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/visual-device-inventory/scripts/validate_inventory.py" \
     work/detail-inventory.json --root .
   

9. Emit the exact receipt object for mockup-to-code:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/visual-device-inventory/scripts/validate_inventory.py" \
     work/detail-inventory.json \
     --root . --receipt
   

   Store that object at specialistReports.deviceInventory. It has the stable shape {contract:"detail-inventory/v1", path, sha256}. The hash covers the report file bytes; changing the report invalidates the receipt.

10. Stop before CSS when validation fails. Fix missing rows, bounds, specificity, composite decomposition, or unreadable evidence first.

Contract

• Read schemas/detail-inventory-v1.schema.json when creating or transforming a report.
• Start from templates/detail-inventory.blocked.json only when inventory cannot honestly proceed. Replace every placeholder and blocker when work resumes.
• Run blocked validation explicitly with --allow-blocked; blocked reports never emit a receipt and normal validation exits nonzero.
• Keep ids lowercase and stable. Ids are globally unique across sections, devices, and composite parts.
• Cover every declared section with at least one device. Never use one giant row to stand in for several independently reproducible details.
• Use relative, traversal-free paths rooted at --root. Evidence must be real readable PNG, JPEG, or WebP files with matching hashes and pixel dimensions.
• Preserve report order. The generator sorts by section order and inventory order and writes deterministic PNG output for identical inputs and Pillow version.

Validation

Run the skill self-check after changes:

SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
"$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
  "$SKILL_ROOT/visual-device-inventory/scripts/quick_validate.py"

Do not hand-edit generated hashes. Regenerate evidence, validate, then copy the emitted receipt into the consuming manifest.