Progress bar

chart.progress_bar

ProductionBounded custom (Class B)Deterministicstrictfastv1.0.0

No network

Overview

Render deterministic safe progress bars from exact decimal strings. Negative values reject, segments reconcile exactly, trends preserve gaps, stable sorting is explicit, and overflow requires acknowledgement. svg is a complete static, script-free chart. Mark highlight, the dotted guide, and the value panel are not in that SVG, and entry motion, focus, and updates stay inactive there. Pass the entire output.behavior.artifact unchanged to SquillifyChartRuntime.mount(container, artifact, options), then call the returned handle's replay() once to play the entry. A later value change uses update(nextArtifact, {intent}). Injecting svg directly leaves hover and motion off. Interaction is on by default for every host chart: after mount, pointer and keyboard focus open the value panel and the dotted guide. Set behavior.interaction.enabled to false to turn that off. motion.preset accepts only the family's entrance.

Completion arithmetic, segment reconciliation and overflow must be exact and inspectable rather than inferred from bar widths. You provide exact quantities; we return every resolved ratio and safe SVG.

Reliability

Every calculated quantity in itemResults is an exact decimal string; gaps remain gaps, segments reconcile with zero tolerance, and identical input is byte-deterministic. Declared failures: CHART_CAPACITY_EXCEEDED — trigger: the item set cannot fit the requested canvas or the predicted output exceeds the safe inline envelope; retryable: no; unchanged input: will not succeed; next: follow the recovery intent in the error details. CHART_OUTPUT_TOO_LARGE — trigger: the inline SVG byte budget would be exceeded at the requested size and data density; retryable: no; unchanged input: will not succeed; next: follow the recovery intent in the error details. CHART_UNSAFE_OUTPUT — trigger: the finished SVG failed our final safety re-validation (this is on us, not your data); retryable: no; unchanged input: will not succeed; next: contact support with the request id — retrying the same input will not help.

Context footprint

At most 100 items, 12 segments and 32 trend positions per item. A successful call costs 3 execution credits.

When to use it

When progress starts at zero and each item has a positive total.

When the value belongs on an arbitrary min/max scale.

Scope

Note

One to one hundred exact repeated or segmented progress indicators.

Non-goals

Arbitrary bounded gauges
Point-level time-series inspection
Caller-authored SVG

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

generationimage-processing

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call3 credits

File handling

Accepts file_refProduces file_refMax input585.9 KB

How we handle your data

Sensitive output possible

What this means

