design-lark-chart

design-lark-chart

Transform user input into a compliant, readable, uploadable Feishu whiteboard diagram. This skill is nota template collection, but rather acontent-driven + style-injection + closed-loop quality-checkpipeline.

Positioning

• Input: natural-language requirements / Feishu document URL / structured business checklist
• Intermediate artifact: routed and written to disk according to data/design-lark-chart/<session>/
• Final artifact：
  • DSL path:board.json（@larksuite/whiteboard-cli DSL v2）
  • SVG high-fidelity path:diagram.svg + board.openapi.json(generated by whiteboard-cli -f svg --to openapi )
  • Code-native path:diagram.mmd / diagram.puml
  • Both must be accompanied by real exported Feishu images and quality-gate evidence

Format boundary notes

This skill will simultaneously work with code syntax and three kinds of JSON, but theyare not the same layer of thing：

• diagram.mmd / diagram.puml: Mermaid / PlantUML source. Used only for scenarios natively supported by Feishu as code diagrams, such as sequence diagrams, state machine diagrams, and standard flowcharts.

• assets/raw/<id>.json: exported from a reference Feishu whiteboardofficial raw structure, with the most complete information, including node details and underlying fields; used only for review and style extraction,must not be passed directly to the Planner。
• assets/style-tokens/<id>.json: thestyle fingerprintextracted from raw, retaining only color palette / font size / shape / connector preferences; this is the basis for the Planner's settlement style_budget .
• <session>/board.json：@larksuite/whiteboard-cli supported DSL v2, which is the declarative whiteboard description written out during the Render stage; it is not the Feishu raw protocol itself, but a higher-level input format that is more layout-friendly.

The relationship is as follows:

参考飞书画板
  -> raw/<id>.json
  -> style-tokens/<id>.json

用户语义输入
  + style-tokens/<id>.json
  -> plan.json
  -> board.json (DSL v2)
  -> whiteboard-cli --to openapi
  -> board.openapi.json / 飞书可写入的原始结构
  -> lark-cli whiteboard +update

It must be made clear:

