Back to Details

svg-precision

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

svg-precision

svg-precision

Generate structurally correct SVGs from a strict JSON spec (scene graph), then validate and optionally render a PNG preview.
从严格的JSON规范（场景图）生成结构正确的SVG，然后进行验证，还可选择性渲染PNG预览图。

Fast path

快速流程

  1. Turn the user request into a Spec JSON (use templates in 
    references/spec.md
    ).
  2. Build the SVG: 
    • python scripts/svg_cli.py build spec.json out.svg
  3. Validate: 
    • python scripts/svg_cli.py validate out.svg
  4. (Optional) Render a PNG preview (requires CairoSVG): 
    • python scripts/svg_cli.py render out.svg out.png --scale 2
  1. 将用户需求转换为规范JSON（可使用
    references/spec.md
    中的模板）。
  2. 构建SVG： 
    • python scripts/svg_cli.py build spec.json out.svg
  3. 验证： 
    • python scripts/svg_cli.py validate out.svg
  4. （可选）渲染PNG预览图（需要CairoSVG）： 
    • python scripts/svg_cli.py render out.svg out.png --scale 2

Spec design rules (for accuracy)

规范设计规则（保证准确性）

  • Always set 
    canvas.viewBox
    and explicit 
    canvas.width
    /
    canvas.height
    .
  • Prefer absolute coordinates; use transforms only when they reduce complexity.
  • Keep numbers sane: no NaN/inf; round to 3-4 decimals.
  • Put reusable items in 
    defs
    (markers, gradients, clipPaths) and reference by id.
  • For predictable results across viewers, avoid exotic filters unless required.
  • Text varies by fonts/viewers. If you need pixel-identical results, treat text as a risk and prefer shapes.
  • 始终设置
    canvas.viewBox
    以及明确的
    canvas.width
    /
    canvas.height
    。
  • 优先使用绝对坐标；仅在能降低复杂度时使用变换（transforms）。
  • 数值保持合理：无NaN/inf；四舍五入到3-4位小数。
  • 将可复用元素放入
    defs
    （标记、渐变、裁剪路径）并通过id引用。
  • 为保证在不同查看器中结果一致，除非必要，避免使用特殊滤镜。
  • 文本显示因字体/查看器而异。如果需要像素级完全一致的结果，需注意文本的风险，优先使用图形替代。

Using the bundled scripts

使用内置脚本

CLI

CLI命令

  • python scripts/svg_cli.py build <spec.json> <out.svg>
  • python scripts/svg_cli.py validate <svg>
  • python scripts/svg_cli.py render <svg> <out.png> [--scale N]
  • python scripts/svg_cli.py diff <a.svg> <b.svg> <diff.png> [--scale N]
    (renders + image-diffs)
  • python scripts/svg_cli.py build <spec.json> <out.svg>
  • python scripts/svg_cli.py validate <svg>
  • python scripts/svg_cli.py render <svg> <out.png> [--scale N]
  • python scripts/svg_cli.py diff <a.svg> <b.svg> <diff.png> [--scale N]
    （渲染并生成图像差异对比）

As a library (in Python)

作为Python库使用

py
from svg_skill import build_svg, validate_svg
svg_text = build_svg(spec_dict)
report = validate_svg(svg_text)
py
from svg_skill import build_svg, validate_svg
svg_text = build_svg(spec_dict)
report = validate_svg(svg_text)

When the request is vague

当需求模糊时

  1. Identify the kind of SVG: icon / diagram / chart / UI / technical.
  2. Pick a template from 
    references/spec.md
    and fill in concrete numbers.
  3. If dimensions are unknown, choose defaults that match the domain:
    • icons: 24x24 or 32x32
    • UI mockups: 1440x900 or 390x844 (mobile)
    • charts: 800x450
    • diagrams: 1200x800
    • technical drawings: specify units (mm/in) and scale
  1. 确定SVG的类型：图标/流程图/图表/UI原型/技术绘图。
  2. 从
    references/spec.md
    中选择一个模板并填入具体数值。
  3. 如果尺寸未知，选择符合该领域的默认值：
    • 图标：24x24或32x32
    • UI原型：1440x900或390x844（移动端）
    • 图表：800x450
    • 流程图：1200x800
    • 技术绘图：指定单位（毫米/英寸）和比例

References

参考资料

  • references/spec.md
    - schema + ready-to-copy templates per SVG type
  • references/recipes.md
    - layout and styling patterns that render consistently
  • references/spec.md
    - 各类SVG对应的Schema + 可直接复制使用的模板
  • references/recipes.md
    - 可一致渲染的布局与样式模式