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

> How to build a small tool for someone who has a browser and nothing else — no terminal, no editor, no package manager, no admin rights.

## Read this first

Unless the user explicitly asks for something else:

- Deliver a folder the user saves. `index.html` must run from a double-click (`file://`).
  No build step, no bundler, no npm, no local server, nothing to install.
- One file is right for a small tool handed over IN A CHAT, because the user saves it manually.
  If you can write files into a folder yourself, that argument does not apply — split freely.
  Classic `<script src>` and `<link>` DO work across files on `file://`, subfolders included;
  splitting never requires a server.
- Having a terminal does not mean the user has one. Never leave behind anything that needs
  a build step, a package manager or a local server to run or to change. If they could not
  edit one label six months from now with a browser and a text editor, simplify.
- NO `<script type="module">` and NO `import`. ES modules are blocked on `file://`
  (CORS against origin `null`) and the tool arrives dead. Use classic `<script>` tags
  and CDN libraries that expose a global (UMD).
- NO `fetch()` or XHR on a local file — also blocked. Ship data as a `.js` file that
  assigns a global (`window.DATEN = {...}`), loaded with a plain `<script src>`.
- Pin every CDN version. `@latest` breaks the tool on a random day.
- Link the design system: https://design-system.flomotlik.me/design-system.css
  It styles no HTML tags — you must set `body` margin/background/color/font-family from the `--fm-*` tokens.
  Its colours are named by ROLE (--fm-color-primary, -secondary, -accent), never by hue.
  For an organisation with its own colours do not fork or copy it: add a `local.css` AFTER it
  that overrides about eight role tokens in a plain `:root` block (see "Adapting the look").
  Ask before rebranding — never apply an organisation's colours unprompted. Never recolour
  --fm-web-status-* or the warn/error/success variants: green means ok everywhere.
- Write the interface in the language the tool will be USED in — derived from the organisation,
  institution or audience, NOT from the language the request was written in. A request in English
  about a Flemish town council means a Dutch interface. Ask once if the two genuinely conflict.
  Number/date format, the readme filename and export labels follow that same language.
  This guide and the rules file you leave behind stay English — they are not the interface.
- Process the user’s files locally. No analytics, no tracking, no remote call carrying their data.
- The page still makes network requests (CDN, design system — and a stylesheet `@import` can pull
  in fonts you never wrote). LOAD THE FINISHED PAGE AND CHECK the network requests before you
  write any privacy claim into the interface. Claim that the FILES stay local, which is true;
  do not claim that nothing is transmitted at all unless you verified exactly that.
- Scope by the question, not by screen count: build the smallest thing that actually answers it.
  Test each control with "can they answer their question without this?" — if yes, leave it out.
  A year selector in a year-comparison tool is required, not feature creep. No login, no
  onboarding, no second job. Ship it before adding anything else.
- Build a visible check into the tool: control total, row count in vs. shown, source for every derived claim.
- Document inside the tool first: a one-line purpose under the title, help at the field that
  needs it, the data-handling sentence, and a date in the footer. Then ONE short plain-text
  readme in the folder. No docs folder, no changelog.
- PRECHECK ANY DATA FILE BEFORE YOU READ IT. Never open a user's data file in full as your
  first action. Read the filename and the HEADER ROW ONLY, and flag any column that looks like
  a name, address, date of birth, national insurance number, IBAN, email, phone, licence plate,
  patient/case id, or a GDPR Article 9 special category (health, religion, union membership,
  ethnicity, sexual orientation, biometrics). If anything is flagged: STOP, do not read the
  rest, say which columns and why, and offer to work from the structure alone or from synthetic
  rows you generate. Continue only if the user confirms there is no personal data in it.
  Once you have read it, it is in the conversation and cannot be taken back out.
- In a chat you cannot inspect a header row that has not been sent, so ask for it: "paste just
  the column headings, not the rows." Never encourage pasting personal data or non-public
  documents. A flagged file never becomes fixture data and is never committed.

Verified in Chromium on `file://` (`isSecureContext` is true). These work:
localStorage, IndexedDB, File System Access API, canvas `toBlob()`, clipboard, CDN resources,
and your own CSS/JS/images by relative path via classic tags, across subfolders.
These do NOT: ES modules, `fetch()`/XHR on a local file, service workers.

## How to use this file

