docs(journal): v0.1 release retro

2026-09-02 06:19:52 +00:00 · 2026-05-03 11:11:19 +07:00
parent 9be87cd573
commit 85ecdc622f
1 changed files with 59 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Bonsai v0.1: Icon Library Split Forced Mid-Course Correction
+
+**Date**: 2026-05-03 14:30  
+**Severity**: Medium  
+**Component**: Icon system, asset paths, demo deployment  
+**Status**: Resolved  
+
+## What Happened
+
+Shipped Bonsai v0.1.0 to Hugo themes catalog in one day: icon system overhaul (Lucide + Simple Icons vendoring), CI/CD pipeline, GitHub Pages demo, docs, submission assets, and PR #708 to gohugoio. All 6 phases executed end-to-end with 11 commits. Live at https://tiennm99.github.io/bonsai/; catalog PR awaiting review.
+
+## The Brutal Truth
+
+Shipping a theme on spec in 15 hours felt clean until we deployed. The first three surprises weren't fatal but exposed how little we knew about Hugo's URL handling under GitHub Pages subpaths and how Chromium renders fonts in CI. Each one cost a fix commit. The Japanese avatar glyph as tofu in a headless browser was funny; the SVGs rendering at 0×0 was not.
+
+## Technical Details
+
+1. **Icon library split enforcement**: Lucide intentionally omits brand/social icons (design principle). Simple Icons provides them but ships SVGs with only `viewBox`, no intrinsic dimensions. First screenshot: brand icons invisible. Fix: `.link__icon svg { width:20px; height:20px }` in `assets/css/style.css`.
+
+2. **Hugo URL function behavior under subpaths**: `relURL` and `absURL` pass through leading-slash inputs unchanged, which bypasses the baseURL subpath. Asset paths broke on `tiennm99.github.io/bonsai/static/*`. Fix: strip leading slash before `relURL`: `strings.TrimPrefix "/" $path | relURL` in `partials/icon.html` and layout.
+
+3. **Chromium headless rendering**: No Japanese fonts in Docker env → 盆 monogram rendered as tofu boxes. Switched to Latin "T" in avatar. Future: any glyph-specific UX needs SVG paths or pre-rendered images.
+
+4. **Playwright Docker deps**: Headless Chromium needs system libs absent from base image: `libnss3 libnspr4 libatk1.0-0t64 libatspi2.0-0t64 libxcomposite1 libxdamage1 libcups2t64`. Documented in `scripts/capture-screenshots.sh`.
+
+## What We Tried
+
+- Initial icon partial used inline SVGs only (8 icons) — ran out of coverage, switched to two-source vendoring.
+- Attempted to use Lucide as single source — failed (no brand icons by design).
+- First deploy: brand icons invisible in screenshots — diagnostic: SVGs had viewBox only, zero dimensions in flex layout.
+- Japanese avatar: rendered in local dev, broke in CI — switching glyph is safer than shipping fonts.
+
+## Root Cause Analysis
+
+**Icon library research was shallow.** The plan correctly identified the split strategy, but we didn't validate that Simple Icons SVGs lack intrinsic dimensions until deploy. A quick inspection of one SVG from each library before implementation would have caught this.
+
+**URL function assumptions didn't account for subpath deploys.** Standard Hugo docs assume domain root. GitHub Pages subpaths require different handling. Should've tested asset paths locally with `baseURL: /bonsai/` before CI.
+
+**No validation that Chromium env matched design expectations.** The avatar glyph choice was visual-first; zero verification that it would render in the CI environment.
+
+## Lessons Learned
+
+1. **Inspect library assets, don't trust API docs.** Download one SVG from each icon library, check for width/height attributes, test in a flex container.
+
+2. **Test baseURL subpaths locally.** Hugo's GitHub Pages subpath handling is a gotcha. Always `hugo server --baseURL http://localhost:1313/bonsai/` before deploy.
+
+3. **Headless rendering != local rendering.** Fonts, system libs, and environment assumptions bite hard. Build and screenshot in CI early, not on final push.
+
+4. **Document dependency chains in scripts.** The Playwright setup needed specific system packages. Future: add precheck or include install hints in README.
+
+## Next Steps
+
+- Monitor PR #708 review feedback from Hugo catalog maintainers.
+- If layout changes are requested, we have the icon system and CI infrastructure in place to iterate.
+- For v1.0: consider layout variants (cards/grid) — the data-driven icon partial scales well.
+- Keep screenshot capture script maintenance low: Playwright + Chromium is reliable once deps are documented.
+
+**Owner**: @tiennm99  
+**Timeline**: v0.2 planning after catalog acceptance feedback