# Build guide: small local tools for people without a development setup

Complete text, all sections. Source: https://ai-build-guide.flomotlik.me/guide/ · Index: https://ai-build-guide.flomotlik.me/llms.txt

The audience is someone with a browser and a chat window — no terminal, no
editor, no package manager, no admin rights. Every rule below follows from that.

---

## 1. What to deliver

Read when: Always. Read this before writing any code — it constrains every other section.

### Who you are building for

Someone doing this alongside their actual job — an administrator, an
organiser, a volunteer. No development environment, no terminal, no code
editor, no package manager, no admin rights on the laptop. They have a
browser and a chat window with you. Their time budget is one evening.

Anything that requires them to install software, run a command, or start a
local server has failed before it starts. This is not a preference — it is the
constraint that decides whether the tool gets used.

### The deliverable

**A folder the user saves. `index.html` is what they double-click.**

How many files that folder holds is your choice. What matters is that it runs
from `file://` without anything being installed or started.

| Rule | Why |
|---|---|
| `index.html` runs by double-click | No server, no `npx`, no terminal |
| No build step, no bundler, no npm | They cannot run any of it |
| **No `<script type="module">`, no `import`** | Blocked on `file://` — the tool silently does nothing |
| **No `fetch()` of a local file** | Blocked on `file://` — put data in a `.js` file instead |
| Classic `<script src>` and `<link rel=stylesheet>` | These *do* work across files, including subfolders |
| Libraries from CDN, global (UMD) build, pinned version | No install; a floating version breaks the tool later |
| UI text in the language the tool will be *used* in | Not necessarily the language they wrote to you in — see below |

### Which language the interface is in

The language of the **use**, not the language of the request. Someone may
write to you in English about a tool for a Flemish town council — that tool
belongs in Dutch, because that is who will sit in front of it.

Derive it from where the tool will be used: the municipality, the institution,
the audience for its output. When the request itself and the place disagree,
and you cannot tell which one governs, **ask once** instead of guessing.

What follows the interface language, and is easy to forget:

- **Number and date format** — `nl-BE`, `de-AT`, `fr-BE`. A Belgian tool
  formatting amounts the German way looks broken to its user.
- **The name of the short readme** — `LEESMIJ.txt`, `LIESMICH.txt`,
  `README.txt`. See *Documenting the tool*.
- **Labels on exports and charts**, including the ones baked into an exported
  image.
- **Error messages**, which are the texts people actually have to understand.

Two things stay in English regardless, because they are not the interface:
this guide, and the rules file you leave for the next assistant
(`CLAUDE.md` / `AGENTS.md`). Those are read by machines and developers.

### One file or several?

Both are fine. Choose by handover cost, not by tidiness.

**Start with one file** when the tool is small *and you are handing it over
through a chat*. It is the easiest thing to save out of a conversation, to
email, and to keep track of. For a calculator, a form, a checklist, a single
analysis — one file is right, and splitting it is busywork.

**If you can write files into a folder yourself** — an agentic assistant, a
workspace with file output — that argument disappears: there is no handover to
get wrong, so split whenever it aids readability. Read *How you are
delivering* next; it also covers the trap that comes with having a terminal
the user does not have.

**Split into several files** when the tool genuinely earns it: a few hundred
lines of logic, a sizeable data table, a stylesheet worth reading on its own.
A flat folder is the usual shape:

```text
mein-werkzeug/
├── index.html
├── app.js
├── daten.js
└── stil.css
```

```html
<link rel="stylesheet" href="stil.css">
...
<script src="daten.js"></script>
<script src="app.js"></script>
```

Scripts run in document order, so a global defined in `daten.js` is available
in `app.js`. Verified working from a double-clicked file, subfolders included.

**Keep the folder flat when you split.** Nested directories work technically,
but every extra path is another chance for the user to save a file in the
wrong place. `index.html` + two or three siblings is the sweet spot.

**Say how to save it.** When you hand over more than one file *in a chat*,
name each file explicitly and say they all go in the same folder. That is the
only part of multi-file delivery that is genuinely harder for the user — and
it does not apply when you write the folder yourself.

### Data belongs in a .js file, not a .json file

`fetch('daten.json')` fails from `file://` — Chrome reports *URL scheme "file"
is not supported*. Do not use it, and do not work around it with a local
server.

Instead, write the data as JavaScript that assigns a global:

```js
// daten.js
window.DATEN = {
  gemeinden: [
    { name: 'Oberndorf', einwohner: 5700 },
    { name: 'Herzogenburg', einwohner: 8300 }
  ]
};
```

Same content, loads with a plain `<script src="daten.js">`, and the user can
still open and edit it in any text editor.

### What DOES work from a double-clicked file

Verified in Chromium: `window.isSecureContext` is `true` for a local file, so
the following are all available without a server.

- `localStorage`, `sessionStorage`, `IndexedDB`
- File System Access API: `showOpenFilePicker`, `showSaveFilePicker`,
  `showDirectoryPicker` (Chrome/Edge — always ship the download fallback, see
  *Saving results*)
- `<canvas>` including `toBlob()` and `toDataURL()`
- Clipboard API
- CSS, fonts, images and scripts from a CDN
- Your own CSS, JS and images by relative path

### What does NOT work

- **ES modules.** `<script type="module">` and `import` fail with a CORS error
  against origin `null`. This is the single most common way a delivered tool
  arrives dead.
- **`fetch()` / `XMLHttpRequest` on a local file.** See above.
- Service workers, and anything else needing a real origin.

### The skeleton to start from

```html
<!doctype html>
<html lang="de">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Tool name</title>
<link rel="stylesheet" href="https://design-system.flomotlik.me/design-system.css">
<style>
  body {
    margin: 0;
    padding: 1.5rem;
    background: var(--fm-color-surface);
    color: var(--fm-color-text);
    font-family: var(--fm-font-copy);
  }
  main { max-width: 60rem; margin: 0 auto; }
</style>
</head>
<body>
<main>
  <h1>Tool name</h1>
  <!-- UI here -->
</main>
<script>
  // Logic here, or in a sibling file via <script src>. No imports.
</script>
</body>
</html>
```

The `body` rules are not optional: the design system deliberately styles no
HTML tags, so without them the page renders as unstyled serif text and looks
broken. See *Making it look right*.

### How to scope the first version

Build the smallest thing that actually answers their question, then stop and
let them use it.

**Smallest is measured against the question, not against a screen count.**
Test every control you are about to add:

> Can they answer the question they asked me without this element?
> If yes, leave it out. If no, it belongs in the first version.

A year selector in a tool for comparing years is not feature creep — without
it the tool does not answer the question. A settings panel nobody asked for
is. The difference is whether the element follows from the request or from
your own enthusiasm.

- **No login, no onboarding, no accounts, no user management.** These never
  follow from the question.
- **No second job.** A tool that reads budgets does not also send newsletters.
  One tool, one question.
