Zon Report

Style Guide

JSON-only data · global CSS/JS · file:// + HTTP

这是你“全局统一”的样式库入口：所有 report 只存一次 JSON，渲染统一交给 zon-report.css + zon-report.js。

zon-report@v1 style-library viewer schema
Open viewer Demo JSON Schema

Usage

Two modes

Local / file://：如果你直接双击打开报告页，脚本会尝试自动加载同目录 report.json，但不同浏览器/策略可能拦截。

推荐：用本地 HTTP server 预览（最稳，零操作自动加载 JSON）。 python3 -m http.server 8000

HTTP / Vercel

直接用 ?src=... 参数加载： viewer.html?src=examples/report-system-v1-demo.json 

<!-- Thin shell (report.html) -->
<link rel="stylesheet" href="/zon-report.css" />
<div data-zon-report data-src="report.json"></div>
<script src="/zon-report.js"></script>

JS data source (file:// friendly)

如果你坚持 file:// 双击 0 操作且不想起 server，可以把数据作为 JS 资源加载： report.data.js 里设置 window.zonReportData，再用 data-var 渲染。

代价：数据不再是纯 JSON（JS 可执行，安全边界更差；也更不利于 JSON Schema/索引）。

<!-- Thin shell (report.html) + JS data source -->
<link rel="stylesheet" href="/zon-report.css" />
<div data-zon-report data-var="zonReportData"></div>
<script src="report.data.js"></script>
<script src="/zon-report.js"></script>
Open demo Open viewer Edit CSS

Components

这里展示 zon-report.js 当前渲染的 block 对应 UI（你改 zon-report.css 即可全局变更）。

Block

prose

适合长段解释、背景、结论。保持排版、字距与可打印性。

支持多段落数组，渲染为多段 <p>。

Block

list

  • 无序列表（ordered=false）
  • 适合枚举、清单、范围
  • 和 cards/callout 混用也很自然
  1. 有序列表（ordered=true）
  2. 适合步骤、流程

Block

callout

neutral

默认提示框：用于 TL;DR、摘要、结论。

info

信息提示：用于方法、说明、定义。

warn

警告提示：用于风险、注意事项、约束。

danger

危险提示：用于踩坑、禁止项、严重后果。

success

成功提示：用于通过标准、完成状态。

Block

cards

Now

Card title

一段简短说明，支持多段落。

Goal

Another card

用于对比、分组、要点归纳。

  • 支持 bullets
  • 保持简洁

A

Three cols

桌面三列，移动端自动一列。

B

Density

适合小卡片集合。

C

Consistency

全局统一靠 CSS。

Block

table

Column Meaning
Format JSON only
Render zon-report.js
Style zon-report.css

Block

code

{
  "version": "zon-report@v1",
  "meta": { "title": "Example" },
  "blocks": []
}

Tokens

主入口：编辑 zon-report.css 里的 :root 变量。 你也可以在任意页面用 style 覆盖局部 token（但建议尽量不这么做）。

--black

#0a0a0a

--white

#fafafa

--gray-200

#e8e8e8

--gray-600

#666

Cache tip

如果你部署在 Vercel 上，浏览器可能缓存 CSS。可以用“hard refresh”或在引用里加 ?v=timestamp（例如 zon-report.css?v=1）。

Schema

JSON 的规范在 zon-report.schema.json。核心字段： version / meta / blocks。

Open schema link + quick notes

Schema: zon-report.schema.json

  • blocks[].type：prose / list / callout / cards / table / code / html
  • blocks[].id + blocks[].nav：用于自动 TOC/Nav
  • html block 为 “trusted escape hatch”（只用于你自己信任的内容）