Skip to content

docs: add whatsaaaa README header from the design system kit - #3

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

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

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: the handle'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

  • Added .github/assets/readme-header.svg, an unedited copy of assets/whatsaaaa/readme-header.svg from @whatsaaaa/design-system. It is byte-identical to the file in the installed package.
  • Put the header at the top of README.md, above the # whatsaaaa.github.io title, as a full-width <img> with alt="whatsaaaa".
  • The site itself is unchanged. The SVG lives under .github/ and nothing in the Astro build references it.

🤖 Generated with Claude Code

Risk Assessment

✅ Low: This is a docs-only change: README.md gains one line, and the header SVG it points to is byte-identical to the published kit file @whatsaaaa/design-system@0.1.0 assets/whatsaaaa/readme-header.svg. No build, deploy, or runtime code paths are affected.

Testing

Downloaded the published design-system kit and compared the committed header to the kit's whatsaaaa header byte for byte: identical in 0.1.0 and 0.1.1. Rendered README.md through GitHub's GFM markdown API (it renders without storing anything) and served the result locally with github-markdown-css. Drove headless Chrome for Testing over CDP at 1280px and 390px in light and dark mode, measured the header image and took screenshots. Also loaded the SVG on its own to confirm it has no scripts or external references. All scenarios passed. One limit: the branch isn't on GitHub yet (push is a later phase), so the live github.com repo page wasn't checked; GitHub's own renderer plus GitHub's CSS stood in for it. The chrome-devtools-axi bridge wouldn't attach (BRIDGE_NOT_READY), so the screenshots came from headless Chrome for Testing driven directly over CDP. Nothing was written to the worktree; the local server and browser are stopped.

  • Live validation: ✅ go - 4 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Committed README header is an unedited copy of the whatsaaaa header in the published design-system kit (oracle: npm tarballs of @whatsaaaa/design-system 0.1.0 and 0.1.1) ✅ pass live asset-provenance.txt: SHA-256 bca7a77d...4181 and cmp identical for the worktree file vs assets/whatsaaaa/readme-header.svg in both tarballs; the manifest lists it as 'Header for a README.'
