# TLH HTML Style Guide

Version 1.2.0

All learning content in TLH is authored in **HTML**. The system applies a
single canonical stylesheet to every rendered surface — PDFs, the public
style-guide page, and (in the future) on-screen rendering. Hand-write clean,
semantic markup; let the stylesheet handle layout and look.

## Principles

1. **Semantic first.** Use `<p>`, `<h3>`, `<ul>`, `<blockquote>`,
   `<figure>` — not generic `<div>`s with classnames.
2. **Reach for reserved classes before overrides.** The `tlh-*` classes
   listed below are tested, look good in both PDF and on screen, and stay
   consistent across the system. Use them by default.
3. **Inline `style="…"` is allowed for genuine one-offs.** When a reserved
   class doesn't cover what you need (e.g. a specific column width, a
   brand-coloured highlight that has to match a unit theme), an inline style
   is fine. Keep it tight — see "Inline style overrides" below.
4. **No `<script>`, no `<style>`, no `<link>`.** The system provides
   one stylesheet and serves all CSS itself. These tags are stripped /
   refused on author input regardless.
5. **Always alt-text images.** Accessibility + PDF rendering both depend on it.
6. **Headings cascade.** Top-level heading in a worksheet section / plan phase
   is `<h3>`; `<h1>` and `<h2>` are reserved for the document shell.
7. **Don't repeat structural titles.** When an entity has a structured `title`
   field (worksheet sections, lesson resources, plan pages), the system
   renders that title as its own heading. Authored `*_html` should start with
   content — not a heading that repeats the title. If you need subheadings
   *inside* a body, use `<h4>` and deeper.

## Allowed elements

**Document-level:** `<h3>`, `<h4>`, `<h5>`

**Block:** `<p>`, `<ul>`, `<ol>`, `<li>`, `<blockquote>`, `<pre>`,
`<hr>`, `<figure>`, `<figcaption>`, `<aside>`, `<section>`,
`<table>` (with `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`)

**Inline:** `<strong>`, `<em>`, `<code>`, `<a href="…">`, `<br>`,
`<span class="…">`, `<sub>`, `<sup>`, `<mark>`

**Media:** `<img src alt>`, `<video src controls>`, `<iframe>`

**Disallowed (security/structure, never overridable):**
`<script>`, `<style>`, `<link>`, `<form>`, `<input>`, `<button>`,
`<font>`, `<center>`, `<marquee>`, any `onclick` / `onload` / etc.
attribute.

## Inline style overrides

Inline `style="…"` is **allowed** when a reserved class doesn't fit the
situation. Treat it as the escape hatch, not the default.

✅ Good reasons to override:
- Constraining a figure to a specific width (`style="max-width: 320px"`).
- Forcing a column split on `tlh-grid-2` (`style="grid-template-columns: 2fr 1fr"`).
- A brand-themed callout colour that doesn't fit any of the five callout
  variants (`style="background: linear-gradient(135deg, #e0f2fe, #f0f9ff); border-left-color: #0284c7"` on a `<aside class="tlh-note">`).
- Adjusting spacing for a tight layout (`style="margin-top: 0"`).

❌ Don't use inline styles to:
- Recolour an existing variant — pick the right `tlh-*` class instead.
- Override base typography (font size, family, line-height). Headings and
  body text are deliberately consistent across all content.
- Add gradients to plain text or paragraphs — they don't print well.

When you do override, prefer overriding a single property on top of a
reserved class:

```html
<aside class="tlh-example" style="padding: 1.25rem 1.5rem;">
  <p>…</p>
</aside>
```

That keeps the class's gradient + shadow + page-break-avoidance and only
adjusts the padding.

## Reserved CSS classes

### Callouts (apply on `<aside>` or `<div>`)

| Class | Use for |
|---|---|
| `tlh-note` | Side information; "good to know." |
| `tlh-tip` | Helpful hint to nudge the learner. |
| `tlh-warning` | Important caveat / common mistake. |
| `tlh-example` | A worked example. Often used in a worksheet section preface. |
| `tlh-summary` | End-of-section recap. |

Pattern:

```html
<aside class="tlh-example">
  <p><strong>Example.</strong> Adding fractions with the same denominator:
  1/4 + 2/4 = 3/4.</p>
</aside>
```

### Worksheet patterns

