bonsai/docs/code-standards.md

Code standards

How code in this theme is written and why. The goal is predictability — both for humans reading the diff and for LLM-driven tooling navigating the repo.

File naming

• Kebab-case for all filenames: link-button.html, theme-toggle.js, schema-website.html.
• Long descriptive names beat short cryptic ones — analytics-loader.html is better than al.html.
• Hugo partials living under layouts/partials/ use the .html extension even when they emit JSON-LD or <script> blocks — Hugo doesn't care about extension, but consistency helps grep.

Partial composition

Each partial reads its input via exactly one of:

1. site.Params directly — for page-wide singletons (head.html, bio-card.html, schema-person.html).
2. A dict argument — for reusable rendering blocks (link-group.html, link-button.html).

Never both. If a partial needs context, pass it explicitly.

CSS conventions

• BEM-ish naming: .block, .block__elem, .block--modifier. Examples: .bio, .bio__avatar, .bio__avatar--initials, .link, .link__icon, .link--featured.
• CSS custom properties for every user-tunable value: colors per palette, layout sizes, fonts. Live in :root (layout) or [data-bonsai-theme="…"] blocks (color).
• No !important except the noscript rule hiding .theme-toggle when JS is disabled.
• No deeply nested selectors — keep specificity at ≤ (0,2,0). The single attribute selector svg[stroke="currentColor"] is the only exception.
• No web fonts — system font stacks only (ui-sans-serif, system-ui, ui-serif, Georgia).
• Honor prefers-reduced-motion — every transition lives behind a media query that disables it.

Template patterns

• Variable-first: read params/inputs into named locals at the top of the partial. Branches use the locals.
• with over nil-checks where idiomatic: {{ with $tagline }}…{{ end }} is preferred over {{ if $tagline }}…{{ end }}.
• else if, not else with — else with had stricter parser rules in some Hugo versions; else if is universal.
• safeHTML / safeJS / safeCSS only when the value comes from a vetted source (an i18n bundle string or a Hugo jsonify payload). Never for user-controlled content rendered raw.
• Warn loudly for misconfigurations — warnf produces a build-time warning without failing the build.

i18n keys

• Snake_case: nav_links_label, skip_to_content, share_copied.
• Every user-facing string the theme renders goes through {{ i18n "key" }}. Add a fallback default with | default "…" so missing keys don't leak raw identifiers into the DOM.
• Both en.toml and vi.toml must be updated together for any new key.

Asset handling

• All processable assets live under assets/ (assets/css/, assets/js/, assets/icons/, optional assets/avatars/, assets/og/, assets/fonts/).
• static/ is for files Hugo should copy through verbatim — _headers, vercel.json, demo media that won't be processed.
• Fingerprint + minify + SRI every CSS and JS file shipped to production: resources.Get | resources.Minify | resources.Fingerprint "sha384" → emit with integrity= + crossorigin="anonymous".

Opt-in posture

Every new feature is off by default. A v0.4 site upgraded to v0.5 must build with byte-identical output unless the user explicitly opts in. This rule has zero exceptions.

When unsure: ship with a param.foo = false default and document the opt-in in README.

Build invariants

• hugo --gc --minify --themesDir ../.. from exampleSite/ must produce a clean build with no ERROR lines.
• Lighthouse CI must pass thresholds ≥ 0.90 across Performance, Accessibility, Best-Practices, SEO.
• No new console.error / console.warn from theme JS at runtime.
• CSS production size budget: ≤ 5.5 KB gzipped (stretch ≤ 5 KB).

Commit messages

Conventional commits: feat:, fix:, docs:, refactor:, chore:, test:, style:. Scope is optional but helpful: feat(theme): add multi-section bio.

No AI references in commit messages. Keep them describing the change, not the process.