--- name: typst description: Syntax guide and ecosystem reference for writing Typst (.typ) files. Use this skill when writing, editing, or debugging Typst documents. Covers core syntax, common errors, packages, and best practices. license: MIT --- # Typst Skill **Current version**: Typst 0.14.2 (Dec 2025) ## Smart Defaults If you know nothing else, follow these rules: 1. **Always** import `@local/qk:1.0.0` — `#import "@local/qk:1.0.0": *` 2. **Always** use `qk-doc` or `qk-report` preset (unless user specifies custom) 3. **Always** use touying for presentations (not raw page dimensions) — see `references/touying-guide.md` 4. **Always** `#set figure(placement: auto)` — prevents blank half-pages 5. **Always** add `alt:` to images — `image("path.png", alt: "description")` 6. **Always** escape `$` in content — scan for bare `$` before compiling 7. **Default fonts**: Libertinus Serif (body), Inter (headings), New Computer Modern Math (math), Fira Code (code) 8. **Default compile**: `typst compile --root .. Source/.typ` 9. **When in doubt** about template: Study Guide 10. **When in doubt** about visual tool: Typst native first → cetz-plot → matplotlib 11. **Always** scan project for existing `.typ` files and match their style (fonts, colors, qk preset) unless user specifies otherwise ## New Document Decision Tree ``` User request → scan for keywords: "resume/CV/job" → CV / Résumé template "slides/presentation" → Presentation (touying — metropolis default) "lecture/class/academic" → Academic Lecture (touying — university theme) "essay/thesis/paper" → Essay "report/brief/client" → Business Report "research/analysis" → Research Report "study guide/revision" → Study Guide "reference/glossary" → Annotated Reference "cheatsheet/reference card/formula sheet" → Cheatsheet template "exam/problem set/homework" → Exam template "flashcard/Q&A/quiz" → Flashcard template ambiguous? → ask purpose + audience → pick template ``` **Steps:** 1. Auto-detect template from keywords above 2. Import `@local/qk:1.0.0` at top 3. Use `qk-doc` or `qk-report` preset when applicable 4. Auto-select template. State choice in Phase 3 summary. User can re-invoke with explicit type override if wrong. 5. Build from `references/templates.md` 6. Custom styles are fine — templates are starting points, not constraints ## Visual Tool Routing (compact) | Need | Tool | |------|------| | Tables, boxes, grids | Typst native | | Flowcharts, trees, ER, state diagrams | `fletcher` | | Sequence diagrams | `chronos` | | Gantt charts | `timeliney` | | Simple charts (< 3 series) | cetz-plot | | Complex charts (4+ series) | matplotlib | | Mind maps | `/mindmap` (auto-invoke) | | Conceptual illustrations | `/nano-banana` (auto-invoke) | | Real photos, logos | `/image-search` (auto-invoke) | Detail and examples in `references/tool-routing.md`. ## Proactive Behaviors ### Visual Auto-detection When writing Typst documents, automatically identify content that benefits from visuals. Do NOT wait for the user to request them. Follow priority: Typst native → cetz-plot → `/image-search` → `/mindmap` → native packages → matplotlib → `/nano-banana`. | Content pattern | Visual to add | Tool | |-----------------|---------------|------| | Comparison grids, attribute tables | Styled table | Typst native | | Callout boxes, styled layouts | `rect()` / `block()` | Typst native | | Sequential steps, decision logic | Flowchart / decision tree | `fletcher` | | Process with inputs/outputs | Workflow diagram | `fletcher` | | System architecture, ER diagrams | Block / entity diagram | `fletcher` | | Hierarchy or taxonomy | Tree diagram | `fletcher` or `/mindmap` | | Topic overview, concept map | Mind map | `/mindmap` | | Request-response, API flows | Sequence diagram | `chronos` | | Project schedule, phases | Gantt chart | `timeliney` | | Historical events, evolution | Timeline | `herodot` or `timeliney` | | Data trends, distributions (< 3 series) | Line/area/scatter chart | cetz-plot | | Complex charts (4+ series, annotations) | Publication chart | matplotlib/Python | | Company logo, brand mark | Logo image | `/image-search --logo` | | Real-world photograph | Photo | `/image-search` | | Concept with analogy, metaphor | AI illustration | `/nano-banana` | See `references/tool-routing.md` for full examples, fallback chains, and auto-invoke rules. ### Content Structure - Suggest TOC (`#outline()`) at 4+ sections - Suggest file split at 40+ pages — see `references/common-patterns.md` "Large Documents" - Convert prose lists to tables when 3+ items with attributes ### Component Library Auto-use When writing content, automatically convert matching patterns to `@local/qk:1.0.0` components: | Content pattern | Use instead | |-----------------|-------------| | Warning paragraph | `warning[...]` | | Key point / takeaway | `keypoint[...]` | | Tip or best practice | `tip[...]` | | Common mistake / trap | `trap[...]` | | Step-by-step procedure | `step-box("Title", [...])` | | KPI or metric highlight | `stat-card("value", "label")` | ### Cross-referencing Add `