Pages and layout

Pages arrange dashboard components on a deterministic grid. Query definitions remain at dashboard scope; the page decides which reusable filters and visuals appear together and where they are placed.

Build the page structure

Define the canvas and grid

pages:
  - id: overview
    title: Overview
    description: Revenue and order performance at a glance.
    canvas:
      width: 1366
      height: 900
    grid:
      columns: 12
      row_height: 48
      gap: 16
      padding: 16
    components: []

The canvas documents the design reference size. The grid creates predictable coordinates and spans. Use a consistent column count, gap, and row height across related pages so users do not experience a different visual rhythm on each route.

Place components

Each page component has a stable ID, a component kind, exactly the relevant reference, and placement:

components:
  - id: revenue
    kind: visual
    visual: revenue_kpi
    placement: {col: 1, row: 1, col_span: 3, row_span: 3}
  - id: revenue-trend
    kind: visual
    visual: revenue_by_month
    placement: {col: 4, row: 1, col_span: 9, row_span: 8}
  - id: order-details
    kind: visual
    visual: orders_table
    placement: {col: 1, row: 10, col_span: 12, row_span: 8}

Use kind: visual for charts, KPIs, tables, matrices, and pivots; rendering is inferred from the referenced visual's type. Use kind: slicer for an on-canvas presentation of a report or page filter binding, and kind: header for headings. The Filters pane presents those same bindings independently of canvas placement.

Coordinates are one-based. Keep col + col_span - 1 within the configured column count. Avoid accidental overlaps unless a future component contract explicitly supports layering.

Design reading order

YAML order should follow the intended document and keyboard order, not just visual coordinates. A practical report order is:

  1. page context or header;
  2. high-value filters;
  3. summary KPIs;
  4. primary analytical visual;
  5. supporting comparisons;
  6. record-level or multidimensional detail.

This order gives compact layouts a sensible fallback and makes the source easier to review. Coordinates still control desktop placement, but source order communicates meaning.

Size for content

Choose spans based on the information a component must display:

  • KPI cards need enough width for formatted values and labels.
  • Legends and long category labels require more chart width.
  • Time-series charts need enough horizontal space for the selected period.
  • Tables need enough height for a useful initial window.
  • Slicers need space for selected values, summaries, search, and operators.

Do not solve overcrowding by shrinking every component. Split a page when users are expected to answer distinct questions or when details push the primary analysis below several screenfuls.

Stabilize and test the layout

Keep IDs stable

Page component IDs participate in interaction targeting and client state. Renaming revenue-trend can break a filter or selection target even when the referenced visual remains unchanged. Treat IDs as local API names: change them intentionally and search the dashboard for references.

Visual definition IDs should also remain stable. Moving a component only requires a placement edit; it should not require copying or renaming its query.

Test layouts

After deployment to development:

  • inspect the page at the reference canvas width;
  • test a compact browser width and the mobile navigation shell;
  • check long titles, large currency values, and empty states;
  • use keyboard navigation to confirm source order is understandable;
  • verify charts resize without clipped labels or legends;
  • confirm tables remain usable without forcing document-wide horizontal scrolling.

Use the sample Sales dashboard and visual showcase as working layout examples. See Dashboard configuration for the current page and placement contract.