1. DSL v2 is not a complete mirror of the official Feishu raw protocol. It is whiteboard-cli a higher-level input format supported byminimal verifiable subset(see references/05-render-dsl.md）。
2. It cannot be assumed that any DSL can losslessly cover all of raw's capabilities. For things like complex decorations, custom details, and certain special connector behaviors, raw may be able to express them, but DSL may not have an equivalent way to write them.
3. Not all diagram types must go through DSL. For code diagrams natively supported by Feishu Whiteboard, prefer going through diagram.mmd / diagram.puml -> lark-cli whiteboard +update --input_format mermaid|plantuml -> Feishu read-back code and diagram export acceptance. For system-architecture / matrix-quadrant / sketch-architecture diagram types that strongly depend on the preview aesthetic, prefer the SVG high-fidelity path, then convert to OpenAPI and write to the whiteboard.
4. This skill's guarantee method is not "verbally believing it is convertible", but actually running through the corresponding route's check chain every time. The DSL path must pass whiteboard-cli --check; the SVG path must pass whiteboard-cli -f svg --check, OpenAPI conversion, and dedicated lint; the code path must pass +query --output_as code round-trip and real Feishu diagram export acceptance.
5. Only diagram types that fall within the currently verified DSL / SVG / Mermaid / PlantUML subset and have been verified through actual writing and Feishu retrieval count as supported. Unverified diagram types must not be promised externally just because they "theoretically should be convertible".

When to trigger

Trigger signal	Description
The user explicitly says "draw an XX architecture diagram / flowchart / sequence diagram / swimlane diagram / state machine / ER diagram / mind map..."	Hit 02-chart-taxonomy.md one of the 17 fixed diagram types to trigger
The user requests "free drawing / product prototype / game page / Sankey diagram / roadmap / illustration", and the fixed diagram types cannot cover it	Trigger freeform-drawing, go through SVG -> OpenAPI -> Feishu whiteboard
The user provides a Feishu docx / wiki URL and requests "add a diagram / draw a diagram / draw it for me"	First read the document, extract semantics, then go through the full pipeline
The user says "sync to Feishu / write to the whiteboard / generate a Feishu whiteboard"	The last step goes through lark-cli whiteboard +update

Fixed diagram types currently supplemented with structural verification examples (17 in total):

• business-architecture
• system-architecture
• flowchart
• swimlane
• sequence
• mindmap
• org-chart
• state-machine
• er-diagram
• funnel
• gantt
• milestone
• matrix-quadrant
• link-architecture
• lark-style-architecture
• sketch-architecture
• complex-swimlane

Additionally, 1 non-templated free mode is supported:

• freeform-drawing: triggered when the user's requirement does not belong to the above fixed diagram types, but explicitly requires visual expression, product prototypes, complex infographics, illustrated diagrams, or custom charts in a Feishu whiteboard. This mode must go through svg-openapi, using SVG as the design source, then converting to OpenAPI to write into the Feishu whiteboard; it must not add hardcoded renderers or solidify a certain acceptance example into a template.

Note: all 17 diagram types have been supplemented with reusable examples, butthey are no longer required to all be JSON. Among them:

• sequence / state-machine / standard flowchart preferentially use .mmd
• mindmap / er-diagram preferentially use .mmd(can switch to .puml）
• funnel continue using DSL JSON, but must satisfy the color layering and no-outer-frame constraints
• Whether the remaining diagram types use DSL is subject to 02-chart-taxonomy.md and 05-render-dsl.md routing rules

For release status and coverage definitions, see references/COVERAGE_REPORT.md。

When not to trigger

• Concepts that can be explained clearly in one or two sentences (no diagram needed)
• What the user wants is a Markdown table, code snippet, or process checklist (not a visual diagram)
• The user explicitly wants "inline SVG written into a markdown document" (that is a different matter, do not confuse it with the Feishu whiteboard)

Hard constraints (fall back on error)

These constraints take priority over "looking good":

1. No hardcoded templates: do not write a renderer with "fixed N layers + fixed colors + fixed copy" for any diagram type. All structures are dynamically produced by the Planner stage based on user input.
2. No hardcoded coordinates: all geometry is determined by the flex / dagre layout engine of whiteboard-cli , or calculated by pure functions in the Layout stage based on the number of nodes. Magic constants like x=340 are not allowed to appear in the code.
3. No hardcoded styles: all colors / font sizes / corner radii / line widths must come from assets/style-tokens/<id>.json. New colors / new font sizes are not allowed to be introduced temporarily in the Render stage.
4. No content fabrication：Normalizer / Planner must notSupplement hierarchy, modules, roles, or nodes that do not appear in the user's original text. Technical sentinel nodes (such as start/end in a flowchart) may be added, but must be explicitly marked auto-added。
5. Do not skip quality gates：whiteboard-cli --check If errors > 0 or any VQA score < 9 or a blocker appears, delivery is not allowed.

Pipeline

See references/01-pipeline.md。

Normalize → Select → Plan → Layout → Render → StaticCheck → VQA → Deliver

For each step, theinput/output/failure fallbackare all provided in the table in 01; follow what is in it.

Reference materials

The 15 standard whiteboards pulled from the official Feishu "Feishu Whiteboard.skill" document (Lww3d2rfwoE1SYxHtHicurYUn5d) serve asstyle references, with the trio consolidated as follows:

assets/
├── previews/<id>.png          # 视觉锚，给多模态 LLM 看
├── raw/<id>.json              # 原始节点结构，审查时查阅；禁止传给 LLM
└── style-tokens/<id>.json     # 抽取出的风格指纹（色板/字号/形状/连线）
    _catalog.json              # 跨图聚合的 house_style

Only reference the style(color palette, font size, corner radius, connector preferences),do notapply templates,do notcopy business copy,do notcopy coordinates. See references/02-chart-taxonomy.md and references/03-style-system.md。

references index

Organized by responsibility, read as needed:

File	When to read
references/01-pipeline.md	Must-read for every generation, to become familiar with the eight-step pipeline and fallback matrix
references/02-chart-taxonomy.md	Read during the Select stage when choosing diagram types
references/03-style-system.md	Read during the Plan stage when selecting style_budget, and during the Render stage when applying colors
references/04-planner-contract.md	Must-read during the Plan stage when producing plan.json (strict schema)
references/05-render-dsl.md	Read during the Render stage when choosing the DSL / Mermaid / PlantUML route; must-read when using DSL
references/06-quality-gates.md	Gate A/B execution + validation by route + VQA rubric + circuit-breaker rules
references/07-premium-style-contracts.md	Generate system-architecture / matrix-quadrant / sketch-architecture, or must-read when the user requests "more advanced / closer to the example diagrams / Feishu Whiteboard style"
references/08-freeform-svg-mode.md	Must-read when fixed diagram types cannot cover the need, or when the user requests free visual expression such as product prototypes, game pages, Sankey/roadmap/illustration

scripts

Script	Purpose	When to run
scripts/fetch_reference_boards.sh	Pull 15 reference whiteboards from the official docx into assets/	On first deployment / when references are updated
scripts/extract_style_tokens.py	Extract style tokens from assets/raw/ into assets/style-tokens/	After reference whiteboards change
scripts/check_board.sh	whiteboard-cli --check, Gate A gate	Run after every Render
scripts/lint_lark_style_architecture.py	Check whether the Feishu advanced architecture diagram has degraded into simple layered boxes	lark-style-architecture After the DSL Render of
scripts/lint_premium_style.py	Check whether the system architecture diagram / matrix quadrant diagram / hand-drawn style architecture diagram has degraded into an ordinary box diagram	After SVG or DSL Render for the three diagram types
scripts/lint_svg_quality.py	Check the platform compatibility, diagram fingerprint, color source, and visual density of free SVG. Optional --style-seed <id> Borrow the color palette of a fixed token, optional --plan <path> Preferentially use plan.style_budget as the allowed color set, with --strict-budget reject supersets	freeform-drawing After and strong visual SVG Render
scripts/render_freeform.sh	Freeform mode end-to-end gate wrapper: validate freeform_brief.json schema → whiteboard-cli -f svg --check(determined by the brief.allowed_check_warnings whitelist) → lint_svg_quality.py --plan/--style-seed → --to openapi Integrated output board.openapi.json and render_freeform.report.json	freeform-drawing The path must be run (replacing manual chaining of check + lint + convert)
scripts/render_preview.sh	Render PNG locally	After Gate A passes, before VQA

All scripts write artifacts to data/design-lark-chart/<session>/，by default; do not commit to git（data/ is already in .gitignore）。

examples

• references/examples/smoke_board.json: the minimal runnable DSL v2 file, used to verify check_board.sh and render_preview.sh are available on this machine.Not a template, do not copy the business logic.
• references/examples/<chart-type>.json: an end-to-end verification example for the DSL path chart type.
• references/examples/<chart-type>.mmd / references/examples/<chart-type>.puml: an end-to-end verification example for the code-native chart type.

Process for extending new chart types (when the 17 types do not cover it)

1. Obtain the style reference board token, append it to data/design-lark-chart/reference_boards.json。
2. Run scripts/fetch_reference_boards.sh to pull png/raw.
3. Run scripts/extract_style_tokens.py to generate the new <id>.json and refresh the catalog.
4. Append the new id to references/02-chart-taxonomy.md 's table, and fill in signals/structure/fallback.
5. Do not change any hardcoded template— new chart types should preferentially be resolved by extending data and routing; only when the capability boundary of the Feishu code chart changes is it permissible to adjust the routing rules.

Final verification before delivery (none may be missing)

• If using DSL:<session>/board.json All colors of plan.style_budget can be traced back in
• If using DSL:<session>/check.json 's errors=0, warnings=0, issues=[]
• If using SVG:<session>/svg_check.json has no issues, and the corresponding lint passes (for strongly visually fixed chart types run lint_premium_style.py; in freeform mode you must run scripts/render_freeform.sh <session>, which uniformly produces render_freeform.report.json and ok=true, and running only one of the steps by hand is forbidden)
• If using code charts:<session>/roundtrip.code.json the source code can be read back, and syntax_type matches expectations
• Based onreal Feishu-side exported imagescomplete Gate B; if read-back fails immediately after updating, first wait about 2 seconds and retry, then determine whether it is a real blocker
• The session directory is complete and contains the required artifacts for the corresponding route

If any is not satisfied: stop delivery and return to the corresponding stage to fix (see 06-quality-gates.md 's fallback matrix).

Coverage

Pre-release coverage is shown in references/COVERAGE_REPORT.md. Each time a chart type is added or downgraded, the coverage definition must be updated accordingly; if a Gate B blocker still exists, it must not be released externally.