Files

Brendan Chen b61cb986f1 feat: initial shared design system extracted from newerror

Foundation + chrome for the bchen.dev static sites: design tokens, Spectral /
Helvetica / IBM Plex Mono type, base + .prose typography, data-driven nav +
footer, and prefers-color-scheme + [data-theme] dark mode with a pre-paint
init. Colors are overridable CSS custom properties (defaults = newerror's
palette); each site sets only its own colors.css.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C96hwEU9cM7mJpqATiv7R5

2026-06-30 21:20:21 -04:00

3.9 KiB

Raw Blame History

static-design-system

Shared visual foundation for the bchen.dev static (Jekyll) sites. The canonical design is A New Error (newerror.bchen.dev) — Spectral serif body, Helvetica sans UI, IBM Plex Mono. Every site shares fonts, spacing, typography, nav/footer chrome, and light/dark behavior, and keeps only its own colors.

What's here

File	Purpose
`base.css`	Tokens, font stacks, base + `.prose` typography, `.nav`/`.foot` chrome, mobile menu, icon swaps. Colors are CSS custom properties with defaults; sites override them.
`theme-init.js`	Pre-paint theme read (inlined in `<head>`, no flash).
`theme-toggle.js`	Theme-toggle + mobile-menu behavior (served + loaded at end of body).
`head.html`	Shared `<head>` contents (meta/OG, fonts, CSS links, inlined theme-init).
`nav.html`	Data-driven nav + mobile menu.
`footer.html`	Shared footer.

Blog-specific components (ledger feed, archive, reader/prose-article chrome) are not here — they live in newerror's own repo.

Consuming it in a Jekyll site

This is designed for legacy GitHub Pages (Jekyll in safe mode: no custom plugins, no symlinks). The trick is to mount this repo as a submodule inside _includes/ and deliver CSS/JS through tiny served wrapper files.

Add the submodule at _includes/ds (use the read-only https URL — a legacy Pages build cannot fetch ssh submodules):
```
git submodule add https://gitea.bchen.dev/brendan/static-design-system.git _includes/ds
```
Serve the CSS — create assets/ds.css:
```
---
---
{% include ds/base.css %}
```

Serve the JS — create assets/ds.js:

---
---
{% include ds/theme-toggle.js %}

Add your palette — create assets/colors.css overriding only the color tokens (--bg --ink --muted --faint --rule --rule-2 --accent --accent-hover --field) for light, :root[data-theme="dark"], and the prefers-color-scheme: dark block. This loads after ds.css.

Nav links — create _data/nav.yml:

- title: Guides
  url: /guides
- title: FAQ
  url: /support

Layout — in _layouts/default.html:

<!DOCTYPE html>
<html lang="en">
<head>{% include ds/head.html %}</head>
<body>
  <div class="page">
    <div class="shell">{% include ds/nav.html %}</div>
    <main><div class="shell">
      {% if page.prose %}<div class="prose">{{ content }}</div>{% else %}{{ content }}{% endif %}
    </div></main>
    <div class="shell">{% include ds/footer.html %}</div>
  </div>
  <script src="/assets/ds.js"></script>
</body>
</html>

Add prose: true to the front matter of markdown content pages to get the shared .prose typography; leave it off for bespoke landing pages.

Config keys the includes read

Key	Used by	Notes
`site.title`	nav mast, head
`site.description`, `site.author`, `site.url`	head meta
`site.data.nav`	nav	list of `{ title, url }`
`site.rss_url`	nav	optional; shows an RSS link when set
`site.author_url`	footer	optional; links the author name
`site.footer_years`	footer	optional; e.g. `2025–2026`

Notes / gotchas

Push over ssh, reference over https. Consuming sites' .gitmodules must use the https URL for the Pages build to fetch it; you can still push here over ssh.
Keep base.css / the .js files Liquid-safe — no {{ or {% sequences, since their contents pass through the Jekyll include tag.
Build-time dependency: a consuming site's build now depends on gitea.bchen.dev being reachable (public, valid TLS).
Local dev: clone consumers with --recurse-submodules, or run git submodule update --init after cloning.
Versioning: tags (v1, v2, …) mark known-good states; a consuming site pins a commit and bumps deliberately.