Whiteboard Cli Skill

Whiteboard Cli Skill

Create and collaborate on Lark whiteboards with programmatic content control

Category: design Source: larksuite/cli

What Is the Whiteboard Cli Skill?

The Whiteboard Cli Skill (lark-whiteboard) is a powerful integration for the Happycapy Skills platform, enabling users to create, edit, and collaborate on Lark (Feishu) whiteboards through programmatic control. This skill is designed for technical, product, and design teams who need to generate architecture diagrams, flowcharts, mind maps, sequence diagrams, and other visualizations directly into Lark whiteboards. It leverages the @larksuite/whiteboard-cli and lark-cli Node.js command-line tools, allowing for automated and reproducible whiteboard content creation with precise control over layout, color, and structure.

Unlike static diagrams, Lark whiteboards provide an infinite canvas where users can freely position elements, connect ideas, and iterate visually. The Whiteboard Cli Skill bridges the gap between automated content generation and collaborative design workflows, making it ideal for teams that require both rigorous structure and flexibility.

Why Use the Whiteboard Cli Skill?

The Whiteboard Cli Skill addresses several pain points common in technical diagramming and visual collaboration:

  • Programmatic Generation: Quickly produce complex diagrams (such as layered system architectures or custom flowcharts) from source code, scripts, or structured content without manual drawing.
  • Visual Consistency: Enforce consistent layout, color schemes, and typography across diagrams by following predefined schemas and style guides.
  • Collaboration in Lark: Directly upload and share visualizations in Lark whiteboards, supporting real-time collaboration and feedback.
  • Flexible Layouts: Choose between layered flex layouts, absolute positioning, or hybrid island-style arrangements to match the complexity and semantics of the content.
  • Reproducibility: Automate whiteboard generation as part of documentation pipelines, reducing errors and manual effort.

This skill is particularly useful for teams using Lark as their central collaboration platform and needing robust, repeatable methods for producing technical visuals.

How to Use the Whiteboard Cli Skill

Prerequisites

  • Node.js 18+ is required.
  • Install the following command-line tools globally:
    npm install -g @larksuite/whiteboard-cli@^0.1.0 lark-cli
  • Ensure the user consents before installing new dependencies.

Workflow Overview

1. Routing and Knowledge Reading

  • Determine rendering path: Decide whether to use Mermaid syntax (for fallback) or the dedicated DSL (domain-specific language) for whiteboard content.
  • Read scene guide: Understand the structure and layout strategy based on the intended diagram type (architecture, flowchart, etc.).
  • Select layout strategy: Refer to quick judgment criteria (see below) to pick the right layout approach.
  • Review core modules: Consult references for syntax, layout patterns, color schemes, typography, and connectors.

2. Generate the Complete DSL

  • Plan content: Organize information and groupings based on source content.
  • Choose layout: Select appropriate layout mode and spacing.
  • Apply styling: Use specified or default color palettes and typographic settings.
  • Produce schema: Output a complete JSON definition for the whiteboard using the required schema.
  • Special cases: For advanced diagrams (e.g., fishbone, flywheel), write JavaScript scripts that generate the JSON structure programmatically:
    node generate-diagram.js > diagram.json

3. Render and Review

  • Self-check before rendering: Ensure information is complete, layout is logical, and colors are harmonious.
  • Render to PNG: Use the CLI to render the whiteboard as a PNG image for review.
  • Quality assurance: Check for text truncation, line overlaps, and overall readability.
  • Iterate if needed: Fix issues and re-render, with up to two revision cycles. If major problems persist, consider falling back to Mermaid rendering.
  • Delivery: If the user requests, upload the whiteboard to Lark. Otherwise, present the PNG image as output.

Example: Generating a Simple Architecture Diagram

Suppose you want to generate a three-layer architecture diagram. Prepare a JSON schema as follows:

{
  "type": "flex",
  "nodes": [
    { "id": "user", "label": "User Layer", "color": "#4A90E2" },
    { "id": "service", "label": "Service Layer", "color": "#50E3C2" },
    { "id": "data", "label": "Data Layer", "color": "#B8E986" }
  ],
  "edges": [
    { "from": "user", "to": "service" },
    { "from": "service", "to": "data" }
  ]
}

Render the diagram:

lark-whiteboard render diagram.json --output=diagram.png

Upload to Lark (if required):

lark-whiteboard upload diagram.json

When to Use the Whiteboard Cli Skill

  • Technical Documentation: Automate the generation of system architecture, data flow, or infrastructure diagrams.
  • Design Sprints: Quickly create and iterate on mind maps or user journey flows during workshops.
  • Product Reviews: Present process diagrams or feature maps in Lark whiteboards for stakeholder review.
  • Education & Training: Produce interactive diagrams for onboarding or instructional materials.

Choose this skill when you need detailed, programmatically controlled visualizations delivered directly to a Lark whiteboard, especially if your use case demands layout precision and collaboration.

Important Notes

  • Skill requires both @larksuite/whiteboard-cli and lark-cli. Installation must be explicitly approved by the user.
  • Always check output quality: Review the rendered PNG for completeness, legibility, and correctness before delivery.
  • Layout strategy is crucial: Select the right approach (layered, absolute, hybrid) based on diagram semantics. Some diagrams require scripts to generate coordinates.
  • Fallback to Mermaid: If the whiteboard approach fails after two iterations, switch to Mermaid rendering for reliability.
  • Whiteboard is not a webpage: The skill is optimized for visual canvas layouts, not for HTML-style responsive layouts.

By following this structured workflow, the Whiteboard Cli Skill enables seamless, automated diagram creation and real-time collaboration within the Lark ecosystem.