---
name: takween-cover-generator
description: Generate a Modern Bold cover page (`template_cover_<subject>.tex` + sample PDF + PNG snapshot) for any of the 15 subjects, using `design_<subject>.json` as the color source-of-truth. Replaces 1 hour/subject of hand-tuning TikZ overlays with a deterministic generator that pulls primary/accent colors from design JSON, injects the subject's English+Arabic name into the footer band, renders the navy header + yellow accent rule + cream body + 3-column stats row + footer band, and compiles to a 1-page PDF in <10 s. Inputs: subject + unit metadata. Outputs: template + preview.pdf + preview.png + cover-report.md.
---

# takween-cover-generator

Skill #6 — Phase 7 cover-page generator. Bridges `design_<subject>.json` (the color config produced by Skill #4) and the production-ready cover layout pioneered by the Phase 1 English template (commit `673946e`, branch `claude/phase1-cover`). Produces 15 covers (one per subject) in ~3 minutes total — replacing what would be ~15 hours of hand-tuning.

## Strategic role

Phase 7 (Cover/TOC for the full Modern Bold suite) needs covers for all 15 subjects. Without this skill, each subject = a manual fork of `template_cover.tex`, hand-replacing 11 `eng_*` color tokens, hand-translating subject name, hand-checking RTL, hand-compiling.

With this skill: `bash run.sh math 11 "Vectors and Matrices"` → 1 file + 1 PDF + 1 PNG. Cycle time 5–10 seconds.

## When to use

