html-spec

转换 HTML 为 PPT 元素——把 HTML 转成可编辑 PPT 元素的契约：白名单决定可编辑范围，data-tabslide-rasterize 兜底复杂视觉。

설치로 이동

저장소: tabtin-ai/TabTin
최근 소스 활동: 2026년 8월 22일 12:25
감지된 SKILL.md 언어: 중국어
스타: 189
포크: 47

설치 방법

기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.

npx skills add https://github.com/tabtin-ai/TabTin --skill html-spec

명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.

로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.

소스 파일 검토

설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.

파일 탐색기

3 개 파일

SKILL.md

소스 지침 · 읽기 전용 미리보기

검색으로 돌아가기 설치로 돌아가기

name	html-spec
description	转换 HTML 为 PPT 元素——把 HTML 转成可编辑 PPT 元素的契约：白名单决定可编辑范围，data-tabslide-rasterize 兜底复杂视觉。
metadata	{"version":"0.4.0","tabtin":{"category":"doc","displayName":"TabSlide HTML 生成规范","autoActivateFor":["tabslide"]}}

TabSlide HTML 生成规范

TabSlide 的 HTML 转页能力（tabtin slide create --html / tabtin slide add-page --html；整份覆盖才用 tabtin slide generate --replace）会把你写的 HTML 转成可编辑的 PPTElement。这份文档定义两件事：

哪些 HTML 模式我们能完整解析为可编辑 PPTElement（用户能拖、能改文字、能改色）
超出白名单的视觉怎么用 data-tabslide-rasterize 兜底（截图为 image，视觉对但整块拖）

一、设计哲学：白名单 + SVG/栅格化兜底

我们不是 Chrome，只能识别 HTML 表现力的一个子集。约定如下：

白名单内 → 可编辑 PPTElement（text / shape / image / line / table / chart）
白名单外的矢量视觉 → 用 <svg> 画（转成清晰图片，视觉稳定）
白名单外的复杂视觉 → 用 <div data-tabslide-rasterize>...</div> 主动包起来，整块截图为 image

这是契约：你写白名单内的内容，我保证可编辑；你写复杂装饰，主动标 rasterize，我保证视觉对。不要写"差不多能识别但又拿不准"的东西 —— 拿不准就 rasterize，宁可降级一块为图片，也别让整页错位。

⚠️ HTML 能做的样式，PPT 不一定能还原。 PPT 的元素模型比 CSS 窄得多——很多纯 CSS 装饰（径向渐变、滤镜、毛玻璃、裁剪形状、异形/曲线、复杂阴影、伪元素画的图形、CSS 画的图标/箭头/连接线等）在转成 PPTElement 时会丢失或走样。这类"用 CSS 硬凑的图形"应当改用 <svg> 画：SVG 会被转成一张清晰的图片元素，视觉在任何机器 / 导出的 .pptx 里都稳定一致，不受 CSS→PPT 能力差异影响。

原则：能进白名单的用白名单（可编辑）；做不进白名单的矢量图形优先用 <svg>（视觉稳定）；再不行才 data-tabslide-rasterize 截图兜底。 代价是 SVG / 栅格化产物是整块图片，不能在编辑器里改文字改色——所以正文、标题、可编辑数据不要塞进 SVG。

二、画布容器（必须）

每页用一个 .ppt-slide div 包裹，宽高固定 1280×720：

<div class="ppt-slide" style="width:1280px;height:720px;position:relative;overflow:hidden">
  <!-- 页面内容 -->
</div>

多页幻灯片在 <body> 中依次排列多个 .ppt-slide。

三、可用资源（自动注入）

