mirror of
https://github.com/tiennm99/tsuki.git
synced 2026-08-15 10:25:08 +00:00
docs: v0.3.0 sync — CHANGELOG, accessibility statement, plan close-out
- README: add a11y badge linking to docs/accessibility.md. - CHANGELOG: full v0.3.0 entry under Unreleased (Added/Changed/Fixed/ Deferred-to-v0.3.1). Documents per-kind CSS bundles, Tier A features, Lighthouse-relevant polish, contrast-token visual diff, tap-target sizing decisions, and Hugo CI matrix. - docs/accessibility.md: new — WCAG 2.2 AA conformance summary, Lighthouse measurement instructions, projected baseline (TBD entries to fill after first production deploy), known limitations. - docs/customization.md: cover-image override snippet (v0.4.0 native pipeline promise); document breadcrumbs/prev-next/lang-switcher opt-ins. - plans/260510-0144-tsuki-v0.3.0/: mark all phases completed; note narrow-TOC <details> deferral to v0.3.1; record audit-pass scope additions integrated into Phases 2–6. - plans/reports/: add researcher-260515-tsuki-vs-stack-papermod-feature -gap.md (verdict: feature parity on must-haves; Tier A gaps shipped this round) + code-reviewer-260515-lighthouse-80-baseline-audit.md (projected ≥80 on all 4 categories; ≥95 a11y achievable with shipped fixes).
This commit is contained in:
+42
-1
@@ -2,12 +2,53 @@
|
||||
|
||||
All notable changes to tsuki will be documented here. Format follows [Keep a Changelog](https://keepachangelog.com/), versioning follows [SemVer](https://semver.org/).
|
||||
|
||||
## [Unreleased]
|
||||
## [Unreleased] — v0.3.0
|
||||
|
||||
Feature-parity round + Lighthouse ≥80 baseline. Six phases per `plans/260510-0144-tsuki-v0.3.0/`. Net: tsuki now ships breadcrumbs, prev/next post navigation, language switcher UI, llm.txt, English i18n bundle, and per-page-kind CSS bundles, while maintaining the ≤4 KB gz / page-kind / ≤1 KB gz JS hard caps.
|
||||
|
||||
### Added
|
||||
|
||||
- **Per-page-kind CSS bundles** — `head.html` now assembles separate bundles per page kind. `core.css` (tokens + reset + typography + layout + components + view-transitions) loads everywhere; `home.css` only on home; `single.css` (toc + callouts + comments + single-extras) only on posts; `archive.css` only under `/archives/`; `search.css` only on `/search/`. Frees ~1 KB gz from non-post pages and unlocks Phase 3 feature growth without breaching budget.
|
||||
- **`code-copy.js` gated to post pages** — separate `<script type=module>` emit on `eq .Kind "page"`; home/list/search no longer load the dead 0.5 KB gz.
|
||||
- **Pagefind UI CSS preload-swap** — `/search/` now `<link rel="preload" as="style" ... onload>` the third-party stylesheet with `<noscript>` fallback. No longer render-blocking.
|
||||
- **Giscus preconnect** — `<link rel="preconnect" href="https://giscus.app">` emitted only on post pages with comments fully configured. Shaves third-party DNS+TLS handshake.
|
||||
- **Breadcrumbs partial** (`_partials/breadcrumbs.html`) — opt-in via `params.breadcrumbs.enable`. Renders Home › Section › Page trail above the post header and emits matching `BreadcrumbList` JSON-LD for SEO. Off by default; demo enables it.
|
||||
- **Prev/next post navigation** (`_partials/prev-next.html`) — opt-in via `params.prevNextNav.enable` (default true). Two-card layout below the post, `rel="prev"` / `rel="next"` for SEO. Renders single-cell when only one neighbour exists.
|
||||
- **Language switcher UI** (`_partials/lang-switcher.html`) — auto-emits when `hugo.IsMultilingual` is true; renders nothing on single-language sites. Marks active language with `aria-current="page"`.
|
||||
- **`hreflang` alternate links** — `<link rel="alternate" hreflang="...">` per `.AllTranslations` + `x-default`, gated on `hugo.IsMultilingual`.
|
||||
- **`i18n/en.yml`** — full English starter (~50 keys) mirroring `vi.yml`. Theme builds with `defaultContentLanguage: en` without missing-key fallbacks.
|
||||
- **`linkToSection` i18n key** + **`breadcrumb`, `breadcrumbHome`, `prevPost`, `nextPost`, `copyCode`, `copiedCode`** keys added to both bundles.
|
||||
- **`<meta name="theme-color">`** — two variants for light/dark `(prefers-color-scheme)`. Mobile browsers theme their chrome to match the site.
|
||||
- **`aria-pressed` SSR** on theme-toggle — rendered in HTML before paint so axe/Lighthouse never see a missing-state toggle button.
|
||||
- **`<details>` styling** in `single-extras.css` — markdown collapse blocks now render with border + padding + dark-mode awareness.
|
||||
- **`/llm.txt` output format** — custom Hugo output format on the home; emits a plain-text summary of site + bio + recent posts + projects per [llmstxt.org](https://llmstxt.org). Builds automatically; consumers can override `layouts/index.llmtxt.txt`.
|
||||
- **Speculation Rules opt-in** — `<script type="speculationrules">` emitted when `params.prefetch.enable: true`. Default rules prefetch internal links with `moderate` eagerness, excluding `/search/*`. Override with `params.prefetch.rules` raw JSON.
|
||||
- **`docs/accessibility.md`** — WCAG 2.2 AA conformance statement, known limitations, Lighthouse measurement instructions, baseline table (TBD entries to fill on next production deploy).
|
||||
- **README a11y badge** linking to `docs/accessibility.md`.
|
||||
- **Hugo CI matrix** — `pages.yml` builds + smoke-tests on Hugo 0.146 (theme.toml floor) and 0.154 (pinned current). Deploy uploads only the current version.
|
||||
- **15+ new smoke-test assertions** in `scripts/smoke-tests.sh` covering: theme-color meta, aria-pressed SSR, breadcrumbs + BreadcrumbList JSON-LD, prev/next nav with rel attrs, heading-anchor aria-label i18n, llm.txt presence, Speculation Rules absence by default, Pagefind preload-swap, Giscus-preconnect gating, per-page-kind CSS bundle routing, code-copy.js gating. Total checks: 32 (was 11).
|
||||
|
||||
### Changed
|
||||
|
||||
- **`--tsuki-fg-subtle`** light-mode darkened from `#888` to `#6b6b6b` for WCAG AA contrast (`#888` was 3.54:1 against `#fbfaf7`; fails 4.5:1 body-text threshold). Affects post-card date, pagination disabled state, heading anchor — they now render slightly darker. Dark-mode `#777` unchanged (passes at 4.7:1). Visual diff is subtle; consumers theming the token are unaffected.
|
||||
- **Pagination disabled state** uses `--tsuki-fg-muted` + `cursor: not-allowed`. Dropped the `opacity: 0.5` compound that double-dimmed text below contrast.
|
||||
- **Tap targets enlarged** — header theme-toggle + search-button bumped from `2rem` (32px) to `2.5rem` (40px); pagination links use `min-width: 2.75rem; min-height: 2.75rem` (44px); footer links get `padding-block`. Closer to Lighthouse's 48×48 audit target. Header buttons may still trip the strict 48px check; documented in `docs/accessibility.md`.
|
||||
- **`<html lang>`** fallback chain — was hard-coded `"vi"`; now `site.Language.LanguageCode | default site.Language.Lang | default "en"`. English-default sites no longer paint `lang="vi"`.
|
||||
- **`render-heading.html` `aria-label`** moved from hard-coded vi to `i18n "linkToSection"` (defaults to "Link to section" when key missing).
|
||||
- **`code-copy.js`** reads `data-copy-code` / `data-copied-code` from `<html>` (set by `baseof.html` via `i18n` resolution). Adds `data-state="copied"` for CSS styling polish.
|
||||
- **`scripts/smoke-tests.sh`** asserts per-kind CSS budget (each page kind ≤ 4200 B gz) instead of aggregate. CI workflow drops the now-redundant standalone budget step.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **CI htmltest URLSwap** — `.htmltest.yml` now strips the `/tsuki/` baseURL prefix so internal-link checks resolve against `exampleSite/public/`. Was failing on every CI run since v0.2.0; deploys did not propagate until this fix. No theme-side change.
|
||||
|
||||
### Deferred to v0.3.1
|
||||
|
||||
- Narrow-viewport TOC `<details>` collapse (UX ambiguity on wide-viewport summary toggle + CSS budget pressure)
|
||||
- Synthetic test posts for branch coverage (`lastmod-test.md`, `no-tags-test.md`)
|
||||
- Optional Lighthouse-CI workflow (manual measurement for now via `docs/accessibility.md`)
|
||||
- Default cover-image renderer pipeline (`images.Resize` + srcset/AVIF) — see `docs/customization.md` for override snippet; built-in support targeted for v0.4.0
|
||||
|
||||
## [0.2.1] — 2026-05-10
|
||||
|
||||
Patch release. Closes 5 P1 correctness/security findings from the post-v0.2.0 review plus 2 CI hygiene items. No new features.
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
[](LICENSE)
|
||||
[](https://gohugo.io)
|
||||
[](https://github.com/tiennm99/tsuki/actions/workflows/pages.yml)
|
||||
[](docs/accessibility.md)
|
||||
|
||||
A Hugo blog + personal portfolio theme. The homepage *is* the portfolio — bio, featured projects, recent posts. Posts live at `/post/`. Vietnamese-first typography, View Transitions on navigation, Pagefind search, Giscus comments.
|
||||
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# Accessibility
|
||||
|
||||
tsuki targets **WCAG 2.2 AA** conformance with **Lighthouse Accessibility ≥ 95** on every page kind. This document records what's covered, what's deferred, and how to measure on your own site.
|
||||
|
||||
## Conformance summary
|
||||
|
||||
| Area | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Skip link | ✅ Shipped | First focusable; jumps to `<main id="main">` |
|
||||
| Landmark roles | ✅ Shipped | `<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>` |
|
||||
| Visible focus rings | ✅ Shipped | `:focus-visible` with 2px outline + accent colour |
|
||||
| `<html lang>` correctness | ✅ Shipped | Resolves from `site.Language.Lang`; falls back to `"en"` |
|
||||
| `aria-pressed` on toggle | ✅ Shipped | SSR-rendered before paint |
|
||||
| `<meta name="theme-color">` | ✅ Shipped | Light + dark variants |
|
||||
| Heading anchor i18n | ✅ Shipped | `aria-label` uses `linkToSection` i18n key |
|
||||
| Reduced motion | ✅ Shipped | View Transitions + animations honour `prefers-reduced-motion` |
|
||||
| Colour contrast (text) | ✅ Shipped | All body text ≥ 4.5:1 in both themes; `--tsuki-fg-subtle` darkened to `#6b6b6b` (light) for AA compliance |
|
||||
| Pagination disabled-state contrast | ✅ Shipped | Uses `--tsuki-fg-muted` + `cursor: not-allowed`; no `opacity` compound |
|
||||
| Tap targets ≥ 40×40 | ✅ Shipped | Header toggle/search-button 2.5rem; pagination 2.75rem; footer links padded |
|
||||
| Tap targets ≥ 48×48 (strict Lighthouse) | ⚠️ Partial | Header buttons at 40×40 (2.5rem); Lighthouse may flag, score remains ≥ 80 |
|
||||
| Forms (search) | ✅ Shipped | Pagefind UI ships its own label semantics |
|
||||
| `<details>` keyboard support | ✅ Native | Tab → Enter to toggle |
|
||||
| Drag operations (SC 2.5.7) | ✅ N/A | Theme has no drag UI |
|
||||
|
||||
## Measuring on your site
|
||||
|
||||
Use the latest Chrome DevTools or `lighthouse` CLI:
|
||||
|
||||
```bash
|
||||
npx lighthouse https://your-site.example.com/ \
|
||||
--only-categories=accessibility,performance,best-practices,seo \
|
||||
--form-factor=mobile --throttling-method=simulate \
|
||||
--output=html --output-path=./lh.html
|
||||
```
|
||||
|
||||
Run against **production** (a live URL), not a localhost build — service workers, caching, TLS, and font loading all affect scores.
|
||||
|
||||
## Project baseline
|
||||
|
||||
Measured on `https://tiennm99.github.io/tsuki/` (mobile profile, median of 3 runs). Update these when the build changes materially.
|
||||
|
||||
| Page kind | Performance | A11y | Best Practices | SEO |
|
||||
|-----------|------------:|-----:|---------------:|----:|
|
||||
| Home (`/`) | TBD | TBD | TBD | TBD |
|
||||
| Post | TBD | TBD | TBD | TBD |
|
||||
| List (`/post/`) | TBD | TBD | TBD | TBD |
|
||||
| Search (`/search/`) | TBD | TBD | TBD | TBD |
|
||||
|
||||
Targets: Performance ≥ 80, Accessibility ≥ 95, Best Practices ≥ 80, SEO ≥ 80.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- **Tap targets on the header buttons** — theme-toggle and search-button are 40×40 px (2.5rem). The Lighthouse "Tap targets are sized appropriately" audit measures against 48×48 px and may flag these. Visual design tradeoff; bump to 3rem to silence the audit at the cost of a larger header footprint.
|
||||
- **`prefers-color-scheme: no-preference`** is treated as light. There is no third "auto" state in the toggle UI — click cycles light ↔ dark only.
|
||||
- **Goldmark `unsafe: true`** is the default — your content controls what HTML renders. Untrusted authorship surfaces should override `markup.goldmark.renderer.unsafe: false`.
|
||||
- **Pagefind UI** ships its own CSS and ARIA semantics. tsuki maps colour tokens but does not override Pagefind's structure.
|
||||
|
||||
## Reporting accessibility regressions
|
||||
|
||||
Open an issue at [tiennm99/tsuki](https://github.com/tiennm99/tsuki/issues) with the WCAG 2.2 SC reference and a reproduction URL. Patches welcome.
|
||||
@@ -175,3 +175,51 @@ Per-post:
|
||||
toc: false
|
||||
comments: false
|
||||
```
|
||||
|
||||
## Cover images
|
||||
|
||||
`cover.image` is currently used for OG / Twitter card metadata only — the theme does **not** render a hero cover above the post title by default. This avoids LCP regressions on themes with un-optimised consumer-supplied images.
|
||||
|
||||
To render a cover, override `layouts/single.html` in your site:
|
||||
|
||||
```hugo
|
||||
{{ define "main" }}
|
||||
{{ partial "breadcrumbs.html" . }}
|
||||
|
||||
<article class="post">
|
||||
<header class="post-header">
|
||||
{{- with .Params.cover.image }}
|
||||
{{- /* Use Hugo image processing for a responsive, hashed asset */ -}}
|
||||
{{- $img := resources.Get . | images.Resize "1200x" -}}
|
||||
<img class="post-cover"
|
||||
src="{{ $img.RelPermalink }}"
|
||||
width="{{ $img.Width }}" height="{{ $img.Height }}"
|
||||
alt="" fetchpriority="high" decoding="async">
|
||||
{{- end }}
|
||||
<h1 class="post-title">{{ .Title }}</h1>
|
||||
{{ partial "meta.html" . }}
|
||||
</header>
|
||||
<div class="post-content" data-pagefind-body>{{ .Content }}</div>
|
||||
</article>
|
||||
|
||||
{{ partial "prev-next.html" . }}
|
||||
{{ partial "related-posts.html" . }}
|
||||
{{ partial "comments.html" . }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
A built-in cover pipeline with `srcset`/AVIF is planned for **v0.4.0**.
|
||||
|
||||
## Breadcrumbs, prev/next, language switcher
|
||||
|
||||
These ship in v0.3.0 as opt-in features.
|
||||
|
||||
```yaml
|
||||
params:
|
||||
breadcrumbs:
|
||||
enable: true # Home › Section › Page trail + BreadcrumbList JSON-LD
|
||||
prevNextNav:
|
||||
enable: true # in-section prev/next post nav below content
|
||||
```
|
||||
|
||||
The language switcher partial auto-emits when `hugo.IsMultilingual` is true; no config flag needed.
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
phase: 2
|
||||
title: "Theme-budget rebase — per-kind CSS + JS gate + default cleanup"
|
||||
status: pending
|
||||
status: completed
|
||||
priority: P1
|
||||
effort: "1d"
|
||||
dependencies: [1]
|
||||
completed_date: 2026-05-15
|
||||
---
|
||||
|
||||
# Phase 2: Theme-budget rebase
|
||||
@@ -105,5 +106,53 @@ Each bundle: `Concat | minify | fingerprint | resources.Get`, emit one `<link re
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 3 depends on Phase 2's bundle layout (details CSS slots into single.css)
|
||||
- Phase 3 depends on Phase 2's bundle layout (details CSS + breadcrumbs CSS + prev/next CSS slot into single.css)
|
||||
- Phase 5 depends on Phase 2's freed budget
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
Cheap perf wins folded in here because they touch the same `head.html` / network-emit surface as the budget rebase. Both are <10 lines each.
|
||||
|
||||
### A2.1 — Pagefind UI CSS preload-swap (Lighthouse P0-2)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P0-2.
|
||||
|
||||
**Problem:** Pagefind UI ships its own stylesheet via `<link rel="stylesheet">` which is render-blocking on the search page.
|
||||
|
||||
**Fix:** ~3 lines in `layouts/search/list.html`. Use preload-swap pattern:
|
||||
|
||||
```html
|
||||
<link rel="preload" as="style" href="{{ ... pagefind-ui.css ... }}" onload="this.rel='stylesheet'">
|
||||
<noscript><link rel="stylesheet" href="{{ ... pagefind-ui.css ... }}"></noscript>
|
||||
```
|
||||
|
||||
**Why this phase:** Phase 2 owns CSS budget + load-order discipline; the Pagefind swap is the same discipline applied to the third-party stylesheet on the one page it lands.
|
||||
|
||||
**Files modified:**
|
||||
- `layouts/search/list.html` — swap link tag
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Pagefind UI CSS uses preload-swap pattern on `/search/`
|
||||
- [ ] `<noscript>` fallback present (no-JS users still get styled search)
|
||||
|
||||
### A2.2 — Conditional preconnect to giscus.app (Lighthouse P1-5)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P1-5.
|
||||
|
||||
**Problem:** Giscus iframe lazy-loads from `giscus.app` post-paint; no preconnect means TLS+DNS happen on demand, hurting INP on comment-enabled posts.
|
||||
|
||||
**Fix:** In `layouts/_partials/head.html`, emit `<link rel="preconnect" href="https://giscus.app">` only when (a) page is a post (`.Kind == "page"`), (b) `params.comments.giscus.enable: true`, and (c) all required Giscus params present (matches Phase 1 P1-5 strict gate).
|
||||
|
||||
**Why this phase:** Same gate structure as P1-5 in Phase 1; same `<head>` emit logic as the per-kind CSS bundle in this phase. Single template branch.
|
||||
|
||||
**Files modified:**
|
||||
- `layouts/_partials/head.html` — add conditional preconnect block
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] preconnect emits only on post pages with Giscus fully configured
|
||||
- [ ] absent from home/list/search HTML even when Giscus configured
|
||||
- [ ] absent from post pages when Giscus disabled or partially configured
|
||||
|
||||
### Effort delta
|
||||
|
||||
+0.2d (small additions, but verification on demo + smoke test adjustments). Phase 2 still fits in ~1d if Phase 1 work is clean. **Code comments / smoke-test names must not reference "P0-2" or "P1-5"** — describe the behavior ("Pagefind CSS preload swap"; "Giscus preconnect when comments enabled") per project rules.
|
||||
|
||||
@@ -1,13 +1,16 @@
|
||||
---
|
||||
phase: 3
|
||||
title: "Author UX — details + TOC narrow + en.yml"
|
||||
status: pending
|
||||
title: "Author UX + Tier A parity — details, TOC narrow, en.yml, breadcrumbs, prev/next, code-copy UI, lang switcher, hreflang"
|
||||
status: completed
|
||||
priority: P2
|
||||
effort: "1d"
|
||||
effort: "2d"
|
||||
dependencies: [2]
|
||||
amended: 2026-05-15
|
||||
completed_date: 2026-05-15
|
||||
notes: "Narrow-viewport TOC <details> wrap deferred to v0.3.1 (UX ambiguity on wide + tight bundle budget)."
|
||||
---
|
||||
|
||||
# Phase 3: Author UX
|
||||
# Phase 3: Author UX + Tier A feature parity
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -85,5 +88,168 @@ None — additive content/styling only, no new dynamic surface.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 4 (WCAG audit) inspects this phase's new keyboard surfaces
|
||||
- Phase 6 smoke tests get a "details renders styled" assertion
|
||||
- Phase 4 (WCAG audit + Lighthouse ≥80) inspects this phase's expanded keyboard + visual surface (breadcrumbs links, prev/next links, code-copy button, language switcher dropdown)
|
||||
- Phase 6 smoke tests get "details renders styled", "breadcrumbs JSON-LD valid", "prev/next link rel-attrs", "code-copy class present", "lang switcher emit gated"
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
Phase 3 grew significantly. Tier A feature parity (researcher report) lives here because it's all author-facing UX, not AI-discovery. Folding into Phase 3 rather than spinning up a Phase 7 because:
|
||||
|
||||
1. Shared CSS bundle (`single.css` already touched for `<details>`); 1 bundle pass instead of 2.
|
||||
2. Shared i18n key updates with the existing en.yml work (breadcrumb labels, prev/next labels, language names).
|
||||
3. Phase 4 (WCAG + Lighthouse) needs the full surface to audit at once.
|
||||
|
||||
Cost: Phase 3 effort 1d → 2d. Cheaper than coordinating a 7th phase.
|
||||
|
||||
### A3.1 — Breadcrumbs partial with BreadcrumbList schema (Tier A)
|
||||
|
||||
**Source:** researcher-260515-tsuki-vs-stack-papermod-feature-gap.md → Tier A item #3.
|
||||
|
||||
**Problem:** Stack + PaperMod ship breadcrumbs; tsuki ships none. Hurts UX clarity on deep posts + loses BreadcrumbList SEO signal.
|
||||
|
||||
**Fix:** New partial `layouts/_partials/breadcrumbs.html`. Gated via `params.breadcrumbs.enable` (default off — opt-in per backwards-compat rule). Emits both rendered breadcrumb trail and `BreadcrumbList` JSON-LD when enabled.
|
||||
|
||||
**Markup pattern:** `Home > /posts/ > {{ .Title }}` (use `.CurrentSection`, `.Parent`, `.Title`).
|
||||
|
||||
**Schema:** Include `BreadcrumbList` JSON-LD inline in the partial (sibling to existing Article JSON-LD in `seo.html`); compose `itemListElement` from same hierarchy.
|
||||
|
||||
**Files modified/created:**
|
||||
- Create: `layouts/_partials/breadcrumbs.html`
|
||||
- Create: `assets/css/breadcrumbs.css` (~50 B gz; add to Phase 2 `single.css` bundle)
|
||||
- Modify: `layouts/_default/single.html` or relevant single layout — include partial above article header
|
||||
- Modify: `docs/config.md` — document `params.breadcrumbs.enable`
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — add `breadcrumbHome` (vi: "Trang chủ", en: "Home")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] `params.breadcrumbs.enable: true` renders trail above post title
|
||||
- [ ] BreadcrumbList JSON-LD parses (jq) and matches rendered trail
|
||||
- [ ] Disabled by default; absent on all kinds when flag unset
|
||||
- [ ] Breadcrumb link tap targets ≥48×48 (Phase 4 verifies)
|
||||
|
||||
### A3.2 — Prev/Next post navigation (Tier A)
|
||||
|
||||
**Source:** researcher-260515 → Tier A item #4.
|
||||
|
||||
**Problem:** Stack/PaperMod ship prev/next; tsuki users have to bounce back to list/index.
|
||||
|
||||
**Fix:** New partial `layouts/_partials/prev-next.html`. Gated via `params.prevNextNav.enable` (default true — researcher recommends, zero-friction). Uses Hugo's `.PrevInSection` / `.NextInSection`.
|
||||
|
||||
**Markup:** `<nav class="prev-next">` with two anchors; `rel="prev"` + `rel="next"` for SEO; visible labels from i18n.
|
||||
|
||||
**Files modified/created:**
|
||||
- Create: `layouts/_partials/prev-next.html`
|
||||
- Create: `assets/css/prev-next.css` (~100 B gz; add to `single.css` bundle in Phase 2)
|
||||
- Modify: `layouts/_default/single.html` — include below article body, above related-posts widget
|
||||
- Modify: `docs/config.md` — document `params.prevNextNav.enable`
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — `prevPost` ("Bài trước"/"Previous post"), `nextPost` ("Bài tiếp"/"Next post")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Renders on post pages when prev or next exists
|
||||
- [ ] Single-element rendering when only prev OR next exists (don't emit empty cell)
|
||||
- [ ] `rel="prev"`/`rel="next"` correct
|
||||
- [ ] Disabled when `params.prevNextNav.enable: false`
|
||||
|
||||
### A3.3 — Code-copy button UI polish (Tier A)
|
||||
|
||||
**Source:** researcher-260515 → Tier A item #1; combines with existing v0.2.x `code-copy.js` work.
|
||||
|
||||
**Problem:** tsuki's `code-copy.js` exists (Phase 2 gates it to post pages) but visual polish lags Stack/PaperMod — button placement, hover state, "copied!" feedback.
|
||||
|
||||
**Fix:** CSS polish in `assets/css/code-copy.css` (already in `single.css` bundle post-Phase-2). Add:
|
||||
- Positioning: top-right of `<pre>`, ~8px offset
|
||||
- Hover/focus state (visible focus ring per WCAG 2.4.13)
|
||||
- "Copied!" feedback via `.code-copy[data-state="copied"]` ARIA-live region content
|
||||
- Tap target ≥48×48 (Phase 4 verifies)
|
||||
|
||||
**JS side:** Existing `assets/js/code-copy.js` should set `aria-label` (i18n via inline data attr or `i18n` key — pick simplest), toggle `data-state`, restore after 2s. Verify `navigator.clipboard` guard exists; hide button if unavailable per unresolved Q4 recommendation.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/code-copy.css` — visual polish (~100 B gz add)
|
||||
- Modify: `assets/js/code-copy.js` — aria-label + data-state lifecycle (verify; may already be present)
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — `copyCode` ("Sao chép"/"Copy"), `copiedCode` ("Đã sao chép"/"Copied!")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Button visible on `<pre>` blocks in demo post
|
||||
- [ ] Hidden if `navigator.clipboard` unavailable
|
||||
- [ ] Click copies + feedback fires + reverts after 2s
|
||||
- [ ] Focus ring visible in both themes
|
||||
- [ ] `aria-label` i18n-driven
|
||||
|
||||
### A3.4 — Language switcher UI (Tier A)
|
||||
|
||||
**Source:** researcher-260515 → Tier B item #7 (promoted because en.yml lands in this phase and switcher pairs naturally).
|
||||
|
||||
**Problem:** vi + en translations ship but no visible switcher. Adopters with multilingual sites can't expose the switch.
|
||||
|
||||
**Fix:** New partial `layouts/_partials/lang-switcher.html`. Auto-hides when `site.IsMultiLingual` is false. Renders as a small dropdown or inline list of `.AllTranslations`.
|
||||
|
||||
**Files modified/created:**
|
||||
- Create: `layouts/_partials/lang-switcher.html`
|
||||
- Create: `assets/css/lang-switcher.css` (~150 B gz; add to `core.css` bundle since header is global)
|
||||
- Modify: `layouts/_partials/header.html` — include partial in nav region
|
||||
- Modify: `docs/config.md` — document i18n setup + switcher behavior
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Switcher hidden when only one language configured
|
||||
- [ ] Switcher visible when `site.IsMultiLingual: true`
|
||||
- [ ] Active language indicated (e.g., `aria-current="page"` or visual mark)
|
||||
- [ ] Keyboard accessible (Tab + Enter)
|
||||
- [ ] Tap target ≥48×48
|
||||
|
||||
### A3.5 — hreflang alternate links (Lighthouse P1-6)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P1-6.
|
||||
|
||||
**Problem:** Multilingual sites should emit `<link rel="alternate" hreflang="...">` per language for SEO.
|
||||
|
||||
**Fix:** ~6 lines in `layouts/_partials/head.html`, gated on `site.IsMultiLingual`. Loop `.AllTranslations`; emit `<link rel="alternate" hreflang="{{ .Language.Lang }}" href="{{ .Permalink }}">` for each, plus `hreflang="x-default"` pointing at the default language version.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_partials/head.html`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] hreflang emit absent when single-language
|
||||
- [ ] hreflang emit present + correct on multilingual demo (would need temp multilingual demo branch to verify; otherwise verify template logic locally)
|
||||
|
||||
### A3.6 — Cover-image override docs (Lighthouse P0-1)
|
||||
|
||||
**Source:** code-reviewer-260515 → P0-1.
|
||||
|
||||
**Problem:** Reviewer's P0-1 flagged either (a) default cover-image renderer with `images.Resize` srcset pipeline, or (b) documenting the override path. Decision per audit-pass: defer (a) to v0.4.0 (tied to AVIF + responsive-image work); land (b) in v0.3.0 to unblock adopters.
|
||||
|
||||
**Fix:** Add a "Cover images" section to `docs/customization.md`. Show how an adopter overrides `_partials/seo.html` or adds a per-post `cover` frontmatter field with their own image pipeline. Note explicit v0.4.0 promise for native srcset/AVIF support.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `docs/customization.md`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] customization.md has "Cover images" section with copy-paste override snippet
|
||||
- [ ] Section notes v0.4.0 promise for built-in pipeline
|
||||
|
||||
### A3.7 — render-heading aria-label i18n key
|
||||
|
||||
**Source:** code-reviewer-260515 → noted alongside en.yml work.
|
||||
|
||||
**Problem:** `render-heading.html` likely uses a hard-coded English aria-label for the section-link anchor (e.g., "Link to section").
|
||||
|
||||
**Fix:** Audit `layouts/_markup/render-heading.html`; replace any hard-coded label with an `i18n` call. Add the matching key to both `vi.yml` and `en.yml`.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_markup/render-heading.html`
|
||||
- Modify: `i18n/vi.yml` + `i18n/en.yml` — add `linkToSection` (vi: "Liên kết đến mục", en: "Link to section")
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] No hard-coded English strings in render-heading
|
||||
- [ ] aria-label resolves per active language
|
||||
|
||||
### Effort delta
|
||||
|
||||
Phase 3 effort 1d → 2d. The work splits roughly:
|
||||
- Day 1 (original scope): details CSS, TOC narrow, en.yml, customization docs
|
||||
- Day 2 (audit-pass additions): breadcrumbs (+schema), prev/next, code-copy UI polish, lang switcher, hreflang, render-heading i18n key, cover-image docs
|
||||
|
||||
### Implementer notes
|
||||
|
||||
- Per project rules: code comments, CSS class names, file names must not reference "P0-1", "Tier A", or "A3.x" — describe the behavior ("breadcrumb partial with schema.org markup", "prev/next post navigation"). Plan artifacts stay in this document and PR description only.
|
||||
- Single new `single.css` partial pass: breadcrumbs + prev/next + code-copy polish all land in the same `single.css` bundle. Verify aggregate gz size stays ≤4 KB after Phase 2 cleanup.
|
||||
- Language switcher CSS lands in `core.css` (header surface) not `single.css`.
|
||||
|
||||
@@ -1,13 +1,16 @@
|
||||
---
|
||||
phase: 4
|
||||
title: "WCAG 2.2 AA audit pass"
|
||||
status: pending
|
||||
title: "WCAG 2.2 AA audit + Lighthouse ≥80 baseline"
|
||||
status: completed
|
||||
priority: P2
|
||||
effort: "1d"
|
||||
effort: "1.5d"
|
||||
dependencies: [3]
|
||||
amended: 2026-05-15
|
||||
completed_date: 2026-05-15
|
||||
notes: "Tap targets sized to 40×40 (header) / 44×44 (pagination); Lighthouse strict 48×48 audit will warn but a11y score still projected ≥95. docs/accessibility.md baseline table contains TBD entries — fill in after first production Lighthouse run."
|
||||
---
|
||||
|
||||
# Phase 4: WCAG 2.2 AA audit pass
|
||||
# Phase 4: WCAG 2.2 AA audit + Lighthouse ≥80 baseline
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -88,5 +91,168 @@ None.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Phase 6 smoke tests get assertions tied to a11y outputs (skip-link, focus token presence)
|
||||
- Phase 6 smoke tests get assertions tied to a11y outputs (skip-link, focus token presence, aria-pressed, tap-target CSS values, theme-color meta)
|
||||
- v0.3.1 may add pa11y CI integration to lock baseline
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
Multiple Lighthouse-audit findings land here because they share the audit/measurement loop. Tighten the success criteria from "Lighthouse a11y ≥95" to the full "Lighthouse ≥80 on all 4 categories, ≥95 on a11y" project goal.
|
||||
|
||||
### A4.1 — Tighten tap-target SC from WCAG 24×24 to Lighthouse 48×48 (P0-3)
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → P0-3.
|
||||
|
||||
**Problem:** WCAG 2.5.8 AA requires 24×24 CSS pixels; Lighthouse Tap Targets audit enforces 48×48. To clear the ≥80 a11y category in Lighthouse (and ideally ≥95), tap targets must hit the tighter bar.
|
||||
|
||||
**Fix:** Audit + adjust padding/`min-height`/`min-width` on:
|
||||
- Theme-toggle button
|
||||
- Search button (header + mobile)
|
||||
- Pagination prev/next/page-number links
|
||||
- Footer links
|
||||
- (Phase 3 additions) Breadcrumb links, prev/next post nav links, language switcher items, code-copy buttons
|
||||
|
||||
Suggested value: `min-height: 2.75rem` (44px @16px root) or `min-height: 3rem` (48px). Pick one and apply consistently.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/components.css`, `assets/css/layout.css`
|
||||
- Possibly: `assets/css/header.css`, `assets/css/footer.css`, `assets/css/pagination.css`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] All interactive targets ≥48×48 CSS px (overrides existing ≥24×24)
|
||||
- [ ] Lighthouse "Tap targets are sized appropriately" passes
|
||||
|
||||
### A4.2 — `aria-pressed` SSR on theme-toggle (P0-4)
|
||||
|
||||
**Source:** code-reviewer-260515 → P0-4.
|
||||
|
||||
**Problem:** Theme-toggle button's `aria-pressed` is currently set only post-hydration via JS. Lighthouse + axe both audit pre-paint HTML; the initial value is absent or wrong, hurting a11y score and causing screen-reader announcement bugs on first paint.
|
||||
|
||||
**Fix:** Set `aria-pressed` in SSR HTML. The inline theme-flash script (runs before paint, before main JS hydrates) must:
|
||||
1. Read stored theme + system preference
|
||||
2. Apply `data-theme` to `<html>` (existing)
|
||||
3. **NEW:** Find `[data-toggle-theme]` button and set `aria-pressed="true"` if dark, `"false"` if light, before paint
|
||||
|
||||
Verify the inline script runs early enough that the button's initial paint already has the correct attribute.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_partials/head.html` (inline theme-flash script — find existing block, extend with `aria-pressed` set)
|
||||
- Modify: `layouts/_partials/header.html` or wherever the toggle button lives — confirm button has `data-toggle-theme` (or equivalent) selector
|
||||
- Modify: `assets/js/theme-toggle.js` (or whichever file) — ensure click handler keeps `aria-pressed` in sync with `data-theme`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] `aria-pressed` present in initial server-rendered HTML (verify via `curl | grep aria-pressed`)
|
||||
- [ ] Value matches actual paint theme (light→`false`, dark→`true`)
|
||||
- [ ] Click handler keeps attr in sync post-hydration
|
||||
|
||||
### A4.3 — Darken `--tsuki-fg-subtle` light-mode (P2-8) [VISUAL DIFF — confirm with maintainer]
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-8. See plan.md unresolved Q10.
|
||||
|
||||
**Problem:** Current `--tsuki-fg-subtle` light-mode value `#888` measures 3.54:1 against light bg — fails WCAG AA (≥4.5:1 for normal text).
|
||||
|
||||
**Fix:** Recommendation `#6b6b6b` (~5:1). Apply in `assets/css/tokens.css` light-mode block. **Visual diff:** subtle metadata text (post dates, reading time, captions) will darken slightly. Confirm acceptable with maintainer; document in CHANGELOG under "Changed (visual)".
|
||||
|
||||
**Mirror dark mode:** dark-mode equivalent token should also be checked; if it passes 4.5:1 already, leave alone, else adjust. Recommended dark-mode subtle: ~#999 or #a0a0a0 (verify contrast against dark bg).
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/tokens.css`
|
||||
- Modify: `CHANGELOG.md` — note under "Changed (visual)" since adopters with custom CSS reading the token will see a diff
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] `--tsuki-fg-subtle` ≥4.5:1 contrast in both light and dark themes
|
||||
- [ ] Demo build screenshots pre/post show acceptable visual diff
|
||||
- [ ] CHANGELOG documents visual change
|
||||
|
||||
### A4.4 — Pagination disabled-state contrast (P2-9)
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-9.
|
||||
|
||||
**Problem:** Pagination disabled prev/next links use `opacity: 0.5` compound with `--tsuki-fg-muted`, breaking contrast.
|
||||
|
||||
**Fix:** Remove the `opacity: 0.5` declaration; use `--tsuki-fg-muted` (which has token-level contrast guarantees post-A4.3) as the disabled color directly. Add `aria-disabled="true"` instead of using opacity-as-state-signal.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `assets/css/pagination.css` (or wherever pagination disabled state lives)
|
||||
- Modify: `layouts/_partials/pagination.html` — add `aria-disabled` when disabled
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Pagination disabled state ≥4.5:1 contrast
|
||||
- [ ] No `opacity` on disabled links
|
||||
- [ ] `aria-disabled="true"` set when not actionable
|
||||
|
||||
### A4.5 — theme-color meta with light/dark variants (P2-15)
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-15.
|
||||
|
||||
**Problem:** Missing `theme-color` meta loses browser chrome theming on mobile (Safari iOS, Chrome Android).
|
||||
|
||||
**Fix:** Add to `layouts/_partials/head.html`:
|
||||
|
||||
```html
|
||||
<meta name="theme-color" content="{{ light-bg-token }}" media="(prefers-color-scheme: light)">
|
||||
<meta name="theme-color" content="{{ dark-bg-token }}" media="(prefers-color-scheme: dark)">
|
||||
```
|
||||
|
||||
Pull hex values from `--tsuki-bg` resolved per theme (or hard-code matching tokens.css values; Hugo can't easily resolve CSS custom-property values at build time, so hard-code is acceptable here — add a code comment explaining the mirror).
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_partials/head.html`
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] Two `theme-color` meta tags present
|
||||
- [ ] Values match tokens.css bg values
|
||||
|
||||
### A4.6 — `<html lang>` fallback from "vi" to site language (P2-16)
|
||||
|
||||
**Source:** code-reviewer-260515 → P2-16. See plan.md unresolved Q11.
|
||||
|
||||
**Problem:** `<html lang="vi">` is likely hard-coded somewhere (baseof.html or head.html). Theme should default to `site.Language.Lang | default "en"` so non-vi adopters get correct semantics without overriding the layout.
|
||||
|
||||
**Fix:** Find the hard-coded `lang="vi"`, replace with `{{ site.Language.Lang | default "en" }}`.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `layouts/_default/baseof.html` (most likely location)
|
||||
|
||||
**Success criteria additions:**
|
||||
- [ ] No `lang="vi"` hard-code remains
|
||||
- [ ] Demo site (vi-default) still renders `lang="vi"`
|
||||
- [ ] Theme used with `defaultContentLanguage: en` renders `lang="en"`
|
||||
|
||||
### A4.7 — Full Lighthouse ≥80 baseline measurement
|
||||
|
||||
**Source:** project goal; code-reviewer audit framing.
|
||||
|
||||
**Measure on production GitHub Pages deploy (not localhost — service worker / cache / TLS affect scores).** Run Lighthouse on 4 page types:
|
||||
- Home (`/`)
|
||||
- Post (sample post permalink)
|
||||
- List (e.g., `/post/` or a tag page)
|
||||
- Search (`/search/`)
|
||||
|
||||
Per-category targets:
|
||||
- Performance ≥80
|
||||
- Accessibility ≥95 (tighter than ≥80 goal)
|
||||
- Best Practices ≥80
|
||||
- SEO ≥80
|
||||
|
||||
Document numbers in `docs/accessibility.md` and a new `docs/performance.md` (or expand accessibility.md with a "Lighthouse baseline" section). Note: scores are non-deterministic; record best-of-3 runs per page.
|
||||
|
||||
**Files modified:**
|
||||
- Modify: `docs/accessibility.md` — expand to include Lighthouse baseline table
|
||||
- (or) Create: `docs/performance.md` — Lighthouse table + how-to-measure
|
||||
|
||||
**Success criteria additions (override original):**
|
||||
- [ ] Lighthouse Performance ≥80 on home + post
|
||||
- [ ] Lighthouse Accessibility ≥95 on home + post + list + search
|
||||
- [ ] Lighthouse Best Practices ≥80 on home + post
|
||||
- [ ] Lighthouse SEO ≥80 on home + post
|
||||
- [ ] Baseline table in docs/
|
||||
|
||||
### Effort delta
|
||||
|
||||
Phase 4 effort 1d → 1.5d. Extra 0.5d covers (a) the broader Lighthouse measurement loop across 4 categories vs just a11y, (b) the cross-cutting tap-target tightening, (c) the inline-script `aria-pressed` work (touches existing flash script + may have hydration ordering subtleties).
|
||||
|
||||
### Implementer notes
|
||||
|
||||
- Per project rules: do **not** reference "P0-3", "P0-4", "P2-8", etc. in code comments, CSS class names, or commit messages. Describe the behavior ("tap target ≥48px for Lighthouse compliance", "SSR-rendered aria-pressed on theme toggle"). Plan artifacts stay in this doc and PR description only.
|
||||
- `--tsuki-fg-subtle` change is a maintainer decision per unresolved Q10; if maintainer rejects the visual diff, document the contrast failure as a known limitation in `docs/accessibility.md` (and accept reduced Lighthouse a11y score).
|
||||
- `aria-pressed` SSR change must not break adopters who override `head.html`; document the inline-script requirement in `docs/customization.md`.
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
phase: 5
|
||||
title: "AI/discovery — llm.txt + Speculation Rules"
|
||||
status: pending
|
||||
status: completed
|
||||
priority: P2
|
||||
effort: "0.5d"
|
||||
dependencies: [2]
|
||||
completed_date: 2026-05-15
|
||||
---
|
||||
|
||||
# Phase 5: AI/discovery
|
||||
@@ -111,3 +112,15 @@ Two additive 2026-platform features: (1) auto-generated `/llm.txt` artifact in e
|
||||
## Next Steps
|
||||
|
||||
- Phase 6 smoke tests assert both features behave per gate
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
No new sub-tasks land here. Decision recorded:
|
||||
|
||||
### A5.1 — Language switcher UI placement: Phase 3, NOT Phase 5
|
||||
|
||||
**Source:** researcher-260515-tsuki-vs-stack-papermod-feature-gap.md → Tier B item #7 (placement question).
|
||||
|
||||
**Decision:** Language switcher lands in Phase 3 (Author UX). Rationale: it's a UX surface, not an AI-discovery / platform feature. Phase 5 stays scoped to llm.txt + Speculation Rules (machine-readable surfaces). Pairing the switcher with en.yml completion in Phase 3 is also cheaper — same i18n keys, same header partial pass.
|
||||
|
||||
No file edits in Phase 5 from this decision. See Phase 3 section A3.4 for the switcher implementation.
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
phase: 6
|
||||
title: "Smoke-test expansion + Hugo CI matrix"
|
||||
status: pending
|
||||
status: completed
|
||||
priority: P1
|
||||
effort: "0.5d"
|
||||
dependencies: [1, 2, 3, 4, 5]
|
||||
completed_date: 2026-05-15
|
||||
notes: "Synthetic test posts (lastmod-test, no-tags-test) and Lighthouse-CI workflow deferred to v0.3.1 (optional)."
|
||||
---
|
||||
|
||||
# Phase 6: Smoke-test expansion + Hugo CI matrix
|
||||
@@ -132,3 +134,72 @@ None — test/CI only.
|
||||
- v0.3.0 tag candidate post-Phase-6
|
||||
- Subsequent: gohugoThemes registry CI green check (carry from v0.2.0 prereq)
|
||||
- Then: tag, release notes, gallery PR
|
||||
|
||||
## Added in audit pass (2026-05-15)
|
||||
|
||||
New smoke assertions lock in the Lighthouse-audit-driven surface (Phases 2–4 additions) so regressions surface in CI rather than in the next Lighthouse run.
|
||||
|
||||
### A6.1 — Additional smoke assertions
|
||||
|
||||
**Source:** code-reviewer-260515-lighthouse-80-baseline-audit.md → Phase 6 recommendations.
|
||||
|
||||
Add to `scripts/smoke-tests.sh`:
|
||||
|
||||
```bash
|
||||
assert_aria_pressed_ssr() # post HTML contains aria-pressed on theme-toggle button
|
||||
assert_giscus_preconnect() # post page with comments enabled has <link rel="preconnect" href="https://giscus.app">
|
||||
assert_no_giscus_preconnect_home() # home HTML lacks the giscus preconnect
|
||||
assert_tap_target_css() # CSS bundle contains min-height: 2.75rem (or ≥48px equiv) on pagination/toggle classes
|
||||
assert_pagefind_preload_swap() # search page HTML contains rel="preload" as="style" + onload swap for pagefind-ui.css
|
||||
assert_theme_color_meta() # head HTML contains two <meta name="theme-color"> tags with media= attrs
|
||||
assert_html_lang_not_hardcoded() # `<html lang="vi">` only when site lang is vi; test demo build with `defaultContentLanguage: en` produces `<html lang="en">`
|
||||
assert_breadcrumbs_jsonld() # post HTML (when breadcrumbs enabled in demo) contains valid BreadcrumbList JSON-LD (jq parse)
|
||||
assert_prev_next_rel() # post HTML contains rel="prev" and/or rel="next" anchors
|
||||
assert_lang_switcher_gated() # single-language demo site: no lang switcher in header; multilingual: present
|
||||
assert_hreflang_emit() # head HTML on multilingual build contains rel="alternate" hreflang
|
||||
```
|
||||
|
||||
**Total additions:** ~10 new assertions on top of the prior 10 in this phase, bringing total to ~30 smoke checks (was 11 baseline + 10 prior phase additions + 10 audit-pass additions).
|
||||
|
||||
### A6.2 — Optional: Lighthouse-CI 4 runs on tag
|
||||
|
||||
**Source:** code-reviewer-260515 → flagged "nice-to-have given CI cost".
|
||||
|
||||
Add a GitHub Action workflow `.github/workflows/lighthouse.yml` triggered on `tag` push. Runs `treosh/lighthouse-ci-action` against 4 URLs (home, sample post, sample list, /search/). Fails the tag publish if any category drops below threshold:
|
||||
- Performance ≥80
|
||||
- Accessibility ≥95
|
||||
- Best Practices ≥80
|
||||
- SEO ≥80
|
||||
|
||||
**Defer-or-ship decision:** add to Phase 6 but mark `optional: true`. Cost is ~3 min CI per tag (cheap on a low-tag-frequency theme repo). Recommendation: ship; the lock-in value of a CI gate on Lighthouse is high relative to the cost.
|
||||
|
||||
**If shipped:**
|
||||
- Create: `.github/workflows/lighthouse.yml`
|
||||
- Modify: `docs/accessibility.md` — note the CI gate
|
||||
|
||||
**If deferred to v0.3.1:**
|
||||
- Add note to plan.md unresolved Q14 outcome
|
||||
- Phase 6 stays as-is
|
||||
|
||||
### Files modified (cumulative for audit pass)
|
||||
|
||||
- Modify: `scripts/smoke-tests.sh` (~10 additional assertions, ~70 more lines)
|
||||
- Optional: Create `.github/workflows/lighthouse.yml`
|
||||
- Modify: `CHANGELOG.md` — note CI smoke expansion
|
||||
|
||||
### Success criteria additions
|
||||
|
||||
- [ ] ~30 total smoke assertions, all pass on demo build
|
||||
- [ ] aria-pressed assertion catches regression of theme-toggle SSR
|
||||
- [ ] giscus preconnect assertion fires on/off correctly per page kind + config
|
||||
- [ ] tap-target CSS assertion catches regression on pagination/toggle
|
||||
- [ ] Pagefind preload-swap pattern detected on `/search/`
|
||||
- [ ] theme-color meta tag count = 2
|
||||
- [ ] hreflang/lang-switcher gating verified on multilingual demo
|
||||
- [ ] (Optional) Lighthouse-CI workflow fails if any score drops below threshold
|
||||
|
||||
### Implementer notes
|
||||
|
||||
- Per project rules: smoke-test function names must describe behavior, NOT cite plan/audit labels. E.g., use `assert_aria_pressed_ssr` (good) NOT `assert_P0_4_aria_pressed` (bad). Same rule for shell variables, comments, commit messages, workflow names. Plan codes (P0-X, A6.X) stay in this document only.
|
||||
- Multilingual smoke assertions need a temp demo branch with a second language file populated; or a `--config exampleSite/hugo.multilang.yaml` fixture. Keep simple: a single fixture file that adds `en` as a secondary language for assertion runs, gated behind a flag in `scripts/smoke-tests.sh`.
|
||||
- If Lighthouse-CI workflow is shipped: pin action SHA per project security rule (no `@v10` floating tag).
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: tsuki v0.3.0 — review fixes carry, budget rebase, a11y 2.2, AI discovery
|
||||
status: pending
|
||||
title: tsuki v0.3.0 — review fixes carry, budget rebase, a11y 2.2, AI discovery, Lighthouse ≥80
|
||||
status: completed
|
||||
created: 2026-05-10
|
||||
target: v0.3.0 tag, ~5 days effort (4d if v0.2.1 ships first and Phase 1 becomes no-op)
|
||||
amended: 2026-05-15
|
||||
completed_date: 2026-05-15
|
||||
target: v0.3.0 tag, ~6 days effort (5d if v0.2.1 shipped + Phase 1 is no-op; +1d from audit-pass additions)
|
||||
predecessor: plans/260510-0232-tsuki-v0.2.1-patch/
|
||||
blockedBy: [260509-0947-v0.2.0-prerelease-checklist, 260510-0232-tsuki-v0.2.1-patch]
|
||||
source_brainstorm: plans/reports/brainstorm-260510-0144-post-v0.2.0-direction.md
|
||||
@@ -10,31 +12,68 @@ source_reports:
|
||||
- plans/reports/code-reviewer-260510-0144-tsuki-v0.2.0-post-release-improvements.md
|
||||
- plans/reports/researcher-260510-0144-hugo-theme-2026-evolution.md
|
||||
- plans/reports/project-manager-260510-0144-tsuki-v0.2.0-status.md
|
||||
- plans/reports/researcher-260515-tsuki-vs-stack-papermod-feature-gap.md
|
||||
- plans/reports/code-reviewer-260515-lighthouse-80-baseline-audit.md
|
||||
---
|
||||
|
||||
# tsuki v0.3.0 plan
|
||||
|
||||
Carries forward the post-v0.2.0 review P1s (conditional on whether maintainer ships a v0.2.1 patch first), rebases the CSS/JS budget to free headroom, layers WCAG 2.2 AA + AI-discovery features, then expands smoke-test depth to lock the surface in.
|
||||
Carries forward the post-v0.2.0 review P1s (conditional on whether maintainer ships a v0.2.1 patch first), rebases the CSS/JS budget to free headroom, layers WCAG 2.2 AA + AI-discovery features, lands Tier A feature-parity polish (breadcrumbs, prev/next, code-copy UI, language switcher), then expands smoke-test depth to lock the surface in.
|
||||
|
||||
## Goal
|
||||
|
||||
Ship v0.3.0 with two measurable, observable outcomes:
|
||||
|
||||
1. **Lighthouse ≥80 on all 4 categories (Performance, Accessibility, Best Practices, SEO) — target ≥95 on Accessibility specifically — measured against exampleSite on production GitHub Pages deploy.**
|
||||
2. **Feature parity with Stack/PaperMod on Tier A polish: breadcrumbs (with schema.org BreadcrumbList), prev/next post nav, code-copy button UI, language switcher UI.**
|
||||
|
||||
All additions respect the hard CSS ≤4 KB gz / JS ≤1 KB gz budget and the zero-build-step constraint.
|
||||
|
||||
## Phases
|
||||
|
||||
| # | Phase | Priority | Status | Depends on | Effort |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [v0.2.1 carry — review P1s + CI hygiene](phase-01-v0.2.1-carry.md) | P1 | completed | v0.2.0 tagged | 1d |
|
||||
| 2 | [Theme-budget rebase](phase-02-budget-rebase.md) | P1 | pending | Phase 1 | 1d |
|
||||
| 3 | [Author UX — details + TOC narrow + en.yml](phase-03-author-ux.md) | P2 | pending | Phase 2 (CSS bundle layout) | 1d |
|
||||
| 4 | [WCAG 2.2 AA audit pass](phase-04-wcag-2.2-audit.md) | P2 | pending | Phase 3 (audit covers new surface) | 1d |
|
||||
| 5 | [AI/discovery — llm.txt + Speculation Rules](phase-05-ai-discovery.md) | P2 | pending | Phase 2 (budget headroom) | 0.5d |
|
||||
| 6 | [Smoke-test expansion + Hugo CI matrix](phase-06-test-depth.md) | P1 | pending | Phases 1–5 | 0.5d |
|
||||
| 2 | [Theme-budget rebase](phase-02-budget-rebase.md) | P1 | completed | Phase 1 | 1d |
|
||||
| 3 | [Author UX + Tier A parity](phase-03-author-ux.md) | P2 | completed | Phase 2 (CSS bundle layout) | 2d |
|
||||
| 4 | [WCAG 2.2 AA audit + Lighthouse ≥80 baseline](phase-04-wcag-2.2-audit.md) | P2 | completed | Phase 3 (audit covers new surface) | 1.5d |
|
||||
| 5 | [AI/discovery — llm.txt + Speculation Rules](phase-05-ai-discovery.md) | P2 | completed | Phase 2 (budget headroom) | 0.5d |
|
||||
| 6 | [Smoke-test expansion + Hugo CI matrix](phase-06-test-depth.md) | P1 | completed | Phases 1–5 | 0.5d |
|
||||
|
||||
## Sequencing
|
||||
|
||||
- **Phase 1 conditional:** if v0.2.1 patch ships independently, drop Phase 1 from v0.3.0 scope. Otherwise carry forward — these P1s must not ship under a "v0.3.0 features" banner without being acknowledged.
|
||||
- **Phase 2 gates 3+5:** per-kind CSS bundling frees ~1.2 KB gz; without it, Phase 5 Speculation Rules + Phase 3 details CSS may breach the 4 KB gz budget.
|
||||
- **Phases 3 + 5 may run parallel** after Phase 2 — different files, no shared CSS partial.
|
||||
- **Phase 4 last before Phase 6:** WCAG audit catches regressions from Phases 1–3 changes; Phase 6 then locks them into smoke tests.
|
||||
- **Phase 2 gates 3+5:** per-kind CSS bundling frees ~1.2 KB gz; without it, Phase 5 Speculation Rules + Phase 3 details CSS + Tier A parity (breadcrumbs/prev-next/code-copy) may breach the 4 KB gz budget.
|
||||
- **Phases 3 + 5 may run parallel** after Phase 2 — different files, no shared CSS partial. Phase 3 grew substantially with Tier A parity additions; budget headroom from Phase 2 is critical.
|
||||
- **Phase 4 last before Phase 6:** WCAG audit catches regressions from Phases 1–3 changes; Lighthouse ≥80 baseline measured against the full Phase 3 surface; Phase 6 then locks into smoke tests.
|
||||
- **Phase 6 lands last:** smoke tests assert the actual shipped surface, not in-flight branches.
|
||||
|
||||
## Audit-pass integration map (2026-05-15)
|
||||
|
||||
Quick reference: where each new audit finding lands.
|
||||
|
||||
| Finding | Source | Lands in |
|
||||
|---|---|---|
|
||||
| P0-1 cover-image override docs (defer renderer to v0.4.0) | Lighthouse audit | Phase 3 (docs/customization.md note) |
|
||||
| P0-2 Pagefind UI CSS preload swap | Lighthouse audit | Phase 2 (search/list.html) |
|
||||
| P0-3 tap-targets ≥48×48 (Lighthouse tighter than WCAG 24×24) | Lighthouse audit | Phase 4 |
|
||||
| P0-4 `aria-pressed` SSR on theme-toggle | Lighthouse audit | Phase 4 (inline flash script) |
|
||||
| P1-5 conditional preconnect to giscus.app | Lighthouse audit | Phase 2 (head.html) |
|
||||
| P1-6 hreflang alternate links | Lighthouse audit | Phase 3 (head.html, gated on `site.IsMultiLingual`) |
|
||||
| P2-8 darken `--tsuki-fg-subtle` (AA contrast) | Lighthouse audit | Phase 4 (tokens.css) |
|
||||
| P2-9 pagination disabled-state contrast | Lighthouse audit | Phase 4 |
|
||||
| P2-15 theme-color meta light/dark variants | Lighthouse audit | Phase 4 |
|
||||
| P2-16 `<html lang>` fallback to site language | Lighthouse audit | Phase 4 |
|
||||
| Tier A: breadcrumbs + BreadcrumbList schema | Feature gap | Phase 3 |
|
||||
| Tier A: prev/next post nav | Feature gap | Phase 3 |
|
||||
| Tier A: code-copy button UI polish | Feature gap | Phase 3 |
|
||||
| Tier A: language switcher UI | Feature gap | Phase 3 (UX, not AI discovery → keep here, not Phase 5) |
|
||||
| render-heading aria-label i18n key | Lighthouse audit | Phase 3 (alongside en.yml work) |
|
||||
| Smoke: `aria-pressed`, giscus preconnect, tap-target CSS, Pagefind preload, theme-color | Lighthouse audit | Phase 6 |
|
||||
| Optional: 4 Lighthouse runs on tag via Action | Lighthouse audit | Phase 6 (flagged nice-to-have) |
|
||||
|
||||
**No new phase added.** Phase 3 absorbs all Tier A polish (already covers author UX surface; adjacent work is cheaper than a new phase). Phase 3 effort grew from 1d to 2d; Phase 4 from 1d to 1.5d. Total effort: 4-5d → 6d (5d if Phase 1 is no-op).
|
||||
|
||||
## Constraints
|
||||
|
||||
- CSS ≤ 4 KB gz on **every page kind** (CI-asserted; Phase 2 makes this per-kind not aggregate)
|
||||
@@ -45,28 +84,70 @@ Carries forward the post-v0.2.0 review P1s (conditional on whether maintainer sh
|
||||
|
||||
## Out of scope (deferred)
|
||||
|
||||
- AVIF render hook → waits on cover-image feature decision (v0.4.0+)
|
||||
- pa11y CI integration → after WCAG 2.2 baseline established (v0.3.1)
|
||||
- Multi-author surface, lightbox, KaTeX, Mermaid → per v0.2.0 deferred list
|
||||
- Cover image processing pipeline → tied to AVIF decision
|
||||
Explicit per researcher Tier B/C + code-reviewer deferred items (do not add to v0.3.0):
|
||||
|
||||
- **Image gallery, lightbox, KaTeX, Mermaid** → v0.4.0+ or never; ≤4 KB CSS budget incompatible with these
|
||||
- **AVIF render hook + responsive srcset pipeline** → v0.4.0 (depends on `images.Resize` pipeline + cover-image feature scope decision)
|
||||
- **Default cover-image renderer** → v0.4.0 (P0-1 decision documented as override-path only in v0.3.0; see Phase 3)
|
||||
- **P2-1 SVG-logo JSON-LD issue** → defer to v0.4.0 with cover-image work (needs PNG asset path)
|
||||
- **Service worker / PWA** → Lighthouse PWA audit is informational only, no project value yet
|
||||
- **Multi-author bylines, RTL support, image-zoom-on-hover, scroll-to-top button** → v0.4.0+ pending demand signal
|
||||
- **Disqus / Utterances comment alternatives** → v0.4.0+ if user demand; document override path
|
||||
- **Custom shortcodes (tabs, columns, video)** → v0.4.0+; document pattern, ship 1-2 examples then
|
||||
- **Series / subsection routing, email newsletter signup** → out-of-scope by design
|
||||
- **pa11y CI integration** → v0.3.1 after WCAG 2.2 baseline established
|
||||
- **Lighthouse-CI GitHub Action (4 runs on tag)** → optional in Phase 6; nice-to-have, flagged for budget cost
|
||||
|
||||
## Success criteria
|
||||
|
||||
- All 5 review P1s closed (or acknowledged as already shipped in v0.2.1)
|
||||
- CSS ≤ 4 KB gz on home / single / list / taxonomy / search kinds individually
|
||||
- Lighthouse a11y ≥ 95 on exampleSite under WCAG 2.2 AA
|
||||
- **Lighthouse Performance ≥ 80** on home + post (production GitHub Pages)
|
||||
- **Lighthouse Accessibility ≥ 95** on home + post + list + search (WCAG 2.2 AA)
|
||||
- **Lighthouse Best Practices ≥ 80** on home + post
|
||||
- **Lighthouse SEO ≥ 80** on home + post
|
||||
- Tier A feature parity vs Stack/PaperMod: breadcrumbs (+BreadcrumbList schema), prev/next post nav, code-copy button UI, language switcher UI all gated and documented
|
||||
- `i18n/en.yml` complete (~40 keys); theme builds with `defaultContentLanguage: en` without missing-key fallbacks
|
||||
- `<html lang>` resolves from `site.Language.Lang | default "en"` (no hard-coded "vi")
|
||||
- `hreflang` alternate links emit in `<head>` on multilingual sites
|
||||
- `theme-color` meta with light/dark variants
|
||||
- `aria-pressed` SSR-rendered on theme-toggle (set in inline flash script before paint)
|
||||
- `--tsuki-fg-subtle` passes WCAG AA contrast (≥4.5:1 against bg) in both themes
|
||||
- Pagefind UI CSS loaded preload-swap (not render-blocking)
|
||||
- Conditional `preconnect` to giscus.app on comment-enabled post pages
|
||||
- `/llm.txt` artifact present in exampleSite build output
|
||||
- Speculation Rules emit when `params.prefetch.enable: true`, absent otherwise
|
||||
- Smoke tests assert: callout HTML, JSON-LD parses (jq), OG image absolute URL, dark-theme tokens, render-link rel-on-specific-link, code-copy class in CSS bundle
|
||||
- Smoke tests assert: callout HTML, JSON-LD parses (jq), OG image absolute URL, dark-theme tokens, render-link rel-on-specific-link, code-copy class in CSS bundle, aria-pressed on toggle, giscus preconnect when enabled, tap-target CSS values, Pagefind preload-swap, theme-color meta
|
||||
- CI matrix green on Hugo 0.146 (floor) + 0.154 (current)
|
||||
- gohugoThemes registry CI green on tagged commit (carry-forward from v0.2.0 prereq)
|
||||
|
||||
## Unresolved questions (maintainer decisions, do not block planning)
|
||||
|
||||
1. **Goldmark `unsafe: true`** — keep (consumer raw-HTML compat) or drop (eliminates bio-XSS surface + reduces P1-1 blast radius)? Test on real sites: `grep -r '<' content/post/*/index.md`. Affects Phase 1 fix shape.
|
||||
2. **Hugo version floor** — bump `theme.toml min_version` to 0.154 (CI-tested, narrower compat) or keep 0.146 (broader compat, untested)? Affects Phase 6 CI matrix decision.
|
||||
3. **Audience signal** — solo bloggers vs teams? Drives whether multi-author / multi-language i18n moves out of deferred for v0.4.0. No code change for v0.3.0.
|
||||
4. **Demo site analytics** — opt-in privacy-respecting analytics on `tiennm99.github.io/tsuki/` (e.g., GoatCounter)? Currently flying blind on which features get used. Affects v0.3.0+ feature prioritization, not v0.3.0 scope itself.
|
||||
5. **v0.2.1 patch** — ship it, or fold its scope into v0.3.0 Phase 1? If folded, drop the "conditional" framing on Phase 1.
|
||||
6. **`data/profile.yaml: url`** — add to documented schema (Phase 1 P1-2 fix), or remove the read in `seo.html`? Schema vs. minimalism trade-off.
|
||||
Reconciled from researcher (feature gap) + code-reviewer (Lighthouse audit) + prior plan. Deduplicated, grouped thematically.
|
||||
|
||||
### A. Scope boundaries
|
||||
|
||||
1. **Cover-image feature scope** — defer entirely to v0.4.0 (current plan recommendation) or ship minimal render-hook in v0.3.0 Phase 2? Drives AVIF + responsive srcset + P2-1 SVG-logo JSON-LD timing. *Recommendation: defer; document override path in customization.md per Phase 3.*
|
||||
2. **v0.2.1 patch** — ship it, or fold its scope into v0.3.0 Phase 1? If folded, drop the "conditional" framing on Phase 1.
|
||||
3. **Language switcher routing** — must Phase 3 ship the switcher UI, or can en.yml + hreflang land alone with switcher slipping to v0.4.0? *Recommendation: ship in Phase 3 since en.yml is half the value; switcher is small (~200 B CSS + ~100 B JS).*
|
||||
4. **Code-copy button accessibility** — hide when `navigator.clipboard` unavailable (HTTP non-localhost), or always show with fallback UI? *Recommendation: hide; smaller bundle, fewer states.*
|
||||
5. **Breadcrumbs schema** — auto-emit `BreadcrumbList` JSON-LD or markup-only? *Recommendation: schema-on; SEO win is the whole point.*
|
||||
|
||||
### B. Config + compat
|
||||
|
||||
6. **Goldmark `unsafe: true`** — keep (consumer raw-HTML compat) or drop (eliminates bio-XSS surface + reduces P1-1 blast radius)? Test on real sites: `grep -r '<' content/post/*/index.md`. Affects Phase 1 fix shape.
|
||||
7. **Hugo version floor** — bump `theme.toml min_version` to 0.154 (CI-tested, narrower compat) or keep 0.146 (broader compat, untested)? Affects Phase 6 CI matrix decision.
|
||||
8. **`data/profile.yaml: url`** — add to documented schema (Phase 1 P1-2 fix), or remove the read in `seo.html`? Schema vs. minimalism trade-off.
|
||||
9. **`en.yml` as canonical baseline?** — Phase 3 ships en.yml as a starter; should it become canonical (English-first) with vi.yml as overlay, or stay Vietnamese-first? *Recommendation: stay vi-canonical for v0.3.0; revisit if audience signal shifts.*
|
||||
|
||||
### C. Visual / token decisions (impact: light-mode visual diff)
|
||||
|
||||
10. **`--tsuki-fg-subtle` light-mode value** — currently #888 (3.54:1, fails AA). P2-8 recommends #6b6b6b (~5:1). Confirm visual acceptable, then mirror to dark-mode equivalent. *Recommendation: ship #6b6b6b, document in CHANGELOG under "Changed (visual diff)".*
|
||||
11. **`<html lang>` default fallback** — replace hard-coded "vi" with `site.Language.Lang | default "en"`. Site-level config wins anyway; this only changes the fallback when `Site.Language.Lang` is empty. *Recommendation: "en" — more sensible default for a theme.*
|
||||
|
||||
### D. Operations / observability
|
||||
|
||||
12. **Audience signal** — solo bloggers vs teams? Drives whether multi-author / multi-language i18n moves out of deferred for v0.4.0. No code change for v0.3.0.
|
||||
13. **Demo site analytics** — opt-in privacy-respecting analytics on `tiennm99.github.io/tsuki/` (e.g., GoatCounter)? Currently flying blind on which features get used. Affects v0.3.0+ feature prioritization.
|
||||
14. **Lighthouse CI in pages.yml** — add 4-run Lighthouse Action on tag commits (home/post/list/search)? Cost: ~3 min CI per tag. *Phase 6 A6.2 leans toward shipping; if maintainer wants minimal CI cost, defer to v0.3.1. Either choice unblocks v0.3.0 tag.*
|
||||
15. **Stack/PaperMod future drift** — are competitors planning AI chat / embedded analytics that would justify expanding tsuki's shortcode ecosystem? Inform v0.4.0+ roadmap, not v0.3.0.
|
||||
|
||||
@@ -0,0 +1,321 @@
|
||||
# Lighthouse ≥80 baseline audit — tsuki v0.2.1
|
||||
|
||||
Scope: full theme at `main` (`d30f50f`). Read: README, CHANGELOG (Unreleased + v0.2.1 + v0.2.0), `layouts/baseof.html`, `layouts/_partials/{head,head/seo,footer,header,nav,meta,post-card,comments,toc,toc-enabled,search-button,related-posts}.html`, `layouts/_partials/home/{hero,projects,recent-posts}.html`, all `layouts/_markup/render-*.html`, `layouts/{single,home,list,404}.html`, `layouts/{search,post,archives,taxonomy,_default}/*.html`, all `assets/css/*.css`, all `assets/js/*.js`, `hugo.yaml`, `exampleSite/hugo.yaml`, `i18n/vi.yml`, `scripts/smoke-tests.sh`, prior audits (v0.2.0-post / v0.2.1-patch). Cross-checked against built `exampleSite/public/{index,2026/01/10/.../index,search/index}.html`, `sitemap.xml`, bundle sizes.
|
||||
|
||||
## TL;DR
|
||||
|
||||
Projected Lighthouse scores on a real production GitHub Pages deploy (`exampleSite`), median of 3 mobile runs, *no measurement performed* — static-inspection estimate:
|
||||
|
||||
- **Performance:** 92–98/100. Comfortable ≥80. Tiny bundles (3.96 KB gz CSS, 1.04 KB gz JS), minify on, hashed assets. LCP risk only on posts with a `cover.image` (no preload, no `fetchpriority`), but exampleSite has none so it lands in the high 90s.
|
||||
- **Accessibility:** 88–93/100. Likely ≥80 but **not the ≥95 ceiling Phase 4 targets**. Three known deductions: theme-toggle button missing `aria-pressed` on initial SSR (only set in JS), small tap targets (`2rem` × `2rem` = 32px for toggle/search button is fine but pagination arrows + footer text links are <24×24 on mobile), and one `aria-label` localized to vi only (`Liên kết đến phần này` in render-heading regardless of site language).
|
||||
- **Best Practices:** 95–100/100. Safe ≥80. SRI on bundles, `noopener noreferrer`, no mixed content, no deprecated APIs, console clean. Single risk: `unsafe: true` Goldmark is the consumer's problem, not Lighthouse's.
|
||||
- **SEO:** 95–100/100. Safe ≥80. Sitemap, canonical, OG/Twitter, JSON-LD, viewport, lang, description all present. Only deductions are robots.txt being absent from `static/` (Hugo emits one only if configured) and `hreflang` not being emitted (theme is monolingual — but README/features list says "i18n").
|
||||
|
||||
**Confidence:** medium-high on Performance/Best Practices/SEO; medium on Accessibility (tap-size is the one place static inspection meaningfully misses what Lighthouse measures).
|
||||
|
||||
**Verdict: all four categories pass ≥80 on the demo today.** This audit identifies what would *block* the score in real-consumer configurations (cover images, English sites, dense menus) and what would push Accessibility past 95 to meet the Phase 4 success criterion.
|
||||
|
||||
---
|
||||
|
||||
## P0 — blocks ≥80 in some category
|
||||
|
||||
### P0-1 — Cover-image LCP unmeasured; no preload / no `fetchpriority` / no `sizes`
|
||||
**Where:** `layouts/_partials/head/seo.html:10-15` (cover resolution), `layouts/single.html:4-15` (post body — no cover rendered at all), `layouts/_markup/render-image.html:1-5` (content images only)
|
||||
**Why it costs points:** A `cover.image` is only used for OG/Twitter cards. It is never rendered into the page DOM as a hero. The CHANGELOG (v0.2.0) advertises `cover.image` as "the preferred OG/Twitter cover key" — fine for SEO, but a typical Hugo theme renders the cover as an LCP element. The instant a consumer adds a cover image and writes their own hero partial (or expects the theme to render it), they will paint a large image with `loading="lazy"` (per render-image.html), no preload, no `fetchpriority="high"`, no `width`/`height`. That fails LCP and CLS simultaneously and can knock Performance below 80 on slow 4G.
|
||||
**Why this is P0 vs P1:** Right now exampleSite has no cover images so the demo Lighthouse number is clean — but the theme advertises a feature whose default rendering would tank the score. Consumer-facing footgun.
|
||||
**Fix sketch (no build step):**
|
||||
1. Render a hero cover in `single.html` (`{{ with .Params.cover.image }}<img ...>{{ end }}`) using Hugo `images.Resize` for `width`/`height`/`srcset`/`sizes`.
|
||||
2. In `head.html`, when `.Params.cover.image` resolves to a local resource, emit `<link rel="preload" as="image" href="{{ . }}" fetchpriority="high">`.
|
||||
3. First in-content cover gets `loading="eager" fetchpriority="high" decoding="async"`; rest stay `lazy`.
|
||||
4. Document the per-post `cover.image` → above-fold rendering path in `docs/data-schemas.md`.
|
||||
**Alternative (KISS):** ship a documented "to render cover, override `single.html`" note + a working snippet in `docs/customization.md`. Phase 5 of v0.3.0 doesn't cover this; Phase 3 (author UX) is the right place.
|
||||
|
||||
### P0-2 — Pagefind UI CSS is render-blocking on `/search/`
|
||||
**Where:** `layouts/search/list.html:5` (`<link rel="stylesheet" href="{{ "/pagefind/pagefind-ui.css" | relURL }}">` in `head_extra`)
|
||||
**Confirmed in built output:** `exampleSite/public/search/index.html` emits `<link rel=stylesheet href=/pagefind/pagefind-ui.css>` with no `media`/`onload` swap. This file is 3rd-party CSS, not part of the 3.96 KB gz bundle, and not preloaded.
|
||||
**Why it costs points:** Pagefind UI CSS is ~3–4 KB gz on its own; on a cold visit it adds one render-blocking request after the theme bundle. Combined with the JS module that constructs the search UI (`scripts` block — loads `pagefind/pagefind-ui.js`), `/search/` is the single worst-LCP page on the site. Already flagged in P2-4 of the prior audit but not in v0.3.0 plan as a P0.
|
||||
**Fix sketch:**
|
||||
```html
|
||||
<link rel="preload" as="style" href="{{ "/pagefind/pagefind-ui.css" | relURL }}" onload="this.rel='stylesheet'">
|
||||
<noscript><link rel="stylesheet" href="{{ "/pagefind/pagefind-ui.css" | relURL }}"></noscript>
|
||||
```
|
||||
Cheaper alt: inline minimal Pagefind reset (~300B) and drop the link entirely.
|
||||
|
||||
### P0-3 — Tap target sizing on pagination, footer links, theme-toggle/search-button on mobile
|
||||
**Where:** `assets/css/components.css:155-172` (pagination), `assets/css/layout.css:68-81` (footer), `assets/css/layout.css:45-56` + `assets/css/search.css:10-25` (`.theme-toggle` + `.search-button` = `2rem × 2rem` = 32×32 — under WCAG 2.5.8 AA threshold of **24×24** so passes 2.5.8 minimum but **fails 2.5.5 AAA** and Lighthouse "Tap targets" audit which uses **48×48 px**)
|
||||
**Why it costs Lighthouse points:** Lighthouse mobile audit specifically measures "Tap targets are sized appropriately" against a 48×48 CSS-px threshold (not WCAG's 24×24). At 32×32, every interactive icon in the header fails. Pagination `<a>` is `padding: 0.25rem 0.75rem; min-width: 2rem;` → ~32×28 on mobile. Multiple failed targets each cost ~5 points. Phase 4 of v0.3.0 plans for WCAG 2.5.8 (24×24) but **not** Lighthouse's stricter 48×48 — flag this delta.
|
||||
**Fix sketch:** Bump theme-toggle/search-button to `min-width:2.5rem; min-height:2.5rem` (40×40, still smaller than 48 but improves). For 48×48, use `padding: 0.5rem` and `min-width:3rem; min-height:3rem`. Pagination needs `padding: 0.5rem 0.75rem` and `min-height:2.75rem`. Footer link area can use `padding-block: 0.25rem` to expand hit zone without resizing visible text.
|
||||
|
||||
### P0-4 — Theme-toggle `aria-pressed` is set only in JS, not in HTML
|
||||
**Where:** `layouts/_partials/header.html:10` (button has `aria-label` but no initial `aria-pressed`); `assets/js/theme-toggle.js:14,20` (sets `aria-pressed` after JS runs)
|
||||
**Why it costs Lighthouse a11y points:** Lighthouse axe rule `button-name` + ARIA validation checks for `aria-pressed` consistency on toggle buttons that announce state. With JS disabled, the button is `hidden` (good), but Lighthouse runs with JS enabled, sees `aria-label="Đổi giao diện"` (only vi, no `aria-pressed`, no `role="switch"` either). On first paint *before* JS finishes parsing the module, screen readers see a button with no pressed state. Tooling counts this as "ARIA toggle button missing aria-pressed" → −5 to −10 a11y points.
|
||||
**Fix sketch:** Render initial `aria-pressed` in the template based on a flash-prevention readable signal. Cleanest: inline the theme-flash script and set `aria-pressed` directly:
|
||||
```html
|
||||
<button … data-theme-toggle aria-pressed="false" hidden>…</button>
|
||||
```
|
||||
Then have the inline `<script>` in `head.html:13-22` also update `aria-pressed` *before* body paints. This is also the right place to set `data-theme="dark"` for SSR. Currently the inline script only sets `data-theme`, not `aria-pressed`.
|
||||
|
||||
### P0-5 — `i18n/en.yml` missing; English-default sites will paint vi strings
|
||||
**Where:** `i18n/vi.yml` (only file); `layouts/_markup/render-heading.html:4` (`aria-label="Liên kết đến phần này"` hardcoded vi); `layouts/_partials/footer.html:7` (`{{ i18n "poweredBy" | default "Powered by" }}`)
|
||||
**Why it costs Lighthouse points:** A consumer site with `defaultContentLanguage: en` and `languageCode: en` will get:
|
||||
- `<html lang="en">` correct
|
||||
- All `i18n "x" | default "English fallback"` calls fall to the default text (mixed quality, some still vi e.g. `i18n "search" | default "Tìm kiếm"` in `search-button.html:1` falls back to **vi** — see also `archives/list.html:14`, `search/list.html:11`, many spots)
|
||||
- `render-heading.html:4` hardcodes `aria-label="Liên kết đến phần này"` regardless of site language — Lighthouse a11y axe rule `lang` flags content text inconsistent with `<html lang>`.
|
||||
**Why this is P0:** Already in Phase 3 of v0.3.0 — but the heading-anchor hardcoded vi is *not* fixed by adding `en.yml`, it requires a template change. Without en.yml + render-heading.html i18n, an English site fails Lighthouse a11y because language attribute / content mismatch.
|
||||
**Fix sketch:**
|
||||
1. Ship `i18n/en.yml` with all 40 keys (already on Phase 3 todo).
|
||||
2. Move `aria-label` in `render-heading.html` to `{{ i18n "headingAnchor" | default "Anchor link" }}` and add the key to both bundles.
|
||||
3. Audit all `| default "vi string"` and either drop (now key exists) or convert to language-neutral. P2-9 in prior audit lists the pass.
|
||||
|
||||
---
|
||||
|
||||
## P1 — improves score but doesn't block ≥80
|
||||
|
||||
### P1-1 — Inline theme-flash script is render-blocking but not SRI-protected
|
||||
**Where:** `layouts/_partials/head.html:13-22`
|
||||
**Why:** The 9-line inline `<script>` runs synchronously before paint. Total cost ~200B uncompressed inline; not large but every Lighthouse "minimize render-blocking" audit gives full credit only when no synchronous JS appears in `<head>`. The pattern is correct (necessary for no-flash dark mode), so the *fix* is acknowledgment, not removal. Worth noting: the inline script has no nonce/SRI — if a consumer adds a strict CSP, this script breaks. Document the CSP requirement.
|
||||
**Fix:** Add `nonce="{{ .CSPNonce }}"` placeholder + documentation. No code change urgent.
|
||||
|
||||
### P1-2 — `home-hero-avatar` and `project-card-image` lack `srcset` / responsive sizes
|
||||
**Where:** `layouts/_partials/home/hero.html:5` (avatar 120×120 explicit, good — but only one size), `layouts/_partials/home/projects.html:13` (no width/height, no srcset)
|
||||
**Why:** Lighthouse "Properly size images" audit fires when an image's intrinsic size is materially larger than its display size. Avatar SVG is fine; project images at 16:9 aspect ratio crop with `object-fit:cover` — if a consumer ships a 2000×1500 JPG it loses points.
|
||||
**Fix:** Use Hugo `.Resources.GetMatch` + `.Resize` to generate `srcset` for project images. Requires moving `data/projects.yaml` images to page resources or doing `images.Resize` on `resources.Get` results. Bigger refactor — defer to v0.4 with cover-image work (P0-1).
|
||||
|
||||
### P1-3 — `project-card-image` `<img>` missing explicit `width`/`height` → CLS risk
|
||||
**Where:** `layouts/_partials/home/projects.html:13` (`<img src="..." alt="..." loading="lazy" decoding="async">` — no `width`/`height`)
|
||||
**Why:** The `aspect-ratio: 16/9` on `.project-card-image` reserves space, so CLS is currently 0 on demo. But: if a consumer's image's intrinsic aspect ratio differs from 16:9, `object-fit: cover` masks it but Lighthouse's CLS metric also penalizes lack of dimensional hints on `<img>`.
|
||||
**Fix:** Add `width="640" height="360"` (canonical 16:9) hint to the `<img>`. Trivial.
|
||||
|
||||
### P1-4 — Site-wide JS bundle (theme-toggle + code-copy) loaded on every page kind
|
||||
**Where:** `layouts/_partials/footer.html:13-18`
|
||||
**Why:** 1.04 KB gz across the board. Lighthouse penalizes unused JS. `code-copy.js` is dead bytes on home/list/taxonomy/search (no `<pre>` blocks). This is **P2-3 in the prior audit** + already on v0.3.0 Phase 2 todo. Mentioning here for completeness: gating saves ~500B gz from home Lighthouse measurement.
|
||||
**Fix:** Already planned (Phase 2 budget rebase). No additional action.
|
||||
|
||||
### P1-5 — No `<link rel="preconnect">` / `<link rel="dns-prefetch">` for Giscus / Pagefind worker
|
||||
**Where:** `layouts/_partials/comments.html:7` (Giscus loaded async, but no preconnect to `giscus.app`); search Pagefind worker loaded lazily
|
||||
**Why:** When comments enabled, the first paint waits on Giscus iframe DNS + TLS handshake. Adding `<link rel="preconnect" href="https://giscus.app" crossorigin>` in `head.html` (conditional on Giscus enable + post-kind) saves 200–500ms on third-party connect.
|
||||
**Fix sketch:**
|
||||
```html
|
||||
{{- $g := site.Params.comments.giscus -}}
|
||||
{{- if and (eq .Kind "page") $g $g.enable $g.repo $g.repoId $g.categoryId (ne .Params.comments false) }}
|
||||
<link rel="preconnect" href="https://giscus.app" crossorigin>
|
||||
{{- end }}
|
||||
```
|
||||
|
||||
### P1-6 — `hreflang` alternate links not emitted; README/features advertise "i18n"
|
||||
**Where:** `layouts/_partials/head.html` (no `<link rel="alternate" hreflang="...">` block); `theme.toml` lists `i18n` as a feature tag
|
||||
**Why:** Lighthouse SEO checks for `hreflang` on multilingual sites. tsuki is single-language by default (vi only) but documentation claims i18n. A consumer running `languages: {vi: {...}, en: {...}}` gets pages built but no `hreflang` linking — Lighthouse SEO drops 2–4 points on each language root.
|
||||
**Fix sketch:** Add to `head.html`:
|
||||
```html
|
||||
{{- if site.Home.AllTranslations }}
|
||||
{{- range .AllTranslations }}
|
||||
<link rel="alternate" hreflang="{{ .Language.Lang }}" href="{{ .Permalink }}">
|
||||
{{- end }}
|
||||
<link rel="alternate" hreflang="x-default" href="{{ site.Home.Permalink }}">
|
||||
{{- end }}
|
||||
```
|
||||
Cheap, conditional, no penalty when not used.
|
||||
|
||||
### P1-7 — `og:locale:alternate` missing for multi-language
|
||||
**Where:** `layouts/_partials/head/seo.html:28-30`
|
||||
**Why:** Same as P1-6 — supplementary; only emits one `og:locale`. OpenGraph spec supports `og:locale:alternate`.
|
||||
**Fix:** Append `og:locale:alternate` per translation when present.
|
||||
|
||||
### P1-8 — `<noscript>` style block missing for theme-toggle / code-copy / pagefind UI
|
||||
**Where:** none — entire theme has only one `<noscript>` (`layouts/search/list.html:18`)
|
||||
**Why:** Lighthouse a11y axe rule `landmark-no-duplicate-banner` and similar don't fire, but the audit "Page contains a meta description" / "Document has a valid hreflang" / etc. — fine. Practical impact: SR users with JS off see "◐" toggle button after `hidden` is removed by JS. Currently the button stays `hidden`. Edge case.
|
||||
**Fix:** None blocking. Document in `docs/accessibility.md` (Phase 4 has it).
|
||||
|
||||
### P1-9 — Service worker / PWA not present
|
||||
**Why:** Lighthouse PWA audit is informational, doesn't count toward Performance/Accessibility/Best-Practices/SEO. **Skip.** Documenting for completeness.
|
||||
|
||||
### P1-10 — `head.html` description fallback chain differs from `head/seo.html`
|
||||
**Where:** `head.html:2` falls back to `site.Title`; `head/seo.html:7-9` falls back to nothing (only truncates if present)
|
||||
**Why (SEO):** Already P2-11 in prior audit. `<meta name="description">` may emit `site.Title` while `og:description` is missing. Lighthouse SEO checks for `meta description` presence — passes. Cosmetic inconsistency only. Won't move score.
|
||||
**Fix:** Hoist to shared partial. Phase 2 (budget rebase) is a good landing spot.
|
||||
|
||||
### P1-11 — Pagefind worker JS lacks SRI / `crossorigin` matching theme bundle
|
||||
**Where:** `layouts/search/list.html:28-49`
|
||||
**Why:** Third-party Pagefind UI script (inline import) has no integrity. CSP "strict-dynamic" friendly but a `<script type="module">` with dynamic `import` defeats SRI anyway. Best-practices audit doesn't penalize. **Skip** — no fix.
|
||||
|
||||
### P1-12 — `<title>` truncation absent
|
||||
**Where:** `layouts/_partials/head.html:1` (`{{- $title := cond .IsHome site.Title (printf "%s · %s" .Title site.Title) -}}` — no length cap)
|
||||
**Why:** Long post titles ("My very long post title about etc..." × site.Title) can exceed Google SERP truncation (~60 chars). Lighthouse SEO doesn't check; SEO tools do.
|
||||
**Fix:** Optional `truncate 60` on the composed title for non-home pages. Not blocking ≥80.
|
||||
|
||||
---
|
||||
|
||||
## P2 — polish / future
|
||||
|
||||
### P2-1 — JSON-LD `image` and `publisher.logo` reuse the avatar SVG
|
||||
**Where:** `layouts/_partials/head/seo.html:71,83`
|
||||
Built output (`2026/01/10/ke-hoach-dau-nam/index.html`) confirms `publisher.logo.url` = avatar.svg. Google Structured Data Testing Tool requires logo to be PNG/JPG; SVG is rejected by some validators. Lighthouse SEO doesn't validate JSON-LD content, only presence. Won't move Lighthouse score but breaks Search Console rich-result eligibility. Add a `params.og.logoImage` distinct from avatar.
|
||||
|
||||
### P2-2 — `:where()` + `:has()` + View Transitions are progressive; no Modernizr / fallback class
|
||||
**Where:** `assets/css/view-transitions.css:3` (`@view-transition`), various uses of `:where()` in tokens.css
|
||||
**Why:** Lighthouse Best Practices audit "CSS has invalid syntax" — both `@view-transition` and `:where()` are post-CR. Modern browsers parse cleanly; older browsers silently ignore. Not a deduction. **Skip.**
|
||||
|
||||
### P2-3 — `min-height: 100vh` on `body` causes mobile-iOS overscroll issues
|
||||
**Where:** `assets/css/reset.css:8`
|
||||
**Why:** Cosmetic on iOS Safari URL bar. Lighthouse doesn't check. Modern alternative is `min-height: 100dvh`. **Trivial fix.**
|
||||
|
||||
### P2-4 — Avatar `<img>` background is `var(--tsuki-code-bg)` — visible empty disk during SVG load
|
||||
**Where:** `assets/css/home.css:15` + `layouts/_partials/home/hero.html:5`
|
||||
**Why:** A circular div with bg color in case SVG never paints. Not a CLS issue since width/height are set. Cosmetic.
|
||||
|
||||
### P2-5 — `code-copy.js` runs `querySelectorAll("pre")` synchronously at module top
|
||||
**Where:** `assets/js/code-copy.js:6`
|
||||
**Why:** Module is loaded with `defer` semantics (via `type=module`). Runs after DOMContentLoaded. No DOM-mutation main-thread block. Lighthouse "main-thread work" minimal. Already noted in P2-3 of prior audit.
|
||||
|
||||
### P2-6 — `IntersectionObserver` in `toc-active.js` runs even on posts under threshold
|
||||
**Where:** Already gated by `partial "toc-enabled.html"` in `footer.html:19-22`. Verified clean.
|
||||
|
||||
### P2-7 — `Cache-Control` headers are not under theme control
|
||||
**Why:** GitHub Pages default. tsuki ships hashed bundles, so consumer caching is achievable via consumer's hosting config. Document in `docs/deployment-guide.md` if not already. Out of theme scope.
|
||||
|
||||
### P2-8 — Color contrast: `--tsuki-fg-subtle: #888` on `--tsuki-bg: #fbfaf7` (light) and `#777` on `#14151a` (dark)
|
||||
**Where:** `assets/css/tokens.css:6,53`
|
||||
**Static contrast check:**
|
||||
- Light: `#888` on `#fbfaf7` ≈ 3.54:1 — **fails WCAG AA 4.5:1 for body text**, passes 3:1 for large text (≥18pt or 14pt bold).
|
||||
- Dark: `#777` on `#14151a` ≈ 4.7:1 — passes 4.5:1 for body text.
|
||||
- `--tsuki-fg-muted: #666` on `#fbfaf7` ≈ 5.7:1 — passes.
|
||||
- `--tsuki-fg-muted: #a0a0a0` on `#14151a` ≈ 7.6:1 — passes.
|
||||
|
||||
The `fg-subtle` token is used for `post-card-date`, `pagination .disabled`, `archive-post-date`, `heading-anchor`, `term-count`, all rendered at `--tsuki-fs-sm` (15px). 15px is below the 18pt/24px large-text threshold. **Light-mode `fg-subtle` fails WCAG AA.** Lighthouse axe contrast rule will flag every page card date → −10 to −20 a11y points.
|
||||
|
||||
**Fix:** Darken `--tsuki-fg-subtle` from `#888` to `#717171` (4.5:1) or `#6b6b6b` (5:1). Test against dark mode (`#777` is fine but if both must move in unison, dark gets `#9a9a9a`).
|
||||
|
||||
### P2-9 — `.pagination .disabled { opacity: 0.5 }` compounds existing low contrast
|
||||
**Where:** `assets/css/components.css:170`
|
||||
**Why:** Disabled pagination links use `--tsuki-fg-subtle` (~3.5:1 light) × `opacity:0.5` = effective 1.5–2:1. Even WCAG AAA disabled-state exemption may not apply if Lighthouse axe treats it as text. Likely flagged.
|
||||
**Fix:** Use `--tsuki-fg-muted` (#666) for disabled state — better contrast even at 0.5 opacity. Or use `pointer-events:none; cursor:not-allowed;` without opacity.
|
||||
|
||||
### P2-10 — `.callout` text uses `var(--tsuki-fg)` on `var(--tsuki-callout-bg)` light tint (e.g., `#2563eb14` = 8% blue)
|
||||
**Where:** `assets/css/callouts.css:9,22-26`
|
||||
**Why:** `#2563eb14` overlay on `--tsuki-bg: #fbfaf7` = pale blue ≈ `#e9eef9`. Body text `#1a1a1a` on `#e9eef9` ≈ 14.8:1 — fine. Title color `var(--tsuki-callout)` = `#2563eb` on the tint ≈ 5.7:1 — passes.
|
||||
Dark mode: `#6ea1ff1f` overlay on `#14151a` = `#1d2434` — title `#6ea1ff` on `#1d2434` ≈ 7.4:1. Fine. **No issue.**
|
||||
|
||||
### P2-11 — `.callout-warning` title `#d97706` on light tint
|
||||
**Where:** `assets/css/callouts.css:25`
|
||||
`#d97706` (amber) on `#fbf6ef` (#d97706 + 8% on bg) ≈ 3.2:1 — **fails 4.5:1 AA for body text but is title-only**. Lighthouse axe checks all text. Could trip on bold-but-small title text. Test with axe.
|
||||
**Fix:** Bump title to `#b45309` (3.8:1) for light mode or move title to body color and rely on color only on the border.
|
||||
|
||||
### P2-12 — `.theme-toggle` button-shape relies on `border-radius:999px` + 32px square — focus ring `outline-offset:2px` overflows into adjacent search button on narrow viewports
|
||||
**Where:** `assets/css/components.css:4-7` + `assets/css/layout.css:45-56` + `assets/css/search.css:5-8` (`gap: var(--tsuki-space-2)` = 8px)
|
||||
**Why:** Two adjacent circular buttons at 8px gap with 2px outline + 2px offset → ring touches sibling. Visual bug, not Lighthouse impact.
|
||||
|
||||
### P2-13 — `<details>` rendering unstyled (callouts replace one use case; raw `<details>` still common)
|
||||
Already P2-1 in prior audit; v0.3.0 Phase 3 covers.
|
||||
|
||||
### P2-14 — `og:image` `width` / `height` not declared
|
||||
**Where:** `layouts/_partials/head/seo.html:32`
|
||||
**Why:** Twitter/Facebook clip aggressively without dims. Not Lighthouse SEO — SEO of social previews. Minor.
|
||||
|
||||
### P2-15 — `meta name="theme-color"` not emitted
|
||||
**Where:** `head.html` does not emit `<meta name="theme-color">`.
|
||||
**Why:** Chrome on Android colors the URL bar with this. Light + dark variants supported via `media`. Cosmetic; not Lighthouse-scored. Adds polish.
|
||||
**Fix:**
|
||||
```html
|
||||
<meta name="theme-color" content="#fbfaf7" media="(prefers-color-scheme: light)">
|
||||
<meta name="theme-color" content="#14151a" media="(prefers-color-scheme: dark)">
|
||||
```
|
||||
|
||||
### P2-16 — `<html>` `lang` attribute hardcoded fallback to `vi`
|
||||
**Where:** `layouts/baseof.html:2` (`lang="{{ site.LanguageCode | default "vi" }}"`)
|
||||
**Why:** If consumer sets `languageCode: en-US` and `defaultContentLanguage: en`, `<html lang="en-US">` — fine. If they forget `languageCode`, it falls to `vi` — Lighthouse a11y `html-has-lang` passes but Lighthouse SEO `html-lang-valid` may flag mismatch with content. Defensive.
|
||||
**Fix:** Use `site.Language.LanguageCode | default site.Language.Lang | default "en"`. Drop the vi default — site should set its own language.
|
||||
|
||||
### P2-17 — Skip-link `inset-block-start: -3rem` may not be enough on dynamic header heights
|
||||
**Where:** `assets/css/components.css:11`
|
||||
**Why:** If header wraps to 2+ lines on mobile, `-3rem` may not fully hide. Cosmetic. Use `transform: translateY(-200%)`.
|
||||
|
||||
### P2-18 — `gohugoThemes` registry CI not yet green (per v0.3.0 plan note)
|
||||
Out of Lighthouse scope, mentioned for tracking.
|
||||
|
||||
---
|
||||
|
||||
## Already addressed (do not duplicate)
|
||||
|
||||
The following are already shipped in v0.2.0 / v0.2.1 (verified against current code):
|
||||
|
||||
- ✅ **Visible focus rings** (`assets/css/components.css:4-7`) — `:focus-visible { outline: 2px solid var(--tsuki-accent) }`. Note: P0-3 / P2-8 above may push focus contrast below 3:1 in light mode (accent `#4a6fa5` on bg `#fbfaf7` ≈ 5.3:1 — passes 3:1 SC 2.4.13 but only just).
|
||||
- ✅ **Skip-link** (`layouts/baseof.html:8`, `components.css:8-20`).
|
||||
- ✅ **`<main id="main">` landmark** (`baseof.html:10`).
|
||||
- ✅ **Render-image `loading="lazy" decoding="async"`** (`render-image.html:2`).
|
||||
- ✅ **Render-link `rel="noopener noreferrer"` for external** (`render-link.html:7-10`).
|
||||
- ✅ **Project links `safeURL` + `noopener noreferrer` + `target=_blank`** (`home/projects.html:30,33`).
|
||||
- ✅ **JSON-LD Article schema** with full author/publisher/keywords/image/datePublished/dateModified (`head/seo.html:62-87`, validated in built post).
|
||||
- ✅ **OG + Twitter Cards** with locale, article:author, article:tag, rune-safe 200-char truncate.
|
||||
- ✅ **Canonical URL** (`head.html:10`).
|
||||
- ✅ **Viewport meta** (`head.html:5`).
|
||||
- ✅ **`<html lang>`** (`baseof.html:2`).
|
||||
- ✅ **Sitemap + RSS** (built `exampleSite/public/sitemap.xml` + `index.xml` confirmed).
|
||||
- ✅ **No mixed content** (`grep -c 'http://'` on built home + post = 0).
|
||||
- ✅ **SRI integrity + crossorigin** on CSS + JS bundles (`head.html:62`, `footer.html:18,21,26`).
|
||||
- ✅ **Hugo generator stripped** (`<meta name=generator content="tsuki">`, no Hugo version).
|
||||
- ✅ **CSS budget 3962/4200 B gz** (verified via gzip on built bundle).
|
||||
- ✅ **`prefers-reduced-motion` honored** (`reset.css:35-42`, `view-transitions.css:15-18`).
|
||||
- ✅ **Pagination paginated-kind gate** (`head.html:33-40`, `pagination.html:2`).
|
||||
- ✅ **`hidden` attribute** on theme-toggle pre-JS (`header.html:10`) — good no-JS UX.
|
||||
- ✅ **Comments gate requires repo + repoId + categoryId** (`comments.html:2`).
|
||||
- ✅ **`seo.html` `$authorURL` chain nil-safe** (`head/seo.html:64-67`).
|
||||
- ✅ **`nav.html` `relURL`** (`nav.html:6`).
|
||||
- ✅ **htmltest pinned to commit SHA** (`.github/workflows/pages.yml:69`).
|
||||
- ✅ **Smoke tests for JSON-LD / OG / skip-link / main-id / render-link rel / CSS budget** (`scripts/smoke-tests.sh`).
|
||||
|
||||
---
|
||||
|
||||
## Covered by v0.3.0 plan (do not re-fix; flag if reordering needed)
|
||||
|
||||
- **Per-page-kind CSS bundles** — Phase 2 (covers P1-4 site-wide JS gating too).
|
||||
- **`i18n/en.yml`** — Phase 3 (covers P0-5 partially; **add render-heading.html `aria-label` i18n** to Phase 3 todo).
|
||||
- **`<details>` styling + TOC narrow-viewport collapse** — Phase 3.
|
||||
- **WCAG 2.2 AA pass** including focus appearance + tap targets ≥24×24 — Phase 4 (**bump tap target threshold to Lighthouse's 48×48 to cover P0-3; flag P2-8 contrast on `fg-subtle` for token adjustment**).
|
||||
- **llm.txt + Speculation Rules** — Phase 5 (Speculation Rules will help LCP on internal nav and contribute to Performance score; opt-in is correct).
|
||||
- **Smoke-test expansion + Hugo CI matrix** — Phase 6.
|
||||
|
||||
---
|
||||
|
||||
## Recommended scope additions for v0.3.0
|
||||
|
||||
Two findings above are scope-adjacent enough they should fold into existing phases rather than being deferred:
|
||||
|
||||
1. **Add P0-1 (cover-image LCP) as a Phase 3 sub-task or new Phase 3.5.** Currently no phase touches `single.html` rendering of cover. Either (a) document override path in `docs/customization.md` + warn that default doesn't render cover (cheap), or (b) ship a default cover renderer in `single.html` with preload + `fetchpriority="high"`. Recommend (a) for v0.3.0, (b) for v0.4.0 alongside `images.Resize`/`srcset` pipeline.
|
||||
|
||||
2. **Add P0-2 (Pagefind UI CSS preload swap) to Phase 5 or Phase 2.** Trivial change (~3 lines in `search/list.html`), zero CSS impact. Drop in Phase 2 (budget rebase already touches search.css).
|
||||
|
||||
3. **Add P0-3 (Lighthouse 48×48 tap targets) as a Phase 4 success criterion.** Phase 4 currently targets WCAG 24×24; Lighthouse uses 48×48. Update Phase 4 success criteria to "≥48×48 on theme-toggle / search-button / pagination / footer links" — or explicitly accept Lighthouse a11y of 90-94 (still ≥80) as the bound.
|
||||
|
||||
4. **Add P0-4 (theme-toggle `aria-pressed` in HTML) to Phase 4.** Single-line change; needs inline-script update too. ~3 lines total.
|
||||
|
||||
5. **Add P1-5 (preconnect to giscus.app) to Phase 2.** Conditional emit alongside other head logic.
|
||||
|
||||
6. **Add P1-6 (`hreflang` alternate links) to Phase 3 or 5.** ~6 lines in `head.html`. Cheap. Without it the theme cannot honestly claim "i18n" as a feature in `theme.toml`.
|
||||
|
||||
7. **Add P2-8 (color contrast `fg-subtle` in light mode) to Phase 4.** Token adjustment, one-line change in `tokens.css`. Critical because every post-card date and pagination disabled state is affected — this alone could be a 10-point a11y hit.
|
||||
|
||||
**Phase 4 (WCAG 2.2 AA audit) is the keystone phase for Lighthouse a11y ≥95.** It already targets 95; the three additions above (P0-3 thresholds, P0-4 toggle ARIA, P2-8 contrast token) are the deltas between "WCAG 2.2 AA" and "Lighthouse a11y ≥95". They're sub-task adjustments, not new phases.
|
||||
|
||||
---
|
||||
|
||||
## Confidence + caveats
|
||||
|
||||
- **Bundle sizes are real**: 3.96 KB gz CSS / 1.04 KB gz JS (measured from `exampleSite/public/`). Performance numbers will be high.
|
||||
- **Color contrast is computed**, not eyeballed: light-mode `fg-subtle: #888` on `bg: #fbfaf7` is 3.54:1 — **inspect on axe-devtools to confirm**.
|
||||
- **Tap-size delta** (WCAG 24×24 vs Lighthouse 48×48) is the most likely place this audit underestimates: actual measurement may show pagination + theme-toggle as fail. Worth running Lighthouse-mobile against the demo before committing to a tap-size scope decision in Phase 4.
|
||||
- **JSON-LD is valid** (parsed mentally against schema.org Article spec from built output) — Lighthouse SEO will count this positively. Note SVG logo is a Google rich-result rejection risk (P2-1), not a Lighthouse deduction.
|
||||
- **No CSP, no analytics, no third-party fonts** — Performance ceiling is high.
|
||||
- **Cover-image LCP** is the single biggest blind spot in this audit because exampleSite has no covers. If a consumer's site is what gets measured for the README claim, P0-1 is the difference between Performance 95 and Performance 75.
|
||||
|
||||
---
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
1. **Which `exampleSite` configuration is the canonical Lighthouse target?** If the README ever claims "≥80 Lighthouse", which page kinds and configurations is the claim scoped to? Home only, or home + a post + list + search? Suggest documenting in `docs/accessibility.md` + adding 4 Lighthouse runs to CI on tag (Phase 6 candidate).
|
||||
2. **Cover-image rendering — theme or consumer responsibility?** Phase 3 (author UX) is the right place to decide. If theme renders cover, what's the default size and aspect ratio? If consumer renders, how do we document `cover.image` is OG-only by default?
|
||||
3. **`og:image` resolution chain emits SVG avatar** when no cover is set; Google rich-result requires PNG/JPG. Worth shipping a default PNG asset alongside the SVG, or documenting that consumers ship their own PNG? Affects P2-1.
|
||||
4. **Tap-size target: WCAG 24×24 or Lighthouse 48×48?** Phase 4 currently aims at WCAG. Tightening to 48×48 may change pagination + theme-toggle visual design materially. Maintainer decision before Phase 4 begins.
|
||||
5. **Is `aria-pressed` on theme-toggle the right ARIA pattern, or `role="switch"` with `aria-checked`?** Both are valid; `switch` is more semantic for binary state. Affects P0-4 fix shape.
|
||||
6. **Should the demo site enable Speculation Rules** so the README Performance claim includes the prefetch benefit, or stay opt-in and claim a lower Performance number? Affects Phase 5 demo config.
|
||||
7. **`hreflang` emit even when site is single-language** — harmless (empty range, no output) but adds template noise. Or gate on `site.IsMultiLingual`? Pick one.
|
||||
8. **Color contrast change to `--tsuki-fg-subtle`** would affect every site visually (dates appear darker). Acceptable design trade-off, or token requires a new variant (`--tsuki-fg-faint` for non-text decorations vs `--tsuki-fg-subtle` for accessible text)?
|
||||
@@ -0,0 +1,398 @@
|
||||
---
|
||||
report_type: Feature Gap Analysis
|
||||
status: DONE
|
||||
date: 2026-05-15
|
||||
scope: tsuki v0.2.1 vs. hugo-theme-stack, hugo-PaperMod, Anatole, Hello Friend NG — blog+portfolio baseline 2026
|
||||
sources:
|
||||
- tsuki README, CHANGELOG, config.md, customization.md
|
||||
- Stack: GitHub, demo site, v4.0 code
|
||||
- PaperMod: GitHub wiki, demo, v1.x code
|
||||
- Anatole, Hello Friend NG: GitHub repos, search results
|
||||
---
|
||||
|
||||
# Feature Gap Report: tsuki v0.2.1 vs. Industry Standards
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Verdict:** tsuki **reaches feature parity with Stack and PaperMod** on all essential blog+portfolio dimensions through v0.2.1. No critical gaps exist.
|
||||
|
||||
**Missing features** fall into three tiers:
|
||||
|
||||
- **Tier A (nice-to-have, low friction, v0.3.0 ready):** image galleries/lightbox, image zoom, series/subsection routing, reading time display, breadcrumbs, email newsletter signup
|
||||
- **Tier B (medium effort, v0.4.0+):** AVIF image processing, multi-author bylines, advanced comment threading, KaTeX/Mermaid shortcodes
|
||||
- **Tier C (out-of-scope per design):** heavy JS features (AI-powered chat, analytics, complex e-commerce)
|
||||
|
||||
**Budget constraint:** tsuki's CSS ≤4 KB gz + JS ≤1 KB gz philosophy is **non-negotiable** and already achieved; all recommendations below respect this hard ceiling.
|
||||
|
||||
---
|
||||
|
||||
## Feature Matrix: tsuki vs. Peers
|
||||
|
||||
| Feature | Stack v4.0 | PaperMod v1.x | Anatole | Hello Friend NG | tsuki v0.2.1 | Gap Status | Priority |
|
||||
|---------|:----------:|:-------------:|:-------:|:---------------:|:------------:|:----------:|:--------:|
|
||||
| **CONTENT SURFACE** |
|
||||
| Posts/Blog | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Draft support | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Cover images (per-post) | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Series/subsections | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Post archetypes | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Callouts/admonitions | ✓ | ✓ | ✓ | ✓ | ✓ (native markdown) | Have | — |
|
||||
| **DISCOVERY** |
|
||||
| Full-text search | ✓ (Fuse.js) | ✓ (Fuse.js) | ✗ | ✓ | ✓ (Pagefind) | Have | — |
|
||||
| Tag/category taxonomy | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Year-grouped archive | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Breadcrumbs | ✓ | ✓ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Related posts | ✓ | ✓ | ✗ | ✓ | ✓ | Have | — |
|
||||
| RSS variants (Atom/JSON) | ✓ | ✓ | ✓ | ✓ | ✓ (standard) | Have | — |
|
||||
| **UX POLISH** |
|
||||
| TOC (auto-mount) | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Reading time | ✓ | ✓ | ✓ | ✓ | ✓ (byline) | Have | — |
|
||||
| Dark mode toggle | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Code copy button | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| Image lightbox/gallery | ✓ (PhotoSwipe) | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Image zoom on hover | ✗ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Prev/Next post nav | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| Scroll-to-top button | ✓ | ✓ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| **PERSONALIZATION** |
|
||||
| Profile/about page | ✓ (via data) | ✓ (via data) | ✓ (via data) | ✓ | ✓ (data/profile.yaml) | Have | — |
|
||||
| Social icons | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Project showcase grid | ✓ | ✓ | ✓ (portfolio) | ✗ | ✓ (data/projects.yaml) | Have | — |
|
||||
| Custom shortcodes | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P3 |
|
||||
| Email newsletter signup | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| **INTERNATIONALIZATION** |
|
||||
| Multi-language support | ✓ (12+ locales) | ✓ (25+ locales) | ✓ | ✓ | ✓ (vi + en) | Partial | P1 |
|
||||
| Language switcher UI | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| RTL support (Arabic/Hebrew) | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P3 |
|
||||
| Date localization | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| **SEO & AI** |
|
||||
| JSON-LD Article schema | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| OpenGraph/Twitter cards | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| Sitemap generation | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| llm.txt (AI crawlers) | ✗ | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Schema.org E-A-T signals | ✓ | ✓ | ✓ | ✓ | Partial (no author byline) | Partial | P2 |
|
||||
| **COMMENTS** |
|
||||
| Giscus (GitHub Discussions) | ✓ | ✓ | ✗ | ✗ | ✓ | Have | — |
|
||||
| Disqus | ✓ | ✓ | ✗ | ✓ | ✗ | Missing | P3 |
|
||||
| Utterances | ✓ | ✓ | ✗ | ✓ | ✗ | Missing | P3 |
|
||||
| Comment threading | ✓ (native Giscus) | ✓ (native) | — | ✓ | ✓ (native Giscus) | Have | — |
|
||||
| **PERFORMANCE SCAFFOLD** |
|
||||
| Responsive images | ✓ | ✓ | ✓ | ✓ | ✗ | Missing | P2 |
|
||||
| AVIF/WebP support | ✓ (render hook example) | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Image lazy-loading | ✓ | ✓ | ✓ | ✓ | ✓ (via render hook) | Have | — |
|
||||
| CSS minification | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| JS bundling/minify | ✓ | ✓ | ✓ | ✓ | ✓ | Have | — |
|
||||
| View Transitions API | ✗ | ✗ | ✗ | ✗ | ✓ | Have | — |
|
||||
| **AUTHOR TOOLING** |
|
||||
| Gallery shortcode | ✓ (Photoswipe) | ✗ | ✗ | ✗ | ✗ | Missing | P2 |
|
||||
| Video shortcode | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Tabs shortcode | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| Columns/grid shortcode | ✓ | ✗ | ✗ | ✗ | ✗ | Missing | P3 |
|
||||
| KaTeX math | ✓ | ✗ | ✗ | ✗ | ✗ (deferred by design) | Missing | P3 |
|
||||
| Mermaid diagrams | ✓ | ✗ | ✗ | ✗ | ✗ (deferred by design) | Missing | P3 |
|
||||
| **THEME CONFIG SURFACE** |
|
||||
| Exposed params | 30+ | 40+ | 25+ | 20+ | 15+ | Partial | P3 |
|
||||
| Override paths | All major | All major | Most | Most | All major | Have | — |
|
||||
| Customization docs | ✓ Excellent | ✓ Wiki+docs | ✓ Wiki | ✓ Docs | ✓ Good | Have | — |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Gap Analysis
|
||||
|
||||
### Tier A: Nice-to-Have, Low Friction (Ready for v0.3.0 or v0.4.0)
|
||||
|
||||
#### **1. Code Copy Button** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** UX convenience; improves blog usefulness for tutorials
|
||||
- **Current tsuki:** Code blocks render via Chroma; no copy button
|
||||
- **Effort:** S (1 partial + ~50 lines JS using `navigator.clipboard`)
|
||||
- **Bundle cost:** ~200 B gz
|
||||
- **Why defer:** Not essential; users can copy manually; low user demand signal yet
|
||||
- **Recommendation:** v0.3.0 optional `params.codeCopy.enable` flag, hidden if `navigator.clipboard` unavailable (HTTP non-localhost)
|
||||
|
||||
#### **2. Image Gallery / Lightbox** (Stack: PhotoSwipe, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** Gallery pages, portfolio grid galleries, post image carousels
|
||||
- **Stack approach:** PhotoSwipe integration (heavier, full-featured)
|
||||
- **Alternative (lightweight):** Unpic.pics API for lazy image loading + native browser `<picture>` elements
|
||||
- **Bundle cost:** PhotoSwipe = 15+ KB gz (heavy); native approach = 0
|
||||
- **Effort:** M (1 shortcode + CSS grid layout)
|
||||
- **Lighthouse concern:** ⚠️ Un-lazy-loaded gallery images tank Lighthouse. Mitigation: `loading="lazy"` on all thumbs.
|
||||
- **Recommendation:** Defer to v0.4.0. If users demand it, use `<picture>` + native CSS Grid before PhotoSwipe. Note: Stack's PhotoSwipe adds complexity and bundle weight incompatible with tsuki's ≤4 KB philosophy.
|
||||
|
||||
#### **3. Breadcrumbs Navigation** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Improves SEO (breadcrumb schema + UX clarity on deep posts)
|
||||
- **Current tsuki:** No breadcrumb navigation visible
|
||||
- **Effort:** S (1 partial + ~8 lines template logic)
|
||||
- **Bundle cost:** ~50 B CSS
|
||||
- **Why missing:** Low priority; posts are shallow (`/year/month/day/slug/`); breadcrumbs less valuable than in deep taxonomies
|
||||
- **Recommendation:** v0.3.0 optional `params.breadcrumbs.enable` flag; renders home > /posts/ > title. Schema.org breadcrumb list included for SEO.
|
||||
|
||||
#### **4. Prev/Next Post Navigation** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Improves post-to-post discoverability; boosts time-on-site
|
||||
- **Effort:** S (1 partial + 2 lines template: `.PrevInSection` / `.NextInSection`)
|
||||
- **Bundle cost:** ~100 B CSS
|
||||
- **Why missing:** Related posts widget already handles discovery; prev/next adds redundancy but improves UX
|
||||
- **Recommendation:** v0.3.0 optional `params.prevNextNav.enable` flag (default true); place above/below related posts.
|
||||
|
||||
#### **5. Scroll-to-Top Button** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** QoL for long posts on mobile
|
||||
- **Effort:** S (1 partial + ~30 lines JS using IntersectionObserver)
|
||||
- **Bundle cost:** ~150 B gz
|
||||
- **Why missing:** Lower priority; keyboard `Home` key works; browser auto-scroll in place
|
||||
- **Recommendation:** v0.4.0 nice-to-have; low friction if demand signals emerge.
|
||||
|
||||
#### **6. llm.txt Generation** (Stack: ✗, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** AI crawler guidance; emerging SEO signal (May 2026 standard)
|
||||
- **Effort:** S (1 Hugo template generating YAML/markdown at build time, like `robots.txt`)
|
||||
- **Bundle cost:** 0 (static artifact)
|
||||
- **Why missing:** Newly standardized (Feb 2026); no competitor yet shipping
|
||||
- **Recommendation:** **v0.3.0 Phase 5** — include in llm.txt generation per prior research report. Already planned.
|
||||
|
||||
---
|
||||
|
||||
### Tier B: Medium Effort, v0.4.0+ Scope
|
||||
|
||||
#### **7. Language Switcher UI** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Essential for multi-language sites; missing from header nav
|
||||
- **Current tsuki:** vi + en translations shipped; no visible switcher
|
||||
- **Effort:** M (1 partial + i18n logic + CSS dropdown)
|
||||
- **Bundle cost:** ~200 B css + ~100 B js
|
||||
- **Why missing:** Current audience primarily Vietnamese; multi-language routing not yet exposed to users
|
||||
- **v0.3.0 blocker:** Phase 3 (Author UX) adds `en.yml` i18n keys. Must include language switcher in Phase 4+ to be useful.
|
||||
- **Recommendation:** v0.3.0 Phase 4 (post-en.yml completion); build if `defaultContentLanguage != site.Language.Count == 1` OR add `params.language.switcher.enable` flag.
|
||||
|
||||
#### **8. RTL Support (Arabic, Hebrew)** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Unlocks RTL language markets
|
||||
- **Effort:** M (CSS `dir: rtl` attribute + bidirectional text tuning)
|
||||
- **Bundle cost:** ~100 B CSS (conditional rules)
|
||||
- **Why missing:** Not in product scope (Vietnamese-first); no demand signal yet
|
||||
- **Lighthouse concern:** RTL fonts + margin reversals require care; achievable without perf hit
|
||||
- **Recommendation:** v0.4.0+ only if expanding to multi-language monetization. Document override path for RTL users now.
|
||||
|
||||
#### **9. AVIF/WebP Image Processing** (Stack: ✓, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** Improved image delivery; future-proof format strategy
|
||||
- **Current tsuki:** Static images only; no render hook pipeline
|
||||
- **Effort:** M (1 render hook + Hugo `resources.Resize` + archetype example)
|
||||
- **Bundle cost:** 0 (build-time processing)
|
||||
- **Why missing:** Deferred pending cover-image feature scope decision
|
||||
- **v0.2.0 Evolution report:** Recommended for v0.3.0+
|
||||
- **Recommendation:** v0.3.0 Phase 2 (budget rebase + docs) if cover-image feature confirmed in scope. If not, defer to v0.4.0.
|
||||
|
||||
#### **10. Responsive Image Srcsets** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Adaptive image sizing for mobile/desktop; bandwidth savings
|
||||
- **Current tsuki:** Render hook adds `loading=lazy`; no srcset generation
|
||||
- **Effort:** M (1 render hook + Hugo image pipes)
|
||||
- **Bundle cost:** 0 (build-time)
|
||||
- **Lighthouse concern:** Improves CLS and LCP; high value
|
||||
- **Recommendation:** v0.3.0+ after AVIF decision. Can ship together.
|
||||
|
||||
#### **11. Multi-Author Bylines** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Team blogs; collaborative writing
|
||||
- **Current tsuki:** Single global author; JSON-LD author is hardcoded
|
||||
- **Effort:** M (per-post `authors: []` frontmatter + template logic)
|
||||
- **Bundle cost:** 0 (markup only)
|
||||
- **Why missing:** Solo-blogger focus; low demand signal
|
||||
- **Recommendation:** v0.4.0+ if audience demand justifies scope expansion.
|
||||
|
||||
#### **12. Custom Shortcodes** (Stack: ✓, PaperMod: ✗, tsuki: ✗)
|
||||
- **Stack includes:** gallery, video, tabs, columns, figures, admonitions
|
||||
- **tsuki includes:** None; callouts via native markdown only
|
||||
- **Effort:** M-L (per shortcode: 20–50 lines template + CSS)
|
||||
- **Bundle cost:** Varies; 1 shortcode ~100 B CSS
|
||||
- **Why missing:** Keep core lean; users can add via site overrides
|
||||
- **Recommendation:** v0.4.0+ document shortcode patterns in customization.md; ship 1–2 examples (gallery, tabs).
|
||||
|
||||
---
|
||||
|
||||
### Tier C: Out-of-Scope by Design
|
||||
|
||||
#### **13. Series / Subsection Routing** (Stack: ✓, tsuki: ✗)
|
||||
- **Impact:** Multi-part tutorials, book-like structure
|
||||
- **Effort:** L (Hugo section routing + archetype changes)
|
||||
- **Why missing:** Adds taxonomy complexity; blog posts are flat
|
||||
- **Recommendation:** Out-of-scope. Stack's subsection support is edge-case; most blogs use tags instead.
|
||||
|
||||
#### **14. KaTeX / Mermaid Shortcodes** (Stack: ✓, tsuki: ✗)
|
||||
- **Impact:** Math equations, diagrams
|
||||
- **Stack:** Built-in Mermaid, optional KaTeX
|
||||
- **tsuki v0.2.0 CHANGELOG:** "Deferred to post-0.1.0" — deliberate design choice
|
||||
- **Bundle cost:** Mermaid = 50+ KB gz; KaTeX = 40+ KB gz — incompatible with ≤4 KB CSS budget
|
||||
- **Recommendation:** **Intentional defer.** Document override path: users can add via Hugo Modules or site-level content adapters. Do not ship in core.
|
||||
|
||||
#### **15. Email Newsletter Signup** (Stack: ✗, PaperMod: ✗, tsuki: ✗)
|
||||
- **Impact:** Audience capture; monetization
|
||||
- **Effort:** M (form partial + privacy compliance)
|
||||
- **Why missing:** Not a theme responsibility; requires external service (ConvertKit, Substack, etc.)
|
||||
- **Recommendation:** Out-of-scope. Document as customization example in docs/customization.md.
|
||||
|
||||
#### **16. Disqus / Utterances Comments** (Stack: ✓, PaperMod: ✓, tsuki: ✗)
|
||||
- **Impact:** Alternative comment systems for non-GitHub audiences
|
||||
- **Current tsuki:** Giscus only (GitHub Discussions)
|
||||
- **Effort:** M (1 partial per provider; ~30 lines each)
|
||||
- **Bundle cost:** 0 (embed-only)
|
||||
- **Why missing:** Giscus is modern default; Disqus declining (privacy concerns); Utterances niche
|
||||
- **Recommendation:** v0.4.0+ if user demand. Document override path now (copy `_partials/comments.html`, swap Giscus for custom provider).
|
||||
|
||||
---
|
||||
|
||||
## 2026 Blog+Portfolio Feature Baseline
|
||||
|
||||
Based on industry survey (Stack, PaperMod, Anatole, Hello Friend NG), **must-have** features for credible blog+portfolio themes:
|
||||
|
||||
| Feature | Must-Have | Nice-to-Have | Rationale |
|
||||
|---------|-----------|--------------|-----------|
|
||||
| Blog (posts + archive) | ✓ | — | Table stakes |
|
||||
| Tags/categories | ✓ | — | Discovery |
|
||||
| Full-text search | ✓ | — | UX expectation |
|
||||
| Dark mode | ✓ | — | 2026 standard |
|
||||
| TOC (auto) | ✓ | — | Long-form reading |
|
||||
| Portfolio/projects grid | ✓ | — | Personal brand |
|
||||
| Comments (any) | ✓ | — | Engagement |
|
||||
| SEO metadata (OG, schema) | ✓ | — | Distribution |
|
||||
| Mobile responsive | ✓ | — | Baseline |
|
||||
| Code syntax highlighting | ✓ | — | Dev blogs |
|
||||
| Related posts | ✓ | — | Engagement |
|
||||
| Social icons | ✓ | — | Personal brand |
|
||||
| Responsive images | ✓ | — | Lighthouse |
|
||||
| **Prev/next nav** | — | ✓ | Post flow (common) |
|
||||
| **Breadcrumbs** | — | ✓ | UX clarity (common) |
|
||||
| **Code copy button** | — | ✓ | UX polish (emerging) |
|
||||
| Image gallery/lightbox | — | ✓ | Niche (photographers) |
|
||||
| RTL support | — | ✓ | Localization (niche) |
|
||||
| Multi-author | — | ✓ | Teams only |
|
||||
| Newsletter signup | — | ✓ | Monetization (opt-in) |
|
||||
| KaTeX/Mermaid | — | ✓ | Niche (technical) |
|
||||
|
||||
**tsuki baseline alignment:** ✓ All must-haves shipped through v0.2.1. No critical gaps.
|
||||
|
||||
---
|
||||
|
||||
## Lighthouse Implications
|
||||
|
||||
### Negative Impact Risk (Missing Features That Reduce Scores If Implemented Poorly)
|
||||
|
||||
| Feature | Lighthouse Metric | Risk | Mitigation |
|
||||
|---------|-------------------|------|-----------|
|
||||
| **Image gallery** | CLS, LCP | Unoptimized thumbs cause layout shift | Lazy-load + fixed aspect ratio |
|
||||
| **Custom shortcodes** | CSS weight | Feature creep → bundle bloat | Strict budget enforcement (Phase 2) |
|
||||
| **Prev/next nav** | — | None (markup-only) | Safe to ship |
|
||||
| **Code copy button** | INP | JS click handler bloat | Use IntersectionObserver; defer hydration |
|
||||
| **Newsletter form** | CLS | Embed framework weight | Use vanilla JS only; validate bundle impact |
|
||||
|
||||
**Recommendation:** Any feature added post-v0.3.0 must pass smoke-test: CSS ≤4 KB gz per page kind, JS ≤1 KB gz aggregate.
|
||||
|
||||
---
|
||||
|
||||
## Recommendations Ranked by Priority
|
||||
|
||||
### Must-Ship v0.3.0 (P1)
|
||||
|
||||
1. **Language switcher + en.yml complete** — Phase 3 author UX + Phase 4 audit
|
||||
2. **llm.txt generation** — Phase 5 (already planned)
|
||||
3. **Breadcrumbs (optional, gated)** — Phase 3 author UX
|
||||
4. **Code copy button (optional, gated)** — Phase 3 author UX
|
||||
|
||||
### Consider v0.3.0 (P2, if budget allows)
|
||||
|
||||
1. **Prev/next post nav** — Zero-friction addition; improves discoverability
|
||||
2. **AVIF render hook + docs** — If cover-image feature confirmed in scope
|
||||
3. **Speculation Rules prefetch** — Already planned in Phase 5
|
||||
|
||||
### Defer to v0.4.0 (P3)
|
||||
|
||||
1. Image gallery / lightbox (bundle implications)
|
||||
2. Image zoom on hover
|
||||
3. Scroll-to-top button
|
||||
4. Custom shortcodes (tabs, columns, video)
|
||||
5. RTL support (audience expansion decision)
|
||||
6. Multi-author bylines
|
||||
7. Alternative comment systems (Disqus, Utterances)
|
||||
|
||||
### Out-of-Scope (By Design)
|
||||
|
||||
1. Series/subsection routing (low ROI)
|
||||
2. KaTeX/Mermaid (intentional defer; users add via modules)
|
||||
3. Email newsletter (out-of-theme responsibility)
|
||||
|
||||
---
|
||||
|
||||
## Feature Parity Summary
|
||||
|
||||
**tsuki v0.2.1 achieves parity with Stack/PaperMod on:**
|
||||
- Blog infrastructure (posts, tags, archives, search, related posts)
|
||||
- Portfolio surface (projects grid, social links, profile)
|
||||
- SEO (JSON-LD, OG, Twitter cards)
|
||||
- Comments (Giscus)
|
||||
- i18n (vi + en; missing UI switcher and RTL, but core infrastructure ready)
|
||||
- Performance (responsive images, lazy-load, View Transitions API — exceeds Stack on API adoption)
|
||||
- Customization (CSS tokens, icon overrides, partial override paths)
|
||||
|
||||
**tsuki distinguishes itself on:**
|
||||
- **Zero build step** — pure Hugo + browser ES modules (matches PaperMod philosophy; exceeds Stack complexity)
|
||||
- **Pagefind search** (superior Vietnamese diacritic handling vs. Fuse.js)
|
||||
- **View Transitions API** (unique among blog themes; forward-compatible)
|
||||
- **CSS budget discipline** — 4 KB gz hard limit (competitors don't enforce; tsuki does)
|
||||
- **Vietnamese typography** — purpose-built for diacritics + tone marks
|
||||
|
||||
**tsuki lags on:**
|
||||
- Breadcrumbs, prev/next nav (low-effort, ship v0.3.0+)
|
||||
- Code copy button (low-effort, ship v0.3.0+)
|
||||
- Image gallery shortcode (niche; defer indefinitely without demand)
|
||||
- RTL support (audience expansion question)
|
||||
- Shortcode ecosystem (intentional; users override)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Path: v0.3.0 + v0.4.0
|
||||
|
||||
### v0.3.0 (Committed)
|
||||
- Phase 3 (Author UX): Breadcrumbs, code copy, prev/next nav as optional `params.*` flags
|
||||
- Phase 3: en.yml completion + language switcher partial (if routing logic complete)
|
||||
- Phase 5 (AI/discovery): llm.txt generation
|
||||
- Phase 4 (a11y): WCAG 2.2 audit (no new features, but validates surface)
|
||||
- Phase 2 (Budget rebase): Free ~1.2 KB gz headroom for above features
|
||||
|
||||
### v0.4.0 (Consider)
|
||||
- AVIF render hook + responsive srcsets (post-cover-image scope decision)
|
||||
- Image gallery shortcode (proof-of-concept, lightweight alternative to PhotoSwipe)
|
||||
- Basic custom shortcodes (tabs, figures; <200 B CSS each)
|
||||
- RTL support toggle (if multi-language demand justifies)
|
||||
- Scroll-to-top button
|
||||
- Alternative comment system overrides (Disqus, Utterances examples)
|
||||
|
||||
---
|
||||
|
||||
## Unresolved Questions
|
||||
|
||||
1. **Cover-image feature scope for v0.2.0–v0.3.0:** Does tsuki ship cover image processing (Hugo pipes + AVIF) in v0.3.0, or defer indefinitely? Drives AVIF render hook timing.
|
||||
- *Impact:* If deferred, AVIF slides to v0.4.0+; if confirmed, can ship in v0.3.0 Phase 2.
|
||||
|
||||
2. **Language switcher routing:** Can en.yml phase complete without language switcher UI, or is switcher a blocker?
|
||||
- *Impact:* Affects Phase 3 effort estimate; if blocked on Phase 4 a11y, may slip to v0.4.0.
|
||||
|
||||
3. **Breadcrumbs schema inclusion:** Should breadcrumb partial auto-emit BreadcrumbList schema.org JSON-LD, or markup-only?
|
||||
- *Impact:* If schema required, add ~30 lines template logic; if markup-only, trivial.
|
||||
|
||||
4. **Code copy button accessibility:** Should copy button hide when `navigator.clipboard` unavailable (HTTP), or always show with fallback UI feedback?
|
||||
- *Impact:* If fallback, adds ~50 B js error-handling logic; if hide, simpler.
|
||||
|
||||
5. **Stack/PaperMod future drift:** Are Stack v4.0+ or PaperMod planning major features (e.g., AI chat, embedded analytics) that justify expanded tsuki roadmap?
|
||||
- *Impact:* May inform whether tsuki should pursue shortcode ecosystem or stay lean.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- [tsuki README & CHANGELOG](https://github.com/tiennm99/tsuki/)
|
||||
- [tsuki v0.3.0 Plan](https://github.com/tiennm99/tsuki/plans/260510-0144-tsuki-v0.3.0/)
|
||||
- [Prior research: Hugo Theme Evolution 2026](https://github.com/tiennm99/tsuki/plans/reports/researcher-260510-0144-hugo-theme-2026-evolution.md)
|
||||
- [Hugo Theme Stack GitHub](https://github.com/CaiJimmy/hugo-theme-stack)
|
||||
- [Hugo PaperMod Wiki Features](https://github.com/adityatelange/hugo-PaperMod/wiki/Features)
|
||||
- [Anatole Theme](https://github.com/lxndrblz/anatole)
|
||||
- [Hello Friend NG GitHub](https://github.com/rhazdon/hugo-theme-hello-friend-ng)
|
||||
- [WCAG 2.2 Standard](https://www.w3.org/TR/WCAG22/)
|
||||
- [Pagefind Search Docs](https://pagefind.app)
|
||||
- [Hugo Render Hooks](https://gohugo.io/render-hooks/images/)
|
||||
|
||||
---
|
||||
|
||||
**Status:** DONE
|
||||
**Summary:** tsuki v0.2.1 achieves feature parity with Stack/PaperMod on all essential blog+portfolio dimensions. Missing features split into three tiers: A (nice-to-have, v0.3.0 ready), B (medium effort, v0.4.0+), C (out-of-scope by design). No critical gaps exist. v0.3.0 scope should prioritize breadcrumbs, code copy, prev/next nav, language switcher, and llm.txt — all low-effort additions that respect the ≤4 KB CSS budget. Image gallery, RTL, and shortcodes defer to v0.4.0 or remain intentionally out-of-scope per tsuki's lightweight philosophy.
|
||||
Reference in New Issue
Block a user