ims-generator

name	ims-generator
description	Generates Interaction Metadata Schema (IMS v1) annotations for interactive web applications, ensuring every UI interaction has proper metadata for testing and agent execution
allowed-tools	Read, Write, Glob, Grep, Edit

Interaction Metadata Schema (IMS v1) Generator

Generate standardized interaction metadata for web applications following the IMS v1 specification. This skill treats UIs as Directed Interaction Graphs where every action, effect, state, and readiness condition is explicitly annotated.

Purpose

This skill enables you to generate standardized interaction metadata for web applications following the IMS v1 specification. The schema treats UIs as Directed Interaction Graphs where every action, effect, state, and readiness condition is explicitly annotated.

Core Concept

An interactive UI follows this flow:

Action ──(trigger)──▶ Effect ──▶ State ──▶ Ready ──▶ Screenshot

Every interactive element must have:

• An action with a unique ID
• A trigger (from closed set)
• At least one effect (state transition)
• A state with status
• A readiness condition for screenshots

Closed Vocabulary

Triggers (ONLY these are allowed)

1. click - User clicks/taps
2. hover - Mouse hover
3. scroll - Scroll event
4. focus - Element receives focus
5. wait - Time-based trigger
6. auto - Automatic trigger
7. keyboard - Keyboard input

Status Values (ONLY these are allowed)

1. hidden - Not visible
2. loading - Data/content loading
3. animating - In transition
4. ready - Stable and complete
5. error - Error state
6. disabled - Interaction disabled

Generation Rules

Critical Rules (MUST FOLLOW)

❌ Never invent triggers - only use the 7 allowed triggers ❌ Never add ready=true without snapshot - ready state requires screenshot ID ❌ Never add effects without observable state - every effect must have a corresponding state ❌ Never use timing if state exists - prefer state-based over wait-based ✅ Prefer existing scopes - reuse scope names for related interactions ✅ Use semantic intent-based naming - IDs should describe what, not how

Required Fields

Field	Requirement	Format
action.id	Required	kebab-case, starts with letter
action.trigger	Required	From closed set only
action.effects	Required	Minimum 1 item, format scope.state
state.scope	Required	Group related states
state.name	Required	State identifier
state.status	Required	From closed set only

Conditional Requirements

Condition	Requirement
If ready === true	Then snapshot is REQUIRED
If user can interact with element	Then action metadata is REQUIRED
If effect is declared	Corresponding state MUST exist

Output Formats

Format 1: DOM Annotations

<button
  data-ui-action="open-settings"
  data-ui-trigger="click"
  data-ui-effect="settings.visible"
>
  Settings
</button>

<div
  data-ui-scope="settings"
  data-ui-state="ready"
  data-ui-ready="true"
  data-ui-snapshot="settings-modal-open"
  class="modal"
>
  <!-- Modal content -->
</div>

Format 2: JSON Manifest

{
  "version": "1.0",
  "interactions": [
    {
      "id": "open-settings",
      "scope": "settings",
      "trigger": "click",
      "effects": ["settings.visible"]
    }
  ],
  "states": [
    {
      "scope": "settings",
      "name": "visible",
      "status": "ready",
      "ready": true,
      "snapshot": "settings-modal-open"
    }
  ]
}

Annotation Algorithm

When annotating a UI component, follow these steps:

1. Identify Interactive Elements

• Buttons, links, form inputs, toggles, etc.
• Each needs action metadata

2. For Each Interactive Element:

a. Assign unique action.id (kebab-case) b. Determine trigger type (from closed set) c. Identify what changes (effects) d. Define effect as scope.state format

3. For Each Effect:

a. Create corresponding state definition b. Assign scope (group related states) c. Determine status (from closed set) d. If visually stable, mark ready=true + snapshot

4. Validate:

• ✅ All actions have effects
• ✅ All effects have states
• ✅ All ready states have snapshots
• ✅ All triggers are from closed set
• ✅ All status values are from closed set

Common Patterns

📖 For detailed examples and complete patterns, see EXAMPLES.md

Modal Dialog Pattern

<!-- Trigger -->
<button
  data-ui-action="open-modal"
  data-ui-trigger="click"
  data-ui-effect="modal.visible"
>
  Open Dialog
</button>

