Visual AI Instructing: Bridging the Gap Between Design and Code with Instruckt

Overview of Visual Annotations

Explaining visual changes to an AI agent often involves a clunky workflow of screenshots, manual uploads, and imprecise descriptions. Instruckt changes this by allowing developers to annotate DOM elements directly in the browser. Instead of guessing class names or describing a button's location, you click the element, add a note, and generate a markdown prompt that contains the exact technical context Claude Code needs to execute the change. This precision reduces the "hallucination" factor when AI attempts to style UI components.

Prerequisites

To follow this workflow, you should be comfortable with basic Laravel development and Tailwind CSS. You also need an AI agent capable of processing markdown context, such as Claude Code. Familiarity with Composer for package management is required for the installation steps.

Key Libraries & Tools

• Instruckt-Laravel: The specific adapter for Laravel applications.
• Instruckt Core: A framework-agnostic JavaScript core that handles the annotation logic.
• Claude Code: The CLI-based AI agent that receives the markdown feedback to modify the source code.
• Blade Components: The templating engine used to inject the annotation toolbar.

Implementation Walkthrough

Installing the tool requires a quick pull via Composer. Run the following command in your terminal:

composer require joshcirre/instruckt-laravel

Once installed, you must register the visual toolbar. In a Laravel environment, you typically place the Laravel component at the bottom of your global layout file (e.g., app.blade.php or welcome.blade.php):

<x-instruckt />

This tag renders a floating toolbar on your frontend. When you enter "Annotate" mode, the tool identifies the underlying Tailwind CSS classes and HTML structure of whatever you click. After adding notes, click "Copy Annotations as Markdown." You then paste this directly into your AI terminal. The agent sees a structured list of targeted elements and your specific instructions, allowing it to swap links or adjust font sizes with perfect accuracy.

Syntax and Conventions

The tool relies on the x-instruckt Laravel component pattern, which is standard for modern Laravel packages. It intelligently scrapes Tailwind CSS classes from the DOM. If you are using Livewire, Instruckt offers specialized adapters to ensure the toolbar persists across reactive state changes.

Tips & Gotchas

Always wrap your Instruckt component in an environment check. You likely don't want the annotation toolbar appearing in production. Use a conditional check like @env('local') to ensure it only loads during development. If the agent fails to find an element, ensure your classes aren't being obfuscated by a minifier during the build process, as Claude Code needs those class strings to locate the correct line in your source files.