logamee-html-constraint

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Logamee HTML Constraint Layer

Logamee HTML约束层

This skill checks HTML presentation/video output. It is not a theme, template, or layout authority. The content plan comes from
storyboard.md
/
slide-specs/
; visual skin comes from
theme-extraction.md
; this file enforces minimum quality.
An optional frontend-quality review may be used before this check as an aesthetic reference layer. It can improve composition, typography hierarchy, spatial rhythm, visual focus, and anti-generic aesthetics. It cannot override this contract.
此技能用于检查HTML演示文稿/视频输出。它并非主题、模板或布局权威。内容规划来自
storyboard.md
/
slide-specs/
;视觉外观来自
theme-extraction.md
;本文件用于强制执行最低质量标准。
在进行此检查前,可选用前端质量评审作为美学参考层。它能提升构图、排版层级、空间节奏、视觉焦点,避免通用化美学,但不能凌驾于本约束契约之上。

Inputs

输入项

  • deck.html
  • theme-extraction.md
  • slide-specs/
  • ../logamee-film-forge/references/TOOLKIT.md
If
deck.html
contains text that conflicts with
slide-specs/
, fix
deck.html
. Do not treat HTML as the text source.
  • deck.html
  • theme-extraction.md
  • slide-specs/
  • ../logamee-film-forge/references/TOOLKIT.md
deck.html
中的文本与
slide-specs/
存在冲突,需修改
deck.html
,不可将HTML视为文本来源。

Typography

排版

Every visible text element must use
clamp()
with a minimum of 18px.
Recommended video floor:
  • body / labels:
    clamp(24px, ..., ...)
    or larger when space allows
  • chrome text / page numbers: minimum 18px, high contrast
  • subtitles: sized for video viewing, not web-page reading
Line-height:
Font sizeMinimum line-height
<= 28px1.5
28-48px1.4
48px+1.2
Single-line labels of three characters or fewer are exempt.
所有可见文本元素必须使用
clamp()
,最小值为18px。
视频场景推荐下限:
  • 正文/标签:
    clamp(24px, ..., ...)
    ,空间允许时可更大
  • 界面文本/页码:最小18px,高对比度
  • 字幕:按视频观看场景设置尺寸,而非网页阅读场景
行高要求:
字体大小最小行高
<= 28px1.5
28-48px1.4
48px+1.2
三个字符及以下的单行标签可豁免此规则。

Spacing

间距

Use
clamp()
for padding, margins, and gaps. Avoid fixed pixel spacing except for unavoidable SVG geometry or hairlines.
Minimums:
  • title-to-body spacing: at least
    2rem
  • grid/flex gap: at least
    clamp(16px, 2vw, 24px)
  • dense horizontal layouts with more than six nodes: at least 100px per node, or split rows
  • paragraph-to-next-heading spacing: at least
    clamp(20px, 3vh, 32px)
Avoid squeezing content into the center. For dense slides, use the full slide area and sequence information through animation.
Breathing room is a quality requirement, not decoration. If the slide feels crowded, remove secondary labels or split the visual into clearer states before reducing font size, narrowing gaps, or pushing elements into the subtitle area.
内边距、外边距和间隙需使用
clamp()
。除不可避免的SVG几何图形或细线外,避免使用固定像素间距。
最小值要求:
  • 标题到正文的间距:至少
    2rem
  • 网格/弹性布局间隙:至少
    clamp(16px, 2vw, 24px)
  • 包含六个以上节点的密集水平布局:每个节点至少100px,或拆分多行
  • 段落到下一个标题的间距:至少
    clamp(20px, 3vh, 32px)
避免将内容挤在中心区域。对于密集型幻灯片,需利用整个幻灯片区域,并通过动画呈现信息序列。
留白是质量要求,而非装饰。若幻灯片显得拥挤,应先移除次要标签或将视觉内容拆分为更清晰的状态,再考虑缩小字体、缩小间隙或把元素推到字幕区域。

Contrast

对比度

  • body text vs background: at least 4.5:1
  • chrome text vs background: at least 4.5:1
  • muted text vs background: at least 3:1
  • --rule
    is for dividers only; do not use it for text
Avoid low-opacity chrome text such as
rgba(..., .3)
.
  • 正文与背景:至少4.5:1
  • 界面文本与背景:至少4.5:1
  • 弱化文本与背景:至少3:1
  • --rule
    仅用于分隔线,不可用于文本
避免使用低透明度的界面文本,如
rgba(..., .3)

Muted and Gray Semantics

弱化与灰色语义