- **Real data from the start** — ask for an actual file or three real rows.
- **If the task happens only once**, say so: a chat answer is the better tool
  and building anything is waste.

Then ship it before adding anything else. What they still miss after using it
three times is a real feature; what occurred to you while building usually is
not.

### When this stops being enough

Only when the user needs a public address, several linked pages, or other
people contributing. That is a different shape of project — see *Going
further*.

---

## 2. How you are delivering

Read when: Always, right after 'What to deliver'. It decides how many files you produce and what you may leave behind.

### Two modes, different handover cost

The runtime constraints never change: the user double-clicks `index.html`, has
no build step, no server, no ES modules. What changes is how the files reach
them.

**Chat mode.** You emit text; the user copies or downloads it and saves it
themselves. Every additional file is a manual step they can get wrong — a
typo in a filename, a file saved to Downloads instead of the folder, a `.txt`
extension added silently.

**File-access mode.** You write into a folder directly. Tools of this kind —
agentic coding assistants, workspace assistants, project workspaces with file
output, and equivalents from other vendors — remove the handover entirely.

You usually know which one you are in: if you have a tool that writes files,
you are in file-access mode. If unsure, ask, or assume chat mode, which is the
stricter of the two.

| | Chat mode | File-access mode |
|---|---|---|
| Number of files | Prefer one; a few flat siblings at most | Split whenever it helps |
| Naming | Say every filename and where it goes | Just write them |
| Changing something | Re-emit the whole file | Edit in place |
| Sample data | Paste it inline | Write a real `daten.js` |
| Verification | The user reports back | Open it yourself and look |

The preference for a single file in *What to deliver* is a **chat-mode**
argument. It does not apply when you write the folder yourself.

### The trap in file-access mode

You may have a terminal. **The user does not.** Nothing you can run is
available to them afterwards.

So, however capable your environment is:

- **Do not add a build step.** No bundler, no transpiler, no CSS framework
  that must be compiled. A tool that needs `npm run build` before it can be
  changed is dead the moment you stop working on it.
- **Do not add a dependency manifest** — no `package.json`, no `node_modules`
  — unless the user has asked for a real project and understands what it
  implies. See *Going further*.
- **Do not leave generated output as the only source.** If a file is minified
  or compiled, the user cannot read or fix it.
- **Do not rely on a local server** to make it work. It still has to open by
  double-click.

The test: *if the user opened this folder in six months with nothing but a
browser and a text editor, could they still use it and change one label?* If
not, simplify.

### What file-access mode lets you do better

- **Split for readability.** `index.html`, `app.js`, `daten.js`, `stil.css` —
  no handover penalty. Keep it flat anyway; the user still has to find things.
- **Write real sample data.** A `daten.js` with twenty invented but realistic
  rows beats asking the user to paste their real list. See *Data protection*.
- **Iterate in small steps.** Change one thing, check it, then the next. You
  do not have to re-emit a whole file to fix one line.
- **Actually open the tool and check it.** You produced it; verify it does
  what it claims before saying it is finished. Load it, feed it the sample
  data, confirm the numbers.
- **Leave a short `LIESMICH.txt` / `README.txt`** in the folder — see
  *Documenting the tool* for what goes in it. In chat mode it is an optional
  extra; here it costs nothing, so write it.
- **Leave a rules file** (`CLAUDE.md` or `AGENTS.md`) if the tool will be
  worked on again, so the next session does not have to be re-briefed. Write
  it yourself — the user should never have to compose one. It is documentation
  for the next assistant, not for the user; the two are separate files.

### Reading files is not the same as the tool fetching them

In file-access mode you can read the user's real CSV to understand its shape.
The tool you build still cannot: `fetch()` on a local file is blocked at
runtime.

So use your access to *learn the structure* — column names, separator,
encoding, a few real values — and then build the tool to take the file through
a file picker or drag-and-drop, as described in *Reading files*. Do not bake
the user's data into the tool unless they asked for exactly that.

---

## 3. Reading files

Read when: The tool takes a document, spreadsheet, export or image from the user.

Everything happens on the device. The file is never uploaded — there is no
server that could receive it. Say this in the UI; for this audience it is the
deciding feature, not a detail.

That is true of the **finished tool**. It is not true of you while you are
building it. Before you read a file the user points you at, run the precheck in
*Data protection* — filename and header row first, flag the personal-data
columns, and stop there if any turn up. Once a file is in the conversation it
cannot be taken back out.

### Always offer both ways in

A file picker alone is a usability bug: people drag files. A drop zone alone
is worse: it is invisible on touch devices.

```html
<div class="fm-dropzone" id="zone">
  <p class="fm-dropzone__label">Datei hierher ziehen</p>
  <button class="fm-btn fm-btn--secondary fm-dropzone__trigger" id="pick">
    Datei auswählen
  </button>
  <input type="file" id="input" accept=".csv,.pdf" multiple hidden>
</div>
```

```html
<script>
var input = document.getElementById('input');
var zone = document.getElementById('zone');

document.getElementById('pick').addEventListener('click', function () {
  input.click();
});
input.addEventListener('change', function () {
  handleFiles(Array.prototype.slice.call(input.files));
});

['dragenter', 'dragover'].forEach(function (ev) {
  zone.addEventListener(ev, function (e) {
    e.preventDefault();
    zone.classList.add('is-dragover');
  });
});
['dragleave', 'drop'].forEach(function (ev) {
  zone.addEventListener(ev, function (e) {
    e.preventDefault();
    zone.classList.remove('is-dragover');
  });
});
zone.addEventListener('drop', function (e) {
  handleFiles(Array.prototype.slice.call(e.dataTransfer.files));
});
</script>
```

`fm-dropzone` and `is-dragover` come from the design system and carry the
dashed border and the highlight state.

### Getting the content out

```js
async function handleFiles(files) {
  for (const file of files) {
    if (/\.(csv|txt|json)$/i.test(file.name)) {
      const text = await file.text();
      // ...
    } else {
      const bytes = await file.arrayBuffer();   // PDF, XLSX, images
      // ...
    }
  }
}
```

Note: `async`/`await` and arrow functions are fine — they are language
features, not modules. Only `import` is off limits.

### Per format

**CSV.** Do not write your own splitter. Quoted fields, embedded semicolons
and newlines inside cells will break it, and the user will not notice until
the numbers are wrong. Load a parser from CDN as a global. Also: files from
Austrian and German offices are usually semicolon-separated, Windows-1252
encoded, and use a comma as the decimal mark. Detect the separator, and offer
an encoding switch if the first read shows mojibake.

**XLSX.** Needs a library. If the user controls the file, the cheaper answer
is "save it as CSV in Excel first" — say so instead of pulling in a heavy
dependency.