<!-- Modal -->
<div
  data-ui-scope="modal"
  data-ui-state="visible"
  data-ui-status="ready"
  data-ui-ready="true"
  data-ui-snapshot="modal-open"
  class="modal"
>
  <button
    data-ui-action="close-modal"
    data-ui-trigger="click"
    data-ui-effect="modal.hidden"
  >
    Close
  </button>
</div>

Form Submission Pattern

<form>
  <input
    type="text"
    data-ui-action="fill-username"
    data-ui-trigger="keyboard"
    data-ui-effect="form.username-filled"
  />

  <button
    data-ui-action="submit-form"
    data-ui-trigger="click"
    data-ui-effect="form.submitting,form.submitted"
  >
    Submit
  </button>
</form>

<!-- Loading state -->
<div
  data-ui-scope="form"
  data-ui-state="submitting"
  data-ui-status="loading"
>
  Submitting...
</div>

<!-- Success state -->
<div
  data-ui-scope="form"
  data-ui-state="submitted"
  data-ui-status="ready"
  data-ui-ready="true"
  data-ui-snapshot="form-success"
>
  Success!
</div>

Accordion/Dropdown Pattern

<div class="accordion">
  <button
    data-ui-action="toggle-section-1"
    data-ui-trigger="click"
    data-ui-effect="section-1.expanded"
  >
    Section 1
  </button>

  <div
    data-ui-scope="section-1"
    data-ui-state="expanded"
    data-ui-status="ready"
    data-ui-ready="true"
    data-ui-snapshot="section-1-open"
    class="accordion-content"
  >
    Content here
  </div>
</div>

Navigation Pattern

<nav>
  <a
    href="/dashboard"
    data-ui-action="navigate-dashboard"
    data-ui-trigger="click"
    data-ui-effect="page.dashboard-loaded"
  >
    Dashboard
  </a>
</nav>

<div
  data-ui-scope="page"
  data-ui-state="dashboard-loaded"
  data-ui-status="ready"
  data-ui-ready="true"
  data-ui-snapshot="dashboard-page"
>
  <!-- Dashboard content -->
</div>

Hover Effects Pattern

<div
  data-ui-action="show-tooltip"
  data-ui-trigger="hover"
  data-ui-effect="tooltip.visible"
>
  Hover me
</div>

<div
  data-ui-scope="tooltip"
  data-ui-state="visible"
  data-ui-status="ready"
  data-ui-ready="true"
  data-ui-snapshot="tooltip-shown"
  class="tooltip"
>
  Tooltip content
</div>

Usage Examples

📖 For comprehensive examples with validation schemas and multi-step forms, see EXAMPLES.md

Quick Start

Tell me to annotate your UI with IMS v1 metadata:

• "Add IMS annotations to my React components"
• "Generate interaction metadata for my web app"
• "Annotate all buttons and modals with IMS v1 schema"
• "Create a JSON manifest of all UI interactions"

Advanced Usage

Annotate Entire Component Directory:

Scan ./src/components and add IMS v1 annotations to all interactive elements

Generate JSON Manifest:

Analyze my UI and create an IMS v1 JSON manifest of all interactions

Validate Existing Annotations:

Check my IMS annotations for compliance with v1 specification

Convert Between Formats:

Convert my DOM annotations to JSON manifest format

Instructions

When you ask me to generate IMS annotations, I will:

1. Analyze UI Components

   • Scan specified directories for interactive elements
   • Identify buttons, links, forms, modals, and other interactive components
   • Map out the interaction flow

2. Generate Metadata

   • Create unique action IDs using semantic naming
   • Assign appropriate triggers from the closed set
   • Define effects in scope.state format
   • Create corresponding state definitions
   • Add readiness conditions and snapshot IDs

3. Apply Annotations

   • Add data-ui-* attributes to DOM elements (if HTML/JSX/TSX)
   • Generate JSON manifest (if requested)
   • Validate against IMS v1 specification

4. Validation Report

   • Check all required fields are present
   • Verify triggers and status values are from closed sets
   • Ensure effects have corresponding states
   • Confirm ready states have snapshot IDs
   • Report any violations

Validation Checklist

