Managing dashboard widgets

For PostHog engineers working on dashboard widget tiles in the repo.

Human overview: products/dashboards/CONTRIBUTING.md

In scope: widget tiles (widget_id on DashboardTile) — ship new types or change shipped types.

Out of scope: adding an existing type to a dashboard (MCP dashboard-widget-catalog-list → dashboard-widgets-batch-add); insight tiles, text cards, button tiles.

1. Route first

Shipped types (code truth): architecture.md § Shipped types.

2. Ship a new widget_type

Intake — ask before coding

Mandatory for new types only. Read widget-intake.md and:

1. Discover product UI in the repo — concrete components/scenes before generic tile-body questions.
2. Apply defaults and inference (groupId, copy spine, list UX) — never AskQuestion banned topics.
3. Resolve ambiguity — one batched follow-up for gaps, max 6 questions (open fields).
4. Post the spec table; get confirmation before checklist §1.

Execute

After spec confirmation → checklist-new-widget-type.md §1 → §8. §5b (dedicated stories — required before the PR, not a follow-up) is sequenced once MVP tests are green.

Self-updating / real-time tile? Read live-widgets.md first — the live contract (is_live, creation_flag, generatedAt seeds) and the widgets/live/ toolkit.

3. Update a shipped type

Skip intake. Identify the type from the request or EXPECTED_WIDGET_TYPES in widget_registry.py.

1. Read managing-existing-widgets.md — "What kind of change?" routing table for primary files.
2. Confirm: which type, what changes, backward-compatible config migration?
3. Follow linked references from that table — do not re-read the new-type checklist.

Cannot change in place: widget_type string on existing rows; stored w/h when catalog defaults change.

New visualization kind = ship (§2). Chart-primary = insight tile (architecture.md § Charts).

4. Platform invariants

Both paths:

1. RBAC registry-driven — no widget_type branches in dashboard.py. permissions-and-sharing.md § Product RBAC
2. One widget_type everywhere — registries + both catalogs + FE registry; variants share groupId only.
3. Per-type code in product paths — not platform shells. architecture.md § Platform files
4. WidgetCard compound pattern — composition.md
5. Config contract = Pydantic SSOT — widget_specs/configs.py + WidgetSpec in registry.py; hogli build:openapi for OpenAPI/FE Zod/MCP. Runtime PATCH stays JSONField. See config-and-codegen.md.
6. No chart-primary widgets — architecture.md § Charts

New widget_type strings need no migration — register registries + catalogs only.

5. Companion skills

6. Verify

MVP smoke (renders + core tests — not a ship point):

hogli test products/dashboards/backend/api/test/test_run_widgets.py
hogli test products/dashboards/backend/api/test/test_dashboard_widgets.py
hogli test products/dashboards/frontend/widgets/registry.test.tsx

Ship gate (required before the PR): checklist §8 + hogli build:openapi + dedicated Storybook stories per checklist §5b (component + edit modal — required, not just the catalog overview).

Config SSOT changes (also run after widget_specs/ edits):

hogli test products/dashboards/backend/api/test/test_widget_config_schema_parity.py
hogli test products/dashboards/frontend/widgets/widgetConfigSchemaParity.test.ts
hogli test products/dashboards/backend/api/test/test_widget_openapi_enums.py   # new widget_type only

Update: tests for layers touched — at minimum test_run_widgets.py if BE changed, products/dashboards/frontend/widgets/ if FE changed, hogli build:openapi if config OpenAPI changed. See managing-existing-widgets.md routing table Also check column.

Reference appendix