Gray is not a decoration. Every muted or gray element must have a stated meaning: background context, previous state, external input, inactive option, secondary evidence, or de-emphasized but still readable material.
Rules:
  • Do not use gray only because the layout needs variety.
  • Do not use gray alone to express negation, rejection, replacement, or correction. If the meaning is "not this", prefer a clear strikethrough, removal, replacement, stamp, or correction arrow. Use a cross mark only when the semantic meaning is actually "wrong", "forbidden", or "invalid". The rejected text may become quieter, but it must remain readable and the rejection mark must carry the meaning.
  • Do not reduce important text to near-invisible opacity. De-emphasized text still needs to be readable in a paused video frame.
  • Prefer semantic hierarchy through weight, size, border, position, and accent rules before using low opacity.
  • If gray means "not currently in focus", keep the text legible enough for the viewer to understand what is being de-emphasized.
  • If gray means "disabled / unavailable", do not use it for information the viewer needs to understand the slide.
  • In final settled states, muted text should normally use the
    --muted
    token at full opacity. Avoid final text opacity below
    .72
    unless the text is decorative or explicitly not meant to be read.
  • If a slide uses gray for a semantic state, the
    visual-logic.md
    for that slide should say what the gray state means.
灰色并非装饰色。每个弱化或灰色元素必须有明确含义:背景上下文、历史状态、外部输入、非活跃选项、次要证据,或弱化但仍可读的内容。
规则:
  • 不可仅因布局需要多样性而使用灰色。
  • 不可仅用灰色表达否定、拒绝、替换或修正。若含义为“非此项”,优先使用清晰的删除线、移除、替换、印章或修正箭头。仅当语义为“错误”“禁止”或“无效”时,才可使用叉号。被拒绝的文本可弱化,但必须保持可读,且拒绝标记需承载明确含义。
  • 不可将重要文本设置为近乎不可见的透明度。弱化文本仍需在暂停的视频帧中可读。
  • 在使用低透明度前,优先通过字重、尺寸、边框、位置和强调规则构建语义层级。
  • 若灰色表示“当前未聚焦”,文本需足够清晰,让观众理解被弱化的内容。
  • 若灰色表示“禁用/不可用”,不可将观众理解幻灯片所需的信息设置为灰色。
  • 在最终稳定状态下,弱化文本通常应使用完全不透明的
    --muted
    令牌。除非文本为装饰性或明确无需阅读,否则最终文本透明度不可低于0.72。
  • 若某幻灯片使用灰色表示语义状态,该幻灯片的
    visual-logic.md
    需说明灰色状态的含义。

Stage and Layout

舞台与布局

The browser viewport is the video stage. Do not create a decorative dark frame around the slide.
Allowed:
  • fixed 16:9 recording viewport
  • full-viewport slide root
  • responsive constraints inside the slide
Forbidden:
  • a visible dark wrapper that makes the slide look framed
  • a small fixed slide floating inside a larger background
  • page layouts that depend on browser scroll
浏览器视口即为视频舞台。不可在幻灯片周围创建装饰性深色边框。
允许的设置:
  • 固定16:9录制视口
  • 全屏视口幻灯片根容器
  • 幻灯片内部的响应式约束
禁止的设置:
  • 可见的深色包裹层,使幻灯片看起来带有边框
  • 小尺寸固定幻灯片悬浮在更大的背景中
  • 依赖浏览器滚动的页面布局

Frontend Quality Boundary

前端质量边界

When an aesthetic review is used, treat it as an advisor, not as a new design system.
Allowed:
  • improve visual hierarchy, spacing rhythm, focal points, and compositional variety
  • replace generic card grids with content-specific visual structures
  • make typography choices more deliberate while still following theme tokens
  • add restrained texture, rules, panels, and emphasis when they help understanding
Forbidden:
  • overriding
    theme-extraction.md
    colors, mood, or token discipline
  • copying layouts, type scales, shadows, radius systems, or animation code from another theme
  • adding decorative effects that do not express the slide's content relationship
  • making the slide visually impressive at the cost of subtitle readability
  • introducing new UI frameworks or libraries
  • changing slide text, narration, subtitle source, or storyboard intent
若使用美学评审,需将其视为顾问,而非新的设计系统。
允许的操作:
  • 提升视觉层级、间距节奏、焦点和构图多样性
  • 用内容特定的视觉结构替代通用卡片网格
  • 在遵循主题令牌的前提下,更审慎地选择排版方案
  • 添加克制的纹理、分隔线、面板和强调效果,以帮助理解内容
禁止的操作:
  • 覆盖
    theme-extraction.md
    中的颜色、氛围或令牌规范
  • 从其他主题复制布局、字体比例、阴影、圆角系统或动画代码
  • 添加与幻灯片内容关系无关的装饰效果
  • 以牺牲字幕可读性为代价,追求幻灯片视觉冲击力
  • 引入新的UI框架或库
  • 修改幻灯片文本、旁白、字幕来源或故事板意图

Color and Theme Tokens

颜色与主题令牌

