Trmnl Paper Blade

trmnl-paper-blade

概览

为 Laravel + trmnl-blade 生成可直接渲染的 Blade 组件 markup。优先复用 x-trmnl:: 组件和 Framework v3 的布局语义，避免自由拼接 CSS/HTML。

两个事实来源：

1. Framework v3 规则：结构层级、颜色系统、Overflow/Clamp/Content Limiter/Pixel Perfect 等运行时机制
2. 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）

工作流

1. 先确认目标：
   • 新建一个 TRMNL 屏幕
   • 把现有 HTML / 草图 / 数据说明改写成 TRMNL Blade
   • 只要骨架，还是要完整屏幕
2. 再收集最小输入：
   • 屏幕主题与核心数据
   • 是否需要标题栏
   • 是否需要双栏、列表、表格、图表、进度条、KPI、大字值、富文本
   • 是否有设备、方向、位深等限制
3. 选择组件路径（优先使用高阶组件 / 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
4. 从基础骨架开始，再填充模块。
5. 默认只负责生成 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）

• 已运行 validate_markup.py 校验结构层级与 table 使用规则（权威说明见 references/design-rules.md）

python3 skills/trmnl-paper-blade/scripts/validate_markup.py <markup-file>

仍需手工检查

• 优先使用已验证的 <x-trmnl::...> 组件；chart / image / progress-dots 用原生 class
• 可能溢出的 title / label / description 已显式加 data-clamp
• 如果只输出局部模块，已说明应插入 layout、column 或 mashup 的位置

参考资料

建议阅读顺序

1. references/design-rules.md：先确认结构层级与 e-paper 约束
2. references/patterns.md：先找最接近的布局模板，不要从零拼装
3. references/components/：按实际组件查 props、CSS 映射与 gotchas
4. references/attributes.md：需要工具类、data-* 属性时再读
5. references/examples/_index.md：需要完整官方示例时先看索引，再按需展开
6. 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 注释）

输出约定

默认按以下顺序输出：

1. Blade markup
2. 如有必要，补 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 的“交接格式”为准：

• issue
• location
• suggested_fix