ccf-visual-composer

CCF Visual Composer

Family File Contract

Before file work, reuse canonical paths and one task/artifact working directory; default to project-root ccfa-workfiles/<purpose>/<artifact-id>/. Update in place, preserve inputs, and use UTF-8 with Chinese-text checks. Apply artifact-contracts.md for naming, ownership, and task-created cleanup; handoffs inherit these paths.

Collaboration Contract

Before specialist execution, read and apply ccf-humanization first, then ccf-common. At every handoff, reuse their applicable active rules or refresh missing/changed ones. Both preflights are required even without prose; detailed editing, experiment, and maintenance modes run only when relevant.

Integrate necessary specialist contributions under one owner; reuse valid prerequisites and verify affected results. Follow the cooperation routes without duplicate reports.

Invocation Controls

CCFA Handoff Mode: PARTIAL (Recommended). Follow metadata.ccf_skill_controls.handoff_question_mode, ../ccf-common/references/handoff-modes.md, and ../ccf-common/references/task-modes.md. Reuse shared rules already in context.

For a new scientific method or architecture concept, GPT Image 2 remains the default first-pass renderer unless the user requests pure SVG/code-first output or opts out. Use the verified host capability and its privacy/image instructions. Do not label an unknown backend as GPT Image 2. Existing authorization covers necessary generation and requested reconstruction; offer extra formats only when outside the request.

Core Rule

Create readable visuals from supplied content. Preserve values, units, uncertainty, exact labels, method modules, and typed connections. Quantitative plots use reproducible code. Missing data or topology requires the relevant evidence owner; do not invent it to complete a composition. Preserve scientific terminology and canonical uppercase acronyms; use natural case for ordinary labels.

For paired long-table groups, declare the sample identity or an explicit matched-order contract through the existing data-binding route; equal group lengths do not establish correspondence. Preserve the selected final-size font settings across panels, templates and linked layouts, and resolve missing Chinese glyphs before export.

Classify the destination as paper mechanism figure, presentation/poster, or README/outreach. Paper figures show representations and computation. Choose visual grammar from the method, not a fixed stage-card template.

For new compositions, use references/visual-contract.md: a compact content-fit canvas, shared alignment anchors, scaled gaps, and typography checked at final size. Do not default to a square or force a fixed aspect ratio. Times New Roman is the default; Comic Sans MS serves a requested comic treatment, subject to user/venue typography. For a new visual direction, choose one functional preset from references/adaptive-architecture-style.md. Inspect supplied references, allocate space by explanatory importance, and keep only necessary labels/numbers.

Modes And Selective References

Read only the relevant sections below. A local edit starts from the existing source and applicable QA; it does not reload the complete generation workflow.

Mode	Use and reference
visual-contract	Non-trivial content/evidence/output decisions: references/visual-contract.md.
figure-design, python-plotting	Numerical plots, benchmarks, ablations and biological data: references/python-plot-recipes.md. For a new composition, query resources/python/ccfa_figure_library.py route by scientific question and available fields, then explain only selected candidates. See references/figure-design-library.md for paper-aware briefs, data bindings and three linked layouts, and references/figure-examples.md for preserved examples and paper cards. Existing ccfa_analysis_templates.py, ccfa_analysis_panels.py and the dependency-free SVG route remain available.
architecture-generation	New concept: references/architecture-diagram-generation.md; paper-specific grammar only from references/paper-vs-presentation-diagrams.md.
pure-svg-generation	Explicit deterministic route: use the supported topology and vector authoring source directly.
editable-reconstruction	Semantic reconstruction sections in references/architecture-diagram-generation.md; load references/editable-pptx.md only for PPTX.
reference-layout-blueprint	Supplied reference composition: references/reference-layout-blueprint.md; use references/adaptive-architecture-style.md when prompt refinement is needed.
icon-system	Native primitives, reusable licensed icons, or necessary custom assets: references/icon-system.md.
table-design, layout-integration	Supplied values, panel/float/caption placement: references/figure-table-layout.md.
render-qa	Inspect the requested formats using the relevant checks in references/render-qa.md.

Use references/palette-and-accessibility.md only when choosing or changing color semantics. Reuse an established palette and icon family when they remain suitable.

Workflow

