| name | infocard-creation-preview-standards |
| description | Use when creating or revising infocard HTML so preview entrypoints and creation-time responsive constraints stay consistent across themes. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| metadata | {"hermes":{"tags":["infocard","preview","responsive","live-server"],"related_skills":["infocard-mobile-verifier","infocard-publish-sop"]}} |
Infocard Creation & Preview Standards
Overview
This skill defines the style-agnostic base rules for infocard creation and preview.
It exists to keep four things stable across all infocard themes:
- the local preview entrypoint
- the preview URL shape
- responsive authoring constraints that must be handled during writing/building, not only during QA
- the specific rule for wide tables on phone-width layouts
This skill is not a theme skill. It does not control colors, typography personality, or visual language. It controls the cross-theme creation and preview contract.
Verification Evidence Discipline
- Treat static validation and visual preview as separate gates: HTML parsing, YAML parsing, forbidden-term checks, and CSS/viewport inspection do not substitute for a real browser screenshot.
- Before claiming visual verification, confirm that the preview server actually serves the target file (HTTP status and non-empty response). If a port is occupied, inspect or choose another available port rather than assuming the existing process is healthy.
- If browser navigation is redirected to an unrelated page or the local server returns an empty response, report visual preview as incomplete; do not present static checks as screenshot evidence.
- Keep the deliverable usable even when preview infrastructure is unavailable: complete the HTML, run deterministic static checks, and clearly separate verified facts from unverified visual claims.
When to Use
Use this skill when:
- creating a new infocard
- rebuilding an infocard from scratch
- revising layout, structure, responsive behavior, or table presentation
- previewing a card before publish
- checking whether a layout rule belongs to creation-time standards rather than one specific theme
重建 vs 补丁（关键区分）
触发"重建"（从零骨架重写）的信号：
- 用户明确说"重建"
- 用户说"样式存在问题"且非单点小修复
- HTML 文件已有多次补丁累积，结构出现裂缝（标签错位、重复闭合、空 div 残留）
- 换主题（如从 main-style 换到 hardblue）
重建标准操作：
- 读取
theme/<theme-name>.html 完整 CSS 骨架（不是参考 HTML 片段）
- 从零写 HTML，用 theme 的正式 CSS class（
.hero / .section / .section-no / .card / .risk 等）
- 禁止用 inline style 补丁代替结构重建；禁止保留旧卡换色
- 写完后用 Python HTMLParser 验证闭合标签
- 更新
meta.yaml 的 date + updated 为当前 Asia/Shanghai 时间戳
触发"补丁"（精准替换）的信号：
- 已知 HTML 结构完好，只需换文案、增删一行内容
- meta.yaml 时间戳或字段修正
- 关键词增删
禁止：对结构已有裂缝的 HTML 打补丁。裂缝只能通过重建修复。
Core Standards
0) Rule placement discipline
本 skill 只负责创建阶段的通用预览面和响应式约束。真实移动端验收、截图、DOM 诊断与修复统一交给 infocard-mobile-verifier；发布级门禁由 infocard-publish-sop 和 visual-verification-gate 负责。不要在这里复制下游验收或发布 SOP。
1) Standard local preview surface
All infocard local preview, including PC preview and mobile preview, should use the same LAN surface:
- server:
live-server
- host:
0.0.0.0
- port:
5588
- preferred LAN IP:
10.6.8.14
- URL shape:
http://10.6.8.14:5588/docs/<slug>.html
Canonical command:
REPO_ROOT="$(git rev-parse --show-toplevel)" || exit 1
cd "$REPO_ROOT"
live-server --host=0.0.0.0 --port=5588 --no-browser .
Rules:
- do not switch preview conventions between PC and mobile
- do not use old 4173/4174 preview habits unless 5588 is unavailable and that exception is stated explicitly
- do not substitute
python http.server for the standard infocard preview workflow
2) Preview is not mobile-only
The same preview surface is used for:
- PC layout review
- mobile layout review
- screenshot verification
- visual debugging before publish
This avoids split-brain workflows where desktop is checked in one environment and mobile in another.
3) Responsive constraints belong in creation, not only acceptance
If a layout problem is predictable during authoring, it must be handled while creating the card, not postponed until the final mobile QA pass.
This especially applies to:
- wide tables
- multi-column blocks
- code blocks
- image galleries
- dense stat grids
Do not rely on final QA to discover a structural issue that should have been designed out earlier.
3.1) Author-stage trigger declaration
Before authoring, the release bundle declares visual_review.required and its triggers. The Author must preserve that declaration and design the responsive behavior for every listed trigger; it cannot downgrade the card to static-only review. If the card introduces a new trigger-bearing element not listed in the bundle, report it to the main thread before handoff so the bundle/evidence plan can be updated. The handoff must identify the responsive treatment for each trigger (for example: multi-column → stack, table/code → dedicated local horizontal scrolling, fixed control → normal flow or safe area on mobile).
Wide Table Rule
4) Wide tables are a creation-time constraint
If a table is likely to exceed phone width, design it from the beginning with a dedicated horizontal scrolling container.
The correct strategy is:
- keep readable column widths
- preserve the rightmost columns
- allow horizontal scrolling inside the table region
The wrong strategies are:
- shrinking the entire page to force the table to fit
- scaling/zooming the viewport to fake a pass
- compressing columns until the text becomes unreadable
- clipping the rightmost columns
- replacing a structurally needed table with a broken pseudo-stack that loses comparison value
5) Wide-table acceptance condition on mobile
On a phone-width viewport, the table passes only if:
- the user can horizontally reach the rightmost column
- the text remains readable
- the table does not force the whole page into unusable overflow
- the rest of the page layout remains stable
This rule is style-agnostic. It applies across infocard themes.
6) Desktop readability rule for manual tables
Do not treat horizontal scrolling as the default desktop outcome for a core reference table.
If the desktop page width can reasonably accommodate the table, prefer:
- giving the table a full-width section
- moving auxiliary explanation below or above the table
- reserving split-column layouts for supporting notes rather than the main parameter matrix
Avoid putting the primary parameter/options table inside a left-right split that makes desktop users scroll sideways for information that should fit in one reading pass.
Mobile may still use an independent horizontal-scroll container when needed, but desktop should first try to preserve one-screen legibility for the main manual table.
Creation-stage checklist
- 在主 checkout 的
.docs/<run-id>/<slug>/ 创建或修订候选稿。
- 使用统一的
live-server 预览面检查桌面布局。
- 对宽表、代码块、多列块、图片和固定控件预先设计窄屏处理，并在交给
infocard-mobile-verifier 前记录处理意图。
- 需要移动端证据时，转交
infocard-mobile-verifier；本 skill 不执行移动截图或发布门禁。
Common Pitfalls
-
Treating preview as a mobile-only rule.
Wrong. The live-server + LAN URL rule is for both PC and mobile preview.
-
Putting wide-table logic only into QA skills.
Wrong. Wide tables are an authoring-time responsibility first, QA responsibility second.
-
Passing by shrinking the whole page.
Wrong. A readable table with local horizontal scroll beats a globally shrunken page.
-
Theme leakage.
Wrong. These rules belong to cross-theme creation/preview standards, not one specific style skill.
-
Using a different local server ad hoc.
Wrong. Standard infocard preview should converge on live-server at 10.6.8.14:5588 unless an explicit exception is documented.
References
references/manual-table-desktop-vs-mobile.md — when a manual/parameter table should become full-width on desktop while preserving local horizontal scroll on mobile.references/rule-placement-and-table-scope-2026-06-18.md — why cross-theme preview rules and style-agnostic wide-table constraints belong in this umbrella skill first.references/darkblue-theme-classes.md — darkblue 主题 CSS class 速查（调色板、hero、card、pill、grid 布局、SVG 简图规范），含完整参考源文件路径。
Handoff checklist
