webcraft-skills 0.1.1

package/skills/webcraft-skills/references/workflows/build-ui.zh.md

@@ -0,0 +1,385 @@
+# UI Build Workflow
+
+用于从零生成页面、站点、组件或在现有项目中新增 UI。`build-ui` 的目标是生成真实可用、符合项目语境、后续可维护的界面，而不是生成一张漂亮但脆弱的概念图。
+
+Build 必须继承 audit、review、polish、fix 的质量标准：先理解目标和约束，再生成结构，最后自检和修复明显问题。
+
+## 1. 先确认构建场景
+
+开始前先判断用户要的是哪一种：
+
+- 新项目静态页面：例如完整 `index.html`。
+- 现有项目新增页面：例如 Next.js / Astro / Vue / Svelte / React 页面。
+- 现有页面新增 section。
+- 单组件或组件组。
+- 原型页面，用于快速展示想法。
+- 高保真页面，用于接近上线质量。
+
+不同场景的完成标准不同。不要把原型做成复杂工程，也不要把上线页面做成只适配理想内容的 demo。
+
+## 2. Build Modes
+
+根据用户目标选择构建深度：
+
+### Prototype Build
+
+- 用于快速验证想法。
+- 可以使用少量占位内容，但必须标明。
+- 不追求完整业务状态，但不能出现明显响应式崩坏。
+- 不添加后端、认证、数据库或复杂状态管理。
+
+### Page Build
+
+- 默认模式。
+- 构建一个真实可用页面。
+- 需要考虑响应式、核心状态、长内容和基础可访问性。
+- 适合 landing page、个人页、产品页、功能页。
+
+### Production Build
+
+- 用于接近上线质量的页面。
+- 必须补齐关键状态、错误/空状态、移动端、内容压力和验证。
+- 优先复用现有组件和 token。
+- 不编造真实业务信息。
+
+### Component Build
+
+- 用于单组件或组件组。
+- 必须考虑变体、状态、长内容、可访问名称、组合使用。
+- 不按整页标准过度设计组件。
+
+## 3. 询问与合理补全
+
+信息不足时不要机械追问，也不要随意编造。
+
+应该先问的情况：
+
+- 页面主体、产品名或目标用户完全不清楚。
+- 用户要求高保真或上线质量，但核心内容缺失。
+- 是否沿用现有风格、是否指定 preset、是否允许外部资源会影响实现方向。
+- 需求涉及真实价格、客户、指标、案例、合规或业务承诺。
+
+可以合理补全的情况：
+
+- section 顺序、按钮次级文案、空状态文案、FAQ 占位。
+- 示例列表、占位图片说明、非关键辅助文案。
+- 原型阶段的 mock 内容。
+
+合理补全必须克制、具体、可信，并避免伪造真实事实。
+
+## 4. 生成前检查清单
+
+动手前确认：
+
+- 构建模式是什么：Prototype / Page / Production / Component。
+- 页面类型是什么。
+- 目标用户是谁。
+- 主 CTA 是什么。
+- 内容是真实内容还是占位内容。
+- 是否在现有项目中构建。
+- 是否已有组件、token、视觉体系。
+- 是否提供了设计图、截图、Figma 导出图或参考页面。
+- 是否指定 preset。
+- 是否有技术限制，例如不使用外部资源、不引入新依赖。
+
+不要在这些关键点完全不清楚时直接生成大页面。
+
+## 5. 收集必要信息
+
+优先识别：
+
+- 页面类型：landing page、dashboard、docs、portfolio、form、checkout、settings、admin 等。
+- 主体名称：产品、人、品牌、项目或功能。
+- 目标用户：普通用户、开发者、企业客户、创作者、内部运营等。
+- 核心任务：注册、购买、阅读、搜索、管理、创作、联系、下载等。
+- 主要内容：首屏、功能、案例、价格、FAQ、表单、列表、数据、作品等。
+- 技术栈：HTML/CSS/JS、React、Next.js、Astro、Vue、Svelte、Tailwind、组件库。
+- 约束：不使用外部资源、必须移动端可用、必须沿用现有组件、必须保留品牌色等。
+
+信息不足时可以合理补全，但不要编造真实客户、价格、指标、案例、团队、公司或产品事实。
+
+## 6. 识别现有项目和视觉体系
+
+如果是在现有项目中构建，先检查：
+
+- 页面入口、路由结构和目录约定。
+- 全局样式、Tailwind 配置、design tokens。
+- 已有组件：Button、Card、Input、Modal、Nav、Table、Toast。
+- 现有视觉体系：颜色、字体、spacing、圆角、边框、阴影、组件状态。
+- 页面语气：营销型、工具型、内容型、后台型、个人品牌型等。
+
+默认沿用现有体系。不要在现有项目里强行引入另一套风格、组件库或 preset。
+
+## 7. 设计图 / 参考图输入
+
+当用户提供截图、设计图、Figma 导出图、参考页面截图或视觉参考时，先判断它的用途：
+
+- 结构参考：主要参考布局、信息顺序、组件关系。
+- 风格参考：主要参考颜色、字体感觉、圆角、边框、阴影、氛围。
+- 完整设计稿：同时参考结构和风格，尽量还原。
+
+### 新项目
+
+没有既有视觉体系时，默认按设计图的结构和风格生成。
+
+- 尽量还原设计图的信息结构、布局比例、视觉层级和组件关系。
+- 尽量还原颜色、字体感觉、圆角、边框、阴影和整体氛围。
+- 可以做必要的响应式、可访问性和真实内容适配。
+- 不要擅自换成其它风格或 preset。
+
+### 现有项目
+
+如果用户没有明确要求改变风格，默认：
+
+- 结构参考设计图。
+- 信息顺序和组件关系参考设计图。
+- 颜色、字体、圆角、按钮、卡片、表单等风格沿用现有网站。
+
+如果用户明确说“按图上的风格”“照这个设计稿实现”“视觉也按这个来”，则：
+
+- 可以按设计图风格实现当前范围。
+- 不要顺手改全站。
+- 如果设计图风格与现有系统冲突，说明冲突和影响。
+- 如果需要全站统一，建议后续做 design system 或 token 迁移，不要在当前任务里擅自扩展。
+
+### 不确定时
+
+如果用户没有说明设计图用途，且项目已有明确视觉体系，先问一句：
+
+```text
+这张图是作为布局结构参考，还是希望新页面也采用图里的视觉风格？
+```
+
+如果用户不想停下来确认，采用保守策略：结构参考设计图，风格沿用现有项目。
+
+## 8. Preset 使用规则
+
+- 用户明确指定 preset 时，按指定 preset 执行。
+- 用户没有指定 preset 时，先根据页面类型和现有项目语境选择合适方向。
+- 如果现有项目已有明确视觉体系，preset 只能作为参考，不得覆盖现有风格。
+- 不要默认套用 `cinematic-minimal`。
+- 不要为了“高级感”强行改成暗色、电影感、极简或 SaaS 风。
+
+Preset 是风格约束，不是产品事实来源。不要根据 preset 编造文案、案例或业务数据。
+
+## 9. 页面类型结构模板
+
+根据页面类型选择信息结构。模板只是起点，不要机械套用。
+
+### Landing Page / Marketing Site
+
+- Hero：是谁、做什么、给谁用、下一步动作。
+- Problem：用户当前痛点。
+- Solution：产品如何解决。
+- Features：少量具体能力。
+- Proof：真实案例、作品、指标或可信说明。
+- CTA：主行动和次行动。
+- FAQ：消除关键疑虑。
+
+### SaaS / Product Page
+
+- Hero：具体产品主张。
+- Use Cases：目标用户和使用场景。
+- Feature Detail：关键功能和实际工作流。
+- Screenshot / Mockup：服务理解，不炫技。
+- Pricing / Trial：如果用户提供或明确需要。
+- FAQ / Security / Support：根据产品语境补充。
+
+### Dashboard / Admin
+
+- Overview：核心指标或状态。
+- Controls：搜索、过滤、排序、时间范围。
+- Main Content：表格、列表、图表或任务流。
+- Detail / Action：详情面板、批量操作、状态反馈。
+- Empty / Loading / Error：数据状态。
+
+### Portfolio / Personal Site
+
+- Hero：人、定位、主张。
+- Selected Work：精选作品，不堆数量。
+- Process / Thinking：方法和判断力。
+- About：可信背景。
+- Contact：清楚但不过度销售。
+
+### Form / Checkout / Onboarding
+
+- Step Context：当前步骤和剩余路径。
+- Input Group：清楚 label、帮助、错误。
+- Review / Confirmation：确认信息和风险。
+- Submit State：loading、success、error、disabled。
+
+### Docs / Content Site
+
+- Title / Summary：页面主题。
+- TOC：目录或锚点。
+- Content Sections：清晰 heading 层级。
+- Code / Table：移动端可滚动或可换行。
+- Next Step：下一篇、相关文档、操作入口。
+
+## 10. 先规划信息结构
+
+生成视觉前，先建立信息结构：
+
+- 首屏：页面是谁、做什么、给谁用、下一步动作是什么。
+- 主体内容：每个 section 只表达一个核心信息。
+- 行动路径：主 CTA、次 CTA、联系/购买/注册/继续阅读路径。
+- 信任信息：真实案例、作品、功能说明、FAQ、数据解释。
+- 状态和边界：loading、empty、error、success、disabled、长内容、无图片。
+
+不要从背景、渐变、卡片、动效开始设计。好的页面先有结构，再有视觉。
+
+## 11. 实现策略
+
+### 新静态页面
+
+- 生成完整可运行文件。
+- CSS 组织清晰，避免大量重复 magic number。
+- 不依赖不可用的远程资源。
+- 移动端、平板、桌面都可用。
+
+### 现有项目页面
+
+- 遵循项目已有目录、组件和样式方式。
+- 优先复用已有组件和 token。
+- 不引入新依赖，除非用户要求或项目已有约定。
+- 不破坏已有路由和业务逻辑。
+
+### 组件
+
+- 支持常见变体：default、hover、active、focus-visible、disabled、loading。
+- 支持长内容和不同数量。
+- 有可访问名称和键盘路径。
+- 不依赖父容器偶然尺寸才能正常显示。
+
+## 12. 不要过度实现
+
+只实现用户请求的 UI 范围。
+
+不要默认添加：
+
+- 登录、权限、用户系统。
+- 数据库、CMS、后端 API。
+- 复杂状态管理。
+- 支付流程。
+- 多语言系统。
+- 主题切换。
+- 动画系统。
+- 大量筛选、排序、批量操作。
+- mock API 或复杂数据层。
+
+如果这些能力对页面体验是必要的，可以做轻量 UI 占位或说明，不要擅自扩展成完整产品。
+
+## 13. 必须补齐的 UI 状态
+
+根据页面功能补齐：
+
+- 按钮：primary、secondary、disabled、loading、hover、active、focus-visible。
+- 表单：label、placeholder、help、error、disabled、loading、success。
+- 列表/数据：loading、empty、error、success、分页或数量变化。
+- 弹窗/菜单：打开、关闭、遮罩、focus、移动端滚动。
+- 导航：当前状态、移动端入口、键盘可达。
+
+如果页面没有相关功能，不要硬塞状态展示；但涉及用户操作的地方必须有状态闭环。
+
+## 14. 响应式要求
+
+默认至少考虑：
+
+- 375px mobile
+- 768px tablet
+- 1280px desktop
+
+需要避免：
+
+- 横向滚动。
+- 文字贴边。
+- 按钮太小或文案溢出。
+- 图片、mockup、表格、代码块溢出。
+- sticky/fixed 元素遮挡内容。
+- 桌面正常但移动端只是缩小版。
+
+对固定格式元素使用 `max-width`、`min-width: 0`、`aspect-ratio`、合理 wrapping 和断点，而不是靠内容撑开。
+
+## 15. 内容压力测试
+
+生成时必须考虑真实内容变化：
+
+- 标题变长。
+- 按钮文案变长。
+- 中英文混排。
+- 图片比例不同。
+- 卡片内容长短不一。
+- 列表为 0、1、3、10、20 项。
+- 表单错误信息较长。
+- 用户名、项目名、邮箱、文件名很长。
+
+不要生成只适配理想短文案的布局。
+
+## 16. 自检与修复
+
+生成完成后，按顺序自检：
+
+1. 是否有 Critical 问题：不可读、不可点击、溢出、遮挡、导航/表单/弹窗不可用。
+2. 是否符合现有视觉体系或用户指定 preset。
+3. spacing、typography、颜色、圆角、边框、阴影是否统一。
+4. 组件状态是否完整。
+5. 移动端是否可用。
+6. 长内容和真实内容是否会破坏布局。
+7. 是否有 AI 模板感：过多 badge、bento grid、渐变光斑、空泛口号、虚构数据。
+
+发现明显问题时，直接修复。不要把可修的问题留给用户。
+
+## 17. 何时转入其它 workflow
+
+- 用户要求检查已有页面：转入 `review-ui` 或 `audit-ui`。
+- 生成后发现系统性质量问题：转入 `audit-ui`。
+- 生成后只需局部细节提升：转入 `polish-ui`。
+- 生成后发现具体可修缺陷：转入 `fix-ui`。
+
+Build 不应该承担所有质量工作。它负责生成可用初稿，并完成必要自检。
+
+## 18. 输出格式
+
+```markdown
+## Build Summary
+
+- 构建了什么：
+- 构建模式：
+- 采用了什么结构：
+- 是否参考了设计图：
+- 遵循了哪些现有风格或 preset：
+
+## Changed Files
+
+- `path/to/file`
+
+## States Covered
+
+- hover / active / focus-visible / disabled / loading / empty / error / success
+
+## Responsive Checks
+
+- 375px:
+- 768px:
+- 1280px:
+
+## Verification
+
+- 已运行：
+- 未验证：
+```
+
+不要只输出抽象设计建议。能实现时直接实现，并说明验证结果。
+
+## 19. 禁止事项
+
+- 不要在用户未指定 preset 时强行套用 preset。
+- 不要在现有项目中把参考图风格当成默认风格，除非用户明确要求。
+- 不要在现有项目中引入另一套视觉体系。
+- 不要编造真实客户、价格、指标、案例或团队信息。
+- 不要生成只适配理想短文案的页面。
+- 不要只做静态好看的截图，忽略状态和响应式。
+- 不要为了丰富页面增加无意义卡片、徽章、图标、渐变和动效。
+- 不要把简单页面扩展成带后端、认证、数据库和复杂状态管理的大项目。
+- 不要引入新依赖或换技术栈，除非用户要求。
+- 不要伪造 lint/build/browser 验证结果。