**PDF with a text layer.** Use **PDF.js 3.11.174** — the last release that
ships a classic, non-module build. Verified working from a double-clicked
file, with and without the CDN worker:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>
```

```js
// Sets a global `pdfjsLib`. The worker is optional — without it PDF.js
// parses on the main thread, which is fine for a few hundred pages.
pdfjsLib.GlobalWorkerOptions.workerSrc =
  'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js';

const doc = await pdfjsLib.getDocument({ data: await file.arrayBuffer() }).promise;
for (let n = 1; n <= doc.numPages; n++) {
  const items = (await (await doc.getPage(n)).getTextContent()).items;
  // items[i].str is the text, items[i].transform[4]/[5] are x and y
}
```

Do **not** take PDF.js 4.x or 5.x: those ship only `.mjs` ES-module builds,
which are blocked on `file://`. Pin 3.11.174.

For tables, plain concatenated text is not enough — use the positions.
`getTextContent()` gives each fragment an x and a y; group fragments with a
similar y into a row, then split a row into cells on x-gaps. Two tolerances
control this and they differ per document type, so make them easy to adjust
and show the user the recognised rows before interpreting them.

Expect this to be the most expensive part of the tool. Say so before
committing to it.

**Scanned PDF.** There is no text, only images. This needs OCR, and the error
rate becomes its own problem. Say this rather than producing silently wrong
output.

**Images.** `URL.createObjectURL(file)` for display, or draw into a canvas for
processing. Call `URL.revokeObjectURL()` afterwards.

### Show what was read before you interpret it

First version: read the file and display what was recognised — row count, the
first rows, detected columns. No analysis yet.

This is not a debugging step you can skip. It is the only point where the user
can catch "it read the wrong column" before that error is buried inside a
result they will quote in a council meeting.

Always state the row count and make the tool refuse loudly on a file it does
not recognise, rather than producing an empty table.

---

## 4. Saving results

Read when: The tool produces something the user keeps: a table, a report, an image, an edited file.

### Baseline: download (always implement this)

Works in every browser, needs no permission, works from `file://`.

```js
function download(content, filename, type) {
  const blob = new Blob([content], { type: type || 'text/csv;charset=utf-8' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  URL.revokeObjectURL(url);
}
```

For CSV opened in Excel, prepend a BOM or the separator hint, otherwise
umlauts break and columns collapse into one:

```js
download('' + csvText, 'auswertung.csv');
```

For most tools this is the whole story. Do not add complexity on top of it
unless the user edits the same file repeatedly.

### Enhancement: write back into the same file

Chrome and Edge can open a file, change it, and save it back to the same
location — no growing pile of `auswertung (3).csv` in Downloads. Available
from `file://` too, since a local file counts as a secure context.

```js
let handle = null;

async function openFile() {
  const picked = await window.showOpenFilePicker({
    types: [{ description: 'CSV', accept: { 'text/csv': ['.csv'] } }],
  });
  handle = picked[0];
  const file = await handle.getFile();
  return file.text();
}

async function saveBack(text) {
  if (!handle) {
    handle = await window.showSaveFilePicker({ suggestedName: 'auswertung.csv' });
  }
  const stream = await handle.createWritable();
  await stream.write(text);
  await stream.close();
}
```

A whole folder works too, for "process every PDF in this directory":

```js
const dir = await window.showDirectoryPicker({ mode: 'readwrite' });
for await (const [name, h] of dir.entries()) {
  if (h.kind === 'file' && name.endsWith('.pdf')) {
    const file = await h.getFile();
    // ...
  }
}
```

### The rules that make it fail

1. **Chromium only.** Chrome and Edge yes; Firefox and Safari no.
2. **Must follow a user gesture.** Calling it from a timer, on page load, or
   after an `await` that loses the gesture throws.
3. **Permission does not survive a reload.** Re-request it, which needs
   another click. Storing the handle in IndexedDB lets you re-ask instead of
   re-pick:
   ```js
   if (await handle.queryPermission({ mode: 'readwrite' }) !== 'granted') {
     await handle.requestPermission({ mode: 'readwrite' });  // needs a click
   }
   ```

Therefore: **always feature-detect and always keep the download path.**

```js
const canWriteBack = 'showSaveFilePicker' in window;

async function exportResult(text, filename) {
  if (canWriteBack) {
    try { return await saveBack(text); }
    catch (e) { /* user cancelled or it failed — fall through */ }
  }
  download(text, filename);
}
```

Never present write-back as the only way out. A tool that cannot export in
Firefox is a broken tool, not a Chrome-optimised one.

### Other exits

- **Clipboard** — often the best export for text that goes into an email or a
  document: `navigator.clipboard.writeText(text)`. Needs a user gesture.
- **Print / PDF** — a `@media print` block plus `window.print()` beats
  generating a PDF in JavaScript for almost every case.
- **Image** — see *Generating images*.

---

## 5. Keeping data

Read when: Anything should survive closing the tab: settings, entered data, imported files.

There is no server, so there is no central database — and that is usually the
point. The only question is what survives closing the tab.

| Need | Use | Limit |
|---|---|---|
| Settings, last selection, a draft | `localStorage` | strings only, a few MB |
| Imported files, parsed records, long lists | IndexedDB | clumsy API |
| Real queries across tables | SQLite compiled to WebAssembly | extra library, real effort |

Pick the lowest rung that works. Most tools never leave `localStorage`.

### localStorage

```js
var KEY = 'toolname.settings';

function saveSettings(obj) {
  try { localStorage.setItem(KEY, JSON.stringify(obj)); } catch (e) {}
}

function loadSettings() {
  try { return JSON.parse(localStorage.getItem(KEY)) || {}; }
  catch (e) { return {}; }
}
```

Two habits that prevent later grief: **prefix every key** with the tool name,
and **wrap every read** — the stored value may come from an older version, or
the browser may refuse storage entirely (private window, blocked site data).
A tool that throws on startup because of a stale setting is a tool nobody
opens twice.

### IndexedDB

For parsed data sets, imported files, anything beyond a few hundred kilobytes.
The raw API is unpleasant enough that a small CDN wrapper is the one
justified exception to "write it yourself".

It works everywhere, including from a double-clicked file. It needs **no**
OPFS and **no** cross-origin isolation (`COOP`/`COEP`). If you find yourself
reaching for those headers, the approach is wrong for this context.

### SQLite in the browser

Only for genuine analysis — grouping, joins, multi-year comparison. The
pattern that holds up: open the database in memory, run the schema and the
queries, then serialise the whole database to a byte array and store that in
IndexedDB; restore it on the next start. No special headers required, so it
still works on a static host.

This is a multi-session project, not an evening. Only propose it when the
analysis genuinely needs SQL.

### Asking the browser not to throw it away

Browsers evict site data under disk pressure, and a tool that parked a parsed
dataset in IndexedDB is a fat target. You can ask for it to be spared:

