Compose a dashboard page

Explore the data and work out which questions the page answers first. At the start of dashboard design, follow the storytelling default, choose a layout and style, then components and, optionally, an expert. Reuse choices established by an existing app or a supplied reference design. Shared sizes are in Tokens and thresholds. App limitations records findings to recheck against the installed package.

Read the layer before you build

Answer these from the layer before choosing objects, and write the answers into the page brief:

1. Grain. For each measure, what one row is and whether the measure can be summed above it; read item.description (see Look every field up by name).
2. Dates. Whether there is a date field at all, and its first and last value. A snapshot has no trend or comparison; historical data needs periods anchored on its last date.
3. Gaps. Empty values and very small groups in the dimensions you plan to break down by.
4. Joins. Which views join. Objects on unjoined views do not filter each other, and no claim can compare them, but each view can still have its own labelled section.

Execute bounded queries to verify these facts; metadata alone does not establish the values. Every free-form App build comes with useful saved Business Questions covering its required analyses, for reuse once the layer is published. An App cannot read a question: it runs its own queries on published items. Reuse complete matching questions. If none are useful, or some analyses are missing, save the missing questions alongside the App through semantic-layer authoring, following From exploration to a dashboard. Save only the few that matter rather than one per chart, and don’t let saving hold up the first build. Build them from published items with no local calculation, and leave any question someone else saved as it is. Saving requires write access and changes the draft; it does not publish. Without write access, build from the same queries and report that nothing was saved, rather than claiming it was. Keep the findings and complete query context available when checking the finished page.

Cover what the data supports

Get the most from the data. A vague request leaves more of the decisions to you; it does not call for a smaller page. Build something small only when you are asked to.

Read the layer only as far as the request needs, so the first build comes quickly. Get a small working page with live data up early, then add to it in small steps:

• The request names what it wants, such as measures, breakdowns or a chart. Skip the survey: find those items, build them, then suggest what else the data could show. Being specific is not asking for something small, but a request for one chart gets that chart.
• The request is vague or asks for more. Survey the layer once, before you plan. Start from its field and view counts. If it fits one catalogue page, list that page, with raw view fields as well as stored items. If it is larger, read the stored items and a small fixed number of searched pages on the request’s topic or the layer’s main subject areas, rather than paging through everything. Search matches item names only. Say that the App covers part of the layer and name what it left out.

Keep what the survey covered and left out in the page brief, so a later change starts from it instead of repeating it.

App Builder limit: on a layer larger than one page, Nash reads one page of stored items and at most three searched pages.

From what you read, work out which questions the measures, dimensions and date fields can answer. Plan for those questions yourself rather than waiting for a list. Then cover the views that mean something for this data:

• headline figures with a comparison
• change over time
• breakdowns and composition
• rankings
• distributions and outliers

Give every view and subject area you read a place on the page or a reason to leave it out. A missing join limits what you can claim across views, not how much of the data appears: put a view that does not join the others in its own labelled section or page, with its own measures and filters, and keep comparisons, shared filters and combined charts out of it. Say which parts are not connected, and name what you left out and why.

Depth follows the data. There is no target number of charts or pages, and a chart that answers no question is padding.

Thin or mock data is not a reason to do less. Derive more from it through the engine, with query calculations or stored measures for share of total, rank, period change and per-unit rates, and state the data’s problems plainly beside the figures they affect. If you offered something you cannot build, say so and why rather than dropping it.

Use semantic-layer and chart capabilities

Apply this checklist to every free-form App build, including prepared builds. Reuse verified capabilities in an existing App and recheck what the requested change affects.

