dashboard-design

Dashboard Design

Use when asked to build or edit a dashboard (the task says "build a self-contained HTML dashboard"). You are a coding agent building a small, beautiful BI web app that renders inside DeepSQL — not filling in a rigid template.

The runtime you build against

Your output is a shell block, then one widget block per KPI/chart — not a single HTML document. The parent assembles them (each widget's markup+script drops into its own [data-widget=id] slot in the shell) and renders each widget into the live canvas the moment its block closes, well before your whole turn finishes — so the user watches the dashboard build piece by piece instead of staring at a blank screen for the whole generation. Both kinds of block run inside the SAME sandboxed iframe with a bridge already injected:

deepsql.connectionId                      // this connection's id (string)
await deepsql.query("SELECT ...")         // -> { columns: string[], rows: any[][] }  (read-only, access-scoped)
deepsql.ready(fn)                          // runs fn() once the bridge is live (use this to kick off loading)

// Charts — ALWAYS use these instead of hand-writing SVG. Built-in hover tooltips
// (show the value on mouse-over), number formatting, sparse axis labels, a
// graceful "No data" empty state, and a corner expand button that opens the
// same chart larger in an overlay — all automatic, nothing to wire yourself.
// Pass the deepsql.query result straight in, or [{label,value}] / [[label,value]].
// First column = label, second = value (or opts.labelKey/valueKey).
// opts: { valueFormat(fn), height, color, emptyText, title }.
deepsql.charts.bar(elOrSelector, data, opts)     // rankings, counts by day
deepsql.charts.line(elOrSelector, data, opts)     // trends over time (area+line)
deepsql.charts.donut(elOrSelector, data, opts)    // share/composition (with legend + %)
deepsql.charts.format(n)                           // human number formatter

Chart sizing and the expand control are handled by the runtime — do not build your own. Height is fixed regardless of container width (a chart in a wide card never balloons), and every chart already gets a corner "expand" button that opens a larger re-render in an overlay — this is exactly the kind of per-chart chrome that's tempting to hand-roll and easy to get inconsistent across widgets, so it's built into deepsql.charts.* once instead. Pass opts.title (the chart's plain-business-language heading) so the expanded overlay has something to show as its title — do not add your own zoom/expand/fullscreen button, modal, or lightbox; one already exists per chart.