All component styles, SVG strokes/fills, subtitles, and tool configuration must use normalized local tokens from
theme-extraction.md
.
Allowed hardcoded color values:
  • only inside the root token definitions, for example
    --bg: #0b1020
  • rare semantic status exceptions, such as success/error marks, when tokenized alternatives do not exist
Forbidden:
  • hardcoded colors inside components
  • copying source theme layout, cards, type scale, shadows, radius system, or animation code
  • returning to the original theme skill after
    theme-extraction.md
    exists
Required token intent:
css
:root {
  --bg: ...;
  --text: ...;
  --muted: ...;
  --accent: ...;
  --accent-2: ...;
  --rule: ...;
  --panel: ...;
  --subtitle-bg: ...;
  --subtitle-text: ...;
  --chrome-text: ...;
}
所有组件样式、SVG描边/填充、字幕和工具配置必须使用
theme-extraction.md
中的标准化本地令牌。
允许硬编码颜色值的场景:
  • 仅在根令牌定义中,例如
    --bg: #0b1020
  • 罕见的语义状态例外,如成功/错误标记,且无令牌化替代方案时
禁止的操作:
  • 在组件内硬编码颜色
  • 复制源主题的布局、卡片、字体比例、阴影、圆角系统或动画代码
  • theme-extraction.md
    存在后,回归使用原始主题技能
必填令牌定义:
css
:root {
  --bg: ...;
  --text: ...;
  --muted: ...;
  --accent: ...;
  --accent-2: ...;
  --rule: ...;
  --panel: ...;
  --subtitle-bg: ...;
  --subtitle-text: ...;
  --chrome-text: ...;
}

Tools and Dependencies

工具与依赖

Default stack:
  • HTML
  • CSS
  • SVG
  • GSAP
This skill does not bundle runtime libraries. GSAP is the only default animation timeline tool, but it must be installed or fetched as a local dependency by the user's agent. Load it locally:
html
<script src="gsap.min.js"></script>
Rules:
  • no CDN scripts
  • if
    gsap.min.js
    is missing, stop HTML generation or preview and instruct the user's agent to install/fetch GSAP locally, then rerun the check
  • no anime.js
  • no CSS keyframes as main animation sequencing
  • no nested
    setTimeout
    animation choreography
  • no default Mermaid, ECharts, CountUp, Typed, Rough.js core, or canvas libraries
  • Rough Notation is allowed only for correction marks, circles, highlights, and hand-drawn emphasis
  • exception tools must have a content reason and must inherit theme tokens
默认技术栈:
  • HTML
  • CSS
  • SVG
  • GSAP
此技能不捆绑运行时库。GSAP是唯一默认的动画时间线工具,但用户的Agent需将其安装或获取为本地依赖。需本地加载:
html
<script src="gsap.min.js"></script>
规则:
  • 禁止使用CDN脚本
  • gsap.min.js
    缺失,需停止HTML生成或预览,并指示用户的Agent本地安装/获取GSAP,然后重新运行检查
  • 禁止使用anime.js
  • 禁止将CSS关键帧作为主要动画序列
  • 禁止嵌套
    setTimeout
    编排动画
  • 禁止默认使用Mermaid、ECharts、CountUp、Typed、Rough.js核心或画布库
  • 仅可将Rough Notation用于修正标记、圆圈、高亮和手绘强调效果
  • 例外工具需有内容层面的理由,且必须继承主题令牌

Animation

动画

Animation must implement the slide's
Animation
field as a cognitive sequence.
Required:
  • one GSAP timeline per slide
  • timeline starts when the slide enters
  • timeline is killed or rebuilt when leaving
  • timeline duration establishes the slide at a natural pace, usually within the first 4-6 seconds unless the user explicitly asks for semantic synchronization
  • motion establishes understanding: cause grows into effect, misconception is corrected, chaos resolves into order, hierarchy builds from base upward
  • relationship lines between nodes must be explicit visible segments in the gaps between nodes; do not draw one long background line through cards and rely on cards to cover it
  • important elements receive final focus through scale, position, contrast, or stillness
  • every major animation state, especially the final settled state, is readable as a still frame
  • the exact
    0%
    timeline state is a valid still frame: text is fully hidden or fully readable, never compressed into a shallow box, clipped to partial glyphs, or shown at an intermediate scale
  • animate text-bearing panels with full conceal/reveal techniques such as
    clip-path
    , masks, or an outer wrapper; do not squash the panel and its text with a nonzero
    scaleX
    /
    scaleY
    start
  • final settled state has no text-text overlap, text-line overlap, text-subtitle overlap, text-page-number overlap, or meaningful element hidden behind another element
  • Boundary QA has two independent layers: viewport containment and semantic-parent containment. A child can remain inside the 1920x1080 stage while still crossing the border of its card, dashed shell, panel, or framed system. For every bordered/background container, compare visible descendant bounding boxes against the parent content/border box at 0%, 25%, 50%, 75%, and 100%; more than 2px of unintended overflow fails the slide.
  • Decorative borders that visually claim to contain content must be implemented on the actual parent container. Do not draw an unrelated border and assume viewport overflow checks can validate it.
  • major visual changes should make the final slide structure clear; they do not need to track every narration/subtitle beat by default
