| name | trmnl-paper-blade |
| description | Use when the user wants to build, edit, or redesign screens for TRMNL e-paper devices. Handles dashboards, KPI displays, item lists, data tables, quotes, rich text, charts, and any screen layout — converting content briefs, data descriptions, or plain HTML into `<x-trmnl::...>` Blade component markup. Also use when they mention "trmnl-blade", "TRMNL Framework", "e-paper screen", or describe content for an e-ink display, even without naming TRMNL directly.
|
trmnl-paper-blade
概览
为 Laravel + trmnl-blade 生成可直接渲染的 Blade 组件 markup。优先复用 x-trmnl:: 组件和 Framework v3 的布局语义，避免自由拼接 CSS/HTML。
两个事实来源：
- Framework v3 规则：结构层级、颜色系统、Overflow/Clamp/Content Limiter/Pixel Perfect 等运行时机制
- trmnl-blade 实际封装范围：当前已有 Blade 组件（见下文），未封装的能力用原生 class
当前 Blade 组件
screen、mashup、view、layout、title-bar、columns、column、flex、grid、col、richtext、content、text、item、table、label、title、value、description、divider、meta、progress（progress-bar 封装）、track、clamp、background、aspect
未封装为 Blade 组件：chart（Highcharts/Chartkick JS）、image（原生 class）、progress-dots（原生 class）
工作流
- 先确认目标：
- 新建一个 TRMNL 屏幕
- 把现有 HTML / 草图 / 数据说明改写成 TRMNL Blade
- 只要骨架，还是要完整屏幕
- 再收集最小输入：
- 屏幕主题与核心数据
- 是否需要标题栏
- 是否需要双栏、列表、表格、图表、进度条、KPI、大字值、富文本
- 是否有设备、方向、位深等限制
- 选择组件路径（优先使用高阶组件 / Components）：
- 第一优先：Rich Text / Item / Table / Chart / Progress。能直接映射时，不要先拆成零散
div、grid、flex
- 文案、引言、通知、段落 →
richtext（旧 markdown 路线已废弃）
- 列表、日程、事件 →
item
- 简单表格、结构化数据 →
table
- 数据可视化 →
chart 原生 class / Highcharts / Chartkick
- 进度表达 →
<x-trmnl::progress> 或 div.progress-dots
- KPI、大数字 →
value + label
- 多区域 / 多列 →
columns / mashup / grid
- 颜色 token、工具类、
data-* 属性 → 原生 class / data 属性
- 具体 props、限制与 gotchas 按需读
references/components/、references/attributes.md、references/patterns.md
- 从基础骨架开始，再填充模块。
- 默认只负责生成 markup；API 推送说明交给
trmnl-paper-screen。
默认骨架
<x-trmnl::screen>
<x-trmnl::view>
<x-trmnl::layout>
<!-- content -->
</x-trmnl::layout>
<x-trmnl::title-bar title="..." />
</x-trmnl::view>
</x-trmnl::screen>
- 无标题栏时可省略
title-bar
- 需要分栏时优先用
columns / column
- 需要居中堆叠时优先用
layout direction="col" alignment="center"
生成规则
- 优先使用
x-trmnl:: 组件，不先写自由 class
- 当需求可直接映射到 Rich Text / Item / Table / Chart / Progress 时，先用这些高阶组件/模式，再考虑
columns、grid、flex
- 先保证结构清晰，再考虑细节
- 保持层级少、信息密度可读
- 避免硬编码像素值
title / label / description 默认不自动 clamp；可能溢出时显式使用 data-clamp="1" 等属性截断- 用户没有要求时，不要臆造未验证的 props
- props 不确定时，宁可使用默认 slot，也不要发明 API
- 输出完整屏幕时，优先给完整可渲染的 Blade 片段
- 输出局部模块时，说明它应插入
layout / column 的位置
输出前自检
自动可校验（运行 validate_markup.py）
python3 skills/trmnl-paper-blade/scripts/validate_markup.py <markup-file>
仍需手工检查
参考资料
建议阅读顺序
references/design-rules.md：先确认结构层级与 e-paper 约束references/patterns.md：先找最接近的布局模板，不要从零拼装references/components/：按实际组件查 props、CSS 映射与 gotchasreferences/attributes.md：需要工具类、data-* 属性时再读references/examples/_index.md：需要完整官方示例时先看索引，再按需展开references/colors.md / references/guides.md：需要颜色 token 或 v3 差异时再查
按需速查
- 组件速查（props / CSS 映射 / 用法）：读
references/components/ 目录下对应组件文件
- 工具类与 data 属性（间距、尺寸、圆角、可见性等）：读
references/attributes.md
utilities.md 兼容入口：读 references/utilities.md（权威内容已收敛到 attributes.md）- 常用布局模板（可直接复制的完整示例）：读
references/patterns.md
- 官方示例索引：先读
references/examples/_index.md
- 官方示例（完整 HTML 源码参考）：读
references/examples/ 目录下对应文件
- v3 颜色系统完整参考（灰度 / 色度 / 语义色）：读
references/colors.md
- v3 特性与升级差异：读
references/guides.md
- v3 设计约束（结构层级权威说明 / e-paper 规则）：读
references/design-rules.md
- 上游文档：https://trmnl.com/framework/docs/v3
- Blade 源码：https://github.com/bnussbau/trmnl-blade
可用脚本
scripts/validate_markup.py — 校验 Blade markup 结构规则（title-bar 位置、layout 嵌套、view 必须且只能有一个 layout、table 内嵌原生 table、忽略 HTML/Blade 注释）
输出约定
默认按以下顺序输出：
- Blade markup
- 如有必要，补 1-3 条简短接入说明
如果用户只要代码，只输出代码。
管道输出
当 markup 需要直接传递给 trmnl-paper-screen 推送时：
- 保存到文件 →
trmnl-paper-screen 通过 --markup-file <path> 读取
- 通过管道 →
echo '<markup>' | python3 skills/trmnl-paper-screen/scripts/push_screen.py --markup-stdin ...
交接格式
收到 trmnl-paper-screen 回传的问题清单时，字段格式以 skills/trmnl-paper-screen/SKILL.md 的“交接格式”为准：
issuelocationsuggested_fix
