legal-visualization

Legal Visualization

A legal diagram and chart generation skill for legal business scenarios. It covers cases, non-litigation projects, compliance management, client collaboration, team case handling, client reporting, and legal service proposals, generating legal diagrams that can be submitted, reported, or embedded into documents directly. The external English name uses Legal Visualization, and in Chinese it may be called "法律可视化"; the Skill identifier and directory name are uniformly legal-visualization. draw.io / diagrams.net is the default editable underlying format, not the boundary of the external positioning.

Hard constraints

1. Missing facts must be explicitly marked: entities, times, amounts, contracts, and evidence not seen in the materials must not appear in the diagram; they must be explicitly written as "to be supplemented/to be verified/one party asserts", and completion or inference is prohibited.
2. Business line takes precedence over diagram type: first identify the business line such as "litigation/corporate/compliance/intellectual property/dispute/contract/client/service", then select the diagram type.
3. VizSpec.routing is required: if not filled in, routing.primary_scene and routing.selection_reason writing drawio is prohibited.
4. One diagram, one point: more than 1 core point must be split into a main diagram + supplementary diagrams; different semantic areas of ≥3 types such as time, calculation, and procedure must not be freely piled into the same canvas, and can only be split into diagrams or use a zoning template with defined capacity.
5. Domain validation must pass：.drawio before copying, exporting, and delivery must pass scripts/validate_drawio.py; geometric overlap, deterministic text overflow, invalid container relationships, or overly long connector labels are blocking errors; estimated overlap between connector labels and independent nodes/text blocks is a warning that must be visually reviewed.
6. Matched templates must lock geometry: when a suitable template already exists, use scripts/instantiate_template.py to replace only value placeholders; afterward scripts/apply_visual_roles.py may be used to compile styles, but before and after compilation each mxGeometry must be exactly identical. Nodes must not be moved, font sizes reduced, or edge labels expanded in order to cram in more material; when capacity is insufficient, split into supplementary diagrams.

Default targets

• Default delivery is a three-piece set:.drawio source file,.svg vector image,.png high-definition preview image; both SVG and PNG are exported from .drawio via draw.io / diagrams.net.
• When the user requests court hearing, report, PPT, or archiving, append as needed PDF。
• PNG is exported at 2x magnification by default; if used for printing, large-screen reporting, or high-definition illustrations, clarity can be improved via --png-scale 3 or --png-scale 4 .
• By default, aim to produce the diagram in one step; only when the export tool is unavailable or key facts in the materials are missing should manual editing in draw.io be used as a fallback.
• A diagram must serve one core point or one clear information task, and must not pile all materials into one diagram.
• Automatically exported .drawio, images, and reports go by default into archive/<timestamp>/, to avoid polluting templates/ or the source file directory.

Dependencies

Ready to use out of the box

• Generate .drawio XML, locked template instantiation, reading reference files, and running draw.io domain validation require only the Python 3 standard library.
• When there is no draw.io CLI, you can still deliver the .drawio source file, and note in the final description that image export was not completed.

Core process dependencies

Feature	Dependency	Installation method
VizSpec 2.1 validation and visual role style compilation	PyYAML	pip install pyyaml
Automatic export to SVG/PNG/PDF	draw.io / diagrams.net desktop CLI	On macOS, diagrams.net can be installed; the script will detect drawio、draw.io、drawio-desktop and common application paths

When using VizSpec or the style compiler for the first time, first run pip install pyyaml. When dependencies are missing, the script must exit with a non-zero status and display that installation command, and must not degrade to "validation passed".

Workflow

