# Tableau Dashboard Creator

> Guides data analysts through a multi-step Tableau dashboard creation workflow - brand setup, data exploration, dashboard planning, interactive HTML mock creation, Tableau implementation spec, and experimental TWB workbook generation. Use when the user wants to create a Tableau dashboard, build a dashboard mock, plan KPIs and charts, or generate a Tableau implementation document.

- Skill: `kilo-org/tableau-dashboard-creator` (Agent Skill, multi-file: 60 files)
- Install (CLI): `npx skillmds@latest add kilo-org/tableau-dashboard-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kilo-org/tableau-dashboard-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Kilo-Org (https://skillmd.com/u/kilo-org)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kilo-org/tableau-dashboard-creator

---


# Tableau Dashboard Creator

A multi-step workflow that transforms a human-language dashboard request into an implementable Tableau specification with an interactive HTML mock and an optional generated workbook.

## Prerequisites

Before starting, scan the user's project root for:

```
Checklist (all paths are inside the project directory the skill is executed in, except `.env` — see note below):
- [ ] QUERIES.md — SQL queries grouped under database type headings (e.g., PostgreSQL)
      OR sample-data/ directory with CSV files
- [ ] <DASHBOARD-NAME>-PRD.md — Human-language dashboard request
- [ ] .env — Database credentials (skip if using sample-data/). Does **not** need to live
      inside the project directory — `load_dotenv()` walks upward from the current
      working directory and picks up the closest `.env` it finds, so the user can keep
      credentials in a parent directory and avoid copying secrets into the project.
      Required variables (PostgreSQL): `PG_HOST`, `PG_DATABASE`, `PG_USER`, `PG_PASSWORD`,
      and optionally `PG_PORT` (defaults to `5432`).
- [ ] branding/ directory (required) containing ONE of:
      - branding.md — brand spec (palette, fonts, padding, sizing)
      - template.twb — Organization's Tableau template workbook
      Optionally, a logo (.svg or .jpg) can be added to branding/ in either case.
