Gh Pages Neo Brutalist

GitHub Pages — Neo-Brutalist

Overview

A cohesive GitHub Pages design system — square borders, solid offset shadows, monospace type throughout, eight saturated accents, and four switchable themes; see Quick Reference below for exact tokens.

This skill packages that system as drop-in Jekyll templates plus a scaffolder.

When to Use

• New repo that needs a cohesive neo-brutalist GitHub Pages site
• Existing repo has no Pages site yet, or has a generic minima/cayman theme to replace
• User asks for "GitHub page", "landing page", "docs site" for a repo
• User mentions "neo-brutalist", "house design system", "drop-in Jekyll site"

When NOT to Use

• Target repo already wires its own Pages build (Next.js, Astro, Docusaurus, MkDocs)
• Repo is a fork that must keep upstream docs
• Production marketing sites needing CMS / dynamic routing
• Sites that must avoid Google Fonts (privacy-first)
• Repos forbidden from running Jekyll (rare; Pages runs Jekyll by default)

Core Pattern

repo-root/
  _config.yml              # baseurl = /<repo>, theme: null, plugins
  Gemfile                  # github-pages gem
  _layouts/
    base.html              # head, theme-switcher, site-nav, footer, scripts
    home.html              # base + .hero + .markdown-body
    page.html              # base + .doc-hero + .breadcrumbs + .markdown-body
  assets/
    css/site.css           # 39KB — copied verbatim, design tokens + 4 themes
    js/site.js             # theme switcher (localStorage) + copy buttons
  .github/workflows/
    pages.yml              # GitHub Actions Pages build
  index.md                 # front-matter: layout: home, hero_*: ...

Front-matter the page wants:

---
layout: home          # or 'page' for docs
title: Repo Tagline
hero_eyebrow: BADGE TEXT
hero_title: Big Headline.
hero_desc: One-paragraph promise.
hero_actions:
  - { label: "Get Started", href: "./getting-started.html", primary: true }
  - { label: "GitHub", href: "https://github.com/...", external: true }
---

Quick Reference (design tokens)

Eyebrow colour map: eyebrow-pm coral, eyebrow-eng blue, eyebrow-ux purple, eyebrow-agent cyan, eyebrow-ai yellow, eyebrow-readme lime, eyebrow-changelog pink, eyebrow-proj orange.

Components (full list + markup) → REFERENCE.md.

Implementation

One-shot scaffold

From the target repo root:

zsh /path/to/at-skills/gh-pages-neo-brutalist/scaffold.zsh

Prompts for repo name + tagline + GitHub URL, copies templates/ into the repo, rewrites baseurl in _config.yml, swaps placeholders in index.md, ensures .nojekyll is NOT present (Pages must run Jekyll), commits nothing.

Re-run is safe: existing files are left alone unless --force is passed.

Manual scaffold

SRC=/path/to/at-skills/gh-pages-neo-brutalist/templates
cp -R "$SRC"/. .
sed -i '' "s|REPLACE_BASEURL|/$(basename $PWD)|" _config.yml

Enable Pages

GitHub repo → Settings → Pages → Source = GitHub Actions. The included .github/workflows/pages.yml does the build.

Common Mistakes

Red Flags — STOP and Re-check

• About to install Tailwind / Bootstrap / Pico CSS → STOP. The system is plain CSS with custom properties.
• Adding a CSS framework "to make it nicer" → STOP. Boldness comes from tokens, not utilities.
• Reaching for prefers-color-scheme only → STOP. Use the four-theme <select> pattern.
• Templating with React / Vue → STOP. Pure Jekyll. No build toolchain beyond Pages.
• Replacing IBM Plex Mono "for legibility" → STOP. The mono is the brand.

Verification Checklist

After scaffolding, before committing:

• _config.yml baseurl: /<repo-name> set
• assets/css/site.css byte-identical to templates/assets/css/site.css
• assets/js/site.js byte-identical to templates/assets/js/site.js
• index.md front-matter has layout: home + hero fields
• No .nojekyll at repo root
• .github/workflows/pages.yml present
• Pages source = GitHub Actions
• bundle exec jekyll serve (if Ruby installed) renders without errors
• Theme switcher cycles 4 themes; localStorage key wb-theme set
• <pre> blocks show Copy button on hover

See Also

• REFERENCE.md — every CSS class, every token, every component with full markup
• scaffold.zsh — interactive scaffolder
• Live examples — see README.md for current adopters of the design system