@dev-workflow/skill 0.1.0

package/skills/execution/figmaSync/scripts/lookup-var.mjs

@@ -0,0 +1,184 @@
+/**
+ * Lookup Var (Fast Path 1)
+ *
+ * 把 CSS 变量名映射到 /theme 路径——专为「设计稿 CSS 已含 var() 引用」的快路径。
+ * 不做反向哈希搜索，只做查表。
+ *
+ * 用法:
+ *   node .agent/skills/figmaSync/scripts/lookup-var.mjs "--fill-neutral-primary"
+ *   node .agent/skills/figmaSync/scripts/lookup-var.mjs "var(--fill-neutral-primary, #090A0B)"
+ *   node .agent/skills/figmaSync/scripts/lookup-var.mjs "--apex-spacing-8"
+ *
+ * 支持的变量命名:
+ *   --apex-fill-neutral-primary   (apex-ui 实际产出)
+ *   --fill-neutral-primary        (设计师在 Figma 里常写的简写)
+ *   var(--xxx, fallback)          (整段 CSS 表达式也接受)
+ *
+ * 输出（命中）:
+ *   {
+ *     "success": true,
+ *     "cssVariable": "--fill-neutral-primary",            // ✅ 直接写入 CSS: var(--fill-neutral-primary)
+ *     "themePath": "foundation.fill.neutral.primary",     // ✅ 写入 PLAN.md 供审核
+ *     "cssValue": "{grey.14}",
+ *     "usage": ["color"],
+ *     "$type": "color",
+ *     "layer": "foundation",
+ *     "shortRef": "fill.neutral.primary"
+ *   }
+ *
+ * 输出（未命中）:
+ *   { "success": false, "message": "...", "candidates": [...top-5 模糊建议...] }
+ */
+import { appendSessionLog } from './_shared/session-log.mjs'
+import { loadCurrentTokenRecords } from './_shared/token-source.mjs'
+
+const ALIAS_LAYER_ORDER = ['foundation', 'baseValue', 'palette']
+
+function parseArg(raw) {
+  if (!raw) return null
+  const varMatch = raw.match(/var\(\s*(--[a-zA-Z0-9_-]+)/)
+  if (varMatch) return varMatch[1]
+  const trimmed = raw.trim()
+  if (trimmed.startsWith('--')) return trimmed
+  return null
+}
+
+function buildVarIndex(records) {
+  // 一个变量记录同时支持两种 var 写法（带/不带 apex- 前缀），并支持 path 后缀命中
+  const map = new Map()
+  for (const rec of records) {
+    const segments = rec.path
+    const dashJoined = segments.join('-').toLowerCase()
+    const variants = new Set([
+      `--${dashJoined}`,
+      `--apex-${dashJoined}`,
+      // 部分设计师会把 setName 也写进 var 名（罕见，但兼容）
+      `--${rec.setName.toLowerCase()}-${dashJoined}`
+    ])
+    if (rec.cssVar) variants.add(rec.cssVar.toLowerCase())
+    for (const v of variants) {
+      if (!map.has(v)) map.set(v, [])
+      map.get(v).push(rec)
+    }
+  }
+  return map
+}
+
+function pickRecommended(records) {
+  // var 命中可能多 set 同名（foundation 与 component 都叫 fill.neutral.primary 很少见，但允许）
+  // 推荐顺序：foundation > baseValue > component > componentUsage > palette
+  for (const layer of ALIAS_LAYER_ORDER) {
+    const hit = records.find((r) => r.setName === layer)
+    if (hit) return hit
+  }
+  return records[0]
+}
+
+function fuzzyCandidates(varName, varIndex, limit = 5) {
+  const clean = varName.replace(/^(--apex-|--)/, '')
+  const keys = [...varIndex.keys()].map((k) => k.replace(/^(--apex-|--)/, ''))
+  // 简单子串排序
+  const ranked = keys
+    .map((k) => ({ k, score: similarity(clean, k) }))
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+  return ranked.map((r) => `--${r.k}`)
+}
+
+function similarity(a, b) {
+  if (a === b) return 1
+  if (b.includes(a) || a.includes(b)) return 0.7
+  const tokensA = a.split('-')
+  const tokensB = b.split('-')
+  const common = tokensA.filter((t) => tokensB.includes(t)).length
+  return common / Math.max(tokensA.length, tokensB.length)
+}
+
+function main() {
+  const arg = process.argv[2]
+  const varName = parseArg(arg)
+  if (!varName) {
+    console.log(
+      JSON.stringify({
+        success: false,
+        message: 'Provide a CSS variable like "--fill-neutral-primary" or "var(--xxx, fallback)"'
+      })
+    )
+    process.exit(0)
+  }
+
+  let records
+  try {
+    records = loadRecords()
+  } catch (err) {
+    console.log(JSON.stringify({ success: false, message: err.message }))
+    process.exit(0)
+  }
+
+  const varIndex = buildVarIndex(records)
+
+  const hits = varIndex.get(varName.toLowerCase())
+  if (!hits || hits.length === 0) {
+    appendSessionLog({ script: 'lookup-var', input: varName, hit: false })
+    console.log(
+      JSON.stringify({
+        success: false,
+        message: `No token mapped to ${varName}. If the value is hardcoded, run match-token.mjs instead.`,
+        candidates: fuzzyCandidates(varName, varIndex)
+      })
+    )
+    process.exit(0)
+  }
+
+  const recommended = pickRecommended(hits)
+  const themePath = `${recommended.setName}.${recommended.pathStr}`
+  const cssVariable = recommended.cssVar ?? toCssVariable(recommended.path)
+  const usage = collectUsage(recommended)
+  appendSessionLog({
+    script: 'lookup-var',
+    input: varName,
+    hit: true,
+    token: themePath,
+    cssVariable,
+    layer: recommended.setName,
+    type: recommended.$type
+  })
+  console.log(
+    JSON.stringify({
+      success: true,
+      cssVariable,
+      themePath,
+      cssValue: recommended.$value,
+      usage,
+      $type: recommended.$type,
+      layer: recommended.setName,
+      shortRef: recommended.pathStr
+    })
+  )
+}
+
+function loadRecords() {
+  return loadCurrentTokenRecords().records
+}
+
+function collectUsage(record) {
+  if (record.$type === 'color')
+    return ['color', 'background-color', 'border-color', 'fill', 'stroke']
+  if (record.$type === 'number') {
+    const first = record.path[0]
+    if (first === 'spacing') return ['gap', 'padding', 'margin', 'inset']
+    if (first === 'radius') return ['border-radius']
+    if (first === 'border') return ['border-width']
+    if (first === 'size') return ['width', 'height', 'min-width', 'min-height']
+    if (first?.startsWith('font'))
+      return ['font-size', 'font-weight', 'line-height', 'letter-spacing']
+  }
+  return []
+}
+
+function toCssVariable(pathParts) {
+  return `--${pathParts.join('-')}`
+}
+
+main()

package/skills/execution/figmaSync/scripts/match-token.mjs

@@ -0,0 +1,210 @@
+/**
+ * Match Token
+ *
+ * 用法:
+ *   node .agent/skills/figmaSync/scripts/match-token.mjs "<value>" [--type=color|number]
+ *
+ * 行为:
+ *   1. 加载 theme/dark CSS token 源
+ *   2. 反向查找：哪些 /theme CSS variables 最终解析后等于 <value>
+ *   3. 按层级优先级排序：foundation > baseValue > palette
+ *   4. 默认推荐 foundation 层（语义稳定 + 跨组件可复用）
+ *
+ * 推荐策略（按 $type 分流）:
+ *   - color  : foundation > palette
+ *              （foundation 语义稳定 + 跨组件复用；palette 是最差选择）
+ *   - number : baseValue
+ *              （baseValue 的 spacing.8 / radius.4 已是语义化最稳定的层）
+ *
+ * 输出示例（命中）:
+ *   {
+ *     "success": true,
+ *     "matches": [...],
+ *     "recommend": {
+ *       "layer": "foundation",
+ *       "themePath": "foundation.fill.neutral.tertiary",
+ *       "cssVariable": "--fill-neutral-tertiary",
+ *       "cssValue": "{grey.12}"
+ *     },
+ *     "recommendReason": "color variables default to foundation layer..."
+ *   }
+ *
+ * 输出示例（未命中）:
+ *   { "success": false, "message": "No match found.", "originalValue": "..." }
+ */
+import { appendSessionLog } from './_shared/session-log.mjs'
+import { createResolver, findTokensByValue } from './_shared/token-resolver.mjs'
+import { loadCurrentTokenRecords } from './_shared/token-source.mjs'
+
+const RECOMMEND_LAYER_ORDER_BY_TYPE = {
+  color: ['foundation', 'component', 'componentUsage', 'palette'],
+  number: ['baseValue', 'componentUsage', 'component']
+}
+
+const RECOMMEND_REASON_BY_TYPE = {
+  color:
+    'color variables default to foundation layer for semantic stability and cross-component reuse',
+  number:
+    'number variables default to baseValue layer (spacing/radius/size) as the most stable semantic source'
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2)
+  const out = { value: null, type: null }
+  for (const arg of args) {
+    if (arg.startsWith('--type=')) {
+      out.type = arg.slice('--type='.length)
+    } else if (!out.value) {
+      out.value = arg
+    }
+  }
+  return out
+}
+
+/**
+ * 把用户输入规范化为可比对的字面量：
+ *   - "8px" / "8.5px" → "8" / "8.5"（字符串，与 CSS token 记录输出对齐）
+ *   - "0.8" / "8" → 同上
+ *   - "#abcdef" / "rgb(...)" 保留小写
+ *   - 其余原样返回
+ * 返回值始终是 string，避免 sonar 多类型返回告警，也方便日志去重。
+ */
+function normalizeQuery(raw) {
+  if (raw === undefined || raw === null) return ''
+  const trimmed = String(raw).trim()
+  const pxMatch = /^(-?\d+(?:\.\d+)?)px$/i.exec(trimmed)
+  if (pxMatch) return pxMatch[1]
+  const numMatch = /^(-?\d+(?:\.\d+)?)$/.exec(trimmed)
+  if (numMatch) return numMatch[1]
+  return trimmed.toLowerCase()
+}
+
+function isNumericQuery(value) {
+  return /^-?\d+(?:\.\d+)?$/.test(String(value))
+}
+
+function main() {
+  const { value, type } = parseArgs(process.argv)
+
+  if (!value) {
+    console.log(
+      JSON.stringify({
+        success: false,
+        message: 'Missing value argument. Usage: node match-token.mjs <value> [--type=color|number]'
+      })
+    )
+    process.exit(0)
+  }
+
+  let loaded
+  try {
+    loaded = loadTokenRecords()
+  } catch (err) {
+    console.log(JSON.stringify({ success: false, message: err.message }))
+    process.exit(0)
+  }
+
+  const records = loaded.records
+  const resolver = createResolver(records, loaded.order)
+
+  const normalized = normalizeQuery(value)
+  let matches = findTokensByValue(resolver, normalized)
+  if (type) {
+    matches = matches.filter((m) => m.$type === type)
+  } else if (isNumericQuery(normalized)) {
+    const numberMatches = matches.filter((m) => m.$type === 'number')
+    if (numberMatches.length > 0) matches = numberMatches
+  }
+
+  if (matches.length === 0) {
+    appendSessionLog({ script: 'match-token', input: value, hit: false })
+    console.log(
+      JSON.stringify({
+        success: false,
+        message: 'No match found. Proceed with Fallback Levels (Level 1/2/3).',
+        originalValue: value,
+        normalizedValue: normalized
+      })
+    )
+    process.exit(0)
+  }
+
+  const simplifiedMatches = matches.map((m) => ({
+    layer: m.setName,
+    themePath: `${m.setName}.${m.path}`,
+    cssVariable: m.cssVar ?? toCssVariable(m.path.split('.')),
+    cssValue: m.$value,
+    resolvedValue: m.resolvedValue,
+    $type: m.$type
+  }))
+
+  const primaryType = simplifiedMatches[0].$type
+  const layerOrder = RECOMMEND_LAYER_ORDER_BY_TYPE[primaryType] ?? ['foundation']
+  let recommend = pickRecommendedMatch(simplifiedMatches, primaryType)
+  for (const layer of layerOrder) {
+    const hit = simplifiedMatches.find((m) => m.layer === layer)
+    if (hit) {
+      recommend = pickRecommendedMatch(
+        simplifiedMatches.filter((m) => m.layer === layer),
+        primaryType
+      )
+      break
+    }
+  }
+
+  appendSessionLog({
+    script: 'match-token',
+    input: value,
+    hit: true,
+    token: recommend.themePath,
+    cssVariable: recommend.cssVariable,
+    layer: recommend.layer,
+    type: primaryType
+  })
+
+  console.log(
+    JSON.stringify({
+      success: true,
+      matches: simplifiedMatches,
+      recommend,
+      recommendReason:
+        RECOMMEND_REASON_BY_TYPE[primaryType] ?? 'no recommendation rule for this token type'
+    })
+  )
+}
+
+function pickRecommendedMatch(matches, primaryType) {
+  if (primaryType !== 'number') return matches[0]
+
+  const pathPriority = [
+    'spacing.',
+    'radius.',
+    'size.',
+    'border.',
+    'icon.',
+    'fontsize.',
+    'fontheight.',
+    'fontspacing.'
+  ]
+  return [...matches].sort((a, b) => {
+    const aPriority = priorityForPath(a.themePath, pathPriority)
+    const bPriority = priorityForPath(b.themePath, pathPriority)
+    return aPriority - bPriority
+  })[0]
+}
+
+function priorityForPath(path, prefixes) {
+  const shortPath = path.split('.').slice(1).join('.')
+  const index = prefixes.findIndex((prefix) => shortPath.startsWith(prefix))
+  return index === -1 ? prefixes.length : index
+}
+
+function loadTokenRecords() {
+  return loadCurrentTokenRecords()
+}
+
+function toCssVariable(pathParts) {
+  return `--${pathParts.join('-')}`
+}
+
+main()