```

**If any are missing, immediately run Project Scaffolding (below) before doing anything else.** Do NOT ask the user to manually provide files — scaffold first, then let them customize.

> **Only check for the files listed above.** Do NOT check for `design-tokens.md`, `DS-ARCHITECTURE.md`, `DASHBOARD-PLAN.md`, or any files inside `mock-version/` — those are **outputs** generated by the workflow steps, not user-provided inputs.

### QUERIES.md Format

Queries must be grouped under a heading matching the database type:

```markdown
## PostgreSQL
SELECT * FROM public.table2
```

The agent selects the correct query script based on the heading.

> **Adding other databases**: The skill ships with PostgreSQL support. To add other databases (Databricks, Snowflake, MySQL, BigQuery, etc.), create a matching `query_<dbtype>.py` script in the installed skill's `scripts/` directory following the same pattern as `query_postgresql.py`, add the corresponding heading to `QUERIES.md`, and update `references/step-a-data-exploration.md`.

### Required Python packages

```
# PostgreSQL
psycopg2-binary, python-dotenv, pandas
```

## Workflow Overview

```
[Scaffolding] ──[user approval]──> Step 0: Brand Setup
Step 0: Brand Setup ──[user approval]──> Step A: Data Exploration
Step A: Data Exploration ──[user approval]──> Step B: Dashboard Planning
Step B: Dashboard Planning ──[user approval]──> Step C: HTML Mock
Step C: HTML Mock ──[user approval]──> Step D: Implementation Spec
Step D: Implementation Spec ──[user approval]──> Step E: TWB Generation (Experimental)
```

**Do NOT skip steps. Wait for explicit user approval before moving to the next step.**

## Project Scaffolding

**When to run**: Automatically when the prerequisites check finds missing files. Skip only if all prerequisite files already exist.

**Process**:

1. **Ask the user for permission** to scaffold their project directory
2. **Read each file from `skeleton/`** in the skill directory and **write its contents** into the user's project root, preserving the directory structure. This creates:
   - `sample-data/` — starter CSV files (sales orders, customer segments, monthly targets) for immediate testing
   - `.env.example` — database credentials template (rename to `.env` when ready)
   - `EXAMPLE-PRD.md` — blank PRD template with section headers and placeholder examples
   - `QUERIES.md` — SQL query template with database type headings
   - `branding/branding.md` — branding spec template with section headers and placeholder values
   - `SalesPerformance-PRD.md` — partially filled Sales Performance PRD as a starting reference
3. **List every file created** and briefly explain what the user should fill in or customize
4. **Be explicit about scaffold state**:
   - `sample-data/` means the project is immediately usable in demo mode
   - database mode is only ready after the user fills in `.env` and `QUERIES.md`
   - branding mode is only ready after the user finishes `branding/branding.md` and optionally adds a logo or icons
5. **Encourage the user** to explore the `demo/` directory in the skill repository for a complete worked example with all steps already generated
6. **If both `sample-data/` and a real database setup exist**, explicitly tell the user which source will be used in Step A and why before proceeding
7. **Wait for the user** to confirm they have reviewed/customized the files, then proceed to Step 0

> **Important**: Do NOT use shell `cp` commands — the skeleton directory is inside the skill installation, not the user's project. Read each skeleton file with the Read tool and write it to the user's project root with the Write tool.

> **Every step is iterative.** The agent will not produce a perfect result in a single pass — this is expected and by design. Encourage the user to review each artifact carefully, request changes, and iterate until satisfied. This is especially true for Step C (HTML mock) and Step E (TWB generation). For Step C, encourage the user to share the mock with stakeholders for validation before approving — a well-reviewed mock prevents costly rework downstream.

## Step 0: Brand Setup

**Identity**: Tableau design systems engineer.

Read [references/step-0-brand-setup.md](references/step-0-brand-setup.md) for detailed instructions.

Summary:
1. **Ask the user for the minimum target Tableau Desktop version first** (`2024.2 – 2025.x` default, or `2026.1+`). Record the answer in `design-tokens.md` — it controls Step E's XML emission.
2. Detect branding source inside `branding/`: `branding.md` OR `template.twb`
3. Extract design tokens from `branding.md` (or from the `.twb` XML), plus optional logo if present
4. If fallback defaults are used for any missing brand decision, call out each fallback decision explicitly in `design-tokens.md`
5. Generate `design-tokens.md` in the project root
6. Present `design-tokens.md` to the user for approval

## Step A: Data Exploration

**Identity**: Senior Data Engineer.

Read [references/step-a-data-exploration.md](references/step-a-data-exploration.md) for detailed instructions.

Summary:
1. **Check for local data first**: If `sample-data/` directory exists with CSV files and the user has not clearly signaled database intent, scan those files directly
2. **If `QUERIES.md` or `.env` clearly indicates DB intent**, say which source you are using and why before continuing
3. **If using the database path**, read `QUERIES.md`, identify the database type from headings, and execute each query via the matching script from the installed skill:
   - PostgreSQL: run the installed skill's `scripts/query_postgresql.py`; it permits one read-only `SELECT`, `WITH`, or plain `EXPLAIN` query and enforces a hard 500-row cap
   - Other databases: add a `query_<dbtype>.py` script following the same read-only-by-default pattern
4. Analyze schema and sample data
5. Create `DS-ARCHITECTURE.md` with datasource and field descriptions
6. Present `DS-ARCHITECTURE.md` to the user for approval

## Step B: Dashboard Planning

**Identity**: Senior Data Analyst specialized in informative graphs and dashboards.

Read [references/step-b-dashboard-planning.md](references/step-b-dashboard-planning.md) for detailed instructions.

Summary:
1. Read the PRD file, `DS-ARCHITECTURE.md`, and `design-tokens.md`
2. Identify KPIs and chart types from the user request
3. Map each visualization to specific columns from `DS-ARCHITECTURE.md`
4. Assign stable IDs for KPIs, charts, filters, and actions so later steps can reuse the same identifiers
5. Suggest additional KPIs and interesting data patterns
6. Propose filter strategy and dashboard actions
7. Present the dashboard plan to the user with approval criteria before moving to Step C

## Step C: HTML Mock Creation

**Identity**: Tableau Developer.

Read [references/step-c-mock-creation.md](references/step-c-mock-creation.md) for detailed instructions.

Summary:
1. Read `design-tokens.md` (generated in Step 0)
2. Select appropriate template layout based on design tokens
3. Ask the user for their target screen size: **Standard Laptop** (1100×800) for portable devices, **Home Screen** (2100×1000) for wide external displays, or **Custom** dimensions. Defaults to Standard Laptop if skipped.
4. Create interactive HTML mock with Chart.js and sample data using the chosen screen dimensions as the dashboard frame
5. Save to `mock-version/v_N/mock.html`
6. Prevent empty-space-heavy, compressed, or out-of-bounds chart layouts by enforcing explicit slot sizes and readable chart occupancy
7. Present the mock to the user for approval
8. If approved, update `DASHBOARD-PLAN.md` and `design-tokens.md` if the mock diverged from them

## Step D: Tableau Implementation Spec

Read [references/step-d-implementation-spec.md](references/step-d-implementation-spec.md) for detailed instructions.

Summary:
1. Translate the approved HTML mock into a technical Tableau implementation spec
2. Document container hierarchy, sheets, calculated fields, parameters, and stable IDs in a strict markdown schema
3. Save to `mock-version/v_N/TABLEAU-IMPLEMENTATION.md`
4. Include enough structured detail for Step E to consume without guessing
5. If approved, update `DASHBOARD-PLAN.md` if the implementation spec diverged from it

## Step E: TWB Workbook Generation (Experimental)

**Scaffold build string**: `2025.1.10 (20251.25.1121.1650)` — all snippets are authored against this build. The emitted workbook `version` attribute and the inclusion of `<explain-data>` are driven by the **Target Tableau Version** captured in Step 0. See `references/step-e-twb-generation.md § Tableau Version Targeting`.

Read [references/step-e-twb-generation.md](references/step-e-twb-generation.md) for detailed instructions.

**Snippet library**: The `references/snippets/` directory contains validated `.twb` files organized by domain. Each domain has a companion `.md` explaining the XML patterns. **Read the relevant snippet files and companion docs before generating XML** — assemble from validated patterns, do not generate XML from scratch.

Summary:
1. Read the approved TABLEAU-IMPLEMENTATION.md and design-tokens.md
2. Read `DS-ARCHITECTURE.md` for field names and types
3. **Select snippet patterns** based on requirements:
   - Data model: `snippets/data-model/` → single CSV, relationship, or join
   - Chart types: `snippets/worksheets/` → bar, line, text-table, area, pie, scatter, dual-axis, map
   - Styling: `snippets/worksheets/bar-chart-styled.twb` → fonts, colors, axis titles
   - Filters: `snippets/worksheets/bar-chart-filtered.twb` → categorical, date range, context
   - Sorting: `snippets/worksheets/bar-chart-sorted.twb` → computed sort
   - Tooltips: `snippets/worksheets/custom-tooltip.twb` → formatted tooltip template
   - Dashboard layout: `snippets/dashboard/` → single/multi-sheet, nested containers
   - Actions: `snippets/dashboard/` → filter, highlight, parameter actions
   - Features: `snippets/features/` → calculated fields, parameters, LOD expressions, Dynamic Zone Visibility
4. **Assemble the `.twb`** using the scaffold skeleton (`snippets/scaffold/workbook-skeleton.twb`) as the base, inserting parameterized snippet patterns in strict element order
5. **Generate as live connection** — do NOT include `<extract>` sections
6. Package as `.twbx` (ZIP archive bundling the `.twb` + all CSV data files)
7. Save both `dashboard.twb` and `dashboard.twbx` to `mock-version/v_N/`
8. Instruct the user to open **`dashboard.twbx`** in Tableau Desktop and use **Data → Replace Data Source** to connect live data

### Handling Unknown Features

If the user requests a Tableau feature that has no validated snippet in `references/snippets/`, **ask the user** which approach they prefer:

1. **Provide a reference `.twb`** — the user builds a minimal example in Tableau Desktop demonstrating just that feature, provides the path, and the agent extracts the pattern from it
2. **Attempt from `examples/`** — the agent searches the `examples/` directory for a similar pattern in the existing complex workbooks, adapts it, and flags it as ⚠️ UNVALIDATED
3. **Skip and document** — the agent generates everything else correctly and writes a `MANUAL_STEPS.md` listing what the user needs to add manually in Tableau Desktop

## Version Management

- All mock and implementation files go inside `mock-version/v_N/` (e.g., `mock-version/v_1/`)
- Each version is a **full standalone copy** (mock.html + TABLEAU-IMPLEMENTATION.md + dashboard.twb + dashboard.twbx)
- When the user requests revisions after Step D or E, increment the version number. Step C revisions overwrite the current mock in-place (same `v_N` directory).
- `DS-ARCHITECTURE.md`, `DASHBOARD-PLAN.md`, and `design-tokens.md` live at the project root and always represent the **latest approved global truth**
- Each versioned artifact should note which approved root-level files and mock version it was derived from

## File Structure (per project)

```
project-root/
├── QUERIES.md                      (user input — with DB type headings)
├── <DASHBOARD-NAME>-PRD.md         (user input)
├── .env                            (user input — DB credentials)
├── branding/                       (user input — required; contains brand source)
│   ├── branding.md                 (option A: brand spec)
│   ├── template.twb                (option B: org Tableau template)
│   ├── logo.svg / logo.jpg         (optional, either case)
│   └── icons/                      (optional)
├── sample-data/                    (user input — optional, skip DB queries)
│   └── *.csv
├── design-tokens.md                (generated - step 0)
├── DS-ARCHITECTURE.md              (generated - step A)
├── DASHBOARD-PLAN.md               (generated - step B)
└── mock-version/
    ├── v_1/
    │   ├── mock.html               (generated - step C)
    │   ├── TABLEAU-IMPLEMENTATION.md (generated - step D)
    │   ├── dashboard.twb           (generated - step E, raw XML)
    │   └── dashboard.twbx          (generated - step E, packaged with data)
    └── v_2/
        ├── mock.html
        ├── TABLEAU-IMPLEMENTATION.md
        ├── dashboard.twb
        └── dashboard.twbx
```