Blog design system
Blog Mood Components Source

Docs Surfaces

Blog design system

The ink-wash design language of 無人之境 — one blue hue, foreground-derived greys, and a single reading column.

Overview

This is the design system for the blog zone (blog.buxx.me), a publication called 無人之境 (“no man’s land”). It is deliberately not harmonized with the main buxx.me hero/identity system — it is its own publication with its own voice. Everything is scoped under .blog-zone; nothing here may leak onto other routes.

The aesthetic is ink-wash: a near-monochrome greyscale field, one blue hue for all accents, and a single 720px reading column. Restraint is the brief — when in doubt, do less. The reference point was chl.ee’s calm, but the visuals were redesigned in this design language rather than ported.

Source of truth. The ink colours live in blogPalette (src/data/site.ts) and are emitted as CSS custom properties by BlogLayout.astro. Greys, type, and layout live in src/styles/blog.css. This file mirrors them — change the code, then sync the tokens here.

Colors

Two layers: greys derived from the theme foreground, and a three-shade blue ink set.

Greys are alpha, not hex. {colors.ink} … {colors.fill} are all hsl(var(--foreground) / α). Because they ride the theme foreground (black in light, white in dark), a single declaration produces both modes. Use them for all text and structure; never hardcode a grey.

The ink set is one hue, graded by depth. A monochrome publication should read as a single voice, so the accents are three blues — not blue plus a warm counter-colour. Each shade owns exactly one job, and the job is fixed by WCAG contrast against the surface it sits on:

  • {colors.dai} — primary. Links, table-of-contents progress, focus rings, hover. The greyed slate-blue shanshui painters dilute to push a ridge into the haze. Text-safe in both modes (6.84:1 / 7.99:1).
  • {colors.dian} — the mark. The “Not by AI” pledge and the author byline. A deep, concentrated indigo — the firmest blue on the page, because it stands for the human behind the work. Text-safe in both modes (10.27:1 / 8.22:1).
  • {colors.ji} — highlight, fill only. The pale “sky after rain” wash for emphasis on the reading surface. (Blog search now lives in the site-wide ⌘K palette, which uses its own neutral mark, so ji is a reserved reading-zone fill rather than a search-hit colour.) It measures 3.57:1 on the light surface, so it fails AA as text — it may only ever be a background wash, never a foreground colour. The constraint picks the role.

Surfaces. {colors.surface.dark} is #0A0A0A, not #000: pure black smears on OLED during scroll, and white text on it hits 21:1, which haloes in long-form reading. The near-black keeps the lights-off feel without the artifacts.

Typography

Body copy reads in Inter via the global .reading contract — content surfaces opt in and inherit the family without re-declaring it. Code uses the mono stack. SiteWordmark.astro renders the shared publication lockup from a 2.6 KB WenKai subset containing 無人之境, sillage, and its separators. The family is named only by that component, so it does not leak into body text.

Sizes step in a clear hierarchy: {typography.masthead} for the wordmark, then {typography.article-h1} → {typography.article-h2} → {typography.article-h3} inside a post, {typography.body} for prose (a generous 1.85 line-height for reading), and the muted scale ({typography.excerpt}, {typography.meta}, {typography.eyebrow}, {typography.tag}) for index and chrome. Negative letter-spacing tightens the large display sizes; body copy gets a hair of positive tracking for screen legibility.

Layout

One column, one width. {layout.measure} (720px) is the reading measure — every shell caps here and centres. Shell padding is {layout.shell-padding} (generous top, comfortable sides, deep floor so the last post never kisses the viewport edge).

Vertical rhythm follows the spacing scale: {spacing.sm} inside a group, {spacing.lg} between groups, {spacing.section}+ between sections. The zone drops the site’s ambient dot-grid background — chl.ee is a flat surface, so this is too.

Elevation & Depth

There is no elevation. The zone is intentionally flat — no drop shadows, no raised cards floating over the page. Depth is expressed two ways only:

  • Hairlines ({colors.line}) and spacing separate content. Prefer whitespace to a divider; reach for {components.divider} only when grouping genuinely needs a line.
  • Image edges use a 1px inset hairline ({layout.image-edge.light} / {layout.image-edge.dark}) in pure black/white — NOT the tinted foreground neutral, which would pick up the surface beneath and read as dirt on the photo.

