> ## Content Index
> Fetch the complete content index at: https://www.vizney.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# What design.md Changes in Tableau Data Apps, and What It Doesn't
- URL: https://www.vizney.com/tableau-data-apps-design-md/
- Published: 2026-11-18T12:56:38.000Z
- Updated: 2026-11-18T12:56:38.000Z
- Author: Yehwan Hwang
- Tags: Knowledge Base

An AI agent can build a working [Tableau Data App](https://www.vizney.com/what-is-tableau-data-apps/) quickly, but the screen it produces often looks like it could belong to any company. We built two apps from the same prompt, added a `design.md` with screen rules to only one of them, and published both to Tableau Cloud. The `design.md` changed number formats, colors, fonts, title style and the first-screen layout. It did not make screen-planning decisions, such as which period each card should cover. Keeping company-wide rules in `design.md` and per-screen decisions in `spec.md` makes it clear what you can hand to an agent and what a person still has to decide.

---

### 1\. Where does design.md go in a data app?

The data app template created by the `scaffold-data-app` tool in Tableau MCP includes a `Resources/.agents/` folder inside the `.twbx`. The template's README describes it as a place for docs read by the AI agents and people who build or change the app, and says Tableau ignores the folder at runtime. The app's web files, which are served to the browser, live separately under `Packages/<id>/content/`.

```
Superstore Sales B.twbx
├─ Superstore Sales B.twb
├─ Packages/<id>/content/   # app files served to the browser
└─ Resources/.agents/       # docs for agents (README.md, design.md)
```

In the data apps segment of Tableau Builder & DataDev Live on November 10, 2026, Tableau described this resources folder as the place to store, version and share spec.md files, design.md files and build notes. The docs are published and downloaded with the workbook, so whoever changes the app next, person or agent, starts from the same rules.

- **Tell the agent to read it:** The README asks agents to read every file in the folder before modifying the app. Saying so explicitly when you hand over the task is still more reliable.
- **Keep secrets out:** Anyone who can download the workbook can read this folder, so tokens, passwords and personal data must not go in it. Tableau's [security guidance](https://tableau.github.io/extensions-api/docs/dataapps/trex%5Fdataapp%5Fsecurity?ref=vizney.com) says the same about packaged resources.
- **Keep it when repackaging:** If you rebuild the `.twbx` without this folder, the docs go with it.

---

### 2\. What changed with the same prompt?

The two apps shared the prompt, data and agent setup, and differed in one file.

- **Prompt:** "Build a sales dashboard from the Superstore data for sales executives to review in their weekly meeting." (translated from Korean; both apps' screens are in Korean)
- **Shared setup:** Claude Code agents, the `Superstore Datasource` published on Tableau Cloud, and the same template, which queries data only through `queryAsync()` with no external origins
- **Shared instructions:** Read every doc in `Resources/.agents/` before starting, and bundle libraries and fonts in the package. Both agents also received the same base guidance, including a principle to start from the viewer and the decision.
- **The difference:** Only app B had a `design.md` in `Resources/.agents/`. It was the [Anthropic style](https://www.vizney.com/style-anthropic/) document from Vizney Styles, an unofficial reading of a publicly visible design. App A found and applied a general charting guide on its own while working.
- **Publishing:** Both apps were published to Tableau Cloud and checked against live data on November 18, 2026\. The [permissions and admin approvals needed to publish a data app](https://www.vizney.com/tableau-data-app-publish-permissions/) are covered separately.

Both apps showed the same numbers. Week 52 sales were down 7.8% on the same week last year, and year-to-date sales and profit were up 21.1% and 15.3%. The year-to-date profit margin was 12.8%, 0.6 points lower. The numbers come from the data source query, so what `design.md` changed was how those numbers were presented.

![App A without design.md: four tiles for sales, profit, margin and orders above a 13-week bar chart](https://storage.ghost.io/c/6a/50/6a50f03c-1922-4e90-bf18-c5abd0f819d4/content/images/2026/11/dataapp-a-first-screen-crop.jpg)

App A, built without design.md

![App B with design.md: a headline sentence on week 52 sales and year-to-date growth, a paragraph on the drivers, and four key figures](https://storage.ghost.io/c/6a/50/6a50f03c-1922-4e90-bf18-c5abd0f819d4/content/images/2026/11/dataapp-b-first-screen-crop.jpg)

App B, built with design.md

- **First screen:** A opens with four tiles for sales, profit, margin and orders. B opens with a sentence: "Week 52 sales were $21K, down 7.8% on the same week last year, but year-to-date sales are 21.1% higher than last year." A paragraph naming the drivers follows, with four key figures on the right. That is the first-screen order written in `design.md`.
- **Number formats:** A uses K suffixes and ▲▼ arrows, as in `$21.4K`. B uses 만 (units of 10,000), the usual way to shorten large numbers in Korean, with signed changes (+, −).
- **Color:** A draws this year as blue bars and last year as black ticks. B draws this year as an orange line and last year as a dashed gray line.
- **Titles:** A names what each chart shows, such as "Weekly trend" and "Performance by region." B states what was found, such as "Only Central's year-to-date sales fell on last year (−0.2%)," and adds "Figure 1" and "Table 1" labels and notes.
- **Fonts:** A uses system fonts. B bundles the Noto Sans KR and Noto Serif KR files named in `design.md`, along with their license file. The `design.md` gives a Google Fonts URL for web pages, but a data app without approved external origins loads only [files inside its package](https://tableau.github.io/extensions-api/docs/dataapps/trex%5Fdataapp%5Fdetails?ref=vizney.com).

App A is clean and its numbers are right. The difference is whether the screen follows conventions the company has already set. Those conventions are not in the data, so they have to be written down.

---

### 3\. What did design.md not prevent?

In app B, Figure 1 is titled "Sales beat the same week last year in 8 of the last 13 weeks." Its subtitle, though, reads "Weekly sales, weeks 1–52 of 2026 and the same weeks of 2025," and the chart draws the whole year. Nothing on the chart marks the 13 weeks the title refers to, so a reader cannot check the title against the chart. The screenshot below shows the app as published.

![Figure 1 and Table 1 in app B: Figure 1's title refers to the last 13 weeks, while its subtitle and line chart cover all 52 weeks of 2026](https://storage.ghost.io/c/6a/50/6a50f03c-1922-4e90-bf18-c5abd0f819d4/content/images/2026/11/dataapp-b-figure1-crop.jpg)

Figure 1 in app B, where the title and the chart cover different periods

`design.md` says a card title should state the finding and the subtitle should name the measure and the period, and app B followed both rules. The title follows the same pattern as the example in `design.md` (`Orders grew on last year in 11 of 12 months`), and the subtitle describes the chart's period correctly. What was missing was a decision: is this card about judging the last few weeks, or about showing the shape of the year? That is not a style rule, so it was in neither `design.md` nor the prompt, and as the agent filled the gap, the title and the chart ended up covering different periods.

With the same prompt, app A drew only the last 13 weeks in its weekly trend card. When nobody sets a card's period, the agent does, and the choice differed even with the same prompt. More rules in `design.md` won't fix this. Deciding each card's question and comparison period up front, then checking the title's period against the chart's before publishing, will.

---

### 4\. What goes in design.md, and what goes in spec.md?

In the same session, the presenter said their spec.md covers the core messages the app should get across and the query logic. One example of query logic is reusing calculations and semantics already in the data model rather than reinventing them. Their design.md covers fonts, colors and overall structure, and there is no required format yet. Based on this comparison, rules you want applied across the company belong in `design.md`, and decisions that change from screen to screen belong in `spec.md`.

What to write in `design.md`:

- **Number formats:** currency units and abbreviations, decimal places, signs for changes, and when to use percent versus percentage points
- **Color:** data colors for this year, last year, target and highlight, kept separate from brand colors, plus the rule for coloring good and bad changes
- **Titles and notes:** label titles or finding titles, figure and table numbering, and the note format
- **Layout:** the order of the first screen and the order inside a card (title → subtitle → chart → note)
- **Fonts and libraries:** font names with the files and licenses to bundle, and the chart library to use without external origins

What to write in `spec.md`:

- **Viewer and decision:** who decides what, in which meeting
- **Benchmark:** whether good or bad is judged against the same week last year, a target or the previous week
- **Question and period per card:** what each card answers and the period it shows, for example the last 13 weeks for the weekly trend
- **First screen and exclusions:** what must be visible without scrolling, and which measures to leave out
- **Query logic and checks:** reuse the data source's calculations, and before publishing, compare the numbers and each title's period with the source query

A good `design.md` can be reused across many apps, but a `spec.md` has to be written for each one. For more on what screen planning decides, see [why AI-built dashboards look plausible but don't get used](https://www.vizney.com/why-ai-dashboards-dont-get-used/). Before handing an app to an agent, it is best to have a person settle the `spec.md` items first.

---

The `design.md` in app B is the [Anthropic style](https://www.vizney.com/style-anthropic/) document from Vizney Styles, and more company style documents are at [styles.vizney.com](https://styles.vizney.com/?ref=vizney.com). To set up your company's `design.md` together with a `spec.md` for each screen, [contact us](https://www.vizney.com/contact-us/).

### Note:

This post is based on the following: a test on Tableau Cloud on November 18, 2026, the Tableau Data Apps [documentation](https://tableau.github.io/extensions-api/docs/dataapps/?ref=vizney.com) and [announcement blog](https://www.tableau.com/blog/what-are-tableau-data-apps?ref=vizney.com), and Tableau Builder & DataDev Live on November 10, 2026\. Tableau Data Apps are in beta and, according to the documentation, available only on Tableau Cloud. The template's `Resources/.agents/` folder and the conventions for these docs may change in later updates.