前端约定的 机器可读化

export const DEFAULT_WIZARD_STATE: WizardState = {
  framework: 'nextjs',
  language: 'typescript',
  pkgMgr: 'pnpm',
  buildTool: 'vite',
  i18n: 'none',
  textDirection: 'ltr',
  componentLib: 'shadcn',
  cssSolution: 'tailwind',
  iconLib: 'lucide',
  globalState: 'zustand',
  serverState: 'tanstack-query',
  linter: 'eslint',
  formatter: 'prettier',
  preCommit: 'husky-lint-staged',
  testing: ['vitest'],
  cicd: 'github-actions',
  dirPattern: 'feature-based',
  dirDepth: 3,
  fileNaming: 'kebab-case',
  importOrder: 'framework-first',
  maxFileLines: 300,
  themeStyle: 'minimalism',
  customTokens: {},
  colorDepth: '5-tier',
  spacingBase: 4,
  tokenConvention: 'css-vars',
  typographyScale: 'major-third',
}

// 用常量避免在模板字符串里转义反引号
const B = '`'
const FENCE = B + B + B  // 代码块标记 ```

let _v: VersionMap = {}

// 获取包的实时版本，失败时回退
const mv = (pkg: string, fb: string): string => _v[pkg] ?? FALLBACK_VERSIONS[pkg] ?? fb

// 格式化为 package.json 依赖条目
const pd = (pkg: string, fb: string): string => `"${pkg}": "^${mv(pkg, fb)}.x"`

export function generateDocument(s: WizardState, v: VersionMap = {}): string {
  // 注入实时版本，使 mv()/pd()/标签辅助函数能取到最新版本
  _v = { ...FALLBACK_VERSIONS, ...v }

  const sections = [
    s1Overview(s),       s2TechStack(s),  s3Directory(s),
    s4Naming(s),         s5Components(s), s6StateManagement(s),
    s7Styles(s),         s8Toolchain(s),  s9Testing(s),
    s10DesignTokens(s),  s11Git(s),       s12CICD(s),
    s13I18n(s),
  ].filter((sec): sec is string => sec !== null)  // s13I18n 对 i18n='none' 返回 null

  _v = {}  // 生成后重置
  return sections.join('\n\n---\n\n')
}

// 功能颜色（必须符合用户心理预期）
const FUNCTIONAL_VARS = [
  '--color-success', '--color-error',
  '--color-warning', '--color-info', '--color-link'
]

// 中性颜色分三层：Text / Background / Border
const NEUTRAL_VARS = [
  // Text:   --color-text-primary/secondary/tertiary/disabled/inverse
  // Bg:     --color-neutral-bg/bg-subtle/bg-muted/elevated
  // Border: --color-neutral-divider/border/border-strong
]

// 品牌颜色（通过 customTokens 自定义，排除已知功能/中性变量）
const brandLines = Object.entries(tokens)
  .filter(([cssVar]) => !FUNCTIONAL_VARS.includes(cssVar) && !allNeutralVars.includes(cssVar))
  .map(([cssVar, value]) => `  ${cssVar}: ${value};`)
  .join('\n')

export function generateSkill(s: WizardState, v: VersionMap = {}): string {
  _v = { ...FALLBACK_VERSIONS, ...v }

  const pm = PM_RUN[s.pkgMgr]    // e.g. "pnpm"
  const px = PM_EXEC[s.pkgMgr]   // e.g. "pnpm dlx"
  const isTS = s.language === 'typescript'

  // 构建技术栈描述
  const stack = [
    fwLabel(s.framework),
    isTS ? 'TypeScript' : 'JavaScript',
    cssLabel(s.cssSolution),
    stateLabel(s.globalState),
    s.serverState !== 'none' ? serverStateLabel(s.serverState) : '',
  ].filter(Boolean).join(', ')

  // ... 生成 skill 内容
}

---
name: frontend-align-dev
description: >
  Use whenever writing, modifying, or reviewing frontend code in this project.
  Stack: Next.js 16, TypeScript, Tailwind CSS v4, Zustand, TanStack Query v5.
  Triggers on any component, hook, store, style, or test file change.
---

## Dependency Bootstrap        # 检查 ui-ux-pro-max-skill 是否存在
## Required Reading            # 要求阅读 frontend-align.md
## Workflow                    # 1 理解需求 2 检查结构 3 实现 4 lint/typecheck/test 5 合规审查
## Compliance Checklist        # 7–10 条，按 stack 动态定制
  - Component naming follows the standard.
  - Folder structure follows the standard.
  - TypeScript types are explicit — no `any`.
  - State management (Zustand) follows the standard.
  - Styling (Tailwind CSS) follows the standard.
  - All user-facing strings go through the i18n layer.   # 若启用 i18n
  - New logic has corresponding unit tests.              # 若启用测试
## Final Response Format       # 修改内容 / 遵循的规则 / 无法遵循的规则 / 运行的命令

const lintCmd = s.linter === 'biome'
  ? `${px} @biomejs/biome check --apply .`
  : `${pm} lint`

const typecheckCmd = isTS ? `${px} tsc --noEmit` : null
const testCmd = s.testing.length > 0 ? `${pm} test` : null

const checkCmds = [lintCmd, typecheckCmd, testCmd].filter(Boolean).join(' / ')
// 输出示例: "pnpm lint / npx tsc --noEmit / pnpm test"

export type VersionMap = Record<string, string>
// 例如: { next: '16', react: '19', vite: '6', ... }

export async function fetchVersions(): Promise<VersionMap> {
  try {
    const res = await fetch('/api/versions', { cache: 'no-store' })
    if (!res.ok) return FALLBACK_VERSIONS
    const data = await res.json() as VersionMap
    // 合并：API 结果优先，回退版本填补空缺
    return { ...FALLBACK_VERSIONS, ...data }
  } catch {
    return FALLBACK_VERSIONS
  }
}

WizardState（用户配置）          VersionMap（npm 版本）
  ├── framework: 'nextjs'          ├── next: '16'
  ├── language: 'typescript'       ├── react: '19'
  ├── pkgMgr: 'pnpm'               ├── tailwindcss: '4'
  ├── cssSolution: 'tailwind'      └── ...
  ├── globalState: 'zustand'
  ├── serverState: 'tanstack-query'
  ├── themeStyle: 'minimalism'
  ├── customTokens: { --color-primary: '#3b82f6', ... }
  └── ...
            │
            ▼
  ┌────────────────────────────────────────────┐
  │  generateDocument(state, versions)          │
  │   s1Overview → s2TechStack → s3Directory     │
  │   → s4Naming → s5Components → s6State…        │
  │   → s7Styles → s8Toolchain → s9Testing       │
  │   → s10DesignTokens → s11Git → s12CICD        │
  │   → s13I18n（可选）                            │
  └────────────────────────────────────────────┘
            │                       │
            ▼                       ▼
  frontend-align.md（人读）   generateSkill(state, versions)
                                    │
                                    ▼
                          SKILL.md（机器读）