---

name: dynamic-layout-report description: Create and fill dynamic layout reports via API. Use when building structured reports with layouts containing grids, flex containers, and content slots. Supports charts (Chart.js), diagrams (Mermaid), infographics (AntV), markdown, tables, and code blocks. Use this skill when asked to create reports, dashboards, or documents with visual layouts. license: MIT metadata: author: dynamic-layout-sys version: "1.1" api-base-url: "/api/v1"

Dynamic Layout Report Skill

This skill enables creating structured reports through a layout-first, content-fill approach:

1. Design Layout - Define the visual structure with containers and slots
2. Fill Content - Populate slots with content matching their component types

API Base URL

/api/v1

Workflow Overview

1. GET /capabilities          → Understand system limits
2. POST /reports              → Create report with layout
3. PATCH /reports/{id}        → Fill slot content (can be parallel)
4. GET /reports/{id}          → Verify completion
5. POST /reports/{id}/export  → Export to PDF (optional)

Step 1: Create Layout

Request

POST /api/v1/reports
Content-Type: application/json

Layout Structure

Layout is a tree of ContainerNode and SlotNode:

type LayoutNode = ContainerNode | SlotNode;

interface ContainerNode {
  node_type: 'container';
  container_type: 'grid' | 'flex';
  props: ContainerProps;
  children: LayoutNodeWrapper[];
}

interface SlotNode {
  node_type: 'slot';
  id: string;              // Format: slot_{ULID}
  component: ComponentType;
  meta?: { prompt_hint?: string; max_words?: number; required?: boolean };
}

interface LayoutNodeWrapper {
  grid_item?: { col_span?: number; row_span?: number };
  node: LayoutNode;
}

Constraints

• Max depth: 2 levels (depth 0 → depth 1 → depth 2 must be slot)
• Slot IDs: Must be unique, format slot_{ULID} (26 char Crockford Base32)
• ULID charset: 0-9, A-H, J-K, M-N, P-T, V-Z (no I, L, O, U)

Example: Create Report

{
  "title": "Q1 Analysis Report",
  "layout": {
    "root": {
      "node_type": "container",
      "container_type": "grid",
      "props": { "columns": 12, "gap": "24px" },
      "children": [
        {
          "grid_item": { "col_span": 12 },
          "node": {
            "node_type": "slot",
            "id": "slot_01JHF0TITLE0000000000000",
            "component": "text_h1",
            "meta": { "prompt_hint": "Report title" }
          }
        },
        {
          "grid_item": { "col_span": 6 },
          "node": {
            "node_type": "slot",
            "id": "slot_01JHF0CHART0000000000001",
            "component": "chart_js",
            "meta": { "prompt_hint": "Sales trend chart" }
          }
        },
        {
          "grid_item": { "col_span": 6 },
          "node": {
            "node_type": "slot",
            "id": "slot_01JHF0MERMAID00000000002",
            "component": "mermaid",
            "meta": { "prompt_hint": "Process flow diagram" }
          }
        },
        {
          "grid_item": { "col_span": 12 },
          "node": {
            "node_type": "slot",
            "id": "slot_01JHF0MARKDOWN00000000003",
            "component": "markdown_long",
            "meta": { "prompt_hint": "Detailed analysis", "max_words": 500 }
          }
        }
      ]
    }
  }
}

Response

{
  "id": "rpt_01JHEZ8KXJMJ2PQRS3T4UV5WXY",
  "status": "draft",
  "layout_version": 1,
  "content": {
    "slot_01JHF0TITLE0000000000000": { "status": "pending", "data": null },
    "slot_01JHF0CHART0000000000001": { "status": "pending", "data": null },
    "...": "..."
  }
}

Step 2: Fill Content

Request

PATCH /api/v1/reports/{report_id}
Content-Type: application/merge-patch+json

{
  "content": {
    "slot_01JHF0TITLE0000000000000": {
      "status": "filled",
      "data": "Q1 2025 Sales Analysis",
      "generated_by": "agt_01JHEZ9ABCMJ2PQRS3T4UV5WX0",
      "generated_at": "2025-01-14T10:30:00Z"
    }
  }
}

Component Data Formats

Text Components (text_h1, text_h2, text_h3)

