← Better StackCONTENT HISTORY

Update to Better Stack

Snapshot Nov 11, 2026 · 06:08 UTC · version 1.1.3

Collection source: downloaded plugin package.

WHAT CHANGED

First saved snapshot

No earlier snapshot is available to establish a change.

Save Better Stack and check future changes in Following.

Up to 3 plugins free · no card required.

Compare saved observations

Download comparison JSON
Full technical diff · 0 changed fields
Full snapshot data
{
  "description": "Definitive guide for Better Stack dashboard layout — grid system, layout rules, row templates, planning process, coordinate math, section manipulation. Load when creating or modifying dashboard layouts.",
  "included_files": [],
  "name": "dashboard-layout",
  "skill_md_contents": "---\nname: dashboard-layout\ndescription: Definitive guide for Better Stack dashboard layout — grid system, layout rules, row templates, planning process, coordinate math, section manipulation. Load when creating or modifying dashboard layouts.\n---\n\n# Dashboard Layout Guide\n\nThis is the single source of truth for all layout decisions. Referenced by the `dashboard-builder` and `grafana-import` skills.\n\n## Grid System\n\nBetter Stack dashboards use a **12-column grid**. Charts have `(x, y, w, h)` coordinates:\n\n- `x`: column position (0-11)\n- `y`: row position (0-based)\n- `w`: width in columns (must sum to 12 per row)\n- `h`: height in rows (always 6 — see Height section)\n\n**Section headers** occupy exactly 1 row of height (h=1) in the y-coordinate space. Charts in a section start at `section_y + 1`.\n\n## Height\n\n**ALL charts use `height: 6`.** Always pass `height: 6` explicitly — the default is 8, which is too tall.\n\n### Minimum chart heights\n\n| Min Height | Chart Types                                                                             |\n| ---------- | --------------------------------------------------------------------------------------- |\n| 6 units    | `line_chart`, `bar_chart`, `scatter_chart`, `heatmap_chart`, `gauge_chart`, `map_chart` |\n| 4 units    | `pie_chart`, `number_chart`, `table_chart`, `tail_chart`                                |\n| 2 units    | `static_text_chart`, `text_chart`                                                       |\n| 1 unit     | sections                                                                                |\n\n## Layout Rules (priority order)\n\nThese rules are ranked. When two rules conflict, the higher-priority rule wins.\n\n**Rule 1 (highest): No vertical gaps.** Every row must be filled. No empty rows between charts within a section.\n\n**Rule 2: No horizontal empty space.** Every row must sum to exactly 12 width units. No gaps on the right side.\n\n**Rule 3: No full-width charts.** A single chart spanning w:12 is almost always wrong. If you have a lone chart, pull it up to share a row with another chart, or push it down to join the next row. Exception: tables or heatmaps that genuinely need the full width.\n\n**Rule 4: No orphan rows.** If the last row has fewer charts than the rows above, merge it into the previous row. Up to 4 charts per row is fine.\n\n**Rule 5: Even widths within a row.** Charts sharing a row should be equal width when possible:\n\n- 2 charts -> w:6 + w:6\n- 3 charts -> w:4 + w:4 + w:4\n- 4 charts -> w:3 + w:3 + w:3 + w:3\n\nRelax this only if needed to satisfy Rules 1-4.\n\n**Rule 6: Prefer 3 charts per row.** This is the ideal density. 2 per row is acceptable for line charts. 4 per row is acceptable for number/gauge charts. 1 per row is a last resort.\n\n## Number Chart (KPI) Rules\n\nNumber charts are compact — they should NEVER be as wide as line/bar charts:\n\n- **Maximum width: w:4.** Number charts should be w:3 (default) or w:4. Never wider.\n- **Mixed rows:** When a number chart shares a row with a line/bar chart, make the number chart narrow and give the remaining space to the line/bar chart.\n\nExamples:\n\n- 1 number + 1 line -> Number(w:3) + Line(w:9) = 12\n- 1 number + 2 lines -> Number(w:3) + Line(w:5) + Line(w:4) = 12\n- 2 numbers + 1 line -> Number(w:3) + Number(w:3) + Line(w:6) = 12\n\n## Row Templates\n\nUse these pre-approved row configurations:\n\n```\n3 line/bar charts:        w:4 + w:4 + w:4 = 12   (best overall)\n2 line/bar charts:        w:6 + w:6 = 12          (acceptable)\n4 number charts:          w:3 + w:3 + w:3 + w:3 = 12\n3 number charts:          w:4 + w:4 + w:4 = 12\n1 number + 1 line:        w:3 + w:9 = 12          (number stays narrow)\n2 numbers + 1 line:       w:3 + w:3 + w:6 = 12\n3 numbers + 1 line:       w:2 + w:2 + w:2 + w:6 = 12  (line takes half)\n1 number + 2 lines:       w:3 + w:5 + w:4 = 12    (or w:4 + w:4 + w:4)\n4 mixed (overflow merge):  w:3 + w:3 + w:3 + w:3 = 12\n```\n\n## Layout Planning Process (MANDATORY)\n\nCharts auto-position left-to-right, top-to-bottom within a section, so **creation order = display order**. Plan first, optimize, then create.\n\n**Step 1 — Draft.** List all charts for the section with their default widths. Assign them to rows summing to 12.\n\n**Step 2 — Optimize.** Review the draft and fix violations. Check these in order:\n\n- Any row with a single w:12 chart? -> Merge with another row (Rule 3)\n- Orphan last row with fewer charts than rows above? -> Merge into previous row (Rule 4)\n- Any number chart wider than w:4? -> Shrink it, give space to adjacent line/bar charts\n- Uneven widths in a row (e.g., w:4 + w:8)? -> Try w:6 + w:6 or w:4 + w:4 + w:4\n- Two rows of 2 that could become one row of 3 + one row of 1? -> Redistribute\n\n**Step 3 — Log the plan.** Output the final layout before creating charts — a compact row list like below, not prose commentary to the user:\n\n```\nSection: \"CPU & memory\"\n  Row 1: Avg CPU utilization (number, w:3) + Avg freeable memory (number, w:3) + Avg connections (number, w:3) + Avg disk queue depth (number, w:3) = 12\n  Row 2: CPU utilization over time (line, w:4) + Freeable memory over time (line, w:4) + Disk queue depth over time (line, w:4) = 12\n  Row 3: CPU by instance (bar, w:4) + Freeable memory by instance (bar, w:4) + Disk queue depth by instance (bar, w:4) = 12\n```\n\n**Step 4 — Create charts in exact row order.** Row 1 left-to-right, then Row 2 left-to-right, etc. All charts `height: 6`.\n\n### Optimization examples\n\n**Full-width chart (Rule 3):**\n\n```\nDRAFT (bad):\n  Row 1: Line(w:6) + Line(w:6) = 12\n  Row 2: Line(w:6) + Line(w:6) = 12\n  Row 3: Bar(w:12) = 12              <- Rule 3: full-width\n\nOPTIMIZED:\n  Row 1: Line(w:4) + Line(w:4) + Line(w:4) = 12\n  Row 2: Line(w:4) + Line(w:4) + Bar(w:4) = 12\n```\n\n**Orphan last row (Rule 4):**\n\n```\nDRAFT (bad):\n  Row 1: Line(w:4) + Line(w:4) + Line(w:4) = 12\n  Row 2: Line(w:4) + Line(w:4) + Line(w:4) = 12\n  Row 3: Bar(w:12) = 12              <- Rule 3 + Rule 4: orphan\n\nOPTIMIZED:\n  Row 1: Line(w:4) + Line(w:4) + Line(w:4) = 12\n  Row 2: Line(w:3) + Line(w:3) + Line(w:3) + Bar(w:3) = 12\n```\n\n**Number chart too wide:**\n\n```\nDRAFT (bad):\n  Row 1: Number(w:6) + Line(w:6) = 12   <- number chart way too wide\n\nOPTIMIZED:\n  Row 1: Number(w:3) + Line(w:9) = 12   <- number stays compact\n```\n\n---\n\n## Coordinate Math\n\n### Section position calculation\n\nEach section's y position is determined by the previous section's content:\n\n```\nsection_y = previous_section_y + 1 (header) + (num_chart_rows * row_height)\n```\n\nExample with h=6 charts:\n\n- Section A at y=0: 1 row of charts -> next section at 0 + 1 + 6 = 7\n- Section B at y=7: 2 rows of charts -> next section at 7 + 1 + 12 = 20\n- Section C at y=20: 1 row of charts -> next section at 20 + 1 + 6 = 27\n\n### Chart position calculation\n\nCharts within a section start at `section_y + 1`:\n\n```\nchart_y = section_y + 1 + (row_within_section * row_height)\n```\n\nWhen multiple sections exist, each chart's absolute y accounts for all section headers above it:\n\n```\nchart_y = (row_index * row_height) + number_of_section_headers_above\n```\n\n### Worked example (5 sections, 8 chart rows, h=6)\n\n| Row | Sections above | Chart y       |\n| --- | -------------- | ------------- |\n| 0   | 1 (Overview)   | 0\\*6 + 1 = 1  |\n| 1   | 1              | 1\\*6 + 1 = 7  |\n| 2   | 2 (+Errors)    | 2\\*6 + 2 = 14 |\n| 3   | 3 (+Cache)     | 3\\*6 + 3 = 21 |\n| 4   | 3              | 4\\*6 + 3 = 27 |\n| 5   | 4 (+Traffic)   | 5\\*6 + 4 = 34 |\n| 6   | 4              | 6\\*6 + 4 = 40 |\n| 7   | 5 (+Edge)      | 7\\*6 + 5 = 47 |\n\nSection headers at: y=0, y=13 (0+1+12), y=20 (13+1+6), y=33 (20+1+12), y=46 (33+1+12).\n\n---\n\n## Section Manipulation\n\n### Adding sections to a new dashboard\n\nWhen building a new dashboard, use the `section` parameter on `add_chart_to_dashboard`. Sections are auto-created and charts auto-positioned within them. No coordinate math needed.\n\n### Reordering sections on an existing dashboard\n\nThere is no tool to move or reorder sections. The reliable pattern:\n\n1. `dashboard` — capture current chart positions and section positions\n2. `remove_dashboard_section` for each section — clear all section headers\n3. `move_charts` (atomic) — reposition all charts to their new y-coordinates\n4. `add_dashboard_section` — add new section headers top-to-bottom (lowest y first). Each section automatically shifts all content at/below its y down by 1 row.\n5. `dashboard` — verify final state; repeat from step 2 if wrong\n\n### Gotchas\n\n**`move_charts` rejects overlapping names at same y-coordinate.** If a chart name and a section name share the same y, `move_charts` rejects the move. Remove conflicting section headers before moving charts.\n\n**Chart removal triggers auto-reflow.** After deleting one chart, remaining charts in that row may scatter. Immediately reposition ALL remaining charts in the affected row atomically via `move_charts`.\n\n**`add_dashboard_section` always shifts content down.** There is no opt-out. When adding sections to a dashboard that already has charts positioned, add sections top-to-bottom so each shift cascades correctly.\n\n---\n\n## Layout Validation Checklist\n\nWhen auditing a dashboard, check:\n\n1. **Section alignment**: First chart in each section at `section_y + 1`\n2. **Row completeness**: Every row sums to exactly w=12\n3. **No vertical gaps**: Rows within a section are contiguous (prev_y + h = next_y)\n4. **No overlaps**: No two charts share the same grid cell\n5. **Section spacing**: `next_section_y = current_section_y + 1 + (rows * h)`\n6. **Chart-to-section membership**: chart_y >= section_y + 1 AND chart_y < next_section_y\n7. **Height**: All charts h=6 (except static_text which can be shorter)\n8. **Number charts**: No number chart wider than w:4\n\n## Common Layout Mistakes\n\n| Mistake                                       | Fix                                                   |\n| --------------------------------------------- | ----------------------------------------------------- |\n| Charts at same y as section header            | Charts must be at `section_y + 1`                     |\n| Row doesn't sum to 12                         | Adjust widths to fill the row                         |\n| Single w:12 chart                             | Merge with adjacent row or split                      |\n| Orphan last row                               | Merge into previous row                               |\n| Number chart at w:6 or wider                  | Shrink to w:3 or w:4                                  |\n| Ignoring section header height during reorder | Add +1 offset per section header above each chart row |\n| Deleting chart without repositioning row      | Use `move_charts` immediately after removal           |\n"
}

SHA-256 of public snapshot: 00123aafc787025fc34cbb480a8beaf1f1dfbe7822b0d5dba648b64dea7f41fd