HoffDesk Blog — Frontend Design Specification

Author: Daedalus 🎨
Date: 2026-04-20
Status: Approved — Phase 3 unblocked
Depends on: Sprint 1 Design Tokens (shared/design-tokens/sprint-1.md)

Design Philosophy

The blog extends the HoffDesk "Functional Luxury" aesthetic into long-form content. The same dark palette, the same typography discipline — but with a reading experience that prioritizes sustained engagement over glanceable status.

If the dashboard is a control panel, the blog is a library: same building, different room.

Core principle: The words are the product. Every design decision serves readability first, aesthetics second.

Layout Architecture

Page Structure

┌──────────────────────────────────────┐
│  HEADER (sticky)                     │
│  [Logo] [Categories] [Search] [RSS]  │
├──────────────────────────────────────┤
│                                      │
│  HERO / FEATURED POST                │
│  (full-width, large image, overlay)  │
│                                      │
├──────────────────────────────────────┤
│                                      │
│  POST GRID                           │
│  ┌─────────┐ ┌─────────┐            │
│  │  Card   │ │  Card   │  (2-col)   │
│  │         │ │         │  desktop   │
│  └─────────┘ └─────────┘            │
│  ┌──────────────────────┐            │
│  │  Long-form Card      │  (1-col)  │
│  │  (featured mid-scroll)│           │
│  └──────────────────────┘            │
│                                      │
├──────────────────────────────────────┤
│  FOOTER                              │
│  [About] [RSS] [HoffDesk Home]       │
└──────────────────────────────────────┘

Mobile Layout (Primary Target)

• Single column, full-width cards
• Sticky header collapses to hamburger menu
• Featured post renders as full-bleed hero image with text overlay
• Post cards stack vertically with generous spacing
• Reading view: 20px side padding, max-width: 72ch for body text

Desktop Layout (>1024px)

• Two-column post grid on index page
• Article view: centered single column, max-width: 720px
• Sidebar appears on article pages with: category list, recent posts, RSS link
• Sidebar width: 280px, hidden on mobile

Typography — Blog Extensions

Extends the Sprint 1 type scale. Blog content has different needs than dashboard widgets.

Font stack: Same as dashboard — Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif. Zero external font loads.

Key difference from dashboard: Blog body text is 17px (vs 16px dashboard) with 1.7 line-height (vs 1.5) for sustained reading comfort. This is intentional — 16px works for glanceable data, 17px works for paragraphs people actually read.

Color Usage — Blog-Specific

All dashboard tokens apply. Blog adds:

Category Colors

Each content category gets a distinct accent for pill badges and visual scanning:

Component Specifications

Post Card

┌────────────────────────────────┐
│  [Category Pill]               │
│                                │
│  Post Title                    │
│  Two-line excerpt max...       │
│                                │
│  Apr 20 · 8 min read          │
└────────────────────────────────┘