This skill may receive sensitive content and may return submitted, transformed, extracted, or reformatted content.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response may contain submitted or transformed content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
items	array	Yes	Required 1..100 items with unique id, label, non-negative exact value, positive exact total, optional target/previous, 1..12 exact segments, and a 2..32-position exact-decimal trend preserving null gaps.
orientation	string	No	horizontal\|vertical; default horizontal.
overflow	string	No	reject\|showOverflow; default reject.
sort	string	No	input\|value\|percent with stable input-order ties; omit for input order.
thresholds	array	No	Optional 1..12 ordered non-overlapping normalized exact ranges with id, label, min, max and meaning; omit for unclassified status.
labels	object	No	Closed item\|value\|total\|percent\|remaining\|overflow\|target\|delta\|status booleans plus auto\|inside\|outside placement; item and percent default visible.
valueFormat	object	No	Closed deterministic raw-unit format for values, totals, targets, deltas and segments; omit for two fixed decimal digits.
percentFormat	object	No	Closed deterministic percent format; style must be percent; defaults to two decimals.
trend	object	No	Closed visible, showGaps and optional non-negative exact reference properties; omit for visible=true, showGaps=true and no reference line.
localization	object	No	Closed object with locale string; omit for locale en. It affects visible formatting only.
title	string	No	Optional bounded visible title; omit to generate the accessible progress title.
subtitle	string	No	Optional bounded visible subtitle; omit to render no subtitle.
caption	string	No	Optional editorial caption up to 240 code points; omit to render no caption.
source	string	No	Optional editorial source up to 240 code points; omit to render no source.
period	string	No	Optional editorial period up to 120 code points; omit to render no period.
layout	object	No	Closed margin, plotPadding and insufficientSpace properties; omit for automatic margin, profile padding and reject-on-insufficient-space.
accessibility	object	No	Closed title and description string properties plus boolean patterns; omit to use generated accessibility text with patterns=false.
behavior	object	No	Optional bounded host behavior request; omitted means static SVG. svg is a complete static, script-free chart. Mark highlight, the dotted guide, and the value panel are not in that SVG, and entry motion, focus, and updates stay inactive there. Pass the entire output.behavior.artifact unchanged to SquillifyChartRuntime.mount(container, artifact, options), then call the returned handle's replay() once to play the entry. A later value change uses update(nextArtifact, {intent}). Injecting svg directly leaves hover and motion off. Interaction is on by default for every host chart: after mount, pointer and keyboard focus open the value panel and the dotted guide. Set behavior.interaction.enabled to false to turn that off. motion.preset accepts only the family's entrance.
width	integer	No	Canvas width in pixels, 100..1600 (optional; default 800). Outside that range the request is refused as invalid input rather than clamped. The ceiling is the size a chart is read at — a full-HD dashboard or a report page; beyond it the canvas stops being what limits how much fits, and type sized for the canvas is illegible once the export is displayed smaller. It applies per side, so a tall portrait canvas for a long horizontal ranking is allowed.
height	integer	No	Canvas height in pixels, 100..1600 (optional; default 480). Outside that range the request is refused as invalid input rather than clamped. The ceiling is the size a chart is read at — a full-HD dashboard or a report page; beyond it the canvas stops being what limits how much fits, and type sized for the canvas is illegible once the export is displayed smaller. It applies per side, so a tall portrait canvas for a long horizontal ranking is allowed.
theme	string	No	Visual language: basic, modern or squillify (optional; default squillify). An unregistered value is rejected with the registered names listed — we never substitute silently.
surface	string	No	Surface the theme renders on: dark or light (optional; default light).
density	string	No	How tightly the chrome is packed: compact, standard or spacious (optional; default standard). Density scales spacing only — it never lowers a legibility minimum.
visualProfile	string	No	What the SVG promises about the host font: portable or certified (optional; default portable). The default is layout-deterministic and tolerates substitution; certified refuses text the certified metrics cannot fully measure.
style	object	No	Optional bounded paint and typography styling; omit it to use the selected theme defaults. text.size is expressed in normalized design pixels at an 800-pixel reference width, so equivalent roles match at equal CSS width. It never changes data or accessibility. 'contract' selects the published semantics. 'tokens' sets design tokens; 'rules' applies typed properties to a role and optional series/category facets; 'palette' accepts a digest-checked palette; 'css' is a bounded post-layout stylesheet. The styleCapabilities section publishes this family's accepted roles, properties and copyable examples. For Bar, target one mark with role 'bar' plus seriesIndex and categoryIndex; categoryIndex alone targets that category across series. A minimal rule is {"target":{"role":"bar"},"set":{"paint.fill":"#2563eb"}}. Unsupported typed rules are refused; unsupported CSS is dropped and reported. Do not discover the grammar through trial calls: style validation failures are currently billable. Before calling, read this contract's styleSurface and styleCapabilities sections for the complete rule shape, accepted roles and properties, limits, and copyable examples.
output	object	No	Output scoping (optional). Nested key output.idNamespace ([a-z][a-z0-9-]{0,31}) is prefixed onto every generated element id when several charts share one host document; omit for a standalone chart. An invalid namespace is rejected.

Output schema

