> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.pluvo.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Pluvo course design with AI

# Pluvo Course Design

This skill describes how to create consistent, professional-looking content within Pluvo's course environment. It covers two things:

1. **Technical formatting rules** that always apply (Pluvo HTML quirks, spacing, typography, images, callouts, structure).
2. **Aesthetic direction** — a chosen style that visually ties the entire course together (warm minimalist, editorial, typographic grid, etc.).

Follow these guidelines when writing HTML for `edit_content_text` or `edit_content_embed` blocks, or when a user asks for a redesign.

---

## 1. Working method — How this skill is applied

### Step 1: Determine the scope

Before writing a single line of HTML, get clarity on:

**How much are you designing?**

* A single content block? → ask for the `content_id` or a description of where it sits
* An entire chapter? → walk through all content blocks in that chapter
* An entire course? → first map out the course structure, then work chapter by chapter

**What's there now?**

* Read existing content with `get_content` or `get_course_contents_summary`
* Take stock of what's there: tables, callouts, accordions, images, plain text
* Identify what works and what needs the most attention

### Step 2: Determine the colour source

Explicitly ask which route is being followed for colours. Three options:

**Option A — Academy house style**
Fetch the theme colours of the Pluvo course via `get_course_theme_colors`. Use those as the basis (primary, secondary, accent). Ask whether any additional colours are known from the organisation's house style (logo colours, brand book).

**Option B — Own colours in mind**
The user has a specific palette in mind or wants to deviate from the academy house style. Ask for concrete colours (hex codes, a brand they admire, or a mood description such as "warm and earthy" or "fresh and blue").

**Option C — Choose a default palette**
No preference, or no house style known. In that case, offer a choice from predefined palettes (see `references/aesthetiek-stijlen.md`, section *Default colour palettes*).

### Step 3: Choose an aesthetic direction

Read the details: `references/aesthetiek-stijlen.md`

Present the user with a choice from the styles. Not just names — describe how it feels in a learning environment:

| Style | Feels like... |
| ---- |
| **Warm minimalist** | Friendly and approachable. Soft colours, rounded corners, mild shadows. A good default for most e-learning. |
| **Functional** | Clean and purposeful. Every element earns its place. No decoration — just clarity. Good for technical or professional content. |
| **Typographic grid** | Sturdy and structured. Strong headings, tight grid, flat design. Makes dense information feel organised and authoritative. |
| **Quiet space** | Calm and breathable. Lots of whitespace, muted colours, fine lines. Elegant — works for reflective or contemplative content. |
| **Editorial** | Typography-driven. Serif headings, pull quotes, thin rules. Makes text-heavy content feel like a well-designed article. |
| **Decorative geometric** | Statement piece. Deep colours, geometric precision, decorative frames. Premium feel for leadership content. |
| **Playful graphic** | Lively and bold. Bright colours, thick borders, energetic layout. Fun for onboarding, team culture or creative skills. |
| **Raw structural** | Unpolished and honest. Monospace, hard edges, no polish. A provocative choice — confirm the user really wants this for learning content. |

For quieter styles the margin may be larger (`40px 0` or more); for rawer styles the rule may be thicker and harder. The style determines how it is filled in — the presence itself is the rule.
**When to place an HR:**
* At the start and the end of every block that contains images
* Between two image+text pairs
* Between a text section and a question
* Between two sections that differ in content
* Before a heading that introduces a new part (if the heading is not the very first element)
### Margins on individual elements
| Element | Recommended style |
| Large (full-width) image | `margin:16px 0 24px 0` |
| Paragraph after a heading | default (nothing extra needed) |
| Callout / highlight block | `margin:20px 0` |
| HR | `margin:30px 0` (default), `40px 0` for quiet styles |

## 4. Typography and headings
### Hierarchy
Pluvo supports `<h2>` through `<h4>` in HTML blocks. Use them consistently and sparingly:
| Level | Use | HTML |
| H2 | Main title of a module or major part | `<h2>Title</h2>` |
| H3 | Subsection within a block | `<h3>Subtitle</h3>` |
| H4 | Small subheading, label | `<h4>Label</h4>` |
| Bold | Lead-in above a single paragraph | `<p><strong>Lead-in</strong></p>` |
The chosen style determines the typeface, the letter spacing and the weight — see `references/aesthetiek-stijlen.md`.
### Heading above a question
Always place a clear heading above a question or quiz block. This gives the learner context and makes the structure scannable. The heading contains two things:
1. **The topic** of the question — what is it about?
2. **The type of question** — knowledge check, self-test, ordering question, reflection question
Use `<h3>` or `<h4>` depending on its weight within the course. The heading goes in a separate `content_text` block directly above the question block:
html
```
Knowledge check — When is a risk assessment required?
```
html
```
Reflection question: How do you deal with resistance?
```
Never place a question without an introduction or heading. A single line of introductory text is fine too:
html
```
Read the situation below and answer the question.
```
For a bundle of questions (several questions on the same topic): place one overarching heading above the entire series.