Forbidden:
  • full-page fade-in as the only animation
  • all elements entering at once
  • rushing the entire slide in a 1-2 second default reveal
  • stretching animation across the whole narration only to match timing, when the slide would work better as an early established visual
  • decorative motion unrelated to the slide goal
  • animation that competes with subtitle readability
  • relying on motion to pass through unreadable or overlapping states
  • hidden relationship lines that only appear as stray borders, edge fragments, or unclear strokes around cards
动画必须将幻灯片的
Animation
字段实现为认知序列。
必填要求:
  • 每张幻灯片一个GSAP时间线
  • 时间线在幻灯片进入时启动
  • 离开幻灯片时终止或重建时间线
  • 时间线时长需自然呈现幻灯片内容,通常在前4-6秒内完成,除非用户明确要求语义同步
  • 动效应帮助理解:原因演变为结果、修正错误认知、从混乱到有序、从基础构建层级
  • 节点间的关系线必须是节点间隙中可见的明确线段;不可绘制一条穿过卡片的长背景线,依赖卡片遮挡多余部分
  • 重要元素需通过缩放、位置、对比度或静止状态获得最终焦点
  • 每个主要动画状态,尤其是最终稳定状态,作为静态帧时必须可读
  • 时间线的
    0%
    状态必须是有效的静态帧:文本完全隐藏或完全可读,不可压缩到狭窄的盒子中、裁剪为部分字形或显示为中间缩放状态
  • 使用完全隐藏/显示技术(如
    clip-path
    、遮罩或外部包裹层)带动文本的面板;不可使用非零的
    scaleX
    /
    scaleY
    起始值挤压面板及其文本
  • 最终稳定状态下,不可存在文本重叠、文本行重叠、文本与字幕重叠、文本与页码重叠,或重要元素被其他元素遮挡的情况
  • 边界QA包含两个独立层:视口容纳检查和语义父容器容纳检查。子元素可保持在1920x1080舞台内,但仍可能超出其卡片、虚线框、面板或框架系统的边界。对于每个带边框/背景的容器,需在0%、25%、50%、75%和100%状态下比较可见后代的边界框与父容器的内容/边框框;意外溢出超过2px则幻灯片不通过检查
  • 视觉上声称容纳内容的装饰性边框必须实现于实际的父容器上。不可绘制无关边框,依赖视口溢出检查验证其有效性
  • 主要视觉变化应清晰呈现最终幻灯片结构;默认无需跟踪每个旁白/字幕节拍
禁止的操作:
  • 将整页淡入作为唯一动画
  • 所有元素同时进入
  • 在1-2秒内快速完成整个幻灯片的默认展示
  • 仅为匹配时长而将动画拉长至整个旁白,而实际上幻灯片作为早期呈现的视觉效果会更好
  • 与幻灯片目标无关的装饰性动效
  • 影响字幕可读性的动画
  • 依赖动效跳过不可读或重叠的状态
  • 隐藏的关系线,仅以卡片周围的零散边框、边缘碎片或模糊描边形式出现

Screen Text and Subtitles

屏幕文本与字幕

Screen text is the visual skeleton. Subtitles are the spoken/readable layer.
Rules:
  • screen text must not repeat the subtitle
  • screen text should be keywords, numbers, labels, nodes, axes, or short claims
  • screen text should let the viewer understand the main visual claim without audio
  • narration/subtitles should carry examples, detailed explanation, qualifications, and connective reasoning
  • when subtitles are complete, prefer fewer screen words and stronger visual structure over detailed on-screen prose
  • subtitle overlay must be compact, floating, and readable
  • subtitle container should not compress the slide layout
  • subtitle position may move to avoid important visuals
  • subtitle display text comes from the slide spec
    Narration
    field by default
屏幕文本是视觉骨架,字幕是语音/可读层。
规则:
  • 屏幕文本不可重复字幕内容
  • 屏幕文本应为关键词、数字、标签、节点、坐标轴或简短主张
  • 屏幕文本应让观众无需音频即可理解主要视觉主张
  • 旁白/字幕应承载示例、详细解释、限定条件和关联推理
  • 字幕完整时,优先选择更少的屏幕文字和更清晰的视觉结构,而非详细的屏幕散文
  • 字幕叠加层需紧凑、悬浮且可读
  • 字幕容器不可压缩幻灯片布局
  • 字幕位置可移动以避开重要视觉内容
  • 字幕显示文本默认来自幻灯片规范的
    Narration
    字段

