用途
Vaadin Form Layout 是一个面向 Vaadin Flow（Java）的智能体技能，用于构建表单、实体编辑器或数据录入视图的视觉结构与布局。它可以从任意规格来源出发，包括 Figma URL、截图或文本提示，生成符合要求的表单界面。
主要能力
该技能的核心能力是依据输入规格规划并实现表单布局。它支持处理三种规格来源：抓取并检查 Figma URL、读取截图、解析文本提示。对于定义明确的规格（如显式字段列表，或带有清晰字段和标签的设计），技能会严格按规格实现，不虚构额外字段、不重命名标签、不添加规格未要求的控件，确保输出可预测且忠实于输入。对于模糊请求（例如“做一个客户表单”但没有字段列表），技能会先提出几个有针对性的澄清问题，包括字段及其数据类型、如何分组、是单区还是多区，不会静默猜测内容。
在内容确定后，技能会规划结构并记录在 TODO 中，包括字段列表及每个字段的数据类型、分区布局（单区、垂直堆叠分区或水平并排分区），以及最匹配的参考示例。分区指导原则：当表单涵盖多个逻辑字段组（如基本信息和地址）时，拆分为多个 FormLayout 实例，每个分区一个，各自带有跨越整列宽度的标题。标题元素级别应与周围视图层级匹配；若无法从周围代码判断，默认使用 H4。分区可用换行的 HorizontalLayout 并排排列（等比例伸缩，窄视口换行为单列），或用 VerticalLayout 堆叠。
使用方式
工作流程分为三步，作为 TODO 跟踪以便中断后恢复。
第一步——理解输入并规划。 先处理规格来源：抓取并检查 Figma URL、读取截图或解析文本提示。明确规格直接实现；模糊请求先澄清。然后规划结构并记录：字段列表及数据类型、分区布局、匹配的参考示例。
第二步——收集参考资料。 根据规划确定的组件集：解析主题，检查 Application.java 中的 @StyleSheet 导入，Aura.STYLESHEET 对应 Aura，Lumo.STYLESHEET 对应 Lumo（未找到主题时 Lumo 为默认）。主题影响组件变体，例如水平单选组使用 RadioGroupVariant.AURA_HORIZONTAL 还是 RadioGroupVariant.LUMO_VERTICAL。端到端阅读匹配的参考示例。通过 mcp_vaadin_get_component_java_api 获取每个将使用组件的 Java API 文档，包括 FormLayout，因为方法签名在不同 Vaadin 版本间存在差异。
第三步——编写 UI 代码。 按照所选参考示例的模式实现表单。表单主体始终使用 FormLayout。关键布局概念包括：自动响应式，使用 setAutoResponsive(true) 配合 addFormRow(...) 从最宽行推断列数，结合 setExpandColumns(true) 和 setExpandFields(true) 填充可用宽度，适用于等宽字段；响应式步骤，作为自动响应式的替代，使用 setResponsiveSteps(...) 在特定断点定义显式列数，适用于需要精确控制不同宽度布局的场景；列跨度，向 form.add(field, n) 传入列数，或使用 FormRow 为每个字段设置 colspan 以支持非对称行；约束宽度，设置 setMaxWidth/setMinWidth 以在大视口下保持表单可读；非对称行，当一行中字段需要不同宽度时，将它们包裹在 HorizontalLayout 中并作为单个全宽项添加。
参考示例
技能提供四个参考示例文件。references/horizontal-sections-form-example.md 展示双分区实体表单，包含并排自动响应式 FormLayout 面板、等比例增长的 HorizontalLayout 包装、通过 HorizontalLayout.expand 实现的非对称字段行、只读字段、水平 RadioButtonGroup（Aura）、带默认值的 ComboBox、带辅助文本的 NumberField。references/vertical-sections-three-column-form-example.md 展示三分区员工表单，包含堆叠的 VerticalLayout 分区、三列自动响应式 FormLayout、FormRow colspan、DatePicker、EmailField、电话辅助文本。references/compact-single-section-form-example.md 展示紧凑单区表单，包含渐进式披露（CheckboxGroup 条件显示字段）、带动态辅助文本的水平 RadioButtonGroup、通过 HorizontalLayout 实现的非对称字段行、图标前缀、实时计算的摘要标签、约束表单宽度。references/compact-labels-aside-form-example.md 展示紧凑标签侧置表单，使用 setLabelsAside(true) 实现两列标签/字段布局、CustomField 组合将 NumberField 和 ComboBox 合并为单个表单项、带字符限制的 TextArea、必填字段指示器、约束表单宽度。
适用场景
适用于在 Vaadin Flow（Java）项目中创建表单、实体编辑器或数据录入视图，尤其是需要从设计稿、截图或文本描述快速生成结构化表单布局的场景。
限制
该技能依赖 Vaadin Flow 和 FormLayout 组件。方法签名因 Vaadin 版本而异，需通过 API 文档确认。对于模糊请求需要先澄清，无法在无字段列表时自动推断内容。主题解析依赖 Application.java 中的 @StyleSheet 导入。