hakula139 · hakula139 · May 10, 2026 · May 9, 2026 · May 9, 2026 · May 9, 2026
diff --git a/.cspell/words.txt b/.cspell/words.txt
@@ -1,4 +1,6 @@
 autoplay
+bangumi
+bilibili
 cachix
 callout
 calt
@@ -9,6 +11,7 @@ elif
 endfor
 endif
 ensp
+fediverse
 fontawesome
 fontsource
 giscus
@@ -21,12 +24,15 @@ inlines
 jetbrains
 katex
 kwargs
+listenbrainz
 lqip
 maple
 materialised
 menlo
+metabrainz
 minijinja
 ndash
+neodb
 netease
 neue
 nixfmt

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,6 +4,8 @@
 
 IgnIt is a kiln theme built with Tailwind CSS v4, inspired by Hugo LoveIt. It provides MiniJinja templates, compiled CSS, and JS assets for [kiln](https://github.com/hakula139/kiln) sites.
 
+User-facing reference lives in [`README.md`](./README.md) and [`docs/`](./docs/). This file is contributor-only context for working on the theme itself: file-tree navigation, build pipeline, conventions, and decisions that don't fit in commit history.
+
 ### Theme Structure
 
 All assets live under a single `static/` tree. Files and directories whose names start with `_` are private build inputs — kiln's `copy_static` skips them when publishing the site.
@@ -31,17 +33,21 @@ All assets live under a single `static/` tree. Files and directories whose names
 │   │   │   │   ├── embed/
 │   │   │   │   │   └── apple-music.css     # Apple Music embed light / dark toggle
 │   │   │   │   ├── layout/
+│   │   │   │   │   ├── error-page.css      # .back-home-link (404 page back-to-home pill)
 │   │   │   │   │   ├── float-buttons.css   # .float-btn shared base + .back-to-top, .jump-to-comments stack
 │   │   │   │   │   ├── glass-panel.css     # .glass-panel, .glass-glow, [data-glow-target], .header-nav, .site-footer
 │   │   │   │   │   ├── header.css          # .header-logo, .header-link, .header-icon, .header-mobile-*, menu animations
 │   │   │   │   │   ├── print.css           # @media print overrides (hide chrome, clean typography)
 │   │   │   │   │   └── skip-link.css       # .skip-link visually hidden, focus-promoted accessibility anchor
 │   │   │   │   ├── listing/
-│   │   │   │   │   ├── home-card.css       # .home-card-*, .profile-avatar, .text-card-*
+│   │   │   │   │   ├── home-card.css       # .home-card-*, .profile-*, .text-card-*
 │   │   │   │   │   ├── listing.css         # .year-heading, .tag-pill, .category-card, .post-entry-*
 │   │   │   │   │   └── pagination.css      # .pagination-link, .pagination-ellipsis, .pagination-input
-│   │   │   │   └── search/
-│   │   │   │       └── search.css          # Pagefind trigger, modal, and result theming
+│   │   │   │   ├── search/
+│   │   │   │   │   └── search.css          # Pagefind trigger, modal, and result theming
+│   │   │   │   └── shared/
+│   │   │   │       ├── fa-icon.css         # @utility fa-icon — Font Awesome glyph setup for ::before / ::after
+│   │   │   │       └── icon-button.css     # @utility icon-tap-hover — circular tinted hover for icon surfaces
 │   │   │   ├── fonts.css                   # @font-face for Inter Variable + Maple Mono
 │   │   │   └── main.css                    # Entry: tokens, dark mode, partial imports
 │   │   └── style.css                       # Compiled Tailwind output (shipped)
@@ -101,12 +107,7 @@ Source CSS lives in `static/css/_src/` using Tailwind CSS v4 conventions:
 
 ### Design Tokens
 
-Defined in `@theme { ... }` in `main.css`. Custom properties follow these prefixes:
-
-- `--color-*` — colors (bg, text, link, border, card, selection)
-- `--radius-*` — border radii
-- `--shadow-*` — box shadows
-- `--surface-*` — glass surface fills, borders, and overlays
+Defined in `@theme { ... }` in `main.css`, with parallel dark-mode overrides under `[data-theme='dark']`. The public namespaces and override pattern are documented in [`docs/customization.md`](./docs/customization.md#visual-tokens).
 
 ### Component Classes vs. Inline Utilities
 
@@ -140,16 +141,13 @@ The theme paints kiln's `lqip_uri` via the `<span class="lqip">` wrapper kiln em
 
 - **Body images**: auto-wrapped by kiln. No template work.
 - **Featured images** (`templates/post.html` banner, `templates/home.html` cards): templates emit the wrapper themselves, gated on `{% if featured_image.lqip_uri %}`. Per-context size overrides (`.post-banner-media .lqip`, `.home-card > .lqip`) live in `lqip.css`.
-- **Body background** (`config.params.background`): hand-rolled in `base.html`. Sites supply `image` + `lqip_uri` (a pre-computed data URI); the wrapper pins fixed-fullscreen with `object-fit: cover`, and `position` / `position_mobile` drive `object-position` via `--bg-position*` CSS vars.
+- **Body background** (`config.params.background`): hand-rolled in `base.html`. The wrapper pins fixed-fullscreen with `object-fit: cover`, and `position` / `position_mobile` drive `object-position` via `--bg-position*` CSS vars. The user-facing config schema is in [`docs/parameters.md`](./docs/parameters.md#paramsbackground).
 
 ## Internationalization
 
-Translation tables live under `i18n/<lang>.toml` (`en`, `zh-Hans`); active language is set by `config.language` in the consuming site. Access:
-
-- **Templates** (MiniJinja): `t('key')`.
-- **Client JS**: `data-i18n-*` attributes on the document root.
+Translation tables live under `i18n/<lang>.toml` (`en`, `zh-Hans`); active language is set by `config.language` in the consuming site. Templates read keys via MiniJinja's `t('key')`; client JS reads `data-i18n-*` attributes on the document root and on per-element carriers.
 
-Sites can layer overrides via a same-named TOML at their root's `i18n/<lang>.toml`, merged key-by-key. Per-key lookup falls back: **site override → theme translation → theme English**.
+The site / theme / English fallback chain and the full key reference are in [`docs/i18n.md`](./docs/i18n.md). When adding a new template string, register the key in **both** `i18n/en.toml` and `i18n/zh-Hans.toml`, then add a row to the `docs/i18n.md` reference table so site authors can discover it.
 
 ## Webfonts
 

diff --git a/README.md b/README.md
@@ -45,6 +45,14 @@ IgnIt is a [kiln](https://github.com/hakula139/kiln) theme built with Tailwind C
 - Keyboard-accessible focus states (`:focus-visible`), skip-to-content link, semantic landmark regions
 - `prefers-reduced-motion` honored across animations and smooth-scroll
 
+## Documentation
+
+| Document                               | Description                                                                         |
+| -------------------------------------- | ----------------------------------------------------------------------------------- |
+| [Customization](docs/customization.md) | Override visual tokens, templates, social icons, comments, fonts, and static assets |
+| [Parameters](docs/parameters.md)       | `[params]` schema reference — defaults, types, where each value is rendered         |
+| [i18n](docs/i18n.md)                   | Translatable string reference — keys, English defaults, override pattern            |
+
 ## Installation
 
 Add IgnIt to your kiln site as a Git submodule:
@@ -61,115 +69,38 @@ theme = "IgnIt"
 
 `static/css/style.css` ships pre-built, so consuming sites don't need Node.js.
 
-## Configuration
-
-IgnIt provides default parameters that can be overridden in your site's `config.toml`.
+## Quick Start
 
-### Theme Parameters
+A minimal `config.toml` to get IgnIt running:
 
 ```toml
-[params]
-cdn = "https://cdn.jsdelivr.net/npm"     # CDN base URL for dependencies
-code_max_lines = 40                      # Max visible lines before code blocks scroll
-emojis = true                            # Enable emoji replacement
-fontawesome = true                       # Enable Font Awesome icon loading
-```
-
-### Background Image
-
-Set a fixed background image with glassmorphism content panels:
-
-```toml
-[params.background]
-image = "/images/bg.webp"                # Path to background image
-lqip_uri = "data:image/webp;base64,..."  # Pre-computed LQIP data URI (optional)
-position = "right center"                # CSS background-position (default: center)
-position_mobile = "60% center"           # Mobile background-position (default: position)
-```
-
-When unset, panels use solid backgrounds (the theme works without a background image).
-
-### Comments
-
-```toml
-[params.comments]
-enabled = true
-provider = "twikoo"                      # Currently the only built-in provider
-
-[params.comments.twikoo]
-api_url = "https://twikoo.example.com"
-```
-
-The dispatcher is provider-agnostic — additional providers (Giscus, Waline, etc.) drop in via a sibling partial under `templates/_partials/comments/`. The provider's CDN dep loads only when comments are enabled.
-
-### Footer
-
-```toml
-[params.footer]
-since = 2018                             # Copyright start year
-license = "CC BY-NC-SA 4.0"              # License name
-license_url = "https://creativecommons.org/licenses/by-nc-sa/4.0/"
-powered_by = true                        # Show "Powered by kiln & IgnIt"
-```
+theme = "IgnIt"
+title = "My Site"
+language = "en"
 
-### Home Profile
+[params]
+fontawesome = true
 
-```toml
 [params.home.profile]
 avatar = "/images/avatar.webp"
 title = "Site Title"
-subtitle = "A short tagline"
-```
-
-### Navigation Menu
+subtitle = "An optional tagline"
 
-```toml
 [[menu.main]]
 name = "Posts"
 url = "/posts/"
-icon = "fas fa-archive"                  # Font Awesome class (optional)
-weight = 1                               # Sort order (ascending)
+icon = "fas fa-archive"
+weight = 1
 
-[[menu.main]]
+[[menu.social]]
 name = "GitHub"
-url = "https://github.com/user"
-icon = "fab fa-github"
-weight = 10
-external = true                          # Opens in new tab
-```
-
-### Visual Effects (experimental)
-
-```toml
-[params.effects]
-cursor_glow = false                      # Cursor-tracking glow on glass panels
+url = "https://github.com/example"
+icon = "svg:github"
+weight = 1
+external = true
 ```
 
-Off by default. The `will-change` layers it injects clash with `backdrop-filter` compositing on Chromium / WebKit:
-
-- **Panel dropout during scroll** (frequent) — the glass panel may briefly vanish for a moment while scrolling.
-- **Phantom gap near `#comments`** (rare) — an in-page anchor jump close to the comments section can leave the article card with a much larger apparent gap than its real 32 px margin; the next manual scroll repaints.
-
-## Image Pipeline
-
-IgnIt paints kiln's `lqip_uri` (low-quality image placeholder, a base64-encoded WebP data URI) via the `<span class="lqip">` wrapper kiln emits around content images. The backdrop shows immediately on first paint; the inner image fades in once it decodes.
-
-- **Body images**: auto-wrapped by kiln. No site-level work.
-- **Featured images** (post banner, home cards): templates emit the wrapper themselves, gated on `featured_image.lqip_uri`.
-- **Body background** (`[params.background]`): supply a pre-computed `lqip_uri` alongside `image`. The wrapper pins fixed-fullscreen with `object-fit: cover`; `position` / `position_mobile` drive `object-position` via CSS variables.
-
-## Internationalization
-
-Translation tables live under `i18n/<lang>.toml` (`en`, `zh-Hans`); the active language follows `config.language` in the consuming site. Access:
-
-- **Templates** (MiniJinja): `t('key')`.
-- **Client JS**: `data-i18n-*` attributes on the document root.
-
-Sites can layer overrides via a same-named TOML at their root's `i18n/<lang>.toml`, merged key-by-key. Per-key lookup falls back: **site override → theme translation → theme English**.
-
-## Webfonts
-
-Inter Variable (`--font-sans`) and Maple Mono Variable (`--font-mono`, with separate regular and italic faces) are self-hosted under `static/fonts/`. Both are fetched lazily on first use — Inter when any page text renders, Maple Mono when the first `<code>` appears. CJK falls through to system fonts (Sarasa Gothic SC, PingFang SC, Noto Sans CJK SC, etc.) via the `--font-sans` cascade.
+For the complete schema (`[params.background]`, `[params.comments]`, `[params.footer]`, `[params.section]`, `[params.effects]`) and the full menu field list, see [Parameters](docs/parameters.md). For visual customization, social icon overrides, comment provider wiring, and other extension patterns, see [Customization](docs/customization.md).
 
 ## Theme Development