## 5. Images and sizes
### Wrapper (required)
```
```
### Sizes per content type
| Type of image | Style | Why |
| Regular illustration next to text | `max-height:280px` | Proportional, does not overwhelm the text |
| Infographic / diagram with text | `max-width:95%` | Text inside the image stays legible |
| Standalone hero image | `max-height:400px` | Large, but bounded |
| Thumbnail / icon | `max-height:120px` | Small accent image |
### Alt text caption (for standalone images)
Always add a descriptive caption below a standalone image:
html
```
Alt: Description of what can be seen in the image.
```
### Layout patterns for images
**Image left, text right:**
html
```
TitleDescriptive text here.
```
**Text left, image right:**
html
```
TitleDescriptive text here.
```
**Full-width image (diagram/infographic):**
html
```
TitleDescription of what the image shows.
```
With multiple pairs, alternate the direction (left/right/left) for visual rhythm.

## 6. Callouts and highlights
Use callouts to emphasise important information without a large image. Always inline styles, single line.
**Info / tip:**
html
```
💡 TipText of the tip here.
```
**Warning / note:**
html
```
⚠️ NoteText of the warning here.
```
**Important / critical:**
html
```
🔴 ImportantText here.
```
These patterns are the default — colour, radius and shadow are adjusted based on the chosen style. See `references/aesthetiek-stijlen.md` for style-specific variations.
**No page-wide quote blocks in course content.** Use callouts instead (as above) or style-specific quotation components from the aesthetics reference.

## 7. Structure of a complete content block
A well-built Pluvo content block follows this order:
1. **HR** (at the start if images or callouts follow)
2. **H3 or H4 heading** (gives context for what comes next)
3. **Introductory text** (1–2 sentences, optional)
4. **Content** (image+text pairs, callouts, or regular paragraphs)
5. **HR** between sections or pairs
6. **HR** at the end (if the block contained images or callouts)
**Example skeleton (conceptual):**
```
[HR] [H3: Section title] [introductory text] [image+text pair] [HR] [second pair] [HR]
```

## 8. Anti-patterns
**No style that clashes with the learning objective.** Raw structural for compliance training is distracting. Playful graphic for medical training undermines credibility. Steer towards choices that fit.
**Do not over-design.** Even the most exuberant style must serve legibility. Does a choice make the content harder to read or navigate? Then it is wrong — however aesthetically "correct" it may be.
**No generic AI look.** No purple gradients on white, no predictable card grids, no cookie-cutter component layouts. Every result should feel as though it was designed for that specific context.
**Do not forget mobile.** Every design choice has to work on a 375px screen. Does your three-column layout collapse on mobile? Then it is not a good design.

## 9. Checklist before saving
* The full HTML is one continuous line (no `\n`)
* Every `<img>` sits inside `<section><figure class="figure-image">...</figure></section>`
* Images have the correct `max-height` or `max-width`
* Flexbox pairs have `min-width:280px` for mobile
* HR dividers use the correct margin (default `30px 0`)
* Blocks containing images start and end with an HR
* Questions have a heading or an introductory sentence
* Standalone images have an alt text caption
* CSS scoped with a unique block id (no leakage)
* No `nth-child` selectors used
* Nothing looks cramped — enough breathing room
* Touch targets at least 44px high
* User warned that the WYSIWYG editor breaks custom HTML

## 10. Additional references
| File | When to read |
| `references/aesthetiek-stijlen.md` | At step 3 (choosing an aesthetic direction) and step 4 (defining tokens). Contains per style: a description of the feel, colour palette, design tokens, and a visual HTML example. Also: default colour palettes for when no brand style is available. |

## Changelog
**1.0.0** — First public version. Merges the technical formatting rules and the aesthetic direction into a single skill. Eight styles (warm minimal, functional, typographic grid, quiet space, editorial, decorative geometric, playful graphic, raw structural) including tokens and visual examples. Default palettes for when no brand style is available.