1. Extract diagramming tasks: Extract from the materials the audience, case/project type, core issue, subject, time, amount, subject matter, process, evidence, risk, client actions, team actions, and user position. When non-critical facts are missing, first mark them reasonably as "to be supplemented"; do not stop and wait.
2. Determine the audience: Diagrams for judges should remain objective, restrained, and verifiable; diagrams for clients should highlight strategy, risk, and possible outcomes; diagrams for business teams should highlight process, responsibilities, and deliverables; diagrams for legal teams may retain more detail and evidence indexes.
3. Route the scenario: First read references/scene-routing-guide.md, and filter out 1-3 candidate scenarios by audience, task verb, material stage, and information form; then read the corresponding chapter in references/scene-library.md to determine the main scenario. Do not directly jump-select by keywords in the complete scenario library. After the scene_id is selected, choose the diagram type variant and node layout from references/chart-decision-tree.md ; this decision tree is downstream of routing and does not replace routing.
4. Resolve conflicts: If multiple scenarios can match, choose the main diagram according to "user specification > audience match > narrower business domain > current material stage > general scenario"; unselected scenarios serve only as candidate supplementary diagrams.
5. Determine the content: Process the materials in the order "comprehensive listing -> logical integration -> concise content". For complex cases, first make a detail diagram, then combine it by core subject, core timeline, or core legal relationship.
6. Generate VizSpec: Write VizSpec 2.1 according to references/vizspec-schema.md ; each visual node separately declares visual_role(semantic category),epistemic_status(factual epistemic status), and emphasis(visual emphasis), and relationships declare status. The three must not be inferred from one another; for example, "defendant" does not equal "disputed".
7. Arrange the visual layout: Control chart logic, lines, annotations, and emphasis according to references/visual-composition-rules.md and references/scene-composition-playbook.md ; for complex scenarios, also read references/advanced-case-patterns.md. Name nodes according to references/naming-conventions.md. The machine source of truth for roles, states, emphasis, density, and the three theme sets is config/visual-role-registry.json；references/shape-registry.md ; it only explains usage. Emoji/icon prefixes are prohibited in formal legal diagrams.
8. Generate draw.io geometry: First check references/template-guide.md. When a template matches, use scripts/instantiate_template.py to only fill in values and lock the geometry; only when no suitable template exists should you write new XML according to references/xml-reference.md , and declare template.id: custom。
9. Compile visual semantics: First run python scripts/check_vizspec.py spec.yaml; after it passes, run python scripts/apply_visual_roles.py source.drawio spec.yaml styled.drawio. The script only changes style and visual metadata, and before output compares all mxGeometry; geometric changes, missing nodes, illegal fields, or output domain validation failures will block it.
10. Run domain gate: execute python scripts/validate_drawio.py styled.drawio. Any error must be corrected; warnings need manual review in conjunction with the exported image.shape_policy will warn about non-qualifying shapes and diamonds with undeclared visualRole=decision .
11. Export image: according to references/output-workflow.md export SVG/PNG/PDF, and retain .drawio。export_drawio.py will first rerun the domain gate; on failure, copying and exporting are prohibited.
12. Quality inspection delivery: open the actually exported SVG/PNG, check text, connectors, legend, theme, and canvas boundaries according to references/quality-checklist.md , then explain to the user the output files, usage scenarios, and links that could not be verified.

Scenario routing quick reference

Input characteristics	Preferred chart	Read
Sequence of events, timeliness, warranty period, construction period, procedural history, project milestones	Timeline, layered timeline, time interval chart, roadmap	scene-library.md General, construction engineering, service plans
Multiple parties, multiple contracts, flow of funds/instruments/goods/equity	Legal relationship chart, flow chart, combination relationship chart	scene-library.md loans, instruments, companies, international trade
Multiple amounts, construction price, contribution ratios, expense trends	Table, bar chart, line chart, proportion chart	scene-library.md data and companies
Litigation procedures, business processes, approval processes, transaction steps, service delivery	Flowchart, swimlane flowchart, roadmap	scene-library.md General, international trade, land, service plans, contracts, compliance
Legal service plans, client reports, project quotations, work plans	Service roadmap, scope-deliverable matrix, solution comparison chart	scene-library.md Service plans
Contract drafting and review, performance management, breach handling, standard text system	Contract lifecycle chart, review swimlane, clause risk chart, obligation ledger	scene-library.md Contracts
Corporate compliance, internal control, corporate governance, regulatory rectification	Risk map, approval matrix, institutional architecture, rectification roadmap	scene-library.md Compliance governance
Investment and financing, M&A, asset transactions, due diligence	Transaction structure chart, due diligence issue map, closing conditions checklist	scene-library.md Transactions
Labor and personnel, intellectual property, data compliance, debt resolution, family wealth, administrative regulation	Lifecycle chart, ownership chain, data flow, repayment priority, property structure, regulatory path	scene-library.md Corresponding topics
Initial consultation, signing, material collection, service progress, case closure and renewal	Customer lifecycle chart, material collection checklist, service progress dashboard	scene-library.md Full customer lifecycle
Pre-litigation assessment, filing preparation, court hearing, mediation, post-judgment, enforcement, retrial	Case handling roadmap, court hearing offense-defense chart, enforcement advancement chart	scene-library.md Full case handling process
Evidence discovery, preservation, corroboration, presentation of evidence, examination of evidence, archiving	Evidence lifecycle diagram, burden of proof diagram, examination-of-evidence attack and defense diagram	scene-library.md Full lifecycle of evidence work
Complaint, statement of defense, lawyer's letter, legal opinion, due diligence report	Document production flowchart, document structure diagram, version evolution diagram	scene-library.md Legal document production
Negotiation, mediation, arbitration, litigation, administrative complaint, criminal-civil intersection, execution-to-bankruptcy conversion	Dispute path selection diagram, parallel proceeding swimlane diagram, cost and timeline comparison diagram	scene-library.md Dispute resolution paths
Team division of labor, material circulation, hearing preparation, review, retrospective, knowledge accumulation	Task division diagram, material circulation diagram, Gantt chart, quality review diagram	scene-library.md Team collaboration
Engineering site, real estate project, route, spatial location	Floor plan, spatial schematic diagram	scene-library.md Space, real estate
Direction of evidence proof, combination of circumstantial evidence, issue decomposition	Evidence chain diagram, issue-evidence matrix	scene-library.md Evidence and composite cases