Explanatory Overlay Text Gate

解释性叠加文本检查

Never place "remark text" on a slide. A remark is any on-screen sentence that explains, labels, or restates what the visual or a provided asset already expresses. Examples that fail: a caption next to a QR code saying "扫描关注", a note under a WeChat graphic saying "课程更新的固定入口", a label over an obvious diagram saying "这是架构图". If the meaning is already carried by the image, geometry, or the subtitle layer, the overlay text is redundant and must be removed.
Apply three tests before adding any non-core text:
  1. Restatement test: is this sentence restating what the image, diagram, or existing screen text already shows? If yes, delete it.
  2. Deletion test: if this text were removed, would the viewer still understand the slide? If yes, it does not earn its place on the screen.
  3. Role test: does the text have a designed role — hierarchy, contrast, anchor, axis, node, number, or short claim — and a deliberate position in the composition? If it is only "placed somewhere to explain", it is remark text.
Provided assets (QR codes, promotion graphics, screenshots, logos) are complete visual statements. Do not attach explanatory labels, captions, or duplicative search hints beside them; the asset carries that information. Do not compensate for a busy slide by adding a text footnote; remove the noise instead.
All screen text must pass the same typography and composition standards as the core slide:
clamp()
sizing, theme tokens, intentional placement, and a defined relationship to the layout. A single un-designed sentence in a corner reads as a leftover and fails the slide.
In the final still-frame review, flag any text element that appears to be a remark, footnote, or caption rather than a designed part of the visual. Fix the slide, not the screenshot.
In non-audio review mode, subtitles may be split by punctuation and displayed by estimated duration. Estimate each subtitle segment from its own visible length, not by dividing the slide duration equally across all segments. For Chinese teaching narration, use a recorded project rate when available; otherwise default to about 5 visible characters per second, with small punctuation pauses and min/max clamps for readability. In video/preview mode after TTS, subtitles must first be recalibrated against the measured audio duration of each slide; if word-level or sentence-level timestamps are later generated, use them to refine the schedule.
Audio preview mode must be usable as a checkpoint, not only as a hidden recording path. If
?preview=1
is present, provide an explicit start control so the browser has a user gesture before audio playback. Preview mode may add this control, audio wiring, and timing logic, but it must not alter the static slide layout used for visual review.
Before TTS, provide a local subtitle-and-slide preview that does not read or play audio. A mode such as
?subtitlePreview=1
should use
Narration
, estimated speaking rate, natural text segmentation, estimated slide duration, and a short inter-slide pause so the user can approve subtitle wording, visual matching, and rough rhythm before any remote or expensive TTS call.
After TTS exists, preview timing must use the measured audio files. Slide advance should listen for the audio
ended
event and then hold a small pause before entering the next slide, with the measured duration only as a fallback. Subtitle segments may still be split from
Narration
before real word-level timestamps exist, but their display schedule must be scaled to the measured duration of the current slide rather than a fixed global character-speed estimate.
不可在幻灯片上放置“注释文本”。注释文本指任何解释、标注或重申视觉内容或已有资产所表达信息的屏幕句子。不合格示例:二维码旁的“扫描关注”、微信图下方的“课程更新的固定入口”、明显图表上方的“这是架构图”。若含义已由图像、几何图形或字幕层承载,则叠加文本属于冗余内容,必须移除。
添加任何非核心文本前,需通过三项测试:
  1. 重述测试:该句子是否重述了图像、图表或现有屏幕文本已展示的内容?若是,删除。
  2. 删除测试:若移除该文本,观众是否仍能理解幻灯片内容?若是,该文本无存在必要。
  3. 角色测试:该文本是否有明确的设计角色——层级、对比度、锚点、坐标轴、节点、数字或简短主张——且在构图中有明确位置?若仅为“随便放个地方解释”,则属于注释文本。
