webcraft-skills 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+English | [中文](./CHANGELOG_zh_CN.md)
+
+---
+
+## v0.1.1 - 2026-05-21
+
+Public release preparation for `webcraft-skills`.
+
+### Changed
+
+- Renamed the project and package from the UI-specific name to `webcraft-skills`, leaving room for a broader website skill pack.
+- Updated the public README and usage docs to present only the currently verified stable commands: `/ui-audit` and `/ui-fix`.
+- Removed maintainer-only implementation details from public-facing documentation.
+- Aligned installer help, package metadata, and skill paths with the new package name.
+
+### Audit
+
+- Tightened the audit checklist around native form controls, custom component reuse, responsive breakpoints, admin workflows, and content stress.
+- Clarified that native inputs, selects, dropdowns, multiselects, and menus should be flagged when they clash with the product style or bypass existing custom controls.
+
+### Fix
+
+- Added clearer repair guidance for replacing or wrapping mismatched native controls with project-appropriate custom components.
+- Strengthened post-fix verification for forms, dialogs, menus, navigation, responsive layouts, and interaction states.
+
+### Release
+
+- Verified the skill package with validation and npm dry-run packaging.
+
+## v0.1.0 - 2026-05-20
+
+Skill-focused foundation release.
+
+### Stable
+
+- Installs both the skill package and slash command prompts.
+- Stable commands:
+  - `/ui-audit`: run a strict UI quality audit.
+  - `/ui-fix`: fix confirmed audit findings.
+- Added bilingual runtime references for audit and fix workflows.
+- Added locale routing so Chinese users read `.zh.md` references and English users read English references.
+
+### Audit
+
+- Expanded the UI audit rubric with clearer Critical / Major / Minor severity definitions.
+- Added stronger checks for admin/dashboard workflows, responsive breakpoints, interaction states, content stress, accessibility, and visual consistency.
+- Added explicit detection for native controls that do not match the product style or fail to use existing custom controls.
+- Added audit workflow guidance for evidence, viewport coverage, code/static inspection, screenshots, and whole-site sampling.
+
+### Fix
+
+- Expanded the fix workflow with scoped repair rules, fix priority, verification steps, and output format.
+- Added repair guidance for replacing or wrapping native inputs, selects, dropdowns, multiselects, menus, and other base controls.
+- Added post-fix recheck rules for responsive behavior, component states, dialogs, menus, forms, navigation, and content stress.
+
+### Docs
+
+- Reworked README for public users.
+- Clearly marks `/ui-audit` and `/ui-fix` as stable.
+- Marks `/ui-review`, `/ui-polish`, `/ui-build`, and `/ui-preset` as experimental and not yet fully tested.
+- Removed maintainer-only sync/runtime details from public README.
+
+## v0.0.1 - 2026-05-16
+
+Initial public version of the project.

package/CHANGELOG_zh_CN.md