{ "status": "filled", "data": "Heading Text" }

Markdown (markdown, markdown_long)

{ "status": "filled", "data": "## Section\n\nParagraph with **bold** and *italic*.\n\n- Item 1\n- Item 2" }

Mermaid (mermaid)

Supports: flowchart, sequenceDiagram, classDiagram, gantt, pie, mindmap, timeline

{ "status": "filled", "data": "flowchart LR\n    A[Start] --> B[Process]\n    B --> C[End]" }

{ "status": "filled", "data": "pie title Market Share\n    \"Product A\" : 45\n    \"Product B\" : 30\n    \"Product C\" : 25" }

{ "status": "filled", "data": "gantt\n    title Project Timeline\n    dateFormat YYYY-MM-DD\n    section Phase 1\n    Task 1 :a1, 2025-01-01, 30d\n    section Phase 2\n    Task 2 :a2, after a1, 45d" }

Chart.js (chart_js)

Required fields: type, data

{
  "status": "filled",
  "data": {
    "type": "bar",
    "data": {
      "labels": ["Jan", "Feb", "Mar", "Apr"],
      "datasets": [{
        "label": "Sales",
        "data": [120, 190, 170, 220],
        "backgroundColor": ["#3b82f6", "#10b981", "#f59e0b", "#ef4444"]
      }]
    },
    "options": {
      "responsive": true,
      "plugins": { "title": { "display": true, "text": "Monthly Sales" } }
    }
  }
}

Chart types: bar, line, pie, doughnut, radar, polarArea, bubble, scatter

Infographic (infographic)

Uses AntV Infographic DSL syntax. Must start with infographic <template-name>.

📖 詳細語法參考: references/INFOGRAPHIC.md

Syntax Structure:

infographic <template-name>
data
  title <標題>
  desc <描述>
  items
    - label <項目標籤>
      value <數值>
      desc <項目描述>
theme
  palette <色彩1> <色彩2> ...

Example - Funnel:

{
  "status": "filled",
  "data": "infographic funnel\ndata\n  title Sales Funnel\n  items\n    - label Visits\n      value 1000\n    - label Signups\n      value 500\n    - label Purchases\n      value 100\ntheme\n  palette #3b82f6 #10b981 #f59e0b"
}

Example - KPI List:

{
  "status": "filled", 
  "data": "infographic list-col-simple\ndata\n  title Key Metrics\n  items\n    - label Growth\n      value +25%\n      desc Year over year\n    - label Users\n      value 10K+\n      desc Active users\n    - label Rating\n      value 4.8\n      desc Average score"
}

Example - Process Steps:

{
  "status": "filled",
  "data": "infographic sequence-steps\ndata\n  title Development Process\n  items\n    - label Plan\n      desc Define requirements\n    - label Design\n      desc Create architecture\n    - label Build\n      desc Implement code\n    - label Test\n      desc Quality assurance"
}

Example - Timeline:

{
  "status": "filled",
  "data": "infographic sequence-timeline\ndata\n  title Project Milestones\n  items\n    - time Week 1\n      label Kickoff\n      desc Team alignment\n    - time Week 2-4\n      label Development\n      desc Core features\n    - time Week 5\n      label Launch\n      desc Go live"
}

Common Templates:

Category	Templates
List	list-row-simple-horizontal-arrow, list-col-simple, list-grid
Sequence	sequence-steps, sequence-timeline, sequence-pyramid
Funnel	funnel, sequence-filter-mesh
Hierarchy	hierarchy-tree, list-pyramid
Compare	compare-binary-horizontal, compare-hierarchy-row
Relation	relation-circle, relation-network
Chart	chart-bar, chart-column, chart-line

Table (table)

Required fields: headers, rows

{
  "status": "filled",
  "data": {
    "headers": ["Product", "Q1", "Q2", "Q3", "Q4"],
    "rows": [
      ["Product A", "100", "120", "150", "180"],
      ["Product B", "80", "90", "100", "110"]
    ]
  }
}

Code Block (code_block)

Required fields: language, code

{
  "status": "filled",
  "data": {
    "language": "python",
    "code": "def analyze_data(df):\n    return df.describe()"
  }
}

Images (image_url, image_base64)

{ "status": "filled", "data": "https://example.com/chart.png" }

