@chinhae/atw-cli 0.2.8 → 0.2.9

package/dist/templates/common/bundled-skills/atw-prototype/scripts/build_explorer.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Build a portable, offline design comparison from a local manifest."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+from html.parser import HTMLParser
+import json
+from pathlib import Path
+import re
+import sys
+import tempfile
+from urllib.parse import urlsplit
+
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+TEMPLATE = SKILL_ROOT / "assets" / "style-explorer.html"
+MARKER = "/*__ATW_EXPLORER_DATA__*/ null"
+PREVIEW_CSP = (
+    "default-src 'none'; style-src 'unsafe-inline'; img-src data:; "
+    "font-src data:; media-src data:; script-src 'none'; "
+    "form-action 'none'; base-uri 'none'; object-src 'none'"
+)
+
+
+def text_field(obj: dict, name: str, *, default: str | None = None) -> str:
+    value = obj.get(name, default)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} 必须是非空字符串")
+    return value.strip()
+
+
+def text_list(obj: dict, name: str) -> list[str]:
+    values = obj.get(name)
+    if not isinstance(values, list) or not values:
+        raise ValueError(f"{name} 必须是非空字符串数组")
+    if any(not isinstance(v, str) or not v.strip() for v in values):
+        raise ValueError(f"{name} 的每项必须是非空字符串")
+    return [v.strip() for v in values]
+
+
+class AssetCheck(HTMLParser):
+    """Reject resource dependencies; the browser sandbox disables behavior."""
+
+    def __init__(self):
+        super().__init__()
+        self.styles = []
+        self.in_style = False
+        self.head_position = None
+
+    def handle_starttag(self, tag: str, attrs: list) -> None:
+        attrs = dict(attrs)
+        if tag == "head" and self.head_position is None:
+            self.head_position = (self.getpos(), self.get_starttag_text())
+        if tag in ("iframe", "frame", "object", "embed"):
+            raise ValueError("候选 HTML 不支持嵌套文档；请提供静态内容或截图")
+        if tag == "style":
+            self.in_style = True
+        if attrs.get("style"):
+            self.styles.append(attrs["style"])
+        if tag == "base":
+            raise ValueError("候选 HTML 不应包含 base；资源需要内嵌")
+        if tag == "meta" and attrs.get("http-equiv", "").lower() == "refresh":
+            raise ValueError("候选 HTML 不应自动跳转")
+        for key in ("src", "poster", "data", "href", "xlink:href"):
+            value = attrs.get(key, "") or ""
+            if not value or value.startswith(("#", "data:")):
+                continue
+            raise ValueError(f"候选 HTML 含未内嵌资源 {tag}.{key}: {value}")
+        if attrs.get("srcset"):
+            raise ValueError("候选 HTML 请用内嵌 src 代替 srcset")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "style":
+            self.in_style = False
+
+    def handle_data(self, data: str) -> None:
+        if self.in_style:
+            self.styles.append(data)
+
+
+CSS_TOKEN = re.compile(
+    r"(?P<comment>/\*.*?\*/)|(?P<string>\"(?:\\.|[^\"\\])*\"|'(?:\\.|[^'\\])*')"
+    r"|(?P<ident>(?:[-_a-zA-Z]|\\(?:[0-9a-fA-F]{1,6}\s?|[^\r\n]))"
+    r"(?:[-_a-zA-Z0-9]|\\(?:[0-9a-fA-F]{1,6}\s?|[^\r\n]))*)"
+    r"|(?P<space>\s+)|(?P<symbol>.)", re.S,
+)
+
+
+def css_unescape(value: str) -> str:
+    def replacement(match):
+        if match.group(1):
+            codepoint = int(match.group(1), 16)
+            return chr(codepoint) if 0 < codepoint <= 0x10FFFF else "\ufffd"
+        return match.group(2)
+    return re.sub(r"\\([0-9a-fA-F]{1,6})(?:\s)?|\\([^\r\n])", replacement, value)
+
+
+def check_css(css: str, label: str) -> None:
+    tokens = [(m.lastgroup, m.group()) for m in CSS_TOKEN.finditer(css)
+              if m.lastgroup not in ("comment", "space")]
+
+    def check_resource(value: str):
+        if not css_unescape(value).strip().lower().startswith(("data:", "#")):
+            raise ValueError(f"{label}: CSS 含未内嵌资源")
+
+    for index, (kind, value) in enumerate(tokens):
+        if value == "@" and index + 1 < len(tokens) and tokens[index + 1][0] == "ident" and css_unescape(tokens[index + 1][1]).lower() == "import":
+            raise ValueError(f"{label}: 请内嵌 CSS，不使用 @import")
+        name = css_unescape(value).lower() if kind == "ident" else ""
+        if name not in ("url", "image-set", "-webkit-image-set", "image", "src"):
+            continue
+        if index + 1 >= len(tokens) or tokens[index + 1][1] != "(":
+            continue
+        depth, body = 1, []
+        for inner_kind, inner_value in tokens[index + 2:]:
+            if inner_kind == "symbol" and inner_value == "(":
+                depth += 1
+            elif inner_kind == "symbol" and inner_value == ")":
+                depth -= 1
+                if depth == 0:
+                    break
+            if name == "url":
+                body.append(inner_value[1:-1] if inner_kind == "string" else inner_value)
+            elif depth == 1 and inner_kind == "string":
+                check_resource(inner_value[1:-1])
+        if name == "url":
+            check_resource("".join(body))
+
+
+# Sandboxed previews have no storage; give prototypes an in-memory stand-in so their scripts keep running.
+STORAGE_SHIM = (
+    "<script>(()=>{const mem=()=>{const m=new Map();return{get length(){return m.size},"
+    "key:i=>[...m.keys()][i]??null,getItem:k=>m.has(String(k))?m.get(String(k)):null,"
+    "setItem:(k,v)=>{m.set(String(k),String(v))},removeItem:k=>{m.delete(String(k))},clear:()=>m.clear()}};"
+    "for(const n of['localStorage','sessionStorage']){try{window[n].length}catch{"
+    "Object.defineProperty(window,n,{value:mem(),configurable:true})}}})();</script>"
+)
+
+
+def preview_csp(interactive: bool) -> str:
+    # Interactive prototypes may run their own inline scripts, still with no network or external files.
+    return PREVIEW_CSP.replace("script-src 'none'", "script-src 'unsafe-inline'") if interactive else PREVIEW_CSP
+
+
+EMBEDDABLE = {
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+    ".gif": "image/gif", ".avif": "image/avif", ".svg": "image/svg+xml",
+    ".woff2": "font/woff2", ".woff": "font/woff", ".ttf": "font/ttf", ".otf": "font/otf",
+    ".mp4": "video/mp4", ".webm": "video/webm",
+}
+ATTR_REF = re.compile(r"""(?P<lead>\b(?:src|poster|href|xlink:href)\s*=\s*)(?P<q>["'])(?P<ref>[^"'#][^"']*)(?P=q)""")
+CSS_REF = re.compile(r"""url\(\s*(?P<q>["']?)(?P<ref>[^"')\s][^"')]*)(?P=q)\s*\)""")
+
+
+def embed_local_files(content: str, base: Path, root: Path, used: set[Path]) -> str:
+    """Inline images, fonts and videos referenced relative to the candidate, as long as they stay inside the manifest folder."""
+
+    def data_url(ref: str) -> str | None:
+        if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*:|^//", ref):
+            return None
+        target = (base / ref.split("?")[0].split("#")[0]).resolve()
+        mime = EMBEDDABLE.get(target.suffix.lower())
+        if not mime or not target.is_file() or not target.is_relative_to(root):
+            return None
+        used.add(target)
+        return f"data:{mime};base64," + base64.b64encode(target.read_bytes()).decode("ascii")
+
+    def attr(match):
+        url = data_url(match["ref"])
+        return match.group(0) if url is None else f'{match["lead"]}{match["q"]}{url}{match["q"]}'
+
+    def css(match):
+        url = data_url(match["ref"])
+        return match.group(0) if url is None else f'url("{url}")'
+
+    return CSS_REF.sub(css, ATTR_REF.sub(attr, content))
+
+
+def prepare_html(path: Path, interactive: bool = False, root: Path | None = None, used: set[Path] | None = None) -> str:
+    content = path.read_text(encoding="utf-8")
+    if root is not None:
+        content = embed_local_files(content, path.parent, root, used if used is not None else set())
+    parser = AssetCheck()
+    parser.feed(content)
+    for style in parser.styles:
+        check_css(style, path.name)
+    if parser.head_position is None:
+        raise ValueError(f"{path.name}: 候选 HTML 需要完整的 head 元素")
+    (line, column), start_tag = parser.head_position
+    head_end = sum(len(part) + 1 for part in content.split('\n')[:line - 1]) + column + len(start_tag)
+    meta = f'<meta http-equiv="Content-Security-Policy" content="{preview_csp(interactive)}">'
+    return content[:head_end] + meta + (STORAGE_SHIM if interactive else "") + content[head_end:]
+
+
+def prepare_image(path: Path) -> str:
+    data = path.read_bytes()
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        mime = "image/png"
+    elif data.startswith(b"\xff\xd8\xff"):
+        mime = "image/jpeg"
+    elif data.startswith(b"RIFF") and data[8:12] == b"WEBP":
+        mime = "image/webp"
+    else:
+        raise ValueError(f"{path.name}: 静态预览支持 PNG、JPEG 和 WebP")
+    return f"data:{mime};base64," + base64.b64encode(data).decode("ascii")
+
+
+LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+
+
+def local_url(value: str, identifier: str) -> str:
+    """Live candidates only point at a dev server on this machine."""
+    parts = urlsplit(value)
+    if parts.scheme not in ("http", "https") or (parts.hostname or "").lower() not in LOOPBACK or parts.username or parts.password:
+        raise ValueError(f"{identifier}: url 只能是本机开发服务器地址，例如 http://localhost:5173/orders")
+    return value
+
+
+def load_manifest(path: Path) -> tuple[dict, set[Path]]:
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict) or raw.get("schemaVersion") != 1:
+        raise ValueError("manifest.schemaVersion 必须为 1")
+    data = {"schemaVersion": 1, "project": text_field(raw, "project"),
+            "brief": text_field(raw, "brief"), "round": text_field(raw, "round", default="01")}
+    candidates = raw.get("candidates")
+    if not isinstance(candidates, list) or not candidates:
+        raise ValueError("candidates 至少需要一个候选")
+    seen = set()
+    inputs = {path, TEMPLATE.resolve()}
+    output = []
+    for candidate in candidates:
+        if not isinstance(candidate, dict):
+            raise ValueError("每个候选必须是对象")
+        identifier = text_field(candidate, "id")
+        if not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", identifier) or identifier in seen:
+            raise ValueError(f"候选 id 无效或重复: {identifier}")
+        seen.add(identifier)
+        kind = candidate.get("kind", "html")
+        if kind not in ("html", "image", "url"):
+            raise ValueError(f"未知候选 kind: {kind}")
+        baseline = candidate.get("baseline", False)
+        interactive = candidate.get("interactive", False)
+        if not isinstance(baseline, bool) or not isinstance(interactive, bool):
+            raise ValueError(f"{identifier}: baseline 和 interactive 必须是 true 或 false")
+        if interactive and kind != "html":
+            raise ValueError(f"{identifier}: interactive 只用于 html 候选")
+        if kind == "url":
+            source = None
+            url = local_url(text_field(candidate, "url"), identifier)
+        else:
+            source = (path.parent / text_field(candidate, "source")).resolve()
+            if not source.is_relative_to(path.parent) or not source.is_file():
+                raise ValueError(f"候选 source 必须是 manifest 目录内可读文件: {identifier}")
+            inputs.add(source)
+        colors = text_list(candidate, "palette")
+        if any(not re.fullmatch(r"#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})", c) for c in colors):
+            raise ValueError(f"{identifier}: palette 需要十六进制颜色")
+        output.append({
+            "id": identifier,
+            **{name: text_field(candidate, name) for name in ("name", "concept", "typography")},
+            "palette": colors, "traits": text_list(candidate, "traits"), "kind": kind,
+            "content": url if kind == "url" else prepare_html(source, interactive, path.parent, inputs) if kind == "html" else prepare_image(source),
+            "sourceLabel": url if kind == "url" else source.name,
+            "baseline": baseline,
+            "interactive": interactive,
+        })
+    if sum(c["baseline"] for c in output) > 1:
+        raise ValueError("最多只能有一个基线候选")
+    # The current version always sits first so every direction is read against it.
+    output.sort(key=lambda c: not c["baseline"])
+    data["candidates"] = output
+    canonical = json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    data["fingerprint"] = hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:24]
+    return data, inputs
+
+
+def build(manifest: Path, output: Path, *, force: bool = False) -> dict:
+    manifest, output = manifest.resolve(), output.resolve()
+    data, inputs = load_manifest(manifest)
+    if output in inputs or output.is_relative_to(SKILL_ROOT):
+        raise ValueError("输出不能覆盖输入或写进 Skill 安装目录")
+    if output.exists() and not force:
+        raise FileExistsError("输出已存在；使用新路径，或明确加 --force 更新")
+    template = TEMPLATE.read_text(encoding="utf-8")
+    if template.count(MARKER) != 1:
+        raise ValueError("模板数据入口缺失或重复")
+    # A closing script tag in metadata or a nested candidate cannot escape the container.
+    payload = json.dumps(data, ensure_ascii=False).replace("<", "\\u003c").replace("\u2028", "\\u2028").replace("\u2029", "\\u2029")
+    page = template.replace(MARKER, payload)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if force:
+        temp = None
+        try:
+            with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=output.parent, delete=False) as handle:
+                temp = Path(handle.name)
+                handle.write(page)
+            temp.replace(output)
+        finally:
+            if temp and temp.exists():
+                temp.unlink()
+    else:
+        with output.open("x", encoding="utf-8") as handle:
+            handle.write(page)
+    return {"output": str(output), "candidates": len(data["candidates"]), "fingerprint": data["fingerprint"], "bytes": output.stat().st_size}
+
+
+def main() -> int:
+    if sys.version_info < (3, 10):
+        print("需要 Python 3.10 或更新版本", file=sys.stderr)
+        return 2
+    parser = argparse.ArgumentParser(description="把本地候选与 manifest 组装成独立风格对比 HTML")
+    parser.add_argument("manifest", type=Path)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--force", action="store_true", help="明确允许原子更新已有输出")
+    args = parser.parse_args()
+    try:
+        print(json.dumps(build(args.manifest, args.output, force=args.force), ensure_ascii=False))
+        return 0
+    except (OSError, ValueError, TypeError) as exc:
+        print(f"未生成对比页：{exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/templates/common/bundled-skills/atw-spec/SKILL.md

@@ -56,6 +56,16 @@ Do NOT include specific file paths or code snippets. They may end up being outda
 
 Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
 
+## UI and Design
+
+Include this section only when the work changes what a user sees; omit it otherwise.
+
+- The chosen visual direction and the user's stated likes and dislikes. If `atw-prototype` left `ui-direction.md` in the task directory, summarise it here and point to it — do not restate the whole direction card.
+- The screens and states that must exist: empty, loading, success, failure, rejected actions.
+- The target viewports (e.g. desktop 1280, mobile 390).
+- Which project design rules apply: the `design-system.md` in the UI layer of `.atw/spec/`, if the project has one.
+- UI acceptance criteria phrased as things you can check on a screenshot: "on mobile 390 the primary action stays visible above the keyboard", not "looks clean".
+
 ## Testing Decisions
 
 A list of testing decisions that were made. Include:

package/dist/templates/common/bundled-skills/atw-spec-bootstrap/references/spec-writing.md

@@ -23,6 +23,10 @@ Keep the spec tree aligned with the project:
 - Delete template files that do not apply.
 - Add new files for important local patterns the template missed.
 
+## UI Layers
+
+When a package renders UI, fill `design-system.md` in its UI layer from the real theme: the token or theme file, CSS variables, Tailwind config, and the shared components screens actually use. Record color roles, the type scale, spacing and radius steps, and how key components look. Where the code is inconsistent — three button styles — record the majority usage and list the rest as to-unify, rather than inventing a cleaner system.
+
 ## Content Standards
 
 Good spec sections include:

package/dist/templates/common/bundled-skills/atw-tickets/SKILL.md

@@ -39,6 +39,11 @@ Give each ticket its **blocking edges** — the other tickets that must complete
 
 **Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
 
+**UI work stays inside the vertical slices.** Don't split "build the UI" into its own ticket — that is a horizontal slice. Instead, every ticket that changes what a user sees carries UI acceptance criteria next to its behavioural ones: which screen, which state, which viewport, checked against the spec's UI and Design section. Two optional exceptions, both sequenced like prefactoring and integration:
+
+- A **design-foundation** ticket first, when several slices need the same new design tokens or shared components. Every UI ticket that uses them is blocked by it.
+- A **visual pass** ticket last, only for multi-screen work: one consistency review across all the screens the slices produced, blocked by every UI ticket. It fixes drift between screens; it does not redesign them.
+
 ### 4. Quiz the user
 
 Present the proposed breakdown as a numbered list. For each ticket, show:
@@ -78,6 +83,7 @@ Do NOT close or modify any parent issue.
 
 - [ ] Acceptance criterion 1
 - [ ] Acceptance criterion 2
+- [ ] UI: <screen> / <state> / <viewport> — <what a screenshot must show> (only for tickets that change what a user sees)
 
 </local-ticket-template>
 

package/dist/templates/common/bundled-skills/atw-ui/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: atw-ui
+description: "按已选定的设计方向实现、精修和评审网站、App、后台与组件的界面：建立视觉层级与交互结构、制作素材、在目标视口取得实际画面证据、独立评审与修正、做减法后交付。用于实现阶段的正式界面、存量页面精修或改版、截图还原和界面评审。方向还没定、需要比较多个风格方向或验证业务逻辑时，先用 atw-prototype。只负责设计判断，组件归属、数据流、状态正确性和测试等代码实现质量不在范围内。"
+---
+
+# atw-ui
+
+以明确的设计北极星组织界面，让构图、字体、色彩、素材和交互相互呼应，形成有辨识度的表达。克制是保留最有力量的选择、删除无贡献的元素，不是把所有风格磨成中庸。视觉表现与任务完成分别验收。
+
+方法和评审协议均在本目录内，直接使用宿主提供的文件、浏览、看图、生成与隔离执行能力。相对链接以本文件所在目录解析。
+
+## 在 ATW 里使用
+
+### 各阶段的用法
+
+| 阶段 | 用法 |
+| --- | --- |
+| discover | 不用本技能。选方向用 atw-prototype，结论写进任务目录的 `ui-direction.md` |
+| implement | 只在 `/atw-implement` 的流水线里使用：工单涉及界面时，界面部分按本技能步骤 1–3 和 5 完成，业务逻辑仍按流水线测试先行。不在流水线之外单独用本技能写实现代码 |
+| accept | 只读。按步骤 4 的“给已有界面评审”，对照需求文档里的界面验收标准和设计规范取证；发现的问题记成新工单或后续任务，不当场修改 |
+| 没有 ATW 任务的小改动 | 直接使用本技能 |
+
+实现阶段发现方向缺失或与需求文档矛盾时，停下来告诉用户，按 ATW 的回退规则处理（回到 specify 或重新探索），不在工单里临时发散新方向。
+
+### 三类设计信息
+
+| 信息 | 位置 | 用法 |
+| --- | --- | --- |
+| 通用设计方法 | 本技能的参考资料 | 判断怎样做得好 |
+| 本项目的设计规范：颜色用途、字号层级、间距与圆角、关键组件样式、图标库 | `.atw/spec/` 里界面所在层的 `design-system.md` | 判断用什么；是长期规定 |
+| 本任务的设计决定：选定方向、方向卡、用户的喜欢与不喜欢、界面验收重点 | 任务目录的 `ui-direction.md` 和需求文档 | 判断这次要做成什么样 |
+
+读取顺序：
+
+1. 运行 `python3 ./.atw/scripts/get_context.py --mode packages`，找到工单所在的包和它的界面层。层名不一定是 `frontend`，可能是 `web`、`ui` 等；多包项目每个包可以有各自的设计规范，只读当前包的。
+2. 读该层的 `index.md`、`design-system.md`，以及组件和代码质量相关的规范。
+3. 读 `ui-direction.md` 和需求文档里的界面部分。
+4. 没有 `design-system.md` 时，从现有设计变量、主题配置和共享组件里读出现状，按多数用法整理。
+
+代码层面的事——用哪种样式方案、组件放哪、状态怎么管——以 ATW spec 为准；本技能只在这些约束内做设计判断。设计规范本身妨碍任务时说出来，交给用户决定，不悄悄绕开。
+
+做完后，本次确立的可复用视觉约定（新增的设计变量、组件变体、统一的密度或间距规则）通过流水线里的 spec 更新步骤写回 `design-system.md`；只属于这一页的决定留在 `ui-direction.md`。
+
+## 选择范围
+
+- 从请求、ATW spec 的设计规范、任务目录的 `ui-direction.md`（通常由 atw-prototype 留下）、需求文档、现有页面和参考资料明确用户、主要任务、真实内容、目标设备与交付形式。检查相关位置即可，不先通读整个项目。
+- 用户已确定的品牌、参考、页面结构、交互约束，以及 `ui-direction.md` 里选定的方向和品味优先。分清借鉴风格、重新设计与精准还原，不能自行切换目标。
+- 仅在缺失信息会改变核心方向且无法合理推断时集中提问；可逆的细节自行决定并简述假设。不把设计工作变成强制问卷或逐步审批。
+- 设计说明、设计稿和可运行产品是不同交付物。只要求评审时保持只读；只要求设计时不默认改业务代码。
+
+| 当前范围 | 路径 |
+| --- | --- |
+| 单个元素、一处间距、文案或颜色这类小改动 | 直接改，在目标视口看改动处和相邻元素，交付时一两句话说明；不盘点现状、不启动评审 |
+| 方向还没定，或明确要求重新探索、比较多个风格 | 交给 atw-prototype 的界面原型，选定方向后再回到这里 |
+| 已有选定方向（`ui-direction.md` 或用户给定）的新界面 | 按步骤 1–5 执行 |
+| 已有方向的深化或局部优化 | 保留方向，从步骤 2 进入，只检查受影响的区域与状态 |
+| 存量项目里的精修、局部重构或改版 | 先盘点现有页面、设计变量和共享组件，留基线截图，从源头修改 |
+| 截图还原 | 按 [布局与视口](references/layout-and-viewport.md) 的“精准还原”，以参考图为视觉基线，确定参考视口与布局约束后进入步骤 2，不发散新风格 |
+| UI/UX 评审 | 按问题读取对应参考，只执行步骤 4 的诊断并交付证据与建议；评审现有界面、不要求重新设计时，用步骤 4 的“给已有界面评审” |
+
+## 1. 确认方向
+
+读 `ui-direction.md` 或用户给定的方向，确认北极星、方向卡、记忆点、用户的喜欢与不喜欢都还适用。方向缺失、彼此矛盾，或用户改变了目标时，回到 atw-prototype 选方向，不在实现中途悄悄换风格。
+
+atw-prototype 第二段留下的纯逻辑模块和原型页面是参考，不是要提升的代码：逻辑模块可以搬进正式代码，页面按项目的组件和规范重新实现。
+
+开始实现前把设计说明补全到可执行：用户任务、内容与主动作、选定方向、视觉关系、关键状态、设备约束和验收重点。已有说明直接更新，不另开一份。
+
+## 2. 建立视觉与交互结构
+
+根据当前决策按需读取，不预先加载全部参考：
+
+| 要解决的问题 | 参考 |
+| --- | --- |
+| 视觉层级、字体、色彩、空间、图标、风格统一或减法精修 | [视觉语言](references/visual-language.md) |
+| 素材选择、视频与 3D | [素材](references/media.md) |
+| 生成配图：让图承担意思、写提示词、和页面接成一体 | [配图](references/imagery.md) |
+| 动效手感、界面过渡、首屏动画与滚动叙事、时长与检查 | [动效](references/motion.md) |
+| 精准还原、视口与溢出检查 | [布局与视口](references/layout-and-viewport.md) |
+
+新产品同时交代主要内容的视觉层级和关键操作链；不要只完成漂亮的默认状态。营销页面可以表达情绪与品牌，高频工具优先识别效率和操作稳定性。
+
+交互、表单、状态、弹窗和响应式的实现规则，项目或宿主已有相应规范时照用。
+
+在构图阶段按 [素材](references/media.md) 判断图像能否承担主信息或情绪重心，包括后台、工具和内容产品。需要关键素材时先选定或制作它，再围绕其主体、留白与裁切安排文字和操作；不等布局填满后再补图。
+
+既有项目先复用有效的设计变量、组件和交互习惯。发现既有模式妨碍任务时，修复对应源头；不为一次调整另造设计系统，也不把无关代码重构混入视觉工作。
+
+## 3. 制作并取得实际证据
+
+- 先完成代表性页面或关键操作链，检查后再延展到其他页面。只做局部修改时直接完成相关改动。
+- 素材有明确表达作用时才制作；文字、控件与业务信息保持可编辑。生成图片中的界面仅作为视觉样本。
+- 示例内容按真实产品的样子写。哪些是模拟数据、生成图片、未接入的动作，写在交付说明里，不写进界面：画面上不出现“示例”“待核实”“示意图”“概念稿”“按钮未接入”这类制作说明。不伪造业务成功、客户评价或产品指标。
+- 在相关目标视口运行并查看结果。记录截图对应的页面、状态、视口与版本；长页检查整体节奏和关键局部，不能只看首屏。
+- 在实际阅读尺寸检查中文多行标题、正文、控件和窄屏换行。文字重叠、被裁切或靠大量小字才装得下时，回到内容和布局修复，不以缩放预览或装饰精修掩盖。
+- 同一批相关修改集中检查，复用已有会话和证据。截图保存成功不等于已经看过；构建成功不等于视觉或操作已验证。
+
+## 4. 独立评审与修正
+
+新页面、整体改版或影响主要构图和任务流程的变更，在初版稳定后按 [视觉评审协议](references/visual-review.md) 进行一轮独立评审，报告评分和剩余差距。局部、低风险修改由主 Agent 检查，不为每个间距调整启动评审者。
+
+已有界面按它自己的规范评审。在已有项目里润色了一整页或多页、做完局部重构，或用户要求评审现有界面而没有要求重新设计时，用 [视觉评审协议](references/visual-review.md) 的“给已有界面评审”：标准是仓库现有的设计规范，没有成文规范时以现有实现和组件为准；怎样做得更好看，照常用视觉语言里的判断。只做一轮，不打分。单个元素的小改动不评审。
+
+- 主 Agent 保持设计方向与集成责任。具备隔离和看图能力时，派发无历史上下文的视觉评审子 Agent；缺少任一能力时改为主 Agent 自检，并标明未独立评审。
+- 在 `/atw-implement` 流水线里不自行派发评审者：独立视觉评审由流水线的审查步骤（atw-code-review）负责，把截图、对应的页面、状态和视口交给它。审查步骤不支持视觉评审时，主 Agent 按 [视觉评审协议](references/visual-review.md) 自检，并在交付说明里标明未独立评审。
+- 评审者看当前画面、任务、约束和必要参考，不看制作历史、代码或旧评分。记忆点是动效时，交给评审者一段录屏或开始、中间、结束三帧，静态截图看不出它。评审以“这一体裁里顶尖设计团队会怎么做”为参照指出最大差距，并按 10 分制给出当前画面离那个标准有多远。主 Agent 按反馈修正并重新取证，不把评审偏好自动当成用户要求。
+- 风格开始漂移、意见反复、收益不清楚或到达用户预算时，保留当前最合适的版本并说明具体取舍；未解决的必需功能仍如实列出，不能以停止美学迭代代替任务完成。
+- 用户对实现出来的设计反复不满意，怎么调都不对时，说明问题可能出在方向本身，建议回到 atw-prototype 重新比较方向，而不是继续在细节上打转。
+
+需要并行制作时，按独立页面、素材或区块划分所有权，给执行者相同的任务约束与设计说明；要求保留他人改动。只有阶段依赖已满足且主 Agent 同时有独立工作时才并行，不能让多个执行者同时改同一共享样式。没有并行能力时顺序完成。
+
+## 5. 验证与交付
+
+检查深度跟着改动走：新页面、改版和局部重构做下面全部检查；精修和基线做前后对比，再做受影响区域的细节检查，润色了一整页以上时加一轮步骤 4 的已有界面评审；小改动只看改动处和相邻元素，不做减法轮、不写评审记录。
+
+- 对照用户任务与选定方向检查真实内容、代表性视口和改动涉及的状态。交互从真实入口走到可观察结果；保存后重新读取，失败后检查输入和当前位置是否保留。
+- 使用现有相关检查及项目必需门禁。普通样式或文案调整以实际结果验证，不为一次检查新建长期测试体系。
+- 修正已发现的可用性、溢出、内容和视觉问题，复查受影响部分。按视觉语言做减法，同时保留识别对象、理解规则和完成操作所需的信息。
+- 单独做一次减法：一页只有一个主角，其余安静；逐区块删一轮文字，只放回删了会影响理解的。减法只删装饰和重复，对象名称、判断依据、当前状态和主动作必须留下。在 100% 和 200% 缩放下看关键区域。
+- 交付请求范围内的文件或预览，说明选定方向、关键变化、实际验证和剩余项。评审记录里写明评分和删掉了哪些文字。某一步没做，就写没做和原因，不省略不提。设计说明、素材、截图及评审记录放在 ATW 任务目录（截图放在 `screenshots/`，文件名写明页面、状态和视口，供审查和验收取证），复用已有组织方式，不写进技能安装目录。
+
+## 能力边界
+
+没有看图能力时可以产出设计说明、实现代码或源码层面的检查，但明确“未验证实际视觉”，不生成虚假的视觉评分。没有可运行环境时不能声称交互通过；请求要求可运行界面却只能交付方案时，明确标为未完成部分。
+
+没有生成能力时优先使用已有合适素材，或交付明确的素材需求和可用占位版本。只使用任务已授权的服务与配置，不因缺少素材自动接入付费服务；本技能不管理密钥、安装工具或发布网站。网络不可用时使用已有参考，并说明来源范围。

package/dist/templates/common/bundled-skills/atw-ui/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "ATW UI"
+  short_description: "按选定方向实现、精修与评审界面"

package/dist/templates/common/bundled-skills/atw-ui/references/imagery.md

@@ -0,0 +1,69 @@
+# 配图
+
+生成图最常见的失败不是画得不好，而是画得太满：细节越丰富越像图库照片，放进版面后没有重点，也和页面没有关系。好的配图要先承担意思，再承担气氛，最后和页面接成一个整体。
+
+## 先让图承担意思
+
+生成之前先写一句：这张图要让人一眼看懂什么？答不上来就先别生成。“一张好看的使用场景”不是答案；“产品把一堆混乱变成了哪几个清楚的结果”才是。
+
+用对比把信息编进图里。整体统一成一种低调的材质或颜色，比如白模、单色、失焦或剪影，只让承载信息的少数几处有颜色、光或细节。例如白色仓库模型里只有出了异常的两排货架亮成橙色，灰度地图上只有正在配送的路线是彩色。所有地方都一样精细，就等于没有重点；第一版通常就是这样失败的。
+
+选能和页面“接上”的主体：
+
+- 能跨过两块色面分界的单个物件。
+- 能延伸出画面的线：线缆、轨道、河流、胶片、纸带。
+- 能在上面标注的空间：模型、地图、剖面、平面图。
+
+这样的主体，之后能和页面里的线、标注和区块连成一体；一张自给自足的风景照做不到。
+
+## 写提示词
+
+按固定顺序写，每项一两句：
+
+1. **主体与表现形式**：什么东西，用什么体裁呈现（照片、插画、模型或图解），体裁从页面的方向推出。
+2. **视角与镜头**：机位的高度和角度；焦段和景深。
+3. **构图**：主体在画面里的位置和占比，四周留多少边距，哪一块留空给文字。要整件物体完整入画，就写明“完整地放在画面内，四周留出宽松边距”，否则常被裁掉一角，之后没法排版。
+4. **背景**：写出页面实际使用的十六进制色值，或者要求透明背景。
+5. **材质与光**：主光方向、辅光、质感。同一页的多张图用同一个光向。
+6. **重点**：用什么对比让哪几处成为焦点，其余部分怎样退后。
+7. **排除**：不要文字、标志、界面、屏幕内容；透明物件写明“地面不要阴影”。
+
+文字、界面和数据一律不让生图模型画：会画错，改不了，也不能被选中、翻译和读屏。它们放在页面上，用真实元素压在图上，或用引线连到图上。
+
+## 生成后放进页面再判断
+
+在真实页面、真实尺寸里看，不在图片查看器里判断。单独看很好的图，放进版面后常常主体太满、朝向不对、留白在错的位置。
+
+不对就改提示词重新生成，并写清要改什么，例如“除了三处重点，其余全部改成白色”“把整个模型收进画面”。不要围着一张不合适的图改版式。同一批里挑最能排版的一张，不挑细节最多的那张。
+
+## 让图和页面接成一体
+
+**背景融合。** 不透明的图，从图的四角实际取色，页面背景用同一个值；四条边都淡出到这个颜色，不加框，也不放进圆角卡片。只淡出一侧时，其余三边在宽屏上会露出矩形接缝。淡出可以用 CSS 遮罩，也可以在导出时直接把边缘渐隐成页面色值，后者不增加样式，适合样式体积受限的页面。生成图的底色常常不均匀，靠边缘会偏色，要在实际显示尺寸下检查接缝。
+
+**透明图。** 先放在最终背景上检查边缘、白边和残留的棋盘格；检查透明通道要看像素，不能看文件后缀。阴影不烘焙在图里，由页面按实际背景加投影，这样换了背景也对。
+
+**跨越结构。** 透明物件放在两个色块或两个区块的分界线上，让它同时属于两边。
+
+**图和代码接力。** 生成图负责代码做不出来的材质和光，例如金属、玻璃、模型、光影。代码负责需要精确、可编辑、会延续的部分，例如从图里延伸出去的线、路径和标注。如果图里有一段本该延续到页面的部分，就把它裁掉，改用矢量接着画。这样它能准确穿过版面，带上真实文字，并在不同宽度下重新走线。
+
+**标注。** 在图上标注用细引线加文字，不用带底色和阴影的气泡卡片。引线端点要对准图里的真实位置：图在版面里用固定的尺寸和位置，按图片像素换算坐标。窄屏上隐藏标注，或改成图下的列表，不让它们漂移到错误的位置。
+
+**窄屏裁切。** 不把整张大场景等比缩小到看不清。从原图裁出焦点区域另存一张给窄屏用，或用对象定位对准焦点。桌面和手机两种裁切，都要保住承载信息的那几处。
+
+**一张图用多次。** 结尾或其他区块可以用同一张图的局部特写，比再生成一张光线和风格对不上的图更统一。
+
+## 让一张画当舞台
+
+另一种用法正好相反：图不讲信息，只给气氛，界面保持黑白克制，全页只用一种有笔触的画当唯一的颜色来源，例如油画、水粉、水彩或版画。
+
+- **画当舞台，界面在上面演示。** 把真实界面的简化版放在画上，画从四周露出来。滚动时画固定不动，只换前面的界面内容，和“滚动叙事”接得上。
+- **大胆裁切。** 只留画的一角或一个局部，接近抽象，不和界面抢。题材不必和产品字面相关，但气质要对得上：快、静、暖或者松弛。
+- **松和紧互相衬托。** 画越松，界面越要精确、干净；两者一起出现，彼此都更好看。
+- **用得少。** 一张画贯穿全页，或者只在两三处出现，例如价格卡的顶端和页脚；不要每个区块配一张。同一页的画统一画种和笔触。
+- **演示用简化过的真实界面。** 次要内容虚化或换成骨架，只把要讲的那一处做清楚；数字对比直接用界面元素画出来，例如两条长短不同的进度条，而不是另做一张图表。
+
+## 文件与说明
+
+- 按显示尺寸的 2 倍导出，不直接内嵌原始大图。不透明的图用 JPEG 或 WebP，透明的用 WebP 或 PNG；单张控制在几百 KB 以内。内嵌成 data URL 后体积会再大约三分之一。
+- 保留提示词、原图和处理后的版本，写清每张图的用途和处理方式。
+- 生成图不冒充真实产品、真实场所或真实人物。虚构产品的小样，在页脚注明图片由 AI 生成。

package/dist/templates/common/bundled-skills/atw-ui/references/layout-and-viewport.md

@@ -0,0 +1,15 @@
+# 布局与视口
+
+## 精准还原
+
+先记录参考图的逻辑视口或已知像素尺寸、完整范围和固定区域。图像像素不等于逻辑视口；无法确定时说明假设。
+
+测量主区域比例、共享对齐线、文字尺度、图片裁切与间距关系。先对齐整体几何与字体，再处理边框、阴影和细节；不因还原任务重新探索风格。
+
+用与参考相当的视口和内容检查差异。参考没有展示的窄屏与状态根据内容约束补充，并区分“参考还原”与“合理延展”。
+
+## 验证重点
+
+实际检查长内容、空内容和当前改动相关状态。移动端注意视口变化、输入面板与安全边距，主操作不能被键盘或固定区域遮挡。
+
+检查页面是否意外横向溢出、滚动是否发生在预期区域、焦点与菜单是否可见，以及缩放或重排后阅读和操作顺序是否仍然清楚。