| name | kami-paper |
| description | Typeset professional documents: resumes, one-pagers, white papers, letters, portfolios, slide decks. Warm parchment canvas, ink-blue accent (#1B365D), serif-led hierarchy. CN uses TsangerJinKai02, EN uses Charter, JA uses YuMincho (best-effort). Triggers on "做 PDF / 排版 / 一页纸 / 白皮书 / 作品集 / 简历 / PPT / slides", or "build me a resume / make a one-pager / design a slide deck / turn this into a PDF / make this presentable". Eight document types and fourteen SVG diagram primitives with auto-selection from data. |
kami-paper
Kami (紙, かみ) - the paper your deliverables land on.
Good content deserves good paper. One design language across eight document types: warm parchment canvas, ink-blue accent, serif-led hierarchy, tight editorial rhythm.
Workflow
Step 0: Load brand profile (if exists)
Check ~/.config/kami/brand.md (preferred) or ~/.kami/brand.md (legacy fallback). If found, read references/brand-profile.md for the four-layer application spec. If no profile exists, continue without interruption.
Key rule: explicit prompt > editorial judgment > habit notes > frontmatter defaults > built-in defaults. Profile fills gaps silently; it never overrides the current conversation.
Step 1: Decide the language
Match the user's language. When ambiguous, ask a one-liner rather than guess.
| User language | HTML templates | Slides (PDF default) | Slides (PPTX fallback) |
|---|
| Chinese (primary) | assets/templates/*.html | assets/templates/slides-weasy.html | assets/templates/slides.py |
| English | assets/templates/*-en.html | assets/templates/slides-weasy-en.html | assets/templates/slides-en.py |
| Japanese (best-effort) | CJK path | slides-weasy.html | slides.py |
Default to the WeasyPrint HTML path; fall back to PPTX only when the user explicitly needs an editable deck.
Always use CHEATSHEET.md and references/*.md for design, writing, production, and diagram guidance.
Step 1.5: Intent extraction (silent checklist)
Before choosing a template, verify these four dimensions. Do not ask unless 2+ are missing and cannot be inferred from context.
| Dimension | What to extract |
|---|
| Purpose | Why this document exists |
| Audience | Who reads it, what they already know |
| Constraint | Hard limits on length, format, tone, delivery |
| Success | What outcome counts as success |
Rules: skip if already answered in conversation; skip if inferable from document type; ask a single compact question (max 2 sub-questions) if 2+ are unclear. Never ask all four as a checklist.
Step 2: Pick the document type
| User says | Document | CN template | EN template |
|---|
| one-pager / 方案 / 执行摘要 / exec summary | One-Pager | one-pager.html | one-pager-en.html |
| white paper / 白皮书 / 长文 / technical report | Long Doc | long-doc.html | long-doc-en.html |
| formal letter / 信件 / 辞职信 / 推荐信 / memo | Letter | letter.html | letter-en.html |
| portfolio / 作品集 / case studies | Portfolio | portfolio.html | portfolio-en.html |
| resume / CV / 简历 / 履歴書 | Resume | resume.html | resume-en.html |
| slides / PPT / deck / 演示 | Slides | slides-weasy.html | slides-weasy-en.html |
| 个股研报 / equity report / 估值分析 / 股票分析 | Equity Report | equity-report.html | equity-report-en.html |
| 更新日志 / changelog / release notes | Changelog | changelog.html | changelog-en.html |
Slides: default to WeasyPrint HTML PDF. Use python-pptx only if user explicitly requires editable PPTX.
Diagrams (primitives, not a separate template type)
When the user asks for a diagram inside a document, extract the <svg> block from assets/diagrams/ templates and drop it into a <figure>.
| User asks for | Diagram | Template |
|---|
| 架构图 / architecture / 系统图 | Architecture | architecture.html |
| 流程图 / flowchart / 决策流 | Flowchart | flowchart.html |
| 象限图 / quadrant / 优先级矩阵 | Quadrant | quadrant.html |
| 柱状图 / bar chart / 分类对比 | Bar Chart | bar-chart.html |
| 折线图 / line chart / 趋势 / 股价 | Line Chart | line-chart.html |
| 环形图 / donut / pie / 占比 | Donut Chart | donut-chart.html |
| 状态机 / state machine / lifecycle | State Machine | state-machine.html |
| 时间线 / timeline / 里程碑 / roadmap | Timeline | timeline.html |
| 泳道图 / swimlane / 跨角色流程 | Swimlane | swimlane.html |
| 树状图 / tree / hierarchy / 组织架构 | Tree | tree.html |
| 分层图 / layer stack / OSI / stack | Layer Stack | layer-stack.html |
| 维恩图 / venn / 交集 / overlap | Venn | venn.html |
| K线 / candlestick / OHLC / 股价走势 | Candlestick | candlestick.html |
| 瀑布图 / waterfall / 收入桥 | Waterfall | waterfall.html |
Read references/diagrams.md before drawing - it has the selection guide, kami token map, and AI-slop anti-patterns.
Auto-select charts from data (first match wins):
| Data shape | Chart |
|---|
| Has OHLC / per-day price | Candlestick |
| +/- contributions summing to total | Waterfall |
| One series, sums to ~100%, <= 6 items | Donut |
| One series, sums to ~100%, >= 7 items | Horizontal bar |
| Two+ series across time | Line |
| One series across time, count changes | Bar |
| Multiple categories, same snapshot, 2+ series | Grouped bar |
| 2x2 strategic positioning | Quadrant |
| Hierarchical data depth >= 2 | Tree |
| Process with decision branches | Flowchart |
| Cross-team process >= 3 actors | Swimlane |
| Set overlaps 2-3 groups | Venn |
| Category comparison, single series, no time | Bar |
Before drawing, always ask: would a well-written paragraph teach the reader less than this diagram? If no, don't draw.
Step 2.1: Source and material pass
Run before distilling when the document depends on facts outside the user's draft. Skip only for personal drafts where the user supplied everything.
Source check: Trigger when the document mentions specific companies, products, people, release dates, metrics, market facts, or technical specs. Use primary sources; keep notes of source names and dates; ask the user if sources conflict.
Material check: For documents about a company, product, or brand, confirm logo, product images, UI screenshots, brand colors. If a required item is missing, use a compact gap table and ask once. Do not replace missing material with generic imagery.
Output a materials status block: OK / MISSING / not required.
Step 2.5: Distill raw content (if applicable)
Auto-detect whether to distill. Do not ask; judge from the input:
| Skip distill | Run distill |
|---|
| Content has explicit section labels matching template | Raw prose without section structure |
| Metrics already quantified with units | Numbers scattered or implied |
| User said "use this as-is" / "原封不动" | Multi-source dump (chat/email/docs) |
| Content count matches template | Content count mismatches template |
| One coherent voice | Conflicting claims across sources |
When distilling: Extract (factual claims, numbers, dates, names) -> Classify (map to template sections per references/writing.md) -> Gap-check (list what template needs but content lacks) -> Ask once (share gap table, do not guess to fill).
Step 2.6: Deck pre-flight (slides only)
Default to WeasyPrint HTML path. Switch to PPTX only if user explicitly requires editable PPTX.
Page sizes: 280mm 158mm (default), 297mm 167mm (more room), 338mm 190mm (heavy content).
Content rules for slides:
- No section divider slides: use
.eyebrow for section numbering
- No CJK parentheses: replace
（...） with · or ,
- Each bullet fits one line: trim until it does
- 2x2 layouts: use
table.t2x2, not CSS Grid
- Pinned conclusions: use
.co at position: absolute; bottom: 12mm
Step 2.7: Layout note
Before loading specs and filling the template, write a short editor-style note under 80 words: template choice, length target, narrative arc, embedded diagrams, material status, output formats. This is for transparency, not approval. Continue immediately after.
Example (CN): "排版意图：Equity Report 中文版，2 页 A4。先立论与目标价，进入估值 (DCF 与可比公司)，落于催化剂与风险。中段嵌一张营收趋势折线和 FY26 收入桥瀑布。Logo 已就位，产品图暂缺，header 改走纯文字。输出 HTML 与 PDF。"
Example (EN): "Layout intent: Equity Report (EN), two pages A4. Open with thesis and price target, run through valuation (DCF and comparables), close on catalysts and risks. A revenue line chart and an FY26 waterfall sit mid-doc. Output: HTML and PDF."
Step 3: Load the right amount of spec
Pick the lowest tier that covers the work:
| Tier | When | Read |
|---|
| Content-only | Updating text, swapping bullets, translating. CSS untouched. | CHEATSHEET.md only |
| Layout tweak | Adjusting spacing, moving sections, font size within spec. | CHEATSHEET.md + template |
| New document | Building from scratch or from raw content. | Full design spec + writing spec + template |
| Resume content | Resume-specific bullet structure, framing. | references/resume-writing.md + template |
| Sources/materials | Company, product, market, branded subject. | references/writing.md source rules + material |
| Deck (>20 slides) | Long presentation. | references/design.md + Deck Recipe (design.md section 8) |
| Troubleshoot | Rendering bug, font issue, page overflow. | references/production.md |
| Anti-patterns | Reviewing AI-generated drafts before shipping. | references/anti-patterns.md |
| Diagram | Embedding SVG in a doc. | references/diagrams.md |
Full spec files:
- Design:
references/design.md
- Writing:
references/writing.md
- Resume writing:
references/resume-writing.md
- Production:
references/production.md
- Diagrams:
references/diagrams.md
- Anti-patterns:
references/anti-patterns.md
Step 4: Fill content into the template
- Copy the template from
assets/templates/ into working directory; don't write HTML from scratch
- CSS stays untouched, only edit the body
- Content follows
references/writing.md: data over adjectives, distinctive phrasing over clichés
- Avoid patterns in
references/anti-patterns.md: emptiness, fabrication, mimicry, excess, source gaps, tone contamination
- Before filling, read the quality bar for your document type in
writing.md section "Quality bars by document type"
Do not generate
- Do not leave placeholder text in the final document ("Lorem ipsum", "[Insert here]", "TBD")
- Do not invent metrics, financial data, or statistics; mark gaps with
[DATA NEEDED: description]
- Do not use stock-image descriptions as image placeholders
- Do not pad content to fill template slots
- Do not write a paragraph that merely restates its own heading
Fill PDF metadata
Every template has meta placeholders in <head>. Fill all four before building:
| Placeholder (CN) | Placeholder (EN) | Rule |
|---|
{{作者}} | {{AUTHOR}} | Resume/letter/portfolio: person's name. Others: leave as-is. |
{{摘要}} | {{DESCRIPTION}} | One sentence (<=150 chars) from first 2 paragraphs |
{{关键词}} | {{KEYWORDS}} | 3-5 keywords from title + headings |
{{文档标题}} etc | {{DOC_TITLE}} etc | Infer from H1 or .header .title |
<meta name="generator" content="Kami"> is fixed in templates; do not change.
Step 4.5: Auto-select output format
| Signal | Output |
|---|
| Any document request | HTML + PDF |
| Slides / PPT / deck | HTML + PDF + PPTX |
| "分享" / "发朋友圈" / "share" / "post" | + PNG |
| "嵌入" / "插图" / "embed" | PNG only |
| User explicitly says a format | Follow the user |
Step 5: Build & verify
python3 scripts/build.py --verify
python3 scripts/build.py --verify resume-en
python3 scripts/build.py --verify slides
python3 scripts/build.py --check-placeholders path/to/filled.html
python3 scripts/build.py --check-density
python3 scripts/build.py --check
Visual anomalies -> references/production.md Part 4.
Fonts
Chinese: Main serif TsangerJinKai02 (W04 for body, W05 for headings). Fallback chain: Source Han Serif SC -> Noto Serif CJK SC -> Songti SC -> STSong -> Georgia. Run bash scripts/ensure-fonts.sh once before building Chinese documents.
English: Charter (system-bundled on macOS/iOS). Fallback: Georgia / Palatino / Times New Roman.
Japanese: CJK template path with JP Mincho-first: YuMincho -> Hiragino Mincho ProN -> Noto Serif CJK JP -> Source Han Serif JP -> TsangerJinKai02 -> serif.
Feedback protocol
When the user gives vague visual feedback, do not guess. Ask back with current values:
| User says | Ask about |
|---|
| "太挤了" / "too cramped" | Which element? Line-height (current: X)? Padding (current: Y)? |
| "太松了" / "too loose" | Same direction, reversed |
| "颜色不对" / "color feels wrong" | Which element? Brand blue overused? |
| "不够好看" / "not polished" | Font rendering? Alignment? Whitespace? Hierarchy? |
| "看着不专业" / "unprofessional" | Content wording? Layout alignment/consistency? |
Never say "I'll adjust the spacing" without naming the exact property and its new value.
When not to use this skill
- User wants Material / Fluent / Tailwind / Bootstrap default aesthetics
- Need dark / cyberpunk / futurist aesthetic (deliberately anti-future)
- Need saturated multi-color (Kami uses one accent: ink-blue #1B365D)
- Need cartoon / animation / illustration style (this is editorial/print)
- Web dynamic app UI (this is for print / static documents)
Next: apply Step 3's tier table to decide what to read, then copy the matching template and start filling.