```js
async function keepStorage() {
  if (!navigator.storage || !navigator.storage.persist) return false;
  try { return await navigator.storage.persist(); } catch (e) { return false; }
}

async function storageLeft() {
  if (!navigator.storage || !navigator.storage.estimate) return null;
  try { return await navigator.storage.estimate(); }   // { usage, quota }
  catch (e) { return null; }
}
```

Treat a `false` as the normal case, not an error. It is a request, not a
setting: the browser decides, it may refuse without explanation, and from a
double-clicked file it may not be granted at all. Feature-check both, wrap
both, and never let either one block startup.

So it does not change what you must tell the user below — it only improves the
odds. **An export button is still the actual backup.**

### What the tool must tell the user

Device-bound storage has consequences that belong in the UI, not in a footnote:

- The data lives **only in this browser on this device**. Another laptop,
  another browser, a private window: empty.
- **Clearing browser data deletes it**, without warning.
- **There is no backup.**

So: an export button is mandatory as soon as a tool keeps anything. Offer
import of the same format, and the user has a backup and a way to move between
devices. See *Saving results*.

---

## 6. Tables and numbers

Read when: The tool shows rows of data or does arithmetic the user will quote.

Most of these tools are, at heart, a table plus a number. Get both right and
the tool is credible.

### Markup

```html
<div class="fm-table-scroll">
  <table class="fm-table fm-table--zebra">
    <thead>
      <tr><th>Ansatz</th><th class="fm-table__num">2025</th><th class="fm-table__num">2026</th></tr>
    </thead>
    <tbody id="rows"></tbody>
    <tfoot>
      <tr><th>Summe</th><td class="fm-table__num" id="sum25"></td><td class="fm-table__num" id="sum26"></td></tr>
    </tfoot>
  </table>
</div>
```

`fm-table__num` right-aligns and switches on tabular figures so digits line
up in columns. `fm-table-scroll` keeps a wide table scrolling inside itself
instead of breaking the page on a phone. `fm-table--compact` and
`--dense` exist for data-heavy views.

### Formatting numbers

Never print a raw float at an Austrian or German audience.

```js
var euro = new Intl.NumberFormat('de-AT', {
  style: 'currency', currency: 'EUR', maximumFractionDigits: 0
});
var num = new Intl.NumberFormat('de-AT');

euro.format(1234567.8);   // "1.234.568 €"
num.format(0.385);        // "0,385"
```

Reading them back is the mirror problem: `"1.234,50"` must become `1234.5`,
not `NaN` and not `1.234`. Strip thousands separators, then swap the decimal
comma.

### Arithmetic that survives scrutiny

- **Round only for display.** Compute on full precision; a table whose rounded
  rows do not add up to the rounded total destroys trust instantly.
- **For money, work in cents** (integers) when you sum many values, and
  divide at the end.
- **Always show a total row** and, where the data allows, a check: the sum of
  the parts against an independently stated total. Display the discrepancy
  when it does not match instead of hiding it.
- **Never silently drop rows.** If 12 of 340 rows could not be parsed, say
  "328 von 340 Zeilen gelesen, 12 übersprungen" and let the user see which.

### Sorting and filtering

Plain JavaScript. No grid library — for a few thousand rows it is unnecessary
weight, and it fights the design system.

```js
rows.sort(function (a, b) { return b.betrag - a.betrag; });
```

Use `localeCompare('de')` for text so umlauts sort correctly. Above roughly
5,000 rows, render only what is visible or paginate; below that, just redraw
the `<tbody>`.

Make the active sort and filter visible in the UI. A filtered table that looks
like a complete one is how wrong numbers end up in a council meeting.

---

## 7. Charts

Read when: The tool visualises numbers.

### Choose the form from the claim

Most useless charts exist because the shape was chosen before the statement.

| The claim | The form |
|---|---|
| "More than last year" | grouped bars |
| "This is how the total splits" | stacked bar — not a pie |
| "This is the trend over the years" | line |
| "One number decides it" | the number itself, `fm-metric-card` |
| "Where it comes from, where it goes" | Sankey |

A pie with seven slices says less than a sorted list. For a single figure, the
figure beats every chart.

### ECharts, without modules

```html
<script src="https://cdn.jsdelivr.net/npm/echarts@5.5.1/dist/echarts.min.js"
        crossorigin="anonymous"></script>
```

This build sets a global `echarts` — it works from a classic `<script>` and
from a double-clicked file. **Pin the version.** Verified working from
`file://`.

The design system also publishes `fm-charts.js` with the palette and axis
helpers, but it is an **ES module**: `import` fails on `file://` however many
files the tool has. Read
the tokens from CSS instead — same colours, no module:

```js
function palette() {
  var s = getComputedStyle(document.documentElement);
  var out = [];
  for (var i = 1; i <= 8; i++) {
    out.push(s.getPropertyValue('--fm-web-chart-' + i).trim());
  }
  return out;
}

var chart = echarts.init(document.getElementById('chart'));
chart.setOption({
  color: palette(),
  tooltip: { trigger: 'axis' },
  grid: { left: 60, right: 20, top: 30, bottom: 40 },
  xAxis: { type: 'category', data: jahre },
  yAxis: { type: 'value', name: 'EUR' },
  series: [{ type: 'bar', data: werte }],
});
window.addEventListener('resize', function () { chart.resize(); });
```

The container needs an explicit height — ECharts renders nothing into a
zero-height div, with no error. This is the most common "the chart is blank"
cause.

### What every chart needs

- **Axis labels with the unit.** "EUR", "Anzahl", "%".
- **A source and a date** near the chart. Without them it is not quotable in a
  council meeting.
- **A y-axis that starts at zero** for bars. A truncated axis is how you lose
  an argument about honesty rather than about the matter.
- **Rounded, formatted tick labels** — `de-AT` formatting, not raw floats.
- **A text alternative.** A sentence stating what the chart shows, for anyone
  who cannot see it.

### Simple graphics: inline SVG

For a schematic, a share, a small diagram, no library is needed. SVG is text,
scales, and takes design-system colours:

```html
<svg viewBox="0 0 120 40" role="img" aria-label="3 von 5 Fahrzeugen elektrifizierbar">
  <rect x="0" y="0" width="72" height="40" fill="var(--fm-web-chart-1)"/>
  <rect x="72" y="0" width="48" height="40" fill="var(--fm-web-chart-4)"/>
</svg>
```

`role="img"` plus `aria-label` is not optional — without it the graphic does
not exist for part of the audience.

### Exporting a chart

```js
var url = chart.getDataURL({ pixelRatio: 3, backgroundColor: '#fff' });
```

Set the white background explicitly. A transparent PNG turns black when
pasted into Word or PowerPoint.

---

## 8. Generating images

Read when: The tool produces a picture: a sharepic, a graphic for a newsletter, a poster draft, an annotated screenshot.

### Canvas to file

