Skip to content

docs: add the form-builder README header from the design system - #5

Merged
whatsaaaa merged 1 commit into
mainfrom
fm/readme-assets-sample
Nov 13, 2026
Merged

whatsaaaa merged 1 commit into
mainfrom
fm/readme-assets-sample

Conversation

@whatsaaaa

@whatsaaaa whatsaaaa commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Intent

Put the Whatsaaaa assets from the design system in every project's README. For this repository, which holds form-builder's sample apps and its release trial: form-builder's README header from the design system's asset kit, copied in unchanged, at the top of the README; the rest of the README stays as it is.

What Changed

  • Adds .github/assets/readme-header.svg, the form-builder README header from the Whatsaaaa design system's asset kit.
  • Puts the header image at the top of README.md, above the # form-builder-sample heading. It is shown at full width, with alt text "form-builder - forms from JSON, validated by Formisch".

🤖 Generated with Claude Code

Risk Assessment

✅ Low: The change only adds an unedited, byte-identical design-system SVG and one img line at the top of the README, matching the design system's own README convention; the only open point is which identity's header this sample repo should carry.

Testing

I checked the committed header SVG against the published @whatsaaaa/design-system@0.1.1 npm tarball: it is byte-identical, listed in the manifest as "Header for a README", and its path resolves case-sensitively in the committed tree. I then put README.md through GitHub's real GFM renderer and screenshotted it in headless Chromium in light and dark themes at desktop and mobile widths, plus a broken-image case. Every time, the header is the first element, scales to the content width with no cropping, and falls back to its alt text. All six live scenarios passed. Viewing the README on github.com itself was not possible, because the branch is not pushed yet and the repo is private; the later PR phase owns the push.

  • Live validation: ✅ go - 6 of 7 scenarios driven live against the product
