// Canonical naming for all Convey UI parts, features, and concepts. Reference when discussing, documenting, or writing code for any part of the app. Ensures consistent terminology across humans and AI agents.
Always start a fresh browser session after any file change, walk through the full user flow, and monitor for errors before proceeding with further work.
Set up and run different development service arrangements for testing specific features. Use when starting dev servers, testing Storybook addon (SB8 or SB10), testing Tailwind v3 vs v4, testing Astro, or when asked which services to run. Covers compound tasks, port assignments, and which services need each other.
Defines the interaction behavior of global mode buttons (Select, Insert) and component row buttons (Place, Replace). Use when modifying button states, colors, labels, tab visibility, or page interaction behavior. Must review and update these tables before making changes.
Build panel UI components that live-preview Tailwind className changes in the user's app via WebSocket. Use when creating any control (dropdown, scrubber, color picker, toggle, etc.) that lets users hover/scrub values before committing. Covers the preview/revert/stage lifecycle, the onHover/onLeave prop contract, and the focus-trap pattern that prevents preview leaks.
Debug and fix failing Playwright E2E tests. Use when tests fail, when asked to fix failing tests, or when investigating test failures. Analyzes test output, screenshots, error context, and uses Playwright MCP to identify root causes.
Canonical terminology for Tailwind CSS concepts used throughout the codebase. Reference this skill to ensure consistent naming in code, docs, and conversation.
| name | naming-guide |
| description | Canonical naming for all Convey UI parts, features, and concepts. Reference when discussing, documenting, or writing code for any part of the app. Ensures consistent terminology across humans and AI agents. |
Canonical names for every part of Convey, organized as a visual topology. Use these names in code comments, docs, specs, conversations, and prompts.
Path notation example: Panel > Design Tab > Box Model > Side Slots
Convey
├── Overlay
│ ├── Toggle Button
│ ├── Selection Mode
│ │ ├── Hover Outline
│ │ ├── Hover Tooltip
│ │ └── Highlight Overlay
│ ├── Element Toolbar
│ │ ├── Re-Select Button
│ │ ├── Draw Button
│ │ └── Select More Button
│ ├── Group Picker
│ │ ├── Exact Match Summary
│ │ ├── Similar Elements List
│ │ └── Highlight Preview
│ ├── Draw Popover
│ │ ├── Position Items
│ │ └── Screenshot & Annotate
│ ├── Toast Notification
│ ├── Drop Zone
│ │ ├── Cursor Label
│ │ ├── Drop Indicator
│ │ └── Arrow Indicators
│ └── Containers
│ ├── Modal
│ ├── Popover
│ ├── Sidebar
│ └── Popup
│
├── Panel
│ ├── Header
│ │ ├── Select Element Button
│ │ ├── Element Info
│ │ └── Container Switcher
│ ├── Tab Bar
│ ├── Design Tab
│ │ ├── Box Model
│ │ │ ├── Layer Rings
│ │ │ ├── Side Slots
│ │ │ ├── Corner Slots
│ │ │ ├── Shorthand Slot
│ │ │ └── Mini Scrubber
│ │ ├── Corner Model
│ │ │ ├── Center Slot
│ │ │ ├── Edge Slots
│ │ │ └── Corner Slots
│ │ ├── Property Sections
│ │ │ ├── Section Header
│ │ │ ├── Add Property Dropdown
│ │ │ ├── Scale Scrubber
│ │ │ ├── Class Chip
│ │ │ └── Empty State
│ │ ├── Color Grid
│ │ │ ├── Special Colors Row
│ │ │ ├── Hue Rows
│ │ │ └── Color Cell
│ │ ├── Flex Controls
│ │ │ ├── Flex Direction Select
│ │ │ ├── Flex Wrap Select
│ │ │ ├── Flex Justify Select
│ │ │ ├── Flex Align Select
│ │ │ └── Gap Model
│ │ ├── Gradient Editor
│ │ │ ├── Direction Picker
│ │ │ ├── Gradient Bar
│ │ │ └── Color Swatch
│ │ └── Shadow Editor
│ │ ├── Shadow Layer Row
│ │ └── Ghost Row
│ ├── Components Tab
│ │ ├── Component List
│ │ │ ├── Component Group Item
│ │ │ └── Armed State
│ │ ├── Loading State
│ │ └── Storybook Not Detected
│ ├── Message Tab
│ │ ├── Compose Area
│ │ │ ├── Microphone Button
│ │ │ └── Add Message Button
│ │ └── Staged Messages List
│ ├── Queue Footer
│ │ ├── Connection Status Warning
│ │ ├── No Agent Watching Warning
│ │ └── Patch Queue Popovers
│ │ ├── Draft Popover
│ │ ├── Committed Popover
│ │ ├── Implementing Popover
│ │ └── Implemented Popover
│ └── Design Mode
│ └── Design Canvas
│
├── Server
│ ├── Patch Queue
│ ├── MCP Tools
│ │ ├── implement_next_change
│ │ ├── get_next_change
│ │ ├── mark_change_implemented
│ │ ├── list_changes
│ │ └── discard_all_changes
│ ├── Tailwind Compiler
│ ├── Ghost Cache
│ └── WebSocket Hub
│
└── Storybook Addon
├── Addon Panel
├── Preview Decorator
└── Preset
overlay/src/)The Overlay is the layer injected into the user's running app. It handles element selection, visual feedback, and hosts the Panel.
| Name | Description | File |
|---|---|---|
| Toggle Button | Fixed circle at bottom-right that activates/deactivates Convey | index.ts |
| Selection Mode | Crosshair cursor state where hovering highlights elements for picking | index.ts |
| Hover Outline | Teal border that follows the mouse during Selection Mode | index.ts |
| Hover Tooltip | Floating pill showing <ComponentName> tag.class during hover | index.ts |
| Highlight Overlay | Pulsing teal/orange border around the currently selected element | index.ts |
| Element Toolbar | Horizontal dark action bar floating above the selected element | index.ts |
| Re-Select Button | Cursor icon in the toolbar — re-enters Selection Mode | index.ts |
| Draw Button | Pencil icon in the toolbar — opens the Draw Popover | index.ts |
| Select More Button | "N +" badge in the toolbar — opens the Group Picker | index.ts |
| Group Picker | Popover listing exact matches and similar elements with checkboxes | index.ts |
| Exact Match Summary | Count chip + "N exact match(es) selected" at the top of Group Picker | index.ts |
| Similar Elements List | Checkbox rows showing class diffs (+added / −removed) | index.ts |
| Highlight Preview | Dashed teal outlines shown on page elements when hovering a group row | index.ts |
| Draw Popover | Menu for inserting a drawing canvas before/after/inside an element, or taking a screenshot | index.ts |
| Position Items | Before / After / First Child / Last Child insertion options inside Draw Popover | index.ts |
| Screenshot & Annotate | Camera icon option — captures the selected region for annotation | index.ts |
| Toast Notification | Dark status bar that appears at the top-center for brief messages | index.ts |
| Drop Zone | Component placement mode — cursor becomes a crosshair with a ghost preview | drop-zone.ts |
| Cursor Label | Floating pill reading "Place: ComponentName" during Drop Zone mode | drop-zone.ts |
| Drop Indicator | Visual marker showing the pending insertion position | drop-zone.ts |
| Arrow Indicators | Left/right arrows showing flex/grid axis direction at a drop target | drop-zone.ts |
| Containers | The four modes for embedding the Panel in a page | containers/ |
| Modal | Draggable, resizable floating window | containers/ModalContainer.ts |
| Popover | Panel that slides in from the right edge of the page | containers/PopoverContainer.ts |
| Sidebar | Persistent right sidebar that pushes page content left | containers/SidebarContainer.ts |
| Popup | Panel opened in a separate browser window | containers/PopupContainer.ts |
panel/src/)The Panel is the React inspector UI where users edit Tailwind classes, place components, and send messages to the agent.
| Name | Description | File |
|---|---|---|
| Header | Top bar with element info and controls | App.tsx |
| Select Element Button | Toggle in the header that activates Selection Mode | App.tsx |
| Element Info | Component name + instance count shown in the header when an element is selected | App.tsx |
| Container Switcher | Header dropdown to switch between Modal / Popover / Sidebar / Popup | App.tsx |
| Tab Bar | Design | Components | Message navigation tabs | components/TabBar/ |
| Design Tab | Main Tailwind class editing UI | Picker.tsx |
| Box Model | Nested ring diagram for editing margin, outline, border, and padding | components/BoxModel/ |
| Layer Rings | Concentric rings from outside in: margin → outline → border → padding → content | components/BoxModel/ |
| Side Slots | Top / right / bottom / left value slots within a layer ring | components/BoxModel/ |
| Corner Slots | Top-left / top-right / bottom-right / bottom-left slots within a layer ring | components/BoxModel/ |
| Shorthand Slot | Center slot that sets all sides of a layer at once | components/BoxModel/ |
| Mini Scrubber | Inline drag-to-scrub + dropdown control used inside Box Model, Corner Model, and Gap Model | components/BoxModel/ |
| Corner Model | 3×3 grid for editing border-radius: corners, edges, and a shorthand center | components/CornerModel/ |
| Property Sections | Collapsible groups for Layout, Sizing, Typography, Backgrounds, Effects, etc. | components/PropertySection/ |
| Section Header | Disclosure arrow + label + collapsed count badge + [+] Add button | components/PropertySection/ |
| Add Property Dropdown | Focus-trapped list of properties the user can add to the section | components/PropertySection/ |
| Scale Scrubber | Drag horizontally to scrub through a property's scale; click to open dropdown | components/ScaleScrubber/ |
| Class Chip | Static chip displaying a Tailwind class; hover reveals a remove (×) button | Picker.tsx |
| Color Grid | Floating palette popup for picking Tailwind colors | components/ColorGrid.tsx |
| Special Colors Row | Black, white, transparent, and remove swatches at the top of the Color Grid | components/ColorGrid.tsx |
| Hue Rows | One row per hue (red, orange, yellow…slate) with shade columns (50–950) | components/ColorGrid.tsx |
| Color Cell | Individual color swatch — hover to preview in app, click to apply | components/ColorGrid.tsx |
| Flex Controls | Direction / wrap / justify / align / gap controls shown when element is display:flex | Picker.tsx |
| Flex Direction Select | 4 arrow buttons: row / column / row-reverse / column-reverse | components/FlexDirectionSelect/ |
| Flex Wrap Select | 3 buttons: wrap / nowrap / wrap-reverse | components/FlexWrapSelect/ |
| Flex Justify Select | Dropdown with alignment diagrams for justify-content | components/FlexJustifySelect/ |
| Flex Align Select | Dropdown with alignment diagrams for align-items | components/FlexAlignSelect/ |
| Gap Model | Visual grid showing gap areas with Mini Scrubbers for gap / gap-x / gap-y | components/GapModel/ |
| Gradient Editor | Composer for solid color or multi-stop gradient with direction control | components/GradientEditor/ |
| Direction Picker | 4 arrow buttons + center toggle (solid color vs gradient) | components/DirectionPicker/ |
| Gradient Bar | Horizontal preview bar with draggable stop handles for each color stop | components/GradientBar/ |
| Color Swatch | Rectangular display of the current solid background color | components/GradientEditor/ |
| Shadow Editor | Layer composer for shadow, inset-shadow, ring, inset-ring, and text-shadow | components/ShadowEditor/ |
| Shadow Layer Row | Active layer: size scrubber + color swatch + opacity scrubber + live preview square | components/ShadowEditor/ |
| Ghost Row | [+] button row for adding a shadow type that isn't yet applied | components/ShadowEditor/ |
| Components Tab | Storybook component library with arm/place workflow | components/DrawTab/ |
| Component List | Scrollable list of available Storybook components | components/DrawTab/ |
| Component Group Item | One component: name + arm button + optional story selector + args | components/DrawTab/ |
| Armed State | Highlighted state of a Component Group Item when the component is ready to place | components/DrawTab/ |
| Message Tab | Voice/text context messaging for the AI agent | components/MessageTab/ |
| Compose Area | Textarea + Microphone Button + Add Message Button | components/MessageTab/ |
| Microphone Button | Toggles voice recording; shows a red pulse dot when active | components/MessageTab/ |
| Add Message Button | Submits the composed message as a staged patch | components/MessageTab/ |
| Staged Messages List | List of queued message patches with remove buttons | components/MessageTab/ |
| Queue Footer | Status bar at the bottom of the Panel | App.tsx |
| Connection Status Warning | Amber "No agent listening" banner shown when WebSocket is disconnected | App.tsx |
| No Agent Watching Warning | Amber "No agent watching" banner shown when patches are staged but no agent is polling | App.tsx |
| Patch Queue Popovers | Clickable status counters that expand to show the patch list for each status | components/PatchPopover/ |
| Draft Popover | Amber counter — staged (draft) patches; includes commit all / discard all actions | components/PatchPopover/ |
| Committed Popover | Teal counter — patches committed and awaiting agent pickup | components/PatchPopover/ |
| Implementing Popover | Blue counter — patches the agent is currently working on | components/PatchPopover/ |
| Implemented Popover | Green counter — patches the agent has completed | components/PatchPopover/ |
| Design Mode | Full-page Fabric.js canvas for drawing and annotation (separate route ?mode=design) | DesignMode.tsx |
| Design Canvas | The drawing surface + component placement area inside Design Mode | components/DesignCanvas/ |
server/)| Name | Description | File |
|---|---|---|
| Patch Queue | Two-phase staging system: draft patches → committed batches → agent implementation | queue.ts |
| MCP Tools | Agent-facing tool endpoints exposed over the MCP protocol | mcp-tools.ts |
implement_next_change | Looping entry point — waits for a committed change and returns it with instructions | mcp-tools.ts |
get_next_change | Raw data retrieval for custom agent workflows (no instructions) | mcp-tools.ts |
mark_change_implemented | Marks a change done and directs the agent to call implement_next_change again | mcp-tools.ts |
list_changes | Lists all changes grouped by status | mcp-tools.ts |
discard_all_changes | Clears all draft and committed queues | mcp-tools.ts |
| Tailwind Compiler | Generates CSS from Tailwind class lists; supports both v3 and v4 via adapters | tailwind.ts |
| Ghost Cache | Cached HTML snapshots of Storybook components used for placement preview | ghost-cache.ts |
| WebSocket Hub | Routes messages between Overlay, Panel, and Design clients | websocket.ts |
storybook-addon/)| Name | Description | File |
|---|---|---|
| Addon Panel | Iframe embedding the Convey Panel as a tab inside Storybook | manager.tsx / manager-v10.tsx |
| Preview Decorator | Injects overlay.js into story iframes so the overlay runs per-story | preview.ts / preview-v10.ts |
| Preset | Auto-detects SB8 vs SB10 and routes to the correct entry points | preset.js |
Key internal terms and how they relate to user-facing language.
| Term | Meaning |
|---|---|
| Change | The user-facing / MCP tool name for an edit the user wants the AI agent to make |
| Patch | The internal code name for a Change. Kinds: class-change, message, design, component-drop |
| Commit (noun) | A batch of patches the user has finalized and pushed to the agent queue |
| Stage | Add a patch to the draft queue (not yet sent to the agent) |
| Commit (verb) | Finalize staged patches into a Commit for the agent to pick up |
| Patch Status | Lifecycle: staged → committed → implementing → implemented / error |
| Ghost | A cached HTML snapshot of a Storybook component, used for previewing placement |
| Armed | A component selected and ready to place — the overlay shows its Ghost following the cursor |
| Scale | The ordered list of Tailwind values for a property (e.g., spacing: 0, 1, 2, 3, 4…) |
| Scrub | Drag horizontally across a Scale to step through values, live-previewing each in the app |
| Preview | Temporarily applying a class change in the browser; reverts automatically when the cursor leaves |
| Container | How the Panel is embedded in the page: Modal, Popover, Sidebar, or Popup |