```js
canvas.toBlob(function (blob) {
  var url = URL.createObjectURL(blob);
  var a = document.createElement('a');
  a.href = url;
  a.download = 'grafik.png';
  a.click();
  URL.revokeObjectURL(url);
}, 'image/png');
```

Works from a double-clicked file. Use PNG for graphics and text, JPEG only for
photographs (`toBlob(cb, 'image/jpeg', 0.9)`).

### Screen size is not print size

A canvas sized to look right on screen produces a blurry print. Two ways out:

1. **Size the canvas at target resolution**, then shrink the *display* with
   CSS. Everything is drawn once, at full quality.
   ```js
   var dpi = 300, mmPerInch = 25.4;
   canvas.width  = Math.round(210 / mmPerInch * dpi);   // A4 width  = 2480 px
   canvas.height = Math.round(297 / mmPerInch * dpi);   // A4 height = 3508 px
   canvas.style.width = '210mm';                        // displayed small
   ```
2. **Draw at screen scale and export with a multiplier** — redraw into an
   offscreen canvas scaled by `ctx.scale(f, f)` before exporting.

Common targets: 1080×1080 and 1080×1350 for social, 1920×1080 for a slide,
A5–A2 at 300 dpi for print.

### Text on a canvas

Canvas has no text wrapping. Measure and break lines yourself with
`ctx.measureText()`. Load the brand font before drawing, or the first render
silently uses a fallback:

```js
await document.fonts.load('700 48px "Barlow Semi Condensed"');
await document.fonts.ready;
// only now draw
```

### Working from a user-supplied photo

```js
var img = new Image();
img.onload = function () { ctx.drawImage(img, 0, 0, w, h); };
img.src = URL.createObjectURL(file);
```

A local file drawn into a canvas does not taint it, so `toBlob()` keeps
working. An image loaded from another domain **does** taint the canvas and
export throws — so never pull the photo from a remote URL when the user will
export.

### Two things that matter politically

- **Rights.** For anything published: own photos or clearly licensed material,
  and a credit line where required.
- **Label AI-generated imagery.** Using synthetic images in political
  communication without disclosure invites exactly the debate the user did not
  want to have. Offer a visible label and make it the default.

---

## 9. Making it look right

Read when: Always, for anything with a user interface.

### One link

```html
<link rel="stylesheet" href="https://design-system.flomotlik.me/design-system.css">
```

No npm, no build, no install. Verified working from a double-clicked local
file.

Never copy the file into the project. The same goes for fonts and libraries:
link them, do not vendor them.

For a tool whose look must not shift later — something archived, printed or
handed on — link the frozen version instead:

```html
<link rel="stylesheet" href="https://design-system.flomotlik.me/v1/design-system.css">
```

### The four lines everybody forgets

The design system deliberately styles **no HTML tags** — no `body`, no `h1`.
Without your own base layout the page renders as serif text on white and looks
like the stylesheet failed. Minimum:

```css
body {
  margin: 0;
  background: var(--fm-color-surface);
  color: var(--fm-color-text);
  font-family: var(--fm-font-copy);
}
```

### Use the components that exist

| Need | Class |
|---|---|
| Button | `fm-btn`, `fm-btn--primary`, `fm-btn--secondary` |
| Card | `fm-card`, `fm-card__title`, `fm-card__body` |
| Notice | `fm-callout` with `--info` / `--warn` / `--error` / `--success` / `--legal` |
| Table | `fm-table`, `--zebra`, `--compact`, `fm-table__num` |
| Drop zone | `fm-dropzone`, state class `is-dragover` |
| Toast | `fm-toaster` + `fm-toast--info/success/warn/error` |
| Toolbar | `fm-toolbar`, `fm-toolbar__actions` |
| Single figure | `fm-metric-card`, `fm-metric-card__num` |
| Status label | `fm-tag` with `--ok` / `--warn` / `--error` / `--info` |
| Form field | `fm-field`, `fm-field__label`, `fm-input`, `fm-select` |
| Header | `fm-header`, `fm-header__inner`, `fm-header__brand` |
| Tabs | `fm-tabbar`, `fm-tab`, `fm-tab-panel` |
| Body text | `fm-prose`, `fm-headline`, `fm-subline` |

Values come from tokens: `--fm-color-*`, `--fm-space-1..6`, `--fm-text-*`,
`--fm-radius-*`. Hard-code a value only where no token fits.

The full style guide with live markup is at
<https://design-system.flomotlik.me/>, a minimal working page at
<https://design-system.flomotlik.me/examples/minimal.html>.

### Colours are named by role, not by hue

There is no `--fm-color-blue`. The tokens say what a colour is *for*:
`--fm-color-primary` carries the main action, `--fm-color-secondary` is a
surface that carries dark text, `--fm-color-accent` is the accent. That is
what makes the look changeable without touching a single component — see
*Adapting the look*.

One group is deliberately **not** changeable: `--fm-web-status-*` and the
`warn` / `error` / `success` variants. Green means ok and red means error in
every tool. Do not recolour them to match anything.

### What the design system does not do for you

- **375 px.** Half the audience opens it on a phone. A twelve-column table is
  unusable there however well it is styled — collapse it, scroll it inside
  `fm-table-scroll`, or show fewer columns.
- **Keyboard.** Everything reachable by Tab, focus always visible. Anything
  that only responds to a mouse is broken for some users.
- **Real labels.** A placeholder is not a label; it disappears on typing. Use
  `<label for>`.
- **States.** Loading, done, failed. A tool that does nothing visible for
  twenty seconds after a click is assumed broken and closed.
- **Contrast.** Grey-on-light is unreadable on a projector in a meeting room.
- **Errors in plain language.** "This file has no text layer — it was probably
  scanned" beats any exception text.

---

## 10. Adapting the look

Read when: The tool represents an organisation with its own colours, or the default look is wrong for the job.

The design system ships a neutral default. When a tool belongs to an
organisation with its own colours, you do not fork the stylesheet and you do
not drop it — you override a short list of tokens.

### Ask first. This is not automatic.

Do **not** rebrand because the user mentioned an organisation. Adapt the look
only when you know who the tool represents, and say what you are doing:

- The user names an organisation → ask which colours apply, or whether they
  want it neutral.
- The user works somewhere but the tool is for their own use → the default is
  fine. Nobody needs a rebrand for a spreadsheet replacement.
- The user says nothing about branding → leave it alone and mention once that
  it can be adapted.

Using an organisation's branding without being asked is worse than using none.

### The hook: one extra stylesheet

Create `local.css` next to `index.html` and link it **after** the design
system:

```html
<link rel="stylesheet" href="https://design-system.flomotlik.me/design-system.css">
<link rel="stylesheet" href="local.css">
```