The one motion affordance is the sliding hover pill ({colors.fill} at {rounded.pill}) that springs to hug the hovered list row.

Shapes

Corner radii are a small fixed set: {rounded.inline} for inline code, {rounded.image} for media, {rounded.card} for cards and panels, {rounded.pill} for tags and round controls. Single-sided or borderless surfaces use {rounded.none} — a rounded corner only belongs on a full border.

Components

Components compose the tokens above; they never introduce new colour or type.

  • {components.link} / {components.post-item} — text in {colors.ink}, links and interaction in {colors.dai}. On hover a row gets {components.post-item-hover} (the {colors.fill} pill).
  • {components.tag-pill} — {colors.dai} text on a 12% {colors.dai} wash. A tag may override its own accent via --tag-accent; absent that, it falls back to {colors.dai}.
  • {components.not-by-ai} — the pledge trigger and byline, in {colors.dian}. This is the only place the deepest ink appears, by design.
  • {components.search-mark} — reserved. Blog full-text search (Pagefind) now renders inside the site-wide ⌘K palette, which owns its own neutral highlight; the blog zone no longer draws its own search mark.
  • {components.callout} / {components.inline-code} — quiet {colors.fill} surfaces at card / inline radius.

Do’s and Don’ts

  • Do keep every accent inside the blue ink set. If a new surface needs an accent, it is {colors.dai} unless it is specifically the human mark ({colors.dian}) or a highlight wash ({colors.ji}).
  • Do derive greys from {colors.ink}’s alpha scale, so both modes stay in sync for free.
  • Do confirm any new text/background pair clears WCAG AA 4.5:1 in both modes before shipping it.
  • Don’t use {colors.ji} as a text or icon colour — it fails AA on the light surface. Fill only.
  • Don’t add a warm or second-hue accent (red, amber, green). The publication is monochrome on purpose; a counter-colour breaks the voice.
  • Don’t introduce drop shadows or raised cards. Separate with whitespace and hairlines.
  • Don’t use pure #000 for the dark surface, or full-opacity dividers.
  • Don’t let any blog token leak outside .blog-zone, and don’t pull the main-site identity tokens in.

Token reference

The normative values. These mirror the live system — blogPalette in src/data/site.ts owns the inks, src/styles/blog.css owns the greys and layout. Edit the code first, then sync this block.

YAML
name: 無人之境 — blog design system
version: alpha
description: >
  The calm, ink-wash visual zone for the blog at blog.buxx.me. A single blue
  hue graded by depth, near-black greys derived from the theme foreground, and a
  720px reading column. Blog styling stays under .blog-zone; only the shared
  publication lockup is also rendered in the homepage Writing doorway.

colors:
  # Surfaces — the page floor in each mode. Dark is near-black, never #000.
  surface.light: '#FFFFFF'
  surface.dark: '#0A0A0A'

  # Greys — NOT fixed hex. Expressed as the theme foreground at alpha, so one
  # declaration yields the calm light palette and a tuned dark variant for free.
  ink: 'hsl(var(--foreground))'           # 100% — titles, strong text
  body: 'hsl(var(--foreground) / 0.78)'   # article body copy
  muted: 'hsl(var(--foreground) / 0.58)'  # list excerpts
  faint: 'hsl(var(--foreground) / 0.42)'  # dates, meta, year ticks
  line: 'hsl(var(--foreground) / 0.10)'   # hairline dividers
  fill: 'hsl(var(--foreground) / 0.045)'  # sliding hover pill

  # Ink set — one hue, three depths. Source of truth: blogPalette in site.ts.
  # The mode-agnostic token is the live CSS var components consume; the
  # .light/.dark entries below document the concrete value resolved in each mode.
  dai: 'var(--blog-dai)'
  dian: 'var(--blog-dian)'
  ji: 'var(--blog-ji)'
  dai.light: '#3C5D80'    # Distant-mountain ink — primary. WCAG 6.84:1 on surface.light
  dai.dark: '#7FA8D6'     #            WCAG 7.99:1 on surface.dark
  dian.light: '#27406E'   # Indigo ink — the mark. WCAG 10.27:1 on surface.light
  dian.dark: '#6FA8FF'    #            WCAG 8.22:1 on surface.dark
  ji.light: '#3E8BD8'     # Clear-sky blue — highlight FILL only. 3.57:1 — never text
  ji.dark: '#6FB2F2'      #            WCAG 8.79:1 on surface.dark