• Time intelligence: when the layer has a date field, include a time-intelligence analysis anchored on that field’s latest date, not today. Read the periods through a period axis whose periodEnd is latest (The date a period is read as of), so the current period is the one the latest date falls in, even when the data stops before today. Reuse such an axis, or save one in the Business Question that needs it. Compare a partial latest period with the same point in the previous period, not with a complete one, and anchor date presets the same way (Periods and date ranges). Verify the latest date with a bounded query, then the period boundaries and comparison it produces, and show that date beside the analysis. Follow Period axes and comparisons; a snapshot without dates cannot support a trend.
• Grouped dimensions: use semantic groups where they make a breakdown meaningful, such as numeric buckets or custom category mappings. Verify membership, nulls, default groups and resulting grain. Follow Dimension variants.
• Other semantic features: use the supported capabilities that answer the question, such as conditional measures, result calculations, parameters or drill-down dimensions. Keep the calculation in its governed definition and preserve it through execution; use the Business questions guide and measure reference.
• Chart features: use supported interactions and encodings that make those analyses visible. Include an uncommon chart when it reveals a useful relationship. Verify the installed package’s definition, operation and mounting support through Choose a chart.

Record the selected capabilities, their question/view bindings and expected results in the page brief. For each omitted capability, state whether it is irrelevant to the data or task, unsupported, or blocked by access. Do not invent dates, alter a question’s grain, force an exotic chart, or recreate unavailable engine behavior in App code. A required capability that cannot be verified remains an incomplete requirement, not a passing build check.

Reproduce a reference design

Before building, inventory each panel’s chart form and mark shape, values printed on marks, reference or average lines, visible and hidden axes and legends, category and date labels, ordering, comparisons, alignment and controls. Record filter restrictions, defaults and linked-control behavior; a screenshot alone does not establish their metric meaning. Resolve consequential ambiguities from the source definitions or the requester.

A category or time restriction shown in the reference remains a requirement even if the model has no matching item. Record it as a named design decision and express it in the tile title.

Use this inventory for implementation and verification. Derive data-dependent defaults, such as the latest period, from the available data. Explain deliberate adaptations and unsupported settings; never silently substitute a different metric or omit a reference requirement.

Improve an existing page

A request to make a page look better is a request to recompose it, not to restyle it. Work again from what the data says and who reads it: change what leads, what takes the most space, what sits together and, where they no longer fit, the layout and style. Keep metric meaning, bindings, interactions, headline figures and every requested view. New surfaces over the same arrangement do not meet the request.

Lead with a business story

Storytelling is the default for a free-form App unless the prompt specifies another approach. Follow explicit layout, style and interaction requirements. Use the storytelling with data examples to connect the audience’s question, verified finding, explanation and next decision.

Lead each page with what the data says, not with what the page contains. “Germany leads net sales, ahead of France” is a finding; “Sales overview” is a label. State the finding in the page’s heading, a narrative or the title of its main chart, whichever suits the page, and do not let the app’s name outrank it. Build it from a live query in the first version of the page, and include a comparison and change over time wherever the data allows them. If the data cannot support a claim, leave the claim out.

Give the strongest relevant analysis the most space and supporting views less emphasis. Derive takeaway titles and annotations from live results; use question titles until a finding is verified. Include units, periods and coverage beside the claim. Describe an association as an association; do not invent causes, targets or recommendations the evidence cannot support.

Choose an existing layout around the decision rather than repeating a header, filter band, KPI row and equal chart cards for every business. These are composition examples, not assumed findings:

Audience’s decision	Possible composition
Network team: which links need investigation?	Table-first exceptions with a selected-link explanation and supporting comparisons.
Catalogue team: which tracks merit promotion review?	Master–detail shortlist beside artist, genre and reach/popularity context.
Commercial team: where should we investigate profit?	Bento with a dominant contribution chart, supporting totals and bounded order detail.

Account review is one such composition as a complete app. Treat it as an example, not a layout or look to copy.

A story can fit one overview screen. Keep large detail tables in bounded panels or supporting views using the overview defaults; choose long-form scrolling only when the requested reading flow calls for it.

Multi-tab apps

• One headline per tab. Open each tab with one sentence that states its finding, built from governed queries, for example “Q4 forecast $22.7m: $1.29m short of target; EMEA drives it”. It must agree with every figure on the tab; see Check that figures agree.
• One hero per tab. Give one chart about 60% of the tab and two or three supporting views, rather than a grid of equal tiles.
• Annotate the story, not only statistics. Prefer a target, a policy threshold or the date of a known event over generic mean ± σ lines.
• Preselect only what does not mislead. A preselected selection shows cross-filtering at a glance, but only where it scopes the objects it is meant to. When every object shares one selection group, a preselection rescopes company-wide figures; give that tab its own group or leave the selection empty.
• Keep a focus out of the shared group. A focused record (a case, an account, a rep) that only one tab uses belongs in its own selection group; otherwise it silently filters every other tab.
• Keep it fast. Preloading every tab multiplies queries; follow Query performance.