样式：只用原生 CSS — 用 <style> 写 class 或元素上写 style="..."。不提供 Tailwind，不要写 class="bg-blue-500 p-8" / bg-[#2563EB] 这类工具类（不会生效）。也不要用与常见框架同名的 class（如 list-item/grid/flex/block/table/hidden），用语义化命名（如 .bullet-row）。
Font Awesome 6 — <i class="fa-solid fa-...">（⚠️ 必须 rasterize 才能出现在 PPT 里，详见 §五）
ECharts — echarts.init(dom).setOption({...})（图表容器必须同时声明确定的 width 和 height；不要只依赖 flex:1 或百分比高度）
Chart.js — new Chart(ctx, {...})
MathJax — $$E=mc^2$$
字体 — Inter（英文）、Noto Sans SC（中文），自动应用

四、可编辑白名单（推荐写法）

8 类可编辑元素（文字 / 简单形状 / 线段 / 线性渐变 / 图片 / SVG 图标 / 图表 / 表格）的逐项推荐写法与示例见 references/editable-whitelist.md。

真实图片必须内嵌数据，别只贴外链（重要）：把网页 / 素材里的真实图片（截图、产品图、logo）放进 PPT 时，先把图下载到本地，再读成 data:image/(png|jpeg|gif|webp|bmp);base64,... 写进 <img src>——这样图数据会落到 slide 自己的存储、长期不掉。<img src="https://第三方..."> 是原样引用第三方链接，会过期 / 防盗链 / 离线掉图。绝不要用文字 / 色块假装图片。 细节见 references/editable-whitelist.md §4.5。

资源导航（按需读取）

references/editable-whitelist.md：当你要判断某个元素是否可编辑、以及该怎么写成稳定白名单形态时读取。
examples/page-templates.md：仅在需要快速起草整页结构或复用模板时读取；示例用于套版，不默认整份注入上下文。

五、栅格化兜底（⚠️ 写法）

5.1 何时用

主动选择 rasterize 的场景：

视觉效果	为什么走 rasterize
Font Awesome 图标（`<i class="fa-*">`）	dom_extractor 会把 FA 元素 `display:none` 隐藏，直接写不会出现在 PPT 里
径向渐变（`radial-gradient`）	仅支持 linear
毛玻璃（`backdrop-filter: blur`）	PPT 无对应能力
裁剪形状（`clip-path`、`mask-image`）	PPT 无对应能力
混合模式（`mix-blend-mode`）	PPT 无对应能力
复杂 filter（`drop-shadow`、多个 filter 叠加）	转换不稳定
复杂 SVG（含动画 / 滤镜 / 渐变填充）	序列化后可能视觉退化
拿不准能不能识别的复杂视觉	主动声明意图，避免错位

5.2 怎么写

把要整块截图的内容包在 <div data-tabslide-rasterize> 里：

<!-- Font Awesome 图标兜底（极其常用） -->
<div data-tabslide-rasterize
     style="position:absolute;top:80px;left:80px;width:48px;height:48px;
            display:flex;align-items:center;justify-content:center;
            color:#2563EB;font-size:32px">
  <i class="fa-solid fa-chart-line"></i>
</div>

<!-- 复杂 SVG 装饰兜底 -->
<div data-tabslide-rasterize
     style="position:absolute;top:80px;left:80px;width:200px;height:60px">
  <svg viewBox="0 0 200 60">
    <defs>
      <linearGradient id="g">
        <stop offset="0" stop-color="#2563EB"/>
        <stop offset="1" stop-color="#7C3AED"/>
      </linearGradient>
    </defs>
    <path d="M0,30 Q50,0 100,30 T200,30" stroke="url(#g)" stroke-width="3" fill="none"/>

dom_extractor 看到 data-tabslide-rasterize 属性后：

截图整个 div（含所有子元素，@2x 分辨率）
上传到 OSS
当一个 image PPTElement 输出
子元素不再被其他识别函数提取（不会有"图片 + 文字"双重提取）

5.3 规则

✅ rasterize 区域必须有明确的 width / height（截图 clip 来自 getBoundingClientRect，无尺寸截不出来）
✅ 在编辑器里 rasterize 出的 image 只能整块拖动、缩放，不能改文字 / 颜色
❌ 别用 rasterize 包裹本来就能识别的简单卡片 / 文字 —— 浪费，且失去可编辑性
❌ rasterize 内不要再嵌套 rasterize（只截最外层）

六、明确禁止 / 不识别

以下用法即使写了也会被忽略或导致异常 —— 看到下表的视觉需求第一反应应该是走 rasterize：

用法	后果
`<i class="fa-*">` 不包 rasterize	图标被 `display:none` 隐藏，PPT 里看不到
`radial-gradient` 不包 rasterize	形状仍输出但渐变丢失（保留 bg / 边框）
`backdrop-filter` 不包 rasterize	毛玻璃丢失
`clip-path` / `mask-image` / `mix-blend-mode` 不包 rasterize	视觉丢失
`<p>` / `<h*>` 上写 `background` / `border` / `box-shadow`	文字识别成功，但背景边框丢失
`position: fixed`	坐标计算异常（相对视口而非 `.ppt-slide`）
CSS `animation` / `transition` / `@keyframes`	PPT 不支持，渲染期被忽略
`<iframe>` `<video>` `<audio>`	不识别（slide generate 不输出此类元素）
`<ul>` / `<ol>` 嵌套结构（多层）	识别不稳；改用 `<div>` 排列

七、配色与样式约定

7.1 颜色写法（任选其一，能识别）

✅ CSS 变量：var(--slide-primary)（保证全局一致，推荐多页演示统一用）
✅ 直接写 hex / rgb / rgba：style="background:#2563EB" / style="color:rgba(255,255,255,0.7)"
✅ 自定义 class 里写原生 CSS：.title{color:#1F2937}

优先使用 CSS 变量 —— 主题切换时统一更新。多页演示混着用容易出现某页跳色。不要用 Tailwind 工具类（bg-blue-500/bg-[#2563EB] 等不会生效）。

7.2 CSS 变量速查

变量	默认值	用途
`--slide-primary`	#2563EB	主色
`--slide-accent`	#DC2626	强调色
`--slide-text` / `--slide-text-secondary`	#1F2937 / #64748B	正文 / 辅助文字
`--slide-bg` / `--slide-bg-subtle`	#FFFFFF / #F8FAFC	背景白 / 浅底
`--slide-border`	#E2E8F0	边框色
`--slide-success/warning/error/info`	绿/橙/红/蓝	状态色
`--slide-blue/teal/green/orange/red/purple`	—	六色板（图表 / 卡片配色）
`--slide-radius-sm/md/lg/xl/full`	8 / 12 / 16 / 24 / 9999 px	圆角
`--slide-shadow-sm/md/lg/xl`	—	阴影

7.3 组件 class 速查

class	说明
`.slide-cover`	居中封面页（flex column center）
`.slide-content`	标准内容页（纵向 + 60/80 px 内边距）
`.slide-split` / `.slide-split-40-60`	1:1 / 2:3 分栏
`.slide-grid-2/3/4`	等宽网格
`.slide-title` / `.slide-title-lg` / `.slide-subtitle`	48 / 64 / 28 px
`.slide-heading` / `.slide-body` / `.slide-caption` / `.slide-label`	36 / 20 / 14 / 14 px
`.slide-number`	56 px 数字高亮
`.slide-card` / `.slide-card-bordered` / `.slide-card-accent` / `.slide-card-filled`	卡片变体
`.slide-card-glass`	⚠️ 含 backdrop-filter，毛玻璃效果必须 rasterize
`.slide-kpi`（内含 `.kpi-label / .kpi-value / .kpi-change.up/.down`）	KPI 指标卡
`.slide-table` / `.slide-table-minimal`	表格主题
`.slide-badge` / `-primary/success/warning/error`	标签（不要塞 FA 图标）
`.slide-list`	带圆点列表（CSS `::before` 实现，识别为 div 文字）
`.slide-divider` / `.slide-divider-accent` / `.slide-accent-bar`	装饰线 / 条
`.slide-step-number`	数字圆圈（识别为 shape + text）
`.slide-timeline` + `.slide-timeline-item`	时间线

八、页面模板

6 套可直接套用的整页 HTML 模板（封面 / KPI 仪表盘 / 图表页 / 对比分析 / 表格页 / 总结页）见 examples/page-templates.md。

html-spec

설치 방법

소스 파일 검토

TabSlide HTML 生成规范

一、设计哲学：白名单 + SVG/栅格化兜底

二、画布容器（必须）

三、可用资源（自动注入）

四、可编辑白名单（推荐写法）

资源导航（按需读取）

五、栅格化兜底（⚠️ 写法）

5.1 何时用

5.2 怎么写

5.3 规则

六、明确禁止 / 不识别

七、配色与样式约定

7.1 颜色写法（任选其一，能识别）

7.2 CSS 变量速查

7.3 组件 class 速查

八、页面模板

九、自查清单（生成前过一遍）

TabSlide HTML 生成规范

一、设计哲学：白名单 + SVG/栅格化兜底

二、画布容器（必须）

三、可用资源（自动注入）

四、可编辑白名单（推荐写法）

资源导航（按需读取）

五、栅格化兜底（⚠️ 写法）

5.1 何时用

5.2 怎么写

5.3 规则

六、明确禁止 / 不识别

七、配色与样式约定

7.1 颜色写法（任选其一，能识别）

7.2 CSS 变量速查

7.3 组件 class 速查

八、页面模板

九、自查清单（生成前过一遍）

html-spec

소스 정보

설치 방법

소스 파일 검토

이 저장소의 다른 Skills

TabSlide HTML 生成规范

一、设计哲学：白名单 + SVG/栅格化兜底

二、画布容器（必须）

三、可用资源（自动注入）

四、可编辑白名单（推荐写法）

资源导航（按需读取）

五、栅格化兜底（⚠️ 写法）

5.1 何时用

5.2 怎么写

5.3 规则

六、明确禁止 / 不识别

七、配色与样式约定

7.1 颜色写法（任选其一，能识别）

7.2 CSS 变量速查

7.3 组件 class 速查

八、页面模板

九、自查清单（生成前过一遍）

TabSlide HTML 生成规范

一、设计哲学：白名单 + SVG/栅格化兜底

二、画布容器（必须）

三、可用资源（自动注入）

四、可编辑白名单（推荐写法）

资源导航（按需读取）

五、栅格化兜底（⚠️ 写法）

5.1 何时用

5.2 怎么写

5.3 规则

六、明确禁止 / 不识别

七、配色与样式约定

7.1 颜色写法（任选其一，能识别）

7.2 CSS 变量速查

7.3 组件 class 速查

八、页面模板

九、自查清单（生成前过一遍）

이 저장소의 다른 Skills