提供的资产(二维码、推广图、截图、Logo)是完整的视觉陈述。不可在其旁添加解释性标签、说明或重复的搜索提示;资产本身已承载该信息。不可通过添加文本脚注来弥补拥挤的幻灯片;应移除冗余内容。
所有屏幕文本必须符合核心幻灯片的相同排版和构图标准:
clamp()
尺寸、主题令牌、明确位置,以及与布局的定义关系。角落中单个无设计的句子会被视为遗留内容,导致幻灯片不通过检查。
在最终静态帧评审中,需标记任何看似注释、脚注或说明的文本元素,而非设计好的视觉部分。需修复幻灯片,而非修改截图。
在非音频评审模式下,字幕可按标点分割,并根据预估时长显示。需根据每个字幕片段的可见长度预估时长,而非将幻灯片时长平均分配给所有片段。对于中文教学旁白,若有录制项目速率则使用该速率;否则默认约每秒5个可见字符,并根据可读性设置最小/最大限制和标点停顿。在TTS后的视频/预览模式中,字幕需先根据每张幻灯片的实测音频时长重新校准;若后续生成单词或句子级时间戳,需使用这些时间戳优化进度安排。
音频预览模式必须可用作检查点,而非仅作为隐藏的录制路径。若存在
?preview=1
,需提供明确的启动控件,以便浏览器在音频播放前获得用户交互。预览模式可添加此控件、音频连接和计时逻辑,但不可修改用于视觉评审的静态幻灯片布局。
在TTS生成前,需提供本地字幕和幻灯片预览,无需朗读或播放音频。
?subtitlePreview=1
模式应使用
Narration
、预估语速、自然文本分割、预估幻灯片时长和短暂的幻灯片间停顿,以便用户在进行任何远程或昂贵的TTS调用前,批准字幕措辞、视觉匹配和大致节奏。
TTS生成后,预览计时必须使用实测音频文件。幻灯片切换应监听音频
ended
事件,然后短暂停顿再进入下一张幻灯片,实测时长仅作为 fallback。在生成真实单词级时间戳前,字幕片段仍可从
Narration
分割,但显示进度必须按当前幻灯片的实测时长缩放,而非固定的全局字符速率预估。

Icons and Symbols

图标与符号

  • no Unicode emoji
  • use inline SVG when an icon is needed
  • keep one icon language per deck: outline or filled, not mixed
  • SVG colors must use theme tokens
  • 禁止使用Unicode表情符号
  • 需要图标时使用内联SVG
  • 整套幻灯片使用统一的图标风格:轮廓或填充,不可混合
  • SVG颜色必须使用主题令牌

Page Numbers

页码

Every slide needs a page number such as
3/9
.
  • position: usually bottom-right unless it conflicts with content
  • token:
    --chrome-text
  • contrast: at least 4.5:1
  • do not make page numbers so faint they disappear in video compression
每张幻灯片需包含页码,如
3/9
  • 位置:通常在右下角,除非与内容冲突
  • 令牌:
    --chrome-text
  • 对比度:至少4.5:1
  • 不可将页码设置得过于暗淡,以免在视频压缩中消失

Brand Mark

品牌标识

If
storyboard.md
Decisions specify a non-empty fixed brand mark, show it as global slide chrome rather than as slide content. If
Brand Mark
is empty or
None provided
, do not render a footer mark.
  • default position: lower-left, visually paired with the page number
  • token:
    --chrome-text
    , with an accent rule or small typographic treatment when useful
  • do not repeat it in every slide's
    Screen Text
  • do not automatically reuse the topic title as the brand mark
  • if a brand URL is provided, it may appear as a second line of the brand mark
  • do not use an image logo unless the user provides one
  • reserve footer/subtitle space so the brand mark, page number, subtitle overlay, and visual content never overlap
  • the topic title must appear prominently on the cover, not only in the brand mark
storyboard.md
的Decisions指定了非空的固定品牌标识,需将其作为全局幻灯片界面元素展示,而非幻灯片内容。若
Brand Mark
为空或
None provided
,则不渲染页脚标识。
  • 默认位置:左下角,在视觉上与页码配对
  • 令牌:
    --chrome-text
    ,必要时可添加强调线或小型排版处理
  • 不可在每张幻灯片的
    Screen Text
    中重复出现
  • 不可自动将主题标题用作品牌标识
  • 若提供品牌URL,可作为品牌标识的第二行
  • 不可使用图像Logo,除非用户提供
  • 需预留页脚/字幕空间,确保品牌标识、页码、字幕叠加层和视觉内容永不重叠
  • 主题标题需在封面显著展示,不可仅出现在品牌标识中

Semantic Visual Expression

语义化视觉表达

A slide fails if it is only a styled transcript. A border gives content a container; it does not express what the content does or how the parts relate.
Before drawing any panel, write two things for the slide:
  • the semantic noun: process, system, hierarchy, contrast, timeline, state, evidence, correction, or another precise relation
  • the semantic verb: gather, transform, scan, monitor, branch, converge, stack, replace, circulate, reveal, or another visible action
Build the visual grammar from those two answers. Do not begin with a card grid and distribute labels into it.
若幻灯片仅为样式化的文字记录,则不通过检查。边框为内容提供容器,但不表达内容的功能或各部分的关系。
绘制任何面板前,需为幻灯片确定两点:
  • 语义名词:流程、系统、层级、对比、时间线、状态、证据、修正或其他精确关系
  • 语义动词:收集、转换、扫描、监控、分支、汇聚、堆叠、替换、循环、揭示或其他可见动作
