A-Znk Blog was designed around a topic-based knowledge network and articles that remain comfortable to read at length. Borrowing the organizational approach of Apple’s Human Interface Guidelines,1 this manual follows Overview → Foundations → Patterns → Components. An equivalent Markdown edition is available at /en/design.md. The source of this document is the implemented experience, existing runtime boundaries, and design contracts captured in tests.2
Overview
Two decisions shape the blog: organize the site around topics, and make article pages primarily serve reading. The site’s design has developed around those priorities.
| Design principle | How it appears in the blog |
|---|---|
| Clarity | Topic-first navigation, one primary task on article pages, and supporting information placed beside the text |
| Consistency | Clear responsibilities for the discover and reading runtimes, with shared tokens and component families |
| Deference | Hover effects, animation, and comments remain subordinate to the content |
These principles are already embodied in the site’s structure. As details evolve, I want changes to happen within this framework rather than discard it.
Foundations
Color
The color system is organized around semantic tokens such as page, surface, text, border, accent, and reading, which are consumed by different runtimes. The shared interface starts with neutrals: a light-gray page, white cards, and dark-gray text. Blue identifies links, buttons, and status feedback, while paper, code, and notices retain the tones their roles require.
In discover, light-gray pages and white cards form the light-mode hierarchy; dark mode separates deep graphite backgrounds from slightly lighter cards. Static blue and amber glows and a fine dot pattern remain in the background, with the homepage’s warm glow becoming purple in dark mode. Solid cards keep text legible, while translucency is reserved for the header.
In reading, the article still resembles an independent sheet of paper. Light mode retains warm paper tones; dark mode preserves a distinction between paper and ink. Body text, contents, marginalia, and comments each have a place. Links, progress indicators, and buttons use blue emphasis without making reading depend on large areas of brand color.
Typography
Fonts are assigned by task. Navigation, buttons, metadata, and discovery-page headings use system interface fonts. Apple devices favor the system font and PingFang, keeping the tool layer clear and familiar. Long-form text uses the reading-oriented serif pairing of Source Serif 4 and Noto Serif SC.
The homepage and discovery pages establish hierarchy through size, weight, and spacing. I retained the code-like research signature: research.ts lists research tracks, paths to notes and papers, and real content counts. It uses monospace text inside one native disclosure panel, expanded on desktop and collapsed on narrow screens.
Each layer needs an appropriate voice. The body should feel steady and readable; the table of contents and rail should be light without becoming weak; the homepage needs a focal point without overpowering the content.
Dark mode
The theme switch cycles through three states: system → light → dark. The preference is stored in localStorage, and the resolved theme is applied early in page loading to prevent a light-to-dark or dark-to-light flash.1
Dark mode uses deep graphite for the page, slightly brighter cards, and adjusted text and blue interaction colors. It shares layout and semantic tokens with light mode, maintaining the same hierarchy. Article text has its own paper tones for sustained reading. Following a dark system theme and manually selecting dark mode should produce the same palette.
Patterns
Content architecture
The blog has four content collections: posts, topics, concepts, and papers. Articles remain the main reading material, situated within a network of topics and concepts. Topics express problem domains; concepts describe local terms or methods; articles connect them as readable nodes. Papers are presented as a separate collection of research outputs.
Accordingly, the homepage does more than list recent posts. It begins with areas of interest, then offers selected writing and recent updates. Topic pages bring introductory paths, related articles, and concepts together. Concept pages lead back to the articles and topics that reference them. Readers can move between problems, concepts, and articles instead of only proceeding by date.
Search follows the same model. Its index brings articles, topics, concepts, and papers into one result set. Readers often remember a problem domain or keyword before they remember an article’s title.
Reading architecture
The discover runtime helps a reader find a useful problem domain; reading sustains the rhythm of an article. Article pages have three parts: the table of contents on the left, the heading and body in the center, and the scholar rail on the right. This separates navigation, the main narrative, and supplementary material by information density.
Paragraph anchors provide the infrastructure. Each eligible paragraph receives a location ID. GFM footnotes become explanatory notes or references, then appear in the right-hand rail near their first occurrence.3 Supporting material follows the argument without repeatedly breaking up the body.
The current comment system uses Waline at the end of the article.4 Paragraph anchors continue to support the table of contents, marginalia, and footnotes, while comments provide whole-article discussion without interrupting the main reading path.
Interaction
Interactions should provide feedback without becoming intrusive. The header changes between top, compact, and hidden states as the reader scrolls. Search is accessible by keyboard shortcut, the theme control stays in place, and the back-to-top button appears when useful. Tools remain available while generally staying out of the way.
The homepage’s areas-of-interest section adds rhythm to browsing without turning content into an advertising carousel. On desktop, a four-card viewport can move using buttons, arrow keys, or the mouse wheel. Mobile layouts return to a more direct one- or two-column arrangement. The effect comes from movement through content rather than elaborate animation.
All movement must respect prefers-reduced-motion. With reduced motion enabled, the page should remain complete, stable, and readable. This applies to reveals, header transitions, card feedback, and the research-signature cursor. Background glows remain static and serve only to establish color layers.
Components
Discover shell
The discovery component family gives non-article pages a shared language. DiscoverShell owns the environmental layer and main container. PageHero provides the opening for each page. SectionHead establishes recurring points of rhythm within the content.
Topics, concepts, author pages, and archives contain different material, yet should feel like parts of the same site. The pages vary while their family resemblance remains stable.
Cards and covers
Cards organize information into units that readers can scan, pause over, and open. Hover feedback is largely confined to edges, shadows, and a slight lift, keeping attention on the material.
PostCover handles both manually supplied and fallback covers, with a shared ghost + main image structure. The main image provides clear boundaries; the ghost layer spreads color and atmosphere around it. Homepage features, article cards, and archive tiles can therefore share one visual family without reinventing their cover treatment.
Table of contents and scholar rail
The table of contents is part of the reading instrument. On desktop, TocSidebar emphasizes section hierarchy and the reader’s current location. On mobile, the same heading data becomes a lighter collapsible list.
PostScholarRail moves figures, notes, citations, and references beside the body while keeping their relationships traceable. It adapts the marginalia of scholarly writing to the browser. For long-form knowledge writing, this can be more effective than repeatedly inserting large explanatory panels into the text.
Waline comments
WalineComments places the third-party commenting system behind a clear boundary. Article pages provide a path and a mounting point. The wrapper handles theme integration, error fallback, missing configuration, and initialization failures.
The comment system can then be replaced, extended, or temporarily unavailable without becoming part of the article’s essential rendering chain. Comments add to the reading experience without putting access to the text at risk.
Spoilers
Spoilers let authors hide material until a reader chooses to reveal it. They can contain answers, Easter eggs, implementation details, or a supplementary conclusion that would otherwise interrupt the reading sequence.
A block spoiler in Markdown looks like this:
:::spoiler[Ending spoiler]
A whole block of hidden content.
:::
For a short phrase, use :spoiler[Hide this sentence for now]. Without a title, a block spoiler becomes a black mask without visible label text, while retaining an accessible label.
Stating immediately would change the rhythm of this passage. Hiding it lets the reader choose when to reveal it.
Ending spoiler
One of this blog’s most consequential decisions is the explicit separation between
discoverandreading. The former helps readers find a problem domain; the latter maintains a steady reading experience.
- Spoiler blocks can contain paragraphs, lists, quotations, and code.
- Version 1 does not allow headings, footnotes, or nested spoilers inside them.
Guidelines
Do:
- Respect runtime boundaries before refining individual pages.
discoverandreadinghave different responsibilities. - Express colors, surfaces, borders, and emphasis through semantic tokens before adding local styles.
- Keep the table of contents, anchors, footnotes, and scholar rail on the same location chain.
- Make interaction serve browsing and reading rather than create another competition for attention.
- Encapsulate third-party capabilities behind boundaries, as with Waline, so their failure does not affect the article itself.
Don’t:
- Bypass shared tokens or runtime constraints for an isolated page effect.
- Fill article bodies with comment threads and explanatory panels again.
- Loosen heading, anchor, or footnote rules casually: the contracts for both the table of contents and rail would drift.
- Copy the homepage’s visual language everywhere without considering content density and reading tasks.
Looking ahead
The next refinements follow the same direction: make discover a more navigable knowledge map and reading a page worth staying with. Whether the work strengthens search, expands author and archive pages, or improves the experience around Waline, the priorities remain content organization, reading rhythm, and clear boundaries.
References
The following sources influenced this manual’s organization, approach to reading, and comment-system boundaries.
Footnotes
Comments
Share a thought about the article, add a reading suggestion, or ask a follow-up question.