package/skills/execution/figmaSync/scripts/prepare-check.mjs

@@ -0,0 +1,290 @@
+/**
+ * Prepare Check
+ *
+ * 检查 figmaSync 原生 CSS 工作流依赖的技术栈与资源。分级输出：
+ *   - blocker: 缺失会阻塞 plan/apply
+ *   - warning: 不影响运行但建议修复
+ *   - info:    诊断信息
+ *
+ * 用法:
+ *   pnpm figma:prepare
+ *   pnpm figma:prepare --json
+ */
+import { execSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ROOT = process.cwd()
+
+const CHECKS = [
+  checkNodeVersion,
+  checkPackageManager,
+  checkRequiredDeps,
+  checkRequiredDevDeps,
+  checkThemeCss,
+  checkPackageScripts,
+  checkGitignore,
+  checkApexUiAvailable,
+  checkCommonComponentSources,
+  checkAssetSources,
+  checkRouterConvention,
+  checkFigmaMcpHint
+]
+
+function main() {
+  const json = process.argv.includes('--json')
+  const results = []
+  for (const fn of CHECKS) {
+    try {
+      const r = fn()
+      if (Array.isArray(r)) results.push(...r)
+      else if (r) results.push(r)
+    } catch (err) {
+      results.push({
+        level: 'blocker',
+        name: fn.name,
+        message: `check threw: ${err.message}`
+      })
+    }
+  }
+
+  const blockers = results.filter((r) => r.level === 'blocker')
+  const warnings = results.filter((r) => r.level === 'warning')
+  const infos = results.filter((r) => r.level === 'info')
+
+  if (json) {
+    console.log(JSON.stringify({ blockers, warnings, infos }, null, 2))
+  } else {
+    printHuman(results)
+    console.log()
+    console.log(
+      `[figma:prepare] ${blockers.length} blocker · ${warnings.length} warning · ${infos.length} info`
+    )
+  }
+
+  process.exit(blockers.length > 0 ? 1 : 0)
+}
+
+function printHuman(results) {
+  const groups = { blocker: '❌', warning: '⚠️ ', info: 'ℹ️ ' }
+  for (const level of ['blocker', 'warning', 'info']) {
+    const items = results.filter((r) => r.level === level)
+    if (items.length === 0) continue
+    console.log(`\n${groups[level]} ${level.toUpperCase()}`)
+    for (const r of items) {
+      console.log(`  · [${r.name}] ${r.message}`)
+      if (r.fix) console.log(`      fix → ${r.fix}`)
+    }
+  }
+  if (results.every((r) => r.level === 'info')) {
+    console.log('\n✅ All checks passed.')
+  }
+}
+
+function checkNodeVersion() {
+  const v = process.versions.node
+  const major = Number(v.split('.')[0])
+  if (major < 18) {
+    return {
+      level: 'blocker',
+      name: 'node-version',
+      message: `Node ${v} 太旧；要求 ≥ 18`,
+      fix: '升级 Node 到 18+'
+    }
+  }
+  return { level: 'info', name: 'node-version', message: `Node ${v} OK` }
+}
+
+function checkPackageManager() {
+  try {
+    const v = execSync('pnpm -v', { encoding: 'utf-8' }).trim()
+    return { level: 'info', name: 'pnpm', message: `pnpm ${v} OK` }
+  } catch {
+    return {
+      level: 'blocker',
+      name: 'pnpm',
+      message: 'pnpm 未安装',
+      fix: 'corepack enable && corepack prepare pnpm@latest --activate'
+    }
+  }
+}
+
+function readPackageJson() {
+  const p = path.join(ROOT, 'package.json')
+  if (!fs.existsSync(p)) throw new Error('package.json missing in project root')
+  return JSON.parse(fs.readFileSync(p, 'utf-8'))
+}
+
+function checkRequiredDeps() {
+  const pkg = readPackageJson()
+  const deps = pkg.dependencies ?? {}
+  const required = ['@frontend/apex-ui--react']
+  return required.map((name) =>
+    deps[name]
+      ? { level: 'info', name: `dep:${name}`, message: `${name}@${deps[name]} OK` }
+      : {
+          level: 'blocker',
+          name: `dep:${name}`,
+          message: `缺少 dependency ${name}`,
+          fix: `pnpm add ${name}`
+        }
+  )
+}
+
+function checkRequiredDevDeps() {
+  const pkg = readPackageJson()
+  const deps = pkg.devDependencies ?? {}
+  const required = ['@babel/parser', '@babel/traverse', 'globby']
+  return required.map((name) =>
+    deps[name]
+      ? { level: 'info', name: `devDep:${name}`, message: `${name}@${deps[name]} OK` }
+      : {
+          level: 'warning',
+          name: `devDep:${name}`,
+          message: `缺少 devDependency ${name}，部分报告能力可能受影响`,
+          fix: `pnpm add -D ${name}`
+        }
+  )
+}
+
+function checkThemeCss() {
+  const srcDir = path.join(ROOT, 'theme', 'dark')
+  const requiredCss = ['primitives.css', 'aliases.css']
+  const missingCss = requiredCss.filter((file) => !fs.existsSync(path.join(srcDir, file)))
+  if (missingCss.length > 0) {
+    return {
+      level: 'blocker',
+      name: 'theme-css',
+      message: `theme/dark 缺少：${missingCss.join(', ')}`,
+      fix: '先补齐 /theme CSS variables 源文件'
+    }
+  }
+  return { level: 'info', name: 'theme-css', message: 'theme/dark CSS variables 源 OK' }
+}
+
+const REQUIRED_SCRIPTS = ['figma:report', 'figma:verify-plan']
+
+function checkPackageScripts() {
+  const pkg = readPackageJson()
+  const scripts = pkg.scripts ?? {}
+  return REQUIRED_SCRIPTS.map((name) =>
+    scripts[name]
+      ? { level: 'info', name: `script:${name}`, message: `script "${name}" OK` }
+      : {
+          level: 'blocker',
+          name: `script:${name}`,
+          message: `package.json scripts 缺少 "${name}"`,
+          fix: '参考 figmaSync SKILL.md 速查表补齐 scripts'
+        }
+  )
+}
+
+const REQUIRED_GITIGNORE = [
+  '.agent/skills/figmaSync/.session-log.jsonl',
+  '.agent/skills/figmaSync/session-report-plan.md',
+  '.agent/skills/figmaSync/session-report-apply.md'
+]
+
+function checkGitignore() {
+  const p = path.join(ROOT, '.gitignore')
+  if (!fs.existsSync(p)) {
+    return {
+      level: 'warning',
+      name: 'gitignore',
+      message: '.gitignore 不存在',
+      fix: '至少忽略 figmaSync session 文件'
+    }
+  }
+  const text = fs.readFileSync(p, 'utf-8')
+  const missing = REQUIRED_GITIGNORE.filter((line) => !text.includes(line))
+  if (missing.length > 0) {
+    return {
+      level: 'warning',
+      name: 'gitignore',
+      message: `.gitignore 缺项：${missing.join(', ')}`,
+      fix: '把缺失行追加到 .gitignore'
+    }
+  }
+  return { level: 'info', name: 'gitignore', message: '.gitignore OK' }
+}
+
+function checkApexUiAvailable() {
+  const llms = path.join(ROOT, 'node_modules/@frontend/apex-ui--react/dist/llms.txt')
+  if (!fs.existsSync(llms)) {
+    return {
+      level: 'warning',
+      name: 'apex-ui-llms',
+      message: 'apex-ui llms.txt 找不到，组件复用判断会受影响',
+      fix: 'pnpm install 重新安装 @frontend/apex-ui--react'
+    }
+  }
+  return { level: 'info', name: 'apex-ui-llms', message: 'apex-ui llms.txt 可用' }
+}
+
+function checkCommonComponentSources() {
+  const commonDir = path.join(ROOT, 'src', 'common')
+  if (!fs.existsSync(commonDir)) {
+    return {
+      level: 'warning',
+      name: 'common-components',
+      message: 'src/common 不存在，plan 阶段无法扫描 common component 复用机会'
+    }
+  }
+  return { level: 'info', name: 'common-components', message: 'src/common 可扫描' }
+}
+
+function checkAssetSources() {
+  const candidates = [
+    'assets',
+    'icons',
+    'public',
+    path.join('src', 'assets'),
+    path.join('src', 'icons')
+  ]
+  const existing = candidates.filter((item) => fs.existsSync(path.join(ROOT, item)))
+  if (existing.length === 0) {
+    return {
+      level: 'warning',
+      name: 'assets',
+      message: '未发现常见 assets/icons 目录，icon 匹配可能全部进入待确认'
+    }
+  }
+  return { level: 'info', name: 'assets', message: `可扫描资产目录：${existing.join(', ')}` }
+}
+
+function checkRouterConvention() {
+  const pkg = readPackageJson()
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
+  const detected = []
+  if (deps['@tanstack/react-router']) detected.push('TanStack Router')
+  if (deps['react-router-dom'] || deps['react-router']) detected.push('React Router')
+  if (deps.next) detected.push('Next.js App Router')
+
+  if (detected.length === 0) {
+    return {
+      level: 'info',
+      name: 'router',
+      message: '未识别到路由库；PLAN.md 中 targetFile 由用户决定'
+    }
+  }
+  const router = detected.join(' + ')
+  let hint = ''
+  if (detected.includes('TanStack Router')) {
+    hint = ' → file-based 路由：targetFile 用 `src/routes/<feature>/route.tsx`'
+  } else if (detected.includes('Next.js App Router')) {
+    hint = ' → App Router：targetFile 用 `app/<feature>/page.tsx`'
+  } else if (detected.includes('React Router')) {
+    hint = ' → 常见约定 `src/pages/<feature>/index.tsx`'
+  }
+  return { level: 'info', name: 'router', message: `检测到 ${router}${hint}` }
+}
+
+function checkFigmaMcpHint() {
+  return {
+    level: 'info',
+    name: 'figma-mcp',
+    message: 'Figma MCP 可用性由 AI 在 plan 阶段调用 whoami 试探，shell 无法判断'
+  }
+}
+
+main()