Layouts

Island Pulse renders four distinct layouts on the Lock Screen and Dynamic Island. Pick the one that matches the shape of your data. All layouts share the same branding fields (icon, accentColor) and the same status field.

Default

The all-purpose layout. Use it for any text-based status update where a single message is enough.

9:41

deploy-api

Island Pulse now

Deployed to production in 38s

deploy-api SUCCESS

Default layout, Lock Screen card

Fields

Field	Required	Notes
`message`	Yes	Main body text. Wraps to two lines on the Lock Screen.
`status`	No	`running` (default), `success`, or `failed`. Controls the status indicator color.
`metric`	No	Short value (up to 6 chars, e.g. `Step 2/3`, `98%`) shown in the Dynamic Island compact view. Without it the island shows a status marker instead.
`icon`	No	SF Symbol name, e.g. `bolt.fill`, `checkmark.circle`.
`accentColor`	No	Hex code (`#00FFDD`) or CSS color name (`green`).

{
  "job_id": "deploy-api",
  "layout": "default",
  "message": "Deployed to production in 38s",
  "status": "success",
  "icon": "checkmark.circle.fill",
  "accentColor": "#00FF88"
}

Progress

Best for long-running tasks where showing progress matters, deployments, data migrations, backup jobs.

9:41

Database Migration

Island Pulse now

Database Migration Step 2/5

Migrating users table…

Progress layout, showing 40% completion

Fields

Field	Max (no scale)	Max (with scale)	Notes
`metric`	10 chars	15 chars	Short status such as `42%` or `Step 2/5`. Shown in the Dynamic Island (compact and expanded).
`message`	40 chars	80 chars	Footer text below the progress bar.
`progress`	-	-	Float `0.0`–`1.0`. Pass `0`–`100` and it auto-normalizes.

The card title comes from title. Keep job_id stable for routing, and use a human-readable title for display.

{
  "job_id": "database-migration",
  "title": "Database Migration",
  "layout": "progress",
  "message": "Migrating users table…",
  "metric": "Step 2/5",
  "progress": 0.4,
  "status": "running",
  "accentColor": "#00CFFF"
}

Send a final update with progress: 1.0 and status: "success" to show the bar full and the job complete:

{
  "job_id": "database-migration",
  "title": "Database Migration",
  "layout": "progress",
  "message": "Migration complete. 1.2M rows processed.",
  "metric": "Done",
  "progress": 1.0,
  "status": "success"
}

Score

A hero-metric layout. Use it when one number is the whole story, a price, a count, a load percentage.

9:41

$48,210

Island Pulse now

+4.2%

$48,210

Monthly Recurring Revenue

Score layout, hero metric with trend badge

Fields

Field	Max (no scale)	Max (with scale)	Notes
`metric`	8 chars	16 chars	Large hero text. Automatically shrinks if over 12 chars.
`message`	20 chars	45 chars	Descriptive label. Wraps to two lines.
`secondaryMetric`	10 chars	10 chars	Small badge in the top-right corner, e.g. `+12%`, `▲ 3`.

{
  "job_id": "mrr-live",
  "title": "MRR Live",
  "layout": "score",
  "metric": "$48,210",
  "message": "Monthly Recurring Revenue",
  "secondaryMetric": "+4.2%",
  "status": "running",
  "accentColor": "#00FF88"
}

Another common use, server load or error rate:

{
  "job_id": "p99-latency",
  "title": "API Latency",
  "layout": "score",
  "metric": "142ms",
  "message": "p99 response time",
  "secondaryMetric": "HEALTHY",
  "status": "running",
  "icon": "server.rack"
}

Sports

A dual-metric layout for any head-to-head comparison, scores, A/B splits, team dashboards.

9:41

3 – 1

Island Pulse now

3 Home

FINAL

1 Away

Sports layout, dual score with status badge

Fields

Field	Max (no scale)	Max (with scale)	Notes
`metricA`	3 chars	6 chars	Left large score.
`metricB`	3 chars	6 chars	Right large score.
`subA`	6 chars	10 chars	Label under `metricA`, e.g. team name.
`subB`	6 chars	10 chars	Label under `metricB`.
`secondaryMetric`	8 chars	12 chars	Center badge, e.g. `FINAL`, `Q3`, `90+4'`.

{
  "job_id": "game-score",
  "title": "Game Score",
  "layout": "sports",
  "metricA": "3",
  "metricB": "1",
  "subA": "Home",
  "subB": "Away",
  "secondaryMetric": "FINAL",
  "status": "success"
}

Works equally well for non-sports comparisons like A/B test results or split revenue metrics:

{
  "job_id": "ab-test",
  "title": "A/B Test",
  "layout": "sports",
  "metricA": "4.2%",
  "metricB": "3.8%",
  "subA": "Variant A",
  "subB": "Variant B",
  "secondaryMetric": "LIVE",
  "status": "running",
  "accentColor": "#AA88FF"
}

What shows where

Every layout renders in three places: the Lock Screen card, the Dynamic Island compact pill (what you always see), and the expanded island (long press).

Layout	Lock Screen	Island, compact (left / right)	Island, expanded
Default	Icon, title, status text, `message`	Icon / `metric`, or a status marker (● running, `OK`, `FAIL`)	Icon, title, `metric` (or a DONE / FAILED pill once finished), `message` (up to 3 lines)
Progress	Icon, title, progress bar, `message`	Progress ring / `metric` (or the percent from `progress`)	Title, `metric`, progress bar, `message`
Score	Icon, title, `secondaryMetric` badge, large `metric`, `message`	Icon / `metric`	Large `metric`, title, `secondaryMetric` badge, `message`
Sports	Icon, title, `metricA` vs `metricB` with `subA` / `subB`, `secondaryMetric` badge in the middle, `message`	`metricA` / `metricB`	`metricA` and `metricB` with `subA` / `subB`, `secondaryMetric` badge in the middle, `message`

Island columns need app version 1.3 or later. Earlier versions show only the icon and metric in the compact island (a placeholder when there is no metric), and the expanded view shows the title, status and message. The Lock Screen cards are unchanged since 1.0.
The icon turns green on success and red on failed. Your accentColor applies while the job is running.
Compact slots fit about 4–6 characters. Longer values shrink to fit (for example 287/10).
status is written out on the Lock Screen only for the Default layout. Everywhere else it shows as colour and, once finished, a marker.
If a layout’s fields are missing (a sports update without metricA and metricB), the island falls back to the Default behaviour.
Every update replaces the whole state, so send layout and the score fields on every update, not only the first.

Branding fields (all layouts)

These fields work on every layout:

Field	Notes
`icon`	Any SF Symbol name. Browse the full set in Apple’s SF Symbols app.
`accentColor`	Hex (`#FF5500`) or CSS color name (`orange`, `green`, `red`). Tints the icon and accent elements.

If you omit accentColor, the app falls back to the user’s chosen default accent in Island Pulse settings.