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:

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

4. Typography and headings

Hierarchy

Pluvo supports <h2> through <h4> in HTML blocks. Use them consistently and sparingly:

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

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

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.

Updated on: 02/09/2026