A visitor opening README.md on GitHub sees the whatsaaaa header at the very top, above the 'whatsaaaa.github.io' title (GitHub GFM API render + github-markdown-css in headless Chrome, light mode, 1280… ✅ pass live shots/readme-light-1280.png; render-report.json readme-light-1280: complete=true, naturalWidth=1280x320, first block contains img, imgAboveH1=true, alt='whatsaaaa', no failed requests
Header adapts to GitHub dark mode and narrow mobile screens without distortion or overflow (dark/light at 390px, dark at 1280px) ✅ pass live shots/readme-dark-1280.png, shots/readme-light-390.png, shots/readme-dark-390.png; render-report.json: renderedW equals the content width (948px / 356px), aspect=4.000, horizontalOverflow=false in eve…
Adversarial: header still draws inside GitHub's sandboxed <img> (no scripts, web fonts or external references that GitHub would block) ✅ pass live shots/svg-standalone-1280.png; render-report.json svg-standalone-1280: scripts=0, externalRefs=0, renders 1280x320; text is drawn as paths, so it doesn't depend on fonts. In the README screenshots the…
Header shows on the live github.com repository page for branch fm/readme-assets-website ⏸️ untested no The branch isn't on GitHub yet; pushing is a later pipeline phase owned by the outer executor, and this phase is not allowed to push. As the closest local stand-in, I used GitHub's real GFM render API…

README rendered by GitHub GFM + GitHub CSS, light, 1280px

README rendered by GitHub GFM + GitHub CSS, dark, 1280px

README rendered by GitHub GFM + GitHub CSS, light, 390px mobile

README rendered by GitHub GFM + GitHub CSS, dark, 390px mobile

Header SVG loaded on its own at 1280x320

Evidence: Browser measurements per viewport/scheme (img load, size, aspect, position, overflow, failed requests)
[
  {
    "name": "readme-light-1280",
    "w": 1280,
    "h": 900,
    "scheme": "light",
    "mobile": false,
    "path": "/index.html",
    "svgStatus": 200,
    "svgMime": "image/svg+xml",
    "failedRequests": [],
    "measured": {
      "firstBlockContainsImg": true,
      "imgSrc": ".github/assets/readme-header.svg",
      "alt": "whatsaaaa",
      "complete": true,
      "naturalWidth": 1280,
      "naturalHeight": 320,
      "renderedW": 948,
      "renderedH": 237,
      "articleContentW": 948,
      "aspect": 4,
      "imgAboveH1": true,
      "h1Text": "whatsaaaa.github.io",
      "horizontalOverflow": false,
      "bodyBg": "rgb(255, 255, 255)"
    }
  },
  {
    "name": "readme-dark-1280",
    "w": 1280,
    "h": 900,
    "scheme": "dark",
    "mobile": false,
    "path": "/index.html",
    "svgStatus": 200,
    "svgMime": "image/svg+xml",
    "failedRequests": [],
    "measured": {
      "firstBlockContainsImg": true,
      "imgSrc": ".github/assets/readme-header.svg",
      "alt": "whatsaaaa",
      "complete": true,
      "naturalWidth": 1280,
      "naturalHeight": 320,
      "renderedW": 948,
      "renderedH": 237,
      "articleContentW": 948,
      "aspect": 4,
      "imgAboveH1": true,
      "h1Text": "whatsaaaa.github.io",
      "horizontalOverflow": false,
      "bodyBg": "rgb(13, 17, 23)"
    }
  },
  {
    "name": "readme-light-390",
    "w": 390,
    "h": 844,
    "scheme": "light",
    "mobile": true,
    "path": "/index.html",
    "svgStatus": 200,
    "svgMime": "image/svg+xml",
    "failedRequests": [],
    "measured": {
      "firstBlockContainsImg": true,
      "imgSrc": ".github/assets/readme-header.svg",
      "alt": "whatsaaaa",
      "complete": true,
      "naturalWidth": 1280,
      "naturalHeight": 320,
      "renderedW": 356,
      "renderedH": 89,
      "articleContentW": 356,
      "aspect": 4,
      "imgAboveH1": true,
      "h1Text": "whatsaaaa.github.io",
      "horizontalOverflow": false,
      "bodyBg": "rgb(255, 255, 255)"
    }
  },
  {
    "name": "readme-dark-390",
    "w": 390,
    "h": 844,
    "scheme": "dark",
    "mobile": true,
    "path": "/index.html",
    "svgStatus": 200,
    "svgMime": "image/svg+xml",
    "failedRequests": [],
    "measured": {
      "firstBlockContainsImg": true,
      "imgSrc": ".github/assets/readme-header.svg",
      "alt": "whatsaaaa",
      "complete": true,
      "naturalWidth": 1280,
      "naturalHeight": 320,
      "renderedW": 356,
      "renderedH": 89,
      "articleContentW": 356,
      "aspect": 4,
      "imgAboveH1": true,
      "h1Text": "whatsaaaa.github.io",
      "horizontalOverflow": false,
      "bodyBg": "rgb(13, 17, 23)"
    }
  },
  {
    "name": "svg-standalone-1280",
    "w": 1280,
    "h": 320,
    "scheme": "light",
    "mobile": false,
    "path": "/.github/assets/readme-header.svg",
    "svgStatus": 200,
    "svgMime": "image/svg+xml",
    "failedRequests": [],
    "measured": {
      "root": "svg",
      "w": 1280,
      "h": 320,
      "title": "whatsaaaa README header",
      "scripts": 0,
      "externalRefs": 0
    }
  }
]
Evidence: Asset provenance: committed SVG vs published kit 0.1.0 and 0.1.1

bca7a77d...4181 .github/assets/readme-header.svg bca7a77d...4181 v0.1.0/package/assets/whatsaaaa/readme-header.svg bca7a77d...4181 v0.1.1/package/assets/whatsaaaa/readme-header.svg cmp vs 0.1.0 (locked): identical cmp vs 0.1.1 (latest): identical

# README header vs published @whatsaaaa/design-system kit
bca7a77df9c8afae6b6f5a2a55d1045b0b39932ad921a45e95c9887144484181  .github/assets/readme-header.svg
bca7a77df9c8afae6b6f5a2a55d1045b0b39932ad921a45e95c9887144484181  v0.1.0/package/assets/whatsaaaa/readme-header.svg
bca7a77df9c8afae6b6f5a2a55d1045b0b39932ad921a45e95c9887144484181  v0.1.1/package/assets/whatsaaaa/readme-header.svg
cmp vs 0.1.0 (locked): identical
cmp vs 0.1.1 (latest): identical
# GitHub GFM render of README (first block):
<p dir="auto"><a target="_blank" rel="noopener noreferrer" href=".github/assets/readme-header.svg"><img src=".github/assets/readme-header.svg" alt="whatsaaaa" width="100%" style="max-width: 100%;"></a></p>
Evidence: GitHub GFM API render of README.md
<p dir="auto"><a target="_blank" rel="noopener noreferrer" href=".github/assets/readme-header.svg"><img src=".github/assets/readme-header.svg" alt="whatsaaaa" width="100%" style="max-width: 100%;"></a></p>
<h1 dir="auto">whatsaaaa.github.io</h1>
<p dir="auto">Personal landing page for projects, tools and ideas, served at <a href="https://whatsaaaa.github.io/" rel="nofollow">https://whatsaaaa.github.io/</a>. Built with <a href="https://astro.build" rel="nofollow">Astro</a>.</p>
<h2 dir="auto">Development</h2>
<p dir="auto">Requires Node.js and pnpm at the versions set by <code class="notranslate">engines</code> and <code class="notranslate">packageManager</code> in <code class="notranslate">package.json</code>.</p>
<div class="highlight highlight-source-shell" dir="auto"><pre class="notranslate">pnpm install
pnpm dev       <span class="pl-c"><span class="pl-c">#</span> local dev server at http://localhost:4321</span>
pnpm check     <span class="pl-c"><span class="pl-c">#</span> type-check .astro and .ts files</span>
pnpm lint      <span class="pl-c"><span class="pl-c">#</span> ESLint</span>
pnpm format    <span class="pl-c"><span class="pl-c">#</span> Prettier</span>
pnpm build     <span class="pl-c"><span class="pl-c">#</span> static build into dist/</span>
pnpm preview   <span class="pl-c"><span class="pl-c">#</span> serve the build locally</span></pre></div>
<h2 dir="auto">Adding a project</h2>
<p dir="auto">Add a Markdown file to <code class="notranslate">src/content/projects/</code>. The file name becomes the URL (<code class="notranslate">src/content/projects/my-tool.md</code> is served at <code class="notranslate">/projects/my-tool/</code>). The frontmatter is validated against the schema in <code class="notranslate">src/content.config.ts</code>:</p>
<div class="highlight highlight-text-md" dir="auto"><pre class="notranslate"><span class="pl-s">---</span>
<span class="pl-ent">title</span>: <span class="pl-s">my-tool</span>
<span class="pl-ent">description</span>: <span class="pl-s">One sentence on what it does.</span>
<span class="pl-ent">status</span>: <span class="pl-s">active </span><span class="pl-c"><span class="pl-c">#</span> active | experimental | planned | archived</span>
<span class="pl-ent">tags</span>: <span class="pl-s">[TypeScript]</span>
<span class="pl-ent">links</span>:
  - <span class="pl-ent">label</span>: <span class="pl-s">Source on GitHub</span>
    <span class="pl-ent">url</span>: <span class="pl-s">https://github.com/whatsaaaa/my-tool</span>
<span class="pl-ent">featured</span>: <span class="pl-s">true </span><span class="pl-c"><span class="pl-c">#</span> shown on the home page</span>
<span class="pl-ent">date</span>: <span class="pl-c1">2026-11-10</span>
<span class="pl-s">---</span>

Longer description in Markdown.</pre></div>
<p dir="auto">Ideas work the same way in <code class="notranslate">src/content/ideas/</code>, with <code class="notranslate">title</code>, <code class="notranslate">description</code> and <code class="notranslate">date</code>.</p>
<p dir="auto">Other repositories publish their own GitHub Pages sites under this domain, such as <a href="https://whatsaaaa.github.io/form-builder/" rel="nofollow">https://whatsaaaa.github.io/form-builder/</a>. Do not add pages at those paths.</p>
<h2 dir="auto">Deployment</h2>
<p dir="auto">Every push to <code class="notranslate">main</code> builds the site and deploys it to GitHub Pages through the <a href=".github/workflows/deploy.yml">deploy workflow</a>. It can also be run by hand from the Actions tab. Pull requests run the <a href=".github/workflows/ci.yml">CI workflow</a>: format check, lint, <code class="notranslate">astro check</code> and a build.</p>
Evidence: Rendered README page served to the browser
<!doctype html>
<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<title>README.md (GitHub GFM render) - whatsaaaa.github.io</title>
<link rel="stylesheet" href="css/package/github-markdown.css">
<style>
body{margin:0;background:var(--bgColor-default,#fff)}
@media (prefers-color-scheme: dark){body{background:#0d1117}}
.box{max-width:1012px;margin:24px auto;border:1px solid #d0d7de;border-radius:6px}
@media (prefers-color-scheme: dark){.box{border-color:#30363d}}
.box-header{padding:8px 16px;border-bottom:inherit;font:600 14px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
.markdown-body{box-sizing:border-box;padding:32px}
@media (max-width:767px){.box{margin:0;border-radius:0}.markdown-body{padding:16px}}
</style></head>
<body><div class="box"><div class="box-header markdown-body" style="padding:8px 16px">README</div><article class="markdown-body">
<p dir="auto"><a target="_blank" rel="noopener noreferrer" href=".github/assets/readme-header.svg"><img src=".github/assets/readme-header.svg" alt="whatsaaaa" width="100%" style="max-width: 100%;"></a></p>
<h1 dir="auto">whatsaaaa.github.io</h1>
<p dir="auto">Personal landing page for projects, tools and ideas, served at <a href="https://whatsaaaa.github.io/" rel="nofollow">https://whatsaaaa.github.io/</a>. Built with <a href="https://astro.build" rel="nofollow">Astro</a>.</p>
<h2 dir="auto">Development</h2>
<p dir="auto">Requires Node.js and pnpm at the versions set by <code class="notranslate">engines</code> and <code class="notranslate">packageManager</code> in <code class="notranslate">package.json</code>.</p>
<div class="highlight highlight-source-shell" dir="auto"><pre class="notranslate">pnpm install
pnpm dev       <span class="pl-c"><span class="pl-c">#</span> local dev server at http://localhost:4321</span>
pnpm check     <span class="pl-c"><span class="pl-c">#</span> type-check .astro and .ts files</span>
pnpm lint      <span class="pl-c"><span class="pl-c">#</span> ESLint</span>
pnpm format    <span class="pl-c"><span class="pl-c">#</span> Prettier</span>
pnpm build     <span class="pl-c"><span class="pl-c">#</span> static build into dist/</span>
pnpm preview   <span class="pl-c"><span class="pl-c">#</span> serve the build locally</span></pre></div>
<h2 dir="auto">Adding a project</h2>
<p dir="auto">Add a Markdown file to <code class="notranslate">src/content/projects/</code>. The file name becomes the URL (<code class="notranslate">src/content/projects/my-tool.md</code> is served at <code class="notranslate">/projects/my-tool/</code>). The frontmatter is validated against the schema in <code class="notranslate">src/content.config.ts</code>:</p>
<div class="highlight highlight-text-md" dir="auto"><pre class="notranslate"><span class="pl-s">---</span>
<span class="pl-ent">title</span>: <span class="pl-s">my-tool</span>
<span class="pl-ent">description</span>: <span class="pl-s">One sentence on what it does.</span>
<span class="pl-ent">status</span>: <span class="pl-s">active </span><span class="pl-c"><span class="pl-c">#</span> active | experimental | planned | archived</span>
<span class="pl-ent">tags</span>: <span class="pl-s">[TypeScript]</span>
<span class="pl-ent">links</span>:
  - <span class="pl-ent">label</span>: <span class="pl-s">Source on GitHub</span>
    <span class="pl-ent">url</span>: <span class="pl-s">https://github.com/whatsaaaa/my-tool</span>
<span class="pl-ent">featured</span>: <span class="pl-s">true </span><span class="pl-c"><span class="pl-c">#</span> shown on the home page</span>
<span class="pl-ent">date</span>: <span class="pl-c1">2026-11-10</span>
<span class="pl-s">---</span>

Longer description in Markdown.</pre></div>
<p dir="auto">Ideas work the same way in <code class="notranslate">src/content/ideas/</code>, with <code class="notranslate">title</code>, <code class="notranslate">description</code> and <code class="notranslate">date</code>.</p>
<p dir="auto">Other repositories publish their own GitHub Pages sites under this domain, such as <a href="https://whatsaaaa.github.io/form-builder/" rel="nofollow">https://whatsaaaa.github.io/form-builder/</a>. Do not add pages at those paths.</p>
<h2 dir="auto">Deployment</h2>
<p dir="auto">Every push to <code class="notranslate">main</code> builds the site and deploys it to GitHub Pages through the <a href=".github/workflows/deploy.yml">deploy workflow</a>. It can also be run by hand from the Actions tab. Pull requests run the <a href=".github/workflows/ci.yml">CI workflow</a>: format check, lint, <code class="notranslate">astro check</code> and a build.</p></article></div></body></html>

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 4 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Committed README header is an unedited copy of the whatsaaaa header in the published design-system kit (oracle: npm tarballs of @whatsaaaa/design-system 0.1.0 and 0.1.1) ✅ pass live asset-provenance.txt: SHA-256 bca7a77d...4181 and cmp identical for the worktree file vs assets/whatsaaaa/readme-header.svg in both tarballs; the manifest lists it as 'Header for a README.'
A visitor opening README.md on GitHub sees the whatsaaaa header at the very top, above the 'whatsaaaa.github.io' title (GitHub GFM API render + github-markdown-css in headless Chrome, light mode, 1280… ✅ pass live shots/readme-light-1280.png; render-report.json readme-light-1280: complete=true, naturalWidth=1280x320, first block contains img, imgAboveH1=true, alt='whatsaaaa', no failed requests
Header adapts to GitHub dark mode and narrow mobile screens without distortion or overflow (dark/light at 390px, dark at 1280px) ✅ pass live shots/readme-dark-1280.png, shots/readme-light-390.png, shots/readme-dark-390.png; render-report.json: renderedW equals the content width (948px / 356px), aspect=4.000, horizontalOverflow=false in eve…
Adversarial: header still draws inside GitHub's sandboxed <img> (no scripts, web fonts or external references that GitHub would block) ✅ pass live shots/svg-standalone-1280.png; render-report.json svg-standalone-1280: scripts=0, externalRefs=0, renders 1280x320; text is drawn as paths, so it doesn't depend on fonts. In the README screenshots the…
Header shows on the live github.com repository page for branch fm/readme-assets-website ⏸️ untested no The branch isn't on GitHub yet; pushing is a later pipeline phase owned by the outer executor, and this phase is not allowed to push. As the closest local stand-in, I used GitHub's real GFM render API…
  • npm pack @whatsaaaa/design-system@0.1.0 @whatsaaaa/design-system@0.1.1 then cmp/shasum -a 256 of .github/assets/readme-header.svg against assets/whatsaaaa/readme-header.svg in both tarballs
  • Parsed the kit's assets/manifest.json (identities: whatsaaaa, building-blocks, dotfiles, form-builder) and read docs/usage.md section 9 to confirm readme-header.svg is the asset for the top of a README and must be copied unedited
  • gh api -X POST /markdown -f mode=gfm -f context=whatsaaaa/whatsaaaa.github.io -F text=@README.md (GitHub's real GFM sanitizer/renderer)
  • Served the rendered README with github-markdown-css via python3 -m http.server on 127.0.0.1:47811
  • node scripts/shoot.mjs driving headless Chrome for Testing 157 over CDP: README at 1280x900 and 390x844, light and dark color schemes, plus the standalone SVG at 1280x320; measured img load/naturalWidth/rendered width/aspect/position/overflow and captured screenshots
  • git ls-files | grep -i readme to confirm README.md is the only README in the repo
  • gh api repos/whatsaaaa/whatsaaaa.github.io/branches/fm/readme-assets-website (404: branch not pushed yet, so the live github.com page can't be checked)
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

@whatsaaaa
whatsaaaa merged commit 5ee1238 into main Nov 13, 2026
1 check passed
@whatsaaaa
whatsaaaa deleted the fm/readme-assets-website branch November 13, 2026 21:24
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