`, no `page-break` |
| **Multi-Page** (exception) | User explicitly requests separate pages (e.g., "make a 4-page booklet") | Multiple `
` with `page-break-after: always` |
> **Default = Single Canvas.** A poster is ONE design composition, not a paginated report. Multi-page is only for booklets/multi-page documents where the user explicitly asks for page separation.
#### ★★★ Dynamic Height (Anti-Blank-Bottom Iron Rule)
**NEVER hardcode `@page { size: W H }` or `.poster { min-height: Xpx }` with a fixed height.** This creates blank space at the bottom when content is shorter than the hardcoded value.
**Correct approach — use `html2poster.js`:**
`html2poster.js` automatically handles all of this — you just need to write the HTML correctly and call one command:
```bash
node "$PDF_SKILL_DIR/scripts/html2poster.js" poster.html --output poster.pdf --width 720px
```
It will automatically:
1. Add `overflow: hidden` to `.poster` container (clips decorative overflow)
2. Inject `@page { margin: 0 }` (zero margins)
3. Sync `html/body` background with `.poster` background
4. Measure `.poster` scrollHeight (actual content height)
5. Generate single-page vector PDF with exact dimensions
**⚠️ Do NOT use `html2pdf-next.js` for posters.** It is designed for multi-page documents and will inject 20mm margins / A4 pagination.
**⚠️ Do NOT write hand-written Playwright scripts for posters.** `html2poster.js` handles everything.
```css
/* ✅ CORRECT CSS for poster HTML (html2poster.js handles the rest): */
html, body { margin: 0; padding: 0; background: var(--c-bg); }
.poster { width: 720px; position: relative; background: var(--c-bg); }
/* Note: overflow:hidden on .poster is auto-injected by html2poster.js,
but including it in CSS is fine too */
```
**CSS iron rules:**
```css
html, body { margin: 0; padding: 0; background: var(--c-bg); }
/* Single poster canvas — NO fixed height */
.poster {
width: 720px;
position: relative;
overflow: hidden;
background: var(--c-bg);
/* Height is determined by content, measured at render time */
}
/* Card/content block */
.card {
background: rgba(255,255,255,0.7);
border-radius: 12px;
padding: 24px 28px;
margin-bottom: 20px;
/* No height, no max-height, no overflow:hidden */
}
/* CJK text iron rules */
.card, .card p, .card li {
text-align: left; /* Absolutely no justify! CJK stretches letter-spacing */
line-height: 1.6;
word-break: break-all; /* CJK natural line break */
}
/* Image */
.hero-image {
width: 100%;
border-radius: 8px;
margin-bottom: 20px;
display: block;
}
```
**HTML structure template (Single Canvas):**
```html
...
南京
... attractions ...
... food ...
...
```
**Why it's stable:**
- No fixed height — content naturally defines poster size
- No `overflow: hidden`, text always fully displayed
- `text-align: left` avoids CJK letter-spacing stretch
- Single canvas = one unified composition, not chopped pages
- PDF height measured at render time = zero blank space
**Convert to PDF and PNG:**
```bash
# PDF (vector, single-page, zero margins, auto-height):
node "$PDF_SKILL_DIR/scripts/html2poster.js" poster.html --output poster.pdf --width 720px
# PNG preview (screenshot):
# Use Playwright screenshot with measured height
```
> **⚠️ Do NOT write hand-written Playwright `page.pdf()` scripts.** Use `html2poster.js` which handles overflow:hidden, margin:0, background sync, and height measurement automatically.
### 12.2 Blueprint Grid Approach (Only for Simple Posters)
| Behavior | Status | Notes |
|------|------|------|
| Dynamic inset | ✅ Fixed | More content → smaller inset (`8% 10%`), less content → default (`10% 12%`) |
| Glass Canvas overflow | ✅ Fixed | `min-height:100%` replaces `height:100%`, removed `overflow:hidden` |
| Glass Canvas / Process List stretch | ✅ Fixed | Auto `align-items: stretch` |
### 12.3 Poster Marker in Blueprint
Add `scene: "poster"` marker in `art_direction` so `design_engine.py` can identify poster scenes and apply specific logic in the future:
```json
{
"art_direction": {
"scene": "poster",
"palette_mode": "minimal",
"color_harmony": "auto",
"background_svg": "flow",
"design_rationale": "..."
}
}
```
---
---
## 14. PDF Conversion Iron Rules
### 14.1 Background Color Consistency
```css
/* Must ensure html/body background = poster canvas background */
html, body {
background: var(--c-bg); /* Same color as .canvas background */
}
```
- Playwright `page.pdf({ printBackground: true })` renders body background color
- If body is white but poster is gray, white borders appear in the PDF
- `design_engine.py` already auto-injects `background: var(--c-bg)`, but if bypassing the engine and writing HTML directly, **you must ensure manually**
**Multi-page posters / brochures with mixed page backgrounds:**
- When pages alternate between dark and light backgrounds, set `body { background }` to the **darkest page color** (see SKILL.md "Background Color Consistency" for full rationale)
- This eliminates sub-pixel white edges on dark pages without affecting light pages
### 14.2 Content Centering (Anti-Drift)
**Poster content must be centered in the PDF, no left or right drift allowed.**
Common drift causes and fixes:
| Cause | Fix |
|------|------|
| `@page { margin }` not 0 | Must be `@page { size:
; margin: 0; }` |
| `.safe-zone` `inset` left-right asymmetric | Ensure `inset: Y% X%` uses same X% for left and right |
| Component `grid_area` only uses partial columns | Most components should span `1 / 1 / X / 13` (full width) |
| Content container has `max-width` but no `margin: 0 auto` | Add `margin: 0 auto` to center |
| Playwright PDF default margin | Pass `margin: { top: 0, right: 0, bottom: 0, left: 0 }` |
### 14.3 Anti-Blank Edges (Dynamic Height Iron Rule)
**Poster edges, top, and bottom should not have large meaningless whitespace.**
**★★★ CRITICAL: Never hardcode poster height.** The poster is a single continuous canvas — its height is defined by content, not by a fixed CSS value.
| Pattern | Status | Result |
|---------|--------|--------|
| `@page { size: 720px 3600px }` | ❌ FORBIDDEN | Creates 853px+ blank space at bottom if content is shorter |
| `.poster { min-height: 3600px }` | ❌ FORBIDDEN | Same problem — blank bottom |
| `.poster { width: 720px }` (no height) | ✅ CORRECT | Content defines height naturally |
| `node html2poster.js poster.html --width 720px` | ✅ CORRECT | Auto-measures height, zero blank space |
**The 720×960 dimension is for multi-page documents with `page-break-after: always` only — NOT for single-canvas posters.**
- Content must make full use of page area, no more than 20% unused space within safe-zone
- If excess whitespace exists, enlarge font sizes or modules to balance the layout
- Checklist:
- [ ] Poster height defined by content (no hardcoded height)?
- [ ] PDF generated via `html2poster.js` (not html2pdf-next.js)?
- [ ] First component starts from the top?
- [ ] Last component reaches the bottom with proper padding?
- [ ] Left-right margins symmetric?
- [ ] No blank space at bottom of PDF?
---
## 15. Preflight Checklist (Poster-Specific)
Before outputting JSON Blueprint, verify the following items:
```
□ ★ Single-canvas check: poster is ONE continuous , not split into separate pages? (unless user explicitly requests multi-page)
□ ★ Dynamic height check: no hardcoded @page size height or .poster min-height? PDF generated via html2poster.js?
□ ★ Anti-modularization check: ≤ 3 containers with background+border in single-page poster? No 2×2 card grid? Hierarchy via font size/weight not border colors?
□ Emphasis elements (price/date/address) highlighted via font size+weight, not wrapped in separate color blocks?
□ Overall looks like a design piece, not an APP interface or dashboard?
□ total_pages = 1 (single canvas)? (unless user explicitly requests multi-page booklet)
□ No hardcoded @page height or .poster min-height? Content defines height?
□ Left-right margins symmetric? (no left/right drift)
□ html/body background = poster canvas background? (no color mismatch)
□ No bottom blank space in PDF? (height measured dynamically)
□ Page main title ≥ 50px? Body text ≥ 24px?
□ Text volume ≤ 150 chars? (single Glass Canvas)
□ palette_mode not #FFFFFF pure white?
□ No single image filling the background?
□ No overlap between cards?
□ No Timeline / complex SVG structure diagrams?
□ All content fully displayed, not truncated?
□ Emphasis text font size < title font size?
□ Entire design ≤ 3 fonts?
□ cover_hero page ≤ 4 components?
□ Hero_Typography has
line breaks?
□ @page { margin: 0 } set? (prevents PDF drift)
```