• Background: bg-secondary (#1a1d27)
• Border: 1px solid border-default (#2e3142)
• Border radius: radius-md (12px)
• Padding: space-6 (24px)
• Hover: bg-tertiary, shadow-card-hover, slight translateY(-2px)
• Transition: transition-base (250ms ease)
• No images on cards — text-only for performance and simplicity (Sprint 1)

Hero / Featured Post

• Full-width container
• Optional background image with blog-img-overlay scrim
• Title in blog-hero-title
• Category pill + date + read time in blog-meta
• Minimum height: 280px on mobile, 360px on desktop
• Text left-aligned, bottom-anchored

Category Pill

• Background: category color at 12% opacity (e.g., rgba(99,102,241,0.12) for OpenClaw)
• Text: category color at full opacity
• Border radius: radius-sm (6px)
• Padding: 4px 10px
• Font: blog-meta (12px, weight 500)
• Hover: background opacity → 20%

Article Page

┌──────────────────────────────────────┐
│  ← Back to Blog    [Category Pill]   │
├──────────────────────────────────────┤
│                                      │
│  Title (blog-post-title)             │
│  By [Author] · Apr 20, 2026          │
│  · 8 min read                       │
│                                      │
│  ─────────────────────────────       │
│                                      │
│  Article body (blog-body, 17px)      │
│  max-width: 720px, centered          │
│                                      │
│  - Headings in text-primary          │
│  - Links in blog-accent              │
│  - Code blocks on blog-code-block-bg │
│  - Blockquotes with left border      │
│  - Images: full-width, radius-md     │
│                                      │
│  ─────────────────────────────       │
│                                      │
│  [Prev Post]          [Next Post]    │
│                                      │
├──────────────────────────────────────┤
│  FOOTER                              │
└──────────────────────────────────────┘

Navigation

• Header: HoffDesk logo (links to dashboard home) | "Blog" | category links | search icon | RSS icon
• Sticky on scroll — thin bar (56px height), bg-primary with border-default bottom border
• Mobile: Logo + hamburger. Hamburger reveals slide-down menu with category links + search
• Search: Simple text input, filters post titles and excerpts client-side (no backend search needed for Sprint 1)

Footer

• Minimal. One line: © 2026 HoffDesk · Built with ☕ and OpenClaw · RSS
• Link back to hoffdesk.com dashboard home
• Link to RSS feed

Responsive Breakpoints

Same as dashboard:

Mobile is the primary target. Every layout must look excellent on a 375px viewport before we consider wider screens.

Performance Budget

Blog pages must meet the same performance standards as the dashboard:

No third-party JS. No Google Fonts. No analytics scripts. HoffDesk runs its own infrastructure — we track our own metrics if we track them at all.

Accessibility (WCAG 2.1 AA)

Following the Sprint 1 a11y review findings:

1. Focus indicators: All interactive elements get visible :focus-visible rings (2px solid accent-primary, offset 2px)
2. Contrast: All blog text meets 4.5:1 minimum. Blog body at 17px on bg-primary with text-primary passes at 13.3:1
3. Link clarity: Links are underlined in article body. Color alone never indicates a link
4. Heading hierarchy: Proper <h1> → <h2> → <h3> nesting on every page
5. Image alt text: Required for all images (enforced in content template)
6. ARIA landmarks: <nav>, <main>, <article>, <footer> — proper semantic HTML
7. Reading flow: No content reorder tricks. Visual order = DOM order

Architectural Decisions (Resolved)

Tech Stack

File Structure (Sprint 1)

blog/
├── templates/
│   ├── base.html.j2            # Shared layout (head, header, footer)
│   ├── blog_index.html.j2      # Post listing page
│   ├── blog_article.html.j2    # Individual article page (full HTML for SEO)
│   ├── blog_category.html.j2   # Category archive page
│   ├── blog_tag.html.j2        # Tag archive page
│   └── feed.xml.j2             # RSS 2.0 feed template
├── static/
│   ├── blog.css                # Blog-specific styles
│   └── search.js               # Fuse.js client-side search (Sprint 1)
├── content/
│   ├── homelab/
│   ├── openclaw/
│   └── ai-news/
└── builder.py                  # Static site generation

Socrates Integration Notes

What the frontend needs from the backend:

1. GET /api/blog/posts — Paginated post list with: slug, title, excerpt, category, date, read_time, author
2. GET /api/blog/posts/:slug — Full article with: title, body_html (rendered markdown), category, date, author, read_time, prev_slug, next_slug
3. GET /api/blog/posts?category=:cat — Filtered by category
4. GET /blog/feed.xml — RSS 2.0 feed
5. Content stored as: Markdown files in blog/content/ with YAML frontmatter, rendered server-side to HTML

Frontmatter spec:

---
title: "Your Post Title"
slug: "your-post-title"
category: "openclaw"  # homelab | openclaw | ai-news
date: 2026-04-20
author: "Matt"
excerpt: "One or two sentences that appear in the card and RSS feed."
read_time: 8  # estimated minutes
tags: ["openclaw", "automation", "tutorial"]
---

This spec is the contract for blog frontend. Changes here propagate to implementation. Socrates builds the backend to match these API needs.