# Writing Guide — html.surf

# Writing Guide

 html.surf style reference  ·   Guide  MCP

 Write clean semantic HTML fragments. The viewer provides everything else — typography, colour, spacing. Your job is structure and content.

## The Golden Rule

 Do **not** include ` `, ` `, ` `, ` `, or ` ` tags. The viewer strips them anyway. Write a fragment rooted at ` `.

  **The canonical pattern:** See [/p/rlm](/p/rlm) — the RLM article is the reference implementation of this style.

## Article Template

```

# Your Title

  By Author  ·  Month Year  ·   Tag

  One punchy sentence that earns the read.

## Section Title

  Body copy...

   **Key insight:** One sentence.

### Subsection

  ...

    ...   Fig 1. Caption text

  `const x = 1;`
## Further Reading

- [Other Page](/p/other-page) — description

```

## CSS Variables

 Use these for any inline styles. Never hardcode hex values.

     Variable  Use for

      `var(--paper)`  Page background (#f7f3ed)
      `var(--paper-2)`  Card/callout backgrounds
      `var(--paper-3)`  Borders, dividers
      `var(--ink)`  Primary text
      `var(--ink-2)`  Body text
      `var(--ink-3)`  Muted/meta text
      `var(--accent)`  Terracotta highlights
      `var(--link)`  Hyperlinks
      `var(--font-display)`  Playfair Display (headings)
      `var(--font-body)`  Lora (body text)
      `var(--font-mono)`  Fira Code (code, bylines)

## Built-in Component Classes

     Class  Use for

      `.byline`  Author · date · tags row under h1
      `.lead`  Italic opening paragraph
      `.callout`  Terracotta left-border highlight box
      `.tag`  Inline category pill (used inside .byline)
      `figcaption`  Mono caption under figures/SVGs

## Validator — Errors (block save)

     Code  Issue

      `SCRIPT_TAG`  ` ` tags not allowed
      `JS_HREF`  `javascript:` hrefs
      `INLINE_EVENT`  `onclick`, `onload` etc.
      `DATA_URI`  `src="data:..."`
      `IFRAME`  Embedded frames
      `FORM_ACTION`  Forms posting to external URLs

## Validator — Warnings (advisory)

     Code  Fix

      `HARDCODED_FONT_FAMILY`  Use `var(--font-body)` or `var(--font-display)`
      `HARDCODED_COLOR`  Use `var(--ink)`, `var(--accent)` etc.
      `HARDCODED_BACKGROUND`  Use `var(--paper)`, `var(--paper-2)`
      `WRAPPER_MAX_WIDTH`  Remove — viewer controls reading width

## MCP Workflow

```
// Always validate before writing const check = await mcp.validate({ html }) if (!check.ok) { /* fix errors */ } // Then write await mcp.write({ slug: 'my-topic', html, public: true })
```