---
name: agentation-layout
description: Process Agentation v3.0 layout mode annotations. Converts drag-and-drop component placements and section rearrangements from the browser toolbar into actual code changes. Use when annotations have kind "placement" or "rearrange," or when the user says "process layout annotations," "implement wireframe," or "apply layout changes."
---
# Agentation Layout Mode Processor
Convert Agentation v3.0 layout annotations into real code changes. Layout mode lets users drag components onto the page and rearrange sections visually — this skill translates those visual intentions into source code.
## Layout Annotation Types
### Placement (`kind: "placement"`)
User dragged a component from the palette onto the page. The annotation contains:
```json
{
"kind": "placement",
"comment": "Optional note about the component",
"placement": {
"componentType": "hero-section",
"width": 1200,
"height": 400,
"scrollY": 150,
"text": "Optional placeholder text"
},
"x": 50,
"y": 200,
"url": "http://localhost:3000/67/home"
}
```
**Fields:**
- `componentType`: One of 65+ types from the palette (see Component Type Map below)
- `width` / `height`: Desired dimensions in pixels
- `scrollY`: Vertical scroll position where the component was placed
- `x` / `y`: Position on the page (x is % of viewport width, y is px from top)
- `text`: Optional placeholder text the user typed
### Rearrange (`kind: "rearrange"`)
User dragged an existing section to a new position. The annotation contains:
```json
{
"kind": "rearrange",
"comment": "Move this above the table",
"rearrange": {
"selector": "section.kpi-row",
"label": "KPI Summary Row",
"tagName": "SECTION",
"originalRect": { "x": 0, "y": 400, "width": 1200, "height": 200 },
"currentRect": { "x": 0, "y": 100, "width": 1200, "height": 200 }
},
"url": "http://localhost:3000/67/home"
}
```
**Fields:**
- `selector`: CSS selector identifying the section
- `label`: Human-readable name detected by Agentation
- `tagName`: HTML tag of the section
- `originalRect`: Where the section was before dragging
- `currentRect`: Where the user moved it to
## Processing Placement Annotations
### Step 1: Identify the target page
Map the annotation URL to a source file:
- `http://localhost:3000/67/home` → `frontend/src/app/(main)/[projectId]/home/`
- `http://localhost:3000/settings` → `frontend/src/app/(main)/settings/` or `(admin)/settings/`
### Step 2: Map componentType to a real component
The Agentation palette uses generic type names. Map them to project components:
| Palette Type | Project Component | Import |
|-------------|------------------|--------|
| `hero-section` | Custom — build with PageShell variant="dashboard" | `@/components/layout` |
| `stats-row` / `kpi-row` | `KpiRow` + `KpiBlock` | `@/components/ds` |
| `data-table` | `UnifiedTablePage` or `DataTable` | `@/components/tables/unified` |
| `form` | React Hook Form + Zod | `react-hook-form`, `@hookform/resolvers/zod` |
| `card` | `Card` | `@/components/ui/card` |
| `tabs` | `Tabs` / `TabsList` / `TabsContent` | `@/components/ui/tabs` |
| `chart` / `bar-chart` / `line-chart` | Recharts wrapper | `recharts` |
| `button` | `Button` | `@/components/ui/button` |
| `input` / `text-field` | `Input` | `@/components/ui/input` |
| `select` / `dropdown` | `Select` | `@/components/ui/select` |
| `dialog` / `modal` | `Dialog` | `@/components/ui/dialog` |
| `sidebar` | Existing sidebar layout | `@/components/layout` |
| `empty-state` | `EmptyState` | `@/components/ds` |
| `status-badge` | `StatusBadge` | `@/components/ds` |
| `section-header` | `SectionHeader` | `@/components/ds` |
| `avatar` | `Avatar` | `@/components/ui/avatar` |
| `alert` | `Alert` | `@/components/ui/alert` |
| `breadcrumb` | `Breadcrumb` | `@/components/ui/breadcrumb` |
| `calendar` | `Calendar` | `@/components/ui/calendar` |
| `progress` | `Progress` | `@/components/ui/progress` |
For types not in this map, check `@/components/ds` and `@/components/ui` first. If nothing matches, create a new component following the design system.
### Step 3: Determine insertion point
Use `scrollY` and `y` position to figure out WHERE on the page the component goes:
- Low y (0-200px): Near the top, likely before or after the page header
- Mid y: Between existing sections
- High y: Near the bottom, likely before the footer or as a new section
Read the target page's source code and identify the nearest existing component boundaries.
### Step 4: Generate the component code
Follow project conventions:
- Use design system tokens (no hardcoded colors)
- Use `@/components/ds` or `@/components/ui` imports
- Match existing page patterns (check sibling pages for reference)
- If `text` is provided, use it as placeholder/default content
- Respect `width`/`height` hints but convert to responsive Tailwind (e.g., `max-w-4xl`)
### Step 5: Insert and resolve
1. Edit the page file to add the component at the correct position
2. Call `agentation_resolve(annotationId, "Added {componentType} to {page} — {brief description}")`
## Processing Rearrange Annotations
### Step 1: Find the section in source code
Use the `selector` and `label` to find the JSX block:
```
grep -n "kpi-row\|KpiRow\|KPI Summary" frontend/src/app/(main)/[projectId]/home/
```
### Step 2: Determine new order
Compare `originalRect.y` with `currentRect.y`:
- `currentRect.y < originalRect.y` → Move the section UP (earlier in the JSX)
- `currentRect.y > originalRect.y` → Move the section DOWN (later in the JSX)
### Step 3: Cut and paste the JSX block
1. Read the page source
2. Identify the JSX block boundaries for the section
3. Cut the block from its original position
4. Insert it at the new position (based on relative y positions of other sections)
5. Preserve all props, state, and imports
### Step 4: Resolve
Call `agentation_resolve(annotationId, "Moved {label} {up/down} in {page}")`
## Design System Compliance
All generated components MUST follow the project's design system:
- Import from `@/components/ds` or `@/components/ui`
- Use semantic color tokens only (`bg-background`, `bg-card`, `text-foreground`, etc.)
- No hardcoded colors, no `gray-*`/`blue-*` classes
- Shadows: only `shadow-xs` (cards) or `shadow-sm` (dropdowns)
- Spacing: use Tailwind scale (`p-4`, `gap-6`), no arbitrary values
- New pages must use `PageShell`
- Check `GOLDEN-EXAMPLES.tsx` for patterns
## Batch Processing
When multiple layout annotations target the same page:
1. Read ALL layout annotations for that page first
2. Plan the combined layout (placements + rearrangements together)
3. Apply all changes in a single edit pass
4. Resolve all annotations together
This prevents conflicts where one placement shifts the positions of other placements.
## Limitations
- Layout mode captures INTENT, not pixel-perfect design. Translate positions into responsive layouts.
- Component palette types are generic — always map to project-specific components.
- Rearrange captures approximate positions — use relative ordering (before/after siblings) rather than absolute coordinates.
