Texture

Form Explainer Guidance Module

Overview & Release Notes

Form Explainer V1.0

The Form Explainer module provides interactive, mood-aware, step-by-step guidance for complex forms. It supports dynamic images, JSON-driven configuration, mood/aura styling, and flexible layout within the AmbientPixels grid system. This V1 release introduces mood/aura-driven UI, a modular architecture, and custom tooltips.

What's Next (Upcoming v0.2)

Live Demo

Component Breakdown

  • Image Container: The left column holds the form image, which serves as the backdrop for the interactive overlays.
  • Field Stack: The right column displays a list of all form fields, driven by your JSON configuration.
  • Three-Part Text: Each step shows a Title, Description, and a custom Tooltip on hover.
  • Whisper Panel: Displays "Nova's Thought" for the active step, providing contextual AI insights.
  • Automated Tour: The module automatically cycles through each step, highlighting the corresponding field and overlay.
  • Responsive Design: The layout adapts seamlessly from a two-column view on desktops to a single-column stack on mobile devices.

Implementation Guide

To use the Form Explainer module, include the following markup in your page. The script will automatically initialize any element with the class form-explainer-container. 

<!-- The container requires data attributes to specify the JSON path and image -->
<div id="form-explainer-container"
     class="form-explainer-container"
     
     data-json-path="/data/form-explainer-map.json"
     data-image-path="/images/your-form-screenshot.png"
     data-step-duration="3000">
     <!-- Module will auto-initialize and render here -->
</div>

<!-- Ensure the script is included -->
<script src="/js/form-explainer.js" defer></script>

Make sure to load the required CSS (form-explainer.css) and provide a valid JSON configuration file.

JSON Configuration (form-explainer-map.json)

The module is driven entirely by a JSON file, which is an array of objects. Each object defines a step in the tour. Each step can also include mood and aura fields for mood-aware UI. Below is a detailed breakdown of the keys for each step object:

Key Type Description
key String A unique identifier for the step. Used for internal mapping and data attributes.
title String The main heading displayed for the step in the right-hand column.
description String The sub-heading text displayed below the title. Provides brief context.
tooltip String The text that appears in the custom tooltip when the user hovers over the step item.
novaThought String The detailed AI insight that appears in the whisper panel below the screenshot.
left, top Number (Float) The X and Y coordinates for the top-left corner of the overlay. Values are percentages (0.0 to 1.0) of the image container's dimensions.
width, height Number (Float) The width and height of the overlay. Values are percentages (0.0 to 1.0) of the image container's dimensions.

Example JSON Entry

[
  {
    "key": "title",
    "title": "1. Form Title",
    "description": "The main heading of the form.",
    "tooltip": "Clearly states the purpose of the form.",
    "left": 0.04, "top": 0.03, "width": 0.92, "height": 0.08,
    "novaThought": "A good title sets the right expectation. Users scan this first to confirm they're in the right place."
  },
  {
    "key": "description",
    "title": "2. Form Description",
    "description": "Provides context and instructions.",
    "tooltip": "A brief summary of what the user needs to do.",
    "left": 0.04, "top": 0.12, "width": 0.92, "height": 0.09,
    "novaThought": "The description is an emotional anchor—it reassures users they'll get the help they need."
  }
      // ... more steps, each with optional "mood" and "aura" fields 
]

Styling & Customization