infocard-layout-debugging
Fix misplaced infocard grid elements.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 2
- Forks
- 1
01 前言 Front Matter
- name
- infocard-layout-debugging
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "infocard", "css", "grid", "responsive", "visual-debugging", "publishing" ], "related_skills": [ "infocard-style-man-skill", "infocard-crayon-style", "web-visual-acceptance", "infocard-mobile-verifier" ] } }
- description
- Fix misplaced infocard grid elements.
03 SKILL.md 正文
infocard-layout-debugging
信息卡主题布局调试与视觉验收技能。用于处理编号、时间轴、正文列、装饰线、响应式布局与线上缓存之间的错位问题。
触发条件
- 用户指出编号跑到右侧、正文被挤窄、时间轴错位或移动端布局异常。
- CSS 已声明
grid-column,但截图仍显示元素位置错误。 - 本地、CDN 与用户截图的视觉结果不一致。
- 主题改造涉及 poster-shell、timeline、编号列或移动端断点。
核心原则
- 先查 DOM 层级,再改 CSS。
grid-column只对当前 grid 容器的直接 grid item 生效;嵌套元素不能跨越父子层级参与祖先 grid。 - 结构优先于视觉补丁。 不要先用
position:absolute把错误嵌套的元素“拉回”目标位置;应优先修复组件骨架。 - 线上事实优先于截图猜测。 先抓取线上 HTML/CSS,确认部署版本和 DOM 顺序,再使用截图或视觉模型分析。
- 桌面与移动端必须成对验证。 编号列宽度、编号宽度、时间轴 left 偏移和正文 padding 必须同步更新。
- 主题必须保持泛化。 修复应落在组件骨架、token 和响应式规则,不得绑定某一张卡片的固定内容。
- 视觉完成 ≠ 几何数据完成。 用户已明确指出:仅靠 DOM rect、CSS computed style、
getBoundingClientRect一致等几何证据,不能算"视觉验收通过"。修复后必须用 Playwright 抓桌面 + 移动端双视口截图,再用vision_analyze给出每张图的 issues / score。任何修复只要缺截图复审,就不允许在交付报告里宣称"完成"。
标准组件骨架
<div class="skill-card">
<div class="card-stripe blue"></div>
<div class="card-num blue">01</div>
<div class="card-body">
<div class="card-icon" aria-hidden="true">🧬</div>
<h3 class="card-title">标题</h3>
<p class="card-desc">正文</p>
<div class="card-tags">标签</div>
</div>
</div>
.card-num 与 .card-stripe 必须是 .skill-card 的直接子级;.card-body 必须显式声明 grid-column:2。
.skill-card {
position: relative;
display: grid;
grid-template-columns: 76px 1fr;
}
.card-num { grid-column: 1; grid-row: 1; }
.card-body { grid-column: 2; grid-row: 1; min-width: 0; }
.card-stripe { position: absolute; left: 72px; }
调试流程
白色空隙与浅色边缘
先确认实际预览/发布的文件路径,尤其要区分 theme/、dist/ 与同名旧模板;不要把截图中的浅色边缘直接归因于浏览器默认 margin。检查 html, body, main, .poster-shell 的 margin、padding、background 和宽度,并用最小、可回滚的覆盖消除外部样式造成的尺寸差异:
html, body, main, .poster-shell { box-sizing: border-box; }
html, body, main { margin: 0; padding: 0; background: var(--crayon-bg); }
不要为了消除空隙直接改 min-height:100vh 或重构 DOM;先验证是否实际加载了旧版 .page { width: calc(100% - 20px) }。
编号列与时间轴几何对齐
时间轴 left 应和编号列边界使用同一基准。
- R6 桌面端(crayon poster-shell 已升级):
grid-template-columns: 100px 1fr,时间轴left:96px,编号padding-right:32px。100 / 96 / 32 三值必须成套调整。 - R6 移动端:
grid-template-columns: 72px 1fr,时间轴left:68px,编号padding-right:24px。 - R5 旧档位(不推荐,仅用于历史卡):
grid-template-columns:68px 1fr,时间轴left:68px,编号padding-right:10px;移动端48px 1fr+left:48px+padding-right:8px。
编号 padding-right 只提供视觉留白,不应承担列定位。如果数字与时间轴看上去贴线,先检查 padding 是否足够(≥24px),再判断是否要扩列宽:
.poster-shell .card-stripe { left: 96px; }
.poster-shell .card-num { padding-right: 32px; align-self: center; }
@media (max-width:720px) {
.poster-shell .card-stripe { left: 68px; }
.poster-shell .card-num { padding-right: 24px; }
}
若色彩类只写了 background-color,不能覆盖时间轴已有的 background-image 渐变;按条目换色时应替换对应的渐变 background-image。
1. 检查线上版本
curl -s --max-time 12 'https://example.com/card.html' > /tmp/card.html
检查预期版本标记、.skill-card 内 DOM 顺序 stripe → num → body、线上 CSS 修复值。不要只根据浏览器旧截图判断部署状态。
2. 检查 DOM 结构
import re
html = open('/tmp/card.html').read()
first = re.search(r'<div class="skill-card">(.*?)</div>\s*<div class="skill-card">', html, re.S)
chunk = first.group(1)
assert chunk.index('card-stripe') < chunk.index('card-num') < chunk.index('card-body')
若 card-num 出现在 card-body 之后,先修 HTML,不要只改 CSS。
3. 检查 computed layout
const card = document.querySelector('.skill-card');
const num = card.querySelector(':scope > .card-num');
const body = card.querySelector(':scope > .card-body');
const stripe = card.querySelector(':scope > .card-stripe');
console.table({
card: card.getBoundingClientRect().toJSON(),
num: num?.getBoundingClientRect().toJSON(),
body: body?.getBoundingClientRect().toJSON(),
stripe: stripe?.getBoundingClientRect().toJSON(),
bodyGridColumn: getComputedStyle(body).gridColumn,
});
预期:num.left 接近 card.left;body.left 约为 card.left + 编号列宽度;body.width 占据剩余宽度;stripe.left 位于编号列右边缘附近;bodyGridColumn 为 2。
4. 移动端同步检查
在 max-width:720px 下,四个值必须成套调整:
.skill-card { grid-template-columns: 52px 1fr; }
.card-num { width: 52px; font-size: 44px; }
.card-stripe { left: 48px; }
.card-body { padding-left: 14px; padding-right: 10px; }
不要只修改 grid-template-columns,否则编号或时间轴会漂移。
5. 视觉验收
先做 DOM/CSS 确定性检查,再做截图。截图只用于确认:编号位于左侧、时间轴线与圆点在编号列右缘、标题正文标签从正文列开始、移动端无横向溢出或裁切。
视觉模型误读平台外壳、浏览器缓存或旧 CDN 时,以线上 HTML/CSS token 和 DOM 顺序为 ground truth。
常见失败模式
| 症状 | 根因 | 正确处理 |
|---|---|---|
| 编号跑到右侧 | .card-num 嵌套在 .card-body,无法参与祖先 grid |
把编号移到 .skill-card 直接子级 |
grid-column:1 看似存在但无效 |
元素不是该 grid 的直接 item | 修 DOM 层级,不是继续堆 CSS |
| 时间轴偏移到正文内部 | .card-stripe 定位基准被错误嵌套层级改变 |
移为 .skill-card 直接子级并相对 card 定位 |
| 移动端编号贴边或线错位 | 只调列宽,没有同步 num width/stripe left/padding | 按移动端四值成套调整 |
| 用户截图仍是旧版本 | CDN、浏览器或平台缓存 | curl 核验线上 HTML,再说明缓存可能性 |
| 本地主题正确、具体卡片错误 | 主题模板与卡片内联 CSS 隔离 | 检查具体卡片 HTML;需要显式同步内联组件 CSS |
交付要求
完成修复后报告根因、修改范围、桌面与移动端确定性检查、build/verify/leak 结果、公网 URL 与线上 DOM/CSS 验证结果。
若现有主题技能已记录旧版列宽或旧骨架,应在其 references 中补充本类修复;若该技能受保护不可编辑,则保留本技能作为布局调试补充,并在交付中说明存在主题技能重叠。
04 同仓库更多 Skills
authorized-infocard-execution
Use for authorized infocard runs after tool failures.
web-capture
Use when a web page needs screenshots or device simulation. Capture desktop, mobile, and tablet screenshots via agent-browser and return auditable image paths.
infocard-x-content-tracing
X content to upstream project/author tracing.
infocard-visual-pass-loop
Screenshot-and-fix loop when 200 passes but theme is broken.
infocard-topic-selection
Use when selecting or evaluating information-card topics from the user's profile or explicitly supplied themes; judge value and visual expression potential without choosing a concrete infocard theme or publishing.
infocard-theme-validation
Use when changing infocard theme CSS or pushing docs.