---
name: document-branding
description: >-
  Apply Gemma Analytics corporate branding to standalone HTML, PDF, and DOCX
  documents. Use when generating any outward-facing document that is not a
  Typst-compiled contract — e.g. one-pagers, reports, summaries, proposals.
  Trigger phrases: "generate a branded", "with our branding",
  "Gemma style", "corporate template", "create a PDF/HTML/DOCX for".
disable-model-invocation: false
---

# Document Branding

Apply Gemma Analytics corporate branding (Kanit typeface, Plum/Purple palette,
logo, bars motif) when generating standalone HTML, PDF, or DOCX documents.

## Brand at a glance

See the full reference at `${CLAUDE_SKILL_DIR}/references/brand_guide.md`.
Always read it before generating a document — do not rely on memory for colour
values or logo rules.

**Key colours**
- Plum `#2f0559` — primary dark, cover backgrounds, headings
- Super Purple `#883dd8` — primary accent, links, accent bars, Title
- Lavender `#a976e5` — sub-headings, subtitles
- Coral `#ed5c58` — highlights, warnings (use sparingly)
- Teal `#2d9b8b` — secondary accents
- Yellow `#ffe000` — warm highlights (use sparingly)

**Typography**

| Style | Font face | Size | Colour |
|---|---|---|---|
| Title | Kanit Medium | 28pt | `#883dd8` Super Purple |
| Subtitle (cover, document) | Kanit Light (ExtraLight) | 10pt | `#000000` Black |
| Subtitle (cover, plum) [IMPL] | Kanit Medium | 14pt | `#ffffff` White |
| H1 | Kanit Medium | 18pt | `#883dd8` Super Purple |
| H2 | Kanit Medium | 16pt | `#2f0559` Midnight Plum |
| H3 | Kanit Medium | 14pt | `#000000` Black |
| H4 | Kanit Medium | 12pt | `#000000` Black |
| Normal text | Kanit Light (ExtraLight) | 12pt | `#000000` Black — justified |
| Highlight (`**text**`) | Kanit Normal (Regular) | 12pt | `#000000` Black |

Font files are in `${CLAUDE_SKILL_DIR}/assets/fonts/`.

**Company details** — use these whenever generating document content:

| Field | Value |
|---|---|
| Company name | Gemma Analytics GmbH |
| Generic email | data@gemmaanalytics.com |
| Website | gemmaanalytics.com |
| Location | Berlin, Germany |

**Cover modes**

| Mode | When to use | Cover background |
|---|---|---|
| Document (default) | Reports, contracts, DOCX, PDF one-pagers | White — no background |
| Plum cover (`--plum-cover`) | A document that wants a plum cover page | Midnight Plum |
| Dark proposal (`--dark-proposal`) | Proposals — default in contracts skill | `#160329` deep purple, lavender accents, white headings |

Always use document mode unless the user asks for a proposal.

**This skill does not make slides.** All three modes produce a flowing document; `--plum-cover` only changes the colour of its cover page. For an actual slide deck, use the `presentation` skill in this plugin.

## When to use this (branding) skill vs. the contracts skill

| Situation | Skill to use |
|---|---|
| Contract, NDA, FSA, offer, proposal via Typst | `contracts` |
| Standalone HTML page, report, one-pager, brief | this skill |
| Word/DOCX deliverable | this skill |
| HTML → PDF or DOCX export | this skill |
| .md → PDF or DOCX export | this skill |
| .txt → PDF or DOCX export | this skill |

## Workflow

### 1. Gather content

Ask the user for (or confirm you already have):
- **Document title** — required
- **Subtitle** — required. Must reflect the context/purpose of the document in a
  solution-oriented way (e.g. "Turning raw data into actionable insights" or
  "Your path to a modern data platform"). Never use a client name as the subtitle.
- **Client name** — optional. Never put it in the subtitle. Instead, append it to
  the cover meta line as `"<date> · Prepared for <client_name>"`, which renders
  alongside the standard "· Gemma Analytics GmbH" suffix, e.g.
  `"<date> · Prepared for <client_name> · Gemma Analytics GmbH"`.
- **Date** — defaults to today if omitted
- **Content** — can be a Markdown draft, bullet points, or a structured brief.
- **Tone** — defaults to semi-formal if omitted
- **Target group** — defaults to a client interested in data consulting services if omitted

Clarify any missing details before generating.

### Placeholder resolution

Before generating any document, scan the full content for placeholders in
`<placeholder_name>` format. For every placeholder found, ask the user for the
value. Collect all values in a single prompt listing each placeholder — do not
ask one by one. Only proceed to generation once every placeholder has a confirmed
value or the user explicitly says to leave it blank.

