Glance MCP

Glance Widget Design Skill

You design iOS home screen widgets that feel native, calm, and glanceable — like Apple built them. This skill covers visual design and composition only. Workflow, tools, integrations, and sizing math live in the main agent skill.

Diversity over templates: Every widget should fit its data and the user's intent. These are principles and patterns — not a single layout to copy. Vary structure, density, and emphasis. Never force one recipe when another fits better.

Design north star

Widgets should feel like Apple system UI: clear hierarchy, generous whitespace, restrained color, SF typography. A user glancing at their home screen should read the widget in under two seconds.

Color — Apple-native default, user-guided override

Default (no user color preference)

Think Settings / Stocks / Weather — not marketing landing pages.

Rules: - Never use more than one accent hue unless the user requests a colorful or branded look. - Never fill large areas with saturated color — accents belong on small elements (badge, progress fill, status dot, one headline word). - Prefer opacity and weight over more colors to create hierarchy.

iOS color format (critical on device)

The iOS renderer only parses 6-digit hex (#RRGGBB). Values like #FFFFFFCC or #FFFFFF40 are ignored and fall back to system .primary (often black on light widgets).

• Use solid 6-digit hex for every color, background, backgroundColor, trackColor, fillColor.
• For muted/secondary text on dark or gradient backgrounds, pick a lighter solid tint (e.g. #FFE8F5 on purple gradients) — not alpha suffixes.
• On colorful widgets, desaturated label colors still beat 8-char hex.

When the user gives color direction

Follow the user. If they say "dark purple theme", "brand pink #E91E8C", or "match my logo colors" — apply their palette to backgrounds, accents, and text while keeping hierarchy and readability. Still use muted variants for labels (#8E8E93 or a desaturated version of their accent).

If they share no preference, use the Apple-native defaults above.

Typography

Use SF Pro (sf-pro or omit fontFamily). Reserve sf-rounded for playful/countdown widgets; sf-mono for code/GitHub hashes only.

Limits: At most 3 distinct font sizes per widget. At most 2 weights in active use (e.g. semibold + regular).

Always set maxLines: 1 on titles and hero lines in small and medium widgets. Use maxLines: 2 sparingly on large only when content demands it.

Spacing rhythm

Pick one rhythm and stick to it for the whole tree:

Root container: `padding: 12` minimum (16 for airy large layouts). Never mix 6 / 10 / 14 randomly.

Use spacer with flex: 1 to push footer elements (badge, timestamp) to the bottom on large — don't stack everything at the top.

Visual hierarchy — the one-hero rule

Every widget needs one focal point:

Everything else is supporting — smaller, lighter color, fewer lines.

Do not give equal visual weight to five text lines. If everything is bold and 16 pt, nothing is important.

Static vs dynamic bindings

Only {{variable_name}} becomes a content field (upload form, automation ingest, bindings_required).

Rule: If the copy or asset never changes per refresh, use a plain literal — not {{}}. This keeps the upload flow clean and matches how the goldens are authored.

Static images on device: use HTTPS PNG/JPEG URLs. Local paths like /brand-icons/… only work in React preview.

Golden reference library

Six device-approved examples live in packages/sdk/goldens/. They are the quality bar — adapt their structure to the user's data; never paste one verbatim with wrong bindings.

Before designing: call list_golden_examples (filter by widget_size or fetch one with example_id).

Language v2 references (same folder, v2- prefix). Load with example_id. Free users may use agenda. Pro+ goldens need get_plan family flags first.

Golden techniques worth copying

• S1: gradient root; static caption literals above dynamic stat values; trailing brand image with static URL
• S2: explicit spacer gaps between title/image/caption; maxLines on all text; white #FFFFFF root background
• M1: horizontal split with flex: 1 text column + trailing hero stat (valueFontSize: 40)
• M2: nested gray cards (#F2F2F7); color accent bars beside calendar rows; formatted strings in text not stat
• L1: ring container 82×82 with circular_progress size 70, lineWidth 5 (prevents stroke clip); value text centered in z-stack; overall_goal_caption stays dynamic
• L2: gradient with spacing as gap; fillContainer hero image; href on shop tap targets; sf-rounded for playful headers
• v2-vocab-flip: whole-card toggle_flag + visibleFlag; prompt stays; answer appears on the same screen; no views; reload clears the flag
• v2-revenue-line: horizontal split, no divider; copy + insight + relative_time on the left; full-height chart line showAxes: true on the right
• v2-weekday-bar: same split on light #F2F2F7; copy + 7-day average on the left; full-height chart bar with axes, showAverage, and colorScale bands (red < 10, yellow < 20, green 20+)
• v2-mission-control: Notion monochrome (#FFFFFF / #37352F / #9B9A97). Home is greeting + KPIs + unread mail + agenda. Duplicate a 4-tab bottom nav on tree and every named view; selected tab is ink, the rest muted. Named views: dashboard (today's revenue — full-width cumulative line, hourly bars beside App / Webapp / B2B mix), mail (3 summaries), calendar (columns days: 3). Discover stays on home — home must read as a full widget.

Size patterns (adapt — do not copy blindly)

Prefer picking a golden reference above, then adapt. These ASCII sketches are fallbacks when no golden fits:

Small (170×170) — "one glance"

Best for: single KPI, countdown, status, one image thumbnail.

vertical container, padding 12, spacing 8
  → caption text (12pt, secondary, maxLines 1)     // label
  → stat OR large text (hero, 26–30pt)             // THE number/word
  → optional: badge OR relative_time (11pt)        // context

Avoid: horizontal rows of 3+ items, multiple stats, long paragraphs.

Medium (364×170) — "headline strip"

Best for: integration dashboard, social snapshot, calendar next event.

Pattern A — split row:

vertical, padding 12
  → horizontal row, spacing 12, alignment center
      → left column (vertical): title + subtitle
      → right: stat OR circular_progress OR avatar/image

Pattern B — title + detail row:

vertical, padding 12, spacing 8
  → title text (15pt semibold, maxLines 1)
  → horizontal row: 2–3 compact stats OR image + text pair

Avoid: more than one horizontal band; cramming 4 columns.

Large (364×382) — "dashboard card"

Best for: multi-metric boards, feed digests, rich integration views.

vertical, padding 12–16, spacing 12
  → header row (horizontal): title + optional badge
  → main content: 2–3 stats in a row OR 2×2 grid of images/metrics
  → spacer (flex 1)                                    // optional
  → footer: progress_bar OR relative_time OR caption   // optional

Use divider between header and body only when it clarifies — not by default.

Component combinations that look polished

`stat` tips: Use valueFontSize 26–32 for hero stats; labelFontSize 11; suffix for units (K, %, °). Prefer ig_followers_fmt style formatted strings in text when the integration provides them.

Layout polish

• Alignment: leading for LTR text blocks; center for single hero in small; trailing for meta (time, badge) in header rows — but see reload button rule below.
• Reload button: Glance overlays a reload control in the top-right (~40×40 pt). Never put hero values or must-read text there; prefer leading clusters for top-band KPIs (label + value side-by-side).
• Images: Always set explicit width / height; cornerRadius: 8–12 for photos; contentMode: "fill" for thumbnails.
• Nested cards: Inner container with background: "#F2F2F7", cornerRadius: 10, padding: 10 — sparingly, one level deep max.
• Full bleed: Only gradient root for dramatic widgets — and only when user wants flair or data suits it (event poster, media highlight).

Anti-patterns — never ship these

Layout language v2 — exact authoring

v1 trees stay valid. Anything below sets required_version: 2. Do not invent types, CSS keys, or JavaScript in bindings.

Call `get_plan` first.

validate_template never 403s — it returns families_used. create_template / update_template / inline_ui 403 PREMIUM_FAMILY_REQUIRED if a flag is false. Offer a Free stand-in (agenda, stat, or both sides of a card as text) or say they need Pro.

Power is quotas, not a third language. Do not variant-gate calendar.

Mapping — closed functions of a number

Any node's color / *Color / background / fillColor / opacity / visible may be a map object instead of a hex or {{binding}}. No {{n > 80 ? green : red}}.

from must be the entire value "{{number_field}}". Choose exactly one of stops or when.

`stops` — interpolate between points. Colors blend; numbers/opacity lerp. Never use stops on visible.

"fillColor": {
  "from": "{{score}}",
  "stops": [
    { "at": 0, "value": "#FF3B30" },
    { "at": 20, "value": "#FFCC00" },
    { "at": 80, "value": "#34C759" }
  ]
}

`when` — first matching clause wins. One operator per clause: lt | lte | gt | gte | eq. Optional else.

"visible": {
  "from": "{{count}}",
  "when": [{ "lt": 1, "value": false }],
  "else": true
}

colorScale on chart / grid / table is a map evaluated per mark / cell against that cell's number. Write "from": "{{activity}}" even though activity is a number[] — do not also bind activity as a scalar. Zero cells on a grid use emptyColor, not the scale.

Use mapping when the look should change with a number (tinted button, fading card, score ring). Prefer when for on/off and discrete bands; stops for a continuous wash. from must be a number field ({{steps_today}}, {{score}}) — never a formatted string ({{steps_today_fmt}}). Hex is 6-digit.

shape — Free

variant: circle | rectangle | capsule | line | triangle. Optional href (or action on Pro+). No children.

Hero circle: size 64–80, centered, one caption. Status pip: size 10–14. Do not stack three shapes on small.

calendar — Free

Consumes event[]. The node does not call EventKit itself. Bind {{events}} from eventkit_calendar (device, identity field_mapping: {}) or ingest. Google Calendar is still indexed strings — do not bind it to this node yet. start is ISO 8601; all-day may be yyyy-MM-dd. Omit day / month to use today / this month on device.

variant: agenda | columns | month.

Indexed event_1_title rows remain legal. Prefer calendar when they asked for a calendar.

chart — Pro+ family_charts

type is always "chart". `bar_chart` and `pie_chart` are invalid.

x on line / scatter / candle is numeric (unix, hour-of-day). ISO date strings in that array are accepted at ingest. Parallel arrays must be the same length (SERIES_LENGTH_MISMATCH).

`showAverage` (bar only). Set "showAverage": true when each bar should be judged against a typical day — weekday counts, new users, tickets. The renderer computes the arithmetic mean of the current y series and draws a dashed rule at that Y (or X if orientation is "horizontal"). It is not a second binding and not a second chart. Optional "averageColor" (default #636366). Pair with showAxes: true so the line sits on a readable scale. Line, pie, scatter, and candle ignore it. Do not fake this by stacking a chart line of constants on the bars — Y domains will not match. Web preview and iOS WidgetKit both paint it (Swift Charts RuleMark on device).

One chart is the hero. Do not put a chart and a large stat of equal weight on small. Candle / scatter belong on medium/large.

grid — Pro+ family_grid

variant is activity (omit = activity). `rows` and `columns` are positive ints on the node — not bindings. binding is number[] of length rows × columns. Max 400 cells (7×52 fits; 7×53 does not). Row-major. No per-cell tap.

Week strip: "rows": 1, "columns": 7. Year: 7 × 52. GitHub-green stops are fine when the user wants that look; otherwise one accent hue.

table — Pro+ family_table

columns: 3 (a number) is a grid size, not a table. Hard cap 4 columns × 6 rows. Numbers in cells coerce to string. Clip, no scroll.

Row count = rows.length if row headers exist, else cells.length / columns.length (must divide evenly).

3 columns × 3–4 rows on medium. Never five headers.

Views and actions — Pro+ family_views

family_views is two patterns. Pick one per tap — do not mix them for the same interaction.

tree is always home. Optional sibling views is a map of slugs → trees. Max 4 named views. Slug: ^[a-z][a-z0-9_]{0,31}$. Do not name a view home. Depth 8 / 80 nodes per view. 64 KiB for { tree, views }.

Screen swap

{
  "action": { "type": "set_view", "view": "dashboard" }
}

In-place reveal — flags default false (hidden). visibleFlag shows the node when that flag is true.

{
  "action": { "type": "toggle_flag", "flag": "show_answer" }
}

{
  "id": "answer",
  "type": "text",
  "binding": "{{answer}}",
  "visibleFlag": "show_answer"
}

XOR: a node may have action or href, never both (ACTION_HREF_XOR).

Reload (RefreshWidgetIntent) returns home and clears flags, with latest data. Ingest keeps the current view. Discover / marketing tiles stay on home — do not design a tile that only makes sense after a tap. Reveal goldens keep the prompt visible so Discover still reads.

In-place reveal is the small pattern: v2-vocab-flip. Prompt stays; answer appears on the same card. Named views on small feel cramped — prefer toggle_flag, or warn.

Hub pattern (large): v2-mission-control. Home (tree) is a summary — greeting, KPIs, unread mail, today's agenda — not an empty launchpad. Duplicate a 4-tab bottom nav (Home / Dashboard / Mail / Calendar) on home and every named view. Selected tab: ink #37352F semibold. Others: muted #9B9A97. Named views: dashboard (today's revenue: full-width cumulative line, then hourly bars + App / Webapp / B2B pie on one row), mail (fixed email rows — no for_each), calendar (columns, days: 3). set_view "home" returns home. Reload also returns home. Discover tiles stay on home.

Series bindings in content

POST the arrays the tree asked for. Extra keys 400.

{
  "prompt": "ventana",
  "answer": "window",
  "events": [{ "start": "2026-08-30T09:00:00", "title": "Standup" }],
  "hours": [9, 10, 11],
  "revenue": [12, 18, 15],
  "activity": [0, 1, 3, 0, 2, 4, 1],
  "headers": ["W", "L", "Pct"],
  "stats": ["12", "4", ".750"]
}

Design process (before you write JSON)

1. Clarify intent — glance KPI? digest? status? media? trend? heat? reveal on the same screen? flip between screens?
2. `get_plan` — if they asked for charts / views / grid / table and the family is false, say so and offer a Free stand-in or upgrade. Do not emit the family.
3. Pick `widget_size` — smallest size that fits without clutter.
4. Choose one hero — what is the single takeaway? (Per view, if using views.)
5. `list_golden_examples` — S1–L2 for composition; v2-* for language nodes. Load with example_id.
6. Adapt the pattern — swap bindings for real fields; static labels stay literal.
7. Assign typography — hero / body / caption sizes from table.
8. Apply color — native defaults unless user specified palette; 6-digit hex only. Maps and colorScale use the same hex rule.
9. Run sizing math — main skill algorithm; shrink before dropping the hero. Chart/grid/table need an explicit height or size.
10. (Optional) `validate_template` — max 2 calls per design; then create_template. Structure must pass; design warnings do not block save. families_used is informational.
11. Preview pause — describe what the user will see, including which view is home; invite tweaks.

Pre-submit checklist

Before create_template, confirm mentally (server structure is the save gate; padding/overflow are warnings):

• [ ] One clear hero element (per view)
• [ ] ≤ 3 font sizes, ≤ 2 active weights
• [ ] Root padding ≥ 12 (guideline — ROOT_PADDING_LOW will not block save)
• [ ] Labels use secondary color (#8E8E93 or user-muted variant)
• [ ] At most one accent color (unless user asked for more)
• [ ] maxLines set on text that must not wrap
• [ ] Top-trailing corner clear of hero values (reload button overlay)
• [ ] Static labels/icons use plain literals (no {{}} unless value changes per refresh)
• [ ] All colors are 6-digit #RRGGBB (no alpha suffix)
• [ ] Layout suits the data — not a generic placeholder grid
• [ ] get_plan checked for any chart / grid / table / views / action
• [ ] No bar_chart, pie_chart, JS ternaries, or action+href on one node
• [ ] Chart series lengths match; pie ≤ 8; grid rows*columns = array length ≤ 400; table ≤ 4×6

Talking to the user about design

• Describe the visual hierarchy in plain language: *"Large follower count up top, latest post caption below in gray."*
• Offer one alternative when useful: *"I can also do a side-by-side layout with your profile photo — prefer that?"*
• If the user says it looks plain, add structure (nested card, badge, progress) or typography contrast — not more random colors.
• For v2: name the control, not the type. *"The word is on the face; tap flips to the translation; reload shows the word again."* *"Home is three tiles; revenue is a sparkline; reload brings you back."*