1. Resolve the requested artifact, existing source, final size, destination, formats, and scientific takeaway. For file work, read ../ccf-common/references/artifact-contracts.md once and resolve canonical output and working paths before rendering. Keep unrelated figures in separate stable working directories; honor existing project paths.
2. Resolve scientific prerequisites before rendering dependent content: source values, units, metric meaning, topology, and intended message. For related panels, resolve entity IDs/order, shared encodings, comparable scales, and any required image aspect ratios. Reject invalid inputs before plotting; do not clamp them into plausible results. Use ccf-experiment-designer for unresolved result semantics, the method's owner for topology, or ccf-integrity-auditor for source conflicts; reuse valid evidence and integrate only the missing contribution. Keep one specification for topology, labels, data locations, layout, style, and provenance, without duplicate contract, prompt, wireframe, or QA files.
3. Select the smallest rendering route that completes the task. New data-led compositions start from the current paper's claim, analytical question, observation unit, data relationships and final-size constraints. Use route --brief for a compact existing-context brief when helpful, or a direct question for a simple figure; inspect only selected design cards. Random choice happens automatically within equally suitable candidates, without asking the user for a seed or forcing global usage balance. Optional task history may diversify tied choices. Keep the selected specification during subsequent edits, and load only relevant cards or signatures. Use ccfa_figure_data.py through compose --spec for explicit CSV/TSV/JSON table bindings; preserve matched rows and declared orders. For joint marginals, aligned position tracks and matrix-linked slices, use the corresponding real linked layout. Keep original templates and requested reference pairs in the examples index; see references/figure-examples.md. Existing templates remain valid starting points, including numerical analyses embedded in a main figure. A purely conceptual architecture uses the default image workflow. For a mixed figure, keep numeric axes, marks and text in their code-generated layer; an optional illustration pass edits a separate region and never redraws the results. For an existing SVG, PPTX, or plot script, directly edit that authoring source and export affected requested formats; do not run a new raster concept pass for a label, color, spacing, data, or export change. Raster edits follow the host image-editing workflow and use the existing image as reference.
4. Preserve a detailed user prompt and add missing constraints once. For a full redesign, include the reference roles, layout geometry, text inventory, typography, and palette needed to make it concrete; do not truncate these to an arbitrary word limit. Reuse approved topology, layout tokens, and assets. Start with one complete candidate. Requested alternatives or Common's applicable figure_variants preference can add a meaningfully different composition using the same approved content; auto requires an unresolved design choice and on applies to new design comparisons, not local edits. Keep each retained candidate in the existing artifact working directory and identify the chosen canonical result. Search or generate assets only to resolve a specific unmet need.
5. Inspect the draft against the layout and scientific contract. Correct vector/native text and geometry during requested reconstruction; for raster delivery, use a targeted image edit for text, spacing, or illustration defects and preserve accepted regions. If two attempts fail to fix the same defect, diagnose the cause and change the relevant strategy. Never stop merely at an attempt count while a feasible correction remains.
6. Build requested editable outputs as semantic groups, live text, shapes, and typed connectors. Do not embed a whole raster and claim editability. Keep unavoidable raster assets separate and describe their actual editability. Generate downstream PDF/PPTX from the canonical authoring source without lossy round trips; retain only necessary reusable source and assets.
7. Use one integrated inspection with two distinct decisions: scientific fidelity (data, scales, IDs, topology, labels) and visual quality (alignment, compactness, final-size type, contrast, clipping, editability). A local edit checks its affected dependencies and protected regions; reuse satisfactory inspections. Save one current preview under the working build directory. An additional independent assessment follows Common's effective independent_review preference or an explicit request; ordinary QA does not require another agent or generation call.
8. Finish the requested deliverable and check file placement, current exports, and disposable temporary files. New data/protocol decisions belong to ccf-experiment-designer, manuscript prose to ccf-paper-writer, and claim mismatches to ccf-integrity-auditor; keep unaffected authorized work moving.

Output Contract

Deliver the requested visual and necessary editable source/formats first. A specification-only request needs no render. Return canonical paths, useful provenance, actual QA results, and material editability limits. Keep the full prompt, specification, and inventory in one reusable source record only when needed or requested; do not also repeat them in the final answer. Preserve explicit exact-output requests.