Example prompt:
> Before I generate the document, I need a few values:
> - `<employee_full_name>` — full legal name of the employee
> - `<start_date>` — employment start date
> - `<annual_salary>` — gross annual salary in EUR
> _(etc.)_

Replace all placeholders with the provided values before writing the output file.
If the user leaves a placeholder blank, keep it as `<placeholder_name>` in the
output so it remains clearly visible for manual completion.

### 2. Determine output format

| User asks for | Format |
|---|---|
| "a PDF" | HTML → tell user to print/export to PDF with browser or weasyprint |
| "an HTML page / web page" | HTML |
| "a Word doc / DOCX" | DOCX |

For PDF: generate HTML first (browser `Ctrl+P → Save as PDF` gives best results;
`weasyprint` is the CLI option if available).

### 3. Generate the document

**For HTML or HTML→PDF:**

Use the template at `${CLAUDE_SKILL_DIR}/assets/templates/base.html`.
Replace all `{{PLACEHOLDER}}` tokens:

`base.html` carries one placeholder set for all three cover modes. Every token
must be replaced — an unreplaced one leaves a literal `{{TOKEN}}` in the class
attribute or a broken `img src`. Dark-proposal-only tokens take an empty string
in the other two modes; the template hides those elements via CSS.

| Placeholder | Document mode | Presentation mode | Dark proposal mode |
|---|---|---|---|
| `{{DOCUMENT_TITLE}}` | Document title | Same | Same |
| `{{DOCUMENT_SUBTITLE}}` | Solution-oriented subtitle — never a client name | Same | Same |
| `{{DOCUMENT_DATE}}` | `"<date>"` or `"<date> · Prepared for <client_name>"` | Same | `"<date>"` — the client moves to `{{COVER_CLIENT}}` |
| `{{DOCUMENT_BODY}}` | HTML body content | Same | Same |
| `{{ASSET_BASE}}` | *(see note below)* | Same | Same |
| `{{COVER_CLASS}}` | *(empty)* | `cover--plum` | *(empty, the theme class sits on `<body>`)* |
| `{{COVER_BARS}}` | Absolute path to `assets/elements/bars/gemma_bars.svg` | *(empty — no bars on plum cover)* | *(empty — no bars on dark cover)* |
| `{{COVER_LOGO}}` | *(empty, no logo on document cover)* | `logos/primary_logo/gemma_primary_logo_white.svg` | Same as plum cover |
| `{{FOOTER_LOGO}}` | `logos/primary_logo/gemma_primary_logo_black.svg` | `logos/primary_logo/gemma_primary_logo_white.svg` | Same as plum cover |
| `{{COVER_PREPARED_LABEL}}` | *(empty)* | *(empty)* | `"Prepared for"` / `"Erstellt für"` — set when `--date` carries the marker |
| `{{COVER_CLIENT}}` | *(empty)* | *(empty)* | Client name — extracted from the `--date` string |
| `{{COVER_META_SUFFIX}}` | `" · Gemma Analytics GmbH"` | Same | *(empty — the company sits in the footer)* |
| `{{COVER_VALIDITY}}` | *(empty)* | *(empty)* | `"Valid for 30 days"` / `"Gültig für 30 Tage"` |
| `{{HEADER_TEXT}}` | *(empty)* | *(empty)* | Running-header line: `"<title> for <client> – <subtitle>"` |
| `{{HEADER_LOGO}}` | *(empty)* | *(empty)* | `logos/secondary_logo/gemma_secondary_logo_white.svg` |

**Never fill these placeholders by hand and save to a file you intend to share.**
A local absolute path in `{{ASSET_BASE}}`, `{{COVER_BARS}}` or any logo token
breaks the moment the file leaves your machine — fonts and SVGs will be missing
for anyone else.

Always generate HTML via `apply_branding.py --format html`, which:
1. Replaces every placeholder, including the cover mode selection
2. Inlines all SVGs directly into the HTML (no external image references), with
   per-SVG id namespacing so gradients and logos on one page cannot collide
3. Base64-encodes all font files into the HTML (fully self-contained)

Only use the manual token-replacement flow for server-rendered contexts where
the HTML is served alongside the assets directory.

Write the output to a user-specified path, or default to the current directory.

Do NOT generate HTML from scratch. Always extend `base.html` — it contains the
correct font declarations, colour tokens, cover structure, and print CSS.

For one-pager HTML documents, use `html_one_pager_template_about_us.html` as the
reference template.