Key principles

• One diagram expresses only one main point; split multiple points into multiple diagrams or multiple pages.
• Color must carry meaning: same entity same color, same type of relationship same line style, dispute/risk/breach use emphasis colors, auxiliary facts use gray.
• Avoid line crossings and long detours; entities with many connections should be placed at the center or near related nodes. Change long edge labels into independent text nodes, sidebars, or legends.
• The main body of the diagram should contain only short labels; long facts, evidence numbers, and statutory bases go in sidebars, footnotes, or appended tables.
• For diagrams submitted to judges, do not use exaggerated expression, and do not depict disputed facts as established facts; handle disputed or facts to be proven with dashed lines, question marks, annotations, or gray.
• Unified rounded rectangles: nodes use unified rounded rectangles (diamonds only for decision points), rely onrole color scheme + fact status line style + emphasis stroketo distinguish semantics; do not use irregular shapes such as ellipses / cylinders / document shapes; formal legal diagrams prohibit emoji/icon prefixes.

Output format

• [图名].drawio: source file, must be delivered together with the image to facilitate continued editing by the user.
• [图名].svg: vector graphic exported from .drawio , suitable for Word, PPT, web pages, and continued scaling.
• [图名].png: high-definition preview image exported from .drawio , suitable for WeChat, Feishu, email body, and ordinary preview.
• [图名].pdf: suitable for archiving, printing, or formal attachments.
• archive/<timestamp>/export-report.json: batch export report, recording .drawio source files, export tools, output files, and lightweight check results.

Reference files

• references/scene-library.md: legal diagram scenario index and routing rules.
• references/scene-routing-guide.md: selection rules, scoring methods, and conflict handling under the large scenario library.
• references/scene-routing-evals.md: scenario routing test set, used to check mis-selection and conflicts.
• references/scene-composition-playbook.md: scenario orchestration manual, explaining how to choose and lay out various scenarios.
• references/vizspec-schema.md: structured diagramming specification, used to stably generate diagrams.
• config/visual-role-registry.json: machine-readable single source of truth for role, theme, status, emphasis, density, and shape tokens.
• references/shape-registry.md: human-readable description and combination rules of the visual registry.
• references/visual-composition-rules.md: legal diagram orchestration rules.
• references/advanced-case-patterns.md: Orchestration patterns for complex cases and advanced argument diagrams.
• references/output-workflow.md: Generate .drawio and images in one step.
• references/quality-checklist.md: Pre-delivery checklist.
• references/xml-reference.md: draw.io XML structure, styles, connections, and container rules.
• references/chart-decision-tree.md: After scene_id is selected, choose the diagram type variant and node layout.
• references/legal-visual-constants.md: Visual constants (page, fonts, palette, line types).
• references/naming-conventions.md: Chinese naming conventions for legal nodes.
• references/template-guide.md: Template directory structure, template list, and rules for adding new templates.
• references/xml-example-*.md: XML syntax examples, not placed in the template directory.
• templates/: Store only .drawio templates that can be opened directly, organized by English business directories.

Implementation Tips

• XML and domain layout validation:python scripts/validate_drawio.py path/to/file.drawio, check structure, containers, node overlap, text capacity, edge label length, and estimated overlap between edge labels and independent elements.
• Template-locked instantiation:python scripts/instantiate_template.py templates/litigation/complex-case-split.drawio values.json output.drawio; only valuemay be replaced, with automatic validation after instantiation.
• Batch export:python scripts/export_drawio.py path/to/file.drawio generates .drawio + .svg + .png as a three-piece set by default, and writes to archive/<timestamp>/export-report.json; PNG is exported at 2x by default, add --png-scale 3for higher resolution, and add --in-place。
• Naming convention check:python scripts/normalize_naming.py path/to/file.drawio path/to/spec.yaml, compare against naming-conventions.md and output a deviation list.
• VizSpec declaration validation:python scripts/check_vizspec.py spec.yaml, validate visual_role / theme is legal;validate_drawio.py 's shape_policy check warns for non-qualified shapes (ellipse / cylinder / document shape, etc.).
• Visual role compilation:python scripts/apply_visual_roles.py source.drawio spec.yaml styled.drawio, compile theme, role, fact status, and emphasis into styles, while proving that mxGeometry has not changed.
• Domain regression:python -m unittest scripts.test_validate_drawio scripts.test_instantiate_template scripts.test_check_vizspec scripts.test_apply_visual_roles, covering minimal violation counterexamples, valid container positive examples, VizSpec declarations, differences across the three themes, and geometric conservation.