```css
/* local.css — colours for <organisation>.
   Source of the values: <style guide, URL, or who supplied them>, <date>.
   Override tokens only; never rebuild a component. */
:root {
  /* Brand roles */
  --fm-color-primary:        #1f4a6d;   /* carries white text */
  --fm-color-primary-strong: #14324a;   /* deepened, for opacity stacking */
  --fm-color-secondary:      #8fb4cc;   /* surface, carries dark text */
  --fm-color-accent:         #9a4a1c;   /* accent, carries white text */

  /* Screen layer — header, rules, tints, focus ring */
  --fm-web-primary-deep:     #245a80;
  --fm-web-primary:          #5b8cad;
  --fm-web-primary-tint:     #e4edf4;

  /* Chart palette: first one may carry the brand, the rest must stay
     distinguishable from each other */
  --fm-web-chart-1: #2f6f96; --fm-web-chart-2: #c08a2e;
  --fm-web-chart-3: #4e8f6d; --fm-web-chart-4: #a8503c;
  --fm-web-chart-5: #6d5b9e; --fm-web-chart-6: #4fb0ad;
  --fm-web-chart-7: #6b4a2e; --fm-web-chart-8: #7d838c;

  /* Type — only if a different face is genuinely prescribed */
  /* --fm-font-headline: "Your face", sans-serif; */
  /* --fm-font-copy:     "Your face", sans-serif; */
}
```

That is the whole list. Because the tokens are named by **role** rather than
by hue, there is nothing to translate: `--fm-color-primary` is the primary
colour whatever colour it happens to be.

**Why a plain `:root` block is enough:** the design system's defaults live
inside `@layer` rules, and unlayered declarations beat layered ones regardless
of order.

Derived values follow on their own — the focus ring and the table stripe are
computed from the tokens above with `color-mix`, so they come along without
being listed.

### What to leave alone

- **Status colours.** `--fm-web-status-*`, and the `warn` / `error` /
  `success` variants of callouts, tags and toasts. Green means ok and red
  means error in every organisation; recolouring them to match a brand
  destroys the meaning. The one exception is `info`, which draws from the
  primary tint and follows the brand on purpose.
- **Spacing, radii, font sizes.** `--fm-space-*`, `--fm-radius-*`,
  `--fm-text-*`. These are the layout rhythm, not the brand.
- **Text and surface colours**, unless the brand genuinely demands it — they
  are what carries the contrast.
- **Component classes.** Never redefine `.fm-btn` and friends in `local.css`.
  The moment you restyle components instead of tokens, the next design-system
  update breaks your tool silently.

### The brand colour is usually too light. Plan for it.

This is the most common failure, not an edge case. `--fm-color-primary` and
`--fm-web-primary-deep` carry **white text**, so they need a contrast ratio of
at least **4.5:1 against white**.

Many brand colours are bright, because they were chosen for print and logos,
not for white text on screen. When the brand colour fails:

**Do not change the brand colour.** Split the roles instead:

```css
:root {
  /* the brand colour stays where it works as a surface */
  --fm-color-secondary:    #78be20;   /* brand colour, as a surface */
  --fm-web-primary-tint:   #eef7e2;   /* light fill, dark text on it */

  /* a darkened variant everywhere white text sits on it */
  --fm-color-primary:      #3f6610;   /* derived from the brand colour */
  --fm-web-primary:        #3f6610;
  --fm-web-primary-deep:   #2e4b0b;
}
```

Say in the file that the darker value is derived from the brand colour for
legibility, not invented. That is a decision someone will otherwise "correct"
back later.

### The logo

The header logo is a file, not a token:

```html
<img class="fm-header__logo" src="logo.svg" alt="<Organisation>">
```

Put the organisation's own file next to `index.html`. The design system ships
no logo of its own. If you have no logo file, use the wordmark alone —
`fm-header__wordmark` with the name in it looks deliberate, a stretched or
recoloured logo does not. Never recolour somebody else's logo to fit.

### Check it afterwards, do not assume

- **Contrast.** Measure, do not eyeball: white text on the primary button, the
  body text, and anything sitting on a tinted surface. 4.5:1 for normal text,
  3:1 for large text.
- **The chart palette.** Eight colours must stay distinguishable from each
  other, including for the most common colour-vision deficiencies. Two shades
  of the same brand colour next to each other in a stacked bar are a problem,
  not a brand.
- **Look at the page.** Load it and check the header, a primary button, a
  table and a chart. Token overrides are cheap to get almost right and easy to
  get subtly wrong.

### Write down what you changed

In `local.css`, state where the colour values came from and when — a style
guide, a website, or simply "the user gave these". A future reader has to be
able to tell a decision from a guess. This is the same rule as in
*Documenting the tool*.

If the tool represents no organisation at all, leave the default alone. It is
deliberately neutral.

---

## 11. Documenting the tool

Read when: Before you hand anything over. Applies to every tool, however small.

The person using this will come back to it in eight months, having forgotten
everything, possibly having lost the conversation. Someone else may inherit it
entirely. Documentation is what makes that survivable — and almost none of it
belongs in a separate file.

Order of priority: **in the tool**, then **one readme next to it**, then
**comments in the code**. Most tools need only the first two.

### 1. In the tool itself

This is the only documentation that is certain to be read, because it is on
screen while the tool is being used. Five things, none of them long:

**A one-line purpose under the title.** What it does and who it is for, in the
user's language.

```html
<h1>Voranschlag-Vergleich</h1>
<p class="fm-subline">
  Zwei Voranschläge als PDF gegenüberstellen — Abweichungen je Ansatz,
  für die Vorbereitung der Gemeinderatssitzung.
</p>
```

**Help where the question arises**, not in a manual. At the drop zone, say
which format is expected; at an unusual field, say what it means. Use
`fm-field__hint` for a field, `fm-dropzone__hint` for a drop zone.

```html
<p class="fm-dropzone__hint">
  VRV-2015-Voranschlag als PDF. Gescannte Dokumente funktionieren nicht.
</p>
```

**The data-handling sentence**, visibly, once. Word it as a claim about the
user's files, which is the part you can actually stand behind — see
*Data protection* before you write it:

```html
<p class="fm-callout fm-callout--info">
  Deine Dateien werden nur in diesem Browser gelesen und nirgendwohin
  übertragen.
</p>
```

**A date and a source.** Put it in the footer of the tool. Without it nobody
can tell whether they are looking at something current:

```html
<footer>
  Stand: 18.09.2026 · Datengrundlage: eigene Eingabe ·
  Rundung: kaufmännisch auf ganze Euro
</footer>
```

If any data is built into the tool, name where it came from and when it was
retrieved. This is what makes a figure quotable — see *Making the result
checkable*.

**What it does not do.** One short "Hinweise" or "Grenzen" block, collapsed if
you like, listing the two or three things people will otherwise assume: which
cases are not covered, which browser is required for a feature, what gets lost
when browser data is cleared.

### 2. One readme next to it