基于这两点构建视觉语法。不可从卡片网格开始,再将标签分配到其中。

Anti-Template Gate

反模板检查

  • Use repeated cards only when the represented objects are genuinely equivalent and comparison is the intended reading task.
  • When items have different verbs, give them different internal structures.
    整理信息
    can show scattered marks becoming ordered rows;
    处理文件
    can show input, processing, and output;
    浏览网页
    can show a viewport and scan path;
    长期监控
    can show a time grid, pulse, and live state.
  • A different icon, border color, or accent bar does not make identical cards semantically different. Icons may reinforce recognition; they cannot substitute for action or relation.
  • Apply the text-removal test: temporarily hide labels. The remaining geometry should still suggest the major action, direction, containment, hierarchy, or state. It need not identify exact terminology, but it must carry more than decoration.
  • Apply the first-viewer paraphrase test: show the settled frame without explanation and ask what it expresses. Passing means the viewer can restate the main relation or transformation. Merely reading back visible labels is a failure.
  • Header words such as chapter names, phases, or section labels need a stable navigation grammar: index, anchor, track, hierarchy, or another explicit role. Bare text placed in a corner is not finished chrome.
  • If a reported slide exposes generic
    box + label
    construction, scan the entire deck for the same pattern before returning. Repair the system, not only the screenshot.
Check every slide:
  • one main goal
  • primary visual form matches the relationship: cause, contrast, hierarchy, timeline, system, correction, conflict, or conclusion
  • visual focus is clear within three seconds
  • minor context is visually quieter
  • cards are used only when they are genuinely the right structure
  • decorative elements carry meaning or support hierarchy
  • at least a few slides in the deck create strong visual memory
  • the final frame can be paused and understood without visible collisions
  • the slide does not try to put narration-level detail onto the screen
  • 仅当所代表的对象真正等效且预期任务为比较时,才可使用重复卡片。
  • 当项目具有不同动词时,需为其设置不同的内部结构。
    整理信息
    可展示零散标记变为有序行;
    处理文件
    可展示输入、处理和输出;
    浏览网页
    可展示视口和扫描路径;
    长期监控
    可展示时间网格、脉冲和实时状态。
  • 不同的图标、边框颜色或强调条无法使相同卡片在语义上产生差异。图标可强化识别,但无法替代动作或关系。
  • 应用文本移除测试:临时隐藏标签。剩余的几何图形仍应能暗示主要动作、方向、容纳、层级或状态。无需识别确切术语,但必须承载装饰以外的含义。
  • 应用首次观看者转述测试:展示稳定帧且不做解释,询问其表达的内容。通过标准为观看者可重述主要关系或转换。仅复述可见标签则不通过。
  • 章节名称、阶段或小节标签等标题文字需有稳定的导航语法:索引、锚点、轨迹、层级或其他明确角色。仅放置在角落的纯文本不属于完成的界面元素。
  • 若某幻灯片被报告存在通用
    盒子+标签
    结构,需在返回前扫描整套幻灯片是否存在相同模式。需修复整个系统,而非仅修改截图。
检查每张幻灯片:
  • 一个主要目标
  • 主要视觉形式匹配关系:原因、对比、层级、时间线、系统、修正、冲突或结论
  • 视觉焦点在三秒内清晰可见
  • 次要上下文在视觉上更弱化
  • 仅在卡片确实是合适结构时使用卡片
  • 装饰元素承载含义或支持层级
  • 整套幻灯片中至少有几张能形成强烈的视觉记忆
  • 最终帧可暂停且无冲突地被理解
  • 幻灯片未尝试将旁白级别的细节放到屏幕上

Self-Check

