# AGENTS.md — SkillMzansi brand pack

Instructions for autonomous coding agents producing SkillMzansi-branded output.

## Start here

1. Read `llms-full.txt` — the complete design playbook (tokens, recipes,
   code templates, worked examples, QA checklist, anti-patterns).
2. Load `brand.json` if you need tokens programmatically.
3. Link or inline `brand.css` rather than re-deriving values.

You are permitted to use these assets to generate SkillMzansi materials.

## Non-negotiables

Playfair Display headlines (sentence case, negative tracking) · Inter body ·
square corners · one gold `#C9A962` accent per layout · paper `#FBF7ED` with
ink `#0D1418`, or black `#000000` with white · logo once, correct light/dark
variant · everything on an 8px grid · South African English · never promise a
job.

Full list: `llms-full.txt` §2. QA before delivering: `llms-full.txt` §9.

## Where things live

```
web/static/brand-pack/          this pack (served at /brand-pack/)
  brand-pack.html               rendered brand pack
  llms.txt  llms-full.txt       AI-facing docs
  brand.json  brand.css         tokens
  logos/  loaders/              assets
  skillmzansi-brand-pack.zip    distributable
web/static/brand/               source logo PNGs (canonical)
web/assets/styles.css           live Tailwind theme tokens
web/components/                 Footer.tsx, BrandLogo.tsx, EmployabilityHandbook.tsx
brand/                          playbook HTML + PPTX template + generators
```

## Regenerating artefacts

```bash
# Presentation template
python brand/pptx/build_brand_template.py

# Visual check without PowerPoint (renders the saved file to HTML)
python brand/pptx/preview_pptx.py brand/SkillMzansi_Brand_Template.pptx out.html

# Rebuild the distributable zip
cd web/static/brand-pack && \
  zip -r skillmzansi-brand-pack.zip logos loaders README.md \
      brand.json brand.css llms.txt llms-full.txt -x "*.DS_Store"
```

Requires `python-pptx` and `lxml`.

## House rules for this repo

- The brand pack page is dependency-free: one HTML file, inline CSS and
  vanilla JS. Keep it that way — no frameworks, no build step.
- Logo PNGs are raster derivations. Do not trace, redraw or "optimise" them
  into vectors.
- Loader SVGs carry their own `<style>` with keyframes so they animate when
  used as `<img>`. Each one also handles `prefers-reduced-motion` internally.
  Preserve both properties.
- PPTX furniture (border, logo, footer, title styling) belongs on slide
  **layouts**, never on individual slides. python-pptx only exposes shape
  helpers on slides, so layout furniture is added via `_spTree` — see
  `build_brand_template.py` and `llms-full.txt` §6.6.
- Title placeholders need an explicit `<a:buNone/>` or they inherit bullets.
- If you change a token, change it in `brand.json`, `brand.css` and
  `llms-full.txt` §3 together. They must not drift.
- Verify visually before claiming done: render HTML with a headless browser,
  render print output to PDF and check the page count, render PPTX with
  `preview_pptx.py`.

## Definition of done

An asset is done when it passes the QA checklist in `llms-full.txt` §9 and
has been rendered and visually inspected — not when the code merely runs.