kami-paper

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              # build all templates + page count + font check + slides
python3 scripts/build.py --verify resume-en    # single target full verification
python3 scripts/build.py --verify slides       # single slide deck verification
python3 scripts/build.py --check-placeholders path/to/filled.html
python3 scripts/build.py --check-density       # page whitespace scanner (skips cover)
python3 scripts/build.py --check               # CSS rule violations only (fast, no build)

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.