自检清单

  • Required source files exist and
    deck.html
    does not override slide spec text
  • Text uses
    clamp()
    with minimum 18px
  • Line-height meets the table
  • Padding, margins, and gaps use
    clamp()
  • Contrast meets body/chrome/muted thresholds
  • No decorative dark stage frame
  • Any aesthetic review stayed within the design-quality boundary
  • No CDN dependencies
  • Default stack is HTML/CSS/SVG + GSAP
  • Exception libraries have a content reason
  • GSAP owns animation sequencing
  • No CSS keyframes or nested
    setTimeout
    choreography
  • Screen text does not repeat subtitles
  • No remark text: no on-screen sentence explains, labels, or restates what the visual or a provided asset already expresses; provided assets carry no attached captions or duplicative hints
  • Every non-core text passes the restatement, deletion, and role tests before it stays on the slide
  • Screen text carries the main visual claim; subtitles carry detail and nuance
  • Subtitle overlay is compact and readable
  • Final animation state has no overlap or covered text
  • Every content slide was captured at 0%, 25%, 50%, 75%, and 100%; no state contains compressed text, half-visible glyphs, collisions, or elements passing through readable content
  • Every bordered/background semantic container passed child-vs-parent containment checks; no card, dashed shell, panel, or framed system has visible descendants crossing its border
  • A defect found on one slide triggered a deck-wide scan for the same animation or composition pattern
  • Final-frame composition uses the stage deliberately: no empty upper region paired with crowded footer content, and every large negative-space region has a stated semantic purpose
  • Crowded slides were simplified by removing secondary screen text, not by squeezing the layout
  • Every slide has a page number
  • Brand mark, if specified, appears consistently and does not collide with subtitles, page numbers, or content
  • No emoji; SVG icons are consistent
  • Component colors come from local theme tokens
  • Source theme layout/components/animation were not copied
  • Every slide has one goal and a fitting visual form
  • Every slide declares a semantic noun and semantic verb before layout is chosen
  • Repeated cards represent genuinely equivalent objects; items with different verbs use different internal visual structures
  • Hiding labels still leaves enough geometry to infer the main action or relation
  • A first-viewer paraphrase test can recover the slide's main relation, not merely repeat visible labels
  • Icons reinforce semantic structures instead of decorating generic
    box + label
    components
  • Chapter/phase chrome has an explicit navigation role rather than bare corner text
  • A generic-card defect found on one slide triggered a deck-wide anti-template scan
  • Animation follows semantic intent
  • Animation timing uses the approved visual rhythm: normally a 4-6 second opening build, or explicit semantic synchronization only when requested
  • Major animation events establish the slide clearly without dragging across the whole narration by default
  • No slide is just text arranged in cards
  • 所需源文件存在,且
    deck.html
    未覆盖幻灯片规范文本
  • 文本使用
    clamp()
    ,最小值为18px
  • 行高符合表格要求
  • 内边距、外边距和间隙使用
    clamp()
  • 对比度符合正文/界面/弱化文本的阈值
  • 无装饰性深色舞台边框
  • 任何美学评审均未超出设计质量边界
  • 无CDN依赖
  • 默认技术栈为HTML/CSS/SVG + GSAP
  • 例外库有内容层面的理由
  • GSAP负责动画序列编排
  • 无CSS关键帧或嵌套
    setTimeout
    编排动画
  • 屏幕文本未重复字幕内容
  • 无注释文本:无屏幕句子解释、标注或重申视觉内容或已有资产所表达的信息;已有资产无附加说明或重复提示
  • 所有非核心文本均通过重述、删除和角色测试后才保留在幻灯片上
  • 屏幕文本承载主要视觉主张;字幕承载细节和细微差别
  • 字幕叠加层紧凑且可读
  • 最终动画状态无重叠或被遮挡的文本
  • 每张内容幻灯片均在0%、25%、50%、75%和100%状态下被捕获;无状态包含压缩文本、半可见字形、冲突或穿过可读内容的元素
  • 每个带边框/背景的语义容器均通过子元素与父容器的容纳检查;无卡片、虚线框、面板或框架系统的可见后代超出其边界
  • 在一张幻灯片上发现的缺陷触发了整套幻灯片中相同动画或构图模式的扫描
  • 最终帧构图刻意利用舞台:无上部空白区域与拥挤页脚内容并存的情况,每个大的负空间区域均有明确的语义用途
  • 拥挤的幻灯片通过移除次要屏幕文本简化,而非挤压布局
  • 每张幻灯片均有页码
  • 品牌标识(若指定)一致显示,且不与字幕、页码或内容冲突
  • 无表情符号;SVG图标风格一致
  • 组件颜色来自本地主题令牌
  • 未复制源主题的布局/组件/动画
  • 每张幻灯片均有一个目标和合适的视觉形式
  • 每张幻灯片在选择布局前均声明了语义名词和语义动词
  • 重复卡片代表真正等效的对象;具有不同动词的项目使用不同的内部视觉结构
  • 隐藏标签后仍有足够的几何图形可推断主要动作或关系
  • 首次观看者转述测试可还原幻灯片的主要关系,而非仅复述可见标签
  • 图标强化语义结构,而非装饰通用
    盒子+标签
    组件
  • 章节/阶段界面元素具有明确的导航角色,而非角落中的纯文本
  • 在一张幻灯片上发现的通用卡片缺陷触发了整套幻灯片的反模板扫描
  • 动画遵循语义意图
  • 动画计时使用经批准的视觉节奏:通常为4-6秒的开场构建,仅在请求时进行明确的语义同步
  • 主要动画事件清晰呈现幻灯片,默认不拖长至整个旁白
  • 无幻灯片仅为卡片排列的文本

Demo Note

演示说明

references/demo.html
is historical visual reference only. It is not a compliance example. Current outputs must follow this file over the demo.
references/demo.html
仅为历史视觉参考,并非合规示例。当前输出需遵循本文件,而非演示文件。