docs(slides): add whiteboard element documentation and improve slide guidance

[Huangwenbo-wb]

Summary

• Add comprehensive lark-slides-whiteboard.md reference covering SVG and Mermaid modes, rendering
  rules, element support, coordinate calculation, and quality checklist
• Clarify <chart> vs <whiteboard> selection across SKILL.md, asset-planning.md, and
  xml-schema-quick-ref.md
• Add <whiteboard> preference hints to visual-planning.md for architecture-diagram and process-flow
  layouts
• Add whiteboard validation limitations section to validation-checklist.md
• Fix SVG rendering rules: content area is determined by child element bounding box union;
  width/height/viewBox do not affect rendering; xmlns required for XML namespace parsing; viewBox
  only needed for percentage-based attribute values
• Correct linearGradient support status (supported; radialGradient is not)
• Add Python-based coordinate and bounding box calculation guidance

Test plan

• Review whiteboard reference doc for accuracy and completeness
• Verify <chart> vs <whiteboard> decision table covers common scenarios
• Check that all cross-file references (SKILL.md, asset-planning.md, visual-planning.md) are
  consistent

Summary by CodeRabbit

• New Features

  • Introduced whiteboard element for creating flow diagrams, sequence diagrams, architecture diagrams, and decorative patterns using SVG or Mermaid syntax.
  • Whiteboard can now be embedded as a root element in slide blocks.

• Documentation

  • Updated reference guides with whiteboard usage rules, positioning properties, SVG rendering conventions, and Mermaid diagram support.
  • Added validation guidance for whiteboard boundary constraints.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces comprehensive support for a new <whiteboard> element in Lark Slides, enabling diagram visualization via SVG or Mermaid within slide content. The change updates XML schema definitions, adds an extensive 330-line reference guide, and integrates whiteboard references throughout existing API operation, asset planning, and validation documentation.

Changes

Whiteboard Element Feature

Layer / File(s)	Summary
XML Schema and Element Definition skills/lark-slides/references/slides_xml_schema_definition.xml	SlideType.data choice is expanded to include sml:whiteboard reference. A new top-level whiteboard element is added as a complexType with required geometry attributes (topLeftX/Y, width/height), optional flip/alpha, and a content model that supports either mermaid text source or embedded SVG XML via xs:any. Optional border child using BorderType is also supported. Documentation for undefined element is updated to remove whiteboard from the "unsupported types" list.
Comprehensive Whiteboard Reference Guide skills/lark-slides/references/lark-slides-whiteboard.md	New 330-line reference covering whiteboard purpose, geometry attributes, and SVG vs. Mermaid decision flow based on diagram type and model identity. SVG mode details include rendering rules, supported elements, color/dash/transform conventions, layout patterns (full-screen overlay, sidebar, footer), and coordinate computation via Python. Prohibited SVG features are listed with alternatives. Mermaid mode covers XML/CDATA usage, supported chart types, recommended sizes, and z-order considerations. Quick self-inspection checklist for SVG, Mermaid, and common validation points provided.
Quick Reference and Skill Documentation skills/lark-slides/SKILL.md, skills/lark-slides/references/xml-schema-quick-ref.md	SKILL.md updated with two generation rules: data series use native <chart>, flowcharts/sequence/architecture/scatter/funnel/decoration use <whiteboard> after reading reference. High-frequency read list adds lark-slides-whiteboard.md link. jq template element list now includes whiteboard. XML schema quick reference adds whiteboard to <data> element list and provides SVG/Mermaid code examples and usage notes.
API Operation Documentation skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md, lark-slides-xml-presentation-slide-get.md, lark-slides-replace-slide.md	Slide create doc adds whiteboard to supported <data> container types. Slide get doc clarifies that returned XML top-level blocks (shape, img, table, chart, whiteboard) use id attribute as block_id (typically 3-char short code). Slide replace doc adds constraint that <whiteboard> blocks returned by slide.get omit internal SVG/Mermaid data but block_replace can still overwrite full whiteboard XML. Replaces-slide doc adds <whiteboard> to legal root elements table.
Asset Planning and Visual Layout Integration skills/lark-slides/references/asset-planning.md, planning-layer.md, visual-planning.md	Asset planning clarifies asset_need is metadata-only and requires XML-native fallback for all assets; narrows chart guidance by removing funnel/scatter from chart type and directing them to <whiteboard> SVG at generation time; adds whiteboard to fallback rendering capability. Planning-layer updates fallback_if_missing examples (architecture-diagram, logo, chart) with simpler XML placeholder descriptions. Visual planning adds "Implementation" preference to use <whiteboard> for architecture-diagram and process-flow, falling back to <shape>+<line>.
Validation and Verification Rules skills/lark-slides/references/validation-checklist.md	New "Whiteboard Elements" section clarifies that round-trip XML from xml_presentations.get returns only coordinate/size attributes (no SVG/Mermaid content). Validation covers coordinate boundary checks (topLeftX + width ≤ 960, topLeftY + height ≤ 540). SVG/Mermaid correctness requires human visual review and must not be claimed as verified in records without user confirmation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• larksuite/cli#389: Initial introduction of the lark-slides skill; this PR extends that foundation with whiteboard element support.

Suggested labels

domain/ccm, size/M

Suggested reviewers

• fangshuyu-768
• syh-cpdsss

Poem

