# Template Block Design Decisions

**Last Updated:** 2026-02-15

Design rationale for template content block types, container usage, and styling alignment with blog/lexikon.

## Block Type Selection

### Flowchart

1. **Does the block need a multi-card grid?** (e.g. 3 distinct sub-cards: ArbZG, Minijob, Branchen)
   - Yes → Use `card-*` with `layout: grid-3` (or `grid-2`)

2. **Does the block contain only a table?**
   - Yes → Use `type: table`

3. **Does the block contain a table plus surrounding prose?**
   - Yes → Use `type: section` (never nest table inside card)

4. **Is it a step-by-step guide?**
   - Yes → Use `type: steps`

5. **Is it a simple H2 + paragraphs (possibly with H3s)?**
   - Yes → Use `type: section`

6. **Do you need a highlighted callout?**
   - Yes → Use `type: callout` or `<div class="content-block-callout">` inside content

7. **Do you need numbered examples with left border?**
   - Yes → Use `type: examples`

### When to Use section vs card vs callout

| Use case | Block type |
|----------|------------|
| Plain prose, H2 + paragraphs, tables | section |
| Multi-card grid (3 distinct cards) | card-blue/green/purple + layout: grid-3 |
| Highlighted tips with subtle emphasis | section (prefer) or card-green |
| Important note (ArbZG, disclaimer) | callout |
| Step-by-step instructions | steps |
| Bullet list with icons | list |
| Structured comparison table | table |

## Spacing and Typography

Aligned with blog/lexikon (e.g. Lohnfortzahlung):

- **H3:** font-size 1.5rem (24px) / 1.75rem (28px) desktop; margin-top 2.5rem / 2.75rem; margin-bottom 1rem / 1.25rem; line-height 1.3
- **H2:** margin-top 2.5rem (except first child); margin-bottom 1.5rem
- **Paragraph before H2/H3:** margin-top 2.5rem on the heading so text is not stuck
- **Paragraph spacing:** margin-bottom 1.5rem; line-height 1.65

## Table Styling

- **Header:** Ordio blue background (`var(--ordio-blue)`), white text
- **Cells:** 1px solid Ordio blue border
- **Rounded corners:** 0.75rem on table
- Matches blog-post.css table styling

## Link Styling

- **Color:** `var(--ordio-blue)` (#4D8EF3)
- **Decoration:** underline, 1.5px thickness, 0.2em offset
- **Hover:** darker blue (`var(--ordio-blue-dark)`)
- Overrides any `text-gray-600` inheritance from parent

## References

- [BLOCK_CONTENT_FORMAT.md](_templates/BLOCK_CONTENT_FORMAT.md) – Format specification
- [TEMPLATE_CONTENT_BLOCKS_GUIDE.md](TEMPLATE_CONTENT_BLOCKS_GUIDE.md) – Block types and sync workflow
- [v2/css/template-content-blocks.css](../../v2/css/template-content-blocks.css) – CSS implementation
- [v2/css/blog-post.css](../../v2/css/blog-post.css) – Reference styling (H3, table, links)