Field	Type	Required	Description
svg	string	Yes	Final script-free canonical SVG. svg is a complete static, script-free chart. Mark highlight, the dotted guide, and the value panel are not in that SVG, and entry motion, focus, and updates stay inactive there. Pass the entire output.behavior.artifact unchanged to SquillifyChartRuntime.mount(container, artifact, options), then call the returned handle's replay() once to play the entry. A later value change uses update(nextArtifact, {intent}). Injecting svg directly leaves hover and motion off. Interaction is on by default for every host chart: after mount, pointer and keyboard focus open the value panel and the dotted guide. Set behavior.interaction.enabled to false to turn that off. motion.preset accepts only the family's entrance.
width	integer	Yes	Resolved rendered canvas width in pixels.
height	integer	Yes	Resolved rendered canvas height in pixels.
viewBox	string	Yes	Rendered coordinate system.
itemResults	array	Yes	Array of 1..100 resolved-order item objects with id, inputIndex, exact value, total, ratio, remaining, overflowAmount, optional target/delta/segments/trend, and status.
renderSummary	object	Yes	Always-present bounded scalar summary of the resolved orientation, item, segment and trend-position counts actually drawn.
transformationSummary	object	Yes	Always-present bounded report of moved, shortened or hidden labels and the affected counts.
behavior	object	No	HOST_INTERACTIVE manifest, data index, digest-bound artifact and closed plans; present only when behavior is requested. svg is a complete static, script-free chart. Mark highlight, the dotted guide, and the value panel are not in that SVG, and entry motion, focus, and updates stay inactive there. Pass the entire output.behavior.artifact unchanged to SquillifyChartRuntime.mount(container, artifact, options), then call the returned handle's replay() once to play the entry. A later value change uses update(nextArtifact, {intent}). Injecting svg directly leaves hover and motion off. Interaction is on by default for every host chart: after mount, pointer and keyboard focus open the value panel and the dotted guide. Set behavior.interaction.enabled to false to turn that off. motion.preset accepts only the family's entrance.
styleReport	object	No	Always reports the resolved typographyProfile and fontMetrics contract, plus tokensApplied, rulesApplied, typedRulesApplied, typedAssignmentsApplied, rulesDropped, declarationsDropped and, when anything was dropped, a bounded list of reasons.
warnings	array	No	Present when the render succeeded with a known degradation. Each entry is an object with a stable code, a message and details. Every chart can emit FONT_SUBSTITUTION_POSSIBLE under visualProfile 'portable', FONT_GLYPH_UNMEASURED when a code point falls outside the certified metrics, and CHART_STYLE_PARTIALLY_APPLIED when part of your styling was dropped — styleReport then names which part and why. Codes are stable for agent routing. PROGRESS_OVERFLOW_SHOWN reports every exact acknowledged item overflow.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"skillKey":"chart.progress_bar","input":{"items":[{"id":"api","label":"API","value":"72","total":"100"},{"id":"ui","label":"UI","value":"45","total":"100"}]}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("chart.progress_bar", {"items":[{"value":"72","id":"api","label":"API","total":"100"},{"value":"45","id":"ui","label":"UI","total":"100"}]});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
CHART_CAPACITY_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.
CHART_OUTPUT_TOO_LARGE	429	No	A size, quota, rate, or time limit was exceeded.
CHART_UNSAFE_OUTPUT	500	No	The skill encountered an unexpected execution failure.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Arbitrary bounded gauges
Point-level time-series inspection
Caller-authored SVG
A scale not anchored at zero (use chart.gauge)
Detailed trends (use chart.line)
Unbounded task lists

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "chart.progress_bar",
  "input": {
    "items": [
      {
        "value": "72",
        "id": "api",
        "label": "API",
        "total": "100"
      },
      {
        "value": "45",
        "id": "ui",
        "label": "UI",
        "total": "100"
      }
    ]
  }
}

Examples

Two progress items

Inputjson

{
  "items": [
    {
      "value": "72",
      "id": "api",
      "label": "API",
      "total": "100"
    },
    {
      "value": "45",
      "id": "ui",
      "label": "UI",
      "total": "100"
    }
  ]
}

Expected outputjson