| Class | Apply on | Use for |
|---|---|---|
| `tlh-question` | `<div>` | A single question block. Wrap the prompt + any answer space. |
| `tlh-question-number` | `<span>` | Visible number/label for a question (e.g. "Q1.") |
| `tlh-answer-line` | `<span>` | An inline fill-in line (printed/PDF: an underlined gap). |
| `tlh-answer-area` | `<div>` | A multi-line writing area (printed/PDF: a boxed area with ruled lines). |
| `tlh-choice-list` | `<ol>` or `<ul>` | Multiple-choice options. |
| `tlh-key-term` | `<span>` | Vocabulary or critical concept (rendered with accent + dotted underline). |

Pattern:

```html
<div class="tlh-question">
  <p><span class="tlh-question-number">Q1.</span> What is 3 + 5?</p>
  <p>Answer: <span class="tlh-answer-line"></span></p>
</div>
```

### Layout helpers (apply on `<div>`)

| Class | Result |
|---|---|
| `tlh-grid-2` | Two equal columns. Override `grid-template-columns` inline if you need a different ratio. |
| `tlh-grid-3` | Three equal columns. |
| `tlh-stack` | Vertical stack with consistent spacing. |

### Special

| Class | Use for |
|---|---|
| `tlh-math` on `<span>` or `<div>` | Math expressions (rendered in italic serif). |
| `tlh-code-block` on `<pre>` | Programming code samples (dark theme). |
| `tlh-page-break` on empty `<div>` | Force a page break in PDF rendering. |
| `tlh-lead` on `<p>` | A slightly larger lead paragraph for section openers. |

## Images

Reference assets via the TLH asset URL:

```html
<figure>
  <img src="/services/asset/{asset_id}" alt="Bar chart of weekly sales">
  <figcaption>Weekly sales for Q1.</figcaption>
</figure>
```

External assets (e.g. registered YouTube links) provide a `public_url` —
use that as the `src` for embeds. To constrain an image's width:

```html
<figure style="max-width: 360px; margin-inline: auto;">
  <img src="…" alt="…">
</figure>
```

## Math notation

Wrap inline math in `<span class="tlh-math">…</span>` and block math in
`<div class="tlh-math">…</div>`. Write the expression in plain text or use
HTML entities (e.g. `&times;`, `&divide;`, `&pi;`, `&deg;`,
`&radic;`). The stylesheet renders `tlh-math` in an italic serif to
match conventional math typography.

## End-to-end example: a worksheet section preface

The section already has a `title` field ("Multiplying decimals") which the
system renders as `<h3>`. The preface starts with content — don't repeat
the title.

```html
<p class="tlh-lead">When you multiply two decimals, line up the digits as if they were
whole numbers, then count decimal places in the inputs and place the
decimal point in the answer accordingly.</p>

<aside class="tlh-example">
  <p><strong>Worked example.</strong></p>
  <p><span class="tlh-math">0.3 &times; 0.7</span></p>
  <ol>
    <li>Multiply as whole numbers: <span class="tlh-math">3 &times; 7 = 21</span>.</li>
    <li>Count decimal places: 1 + 1 = 2.</li>
    <li>Place the decimal point: <span class="tlh-math">0.21</span>.</li>
  </ol>
</aside>

<aside class="tlh-tip">
  <p>Quick check: the answer should always be smaller than either input
  when both are between 0 and 1.</p>
</aside>
```

## End-to-end example: a worksheet section body

```html
<div class="tlh-question">
  <p><span class="tlh-question-number">Q1.</span>
  <span class="tlh-math">0.4 &times; 0.5</span> = <span class="tlh-answer-line"></span></p>
</div>
<div class="tlh-question">
  <p><span class="tlh-question-number">Q2.</span>
  Show your working for <span class="tlh-math">1.2 &times; 0.06</span>:</p>
  <div class="tlh-answer-area"></div>
</div>
```

## What NOT to do

- ❌ Repeating the section/resource/page title as a leading heading inside
  the authored HTML — the system renders the title already. Start with
  content.
- ❌ `<font color="red">…</font>` — deprecated; use a callout class or
  inline-style a `<mark>` if you really need an in-line highlight.
- ❌ `<h1>…</h1>` inside a section — `h1`/`h2` are reserved for the shell.
- ❌ `<br><br>` for spacing — use `<p>` elements.
- ❌ Tables for layout — use `tlh-grid-2` / `tlh-grid-3` for layout and
  `<table>` for tabular data only.
- ❌ Recolouring `tlh-question` or callout variants away from their
  semantic palette — the colours signal meaning, don't fight them.
- ❌ `<script>`, `<style>`, `<link>` — never permitted.