Creating documents with Notion's design
This skill governs only how the document looks. The outline, sections, and flow are decided by the content and the request — no particular document format (proposal, etc.) is imposed. Instead, every document is rendered with the blocks and design language Notion provides.
1. Header area (required)
- Page icon: one emoji matching the document's topic, large, above the title (Notion page icon)
- Title: a short noun phrase. In HTML, set
<title>to the exact same text as the<h1> - Meta line: date · author · 1–2 tag pills
- A thin divider below the meta line
2. Notion block dictionary — pick the block that fits the content
| Content | Block |
|---|---|
| Key takeaway, the one line to emphasize | Callout (blue 💡) |
| Reference, supplementary info | Callout (gray) |
| Done, success, what went well | Callout (green ✅) |
| Caution, constraints | Callout (yellow ⚠️) |
| Warning, incident, risk | Callout (red 🚨) |
| Opening of a long document (4+ h2s) | Table of contents (toc) |
| Parent document, location context | breadcrumb |
| Comparable, listable facts | simple table |
| Two chunks that belong side by side | 2-column layout |
| Long details or logs that break the flow | <details> toggle |
| Tasks, progress | checkbox list (done items get strikethrough) |
| Code | code block + class="language-<lang>" syntax highlighting (required) |
| One striking sentence | quote (bold left bar) |
| Introducing an external link | bookmark card |
| A single call-to-action link | button block (btn) |
| Word-level emphasis | bold, inline code, Notion text colors (t-blue etc., 5 colors) |
Never use blocks as decoration — only when they match a purpose in this table.
3. Visual style
HTML documents MUST start from the template.html skeleton in this skill's
directory. Do not write new CSS; use the template's classes as they are. The
template's palette and dimensions are Notion's actual design-token values
(see the comment next to each value). Core rules:
- 720px content width, centered, generous whitespace — measured values as-is
- Text color
#2C2C2B, 16px/1.5, white background, minimal decoration. No shadows, gradients, or heavy background colors - Rounded corners use only the
--radius(10px) token — shared by callouts, bookmarks, and code blocks - Colors come only from the template's tokens (5 callout colors, 5 text colors,
--tok-*code tokens) — no new colors - Light/dark palettes are built in as CSS tokens and follow the viewer's theme automatically
- Code highlighting is handled by the Prism scripts at the bottom of the template — just add the
language-*class - Korean line breaking (
word-break: keep-all) and print/PDF rules (@media print) are already in the template — do not add your own. The dark palette is wrapped in@media screen, so printing automatically falls back to light
For Markdown documents, apply the same sensibility: emoji + title (h1), a meta
line, callouts as > emoji **Title** — body quotes, tasks as - [ ]
checklists, code in language-tagged fences.
4. Verify after writing
After writing an HTML document, check it with lint.py from this skill's directory.
bashpython3 <skill directory>/lint.py doc.html
css-drift— you modified the template's<style>. Restore it and change only the bodyunknown-class— you invented a class. Pick one from the block dictionary in section 2inline-style·raw-color— you styled or colored the body directly. Use template classes instead
5. Interaction with other skills
- If another skill or host also governs presentation (a design-system skill, an artifact/preview host), take only its technical requirements — responsiveness, dark mode, sandbox constraints. This skill's style tokens take precedence
- If charts are included, follow whatever chart skill is available for color and mark choices, but keep the layout inside this template
