Fluxwing Screenshot Importer

What this skill does

# Fluxwing Screenshot Importer

Import UI screenshots and convert them to the **uxscii standard** by orchestrating specialized vision agents.

## Data Location Rules

**READ from (bundled templates - reference only):**
- `{SKILL_ROOT}/../uxscii-component-creator/templates/` - 11 component templates (for reference)
- `{SKILL_ROOT}/docs/` - Screenshot processing documentation

**WRITE to (project workspace):**
- `./fluxwing/components/` - Extracted components (.uxm + .md)
- `./fluxwing/screens/` - Screen composition (.uxm + .md + .rendered.md)

**NEVER write to skill directories - they are read-only!**

## Your Task

Import a screenshot of a UI design and automatically generate uxscii components and screens by **orchestrating specialized agents**:

1. **Vision Coordinator Agent** - Spawns 3 parallel vision agents (layout + components + properties)
2. **Component Generator Agents** - Generate component files in parallel (atomic + composite)
3. **Screen Scaffolder Skill** - Delegates to fluxwing-screen-scaffolder for screen composition

**⚠️ ORCHESTRATION RULES:**

**YOU CAN (as orchestrator):**
- ✅ Spawn vision analysis agents
- ✅ Spawn component generator agents
- ✅ Invoke fluxwing-screen-scaffolder skill
- ✅ Read screenshots
- ✅ Validate vision data

**YOU CANNOT (worker mode - forbidden):**
- ⚠️ Create screen files yourself using Write/Edit tools
- ⚠️ Generate .uxm, .md, or .rendered.md files for screens
- ⚠️ "Help" the scaffolder by pre-creating screen files
- ⚠️ Use TodoWrite to work through screen creation tasks yourself

**For screen composition:** ALWAYS delegate to fluxwing-screen-scaffolder skill. It will spawn composer agents that create all screen files (.uxm, .md, .rendered.md).

## Workflow

### Phase 1: Get Screenshot Path

Ask the user for the screenshot path if not provided:
- "Which screenshot would you like to import?"
- Validate file exists and is a supported format (PNG, JPG, JPEG, WebP, GIF)

```typescript
// Example
const screenshotPath = "/path/to/screenshot.png";
```

### Phase 2: Spawn Vision Coordinator Agent

**CRITICAL**: Spawn the `screenshot-vision-coordinator` agent to orchestrate parallel vision analysis.

This agent will:
- Spawn 3 vision agents in parallel (layout discovery + component detection + visual properties)
- Wait for all agents to complete
- Merge results into unified component data structure
- Return JSON with screen metadata, components array, and composition

```typescript
Task({
  subagent_type: "general-purpose",
  description: "Analyze screenshot with vision analysis",
  prompt: `You are a UI screenshot analyzer extracting component structure for uxscii.

Screenshot path: ${screenshotPath}

Your task:
1. Read the screenshot image file
2. Analyze the UI layout structure (vertical, horizontal, grid, sidebar+main)
3. Detect all UI components (buttons, inputs, navigation, cards, etc.)
4. Extract visual properties (colors, spacing, borders, typography)
5. Identify component hierarchy (atomic vs composite)
6. Merge all findings into a unified data structure
7. Return valid JSON output

CRITICAL detection requirements:
- Do NOT miss navigation elements (check all edges - top, left, right, bottom)
- Do NOT miss small elements (icons, badges, close buttons, status indicators)
- Identify composite components (forms, cards with multiple elements)
- Note spatial relationships between components

Expected output format (valid JSON only, no markdown):
{
  "success": true,
  "screen": {
    "id": "screen-name",
    "type": "dashboard|login|profile|settings",
    "name": "Screen Name",
    "description": "What this screen does",
    "layout": "vertical|horizontal|grid|sidebar-main"
  },
  "components": [
    {
      "id": "component-id",
      "type": "button|input|navigation|etc",
      "name": "Component Name",
      "description": "What it does",
      "visualProperties": {...},
      "isComposite": false
    }
  ],
  "composition": {
    "atomicComponents": ["id1", "id2"],
    "compositeComponents": ["id3"],
    "screenComponents": ["screen-id"]
  }
}

Use your vision capabilities to analyze the screenshot carefully.`
})
```

**Wait for the vision coordinator to complete and return results.**

### Phase 3: Validate Vision Data

Check the returned data structure:

```typescript
const visionData = visionCoordinatorResult;

// Required fields
if (!visionData.success) {
  throw new Error(`Vision analysis failed: ${visionData.error}`);
}

if (!visionData.components || visionData.components.length === 0) {
  throw new Error("No components detected in screenshot");
}

// Navigation check (CRITICAL)
const hasNavigation = visionData.components.some(c =>
  c.type === 'navigation' || c.id.includes('nav') || c.id.includes('header')
);

if (visionData.screen.type === 'dashboard' && !hasNavigation) {
  console.warn("⚠️ Dashboard detected but no navigation found - verify all nav elements were detected");
}
```

### Phase 4: Spawn Component Generator Agents (Parallel)

**CRITICAL**: YOU MUST spawn ALL component generator agents in a SINGLE message with multiple Task tool calls. This is the ONLY way to achieve true parallel execution.

**DO THIS**: Send ONE message containing ALL Task calls for all components
**DON'T DO THIS**: Send separate messages for each component (this runs them sequentially)

For each atomic component, create a Task call in the SAME message:

```
Task({
  subagent_type: "general-purpose",
  description: "Generate email-input component",
  prompt: "You are a uxscii component generator. Generate component files from vision data.

Component data: {id: 'email-input', type: 'input', visualProperties: {...}}

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/screenshot-import-helpers.md
3. Generate .uxm file (valid JSON with default state only)
4. Generate .md file (ASCII template matching visual properties)
5. Save to ./fluxwing/components/
6. Return success with file paths

Follow uxscii standard strictly."
})

Task({
  subagent_type: "general-purpose",
  description: "Generate password-input component",
  prompt: "You are a uxscii component generator. Generate component files from vision data.

Component data: {id: 'password-input', type: 'input', visualProperties: {...}}

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/screenshot-import-helpers.md
3. Generate .uxm file (valid JSON with default state only)
4. Generate .md file (ASCII template matching visual properties)
5. Save to ./fluxwing/components/
6. Return success with file paths

Follow uxscii standard strictly."
})

Task({
  subagent_type: "general-purpose",
  description: "Generate submit-button component",
  prompt: "You are a uxscii component generator. Generate component files from vision data.

Component data: {id: 'submit-button', type: 'button', visualProperties: {...}}

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/screenshot-import-helpers.md
3. Generate .uxm file (valid JSON with default state only)
4. Generate .md file (ASCII template matching visual properties)
5. Save to ./fluxwing/components/
6. Return success with file paths

Follow uxscii standard strictly."
})

... repeat for ALL atomic components in the SAME message ...

... then for composite components in the SAME message:

Task({
  subagent_type: "general-purpose",
  description: "Generate login-form composite",
  prompt: "You are a uxscii component generator. Generate composite component from vision data.

Component data: {id: 'login-form', type: 'form', components: [...], visualProperties: {...}}

IMPORTANT: Include component references in props.components array.

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Generate .uxm with components