loamui

使用 LoamUI

面向 Agent 辅助开发者的现代 UI 基元。区域声明其含义，内部组件会相应调整；你组合的是部件，而不是配置 props。结果必须符合要求，也必须看起来是为其主题精心设计的。

真正的信息来源

• 离线参考文档由文档生成，随项目存放在 references/ 下；从索引开始。在线版本：在任意 https://loamui.com 页面后追加 .md；索引位于 https://loamui.com/llms.txt。
• 使用组件前先阅读其参考文档：其中介绍部件、props、自定义属性、适用场景及无障碍规范。
• references/recipes/ 下的配方是可移植的 React 和 CSS 示例，附有设计决策。按用途选一个匹配的配方，再进行调整；配方指南说明了具体方法。
• 参考文档与同一提交版本的库相对应。如果行为有所不同，请检查 node_modules/@loamui/core/package.json 中安装的版本。

1. 检查项目

运行 npx loamui@latest doctor。如果报告指出缺少配置，运行 npx loamui@latest init 可在现有配置基础上补齐；如果它会替换冲突的工具或样式，请先征求同意。配置是工具的工作，不是你的：工具能够处理时，不要手动接入样式表、lint 或检查。AGENTS.md 中的 ## LoamUI 章节会记录它完成的配置和 check 命令。确认当前 Agent 能发现以下四项技能：loamui、frontend-design、modern-css 和 modern-web-guidance。如果配置受阻或被拒绝，请商定缩减后的交付范围，并在报告中说明。如果没有代码仓库，请先确认环境能做什么；切勿伪造 @loamui/core 导出、在原生元素上借用 loam-* 类名，也不要把近似实现称为 LoamUI。

2. 先设计，再编写代码

遵循 frontend-design 技能：以主题和受众为依据，撰写简短的设计方案（配色、字体、布局构想、原则，以及一个令人难忘的亮点），检查设计是否流于普通，然后再开始构建。技能之间若有分歧，分工固定如下：用户需求决定内容；frontend-design 决定方向；LoamUI 决定表现方式。 方案中的颜色将成为 oklch() 中的 light-dark() 成对令牌输入，字体将成为 --loam-font 和 --loam-font-display，间距取自间距比例尺，规则放在图层和作用域中，且底层不应添加重置样式。设计指南介绍了映射方式、主题样式表和页面级指导。默认配色和 system-ui 只是起点，并非完整设计：真正的产品应有自己的主题。

三种基元

1. 令牌（--loam-*）：少量语义化输入，其余内容均由此派生。主题化就是覆盖这些输入。
2. 元素样式：为原生 HTML 设置样式，使其默认具备响应式和浅色／深色模式适配能力，并作用于整个页面。
3. 组件：由以上两者组合而成的精选集合，仅在原生元素缺少相应结构时添加：例如关联标签与错误信息的字段、能锁定焦点的对话框、支持焦点轮转的菜单。其他情况下，带有作用域规则的语义化元素就是你的组件。

规则

• 原生平台。 使用真实元素表达语义，使用静态 CSS 进行样式设置。 操作使用按钮，目的地使用链接。使用 showModal() 的 <dialog>、 <details>，以及带标签并支持键盘操作的原生控件。
• 现代 CSS。 配方规则位于 @scope (.recipe) to ([class*="loam-"]) 内的 @layer loamui.components 中； 使用嵌套、逻辑属性、容器查询、内在网格与弹性布局，以及相加且不重叠的查询范围。在作用域内，标记就是 API：按类型引用元素 （h2、figure、nav、h1 + p）；类仅用于区分同级的同类型元素，绝不能作为样式钩子，也不应存在仅用于承载类的包装元素。不使用 !important、BEM、重置样式、像素尺寸或视口单位来设置尺寸。必须在任何配方注册图层之前建立 @layer loamui.tokens, loamui.elements, loamui.components; 顺序。原生使用基线广泛可用和新近可用的功能；除此之外的功能都属于渐进增强，绝不暗中更改项目的浏览器策略。
• 组合。 简单需求使用可调用组件，组合时使用命名部件，支持的元素替换使用 render。图标和加载器作为子元素。Field.Root 内的控件会接收其标签、描述和错误关联；Field.Item 用于限定分组选项的作用范围。
• 情境化。 在承载特定含义的区域上声明 --loam-context；其中所有内容都会随之调整。尺寸根据可用空间变化。不提供 size、variant、color 或 fullWidth 属性；例外是内在显示尺寸（Badge、Loader、Progress、Meter）以及平台自身的数值。身份仅作为最后手段：使用品牌色包装元素是合理的，为单个元素设置颜色则不合理。
• 无障碍。 使用语义化 HTML、带名称的控件，并支持键盘操作、焦点和用户偏好。绝不移除焦点环，也不单靠颜色传达状态。必填是默认状态；如为选填，需用文字标明。错误信息应使用问题本身的措辞，说明发生了什么以及如何修复。提交后显示新错误；原生约束错误在修正内容有效后应清除。

组件

类别	组件
输入	Field、Fieldset、ErrorSummary、Button、Input、Textarea、Select、DateInput、Checkbox、Radio、Switch、Range、Search、QuantityInput、Rating、FileInput、CopyButton、Combobox、PasswordInput、SegmentedControl
数据展示	Badge、Price、Time、Card、Avatar、Table、Separator、Carousel、Stepper
反馈	Alert、Progress、Meter、Skeleton、Loader、Toast
披露	Details、Tooltip、Modal、Drawer、Popover、Menu
导航	Tabs、SignpostLink、SkipLink、Breadcrumbs、Pagination、Nav
实用工具	VisuallyHidden

不包含布局组件（使用间距令牌的原生 grid、flex 或 flow），不包含 Heading 或 Text（使用语义元素加作用域规则即可），不包含 Accordion （对应 Details），也不包含 Slider（对应 Range）。