A gallery of apps

Several apps for one audience should not share one structure with different colours. Reviewers read a repeated header, filter strip, KPI row, hero chart and right rail as a template. Vary the experience: an operational workbench (queue, record, decision, audit), an editorial briefing, an entity record, an analytical lab, a real-time command surface. Lead each app with the screen where a user acts on governed data (a forecast call, a save plan, an approval), not with its most generic chart.

For stories with many objects, follow visibility and lazy-mounting guidance to defer off-screen charts and mount only the active chart in a tabbed container.

Chart rendering policy

Use @astrato-io/visualizations for charts and analytical data tables. For simple scalar KPI cards, choose the native number object or ordinary app UI according to the presentation needed; this choice needs no renderer exception. Icons, decorative SVG, layout, controls and non-analytical layout tables are ordinary app UI.

Judge by purpose and behavior, not by technology. A value card with a delta is ordinary presentation; a plotted trend or sparkline is a chart. Use Astrato for the chart portions inside custom UI rather than improvising chart or analytical-table replacements in HTML, CSS, SVG, canvas or another chart library because it seems easier.

Only two exceptions allow a different chart or analytical-table solution:

1. You directly and specifically instruct the assistant to use another solution. General design or styling requests do not authorize replacing charts or analytical data tables.
2. A current Astrato capability gap is verified through Choose a chart. Identify the unmet requirement and evidence, normally offer the closest viable Astrato-supported alternative first, then ask for your explicit permission before implementing the custom solution.

A gap alone is not permission. Historical notes and compiler, query or interaction errors do not verify a current gap. Keep values governed and live; renderer choice does not authorize static data.

Choose a layout

Use Choose a layout to match the page to its reading and interaction flow. The chooser starts with general dashboard layouts and links to specialized and supporting pages. Read the selected guide for its variants and responsive behavior.

Choose a style

Use Choose a style to work out a visual treatment from the subject, reader and data. Reuse an established style or reference design where available.

Choose components

Use Choose components for framing and states, then add the controls, explanations and navigation the app flow needs. Read the guides for the selected components.

Choose chart forms

Use Choose a chart for each question. Consider the full range of supported forms, including distributions, flows and hierarchies, before repeating the same few chart types. Give the chart enough space in the chosen layout and add the labels or explanatory components it needs.

Choose an expert

Use Choose an expert approach when a design lens helps with chart choice, emphasis or density. This is optional; consult the guide that fits the task.

Write a page brief

Record the choices before building, naming measures and dimensions as they appear in the semantic layer:

Page:        Executive sales overview
Question:    How are sales tracking this quarter, and where is the gap?
Finding:     The sentence the page leads with, its template and the live query behind it
Evidence:    Verified grain, units, date range and exploratory query results
Capabilities: period comparison anchored on the latest order date, semantic groups, additional
              calculation and chart interaction;
              question/view bindings, expected results and any unsupported or inapplicable items
Business Questions: existing revenue trend; saved revenue by region and revenue-to-margin bridge
Look:        Notes on subject, reader and data; the ground, accent, heading voice, density and
             view separation they led to
Layout:      kpi-led, grid variant
Style:       storytelling-with-data
Expert:      few
Components:  header, period-picker, filter-panel, kpi-card ×4, card, object-states,
             loaders, object menu, toasts, drill-through → detail
Objects:     revenue trend (line), revenue by region (bar), revenue-to-margin bridge (waterfall),
             margin by category (dot), top products (table)
Viewports:   desktop and laptop overview; stacked on narrow screens
Scrolling:   overview fits above its measured width/height thresholds;
             table rows scroll within their frame; page scrolls below the thresholds
Priority:    keep headline numbers and explanations readable; move extra detail to tabs

If the request leaves these choices open, use the overview dashboard defaults. Derive the thresholds from the chosen objects rather than copying a layout example’s numbers.