Tableau Brand

tableau-brand

Step 4 of 8. Turns the analyst's branding into a DESIGN-TOKENS.md — the single source of truth for palette, type, and spacing that tableau-mock (the HTML demo) and tableau-build (the .twb) both consume.

| | | |---|---| | Reads | The analyst's branding/ (lowercase input): branding/branding.md (spec, preferred), an org template branding/*.twb, and any branding/logo.* / branding/icons/. Falls back to the scaffold/branding/EXAMPLE-branding.md demo. No required read — branding is an input, so this step never refuses for a "missing" file (CONTRACT.md §1). | | Writes | DESIGN-TOKENS.md at the project root (latest approved truth; overwritten in place). May also author branding/branding.md from a scraped .twb or the brand interview. | | STATE.md update | Sets brand = approved (tokens authored) or skipped; flips every downstream approved step to stale on a re-run (CONTRACT.md §4.2). | | Entry gate | Refuses to run until init is approved in STATE.md (CONTRACT.md §4.1). | | Next step | tableau-plan (or tableau-route to confirm). |

> Tell the analyst this step matters. Branding is what lets the later steps > know how to build the mock and how to write a precise Tableau implementation > spec. Don't skimp on the palette, the fonts, the padding, the sizing — vague > branding here produces a bland, generic dashboard downstream. This is why the step > can only be skipped once branding/branding.md exists (see below): the analyst > must capture at least some brand intent before opting into neutral styling.

The mechanical guarantees — the entry gate, the DESIGN-TOKENS.md schema check, the skip precondition, and the STATE.md transition — live in brand.py, this skill's executable mirror of the contract. Your job is the part that needs judgment: reading the branding (or interviewing for it) and authoring the tokens. Run the script at the two points below; do not hand-edit STATE.md yourself.

How to run

1. Precheck. From the project directory, run:

``bash python "${CLAUDE_SKILL_DIR}/scripts/brand.py" precheck "" ``

(Use python3 if python is unavailable.) If it prints [BLOCKED], relay the reason and stop — the analyst must run tableau-init first. Otherwise note its signals: whether a DESIGN-TOKENS.md already exists (refine vs overwrite), the source mode, any logo/icon assets to integrate, and whether skip is allowed.

1. Refine vs overwrite. If precheck reports DESIGN-TOKENS.md already exists,

use AskUserQuestion to offer Refine (keep its structure, update values), Overwrite (author fresh), or Skip (only if allowed). Never silently overwrite existing tokens.

1. Follow the source mode precheck reported:

| source mode | what to do | |-------------|------------| | spec | Extract tokens from branding/branding.md. | | spec+twb | Scrape the org branding/*.twb and use it to enrich the existing branding/branding.md (don't discard the analyst's spec), then build tokens. | | twb | Scrape the org branding/*.twb, write branding/branding.md from what you find, then build tokens. | | scaffold | Only the scaffold/ demo example exists — say so (you're demoing, not using real brand input). | | none | Run the brand interview (next section), write branding/branding.md from the answers, then build tokens. |

When a .twb is involved: before reading it, ask the analyst to confirm the workbook is as thin as possible (a minimal template — ideally one styled sheet/dashboard, no large data extracts or dozens of sheets). A heavy .twb floods the context with irrelevant XML. Scrape only what feeds design tokens: fonts, colors (fills, text, series palette), sizing, container/spacing structure, and any embedded logo (``).

1. Brand interview (source mode none only). When there is no branding input at

all, do not leave the brand blank — interview the analyst, borrowing the grill-me approach but bounded to at most 10 questions. Ask one at a time, propose a recommended default for each (from references/tableau-design-tokens.md), and choose the questions that recover the most token-relevant information: primary/secondary colors, a cohesive ≤5-color series palette, font family (default the Tableau family), title vs label sizing, card padding / section spacing, dashboard sizing mode, and whether a logo/icons exist. Prefer AskUserQuestion (multiple-choice with your recommendation first). Write the answers into branding/branding.md, then build tokens.

1. Author DESIGN-TOKENS.md. Write (or Edit, when refining) DESIGN-TOKENS.md

at the project root using references/DESIGN-TOKENS-TEMPLATE.md as the structure. Fill palette/type/spacing from the branding source. For every value the brand did not specify, pull the Tableau default from references/tableau-design-tokens.md and list it under ## Fallback Decisions — that section is how the analyst sees which visual choices were guessed (it is required; if nothing was guessed, write "None"). Integrate any logo/icons precheck found. Present the tokens for approval.

1. Commit — only after the analyst approves (or chooses to skip):

``bash python "${CLAUDE_SKILL_DIR}/scripts/brand.py" commit "" --status approved # or, to skip the step (allowed only once branding/branding.md exists): python "${CLAUDE_SKILL_DIR}/scripts/brand.py" commit "" --status skipped ``

On --status approved the script validates DESIGN-TOKENS.md has the required core; if it prints [REFUSED] listing missing sections, add them and re-run. On --status skipped it refuses unless branding/branding.md exists. On success it records the status and reports any downstream steps it marked stale. Relay the summary and tell the analyst to open a fresh conversation and run the next step (tableau-plan, or tableau-route to confirm).

The DESIGN-TOKENS schema

brand.py enforces the required core; the rest is recommended-but-optional.

| section | required? | what goes there | |---------|-----------|-----------------| | ## Colors | required | Backgrounds, accent bars, a cohesive ≤5-color series palette, text colors. | | ## Typography | required | Font family + sizes/weights for title, chart title, labels, tooltips. | | ## Spacing | required | Card padding, section spacing, container margins, accent-bar height. | | ## Fallback Decisions | required | Every value pulled from a Tableau default, flagged as guessed (or "None"). | | ## Source | optional | Which branding source produced these tokens. | | ## Dashboard Sizing | optional | Mode (default Range), min width/height, max (default Flex). | | ## Logo / ## Icons | optional | Brand assets to integrate; omit when none. |

The validator matches headings as case-insensitive substrings and allows extra custom sections, so a refined token file that keeps its own structure still passes.

Notes

• Skippable, but deliberately gated. Skipping records skipped in STATE.md

and yields neutral styling downstream (mock/build read DESIGN-TOKENS.md as an optional input — absent ⇒ neutral, CONTRACT.md §1). But skip is only offered once branding/branding.md exists, so the analyst can't bypass branding with zero brand intent on file.

• Defaults worth keeping (from references/tableau-design-tokens.md): the native

Tableau font family (Bold/Medium/Light); a cohesive ≤5-color palette (a dashboard speaks one color language); Range sizing with no max (Flex), not Automatic; worksheet headers hidden with the visible title as a Text object; a collapsible filter panel via a Show/Hide button.

• Root file, no version bump. Re-running refines the root DESIGN-TOKENS.md in

place and flips downstream approved steps to stale; it does not create a new version directory (DESIGN-TOKENS.md is a root "latest truth" file, CONTRACT.md §4.3).

> The full STATE.md schema and the ordering / staleness / versioning rules live in > CONTRACT.md at the repo root. This skill restates only its own slice; brand.py > is the executable mirror of the contract it enforces.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: laviDrori0702
• Source: laviDrori0702/tableau-dashboard-creator-skill
• License: MIT

Install and usage instructions live in the source repository linked above.