Check	Description
✅ All interactive elements have action.id	Every clickable/interactive element annotated
✅ All triggers are from closed set	Only the 7 allowed triggers used
✅ All effects follow scope.state format	Proper dot notation
✅ All effects have corresponding states	No orphaned effects
✅ All status values are from closed set	Only the 6 allowed statuses used
✅ All ready=true states have snapshots	Screenshot IDs present
✅ Semantic naming used	IDs describe intent, not implementation
✅ Scopes are reused appropriately	Related states grouped together

Benefits

For Testing

• Automated test generation from metadata
• Complete UI coverage validation
• State-based screenshot capture
• Interaction flow documentation

For Agents

• Explicit action discovery
• State transition understanding
• Screenshot timing optimization
• Error state identification

For Developers

• Self-documenting UI interactions
• Standardized annotation format
• Easy debugging of interaction flows
• Clear separation of actions, effects, and states

Specification Compliance

This skill generates annotations strictly compliant with IMS v1 specification:

• ✅ Closed vocabulary enforcement (triggers, status)
• ✅ Required field validation
• ✅ Conditional requirement checks
• ✅ Effect-state correspondence
• ✅ Ready-snapshot pairing
• ✅ Semantic naming conventions

What I'll Generate

Annotated Components

• HTML/JSX/TSX files with data-ui-* attributes
• Vue/Svelte components with metadata
• Clean, spec-compliant annotations

JSON Manifests

• Complete interaction catalog
• State definitions
• Screenshot markers
• Validation-ready format

Validation Reports

• Specification compliance check
• Missing annotations report
• Invalid trigger/status detection
• Orphaned effects identification

Requirements

No special dependencies required. This skill works with:

• HTML files
• React/JSX/TSX components
• Vue single-file components
• Svelte components
• Any web UI framework

Quick Reference

Annotation Syntax

<!-- Action annotation -->
<element
  data-ui-action="unique-id"
  data-ui-trigger="click|hover|scroll|focus|wait|auto|keyboard"
  data-ui-effect="scope.state,scope.state2"
>

<!-- State annotation -->
<element
  data-ui-scope="scope-name"
  data-ui-state="state-name"
  data-ui-status="hidden|loading|animating|ready|error|disabled"
  data-ui-ready="true"
  data-ui-snapshot="screenshot-id"
>

JSON Schema

{
  "version": "1.0",
  "interactions": [
    {
      "id": "action-id",
      "scope": "scope-name",
      "trigger": "click",
      "effects": ["scope.state"]
    }
  ],
  "states": [
    {
      "scope": "scope-name",
      "name": "state-name",
      "status": "ready",
      "ready": true,
      "snapshot": "screenshot-id"
    }
  ]
}

---

Additional Resources

• EXAMPLES.md - Comprehensive examples including:
  • Modal dialogs with multiple buttons
  • Loading states and async operations
  • Dropdown menus with navigation
  • Common patterns (toggle, form submission, navigation, hover)
  • JSON Schema validation
  • Complete JSON manifest examples
  • Multi-step form workflows
  • Best practices and validation checklists

---

Validation Checklist

Before finalizing annotations:

• ☑ All interactive elements have data-ui-action
• ☑ All actions use only allowed triggers
• ☑ All actions have at least one effect
• ☑ All effects follow scope.state pattern
• ☑ All effects have corresponding state definitions
• ☑ All states have valid status values
• ☑ All ready=true states have snapshots
• ☑ Action IDs are unique and kebab-case
• ☑ Scope names are consistent and semantic
• ☑ No invented triggers or status values

---

Benefits

This metadata enables:

Automated Testing: Generate Playwright/Cypress tests from annotations

Visual Regression: Screenshot capture at stable states

Agent Execution: AI can understand and interact with UI programmatically

Documentation: Self-documenting interaction flows

Debugging: Clear state transitions for troubleshooting

---

When to Use This Skill

Use this skill when:

• Creating new interactive web applications
• Adding test automation metadata to existing UIs
• Building AI-navigable interfaces
• Documenting complex interaction flows
• Setting up visual regression testing
• Enabling agent-based UI testing

---

Notes

• This is a constrained language - AI cannot invent new values
• Focus on observable states, not implementation details
• Prefer semantic naming over technical jargon
• Keep scopes consistent across related interactions
• Always validate against the JSON schema before finalizing

---

Ready to annotate your UI with IMS v1 metadata! Just tell me which components to process or provide a directory path to scan.