Invoke this skill:
- **Phase 7 cover production** — once per subject × per unit (or once for a sample cover demonstrating the subject's palette).
- **When `design_<subject>.json` updates** — re-run to pick up the new colors.
- **When Brief 3.1 changes** — update SKILL.md template body, re-run for all subjects.

Do NOT use this skill for:
- TOC pages — separate skill (Phase 7 follow-up).
- Per-section cards — those are existing template macros (`\sectioncard`, `\mcqcard`).
- Cover for `english` subject — the canonical Phase 1 template stays the source of truth. Use this skill for the **other 14 subjects** to mirror that source faithfully.

## Inputs

| Field | Type | Default | Description |
|---|---|---|---|
| `subject` | string | required | Must have `backend/config/design_<subject>.json` (generated by Skill #4). |
| `unit_number_word` | string | `"ONE"` | Uppercase English ordinal — e.g. `"EIGHT"`, `"ONE"`. |
| `unit_title_en` | string | `"Sample Unit Title"` | English unit title (display top of cover). |
| `unit_title_ar` | string | `""` | Arabic unit title (smaller, below English). Empty hides the line. |
| `description_en` | string | `""` | One-line English subtitle. |
| `description_ar` | string | `""` | One-line Arabic subtitle. |
| `grade_level` | int | `11` | Tawjihi grade (10/11/12). Used in footer band. |
| `year` | string | `"2025/2026"` | Academic year, header band. |
| `stat_mcq` | string | `"85+ MCQ"` | Stats row column 1. |
| `stat_reading` | string | `"5 READING"` | Stats row column 2. |
| `stat_words` | string | `"40+ WORDS"` | Stats row column 3. |
| `teacher_name` | string | `"أحمد الهندي"` | Author name (Arabic, left footer of body). |

## Outputs

The skill writes to **two locations**:

| File | Description |
|---|---|
| `backend/temp/cover_<subject>/template_cover_<subject>.tex` | Standalone self-compiling template |
| `backend/temp/cover_<subject>/cover.pdf` | 1-page rendered cover |
| `backend/temp/cover_<subject>/cover-p1.png` | 110 dpi snapshot |
| `backend/temp/cover_<subject>/cover-report.md` | Color manifest + verdict |

The template lives under `backend/temp/cover_<subject>/` not `backend/engine/templates/<subject>/` because the per-subject template directories don't exist yet (Phase 8 work). When Phase 8 wires the renderer to load per-subject templates, these files get migrated into place.

### `cover-report.md` shape

```markdown
# Cover Generation Report — <subject>

**Run at**: <yyyy-mm-dd hh:mm>
**Source design**: backend/config/design_<subject>.json
**Verdict**: PASS | FAIL

## Color manifest
| Token | Hex |
|---|---|
| primary.main      | #1A5C38 |
| primary.light     | #2B985C |
| primary.dark      | #092014 |
| accent.yellow     | #FFC107 |
| accent.orange     | #FF5722 |
| (… all loaded …) |

## Footer band
- English: `GRADE 11 · MATH`
- Arabic:  `الرياضيات — الصف الحادي عشر`

## Compile
- template.tex: <bytes> bytes
- cover.pdf: <bytes> bytes, 1 page
- compile time: <seconds> s

## Verdict
PASS / FAIL: <one-line rationale>
```

## Subject Arabic-name map

The skill ships an internal mapping (since `SUBJECT_PRIMARY` in `latex_renderer.py` carries color labels, not subject labels):

```python
SUBJECT_AR_NAME = {
    "arabic":     "اللغة العربية",
    "english":    "اللغة الإنجليزية",
    "math":       "الرياضيات",
    "science":    "العلوم",
    "history":    "التاريخ",
    "geography":  "الجغرافيا",
    "physics":    "الفيزياء",
    "chemistry":  "الكيمياء",
    "biology":    "علم الأحياء",
    "islamic":    "التربية الإسلامية",
    "national":   "التربية الوطنية",
    "technology": "التكنولوجيا",
    "economics":  "الاقتصاد",
    "philosophy": "الفلسفة",
    "other":      "مادة أخرى",
}

SUBJECT_EN_DISPLAY = {
    "arabic":     "ARABIC",
    "english":    "ENGLISH",
    "math":       "MATH",
    "science":    "SCIENCE",
    "history":    "HISTORY",
    "geography":  "GEOGRAPHY",
    "physics":    "PHYSICS",
    "chemistry":  "CHEMISTRY",
    "biology":    "BIOLOGY",
    "islamic":    "ISLAMIC",
    "national":   "NATIONAL",
    "technology": "TECHNOLOGY",
    "economics":  "ECONOMICS",
    "philosophy": "PHILOSOPHY",
    "other":      "GENERAL",
}

GRADE_AR = {10: "العاشر", 11: "الحادي عشر", 12: "الثاني عشر"}
```

These are stable lookups. If Ahmad ever wants a subject renamed (e.g. "بنفسجي" instead of "علم الأحياء"), the map gets edited; nothing else changes.

## Layout (mirroring Phase 1 English cover, commit 673946e)

| Region | Element | Color source |
|---|---|---|
| Header band (1.6 cm tall) | navy fill | `primary.main` |
| Header left | "USTAZI ONLINE" wordmark | yellow on navy: `accent.yellow` |
| Header right | "2025/2026" | white |
| Yellow accent rule (4 pt) | under header | `accent.yellow` |
| Body top | UNIT N (small, letter-spaced) | `accent.orange` |
| Body | 2 pt rule, 40 pt wide | `primary.main` |
| Body | Big English title (36 pt) | `primary.main` |
| Body | Arabic title (16 pt, RTL) | `accent.orange` |
| Body | Thin separator (0.4 pt) | `primary.main!30` |
| Body | English description (11 pt) | `text_secondary` |
| Body | Arabic description (11 pt) | `text_secondary` |
| Body | Stats row (3 columns, 18 pt) | orange / yellow_dark / sec_phonetics |
| Body | Author (Arabic, left) + URL (English, right) | `text_secondary` |
| Footer band (1.4 cm tall) | navy fill | `primary.main` |
| Footer left | "GRADE N · SUBJECT" | yellow on navy |
| Footer right | "<subject_ar> — الصف <grade_ar>" | white |

The skill emits **no decorative TikZ circles** — the Phase 1 spec deliberately omitted them in favor of the minimalist cream-paper aesthetic (Brief Visual Spec v2 §1). Re-introducing decorative circles would diverge from the Approved-94% Phase 1 visual.

## Step-by-step procedure

```bash
SUBJECT="${SUBJECT:?must set SUBJECT}"
GRADE_LEVEL="${GRADE_LEVEL:-11}"
UNIT_TITLE_EN="${UNIT_TITLE_EN:-Sample Unit Title}"
WORK_DIR="backend/temp/cover_${SUBJECT}"
mkdir -p "$WORK_DIR"

# Verify design exists
test -f "backend/config/design_${SUBJECT}.json" || \
    { echo "FAIL: design_${SUBJECT}.json not found — run takween-design-injector first"; exit 1; }

# Step 1-3: generate template + preview tex
PYTHONIOENCODING=utf-8 python .claude/skills/takween-cover-generator/generate_cover.py

# Step 4: compile
START=$(date +%s)
(cd "$WORK_DIR" && xelatex -interaction=nonstopmode -halt-on-error template_cover_${SUBJECT}.tex >/dev/null 2>&1)
END=$(date +%s)

# Step 5: verify + extract PNG
PDF="$WORK_DIR/template_cover_${SUBJECT}.pdf"
if [ -f "$PDF" ] && [ -s "$PDF" ]; then
    pdftoppm -r 110 -png "$PDF" "$WORK_DIR/cover-p"
    PAGES=$(pdfinfo "$PDF" | awk '/^Pages:/ {print $2}')
    [ "$PAGES" = "1" ] || echo "WARN: cover compiled but produced $PAGES pages, expected 1"
else
    echo "FAIL: PDF not produced — see $WORK_DIR/template_cover_${SUBJECT}.log"
    exit 1
fi

# Step 6: emit cover-report.md
PYTHONIOENCODING=utf-8 python .claude/skills/takween-cover-generator/emit_report.py
```

The Python generator (`generate_cover.py`) is self-contained — it loads `design_<subject>.json`, computes the per-subject Arabic+English footer strings, and writes a fully self-compiling `.tex` to the work dir.

## Critical anti-patterns to AVOID

Inherited from Skills #1–#5, plus cover-specific:

- ❌ **Don't hardcode color hex values in the template body.** Read every color from `design_<subject>.json`. Hardcoding kills the whole point — the skill exists to honor per-subject palettes.
- ❌ **Don't use emoji codepoints for stats or decorations** — Noto Sans doesn't ship most. Use TikZ shapes / colored rules / letter-spaced uppercase labels instead. (Carry-over from Skill #5 R6.)
- ❌ **Don't omit `\RL{...}` around multi-word Arabic** in the footer or unit_title_ar. Bare `\textarabic{...}` is just a font switch; multi-word Arabic without `\RL` renders left-to-right. (Carry-over from Skill #1 v2 anti-pattern #6.)
- ❌ **Don't forget `\thispagestyle{empty}`** inside the `titlepage` environment. The cover has its own header/footer bars drawn by TikZ; fancyhdr's pagestyle would draw competing bars.
- ❌ **Don't use the legacy `SUBJECT_PRIMARY[english]` value `#1A3A6B`** — design_english.json correctly carries the Modern Bold `#1A237E`. Reading from JSON gives you the correct value automatically.
- ❌ **Don't embed Python scripts in `<<'PY' ... PY` heredocs on Windows MSYS2** (Skill #4 anti-pattern). Use the shipped `.py` files.
- ❌ **Don't run on Windows without `PYTHONIOENCODING=utf-8`** (Skill #3 anti-pattern). The Arabic strings in the template will explode on cp1252.
- ❌ **Don't introduce decorative TikZ circles** unless Brief is updated. Phase 1 deliberately removed them in favor of minimalism (Approved 94%). Re-adding ≠ enhancement; it's regression.
- ❌ **Don't put `polyglossia` `\setdefaultlanguage` inside the macro body** — it must be in the preamble. Polyglossia complains noisily otherwise.
- ❌ **Don't compile with a single xelatex pass.** The TikZ overlays use `remember picture, overlay` which writes `current page.*` coordinates to the .aux file on pass 1 and reads them on pass 2. **A single-pass compile resolves all `current page` references to default (invalid) values — header bar, USTAZI ONLINE wordmark, year, yellow accent rule all draw off-page; only the footer "GRADE N · SUBJECT" appears (incorrectly at the top).** Always run xelatex twice. (Discovered Skill #6 v1.1, Test 1.)
- ❌ **Don't reference fonts via the legacy `Path = ../../engine/templates/english/fonts/`.** Fonts live at `backend/fonts/` (verified 2026-05-10). From `backend/temp/cover_<subject>/` the relative path is `../../fonts/`. The Phase 1 reference template at commit `673946e` carries the legacy path — `.claude/skills/takween-cover-generator/generate_cover.py` corrects it. (Skill #6 v1.1, Test 1.)

## Test cases — required validation

### Test 1 — Math cover (green theme)
```bash
SUBJECT=math GRADE_LEVEL=11 UNIT_TITLE_EN="Vectors and Matrices" \
    bash .claude/skills/takween-cover-generator/run.sh
```
Expected:
- `backend/temp/cover_math/cover.pdf` exists, 1 page, < 100 KB
- Header band fill = `#1A5C38` (Tawjihi green)
- Footer reads `GRADE 11 · MATH` (left) + `الرياضيات — الصف الحادي عشر` (right)
- Big title shows "Vectors and Matrices" in primary.main green

### Test 2 — Science cover (purple theme)
```bash
SUBJECT=science GRADE_LEVEL=11 UNIT_TITLE_EN="Cells and Genetics" \
    bash .claude/skills/takween-cover-generator/run.sh
```
Expected: primary.main `#4A1A7B` purple. Footer `GRADE 11 · SCIENCE` + `العلوم — الصف الحادي عشر`.

### Test 3 — Arabic cover (burgundy theme + RTL title)
```bash
SUBJECT=arabic GRADE_LEVEL=12 UNIT_TITLE_EN="Classical Poetry" \
    UNIT_TITLE_AR="الشعر الكلاسيكي" \
    bash .claude/skills/takween-cover-generator/run.sh
```
Expected: primary.main `#7B1F3A` burgundy. Arabic title rendered RTL via `\RL{\textarabic{...}}`. Footer `GRADE 12 · ARABIC` + `اللغة العربية — الصف الثاني عشر`.

### Test 4 — Custom unit_title regenerates cleanly
```bash
SUBJECT=math GRADE_LEVEL=11 UNIT_TITLE_EN="Trigonometry & Functions" \
    bash .claude/skills/takween-cover-generator/run.sh
```
Expected: same primary.main as Test 1, but title now reads "Trigonometry & Functions". Confirms the skill regenerates without manual edits.

If any test produces unexpected output, mark the skill experimental and document in `test-results/`.

## Validated 2026-05-10 — see `test-results/`

All 4 test cases passed after 2 v1.1 patches. Visual artifacts:
- `test-results/preview-math.png` — Tawjihi green (#1A5C38)
- `test-results/preview-science.png` — purple (#4A1A7B)
- `test-results/preview-arabic.png` — burgundy (#7B1F3A) + RTL Arabic title
- `test-results/preview-math-test4.png` — math regen with "Trigonometry & Functions"
- `test-results/validation-summary.md` — combined report

| Test | Subject | Verdict | Compile | Visual |
|---|---|---|---|---|
| 1 | math | ✅ PASS | 3s, 21 KB PDF, 1 page | header + body + footer all correct |
| 2 | science | ✅ PASS | 3s | purple primary, footer "SCIENCE / العلوم" |
| 3 | arabic (grade 12) | ✅ PASS | 3s | burgundy primary, footer "ARABIC / اللغة العربية — الصف الثاني عشر" |
| 4 | math regen | ✅ PASS | 2s | same green palette, new title "Trigonometry & Functions" |

**v1.1 patches** (folded into SKILL.md + helper scripts):

1. **Font path corrected**: `../../engine/templates/english/fonts/` → `../../fonts/`. The Phase 1 reference at commit 673946e carries the legacy path; current repo has fonts at `backend/fonts/`. Without this fix, fontspec errors ("font not found") and compile fails entirely.

2. **2-pass xelatex compile**: TikZ overlays use `remember picture, overlay`, which requires reading `current page.*` from the .aux file written on pass 1. A single-pass compile produces a malformed page where the header band, "USTAZI ONLINE" wordmark, year, and yellow accent rule are all drawn at invalid coordinates (effectively off-page); only the footer band's `GRADE N · SUBJECT` text accidentally appears at the top. Adding a second pass to `run.sh` produces the canonical layout.

Bug detection time: ~15 min total. Visual confirmation via Read tool on the generated PNG was the fastest diagnostic — diffing the broken render against the Phase 1 reference made the symptom obvious.

## Composability notes

This skill **uses no other skill internally** in v1.0 — it's pure generation. It **consumes** `design_<subject>.json` produced by Skill #4 (`takween-design-injector`).

Future composition:
- The future `phase-builder-agent` (Week 4) will run this skill once per subject during Phase 7 cover production, then run `takween-smoke-tester` (Skill #2) on each generated cover for log-level verification, then `takween-quality-gate` (Skill #3) for cross-cover regression checks.

## Reference helper scripts

```bash
.claude/skills/takween-cover-generator/run.sh <subject> [grade_level] [unit_title_en] [unit_title_ar]
```

Wraps Steps 0–6 of the procedure. The Python generators live at:
- `generate_cover.py` — emits the template .tex
- `emit_report.py` — emits the cover-report.md after compile