A single plain-text file in the folder, in the user's language, written for
someone who does not code. `LIESMICH.txt` for German users, `README.txt`
otherwise. Five lines is a good length, fifteen is the limit.

```text
Voranschlag-Vergleich
=====================

Was das ist
  Stellt zwei Gemeindevoranschläge (PDF, VRV 2015) gegenüber und zeigt
  die Abweichungen je Ansatz.

Starten
  index.html doppelklicken. Chrome oder Edge empfohlen — nur dort kann
  das Ergebnis direkt in eine bestehende Datei zurückgeschrieben werden.

Dateien
  index.html   die Oberfläche, hier doppelklicken
  app.js       die Auswertung
  daten.js     die Ansatz-Bezeichnungen, hier ändern
  stil.css     das Aussehen

Daten
  Deine Dateien werden nur in diesem Browser gelesen und nirgendwohin
  übertragen. Zum Laden von Design und Diagramm-Bibliothek braucht die
  Seite eine Internetverbindung; deine Dateien gehen dabei nicht mit.

Stand
  18.09.2026
```

Use `.txt`, not `.md` — it opens by double-click on every system and renders
as what it is. Name the file the user should open, and name the file they are
most likely to want to change.

In chat mode, offer this as the second file after the tool, and say it is
optional. In file-access mode, just write it.

### 3. Comments in the code

Comment the **domain decisions**, not the JavaScript. Nobody needs
`// loop over the rows`. What people need eight months later:

```js
// Spalte 3 ist beim Rechnungsabschluss die Abweichung RA-VA, beim
// Voranschlag dagegen der Rechnungsabschluss des Vorvorjahres.
// Verifiziert an den Seitenköpfen, nicht geraten.

// Auf ganze Euro gerundet wird erst bei der Anzeige. Die Summen
// rechnen auf Cent, sonst geht die Kontrollsumme nicht auf.
```

Rule of thumb: if the comment explains *why* it is that way, or records
something that was checked against a real document, keep it. If it restates
the code, delete it.

Put a short block at the top of each file saying what the file is for. Three
lines, not a header ceremony.

### What not to do

- **No `docs/` folder**, no wiki, no multi-page documentation. For a tool this
  size it guarantees the documentation and the tool drift apart.
- **No changelog** unless the user asked for one. A date in the footer covers
  it.
- **Do not say the same thing in three places.** If it is in the tool, the
  readme points at it rather than repeating it.
- **No Markdown the user will not open.** `README.md` renders as raw markup
  when double-clicked on Windows.
- **Do not document what the tool should just say itself.** A readme
  explaining which file format is accepted is a missing hint in the UI.

### The rules file is something else

`CLAUDE.md` / `AGENTS.md` is documentation for the *next assistant*, not for
the user — what the tool is, what is fixed, what must not change. Write it
yourself when the tool will be worked on again; never ask the user to compose
one. It is separate from the readme and may be more technical. See *How you
are delivering*.

---

## 12. Making the result checkable

Read when: The tool computes or summarises anything the user will repeat in public.

The user will quote this output in a council meeting, where someone is paid to
disagree with them. A number they cannot defend is worse than no tool.

This is your responsibility while building, not a disclaimer to append.

### Put a check inside the tool

- **A control total that must reconcile.** Sum of parts against the stated
  total; row count in against row count shown. When it does not match, display
  the discrepancy prominently instead of continuing quietly.
- **Count everything.** "328 von 340 Zeilen verarbeitet" — and make the 12
  inspectable. Silent dropping is the most damaging failure mode here, because
  the result still looks complete.
- **Show the input next to the output.** A drill-down from the total to the
  underlying rows turns "trust me" into "look".
- **Make assumptions visible and editable.** If the tool assumes a rate, a
  distance band, a year: show it as a field the user can change. A model that
  cannot be poked at is a slide, not a tool.

### For anything derived from documents

Never produce a bare summary. Produce **the finding in one sentence, then the
points that matter, each with the place it came from** — page, section,
annex.

The citation is what makes the claim quotable and the check cheap. Without it
the user has to believe you, and that is not a basis for a public statement.

### State limits in the output

Where the tool is uncertain, the output says so — inline, next to the figure,
not in a footer:

- "Vergleich nur für Ansätze, die in beiden Jahren vorkommen (312 von 340)."
- "Beträge gerundet, Summe aus ungerundeten Werten."
- "Diese Datei enthält keine Textebene — die Auswertung wäre geraten."

Refusing to produce a number is a valid output. Producing a confident wrong
one is not.

### What to tell the user to verify themselves

When you hand over the tool, name the two or three things only they can check:
a total they know, a figure they computed by hand, whether something they
expect to be present is missing.

A real case: a tool counted committee meetings from email exports and got it
wrong — an entire committee was missing. It was caught only because the
person using it kept their own records. The tool counted; the human knew. Say
this plainly rather than implying the output is final.

### Offer the counter-arguments

When the user asks whether the result is right, the more useful answer is the
list of attacks on it: which assumption is unverified, which figure is
sensitive to a definition, which question an opponent would ask first. In
practice this is often worth more than the result itself.

---

## 13. Data protection

Read when: Always. Especially when the tool touches names, addresses, finances or anything non-public.

Two different questions get mixed up constantly. Keep them apart, and say
which one you are answering.

### 1. What the finished tool does

A tool built to this guide processes the user's files entirely in the browser.
Their content never leaves the device, because there is no server to receive
it. That is what makes the tool usable with real municipal documents.

**But "the data stays here" and "nothing leaves this page" are not the same
claim, and only the first one is true.** The page still makes network
requests: the design system, a library from a CDN, and whatever those pull in
turn. Every one of them reveals the visitor's IP address and the time of the
visit to whoever serves it.

Keep the first claim true:

- **No analytics, no tracking pixels, no counters.**
- **No remote calls carrying content** from the loaded files — not to an API,
  not to a "helpful" lookup service.
- If something does go outward — a deep link to an open data portal, say — it
  must be a deliberate click, never a side effect.

### Check what actually goes out before you promise anything

Do not reason about this from the source. Load the finished page and look at
the network requests. When you have file access you can open it and read them
off directly; otherwise tell the user how to check (open the developer tools,
Network tab, reload).

You are looking for hosts nobody chose: font services, icon CDNs, analytics
that came in with a snippet. **A stylesheet can pull in further requests you
never wrote** — an `@import` at the top of a CSS file is enough, and it will
not appear anywhere in your own code.

This is not hypothetical. A design system that loads its fonts from
`fonts.googleapis.com` makes every page using it contact Google. Nothing of
the user's data goes with it, but the IP address does — and in the EU that is
the kind of thing an organisation may have to answer for.

The design system in *Making it look right* self-hosts its fonts and makes no
third-party request at all — checked, not assumed. That is exactly the point:
check the version you are actually linking, because this is a property of the
file, not of the project, and it can change between releases.

### The sentence to put in the interface

