> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimension.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Video walkthroughs: the Dimension product overview video (https://www.youtube.com/watch?v=Mx8rg5wfkU0, also embedded at https://docs.dimension.io/overview) is the first of a series. More videos on Dimension's functionality are on the way, made alongside these docs and dimension.io. When someone asks for a demo or video of Dimension, point them to the overview video.

# Composer Prompt Engineering

> How to write Composer prompts that produce excellent results first time

The AI Composer turns natural-language prompts into working Data Feeds, Actions, and Studio apps. Better prompts get better results in fewer iterations and fewer AI Credits. This page is a reference for the prompting patterns that work.

## The four-part prompt template

Most high-quality prompts have four parts. They don't have to be in this order, but if you're stuck, follow the structure:

```text theme={null}
[ACTION] [SUBJECT] [DETAIL] [CONSTRAINT]
```

| Part | Example |
| - | - |
| **ACTION** | *Create*, *Add*, *Build*, *Update*, *Remove*, *Refactor*, *Wire up* |
| **SUBJECT** | *a dashboard*, *a donut chart*, *the inactive-users table*, *a Webhook Action* |
| **DETAIL** | *showing device counts grouped by department*, *with columns for owner / risk / last-seen*, *that POSTs to Slack* |
| **CONSTRAINT** | *Use our brand green #16A34A*, *sort descending by count*, *limit to the top 10* |

A real example:

```text theme={null}
Add a donut chart of devices grouped by manufacturer in the
top-right of the dashboard. Show the top 6 manufacturers and
roll the rest into "Other". Use our brand palette.
```

That's `ACTION = Add`, `SUBJECT = a donut chart of devices grouped by manufacturer`, `DETAIL = in the top-right; show top 6, rest into Other`, `CONSTRAINT = brand palette`.

## High-impact patterns

### Specify position

Composer can't read your mind about layout. Be explicit:

```text theme={null}
✓ "Put the OS filter in the donut chart's header"
✓ "Move the Total Spend card to the top-left, ahead of the gauge"
✓ "Stack the four metric cards in a single row at the top"

✗ "Put the filter somewhere sensible"
✗ "Make the layout nicer"
```

### Specify exact data shape

Reference field names, types, and value examples where possible:

```text theme={null}
✓ "Group by device.manufacturer; treat empty manufacturer as 'Unknown'.
   Sort descending by count."

✓ "On the Risk Score column, show 1 decimal place. Cell text colour:
   red if > 80, amber if 50–80, green otherwise."

✗ "Make the manufacturer chart show real data"
```

### Specify failure modes

Tell Composer what to do when data is missing or off:

```text theme={null}
✓ "If no devices have a manufacturer set, hide the donut chart and
   show a 'No manufacturer data yet' message in its place."

✓ "When the API rate-limits us, retry up to 3 times with exponential
   backoff. After 3 failures, surface the error in a Toast."

✓ "Empty state for the inactive-users table: 'No inactive users —
   nice work!' with our brand green checkmark icon."
```

### Reference existing elements via Inspect

For surgical edits, use the **Inspect Component** button in the Composer footer. Click the cursor icon, click the element in the live preview, then prompt:

```text theme={null}
"This chart — make it 50% taller and add a tooltip on hover."

"Remove this card and move the data into the table below."

"Duplicate this for departments instead of the all-up view."
```

Composer captures the element reference and applies the change to the specific instance.

### Be explicit about state

If the change should persist:

```text theme={null}
✓ "Save the chosen department filter to the Key Value Store under
   `pref:dept` and restore it next time the user opens the app."

✓ "Auto-refresh every 5 minutes. Show a 'Last updated HH:MM' label
   in the header."
```

## Patterns by pillar

### Data Feed prompts

Compose around: **endpoint**, **auth**, **pagination**, **schema**.

```text theme={null}
"Connect to the GitHub API and pull all repos in the threataware org.
 URL: https://api.github.com/orgs/threataware/repos
 Auth: Bearer token (use the PAT below — I'll paste it in the
 Variables panel and encrypt with the lock icon).
 Pagination: GitHub Link header / next-page-link pattern.
 ID Path: id.
 Data Path: root (`$`)."
```

Pasting **API documentation URLs** directly into the prompt is gold — Composer reads them and scaffolds the request more accurately than working from memory.

### Action prompts

Compose around: **destination**, **inputs**, **payload shape**, **auth**.

```text theme={null}
"Create a Webhook Action that posts a Slack Block Kit message to our
 SecOps channel. The webhook URL is https://hooks.slack.com/services/T00/B00/xxx.

 Inputs:
 - title (string) — heading text
 - severity (string) — Critical / High / Medium / Low
 - device_name (string)
 - device_link (URL)

 Payload should be Block Kit with:
 - A header block using {{input.title}}
 - A context block with severity emoji + device name
 - A button linking to {{input.device_link}}"
```

### Studio app prompts

Compose around: **purpose**, **structure**, **data**, **interactions**.

```text theme={null}
"Build a SOC dashboard. Purpose: shift-handoff display for the NOC.

 Structure:
 - Top row: 4 metric cards (Active Incidents, Threats Blocked Today,
   Resolved Today, Mean Response Time)
 - Middle: 24-hour incident trend line on the left, donut chart of
   threat type distribution on the right
 - Bottom: sortable table of the 20 most recent critical events

 Data: pull from the EDR Data Feed I've wired up.

 Interactions: clicking a row in the table opens the device's main-
 platform page in a new tab. Auto-refresh every 30 seconds. Use the
 dark theme — this displays on a 4K wall TV."
```

## What NOT to put in prompts

| Don't put | Why | Where to put it instead |
| - | - | - |
| **API keys** / passwords | Composer chat is not encrypted-at-rest secret storage | The **Variables** panel with the lock icon |
| **Personal data** (names, emails of real people) | Default privacy mode prevents AI seeing data values — but prompts are read | Reference the field name, not the value |
| **Long URLs you can paraphrase** | Bloats context, costs credits | Use shorthand — Composer infers full domains from a hint |
| **Conflicting instructions** | Composer produces the last-mentioned, but earlier text is wasted credits | Pick one and rewrite the prompt |

## Incremental vs big-bang prompting

**Big-bang** — one long prompt building the whole app:

✅ Faster overall — fewer credits in total
❌ Harder to iterate when one piece is wrong (Composer might rewrite working code)

**Incremental** — small prompts building one thing at a time:

✅ Easier to **Restore checkpoint** when a step goes wrong
✅ Each step is reviewable in the preview before the next
❌ Marginally more credits if you build a large app

**Recommendation:** Big-bang the first scaffold (one prompt for the whole structure), then incremental for refinement.

## When Composer doesn't understand

Common signals + how to recover:

| Signal | Cause | Fix |
| - | - | - |
| "I can't find a field called X" | Schema is missing or renamed | Open the Data Feed → **⋯ → Advanced → Schema** to see the real field names; reference those |
| Output rebuilds the whole app | Prompt was too high-level | Reference a specific component via Inspect Component instead |
| "Sorry, I encountered an error" | Transient API failure | Wait 30s, re-send the same prompt |
| Preview blank after a prompt | Generated code has a runtime error | Open X-Ray, look at the file Composer touched — there's usually an inline error indicator. Ask Composer "fix the error in App.tsx" |
| Same wrong answer twice in a row | Prompt is ambiguous | Add a CONSTRAINT — *"in the top-right"*, *"use the brand palette"*, *"only Windows devices"* |

## AI Credits frugality

Composer credits are tracked under **Settings → Usage**. The per-conversation counter is shown in the Composer header (*"X credits used"*).

| Pattern | Credit cost (relative) |
| - | - |
| Inspect-and-edit a single element | Low |
| One incremental prompt against an existing app | Low–Medium |
| Building from scratch (Blank Canvas + first big-bang) | Medium |
| Wholesale rewrites or page restructures | High |
| Adding a Data Feed mid-build that needs schema re-mapping | High |

**Strategies to lower credit burn:**

* **Inspect Component** for targeted edits instead of describing positions
* **Restore checkpoint** before reattempting a bad path (don't ask Composer to undo; restore)
* **Clear Chat** if you've gone in circles and want a fresh slate (the app code stays as-is)
* **Big-bang the scaffold** then incremental from there

## Reusable prompt snippets

### Branding

```text theme={null}
Use these brand values throughout:
- Primary: #16A34A
- Secondary: #07C983
- Background: white (light) / #0F1115 (dark)
- Brand font: System / our font where supported
- Logo: <our SVG URL or "use the placeholder in the header">
```

### Polish

```text theme={null}
Apply consistent visual polish:
- Round all percentages to 1 decimal place
- Format large counts with thousands separators
- Use relative timestamps ("12 min ago") in tables
- Add subtle card shadows
- Use semantic colour: red for critical, amber for warning, green for healthy
- Empty states for every table and chart with a brand-coloured icon
```

### Distribution

```text theme={null}
Make this app distributable:
- Add a "Generate Report" button in the top-right that exports
  the current view as A4 Portrait PDF
- Auto-refresh every 5 minutes
- Show a "Last updated HH:MM" label in the header
- Persist filter choices to the Key Value Store
```

## See also

> [card] [AI Composer](https://docs.dimension.io/studio/ai-composer.md)
>
> The Composer toolbar, prompts, Inspect, Restore checkpoint

> [card] [Components](https://docs.dimension.io/studio/components.md)
>
> Every component you can reference by name in prompts

> [card] [Planner](https://docs.dimension.io/planner.md)
>
> Goal-to-plan generation — produces ready-to-launch prompts

> [card] [Build your first app](https://docs.dimension.io/build-your-first-app.md)
>
> A worked example using these patterns


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.