@@ -0,0 +1,67 @@
+# 更新日志
+
+[English](./CHANGELOG.md) | 中文
+
+---
+
+## v0.1.1 - 2026-05-21
+
+`webcraft-skills` 的公开发布准备版本。
+
+### 变更
+
+- 项目名和包名从偏 UI 的旧名称调整为 `webcraft-skills`，为后续扩展成更完整的网站 skill pack 预留空间。
+- 更新公开 README 和 usage 文档，只承诺当前已验证的稳定命令：`/ui-audit` 和 `/ui-fix`。
+- 从面向用户的文档中移除维护者内部实现和同步运行层说明。
+- 统一安装器帮助、package metadata 和 skill 路径，使其全部指向新的包名。
+
+### Audit
+
+- 继续打磨 audit checklist，强化原生表单控件、自定义组件复用、响应式断点、后台工作流和真实内容压力检查。
+- 明确输入框、选择框、下拉框、多选框、菜单等原生控件在不符合网站风格，或绕过项目已有自定义组件时，应被识别为问题。
+
+### Fix
+
+- 补充控件修复策略：将不协调的原生控件替换或封装为符合项目风格的自定义组件。
+- 强化修复后的复检范围：表单、弹窗、菜单、导航、响应式布局和交互状态。
+
+### 发布
+
+- 已通过项目校验和 npm dry-run 打包预检。
+
+## v0.1.0 - 2026-05-20
+
+Skill 化基础版本。
+
+### 稳定能力
+
+- 安装时会同时安装 skill package 和 slash command prompts。
+- 当前稳定命令：
+  - `/ui-audit`：严格排查 UI 质量问题。
+  - `/ui-fix`：根据明确的 audit findings 修复问题。
+- 补齐 audit / fix 的中英文运行时 reference。
+- 增加语言路由：中文用户读取 `.zh.md` reference，英文用户读取英文 reference。
+
+### Audit
+
+- 扩展 UI audit rubric，明确 Critical / Major / Minor 的分级标准。
+- 加强后台 / dashboard、响应式断点、交互状态、真实内容压力、可访问性和视觉一致性检查。
+- 增加原生控件检查：发现不符合网站风格的原生控件，或已有自定义控件却没有使用的情况。
+- 完善 audit workflow：覆盖证据采集、视口检查、代码静态审查、截图审查和整站抽样。
+
+### Fix
+
+- 扩展 fix workflow：增加修复边界、修复优先级、验证步骤和输出格式。
+- 增加输入框、选择框、下拉框、多选框、菜单等基础控件的修复策略。
+- 增加修复后的复检规则：响应式、组件状态、弹窗、菜单、表单、导航和真实内容压力。
+
+### 文档
+
+- 重写 README，使其更适合外部用户阅读。
+- 明确 `/ui-audit` 和 `/ui-fix` 是当前稳定能力。
+- 标注 `/ui-review`、`/ui-polish`、`/ui-build`、`/ui-preset` 为实验性能力，尚未完整测试。
+- 从公开 README 中移除维护者使用的同步运行层说明。
+
+## v0.0.1 - 2026-05-16
+
+项目的第一个公开版本。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Guo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# Webcraft Skills
+
+English | [中文](./README_zh_CN.md)
+
+UI audit and fix skill for Codex and Claude Code, with slash commands for inspecting and repairing rough AI-generated web UI.
+
+AI coding tools can generate code quickly, but their UI often feels too crowded, flashy, inconsistent, or obviously AI-generated.
+
+---
+
+# What Is This?
+
+Webcraft Skills is a UI quality system for AI agents.
+
+It is not a UI framework, design system, component library, or product builder.
+
+The current verified scope is focused: **audit existing UI and fix confirmed audit findings**.
+
+The broader goal is:
+
+- audit layout, typography, color, borders, radius, modals, responsive behavior, and interaction states
+- fix rough AI-generated UI based on concrete findings
+- eventually build and polish more realistic, restrained web UI
+- refine the core reusable skill first, then gradually expand Codex, Claude, Cursor, and plain prompt adapters
+- help AI act more like a senior UI/UX and frontend reviewer
+
+The currently tested commands are `/ui-audit` and `/ui-fix`. Other command prompts are present for iteration, but are not yet part of the stable public surface.
+
+---
+
+# Quick Start
+
+## Current Recommended Install
+
+Install the skill and slash commands with npx:
+
+```bash
+npx webcraft-skills install --agent codex
+```
+
+For Claude Code:
+
+```bash
+npx webcraft-skills install --agent claude
+```
+
+To install for both:
+
+```bash
+npx webcraft-skills install --agent all
+```
+
+This installs:
+
+```text
+~/.codex/skills/webcraft-skills
+~/.codex/commands/*.md
+```
+
+or:
+
+```text
+~/.claude/skills/webcraft-skills
+~/.claude/commands/*.md
+```
+
+Then use it in a project:
+
+```text
+/ui-audit current website
+/ui-fix Critical and Major issues from the last audit
+```
+
+Full parameter-style usage:
+
+```text
+/ui-audit --scope whole-site --strict --viewports 375,768,1280
+/ui-fix --severity critical,major --yes
+```
+
+If a client does not load commands from `~/.codex/commands`, use explicit natural invocation:
+
+```text
+Use webcraft-skills to audit the current website.
+```
+
+## Cursor
+
+Cursor support is not part of the stable install path yet. For now, use the audit and fix guidance manually if you know how to configure Cursor Project Rules.
+
+## Plain Prompt
+
+Plain prompt usage is not part of the stable release yet.
+
+## Project Extensions
+
+Create `.webcraft-skills/EXTEND.md` and `.webcraft-skills/config.json` in the target project to override default audit standards, brand constraints, radius scale, viewports, and visual rules.
+
+---
+
+# Capabilities
+
+Stable:
+
+- `/ui-audit`: run a strict UI quality audit
+- `/ui-fix`: implement fixes from audit results
+
+Experimental / not yet fully tested:
+
+- `/ui-review`: review a page, component, or screenshot
+- `/ui-polish`: refine existing UI without changing product meaning
+- `/ui-build`: build a page or site
+- `/ui-preset`: list and apply visual presets
+
+---
+
+# Presets
+
+The package currently includes one bundled preset: `cinematic-minimal`.
+
+Calm cinematic interfaces with:
+
+- restrained motion
+- warm dark tones
+- spacious layouts
+- quiet product feeling
+
+More presets will be added when they are ready.
+
+---
+
+# Philosophy
+
+Good UI is usually restrained.
+
+This project focuses on helping AI generate interfaces that feel:
+
+- cleaner
+- calmer
+- more intentional
+- more realistic
+- less artificial
+
+---
+
+# License
+
+MIT

