naming-guide

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.

Convey Naming Guide

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

---

Topology

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 (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

---

Panel (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.

---

Server (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 (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

---

Glossary

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