🐰 A whiteboard blooms in slides so bright,
SVG and Mermaid dance in flight,
With geometry precise and borders neat,
The visual story now complete! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding comprehensive whiteboard element documentation and improving related slide guidance across multiple files.
Description check	✅ Passed	The description covers all required sections from the template (Summary, Changes, Test Plan, Related Issues) with detailed, specific information about the PR objectives and testing approach.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/slides-whiteboard

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.75%. Comparing base (de00343) to head (c807666).
⚠️ Report is 45 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1029      +/-   ##
==========================================
+ Coverage   66.80%   67.75%   +0.95%     
==========================================
  Files         564      590      +26     
  Lines       52465    55188    +2723     
==========================================
+ Hits        35048    37392    +2344     
- Misses      14516    14684     +168     
- Partials     2901     3112     +211     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@c8076663722ce7d423def6a0f97c2546ab4f4da3

🧩 Skill update

npx skills add larksuite/cli#feat/slides-whiteboard -y -g

[coderabbitai]

🧹 Nitpick comments (2)

skills/lark-slides/references/validation-checklist.md (1)

79-86: 💤 Low value

Consider adding guidance for coordinate validation failure handling.

The coordinate boundary validation rules are clear and correct (topLeftX + width ≤ 960, topLeftY + height ≤ 540), but the section doesn't specify what to do when these checks fail. Consider adding a brief note about the expected remediation, for example:

"If coordinates exceed boundaries, regenerate the whiteboard element with corrected dimensions before delivery."

This would align with the pattern in lines 35-45 where error codes are paired with handling guidance.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-slides/references/validation-checklist.md` around lines 79 - 86,
Add a short remediation note for failed coordinate validation in the Whiteboard
Elements section: when `slide.get` returns a `<whiteboard>` whose `topLeftX +
width > 960` or `topLeftY + height > 540`, instruct to regenerate or adjust the
whiteboard element with corrected `topLeftX`/`topLeftY`/`width`/`height` before
delivery and record an error code plus the remediation action in the validation
log (matching the handling guidance pattern used around lines 35-45).

skills/lark-slides/references/asset-planning.md (1)

46-46: ⚡ Quick win

Consider making the chart vs whiteboard distinction more prominent.

The inline note clarifying that funnel and scatter must map to <whiteboard> SVG is critical guidance but could be easily missed when scanning the list. This creates a conceptual gap: developers plan asset_type: "chart" but must generate <whiteboard> XML.

Consider one of these improvements:

1. Add a separate bullet or subsection before line 40 titled "Chart vs Whiteboard Selection"
2. Reference a decision table (mentioned in PR objectives) if it exists elsewhere
3. Split the list to show "Chart element supports: line, bar, pie, radar, area, combo" and "Whiteboard element required for: funnel, scatter, architecture diagrams, flow diagrams"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-slides/references/asset-planning.md` at line 46, The note about
mapping funnel and scatter to <whiteboard> is easy to miss in the `chart` list;
update the document to make the "Chart vs Whiteboard" distinction explicit by
either adding a short subsection titled "Chart vs Whiteboard Selection"
immediately before the `chart` bullet, or by splitting the existing list into
two bullets: one listing supported `chart` types (line, bar, pie, radar, area,
combo) and a second listing types that must use `<whiteboard>` (funnel, scatter,
architecture diagrams, flow diagrams), and optionally add a cross-reference to
the decision table if it exists; ensure you mention `asset_type: "chart"` vs
`asset_type: "whiteboard"` so implementers know which XML element to generate.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@skills/lark-slides/references/asset-planning.md`:
- Line 46: The note about mapping funnel and scatter to <whiteboard> is easy to
miss in the `chart` list; update the document to make the "Chart vs Whiteboard"
distinction explicit by either adding a short subsection titled "Chart vs
Whiteboard Selection" immediately before the `chart` bullet, or by splitting the
existing list into two bullets: one listing supported `chart` types (line, bar,
pie, radar, area, combo) and a second listing types that must use `<whiteboard>`
(funnel, scatter, architecture diagrams, flow diagrams), and optionally add a
cross-reference to the decision table if it exists; ensure you mention
`asset_type: "chart"` vs `asset_type: "whiteboard"` so implementers know which
XML element to generate.

In `@skills/lark-slides/references/validation-checklist.md`:
- Around line 79-86: Add a short remediation note for failed coordinate
validation in the Whiteboard Elements section: when `slide.get` returns a
`<whiteboard>` whose `topLeftX + width > 960` or `topLeftY + height > 540`,
instruct to regenerate or adjust the whiteboard element with corrected
`topLeftX`/`topLeftY`/`width`/`height` before delivery and record an error code
plus the remediation action in the validation log (matching the handling
guidance pattern used around lines 35-45).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 900593dc-b8a4-476a-8c32-0ec700c4b5e8

📥 Commits

Reviewing files that changed from the base of the PR and between fbe4cc6 and c807666.

📒 Files selected for processing (12)

• skills/lark-slides/SKILL.md
• skills/lark-slides/references/asset-planning.md
• skills/lark-slides/references/lark-slides-replace-slide.md
• skills/lark-slides/references/lark-slides-whiteboard.md
• skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md
• skills/lark-slides/references/lark-slides-xml-presentation-slide-get.md
• skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md
• skills/lark-slides/references/planning-layer.md
• skills/lark-slides/references/slides_xml_schema_definition.xml
• skills/lark-slides/references/validation-checklist.md
• skills/lark-slides/references/visual-planning.md
• skills/lark-slides/references/xml-schema-quick-ref.md