package/README_zh_CN.md

@@ -0,0 +1,148 @@
+# Webcraft Skills
+
+[English](./README.md) | 中文
+
+适合 Codex 和 Claude Code 的 UI audit / fix skill，提供 slash commands，用于排查和修复粗糙的 AI 生成网页 UI。
+
+AI Coding 工具已经很会写代码，但生成的 UI 经常会显得太拥挤、太花哨、层级混乱，或者有很强的“AI 模板感”。
+
+---
+
+# 这是什么？
+
+Webcraft Skills 是一个面向 AI Agent 的网页 UI 质量系统。
+
+它不是 UI 框架、设计系统、组件库，也不是可视化建站工具。
+
+当前已验证范围很明确：**审查现有 UI，并根据明确的 audit findings 修复问题**。
+
+更完整的长期目标是：
+
+- 排查布局、字体、颜色、边框、圆角、弹窗、响应式和交互状态
+- 根据具体 findings 修复粗糙的 AI 生成 UI
+- 逐步支持生成更真实、更克制的网页
+- 先打磨可复用的核心 Skill，再逐步扩展 Codex / Claude / Cursor 等平台适配
+- 让 AI 不只会生成 UI，也会像资深 UI/UX + 前端 reviewer 一样修 UI
+
+当前已测试命令是 `/ui-audit` 和 `/ui-fix`。其它 command prompt 会保留用于迭代，但暂时不作为稳定公开能力承诺。
+
+---
+
+# Quick Start
+
+## 当前推荐安装
+
+使用 npx 安装 skill 和 slash commands：
+
+```bash
+npx webcraft-skills install --agent codex
+```
+
+Claude Code 使用：
+
+```bash
+npx webcraft-skills install --agent claude
+```
+
+同时安装 Codex 和 Claude Code：
+
+```bash
+npx webcraft-skills install --agent all
+```
+
+这会安装到：
+
+```text
+~/.codex/skills/webcraft-skills
+~/.codex/commands/*.md
+```
+
+或：
+
+```text
+~/.claude/skills/webcraft-skills
+~/.claude/commands/*.md
+```
+
+然后在项目中使用：
+
+```text
+/ui-audit current website
+/ui-fix Critical and Major issues from the last audit
+```
+
+更完整的参数式调用：
+
+```text
+/ui-audit --scope whole-site --strict --viewports 375,768,1280
+/ui-fix --severity critical,major --yes
+```
+
+如果当前客户端没有从 `~/.codex/commands` 加载命令，可以直接显式调用：
+
+```text
+Use webcraft-skills to audit the current website.
+```
+
+## Cursor
+
+Cursor 暂时不属于稳定安装路径。如果你熟悉 Cursor Project Rules，可以先手动参考 audit / fix 规则。
+
+## Plain Prompt
+
+Plain Prompt 暂时不属于稳定发布能力。
+
+## 项目扩展
+
+在目标项目中创建 `.webcraft-skills/EXTEND.md` 和 `.webcraft-skills/config.json`，可覆盖默认 UI 审查标准、品牌约束、圆角体系、默认视口等。
+
+---
+
+# 能力
+
+稳定能力：
+
+- `/ui-audit`：严格排查整页或整站 UI 质量
+- `/ui-fix`：根据 audit 结果直接修复代码
+
+实验性能力，尚未完整测试：
+
+- `/ui-review`：审查页面、组件或截图
+- `/ui-polish`：保留业务含义的前提下润色页面
+- `/ui-build`：生成网页或站点
+- `/ui-preset`：查看和应用视觉 preset
+
+---
+
+# Presets
+
+当前包内置一个 preset：`cinematic-minimal`。
+
+电影感极简风格：
+
+- 克制动效
+- 暖黑色调
+- 大留白
+- 安静的产品感
+
+更多 preset 会在准备好后继续补充。
+
+---
+
+# Philosophy
+
+真正高级的 UI，很多时候都是克制的。
+
+这个项目能让 AI 生成的界面：
+
+- 更干净
+- 更平静
+- 更有节奏
+- 更真实
+- 更少 AI 味
+
+---
+
+# License
+
+MIT