Scenario Result Live Evidence
Visitor opens the README (GitHub GFM render, light theme, 1280px): the Whatsaaaa header is the first thing shown, at full content width, above the form-builder-sample heading ✅ pass live readme-light-desktop.png; render/readme-github-gfm.html (first element is the <img> with width=100%, kept by GitHub's sanitizer)
Visitor in GitHub dark theme sees the header clearly separated from the page (border and text readable on #0d1117) ✅ pass live readme-dark-desktop.png
Visitor on a 390px phone width sees the header scaled down to the column without cropping or horizontal overflow ✅ pass live readme-light-mobile.png, readme-dark-mobile.png
The shipped header is an unedited copy of the published design-system asset (npm @whatsaaaa/design-system@0.1.1 assets/form-builder/readme-header.svg, listed in assets/manifest.json as 'Header for a R… ✅ pass live asset-and-path-check.txt
Adversarial: the header still loads on GitHub's case-sensitive storage and inside an <img> sandbox (no fonts, scripts or external refs needed) ✅ pass live asset-and-path-check.txt; readme-*-desktop.png
Adversarial: when the header image cannot load, the reader sees the alt text 'form-builder - forms from JSON, validated by Formisch' in its place and the README continues normally ✅ pass live readme-light-image-unreachable-alt-text.png
Header shown on the actual github.com repository page for branch fm/readme-assets-sample ⏸️ untested no The branch is not on GitHub yet, and this test phase may not push or open the PR; the later push and PR phases own that. So github.com's own repo page could not be loaded. Instead I drove GitHub's rea…

README rendered by GitHub GFM, light theme, 1280px desktop: header at top above the h1

README rendered by GitHub GFM, dark theme, 1280px desktop

README rendered by GitHub GFM, light theme, 390px mobile @2x

README rendered by GitHub GFM, dark theme, 390px mobile @2x

Header image unreachable: alt text shown in its place, h1 follows

Evidence: Asset identity vs npm @whatsaaaa/design-system@0.1.1, manifest entry, case-sensitive path resolution, img-sandbox safety

src=./.github/assets/readme-header.svg (first element of rendered README) git ls-tree b32c3fb: 100644 blob 4c7a977f .github/assets/readme-header.svg sha256 committed blob = sha256 npm package/assets/form-builder/readme-header.svg = 276684914a9798c0983cc204c75a6c0adc99b0b97dd4ac45986481d6426601f2 RESULT: byte-identical (unedited copy) manifest: form-builder readme-header.svg 1280x320 'Header for a README.' script/foreignObject/@import/font-face/<text>/external href: 0

## README image src as emitted by GitHub's GFM renderer (POST /markdown, mode=gfm)
src=./.github/assets/readme-header.svg

## Is that src the first element of the rendered README?
<p dir="auto"><a target="_blank" rel="noopener noreferrer" href="./.github/assets/readme-header.svg"><img src="./.github

## Resolve src against the committed tree at b32c3fb (case-sensitive git path lookup)
100644 blob 4c7a977f8a01c89960c715e3d0a2ca1665d98211	.github/assets/readme-header.svg

## Committed blob vs @whatsaaaa/design-system@0.1.1 assets/form-builder/readme-header.svg (npm registry tarball)
276684914a9798c0983cc204c75a6c0adc99b0b97dd4ac45986481d6426601f2  committed blob
276684914a9798c0983cc204c75a6c0adc99b0b97dd4ac45986481d6426601f2  package/assets/form-builder/readme-header.svg
RESULT: byte-identical (unedited copy)

## Manifest entry (assets/manifest.json in the npm package)
[{'file': 'readme-header.svg', 'width': 1280, 'height': 320, 'use': 'Header for a README.'}]

## Does the SVG need anything an <img> sandbox blocks? (scripts, foreignObject, external refs, fonts)
<script                0
foreignObject          0
@import                0
font-face              0
<text                  0
xlink:href=\"http      0
href=\"http            0

## README files tracked in the repo
.github/assets/readme-header.svg
README.md
Evidence: README HTML as emitted by GitHub's GFM renderer (POST /markdown)
<p dir="auto"><a target="_blank" rel="noopener noreferrer" href="./.github/assets/readme-header.svg"><img src="./.github/assets/readme-header.svg" alt="form-builder - forms from JSON, validated by Formisch" width="100%" style="max-width: 100%;"></a></p>
<h1 dir="auto">form-builder-sample</h1>
<p dir="auto">Two small apps built with <a href="https://whatsaaaa.github.io/form-builder/" rel="nofollow">form-builder</a> <code class="notranslate">1.0.0-rc.0</code>, using only what a new user has: the documentation site and the packages on npm. The repository is the release-candidate trial for form-builder 1.0: it shows that real forms can be built from the public material, and records every problem met on the way. The apps take their look from the <a href="https://github.com/whatsaaaa/design-system">Whatsaaaa design system</a>, installed from npm as <code class="notranslate">@whatsaaaa/design-system</code> like any other package.</p>
<p dir="auto"><strong>The record of the trial is <a href="FRICTION-LOG.md">FRICTION-LOG.md</a>.</strong> Start there if you work on form-builder.</p>
<h2 dir="auto">The apps</h2>
<markdown-accessiblity-table><table role="table">
<thead>
<tr>
<th>App</th>
<th>What it is</th>
<th>What it exercises</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="vue-event-registration"><code class="notranslate">vue-event-registration</code></a></td>
<td>A multi-step event registration in Vue</td>
<td>Steps, rows, a section and a slot, conditional fields and a conditional step, a repeating guest list, form rules, a definition loaded from a JSON file</td>
</tr>
<tr>
<td><a href="react-checkout"><code class="notranslate">react-checkout</code></a></td>
<td>A checkout in React, with a small server</td>
<td>A definition served by the server and validated again there, messages in English and German, a repeating list of items, conditional fields, server errors shown on the fields</td>
</tr>
</tbody>
</table></markdown-accessiblity-table>
<p dir="auto">Each app is self-contained: its own <code class="notranslate">package.json</code>, lockfile and tooling. Both need pnpm 11, and Node 22.18 or a later 22, or Node 24.12 or later, as the design system does.</p>
<p dir="auto">Everything visual lives in each app's <code class="notranslate">src/ui</code> folder (field, layout and page components) and its one stylesheet, <code class="notranslate">src/styles.css</code>, so a restyle swaps those and leaves the forms alone. Both apps are restyled on the design system: their page is the system's terminal frame, with a tab bar, a status line that switches the theme and the shortcut keys, and a dark and a light theme.</p>
<h2 dir="auto">Run the Vue app</h2>
<div class="highlight highlight-source-shell" dir="auto"><pre class="notranslate"><span class="pl-c1">cd</span> vue-event-registration
pnpm install
pnpm dev        <span class="pl-c"><span class="pl-c">#</span> http://localhost:5173</span></pre></div>
<h2 dir="auto">Run the React app</h2>
<div class="highlight highlight-source-shell" dir="auto"><pre class="notranslate"><span class="pl-c1">cd</span> react-checkout
pnpm install
pnpm dev        <span class="pl-c"><span class="pl-c">#</span> the app on http://localhost:5173, the API on http://localhost:8787</span></pre></div>
<p dir="auto"><code class="notranslate">pnpm dev</code> starts the API server and Vite together, and Vite passes <code class="notranslate">/api</code> on to the server. To run the production build the way the end-to-end tests do, with one server for the app and the API:</p>
<div class="highlight highlight-source-shell" dir="auto"><pre class="notranslate">pnpm build
pnpm start      <span class="pl-c"><span class="pl-c">#</span> http://localhost:8787</span></pre></div>
<h2 dir="auto">Checks</h2>
<p dir="auto">The same commands work in both apps, and CI runs them all for both on every pull request and on <code class="notranslate">main</code>:</p>
<div class="highlight highlight-source-shell" dir="auto"><pre class="notranslate">pnpm lint       <span class="pl-c"><span class="pl-c">#</span> the linter, and Prettier</span>
pnpm typecheck  <span class="pl-c"><span class="pl-c">#</span> strict TypeScript</span>
pnpm <span class="pl-c1">test</span>       <span class="pl-c"><span class="pl-c">#</span> unit tests, with Vitest</span>
pnpm build
pnpm test:e2e   <span class="pl-c"><span class="pl-c">#</span> end-to-end tests in a browser, with Playwright</span></pre></div>
<p dir="auto">The end-to-end tests need a browser once: <code class="notranslate">pnpm exec playwright install chromium</code>.</p>
<h2 dir="auto">Where things are</h2>
<pre class="notranslate"><code class="notranslate">vue-event-registration/
  src/registration/   the definition (JSON), the builder, the form and its review summary
  src/ui/             field, layout and page components
  e2e/                end-to-end tests

react-checkout/
  shared/             the definition, the builder, the catalog and the texts: used by browser and server
  server/             the API: serves the definition, validates and prices orders
  src/checkout/       the form and its calls to the API
  src/ui/             field, layout and page components
  e2e/                end-to-end tests
</code></pre>

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning
  • ⚠️ README.md:1 - The README header is form-builder's kit (assets/form-builder/readme-header.svg, identical to design-system main and npm 0.1.1), not a kit for this repo. Rendered, it shows whatsaaaa: ~/form-builder, form-builder --help and a large "form-builder", directly above the # form-builder-sample heading, so the header names a different repository. The intent counts this repo as one of "all our projects". The usage guide it cites (docs/usage.md section 9) says: "For a project that has no kit yet, add a file like identity/projects/form-builder.json first." The manifest has kits only for whatsaaaa, building-blocks, dotfiles and form-builder, with none for form-builder-sample. Borrowing form-builder's kit is defensible because this repo is form-builder's 1.0 trial, but it is a branding decision. Options: (a) keep form-builder's header, (b) use the whatsaaaa handle header, or (c) add identity/projects/form-builder-sample.json in the design-system repo, run pnpm assets, and copy that header here. The remedy (option c) needs work outside this repo, which is why this needs your decision rather than an auto-fix. The same choice applies to the copied asset at .github/assets/readme-header.svg:1 and the alt text at README.md:1 ("form-builder - forms from JSON, validated by Formisch").
✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 6 of 7 scenarios driven live against the product
Scenario Result Live Evidence
Visitor opens the README (GitHub GFM render, light theme, 1280px): the Whatsaaaa header is the first thing shown, at full content width, above the form-builder-sample heading ✅ pass live readme-light-desktop.png; render/readme-github-gfm.html (first element is the <img> with width=100%, kept by GitHub's sanitizer)
Visitor in GitHub dark theme sees the header clearly separated from the page (border and text readable on #0d1117) ✅ pass live readme-dark-desktop.png
Visitor on a 390px phone width sees the header scaled down to the column without cropping or horizontal overflow ✅ pass live readme-light-mobile.png, readme-dark-mobile.png
The shipped header is an unedited copy of the published design-system asset (npm @whatsaaaa/design-system@0.1.1 assets/form-builder/readme-header.svg, listed in assets/manifest.json as 'Header for a R… ✅ pass live asset-and-path-check.txt
Adversarial: the header still loads on GitHub's case-sensitive storage and inside an <img> sandbox (no fonts, scripts or external refs needed) ✅ pass live asset-and-path-check.txt; readme-*-desktop.png
Adversarial: when the header image cannot load, the reader sees the alt text 'form-builder - forms from JSON, validated by Formisch' in its place and the README continues normally ✅ pass live readme-light-image-unreachable-alt-text.png
Header shown on the actual github.com repository page for branch fm/readme-assets-sample ⏸️ untested no The branch is not on GitHub yet, and this test phase may not push or open the PR; the later push and PR phases own that. So github.com's own repo page could not be loaded. Instead I drove GitHub's rea…
  • npm pack @whatsaaaa/design-system@latest (0.1.1) into the evidence dir, extracted, read assets/manifest.json and docs/usage.md section 9
  • git show b32c3fb:.github/assets/readme-header.svg | cmp - package/assets/form-builder/readme-header.svg plus sha256 of both (identical: 276684914a97...)
  • git ls-tree b32c3fb -- .github/assets/readme-header.svg using the exact img src that GitHub's renderer emitted (case-sensitive path lookup)
  • Checked the SVG for things an <img> sandbox blocks (script, foreignObject, @import, font-face, <text>, external hrefs): none present, text is outlined as paths
  • gh api -X POST /markdown -f mode=gfm -f context=whatsaaaa/form-builder-sample -F text=@README.md (GitHub's real GFM renderer and sanitizer) -> render/readme-github-gfm.html
  • Served the worktree read-only and the rendered page with github-markdown-css 5.9.0 on 127.0.0.1, screenshotted with Playwright's cached chrome-headless-shell at 1280x900 (light, dark) and 390x844 @2x (light, dark)
  • Adversarial: same page with the header unreachable (base pointed at a dead port), screenshotted to show the alt-text fallback
  • git ls-files | grep -i readme to confirm README.md is the only README in the repo
  • Stopped both local servers and removed the temp browser profiles; git status --porcelain is empty
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

@whatsaaaa
whatsaaaa merged commit 8308fbe into main Nov 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant