着陆页构建 是做什么的?
将已批准的文案、视觉方向和设计令牌转化为一个即使关闭 JavaScript 也能完整运行的静态页面。完整意味着访问者可以阅读每个部分、从页眉导航到每个部分,并可以发送表单。动效和 3D 效果将在后续由 landing-skills:landing-motion 添加,它们基于一个已经能正常工作的页面之上。
在没有使用此技能构建的测试版本中,出现了两个 Bug,而此技能的设计使得这两个 Bug 都不可能发生:
- 一个带有
padding简写属性的容器类覆盖了节的垂直内边距,导致每个节都紧挨在一起。修复方案是结构性的:节拥有块轴的控制权,容器拥有内联轴的控制权,并且两者都不使用简写属性(第 5 步)。 - 一个无效的表单:
action="#"、onsubmit="return false",或者一个显示“谢谢”然后丢弃数据的脚本。修复方案是:一个真实的action、一个真实的method、一个服务器支持的成功页面,并且没有页面无法回退的成功消息(第 8 步)。
输入
在编写代码之前,从用户的项目中读取这些文件。
| 文件 | 你需要从中获取的信息 |
|---|---|
landing/brief.md | landing-skills:landing-page 写入的字段。你将用到:语言(用于 lang);转化操作(一个带有字段和端点的表单,或 none yet,或一个外部 URL);技术栈(按名称,或 detect);域名(生产域名,或 unknown);联系途径(用于页脚和 /form-error/);可用的资源 |
landing/copy.md | 每个页面部分对应一个 H2,按页面顺序排列;最后一个 H2 Placeholders 列出了所有空白 |
landing/direction.md | 字体(包含来源和许可)、每个部分的布局行、图片(包含宽高比)、表面(surfaces)、以及最后一个 H2 Motion and 3D intent |
landing/tokens.css | 自定义属性:--color-*、--font-*、--text-*、--space-*、--radius-* |
当某个输入缺失时:
- 没有
copy.md:不要自行编写营销文案。向用户索要文本,或建议使用landing-skills:landing-copy。如果用户交给你文本,请按原样使用。切勿编造证据:没有客户评价、标志、计数或评分。缺失的部分变成[PLACEHOLDER: 需要什么]。 - 没有
direction.md或tokens.css:首先建议使用landing-skills:landing-art-direction。如果用户希望在没有这些的情况下继续,请自行编写landing/tokens.css,包含五个前缀,从用户提供的品牌约束中推导出值,并告知用户这些令牌是临时的。 - 没有
brief.md:询问语言、转化操作(一个表单及其提交地址,或一个外部 URL)、生产域名和联系途径。 - 一个值为
unknown或none yet的 brief 字段是一个空白,而非错误:按照此技能为该情况设定的规则进行构建(没有域名则不添加 URL 标签;没有端点则使用/api/lead占位符;没有联系途径则使用占位符联系信息),并在交接清单中列出。当可以扫描项目文件时(请参见“技术栈检测”),检测技术栈,而不是在可以避免的时候询问。
流程
1. 检测技术栈
使用“技术栈检测”表格。在写入文件之前,阅读 references/adapters.md 中的相应部分;它只涵盖与其他参考资料中的通用方案不同的部分。
2. 创建清单
在任何标记之前,记录下来:
copy.md中的每个 H2 以及它对应的<section>,附带其id。tokens.css中的每个令牌名称。你将使用这些名称(而非其他名称)来表示颜色、字体、间距和圆角。- 方向中要求的每张图片、它的宽高比,以及文件是否存在。
- 来自简介的转化操作:一个外部 URL(链接,无表单),或一个带有字段和端点的表单。如果端点是
none yet,表单将提交到/api/lead,并且该空白将放入交接清单(第 11 步)。 - 域名(已知或
unknown)和联系途径,<head>、页脚和/form-error/需要这些信息。
3. 编写头部
标题、描述、规范链接、Open Graph 和社交卡片、favicon 集合、theme-color、lang、结构化数据。模板和规则在 references/seo-meta.md 中。从 copy.md 中获取标题和描述;一个默认标题(如框架的起始标题)是一个明显的标志。
4. 加载字体
自行托管方向中命名的 WOFF2 文件,声明与 tokens.css 中的字体堆栈完全匹配的 @font-face 族名称,添加一个度量匹配的回退字体,并且只预加载首屏上方使用的一到两个文件。references/performance.md 包含方案和经过测试的计算回退值的脚本。一个页面如果命名了一种字体但从未加载它,或者回退到 system-ui,将会在不同机器上呈现不同的效果。
5. 构建布局骨架
页面的每个行是一个 <section class="section">,内部包含一个 <div class="container">。两者永不分享职责:
/* 节负责垂直间距,容器负责宽度和边距 */
.section { padding-block: var(--space-section-open); }
.container {
inline-size: min(100% - 2 * var(--space-gutter), var(--space-content-max));
margin-inline: auto;
}
上面的令牌名称是示例;请使用你的 tokens.css 中的名称。references/css.md 列出了方案假设的每个令牌角色,以及当你的文件没有对应令牌时该怎么做。
容器没有设置任何内边距,因此没有任何规则顺序或特异性可以擦除节的间距。绝不要在节或容器类上编写 padding 或 margin 简写属性:简写属性会设置两个轴,并静默地替换另一个类设置的任何一个轴。这是消除 Bug 1 的规则。references/css.md 展示了这个正确版本旁边的错误版本,以及全宽出血和细线情况。
6. 构建各个节
- 使用语义元素:
header、nav、main、section、footer、ol(用于步骤)、dl或table(用于规格说明)、figure(用于带标题的媒体)。 - 一个
h1,位于英雄区域。每个节以一个来自copy.md的h2开头。不要跳过标题层级。 - 按照
direction.md中为该行指定的布局来排列每个节。当方向中布局未明确指定时,从references/css.md中的方案中选择;块的数量和形状遵循内容,因此只有当内容是三个相等的东西时,才会出现三个相等的卡片。 - 为每个颜色、字体、大小、间距和圆角使用令牌。绝不要在页面 CSS 中重新声明令牌。如果需要的值没有对应的令牌,则从令牌组合(
calc()、color-mix())并在交接清单中列出,以便方向可以添加它。 - 使用带有
clamp()的流式尺寸、逻辑属性、带有references/css.md中回退方案的oklch()颜色,以及针对那些根据自身宽度改变形状的组件的容器查询。
7. 放置媒体
真实图片应包含 width 和 height、描述图片内容的 alt 文本、带有回退方案的现代格式,并且仅在英雄图片上使用 fetchpriority="high"(references/performance.md)。尚不存在的资源将变成一个可见的、带标签的占位框,保持最终的宽高比,并包含类似 [PLACEHOLDER: 照片,从上往下看的工坊工作台,3:2] 的文本。不要给这个框设置 role="img":它会宣告一张不存在的照片。为每个占位框提供方向赋予该图片的宽高比、宽度和背景色,这样框架才能展示预期的布局,而不是一排相同的虚线框(references/css.md,媒体占位符)。绝不要绘制一个假的产品屏幕并将其作为产品呈现。
8. 构建转化操作
简介中的转化操作决定你要构建的内容:
- 一个外部 URL(结账、预订页面、应用商店):操作是一个链接
<a class="button" href="https://...">,标签来自copy.md。没有表单,没有form.js,也没有/thanks/或/form-error/页面;跳过此步骤的其余部分。如果简介说点击应该被计数,landing-skills:landing-launch会添加信标。 - 一个带有用户已拥有端点的表单:表单提交到该 URL,并且不使用
/api/lead占位符。仅当该端点重定向到结果页面时,才构建结果页面;否则,在交接清单中说明端点将访问者发送到哪里。 - 一个端点为
none yet的表单:表单提交到占位符/api/lead,landing-skills:landing-launch将其构建为一个 Worker。
对于表单,请阅读 references/forms-a11y.md。不可协商的部分:
<form action="..." method="post">,其中action是简介中的端点,或者action="/api/lead"并在旁边添加一个 HTML 注释说明该端点尚不存在,并在交接清单中列出。- 每个字段都有一个
name、一个可见的<label>、正确的type和autocomplete,并且当格式需要解释时,通过aria-describedby链接一个提示。 - 在没有 JavaScript 的情况下,浏览器提交表单,端点用
303重定向回复到你现在构建的两个静态页面之一:/thanks/和/form-error/。一旦landing-skills:landing-launch添加了 Turnstile,没有 JavaScript 的访问者将没有令牌,并且总是会到达/form-error/,因此该页面必须提供另一种联系方式,取自简介的联系途径。 - 始终将
references/forms-a11y.md中的form.js作为渐进式增强的一部分发布。表单在没有它的情况下也能工作;该文件仍然是构建的一部分,因为landing-skills:landing-motion扩展了它设置的状态,并且landing-skills:landing-launch会检查它们。它只在响应是 2xx 且其 JSON 主体显示ok: true时才显示成功。仅 2xx 本身只证明有东西回复了:fetch会跟随重定向并将目标页面的状态报告为 200,而一个静态主机可以用一个普通的 HTML 页面来回答 POST 请求。两者都在测试中出现过,并且两者都是失败。失败时,脚本会说明情况并保留访问者输入的内容。在服务器确认之前,绝不要重置表单或显示“谢谢”。
9. 满足可访问性基线
跳过链接、地标、一个链接指向真实节 ID 的 nav、链接到 / 的标志、每个可交互元素上可见的焦点样式、至少 44x44 像素的点击目标,以及页面实际渲染的每个文本和背景对的对比度检查:每个表面上的正文文本、说明文字、提示、占位符文本、强调色上的文本。详细信息和数字在 references/forms-a11y.md 中。在手机上隐藏链接且没有替换方案的导航不符合此基线;改为允许链接换行。
10. 不加入动效
在“减少动效”偏好设置下,减少的是运动,而不是反馈,因此不要编写任何全局规则来清零过渡。以最终、可见的状态构建每个元素。没有进入动画,没有 opacity: 0 等待脚本,没有滚动库。
对于方向的 Motion and 3D intent 中命名的每个时刻,留下一个占位表示:一个静态的海报图像,或一个带标签的占位框,处于该时刻的最终大小和宽高比,以便当 landing-skills:landing-motion 挂载真实效果时布局不会发生位移。用 data-moment="<name>" 标记它,使用方向为该时刻提供的短名称;动效通过该属性找到它的目标。占位表示在没有动效的情况下是完整的:一个带有 alt 文本的真实图片,或说明该时刻内容的占位符文本。
<div class="hero__media" data-moment="exploded-view">
<img src="/img/exploded-poster.jpg" width="1600" height="1000" alt="设备的各层展开:外壳、电路板、电池、镜头">
</div>
当意图为 none 时,不要添加 data-moment 元素。
11. 检查并交接
运行“完成定义”。然后,以简短列表的形式告知用户:
- 构建了什么及其位置(文件、输出目录),以及如果简介的 Stack 字段是
detect,则写入已解析的技术栈, - 页面上仍然存在的每个
[PLACEHOLDER: ...]以及需要提供的每个资源, - 按构建的转化操作:一个指向外部 URL 的链接,一个提交到用户端点的表单,或一个提交到尚不存在的
/api/lead的表单, - 表单提交的每个字段,每行一个:其
name、类型(email、tel、text、textarea)、是否为required、以及来自标记的maxlength。landing-skills:landing-launch将根据此列表设置其 Worker 的验证、长度限制、存储和请求大小限制,并拒绝它未被告知的字段, - 因为不存在令牌而组合的值,以及
tokens.css缺少的每个可选令牌以及方案为其使用的回退值, - 如果简介说
unknown,则为生产域名,以及因此遗漏的 URL 标签(规范链接、og:url、og:image、站点地图), - 简介中留空为
unknown的联系途径,页脚和/form-error/将其显示为占位符, - 每个未子集化的字体文件及其大小(字节),
- 每个未运行的“完成定义”检查,标记为“未运行”并说明原因,
Motion and 3D intent中的每个时刻:其data-moment名称及其占位表示所在位置(节和元素),如果意图为none则为“无”,- 下一个技能:当方向的
Motion and 3D intent命名了一个时刻时,使用landing-skills:landing-motion,然后使用landing-skills:landing-review,再然后使用landing-skills:landing-launch来托管和设置表单端点。
技术栈检测
按此顺序检查项目根目录,并在第一个匹配时停止。当项目文件夹为空时,由 brief.md 中的 Stack 字段决定。
一旦技术栈被解析,请将其写回:如果 landing/brief.md 的 Stack 字段是 detect,则用已解析的技术栈(例如 Astro 或 plain HTML and CSS)替换该单词,并且不更改 landing/brief.md 中的其他任何内容。后续技能将读取该字段,不应遇到未解析的单词。用户命名的技术栈保持原样。当没有 landing/brief.md 时,不要创建它。
| 项目中的信号 | 技术栈 | 适配器章节 |
|---|---|---|
astro.config.mjs(或 .ts、.js),或 package.json 依赖中的 astro | Astro | Astro |
...
[为翻译而截断]
