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.

1. 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.

1. 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.

1. 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.

1. Always alt-text images. Accessibility + PDF rendering both depend on it.
2. Headings cascade. Top-level heading in a worksheet section / plan phase

is <h3>; <h1> and <h2> are reserved for the document shell.

1. 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. ×, ÷, π, °, √). 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 × 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 × 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.