typography:
  # Families. Body reads in Inter (the .reading contract); code in the mono
  # stack; the publication lockup uses a tiny WenKai subset for its Chinese sillage.
  family.sans: "'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif"
  family.mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
  family.display: "'WenKai Lockup', 'Songti SC', 'Noto Serif CJK SC', serif"

  masthead:     { fontFamily: '{typography.family.display}', cjkSize: '50px', latinSize: '20px', lineHeight: '1', cjkLetterSpacing: '0.10em', fontWeight: 400 }
  article-h1:   { fontFamily: '{typography.family.sans}', fontSize: 'clamp(27px, 4.4vw, 34px)', lineHeight: '1.3', letterSpacing: '-0.02em', fontWeight: 600 }
  article-h2:   { fontFamily: '{typography.family.sans}', fontSize: '22px', lineHeight: '1.4', letterSpacing: '-0.01em', fontWeight: 600 }
  article-h3:   { fontFamily: '{typography.family.sans}', fontSize: '19px', lineHeight: '1.45', fontWeight: 600 }
  body:         { fontFamily: '{typography.family.sans}', fontSize: '17.5px', lineHeight: '1.85', letterSpacing: '0.003em', fontWeight: 400 }
  post-title:   { fontFamily: '{typography.family.sans}', fontSize: '19px', lineHeight: '1.45', letterSpacing: '-0.012em', fontWeight: 500 }
  excerpt:      { fontFamily: '{typography.family.sans}', fontSize: '15px', lineHeight: '1.55', fontWeight: 400 }
  meta:         { fontFamily: '{typography.family.sans}', fontSize: '13px', lineHeight: '1.4', fontWeight: 400 }
  eyebrow:      { fontFamily: '{typography.family.sans}', fontSize: '13px', letterSpacing: '0.02em', fontWeight: 500 }
  tag:          { fontFamily: '{typography.family.sans}', fontSize: '11.5px', lineHeight: '1', fontWeight: 500 }
  inline-code:  { fontFamily: '{typography.family.mono}', fontSize: '0.875em', fontWeight: 400 }

spacing:
  # 2px base, used as a calm 4px-ish rhythm. The named steps below are the ones
  # the zone actually reaches for.
  xs: '4px'
  sm: '8px'
  md: '12px'
  lg: '16px'
  xl: '24px'
  section: '40px'
  floor: '96px'

rounded:
  none: '0'        # single-sided / borderless surfaces (mobile list rows)
  inline: '6px'    # inline code, kbd, small chips
  image: '10px'    # media corners
  card: '12px'     # cards, callouts, share row, subscribe panel
  pill: '999px'    # tag pills, sliding hover pill, round controls

layout:
  measure: '720px'           # the reading column — every shell maxes here
  shell-padding: '40px 24px 96px'
  image-edge.light: 'inset 0 0 0 1px rgba(0, 0, 0, 0.1)'
  image-edge.dark: 'inset 0 0 0 1px rgba(255, 255, 255, 0.1)'

components:
  post-item:
    typography: '{typography.post-title}'
    textColor: '{colors.ink}'
    backgroundColor: 'transparent'
  post-item-hover:
    backgroundColor: '{colors.fill}'
    rounded: '{rounded.pill}'
  link:
    textColor: '{colors.dai}'
  tag-pill:
    typography: '{typography.tag}'
    textColor: '{colors.dai}'
    backgroundColor: 'color-mix(in srgb, {colors.dai} 12%, transparent)'
    rounded: '{rounded.pill}'
    padding: '4px 9px'
  search-mark:
    backgroundColor: 'color-mix(in srgb, {colors.ji} 26%, transparent)'
    textColor: 'inherit'
    rounded: '3px'
  not-by-ai:
    typography: '{typography.meta}'
    textColor: '{colors.dian}'
  callout:
    typography: '{typography.excerpt}'
    textColor: '{colors.body}'
    backgroundColor: '{colors.fill}'
    rounded: '{rounded.card}'
    padding: '16px 18px'
  inline-code:
    typography: '{typography.inline-code}'
    backgroundColor: '{colors.fill}'
    rounded: '{rounded.inline}'
    padding: '0.15em 0.4em'
  divider:
    backgroundColor: '{colors.line}'
    height: '1px'