docs(SKILL.md): comprehensive update with Expert session learnings
New rules: - Concentration save DC formula: "higher of [rarity DC] or half damage" - Charges not recharges on consumables - Verify mechanics against raw material and item name (wrong-mechanics items exist) - rewrite-mechanics.py added to Scripts section New/expanded pitfalls: - #19: lore font-size reduction technique (9.33→8.8px) when rect extension isn't enough - #24: title overflow fixes (two-line split, hyphenation) - #25: mechanics rect too small (compare against working card) Updated editorial status: - Expert tier: Done (2026-04-17), full editorial cycle complete Made-with: Cursor
This commit is contained in:
@@ -44,6 +44,7 @@ Edit lore/mechanics → patch SVG directly
|
||||
- `scripts/generate-source-of-truth.py` — Extract ITEMS.md/PACKS.md/BALANCE.md from SVGs
|
||||
- `scripts/generate-5etools-json.py` — Generate 5etools Homebrew JSON from ITEMS.md
|
||||
- `scripts/rewrite-lore.py` — Rewrite lore in an existing SVG without full card regeneration
|
||||
- `scripts/rewrite-mechanics.py` — Rewrite mechanics (`-m`) and/or subhead (`-s`) in an existing SVG. Preserves lore, images, layout. Use argparse flags only (see pitfall #22).
|
||||
- `scripts/assemble-packs.py` — Pack assembly with cross-flavor lookup, name aliasing, and QA
|
||||
- `scripts/check-flavor-marks.py` — Audit multi-flavor mark colors against ITEMS.md
|
||||
- `scripts/fix-flavor-marks.py` — Inject/repair flavor marks on existing SVGs
|
||||
@@ -141,8 +142,11 @@ Lore (N words; source=custom):
|
||||
- **Dimension expressions** use the multiplication sign × (U+00D7), not lowercase x: **5×10×5-foot**, **10×10-foot**. Bold the full dimension expression.
|
||||
- **Every save must specify a DC.** If an item forces a creature to make a saving throw, the DC must appear in the mechanics text. No exceptions. Standard DCs by rarity: Common DC 12, Uncommon DC 14, Rare DC 16, Very Rare DC 19, Legendary DC 21–25 (varies by item). Raw materials from the generating agent frequently arrive without DCs — always add them. **Note:** Specialist tier (already printed) still uses DC 13 from the original generating agent.
|
||||
- When Grandmaster tier upgrades remove a penalty or tradeoff from a lower tier, just state the clean final effect. Do not mention the absence of a penalty (e.g., don't write "with no speed penalty").
|
||||
- **Concentration save DCs** should be "the higher of [rarity DC] or half damage" — e.g. "Con save (DC is the higher of 14 or half damage dealt)". This prevents the item from nerfing high-damage scenarios where RAW concentration DC would be higher.
|
||||
- **Charges, not recharges, on consumables.** Consumable items have finite charges: "Three charges." not "Three charges; recharges at dawn." Only use recharge language if the item is explicitly durable/permanent.
|
||||
- Reactions must have a trigger event ("Reaction when X happens"). A reaction without a trigger is not RAW-legal.
|
||||
- "nonmagical" is one word (no hyphen). Avoids "non-magical" splitting across tspan line breaks in SVGs.
|
||||
- **Verify mechanics against the raw material and item name.** Wrong-mechanics items exist — Frost-Away Unguent had identical mechanics to Cinder-to-Soot Ointment (copy-paste from card generation). Always sanity-check that the mechanics match what the item name describes.
|
||||
|
||||
### Mechanics Typography
|
||||
- **Bold = the highlights.** A player glancing at the card should immediately see the numbers and effects that matter. When in doubt, bold it.
|
||||
@@ -284,7 +288,7 @@ Lore in ITEMS.md is tagged with a `Lore source` field:
|
||||
|
||||
18. **Pack mapping for handmade tiers** — Novice (0a) and Intermediate (0b) packs were mapped by rendering pack PDF pages to PNG and comparing against singles using ImageMagick (`compare -metric MAE`). This works even when `pdftotext` fails on rasterized cards.
|
||||
|
||||
19. **Lore text field clipping** — If lore clips at the bottom of the card back, the `shape-inside` rect is too short. Fix: find the rect ID from the lore text element's `shape-inside:url(#rectID)` style, then adjust y (move up ~5) and height (grow ~20). This adds about one line of space. Common with 100-120 word lore on templates that were sized for shorter text. See QUICKSTART.md for the full technique.
|
||||
19. **Lore text field clipping** — If lore clips at the bottom of the card back, the `shape-inside` rect is too short. Fix: find the rect ID from the lore text element's `shape-inside:url(#rectID)` style, then adjust y (move up ~5) and height (grow ~20). This adds about one line of space. If the rect extension still isn't enough, subtly reduce the lore text element's font-size (9.33→8.8px) and line-height (1.25→1.20), then recalculate all tspan y positions with the new spacing (base_y + i × new_font_size × new_line_height). This is visually subtle but gains significant room.
|
||||
|
||||
20. **Tea/brew items** — Items depicted as brewed teas (not bottled potions) should have "One minute to brew and drink." as the first mechanics line and "Single use." at the end. The image suggests reusability, so "Single use" must be stated explicitly for these items only. Normal potions never state this (it's implied by RAW).
|
||||
|
||||
@@ -301,7 +305,11 @@ Lore in ITEMS.md is tagged with a `Lore source` field:
|
||||
|
||||
23. **Split-bold and range-bold patterns** — `_bold_fmt()` produces broken bold in two common cases: (a) dice+modifier splits as `**1d8**+2` instead of `**1d8+2**`, and (b) normal/far ranges become `20/**60 ft**` instead of `**20/60 ft**`. When using `rewrite-mechanics.py`, always write your own `**` markup explicitly rather than relying on auto-bolding. Scan every editorial batch for these patterns.
|
||||
|
||||
24. **FLAVOR_COLORS in generate-card.py has wrong mark colors for Magic and Utility.** The `FLAVOR_COLORS` dict says Magic=`#9966cc` and Utility=`#ff9933`. These may be correct for gradient stops or price tag backgrounds, but the mark tick colors across ALL tiers (Specialist through Grandmaster) are Magic=`#c34cff` and Utility=`#ffcc00`. When `set_flavor_marks` clones from an existing template mark, it inherits the correct color. But when creating marks from scratch (no template), it falls back to `FLAVOR_COLORS` and produces wrong colors. Always verify against existing single-flavor cards in the same tier. Use `scripts/check-flavor-marks.py` to audit. Also: `MARK_WIDTH` (1.5875) doesn't match Specialist card marks (0.76627). Copy geometry from a known-good card in the same tier.
|
||||
24. **Title overflow on long item names** — If a title overflows the right edge of the card, either (a) split to two lines by converting the single tspan to two tspans at y=7.151 and y=11.508 with font-size 4.58611px, and move the subhead y from 12.37 to 17.0; or (b) if already two lines, hyphenate the long word at a valid English hyphenation point (e.g. "COOPERATIVE" → "CO-" / "OPERATIVE"). Always verify in the PDF — SVG previews can be misleading about text overflow.
|
||||
|
||||
25. **Mechanics rect too small** — Some SVGs have a mechanics `shape-inside` rect (#rect17) with an abnormally small height (e.g. 84 instead of ~239), causing mechanics text to clip mid-sentence with blank space below. Compare against a working card in the same tier and fix the rect dimensions. Standard mechanics rect height is ~238.70943.
|
||||
|
||||
26. **FLAVOR_COLORS in generate-card.py has wrong mark colors for Magic and Utility.** The `FLAVOR_COLORS` dict says Magic=`#9966cc` and Utility=`#ff9933`. These may be correct for gradient stops or price tag backgrounds, but the mark tick colors across ALL tiers (Specialist through Grandmaster) are Magic=`#c34cff` and Utility=`#ffcc00`. When `set_flavor_marks` clones from an existing template mark, it inherits the correct color. But when creating marks from scratch (no template), it falls back to `FLAVOR_COLORS` and produces wrong colors. Always verify against existing single-flavor cards in the same tier. Use `scripts/check-flavor-marks.py` to audit. Also: `MARK_WIDTH` (1.5875) doesn't match Specialist card marks (0.76627). Copy geometry from a known-good card in the same tier.
|
||||
|
||||
### Editorial pass status (pre-print review)
|
||||
|
||||
@@ -311,7 +319,7 @@ Lore in ITEMS.md is tagged with a `Lore source` field:
|
||||
| 0b Intermediate | Yes | Lore done (2026-04-16) | Full Claude Opus lore; opening restructure complete (3 items); 5etools JSON generated |
|
||||
| 0c Specialist | Yes | Lore done (2026-04-16) | Full Claude Opus lore; opening restructure complete (49 items); mechanics editorial done (2 passes); dual-flavor marks fixed; PDFs+packs rebuilt; 5etools JSON generated; DC 13 gap remains |
|
||||
| 1 Capable | Yes | Done (2026-04-16) | Full editorial: 29 lore rewrites, DC standardization, potion RAW cleanup, throwable subheads, bold typography, 2 editorial passes from PDF. Complete. |
|
||||
| 2 Expert | Yes | Lore mostly done (105/110 claude-opus) | Lore rewritten; 5 items remain non-claude; DC 13 gap remains |
|
||||
| 2 Expert | Yes | Done (2026-04-17) | Full editorial: 13 lore rewrites, DC standardization, potion/throwable/bold/subhead/spell-name fixes, 2 human editorial passes (text + PDF visual). Complete. |
|
||||
| 3 Master | Printing | Done (2026-04-16) | Typography, DCs, mechanics, lore closers all fixed; 57 OpenClaw lore still to rewrite; replacement set printed |
|
||||
| 4 Grandmaster | No | Pending | Mechanics merged, 110 Claude lore, 30 OpenClaw lore to rewrite; needs editorial review before printing |
|
||||
| 5 Exit | No | Pending | Lore restored from archive; 21 OpenClaw lore to rewrite; needs editorial review before printing |
|
||||
|
||||
Reference in New Issue
Block a user