docs: add emoji support design spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

1 files changed, 89 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-04-30-emoji-support-design.md b/docs/superpowers/specs/2026-04-30-emoji-support-design.md
new file mode 100644
index 0000000..5d24926
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-30-emoji-support-design.md
@@ -0,0 +1,89 @@
+# Emoji Support — Design Spec
+
+**Date:** 2026-04-30
+**Status:** Approved
+
+## Problem
+
+Authors can't use `:grin:` emoji shortcodes in article prose. Hugo's default config ignores them; no consistent cross-platform rendering exists.
+
+## Scope
+
+Article prose only (`.prose` div in `layouts/articles/single.html`). Not titles, excerpts, tags, or UI chrome.
+
+## Approach
+
+Two-layer solution:
+
+1. **Build time** — Hugo's `enableEmoji = true` converts `:shortcode:` syntax to Unicode emoji characters during markdown rendering.
+2. **Runtime** — Twemoji JS (CDN) replaces Unicode emoji inside `.prose` with consistent SVG `<img>` tags.
+
+## Components
+
+### 1. hugo.toml — `enableEmoji`
+
+Add to top-level config in `/home/danix/Programming/GIT/danix.xyz-hacker-theme/hugo.toml`:
+
+```toml
+enableEmoji = true
+```
+
+Enables Hugo's built-in Go emoji library. Converts GitHub-style `:shortcode:` to Unicode at build time. No other markup changes needed.
+
+### 2. Twemoji init script
+
+New file: `assets/js/twemoji-init.js` in theme repo (`/home/danix/Programming/GIT/danix2-hugo-theme/`).
+
+```js
+document.addEventListener('DOMContentLoaded', () => {
+  const prose = document.querySelector('.prose')
+  if (prose) twemoji.parse(prose, { folder: 'svg', ext: '.svg' })
+})
+```
+
+Targets `.prose` only. SVG format for crisp rendering at any size. Loaded via Hugo Pipes (minified), consistent with all other JS in the theme.
+
+### 3. Twemoji CDN script tag
+
+In `layouts/articles/single.html` (theme repo), add before closing `</body>` or in the scripts block:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/twemoji@latest/dist/twemoji.min.js" crossorigin="anonymous"></script>
+```
+
+Loaded only on article pages — matches existing conditional JS loading pattern in `baseof.html`.
+
+### 4. CSS — inline emoji sizing
+
+In `assets/css/main.css` (theme repo), add under prose styles:
+
+```css
+.prose img.emoji {
+  @apply inline-block h-[1em] w-[1em] align-[-0.1em];
+}
+```
+
+Twemoji adds class `emoji` to generated `<img>` tags. This keeps emoji inline with text at correct optical size.
+
+## Accessibility
+
+Default Twemoji output sets `alt` to the Unicode emoji character (e.g., `alt="😁"`). Screen readers announce the Unicode name ("grinning face"). Passes WCAG 2.1 AA. No override needed.
+
+## Emoji Shortcode Reference
+
+Uses GitHub emoji shortcode names. Reference: search "github emoji cheat sheet" for the full list.
+
+## Files Changed
+
+| File | Repo | Change |
+|------|------|--------|
+| `hugo.toml` | content | Add `enableEmoji = true` |
+| `assets/js/twemoji-init.js` | theme | New file — Twemoji init targeting `.prose` |
+| `layouts/articles/single.html` | theme | Add Twemoji CDN `<script>` tag |
+| `assets/css/main.css` | theme | Add `.prose img.emoji` sizing rule |
+
+## Build Notes
+
+- CSS rebuild required (`npm run build`) after adding Tailwind classes to `main.css`
+- Submodule bump required after theme changes
+- No new npm dependencies