package/commands/ui-audit.md

@@ -0,0 +1,21 @@
+# /ui-audit
+
+Run a strict visual, responsive, interaction, and AI-template-smell audit.
+
+## Usage
+
+```text
+/ui-audit [scope]
+```
+
+Examples:
+
+```text
+/ui-audit whole site
+/ui-audit current localhost app
+```
+
+## Agent Instructions
+
+Use the `webcraft-skills` skill in Audit mode. Read the selected-locale audit workflow and UI audit checklist before reporting findings. Inspect layout, typography, color, borders, radius, shadow, components, forms, modals, responsive behavior, motion, accessibility, content stress, and AI template smell. Prefer browser verification when available.
+

package/commands/ui-build.md

@@ -0,0 +1,21 @@
+# /ui-build
+
+Build a production-quality web page or site with Webcraft Skills.
+
+## Usage
+
+```text
+/ui-build [preset] [target]
+```
+
+Examples:
+
+```text
+/ui-build cinematic-minimal personal homepage
+/ui-build saas-clean product landing page
+```
+
+## Agent Instructions
+
+Use the `webcraft-skills` skill in Build mode. Read the selected preset when provided. If no preset is provided, choose based on product context. Generate or modify real project files when possible, then check responsive behavior and interactive states.
+

package/commands/ui-fix.md

@@ -0,0 +1,21 @@
+# /ui-fix
+
+Fix UI issues found by review or audit.
+
+## Usage
+
+```text
+/ui-fix [issue or scope]
+```
+
+Examples:
+
+```text
+/ui-fix Critical and Major issues from the last audit
+/ui-fix mobile overflow and modal states
+```
+
+## Agent Instructions
+
+Use the `webcraft-skills` skill in Fix mode. Read the selected-locale fix workflow before editing. Keep edits scoped to confirmed findings. Fix Critical issues first, then Major, then Minor. Verify with the project's existing checks.
+

package/commands/ui-polish.md

@@ -0,0 +1,21 @@
+# /ui-polish
+
+Polish existing UI while preserving product meaning and codebase style.
+
+## Usage
+
+```text
+/ui-polish [scope]
+```
+
+Examples:
+
+```text
+/ui-polish homepage
+/ui-polish reduce AI template feel
+```
+
+## Agent Instructions
+
+Use the `webcraft-skills` skill in Polish mode. Improve spacing, typography, color hierarchy, radius, border, component states, responsive behavior, and copy restraint. Avoid unrelated redesign.
+

package/commands/ui-preset.md

@@ -0,0 +1,15 @@
+# /ui-preset
+
+List, select, or apply Webcraft Skills presets.
+
+## Usage
+
+```text
+/ui-preset list
+/ui-preset cinematic-minimal
+```
+
+## Agent Instructions
+
+Use the `webcraft-skills` skill. Explain when the preset fits, when it does not, and what constraints it applies.
+

package/commands/ui-review.md

@@ -0,0 +1,21 @@
+# /ui-review
+
+Review a page, component, screenshot, or site with Webcraft Skills.
+
+## Usage
+
+```text
+/ui-review [scope]
+```
+
+Examples:
+
+```text
+/ui-review current page
+/ui-review homepage and pricing page
+```
+
+## Agent Instructions
+
+Use the `webcraft-skills` skill in Review mode. Read `ui-audit.zh.md`. Lead with Critical, Major, Minor findings. Each finding must include location, problem, impact, and fix.
+

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "webcraft-skills",
+  "version": "0.1.1",
+  "description": "Webcraft skill pack for auditing and fixing rough AI-generated websites.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "webcraft-skills": "scripts/install.mjs"
+  },
+  "files": [
+    "skills/",
+    "commands/",
+    "scripts/install.mjs",
+    "README.md",
+    "README_zh_CN.md",
+    "CHANGELOG.md",
+    "CHANGELOG_zh_CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "validate": "node scripts/validate.mjs",
+    "sync:runtime": "node scripts/sync-runtime.mjs"
+  },
+  "keywords": [
+    "ai",
+    "webcraft",
+    "website",
+    "ui",
+    "frontend",
+    "codex",
+    "claude",
+    "cursor",
+    "skills",
+    "design-review"
+  ]
+}