For a **true single-page** one-pager (no separate cover page), pass `--one-pager`.
It collapses the cover into a compact branded header (title, subtitle, date +
plum divider) on the same page as the body, drops the bars, and suppresses the
page break — so the whole document prints to a single sheet. Without this flag
the script always emits a dedicated cover page, giving a minimum of two pages.

For analysis or multi-page documents (tables, charts, summaries), use
`template_analysis_gemma_overview_2026.html` as the reference template.

For dark proposal documents (`--dark-proposal`), use
`template_proposal_dark.html` as the reference template. It demonstrates the
correct dark theme: `#160329` page fill, white headings, lavender accents, white
footer logo, and the full placeholder/phase/table structure for a proposal.

Both are in `${CLAUDE_SKILL_DIR}/assets/templates/`.

**Dark proposal language (`--language`).** Dark proposals support `--language en`
(default) or `--language de`. It sets the running-header connective
(`for` / `für`), the cover "Prepared for" / "Erstellt für" label, the validity
line ("Valid for 30 days" / "Gültig für 30 Tage"), and the `<html lang>`
attribute. Pass the client via the date string using the matching marker:
`--date "Juli 2026 · Erstellt für <client>"` for DE,
`--date "July 2026 · Prepared for <client>"` for EN.

**Dark proposal components.** Raw HTML passthrough is enabled, so proposals can
embed styled component blocks (ports of the contracts `proposal-*` Typst
functions). Author them as HTML in the Markdown body:

- `<div class="info-cards">` with three `<div class="info-card">` children, each
  holding `info-card__label`, `info-card__value`, `info-card__detail` — the
  Investment / Start / Duration summary row.
- `<div class="module-card">` (add `module-card--teal` for the teal accent) with
  a `module-card__title` and a `<p>` — work-stream / module cards.
- `<div class="timeline__item">` (add `timeline__item--teal`) containing a
  `timeline__dot`, a `timeline__title`, an inline `timeline__period` badge, and a
  `timeline__desc`.
- `<div class="investment-summary">` with `investment-summary__row`s, an
  `<hr class="investment-summary__divider">`, and an `investment-summary__total`.
- `<div class="fixed-price-box">` with `fixed-price-box__label` and
  `fixed-price-box__amount`.
- `<div class="callout">` (plus `callout--coral` / `callout--teal` / `callout--yellow`)
  for notes and prerequisites.
- `<p class="pricing-disclaimer">` — muted billing-terms note; place it directly
  after the pricing table. Standard copy:
  EN: "All prices net (excl. VAT). Fixed-price items are billed upon completion.
  Time & materials items are billed monthly based on actual days worked. Travel
  expenses, if any, are billed at cost."
  DE: "Alle Preise netto (zzgl. MwSt.). Festpreise werden nach Abschluss des
  jeweiligen Moduls in Rechnung gestellt. Positionen nach Aufwand werden monatlich
  auf Basis der tatsächlich geleisteten Tage abgerechnet. Etwaige Reisekosten
  werden nach Aufwand berechnet."

Standard Markdown pipe tables also render with the dark proposal styling.

**Auto-appended standard sections.** Every dark proposal automatically ends with
a **Ways of Working** table and an **About Gemma Analytics** section (fixed
copy + a centred logo/address closing page), language-aware — mirroring
`proposal-en.typ`, which always includes them. Pass `--no-standard-sections` to
omit both (e.g. when the proposal is an appendix or the sections are authored
manually).

**Cover layout rules — always enforce:**
- The cover inner `.page` div must have `padding-bottom` of at least 136px so the
  bars decoration never overlaps the title or subtitle.