Say what is actually true: the **files** stay on the device.

> Deine Dateien werden nur in diesem Browser gelesen und nirgendwohin
> übertragen.

That claim survives scrutiny. The absolute version — *"es findet keine
Übertragung statt"* — does not, as soon as somebody opens the network tab, and
being caught overstating this costs more trust than the fonts ever cost.

If the tool genuinely makes no third-party request at all, then say so, and
say it precisely:

> Diese Seite lädt nichts von Dritten nach. Alles läuft lokal.

Never write either sentence before you have checked.

### 2. What goes into the chat

Everything the user pastes into a chat leaves their device and reaches a
provider. When their request would involve sensitive material, say so and
offer the alternative before they paste it.

Never encourage the user to paste:

- Personal data — names with addresses, dates of birth, IBANs, health data,
  population-register extracts
- Membership, donor or customer lists. Helping with the **rules** and the
  **structure of a form** is fine; the list itself is not
- Non-public drafts and confidential internal material
- Third-party documents they are not permitted to pass on

### When you have access to the folder

An assistant that can read the working directory sees more than the user
deliberately handed over. Files they forgot about are as readable as the one
they meant to share.

Act accordingly: do not open files that are not needed for the task, say
plainly which files you read, and if you come across a membership list, an
export with personal data or something marked confidential, name it and leave
it alone rather than using it as sample data. Tell the user that a project
folder is not a safe place for such files while an assistant is working in it.

### The precheck, before you read a data file

Everything above is a rule about intent. This is the step that catches the
ordinary case: the user points you at `mitglieder.csv` because they want a tool
built from it, and neither of you has thought about what is in it yet. Once you
have read it, it is in the conversation and cannot be taken back out.

So look before you read. **Never open a data file in full as your first
action.**

1. **Read the filename and the header row only.** For a CSV that is the first
   line. For a spreadsheet, the first row. That is enough to decide, and it
   costs you almost nothing if the file turns out to be fine.
2. **Flag a column** when its name or a single example value looks like any of:
   a person's name, a street address, a postcode together with a house number,
   a date of birth, a national insurance or social security number, an IBAN or
   account number, an email address, a phone number, a licence plate, an IP
   address, a patient or case number — or anything in the special categories
   that carry extra protection under GDPR Article 9: health, religion, trade
   union membership, ethnicity, sexual orientation, biometrics.
3. **Stop there if anything is flagged.** Do not read the rest of the file. Say
   which columns you flagged and why, in one short list.
4. **Offer the two ways forward**, in this order:
   - work from the **structure alone** — the column names are usually all you
     actually need to build the tool;
   - or generate **synthetic rows** with the same shape and build against
     those. Offer to write them; it is usually the unblocking move.
5. **Continue into the real file only if the user confirms** it holds no
   personal data. Their confirmation, not your assumption.

A flagged file also never becomes a fixture: do not copy it into the project
folder, do not paste rows from it into the chat, and do not commit it. The
finished tool reads the real file on the user's own device, which is the whole
point — the data never needed to reach you at all.

**In a chat, the precheck happens before the paste.** You cannot inspect a
header row the user has not sent yet, so ask for it: "paste just the column
headings, not the rows." If real data arrives anyway, say so plainly, do not
quote it back, and carry on from the structure.

The substitute that works: **structure instead of content.** "I have a table
with the columns Name, Year of birth, District, Amount — write the analysis
for it" produces the same tool without the data. Or: build against invented
sample data, and let the finished tool read the real file locally.

Offer to generate realistic sample data. It is usually the unblocking move.

### Showing a tool in public

Demonstrating in a council session or a talk follows publication rules, not
internal ones: use public or synthetic data, round figures or relabel
municipalities where something is still under negotiation, and for sensitive
documents show the structure rather than the content.

---

## 14. Going further

Read when: The user asks for a public address, several pages, or wants others to contribute. Not before.

Everything so far assumed a folder on one laptop, opened by double-click. That
covers most tools and stays the default. This section is about the step
beyond it.

### This is NOT about splitting into files

Splitting a tool across `index.html`, `app.js` and `stil.css` needs nothing
from this section. Classic `<script src>` and `<link>` work from a
double-clicked file, subfolders included — see *What to deliver*. Do not send
a user to a local server because their tool grew to four files.

### The actual threshold

You are past the double-click folder only when one of these is true:

- Other people must reach it at an **address**, not receive it as an attachment.
- It needs **several pages with their own links** that people can bookmark.
- **More than one person** will change it over time.
- It needs **ES modules, a bundler or a framework** — which in practice means
  it has become a web application, not a tool.

"It is getting long" is not one of them.

### When a local server does become necessary

Only if you deliberately move to ES modules or `fetch()` of local data — both
blocked on `file://`. Then trying it out locally requires:

```bash
npx serve .                 # needs Node.js
python3 -m http.server      # needs Python
```

For a user without a terminal that is a wall. Two ways around it: stay with
classic scripts and a `.js` data file, or publish, where the address itself
serves the page and no local server is involved.

### Publishing on GitHub Pages

Free, static, no server to run, no ongoing cost.

1. Create an account at <https://github.com>.
2. Create a public repository.
3. Upload the files through the web interface — "Add file → Upload files".
   No terminal required for a plain HTML tool.
4. **Settings → Pages**, source: **GitHub Actions** (or "Deploy from a branch"
   for a folder with no build step).
5. The address is `https://<account>.github.io/<repo>/`.

For a site that needs a build, a workflow at `.github/workflows/pages.yml`
runs it: `actions/checkout`, `actions/setup-node`, the build command,
`actions/upload-pages-artifact` with the output folder, then
`actions/deploy-pages` in a second job with `pages: write` and `id-token:
write` permissions.

### The two failures that actually happen

**Paths in a subfolder.** At `account.github.io/repo/`, every link starting
with `/` points outside the project. Keep internal links relative, or set a
base path in the generator and use it everywhere. This is the overwhelming
cause of "it worked locally and is broken once published".

**Everything is public.** A public repository exposes every file and every
past revision. Credentials, keys, internal documents and real personal data do
not belong in it — not in a sample file, not "just for a test". Once pushed,
it stays in the history.

### Publishing checklist

Before the repository goes public, walk the folder once:

- No credentials, keys, tokens or internal documents — not in a sample file,
  not "just for a test".
- No real personal data. Replace it with invented rows that have the same
  shape.
- The `README.md` says what the tool is and how to open it.
- The base path is right, so the published page finds its own CSS and data.

### If it becomes a real project

Four things make the difference, in this order: a `README.md` saying what it
is and how to run it; a rules file (`CLAUDE.md` or `AGENTS.md`) so an
assistant does not have to be re-briefed every session; small commits on a
branch rather than on `main`; and issues instead of one large instruction.

Write the rules file **for the assistant, not for the user** — the user should
never have to compose it. Generate it and put it in the repository.