{ "status": "filled", "data": "data:image/png;base64,iVBORw0KGgo..." }

Container Types

Grid Container

{
  "node_type": "container",
  "container_type": "grid",
  "props": {
    "columns": 12,
    "rows": 2,
    "gap": "16px",
    "padding": "24px"
  },
  "children": [
    { "grid_item": { "col_span": 4 }, "node": { "..." } },
    { "grid_item": { "col_span": 8 }, "node": { "..." } }
  ]
}

Flex Container

{
  "node_type": "container",
  "container_type": "flex",
  "props": {
    "direction": "column",
    "justify": "start",
    "align": "stretch",
    "gap": "16px"
  },
  "children": [
    { "node": { "..." } },
    { "node": { "..." } }
  ]
}

Common Layout Patterns

Full-width header + two columns

Grid(12)
├── Slot(col_span:12) - Header
├── Slot(col_span:6) - Left content
└── Slot(col_span:6) - Right content

Sidebar + main content

Grid(12)
├── Flex(col_span:3) - Sidebar
│   ├── Slot - Nav
│   └── Slot - Info
└── Flex(col_span:9) - Main
    ├── Slot - Title
    ├── Grid(2) - Charts
    │   ├── Slot - Chart 1
    │   └── Slot - Chart 2
    └── Slot - Content

Content Status Values

Status	data	Description
pending	null	Waiting to be filled
processing	null	Currently being generated
filled	<content>	Successfully filled
failed	null	Failed (requires error_msg)

Error Codes

Code	HTTP	Description
VALIDATION_ERROR	400	Request body invalid
INVALID_SLOT_ID	400	Slot ID not in layout
MAX_DEPTH_EXCEEDED	400	Layout exceeds 2 levels
DUPLICATE_SLOT_ID	400	Slot ID appears twice
CONTENT_TYPE_MISMATCH	422	Data format doesn't match component
REPORT_NOT_FOUND	404	Report ID not found

ID Format Reference

Type	Prefix	Regex
Report	rpt_	^rpt_[0-9A-HJKMNP-TV-Z]{26}$
Slot	slot_	^slot_[0-9A-HJKMNP-TV-Z]{26}$
Agent	agt_	^agt_[0-9A-HJKMNP-TV-Z]{26}$
Export	exp_	^exp_[0-9A-HJKMNP-TV-Z]{26}$

Complete Example

1. Create Report

POST /api/v1/reports

{
  "title": "Q1 Product Report",
  "layout": {
    "root": {
      "node_type": "container",
      "container_type": "grid",
      "props": { "columns": 12, "gap": "24px" },
      "children": [
        {
          "grid_item": { "col_span": 12 },
          "node": {
            "node_type": "slot",
            "id": "slot_01JHF0A00000000000000001",
            "component": "text_h1"
          }
        },
        {
          "grid_item": { "col_span": 6 },
          "node": {
            "node_type": "slot",
            "id": "slot_01JHF0A00000000000000002",
            "component": "chart_js"
          }
        },
        {
          "grid_item": { "col_span": 6 },
          "node": {
            "node_type": "slot",
            "id": "slot_01JHF0A00000000000000003",
            "component": "mermaid"
          }
        }
      ]
    }
  }
}

2. Fill All Slots

PATCH /api/v1/reports/rpt_01JHEZ8KXJMJ2PQRS3T4UV5WXY

{
  "content": {
    "slot_01JHF0A00000000000000001": {
      "status": "filled",
      "data": "Q1 2025 Product Analysis"
    },
    "slot_01JHF0A00000000000000002": {
      "status": "filled",
      "data": {
        "type": "line",
        "data": {
          "labels": ["Jan", "Feb", "Mar"],
          "datasets": [{ "label": "Sales", "data": [100, 150, 200] }]
        }
      }
    },
    "slot_01JHF0A00000000000000003": {
      "status": "filled",
      "data": "flowchart TD\n    A[Research] --> B[Design]\n    B --> C[Build]\n    C --> D[Launch]"
    }
  }
}

3. Export (Optional)

POST /api/v1/reports/rpt_01JHEZ8KXJMJ2PQRS3T4UV5WXY/export

{
  "format": "pdf",
  "options": { "page_size": "A4" }
}