- Read the rules above. They apply to every task.
- Fetch one or two sections that match the task. Do not fetch all of them.
- Need everything in one request? [llms-full.txt](https://ai-build-guide.flomotlik.me/llms-full.txt) contains every section.

## Sections

- [What to deliver](https://ai-build-guide.flomotlik.me/guide/contract.md) — read when: Always. Read this before writing any code — it constrains every other section.
  Deliver a folder the user saves; index.html opens by double-click. One file for a small tool, several when the tool earns it — classic <script src> and <link> across files work fine from file://. What does NOT work: ES modules and fetch() of local files. Libraries from CDN as globals with a pinned version. Interface in the language the tool is USED in, not the language of the request. Scope by the question asked, not by screen count.
- [How you are delivering](https://ai-build-guide.flomotlik.me/guide/delivery-mode.md) — read when: Always, right after 'What to deliver'. It decides how many files you produce and what you may leave behind.
  Work out whether you hand files to the user through a chat or write them into a folder yourself. Chat: prefer one file, name every file explicitly. Direct file access: split freely, iterate in place, open the tool and check it. Either way the user has no toolchain — never leave behind anything that needs a terminal to run or change.
- [Reading files](https://ai-build-guide.flomotlik.me/guide/files-in.md) — read when: The tool takes a document, spreadsheet, export or image from the user.
  Take files in via <input type=file> AND drag-and-drop. Read with File.text() or File.arrayBuffer(). CSV: use a CDN parser, never split on commas. PDF: PDF.js 3.11.174 is the last classic non-module build and works from file:// — never 4.x/5.x, those are ESM only. Use text positions for tables.
- [Saving results](https://ai-build-guide.flomotlik.me/guide/files-out.md) — read when: The tool produces something the user keeps: a table, a report, an image, an edited file.
  Blob download via a temporary <a download> is the baseline and always works. Direct write-back with showSaveFilePicker is a Chrome/Edge enhancement behind a feature check — never the only path.
- [Keeping data](https://ai-build-guide.flomotlik.me/guide/remember.md) — read when: Anything should survive closing the tab: settings, entered data, imported files.
  localStorage for settings and drafts (wrap every read in try/catch), IndexedDB for large or structured data, SQLite-on-WASM only for real queries. navigator.storage.persist() asks the browser not to evict, but may refuse — an export button is the actual backup and is mandatory, not a feature.
- [Tables and numbers](https://ai-build-guide.flomotlik.me/guide/tables.md) — read when: The tool shows rows of data or does arithmetic the user will quote.
  Use fm-table with fm-table__num for figures; right-align and use tabular-nums. Format with de-AT locale. Show a total row and make it verifiable. Sorting and filtering in plain JS, no grid library.
- [Charts](https://ai-build-guide.flomotlik.me/guide/charts.md) — read when: The tool visualises numbers.
  ECharts from CDN as a global script with a pinned version. Read the palette from the design-system CSS tokens --fm-web-chart-1..8 via getComputedStyle — do NOT import fm-charts.js, it is an ES module and fails on file://. Pick the chart type from the claim, label axes, state source and date.
- [Generating images](https://ai-build-guide.flomotlik.me/guide/images.md) — read when: The tool produces a picture: a sharepic, a graphic for a newsletter, a poster draft, an annotated screenshot.
  Canvas plus toBlob() for PNG export. For print, size the canvas at target resolution and scale it down with CSS, or export with a multiplier — 300 dpi needs roughly 3.5x the screen size. Label AI-generated imagery.
- [Making it look right](https://ai-build-guide.flomotlik.me/guide/look.md) — read when: Always, for anything with a user interface.
  Link https://design-system.flomotlik.me/design-system.css and set the four body properties from --fm-* tokens — the design system styles no HTML tags, so without them the page renders unstyled. Use fm-* component classes. Must work at 375px and by keyboard.
- [Adapting the look](https://ai-build-guide.flomotlik.me/guide/branding.md) — read when: The tool represents an organisation with its own colours, or the default look is wrong for the job.
  The design system is token-driven, so different colours are one extra stylesheet — local.css linked AFTER design-system.css, overriding about eight role tokens in a plain :root block. Never fork or copy the design system. Ask before applying anyone's branding; leave status colours, spacing and radii untouched; re-check contrast.
- [Documenting the tool](https://ai-build-guide.flomotlik.me/guide/document.md) — read when: Before you hand anything over. Applies to every tool, however small.
  Document inside the tool first — a one-line purpose under the title, inline help at the field that needs it, a data-handling sentence, and a date. Then one short plain-text readme in the folder. Comment the domain decisions in the code, not the JavaScript. No docs folder, no changelog ceremony.
- [Making the result checkable](https://ai-build-guide.flomotlik.me/guide/trust.md) — read when: The tool computes or summarises anything the user will repeat in public.
  Build a visible check into the tool: a control total that must reconcile, the input row count, and a stated source for every derived claim. Show what was skipped. State limits instead of hiding them.
- [Data protection](https://ai-build-guide.flomotlik.me/guide/privacy.md) — read when: Always. Especially when the tool touches names, addresses, finances or anything non-public.
  Precheck any data file before reading it: filename and header row only, flag PII columns, stop and offer structure-only or synthetic rows. The tool must not transmit user data — no analytics, no tracking, no remote calls carrying file contents. But the page still makes network requests (CDN, design system, fonts pulled in by an @import you never wrote): check them before promising anything, and claim only that the FILES stay local. Separately: warn the user not to paste personal data or non-public material into the chat.
- [Going further](https://ai-build-guide.flomotlik.me/guide/going-further.md) — read when: The user asks for a public address, several pages, or wants others to contribute. Not before.
  For a public address, several linked pages, or other contributors. Splitting into files does NOT require this — that works by double-click. GitHub Pages publishes a static folder for free; watch the base path and remember everything in a public repo is public.

## Related

- [Design system](https://design-system.flomotlik.me/): tokens, components, live style guide
- [Human-readable start page](https://ai-build-guide.flomotlik.me/en/)