{
  "transformationSummary": {
    "applied": false,
    "operations": [],
    "affectedCategoryCount": 0,
    "affectedPointCount": 0,
    "affectedLabelCount": 0
  },
  "viewBox": "0 0 800 480",
  "height": 480,
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"800\" height=\"480\" viewBox=\"0 0 800 480\" role=\"img\" class=\"sq-chart sq-chart--progress-bar sq-family--kpi-status sq-theme--squillify sq-surface--light sq-density--standard\" data-sq-style-contract=\"CHART_STYLE@1\" data-sq-chart=\"progress-bar\" data-sq-family=\"kpi-status\" data-sq-theme=\"squillify\" data-sq-theme-version=\"1\" data-sq-surface=\"light\" data-sq-density=\"standard\" data-sq-a11y-detail=\"full\" aria-labelledby=\"sq-c6a86e28e79e-title-1 sq-c6a86e28e79e-desc-2\"><title id=\"sq-c6a86e28e79e-title-1\">Progress for 2 item(s)</title><desc id=\"sq-c6a86e28e79e-desc-2\">API 72.00 of 100.00; UI 45.00 of 100.00</desc><style>.sq-chart{--sq-chart-axis:#c9d1df;--sq-chart-font-family:'Squillify Mono', 'IBM Plex Mono', monospace;--sq-chart-grid:#d8dee9;--sq-chart-surface:#ffffff;--sq-chart-text-muted:#667085;--sq-chart-text-primary:#101828;--sq-series-1:#2563eb;--sq-series-2:#6d5ce7;--sq-series-3:#168a5b;--sq-series-4:#c45412;--sq-series-5:#d92d20;--sq-series-6:#667085;font-family:var(--sq-chart-font-family);font-weight:500;}.sq-chart .sq-background{fill:var(--sq-chart-surface);}.sq-chart .sq-category-label{fill:var(--sq-chart-text-muted);}.sq-chart .sq-bar[data-sq-palette-index=\"0\"]{fill:var(--sq-series-1);}.sq-chart .sq-bar[data-sq-palette-index=\"1\"]{fill:var(--sq-series-2);}</style><defs><linearGradient id=\"sq-c6a86e28e79e-fh-0\" gradientUnits=\"objectBoundingBox\" x1=\"0\" y1=\"0\" x2=\"1\" y2=\"0\"><stop offset=\"0\" stop-color=\"#f0f5fe\"/><stop offset=\"0.54\" stop-color=\"#ffffff\"/></linearGradient></defs><rect x=\"0\" y=\"0\" width=\"800\" height=\"480\" fill=\"#ffffff\" class=\"sq-background\" data-sq-role=\"background\"/><rect x=\"0\" y=\"0\" width=\"800\" height=\"60\" fill=\"url(#sq-c6a86e28e79e-fh-0)\" class=\"sq-brand-band\"/><rect x=\"0\" y=\"60\" width=\"800\" height=\"420\" fill=\"#f8fafd\" class=\"sq-plot\" data-sq-role=\"plot\"/><line x1=\"0\" y1=\"60\" x2=\"800\" y2=\"60\" stroke=\"#c9d1df\" stroke-width=\"1\" class=\"sq-card-frame\"/><text x=\"12\" y=\"16\" font-size=\"10\" text-anchor=\"start\" font-family=\"&#39;Squillify Mono&#39;, &#39;IBM Plex Mono&#39;, monospace\" font-weight=\"600\" letter-spacing=\"1.2\" textLength=\"58\" lengthAdjust=\"spacing\" fill=\"#2563eb\" class=\"sq-caption\" data-sq-role=\"caption\">PROGRESS</text><rect x=\"0.5\" y=\"0.5\" width=\"799\" height=\"479\" fill=\"none\" stroke=\"#c9d1df\" stroke-width=\"1\" class=\"sq-card-frame\"/><text x=\"12\" y=\"249\" font-size=\"10\" text-anchor=\"start\" font-family=\"&#39;Squillify Mono&#39;, &#39;IBM Plex Mono&#39;, monospace\" font-weight=\"500\" textLength=\"19\" lengthAdjust=\"spacing\" fill=\"#101828\" class=\"sq-category-label\" data-sq-role=\"category-label\" data-sq-category-index=\"0\">API</text><rect x=\"202\" y=\"235.42\" width=\"538\" height=\"20.16\" rx=\"10.08\" fill=\"#c9d1df\" class=\"sq-bar\" data-sq-role=\"progress-track\" data-sq-target-key=\"t-pi-f1429e7045a031ba\" data-sq-category-index=\"0\"/><rect x=\"202\" y=\"235.42\" width=\"387.36\" height=\"20.16\" rx=\"10.08\" fill=\"#2563eb\" class=\"sq-bar\" data-sq-role=\"progress-value\" data-sq-target-key=\"t-pv-4538e7dfb6875260\" data-sq-category-index=\"0\" data-sq-palette-index=\"0\" data-sq-emphasis=\"focus\" data-sq-meaning=\"info\"/><text x=\"748\" y=\"249\" font-size=\"10\" text-anchor=\"start\" font-family=\"&#39;Squillify Mono&#39;, &#39;IBM Plex Mono&#39;, monospace\" font-weight=\"500\" textLength=\"37\" lengthAdjust=\"spacing\" fill=\"#101828\" class=\"sq-value-label\" data-sq-role=\"value-label\" data-sq-category-index=\"0\">72.00%</text><text x=\"12\" y=\"297\" font-size=\"10\" text-anchor=\"start\" font-family=\"&#39;Squillify Mono&#39;, &#39;IBM Plex Mono&#39;, monospace\" font-weight=\"500\" textLength=\"13\" lengthAdjust=\"spacing\" fill=\"#101828\" class=\"sq-category-label\" data-sq-role=\"category-label\" data-sq-category-index=\"1\">UI</text><rect x=\"202\" y=\"283.42\" width=\"538\" height=\"20.16\" rx=\"10.08\" fill=\"#c9d1df\" class=\"sq-bar\" data-sq-role=\"progress-track\" data-sq-target-key=\"t-pi-e2b97dfab1221d27\" data-sq-category-index=\"1\"/><rect x=\"202\" y=\"283.42\" width=\"242.1\" height=\"20.16\" rx=\"10.08\" fill=\"#6d5ce7\" class=\"sq-bar\" data-sq-role=\"progress-value\" data-sq-target-key=\"t-pv-e543082b56bc9de2\" data-sq-category-index=\"1\" data-sq-palette-index=\"1\" data-sq-emphasis=\"focus\" data-sq-meaning=\"info\"/><text x=\"748\" y=\"297\" font-size=\"10\" text-anchor=\"start\" font-family=\"&#39;Squillify Mono&#39;, &#39;IBM Plex Mono&#39;, monospace\" font-weight=\"500\" textLength=\"37\" lengthAdjust=\"spacing\" fill=\"#101828\" class=\"sq-value-label\" data-sq-role=\"value-label\" data-sq-category-index=\"1\">45.00%</text></svg>",
  "width": 800,
  "itemResults": [
    {
      "value": "72",
      "status": {
        "id": "unclassified",
        "label": "Unclassified",
        "meaning": "info"
      },
      "total": "100",
      "remaining": "28",
      "inputIndex": 0,
      "overflowAmount": "0",
      "id": "api",
      "ratio": "0.72"
    },
    {
      "value": "45",
      "status": {
        "id": "unclassified",
        "label": "Unclassified",
        "meaning": "info"
      },
      "total": "100",
      "remaining": "55",
      "inputIndex": 1,
      "overflowAmount": "0",
      "id": "ui",
      "ratio": "0.45"
    }
  ],
  "renderSummary": {
    "skill": "chart.progress_bar",
    "variant": "repeated",
    "orientation": "horizontal",
    "itemCount": 2,
    "markCount": 4
  }
}

Segmented release with trend gap