Core principle: every section must have a visual anchor
Plain text walls are prohibited. Any content block longer than 3 lines must include at least one visual element.
| Content type | Required element |
|---|---|
| Important notes / cautions / conclusions | <callout> callout |
| Side-by-side comparison / left-right partitions | <grid> columns |
| Multi-column structured data (including code/lists) | <lark-table> enhanced table |
| Process / architecture / sketch | <whiteboard> whiteboard |
| Commands / code | Code block ``` + language annotation |
| Key terms / emphasized words | <text color="..."> inline coloring |
| Plain-text data comparison (≤3 columns) | Markdown standard table `|--- |
Quick decision: which element to use
There is an important note → callout
Color quick reference: 💡light-blue tip | ⚠️light-yellow warning | ❌light-red danger | ✅light-green success | 📌pale-gray note
There is comparison / side-by-side content → grid with 2 columns Put "old/problem/method A" in the left column and "new/solution/method B" in the right column
There is a list of tools/options, and cells contain code → lark-table
For plain-text tables, use Markdown directly |---|, and use lark-table only when rich-text cells are needed
There are process steps → ordered list + code block combination Use a whiteboard only for complex architecture diagrams; for simple processes, use an indented ordered list
There are important terms → inline coloring
<text color="blue">关键术语</text> or <text background-color="yellow">高亮</text>
Document structure rules
- There must be a callout at the beginning — 1-2 sentences explaining the document's purpose and intended readers
- At least one non-plain-text element in each H2 section(one of table/columns/callout/code block)
- Comparison scenarios must use columns — "traditional vs new", "pros vs cons", "solution A vs solution B"
- Data with more than 3 key-value pairs → table, not a list
- End with a callout or
---to close, do not let the document "break off" in an ordinary paragraph
Document type templates
Load the corresponding template according to the content type:
- templates.md — complete skeleton for technical exploration, project proposals, meeting minutes, and status reports
- element-guide.md — detailed syntax for each element + combination patterns + counterexamples
Collaboration with lark-doc
This skill determinescontent structure and visual design, lark-doc executes lark-cli docs +create / +update。
Before writing, ask three questions:
- Is this section data/comparison → table or columns
- Is this section notes/conclusions → callout
- Is this section steps/process → ordered list + code block