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.