**Chart rules — always enforce:**
- SVG axis note / subtitle text must be centred within the plot area, not anchored
  to the left axis edge. Use the midpoint x of the plot area (e.g. `x="345"` for a
  plot from x=50 to x=640`) with `text-anchor="middle"`.
- Chart colours must be validated with the dataviz skill validator before use.
  Use the validated palette: Super Purple `#883dd8`, Coral `#ed5c58`, Teal `#2d9b8b`.

Do NOT repeat the document title as an H1 at the top of the body content — it
is already rendered on the cover. Start the body with H2 or lower.

**For DOCX:**

Run the branding script:

```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/apply_branding.py \
  <input.md> \
  [output.docx] \
  --format docx \
  --title "<title>" \
  --subtitle "<subtitle>" \
  --date "<date>" \
  [--plum-cover]     # add only when the cover should be plum
```

The script prints the output path. If `python-docx` is unavailable the script
will fail with a clear error — in that case, generate HTML and ask the user to
convert with LibreOffice (`libreoffice --headless --convert-to docx`).

DOCX supports headings, bullet and numbered lists, `**highlight**` spans, and
Markdown pipe tables (emitted as real Word tables). It does not support the dark
proposal theme, the one-pager layout, inline SVGs, or the proposal component
blocks — `--dark-proposal`, `--one-pager` and `--no-standard-sections` are
rejected with `--format docx` rather than silently dropped. Use HTML for those.

Same client-name rule applies here: pass `--date "<date> · Prepared for <client_name>"`
rather than putting the client name in `--subtitle`.

### 4. Deliver

- Tell the user the output file path.
- For HTML, also offer to open it in a browser (`open <file>` / `xdg-open <file>`).
- For PDF, remind the user to use browser Print → Save as PDF

### 5. Iterate

Apply feedback by editing the HTML or re-running the script with updated
Markdown. Keep changes minimal — do not restructure the template unless the user
explicitly requests a layout change.

## Asset inventory

```
${CLAUDE_SKILL_DIR}/assets/
├── fonts/
│   ├── Kanit-ExtraLight.ttf
│   ├── Kanit-Regular.ttf
│   ├── Kanit-Medium.ttf
│   ├── Kanit-SemiBold.ttf
│   └── OFL.txt                        — font licence
├── logos/
│   ├── primary_logo/
│   │   ├── gemma_primary_logo.svg     — colour, light backgrounds
│   │   ├── gemma_primary_logo_white.svg
│   │   ├── gemma_primary_logo_black.svg
│   │   ├── gemma_primary_logo_plum.svg
│   │   └── gemma_primary_logo_negativ.svg
│   ├── secondary_logo/                — horizontal wordmark
│   │   ├── gemma_secondary_logo.svg
│   │   ├── gemma_secondary_logo_white.svg
│   │   ├── gemma_secondary_logo_black.svg
│   │   ├── gemma_secondary_logo_plum.svg
│   │   └── gemma_secondary_logo_negative.svg
│   ├── logo_mark/                     — gem icon only
│   │   ├── gemma_logo_mark.svg
│   │   ├── gemma_logo_mark_white.svg
│   │   ├── gemma_logo_mark_black.svg
│   │   └── gemma_logo_mark_negative.svg
│   ├── word_mark_with_logo_mark/      — gem + wordmark combined
│   │   ├── gemma_logo_mark + word_mark.svg
│   │   ├── gemma_logo_mark + word_mark_white.svg
│   │   ├── gemma_logo_mark + word_mark_black.svg
│   │   ├── gemma_logo_mark + word_mark_plum.svg
│   │   ├── gemma_logo_mark + word_mark_negativ.svg
│   │   └── gemma_logo_mark + word_mark_negative_white.svg
│   └── subbrands_logos/               — don't use by default
│       ├── GEM.AI/                    — gem.AI sub-brand
│       │   ├── gem.AI.svg
│       │   ├── gem.AI_white.svg
│       │   ├── gem.AI_black.svg
│       │   ├── gem.AI_plum.svg
│       │   └── gem.AI_negative.svg
│       └── GEM.BI/                    — gem.BI sub-brand
│           ├── gem.BI.svg
│           ├── gem.BI_white.svg
│           ├── gem.BI_black.svg
│           ├── gem.BI_plum.svg
│           └── gem.BI_negative.svg
├── elements/
│   ├── bars/                          — 3-bar signature motif
│   │   ├── gemma_bars.svg             — colour (purple/plum/black) — use on cover for long reports
│   │   ├── gemma_bars_white.svg       — dark backgrounds
│   │   ├── gemma_bars_black.svg
│   │   ├── gemma_bars_purple.svg
│   │   ├── gemma_bars_plum.svg
│   │   ├── gemma_bars_lavender.svg
│   │   ├── gemma_bars_teal.svg
│   │   ├── gemma_bars_coral.svg
│   │   ├── gemma_bars_yellow.svg
│   │   └── gemma_bars_negativ.svg
│   ├── asterisk/                      — starburst accent
│   │   ├── gemma_asterisk_purple.svg
│   │   ├── gemma_asterisk_plum.svg
│   │   ├── gemma_asterisk_lavender.svg
│   │   ├── gemma_asterisk_teal.svg
│   │   ├── gemma_asterisk_coral.svg
│   │   ├── gemma_asterisk_yellow.svg
│   │   ├── gemma_asterisk_white.svg
│   │   └── gemma_asterisk_black.svg
│   ├── semicolon/                     — typographic accent
│   │   ├── gemma_semicolon.svg
│   │   ├── gemma_semicolon_purple.svg
│   │   ├── gemma_semicolon_plum.svg
│   │   ├── gemma_semicolon_lavender.svg
│   │   ├── gemma_semicolon_teal.svg
│   │   ├── gemma_semicolon_coral.svg
│   │   ├── gemma_semicolon_yellow.svg
│   │   ├── gemma_semicolon_white.svg
│   │   ├── gemma_semicolon_black.svg
│   │   └── gemma_semicolon_negativ.svg
│   ├── blob/                          — organic shape accent
│   │   ├── gemma_blob_purple.svg
│   │   ├── gemma_blob_plum.svg
│   │   ├── gemma_blob_lavender.svg
│   │   ├── gemma_blob_teal.svg
│   │   ├── gemma_blob_coral.svg
│   │   ├── gemma_blob_yellow.svg
│   │   ├── gemma_blob_white.svg
│   │   └── gemma_blob_black.svg
│   ├── gem/                           — gem shape accent
│   │   ├── gemma_gem_purple.svg
│   │   ├── gemma_gem_lavender.svg
│   │   ├── gemma_gem_teal.svg
│   │   ├── gemma_gem_coral.svg
│   │   ├── gemma_gem_yellow.svg
│   │   ├── gemma_gem_white.svg
│   │   ├── gemma_gem_black.svg
│   │   └── gemma_gem_plum.svg
│   └── gradient/                      — brand gradient (white → purple → plum → black)
│       ├── gemma_gradient_horizontal.svg
│       └── gemma_gradient_vertical.svg
├── pictures/
│   ├── README.txt                     — licence information — read before using images
│   ├── codding_picture.png
│   ├── grid.png
│   ├── zoom_backgroud_1.png
│   ├── zoom_backgroud_2.png
│   ├── 3d-render-abstract-background-with-floating-cyber-particles.jpg
│   ├── 3d-render-modern-background-with-flowing-cyber-dots-design.jpg
│   ├── purple-particle-wave-mesh.png   — dark top-left, mesh sweeping right; suits a dark cover with left-aligned text
│   ├── purple-particle-plane-horizon.png — dark upper third over a particle plane; suits text set high
│   ├── geschaftsmann-borsenhandler-der-nachts-auf-den-laptop-bildschirm-schaut.jpg
│   ├── organisationsdokumente-fur-junge-erwachsene_1.jpg
│   └── organisationsdokumente-fur-junge-erwachsene_2.jpg
└── templates/
    ├── base.html                                        — base HTML template (source)
    ├── html_one_pager_template_about_us.html           — approved one-pager reference layout (light)
    ├── template_analysis_gemma_overview_2026.html      — approved analysis / multi-page reference layout (light)
    └── template_proposal_dark.html                     — approved reference layout for dark proposals (--dark-proposal)
```

**Which logo to use in documents:**
- Cover page (dark background): `primary_logo/gemma_primary_logo_white.svg`
- Footer / body (light background): `primary_logo/gemma_primary_logo.svg` or `gemma_primary_logo_black.svg`
- Compact/horizontal layouts: `secondary_logo/`
- When both gem and name are needed at high visibility: `word_mark_with_logo_mark/`

**Which bars to use:**
- Use only for long reports or when prompted
- White/document cover decoration: `bars/gemma_bars.svg` (colour variant)
- No bars on plum or dark-proposal covers; the motif is reserved for white covers
- On a dark background elsewhere in the body (not the cover): `bars/gemma_bars_white.svg`

## Quality checklist

Before delivering any document, confirm:

- [ ] Cover logo matches the mode: plum and dark proposal covers carry the white primary logo; the document cover carries none, and "Gemma Analytics GmbH" appears in the meta line instead
- [ ] Bars decoration in bottom-right of cover on white/document covers only (colour variant); no bars on plum or dark-proposal covers
- [ ] Kanit font applied (or fallback declared for DOCX)
- [ ] Headings use `#2f0559` (Plum), not default black
- [ ] Accent bars use `#883dd8` (Super Purple) below each major heading
- [ ] No off-brand colours (no default blue, orange, or generic grey)
- [ ] Logo has clear space and is not distorted
- [ ] If a stock photo from `assets/pictures/` is used, the Freepik attribution is in the document and the user has confirmed the licence covers this use (see that folder's `README.txt`)
- [ ] Footer shows logo + "Gemma Analytics GmbH · gemmaanalytics.com"
- [ ] Date on cover, with client name appended to the meta line (never the subtitle) if given - Always prompt a user to confirm the client name.
- [ ] Markdown tables render as HTML tables, not raw `| a | b |` text
- [ ] For dark proposals exported to PDF, pages are full-bleed dark with no white margin frame