3. 组合

1. 在 modern-web-guidance 中搜索工作所需的每种平台模式，并阅读适用的 modern-css 规则；阅读配方指南、最接近的配方，以及所用每个部分的契约。
2. 根据设计计划编写主题样式表；在核心样式之后加载。
3. 按合理顺序使用配方组装页面，以间距比例设置各区块的节奏，并将 正文宽度限制为 var(--loam-measure)。
4. 使用原生 CSS 布局。使用 :root 或作用域设置主题令牌；绝不修改组件内部结构或其私有 --_* 属性。
5. 保持交付内容可移植：使用 React 和 CSS，提供应用所需的集成，在明确的边界后提供实际操作，不包含仅供文档使用的机制。

没有现成配方时

这些配方是经过实践的参考示例，不是目录。页脚、统计数据栏、客户评价、Logo 行、价格表：真实网站的大部分内容都没有现成配方，而构建好这些内容正是这项技能的工作，并非缺失。按以下阶梯逐级尝试，在第一个能满足需求的层级停下：

1. 使用元素样式已经设置好的原生元素：<footer>、<table>、<blockquote>。通常这样就够了。
2. 使用带作用域规则的语义元素：@scope (blockquote.testimonial)。按它在产品中的实际用途命名，而不是使用设计系统中的别名。
3. 组合现有组件和元素：Card 网格、Nav、Field 表单。
4. 只有在原生元素缺少所需行为时，才创建新组件。

无论处于哪个层级，都要让它具备每个配方都有的结构：单独的组件文件，样式表与其并列，绝不在页面中内联 JSX；只有一个根类；规则放在 @scope (.root) to ([class*="loam-"]) 内的 @layer loamui.components 中；颜色、间距和字体均来自令牌；测量容器置于它所控制的布局之外；每个分区只承担一项职责；标题层级恰当；内容真实。页面负责组装分区，而不是包含分区。以最接近的配方为结构范本，绝不要强行套用其内容。绝不能借用 loam-* 类名、虚构部件或替换成其他库。第 4 步中的审查要求同样适用于它，也适用于经过调整的配方。

人们常犯的错误

• 虚构 size、variant 或 color 属性。 颜色由区域决定，尺寸由容器决定，宽度由父级布局决定。Modal 和 Drawer 的宽度分别由 --loam-modal-size 和 --loam-drawer-size 控制。
• 保留默认值。 编写代码前先查看设计。
• 用 type="number" 表示数量。 每次递增 1 的数量应使用 QuantityInput；其他数字应使用带 inputMode 的 Input。
• 在原始元素上借用 loam-* 类。 类名不是 API；组件包含该类名不具备的联动逻辑和测试。
• 把链接装扮成按钮。 显眼的导航使用 SignpostLink；普通导航使用 <a>；Button 用于执行操作。
• 重复设置 Field 的联动逻辑。 让 Field.Root 提供这些逻辑；仅在确实存在关联时添加显式 ID。对于重复使用的配方，使用 useId。
• 必填星号和“This field is required”。 请查看相关规则。
• 先重置样式，再重新设置。 元素样式是基础；在此基础上构建。
• Input 的包装器。 className、style 和 ref 指向原生输入框；wrapperProps 指向其外层容器。Input 提供 startSection 和 endSection。
• 已移除的间距名称。 --loam-space-sm/md/lg 已不存在；间距刻度为 4xs 到 4xl，固定几何尺寸使用 --loam-space-fixed-*。

4. 审查，然后报告

只有经过审查，才可报告；审查应作为独立环节进行，并按以下顺序记录审查结果：

1. 门禁。 运行项目的 check 脚本（CSS lint、JS lint、组合、格式检查）、类型检查器和测试。修复它们报告的问题；绝不要为了通过检查而禁用检查。不要手动复核它们已验证的内容。
2. 理念。 对照上述规则重新审视组合：原语顺序正确、组件前有原生元素、使用上下文而非属性、使用部件而非配置、Field 接线、范围甜甜圈、不重置、只在合理的地方使用 identity、每个部分各有自己的组件文件。
3. 现代 CSS。 对照 modern-css 规则重新审视编写的 CSS，检查 lint 不会强制执行的规则：仅使用 oklch()、带 rem 项的流式 clamp()、顺流方向属性、优先使用 :has() 而非状态类、优先使用容器单位而非固定间距、范围不重叠、动效须选择启用，以及对于范围内的每个类，判断类型选择器是否足以实现。
4. 现代 Web 指南。 对第 3 步中检查的每种模式，确认已采用指南中的做法，或说明未采用的原因。
5. 渲染结果。 检查两种配色方案在窄屏和宽屏下的显示效果、长文本、键盘与焦点、减少动态效果、强制颜色；测量主题变更涉及的每一组对比度。然后检查设计方案：有一个令人难忘的亮点，其余内容都保持低调，并移除了一项内容。

每条发现都应注明 文件:行号、违反的规则及修复方法；修复后重新运行受影响的门禁。报告运行了什么、发现并修复了什么、检查了什么，以及还有什么未经验证。通过检查只能作为其所检查内容的证据，绝不代表全面符合规范。

实践参考

• 设计、主题和页面节奏：references/guides/design.md。
• 令牌和深色模式：references/guides/tokens.md；布局： references/guides/layout.md；排版：references/guides/typography.md。
• 区域和 identity：references/guides/contextualism.md。
• init 设置的内容，以及完整的 Agent 合约： references/guides/agent-workflow.md。
• 一个组合表单：references/recipes/forms/sign-in-with-errors.md；一个页面开场区：references/recipes/heroes/hero-with-image.md。
• 所有组件：references/components/<slug>.md。