Managing dashboard widgets

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

Human overview: [products/dashboards/CONTRIBUTING.md](../../../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](references/architecture.md#shipped-types-source-of-truth).

2. Ship a new widget_type

Intake — ask before coding

Mandatory for new types only. Read [widget-intake.md](references/widget-intake.md) and:

1. [Discover product UI in the repo](references/widget-intake.md#discover-product-ui-in-the-repo) — concrete components/scenes before generic tile-body questions.
2. Apply [defaults and inference](references/widget-intake.md#defaults-and-inference) (groupId, copy spine, list UX) — never AskQuestion banned topics.
3. [Resolve ambiguity](references/widget-intake.md#resolve-ambiguity-ask-dont-guess) — one batched follow-up for gaps, max 6 questions ([open fields](references/widget-intake.md#open-fields-may-need-questions)).
4. Post the [spec table](references/widget-intake.md#spec-fields-to-lock); get confirmation before checklist §1.

Execute

After spec confirmation → [checklist-new-widget-type.md](references/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](references/live-widgets.md) first — the live contract (islive, creationflag, generatedAt seeds) and the widgets/live/ toolkit.

3. Update a shipped type

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

1. Read [managing-existing-widgets.md](references/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](#2-ship-a-new-widget_type)). Chart-primary = insight tile ([architecture.md § Charts](references/architecture.md#charts--use-insight-tiles-not-widgets)).

4. Platform invariants

Both paths:

1. RBAC registry-driven — no widget_type branches in dashboard.py. [permissions-and-sharing.md § Product RBAC](references/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](references/architecture.md#platform-files--do-not-branch-per-type)
4. WidgetCard compound pattern — [composition.md](references/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](references/config-and-codegen.md).
6. No chart-primary widgets — [architecture.md § Charts](references/architecture.md#charts--use-insight-tiles-not-widgets)

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](references/checklist-new-widget-type.md#8-tests) + hogli build:openapi + dedicated Storybook stories per [checklist §5b](references/checklist-new-widget-type.md#5b-storybook) (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 testrunwidgets.py if BE changed, products/dashboards/frontend/widgets/ if FE changed, hogli build:openapi if config OpenAPI changed. See [managing-existing-widgets.md](references/managing-existing-widgets.md) routing table Also check column.

Reference appendix