package/skills/webcraft-skills/references/workflows/fix-ui.md

@@ -0,0 +1,261 @@
+# UI Fix Workflow
+
+Use this workflow to implement UI fixes from review findings, audit findings, user-reported issues, screenshots, or code observation. The goal is to make confirmed issues usable, clear, and consistent without turning a fix into a redesign.
+
+By default, fix only issues with evidence, impact, and a clear repair direction. Put unsupported issues into `Open Questions`; do not pretend they are confirmed.
+
+## 1. Confirm Fix Boundary
+
+Before editing code, confirm or infer:
+
+- Source: audit, review, user-specified issue, or current observation.
+- Scope: single page, component, whole site, viewport, or state category.
+- Severity: Critical only, or Critical / Major / Minor.
+- Whether visual tokens may change: color, radius, shadow, spacing, type hierarchy.
+- Whether existing style, copy, layout structure, and tech stack must be preserved.
+- Whether the user needs a fix plan before execution.
+
+If the user says "fix it directly" or equivalent, proceed. If the scope may become broad, provide a short fix plan first.
+
+## 2. Preserve Existing Visual System
+
+Before fixing, identify and respect the current visual system:
+
+- Color: brand, background, text, state, and accent colors.
+- Typography: type scale, weight, line-height, heading/body rhythm.
+- Spacing: container width, section spacing, component padding, grid gap.
+- Radius, border, shadow: shared rules for buttons, cards, inputs, dialogs, menus.
+- Component style: buttons, forms, navigation, cards, tables, dialogs, toasts.
+- Page tone: marketing, tool, content, admin, personal brand, etc.
+
+Unless the user explicitly asks for redesign or a preset, fix within the existing visual system. Do not change the page into a different style to repair one issue.
+
+## 3. Choose Strategy By Source
+
+### From Audit
+
+- Fix in Critical / Major / Minor and Fix Order priority.
+- Every change should map to a finding.
+- Do not opportunistically fix unsupported low-value issues.
+
+### From Review
+
+- Prioritize reviewer-identified risks.
+- If review feedback is directional, convert it into executable findings before fixing.
+- Do not expand an ordinary review into a full redesign.
+
+### From User-Specified Issue
+
+- Fix only the named issue and direct dependencies.
+- Do not expand scope unless the issue cannot be fixed otherwise.
+- If you find an extra Critical issue, mention it, but do not broadly rewrite without user intent.
+
+### From Screenshot
+
+- Fix only visible layout, visual hierarchy, copy, and obvious state issues.
+- Do not assert or fix behavior that cannot be confirmed from the screenshot.
+- Hover, focus, loading, dialog close behavior, and similar interactions need runtime verification.
+
+### From Code Observation
+
+- Label code-based inferences.
+- If the page can run, verify before fixing when practical.
+- If it cannot run, keep fixes conservative and report unverified risk.
+
+## 4. Fix Plan Format
+
+For larger scopes or multiple files, provide a short plan:
+
+```markdown
+## Fix Plan
+
+1. Fix mobile hero CTA overflow.
+   Finding: Mobile hero CTA overflows.
+   Scope: `src/app/page.tsx`
+
+2. Add button focus-visible / disabled / loading states.
+   Finding: Primary actions lack complete states.
+   Scope: `src/components/Button.tsx`
+
+3. Align card/button/input radius system.
+   Finding: Radius system is inconsistent.
+   Scope: shared component styles
+```
+
+The plan must map to findings. Do not include "also improve the whole UI" as hidden scope.
+
+## 5. Fix Priority
+
+Fix in this order:
+
+1. `Critical`: unusable, unreadable, unclickable, unclosable, horizontal scrolling, broken core flow.
+2. `Major`: failed responsive degradation, unclear hierarchy, missing component states, inconsistent visual tokens.
+3. Content Stress: long copy, mixed-language content, real data counts, media ratios.
+4. AI Template Smell: remove template noise and add real information structure.
+5. `Minor`: alignment, spacing, motion, copy, and visual polish.
+
+Do not fix Minor first. If Critical issues remain, do not spend time on local refinement.
+
+## 6. Fix Strategies
+
+### Layout / Responsive
+
+- Find the root cause first: fixed width, container padding, grid/flex breakpoint, overflow, absolute/fixed positioning.
+- Prefer responsive constraints: `max-width`, `min-width: 0`, `flex-wrap`, reasonable breakpoints, single-column degradation, `aspect-ratio`.
+- Do not hide content to mask layout problems unless the content is truly secondary on mobile.
+- Recheck the affected viewports after fixing.
+
+### Typography
+
+- Fix readability first: size, line-height, paragraph width, contrast, wrapping.
+- Break Chinese headings by meaning, not by decorative block shape.
+- Long English, emails, filenames, numbers, and IDs need wrapping or truncation strategies.
+- Do not make headings huge to simulate premium quality.
+
+### Color
+
+- Ensure contrast and state recognition first.
+- Limit accent usage; avoid spreading the primary color everywhere.
+- Preserve existing brand colors unless the user asks for a new visual direction.
+- Do not repaint the whole page into a single style palette.
+
+### Border / Radius / Shadow
+
+- Prefer token convergence over per-component tweaks.
+- Extract the smallest useful scale, such as button/input, card, modal.
+- Use shadows only for real elevation such as popovers, modals, and dropdowns.
+- Avoid heavy outlines, glow effects, and excessive glassmorphism.
+
+### Components And States
+
+- Add usability states first: focus-visible, disabled, loading, error.
+- Then add experience states: hover, active, empty, success.
+- State feedback must not cause layout shift.
+- Icon buttons need visible text, tooltip, or `aria-label`.
+- When fixing inconsistent inputs, selects, dropdowns, multiselects, or menus, first check whether the project already has matching custom components. Reuse or extend them instead of continuing to hand-style native controls.
+- If the project has no matching custom control and native controls visibly break the visual system, create the smallest reusable control or shared style so core filtering, editing, and bulk actions use one interaction and visual pattern.
+
+### Accessibility
+
+- Fix keyboard path, focus-visible, accessible names, and label associations first.
+- Icon buttons, close buttons, and menu buttons need clear `aria-label` or visible text.
+- Do not rely on color as the only state indicator.
+- Form errors must be associated with their inputs.
+- Dialogs must handle focus entry, focus return, Escape, and close button paths.
+
+### Forms / Modals / Navigation
+
+- Form fixes should close the loop: label, help, error, disabled, loading, success.
+- Select-like controls should cover trigger, menu/popup, option, selected, disabled, empty, error, focus-visible, keyboard path, and long options.
+- Dialogs should first guarantee close, scroll, focus, and destructive confirmation.
+- Navigation should first guarantee usable desktop and mobile paths, then visual polish.
+
+## 7. Local Vs Systemic Fix
+
+- If a problem appears once, prefer a local fix.
+- If the same problem appears in 3+ components or pages, consider a shared component, design token, or utility.
+- If related issues have different root causes, do not force abstraction.
+- Abstraction must reduce duplication or risk; do not abstract for architecture theater.
+- Before changing shared components, check that other usage scenarios will not break.
+
+## 8. Scope Control
+
+- Follow the existing framework, components, styling system, and naming habits.
+- Prefer local components and styles; avoid unrelated architecture refactors.
+- Do not change UI library, routes, or business logic.
+- Do not remove necessary content for visual consistency.
+- If multiple pages share the same issue, prefer shared components or tokens.
+- If only one page has the issue, do not over-abstract.
+
+## 9. User Decisions
+
+Put these under `Open Questions`; do not decide silently:
+
+- Product positioning, target user, or core value is unclear.
+- Real data, cases, customers, pricing, or metrics need confirmation.
+- Brand color, typeface, or visual direction requires tradeoff.
+- Removing business content may harm information completeness.
+- The fix requires a new dependency, UI library change, or design-system refactor.
+
+## 10. Post-Fix Recheck
+
+After each fix, recheck the affected dimension:
+
+- Overflow: relevant viewports, especially 375px, 768px, 1280px.
+- Buttons/forms: hover, active, focus-visible, disabled, loading, error.
+- Select/dropdown/multiselect/menu: open, close, selected, clear, keyboard path, long options, empty state, mobile.
+- Dialogs: open, close, overlay, scroll, focus, mobile.
+- Navigation: desktop, mobile, current state, keyboard path.
+- Tokens: whether same-type components remain consistent and no new conflict appears.
+- Copy/headings: long copy and mixed Chinese/English content.
+
+If the page cannot run, state which rechecks are code-based only.
+
+## 11. Verification
+
+### Engineering Verification
+
+Prefer existing project commands:
+
+- lint
+- typecheck
+- test
+- build
+
+Do not add new tools only for validation. Report anything not verified.
+
+### Visual Verification
+
+- Recheck relevant viewports, at least the widths where issues occurred.
+- Compare the fixed area before and after, ensuring no new overlap, overflow, or layout shift.
+- When fixing visual tokens, check same-type components remain consistent.
+
+### Interaction Verification
+
+- Recheck hover, active, focus-visible, disabled, loading, error.
+- When fixing dialogs, menus, forms, or navigation, recheck open, close, keyboard path, and mobile.
+- When replacing native controls or creating custom controls, recheck same-type pages for remaining native-control mixing and verify the new control follows existing tokens.
+- Without a browser, explain unverified interaction risk based on code.
+
+## 12. Output Format
+
+```markdown
+## Fix Summary
+
+- Fixed:
+- Preserved:
+- Not handled:
+
+## Fixed Findings
+
+- Finding:
+  Change:
+  Recheck:
+
+## Changed Files
+
+- `path/to/file`
+
+## Verification
+
+- Ran:
+- Not verified:
+
+## Remaining Questions
+
+- Questions needing user confirmation.
+```
+
+Be specific. Do not say only "optimized UI". State which finding was fixed, how, and whether it was rechecked.
+
+## 13. Prohibited
+
+- Do not turn fix into redesign unless explicitly requested.
+- Do not rewrite a page because of taste.
+- Do not force a preset when the user did not choose one.
+- Do not perform unrelated refactors.
+- Do not change tech stack or introduce dependencies unless necessary and approved.
+- Do not delete user content, business logic, or real data.
+- Do not fabricate lint/build/browser verification.
+- Do not fix one issue by introducing new responsive, state, or accessibility problems.
+- Do not introduce global visual changes to repair a local issue.