design-compliance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Compliance

设计合规性

Run a fully autonomous design system compliance audit on a page or component of the Hexagone Web application. The skill discovers source files, recursively analyzes the full component tree, visually inspects the rendered page (light + dark mode), detects all violations against the Hexagone design system rules, auto-fixes every violation in place, and prints a structured report — all without asking the user for confirmation.

对Hexagone Web应用的页面或组件执行完全自动化的设计系统合规性审计。该技能会自动发现源文件，递归分析完整组件树，可视化检查渲染后的页面（亮色+暗色模式），检测所有违反Hexagone设计系统规则的问题，就地自动修复所有违规项，并输出结构化报告——全程无需向用户请求确认。

When to Use This Skill

何时使用此技能

Activate when the user:

Says "design-compliance" followed by a URL, component name, or page name
Asks to audit or check design system compliance on a page or component
Wants to enforce PrimeVue / Tailwind / Hexagone token conventions on existing code
Says "check the design", "audit the UI", "design review" on Hexagone code

当用户出现以下行为时激活：

说出"design-compliance"并附带URL、组件名或页面名
要求审计或检查页面/组件的设计系统合规性
想要在现有代码上强制执行PrimeVue / Tailwind / Hexagone令牌规范
针对Hexagone代码说出"检查设计"、"审计UI"、"设计评审"等需求

Core Principles

核心原则

1. Full Autonomy

1. 完全自动化

The entire pipeline runs without asking questions during execution
If no argument is provided, ask the user what to review — then run autonomously
Files are edited in place without confirmation
Changes are NOT committed — the developer reviews the diff

整个流程执行期间无需询问任何问题
如果未提供参数，先询问用户需要评审的内容，再自主执行
文件就地编辑，无需确认
不会提交更改——由开发者审核diff内容

2. Single Standard (No Per-MF Exceptions)

2. 统一标准（无单微前端例外）

Composition API with
```
<script setup lang="ts">
```
— always
Tailwind CSS 4 — always
Pinia for state management — always
PrimeVue 4 native components — always (no hexa-compat in new/modified code)
dt
for scoped token overrides — always (never
```
pt
```
for visual styling)

始终使用带
```
<script setup lang="ts">
```
的Composition API
始终使用Tailwind CSS 4
始终使用Pinia做状态管理
始终使用PrimeVue 4原生组件（新/修改代码中不得使用hexa-compat组件）
始终使用**
```
dt
```
**做作用域令牌覆盖（视觉样式不得使用
```
pt
```
）

3. Hexagone-Specific

3. Hexagone专属适配

This skill is tailored to the Hexagone Web monorepo stack:

PrimeVue 4.3 with
```
hexagone-preset.js
```
(extends Aura)
Tailwind CSS 4
3-layer token system:
```
--p-*
```
(PrimeVue),
```
--hexa-*
```
(shell only), beta-scss (legacy, forbidden)
Vue.js 3.5 with TypeScript

该技能专为Hexagone Web monorepo技术栈定制：

搭载
```
hexagone-preset.js
```
的PrimeVue 4.3（扩展自Aura）
Tailwind CSS 4
三层令牌系统：
```
--p-*
```
（PrimeVue）、
```
--hexa-*
```
（仅shell层使用）、beta-scss（遗留语法，已禁用）
搭载TypeScript的Vue.js 3.5

4. Fix Everything

4. 全量修复

The skill auto-fixes ALL violations — mechanical (import renames, class swaps) AND structural (component replacements, template rewrites). No report-only mode. No asking before editing.

该技能会自动修复所有违规项：包括机械类（导入重命名、类名替换）和结构类（组件替换、模板重写）。无仅报告模式，编辑前无需询问。

Source of Truth (Priority Order)

规则优先级（从高到低）

The skill builds its ruleset from these sources, checked in order:

Explicit rules files (override everything if present):

design-system.md

docs/design-system/design-rules.md

```
CLAUDE.md
```
(root and per-MF)

.github/copilot-instructions.md

.github/instructions/*.md

Framework configuration:
- ```
hexagone-preset.js
```
  — PrimeVue preset (tokens, color scheme)
- ```
shell-tokens.scss
```
  — Shell chrome tokens (
```
--hexa-*
```
  )
- ```
tailwind.config.*
```
  — Tailwind configuration
- ```
package.json
```
  — PrimeVue version, dependencies
Codebase patterns:
- Existing "good" components as implicit conventions
- Router configuration for route-to-component mapping

该技能从以下来源构建规则集，按顺序校验：

显式规则文件（如果存在会覆盖所有其他规则）：

design-system.md

或

docs/design-system/design-rules.md

```
CLAUDE.md
```
（根目录和单微前端目录）

.github/copilot-instructions.md

或

.github/instructions/*.md

框架配置：
- ```
hexagone-preset.js
```
  —— PrimeVue预设（令牌、配色方案）
- ```
shell-tokens.scss
```
  —— Shell层Chrome令牌（
```
--hexa-*
```
  ）
- ```
tailwind.config.*
```
  —— Tailwind配置
- ```
package.json
```
  —— PrimeVue版本、依赖项
代码库模式：
- 现有“合规”组件作为隐式规范
- 路由配置用于路径到组件的映射

Input Modes

输入模式

The skill accepts three types of input, all converging to the same pipeline:

该技能支持三种输入类型，最终都会进入同一处理流程：

URL Mode

URL模式

/design-compliance http://localhost:5173/hexagone-etab/vue/patients

Use the URL directly for visual inspection
Reverse-map the URL path to a route in the router config
Find the component file for that route
Recursively resolve all local imports

/design-compliance http://localhost:5173/hexagone-etab/vue/patients

直接使用URL进行可视化检查
将URL路径反向映射到路由配置中的对应路由
查找该路由对应的组件文件
递归解析所有本地导入

Component Name Mode

组件名模式

/design-compliance PatientDashboard

Glob for matching files:

**/PatientDashboard.vue

**/patient-dashboard.vue

**/PatientDashboard/**

If multiple matches, review all of them
For each matched component, resolve the route it belongs to (if any) for visual inspection
Recursively resolve all local imports

/design-compliance PatientDashboard

全局搜索匹配文件：

**/PatientDashboard.vue

、

**/patient-dashboard.vue

、

**/PatientDashboard/**

如果有多个匹配项，全部评审
对每个匹配的组件，解析其所属路由（如果存在）用于可视化检查
递归解析所有本地导入

Page Name Mode

页面名模式

/design-compliance Patients

Search the router configuration files for a route named "Patients" or with path
```
/patients
```
Find the component assigned to that route
Construct the URL for visual inspection
Recursively resolve all local imports

/design-compliance Patients

在路由配置文件中搜索名为"Patients"或路径为
```
/patients
```
的路由
查找该路由关联的组件
构造URL用于可视化检查
递归解析所有本地导入

No Argument

无参数

/design-compliance

Ask the user what to review. Do not assume.

/design-compliance

询问用户需要评审的内容，不得自行假设。

Workflow

工作流程

Step 1: Discover Source of Truth

步骤1：拉取规则源

Read explicit rules files (if they exist in the project):
- Glob for
```
**/CLAUDE.md
```
  ,
```
**/design-system.md
```
  ,
```
**/design-rules.md
```
- Glob for
```
.github/copilot-instructions.md
```
  ,
```
.github/instructions/*.md
```
- Extract design system rules, anti-patterns, token conventions
Read framework configuration:
- Find and read the PrimeVue preset file (usually
```
**/hexagone-preset.js
```
  or
```
**/theme/*.js
```
  )
- Find and read shell tokens (usually
```
**/shell-tokens.scss
```
  )
- Read
```
package.json
```
  to confirm PrimeVue version and dependencies
- Read Tailwind config if present
Build the merged ruleset — combine all sources into a single checklist of rules to enforce

读取显式规则文件（如果项目中存在）：
- 全局搜索
```
**/CLAUDE.md
```
  、
```
**/design-system.md
```
  、
```
**/design-rules.md
```
- 全局搜索
```
.github/copilot-instructions.md
```
  、
```
.github/instructions/*.md
```
- 提取设计系统规则、反模式、令牌规范
读取框架配置：
- 查找并读取PrimeVue预设文件（通常为
```
**/hexagone-preset.js
```
  或
```
**/theme/*.js
```
  ）
- 查找并读取shell层令牌（通常为
```
**/shell-tokens.scss
```
  ）
- 读取
```
package.json
```
  确认PrimeVue版本和依赖项
- 如果存在Tailwind配置则读取
构建合并规则集——将所有来源的规则合并为单一的待执行规则检查清单

Step 2: Resolve Target Files

步骤2：解析目标文件

Based on the input mode:

Parse the user's input to determine the mode (URL, component name, or page name)
Find the entry-point file(s):
- URL → parse the path, search router files (
```
**/router/**/*.{js,ts}
```
  ,
```
**/router.{js,ts}
```
  ) for matching route, get the component
- Component name → glob for
```
**/<name>.vue
```
  ,
```
**/<name-kebab>.vue
```
  ,
```
**/<Name>/**
```
- Page name → search router config for route name or path match
Recursively resolve the component tree:
- Read each
```
.vue
```
  file
- Extract all local imports (skip
```
primevue/*
```
  ,
```
vue
```
  ,
```
vue-router
```
  ,
```
pinia
```
  ,
```
node_modules
```
  )
- Follow each import to its file, repeat until no new local components are found
- Build the full file list to review

Report the discovered tree to the user:

Found 12 files in component tree for PatientDashboard:
- frontend/gap-mf/src/views/PatientDashboard.vue (entry)
- frontend/gap-mf/src/components/PatientHeader.vue
- frontend/gap-mf/src/components/PatientTimeline.vue
- ...

基于输入模式执行：

解析用户输入确定模式（URL、组件名或页面名）
查找入口文件：
- URL → 解析路径，在路由文件（
```
**/router/**/*.{js,ts}
```
  、
```
**/router.{js,ts}
```
  ）中搜索匹配路由，获取对应组件
- 组件名 → 全局搜索
```
**/<name>.vue
```
  、
```
**/<name-kebab>.vue
```
  、
```
**/<Name>/**
```
- 页面名 → 在路由配置中搜索匹配的路由名或路径
递归解析组件树：
- 读取每个
```
.vue
```
  文件
- 提取所有本地导入（跳过
```
primevue/*
```
  、
```
vue
```
  、
```
vue-router
```
  、
```
pinia
```
  、
```
node_modules
```
  ）
- 追踪每个导入对应的文件，重复直到没有新的本地组件被发现
- 构建完整的待评审文件列表

向用户上报发现的组件树：

Found 12 files in component tree for PatientDashboard:
- frontend/gap-mf/src/views/PatientDashboard.vue (entry)
- frontend/gap-mf/src/components/PatientHeader.vue
- frontend/gap-mf/src/components/PatientTimeline.vue
- ...

Step 3: Static Code Analysis

步骤3：静态代码分析

For each file in the component tree, check ALL violation categories:

对组件树中的每个文件，检查所有违规类别：

Category 1: Wrong Component

类别1：错误组件

Raw

<button>

<input>

<select>

<textarea>

<table>

when PrimeVue equivalents exist

```
<btn>
```
,
```
<alert>
```
,
```
<card>
```
,
```
<action>
```
,
```
<spinner>
```
(hexa-compat) — should be PrimeVue native
Any hexa-components (
```
<datepicker>
```
,
```
<data-table>
```
,
```
<modal>
```
, etc.) — should be PrimeVue native
Fix: replace with the correct PrimeVue component, update imports, adapt props/slots

存在PrimeVue等效组件时使用原生
```
<button>
```
、
```
<input>
```
、
```
<select>
```
、
```
<textarea>
```
、
```
<table>
```
使用
```
<btn>
```
、
```
<alert>
```
、
```
<card>
```
、
```
<action>
```
、
```
<spinner>
```
（hexa-compat组件）——应替换为PrimeVue原生组件
使用任意hexa组件（
```
<datepicker>
```
、
```
<data-table>
```
、
```
<modal>
```
等）——应替换为PrimeVue原生组件
修复方案：替换为正确的PrimeVue组件，更新导入，适配props/slots

Category 2: Wrong Token Layer

类别2：错误令牌层级

Hardcoded colors:
```
#xxx
```
,
```
rgb(...)
```
,
```
hsl(...)
```
in
```
<style>
```
or inline styles
beta-scss classes:
```
text:teal
```
,
```
bg:grey-lightest
```
,
```
flex:6/12
```
, etc. in templates
```
--hexa-*
```
tokens used outside shell components (Header, Sidebar, Navigation)
Arbitrary Tailwind values:
```
text-[#ff0000]
```
,
```
bg-[rgb(...)]
```
,
```
p-[17px]
```
Fix: replace with
```
var(--p-*)
```
tokens, Tailwind theme classes, or
```
dt()
```
overrides

```
<style>
```
或内联样式中使用硬编码颜色：
```
#xxx
```
、
```
rgb(...)
```
、
```
hsl(...)
```
模板中使用beta-scss类名：
```
text:teal
```
、
```
bg:grey-lightest
```
、
```
flex:6/12
```
等
Shell组件外（Header、Sidebar、Navigation）使用
```
--hexa-*
```
令牌
使用Tailwind任意值：
```
text-[#ff0000]
```
、
```
bg-[rgb(...)]
```
、
```
p-[17px]
```
修复方案：替换为
```
var(--p-*)
```
令牌、Tailwind主题类或
```
dt()
```
覆盖

Category 3:

pt

Misuse

类别3：

pt

滥用

pt

prop used for visual styling:

border

shadow

padding

margin

background

color

font-size

border-radius

Fix: move visual overrides to
```
dt
```
prop or
```
<style scoped>
```
with tokens

将

pt

属性用于视觉样式：

border

、

shadow

、

padding

、

margin

、

background

、

color

、

font-size

、

border-radius

修复方案：将视觉覆盖移动到
```
dt
```
属性或使用令牌的
```
<style scoped>
```
块中

Category 4: Import Violations

类别4：导入违规

Uppercase PrimeVue imports:
```
primevue/InputText
```
→
```
primevue/inputtext
```

v3 component names:

Dropdown

→

Select

Calendar

→

DatePicker

InputSwitch

→

ToggleSwitch

OverlayPanel

→

Popover

TabView

TabPanel

→

Tabs

TabList

Tab

TabPanels

TabPanel

Chips

→

InputChips

Named imports from

primevue

barrel:

import { InputText } from "primevue"

→ default import

Fix: rewrite the import statement, update component registration and template usage

PrimeVue导入首字母大写：
```
primevue/InputText
```
→
```
primevue/inputtext
```

使用v3组件名：

Dropdown

→

Select

、

Calendar

→

DatePicker

、

InputSwitch

→

ToggleSwitch

、

OverlayPanel

→

Popover

、

TabView

TabPanel

→

Tabs

TabList

Tab

TabPanels

TabPanel

、

Chips

→

InputChips

从
```
primevue
```
barrel导入命名导出：
```
import { InputText } from "primevue"
```
→ 改为默认导入
修复方案：重写导入语句，更新组件注册和模板使用方式

Category 5: Dark Mode Violations

类别5：暗色模式违规

```
:global(.p-dark)
```
nested inside
```
<style scoped>
```
— must use a separate unscoped
```
<style>
```
block
Hardcoded light-only colors without dark mode variant
Fix: move dark mode styles to a separate
```
<style>
```
block, use tokens that auto-switch

```
<style scoped>
```
内部嵌套
```
:global(.p-dark)
```
——必须使用单独的非作用域
```
<style>
```
块
硬编码仅亮色模式的颜色，无暗色模式变体
修复方案：将暗色模式样式移动到单独的
```
<style>
```
块，使用可自动切换的令牌

Category 6: i18n Violations

类别6：i18n违规

Hardcoded text strings in templates (labels, placeholders, titles, messages, error text)
Exceptions: single characters (
```
/
```
,
```
|
```
,
```
:
```
,
```
-
```
), numbers, CSS class names, prop values that are not user-visible
Fix: extract to locale file, replace with
```
t('key')
```
(Composition API) or
```
$t('key')
```
(Options API)

模板中存在硬编码文本字符串（标签、占位符、标题、消息、错误文本）
例外情况：单个字符（
```
/
```
、
```
|
```
、
```
:
```
、
```
-
```
）、数字、CSS类名、对用户不可见的prop值
修复方案：提取到国际化文件，替换为
```
 t('key')
```
（Composition API）或
```
$t('key')
```
（Options API）

Category 7: Accessibility

类别7：无障碍问题

```
<button>
```
or PrimeVue
```
Button
```
with only an icon and no
```
aria-label
```
Form fields without associated
```
<label>
```
(no
```
for
```
/
```
id
```
pair, no
```
FloatLabel
```
wrapper)
Context menus (right-click handlers) — app must work on tablets
Hover-only interactions (
```
@mouseenter
```
/
```
@mouseleave
```
without click alternative)
Missing
```
alt
```
on
```
<img>
```
tags
Fix: add
```
aria-label
```
, wrap in
```
FloatLabel
```
, replace hover with click, add
```
alt
```
text

```
<button>
```
或PrimeVue
```
Button
```
仅包含图标，无
```
aria-label
```
表单字段无关联
```
<label>
```
（无
```
for
```
/
```
id
```
配对，无
```
FloatLabel
```
包裹）
存在右键菜单（右键点击 handler）——应用必须支持平板设备使用
仅支持 hover 交互（
```
@mouseenter
```
/
```
@mouseleave
```
无点击备选方案）
```
<img>
```
标签缺失
```
alt
```
属性
修复方案：添加
```
aria-label
```
、用
```
FloatLabel
```
包裹、将hover交互替换为点击、添加
```
alt
```
文本

Category 8: Framework Conventions

类别8：框架规范违规

Options API (

export default { data(), methods, computed }

) instead of

<script setup lang="ts">

Missing
```
lang="ts"
```
on
```
<script setup>
```
Vuex/pathify usage instead of Pinia

this.$store

mapState

mapGetters

mapActions

instead of Pinia

useXxxStore()

Inline styles (
```
style="..."
```
) instead of Tailwind classes or scoped CSS with tokens
```
!important
```
in new code (acceptable only to counter beta-scss legacy conflicts)
Fix: rewrite to Composition API with
```
<script setup lang="ts">
```
, migrate state to Pinia, replace inline styles

使用Options API（

export default { data(), methods, computed }

）而非

<script setup lang="ts">

```
<script setup>
```
缺失
```
lang="ts"
```
属性
使用Vuex/pathify而非Pinia

使用

this.$store

mapState

mapGetters

mapActions

而非Pinia的

useXxxStore()

使用内联样式（
```
style="..."
```
而非Tailwind类或带令牌的作用域CSS
新代码中使用
```
!important
```
（仅在解决beta-scss遗留冲突时可接受）
修复方案：重写为带
```
<script setup lang="ts">
```
的Composition API，将状态迁移到Pinia，替换内联样式

Step 4: Visual Inspection

步骤4：可视化检查

Prerequisite: Check if a dev server is running by probing common ports (5173, 5174, 3000, 8080).

If no dev server is detected, skip visual inspection entirely and proceed to Step 5 with code-only results.

If a dev server is running:

前置条件：通过探测常用端口（5173、5174、3000、8080）检查开发服务器是否运行。

如果未检测到开发服务器，完全跳过可视化检查，仅基于代码分析结果进入步骤5。

如果开发服务器正在运行：

4a. Navigate to the Page

4a. 导航到目标页面

Determine the URL:
- If the user provided a URL, use it directly
- If a component/page name was provided, construct the URL from the route config
- If the route cannot be determined, skip visual inspection
Open the page in a headless browser (Playwright)
Handle authentication:
- If a login page is detected (look for login form,
```
/login
```
  redirect), authenticate:
  - Username:
```
apvhn
```
  - Password:
```
apvhn
```
- After login, navigate to the target page

确定URL：
- 如果用户提供了URL，直接使用
- 如果提供了组件/页面名，从路由配置构造URL
- 如果无法确定路由，跳过可视化检查
在无头浏览器（Playwright）中打开页面
处理身份验证：
- 如果检测到登录页面（查找登录表单、
```
/login
```
  重定向），执行认证：
  - 用户名：
```
apvhn
```
  - 密码：
```
apvhn
```
- 登录后导航到目标页面

4b. Light Mode Inspection

4b. 亮色模式检查

Take a full-page screenshot
Analyze computed styles on key elements:
- Check for hardcoded colors not matching
```
--p-*
```
  token values
- Check for non-standard spacing (values that don't align with the Tailwind spacing scale)
- Check for inconsistent border-radius across sibling elements
Visual heuristics:
- Misaligned elements (inconsistent padding/margins between siblings)
- Broken or inconsistent responsive behavior
- Elements overflowing their containers
- Inconsistent font sizes within the same context

截取全页面截图
分析关键元素的计算样式：
- 检查硬编码颜色是否不匹配
```
--p-*
```
  令牌值
- 检查非标准间距（值不符合Tailwind间距标尺）
- 检查同级元素之间的border-radius不一致问题
可视化启发式检查：
- 元素对齐错误（同级元素之间padding/margin不一致）
- 响应式行为损坏或不一致
- 元素溢出容器
- 同上下文内字体大小不一致

4c. Dark Mode Inspection

4c. 暗色模式检查

Toggle dark mode: execute

document.documentElement.classList.add('p-dark')

in the browser

Take a second full-page screenshot
Check for:
- Elements with hardcoded light colors that don't adapt (white backgrounds, dark text on dark bg)
- ```
--hexa-*
```
  tokens not switching correctly
- Contrast issues (text unreadable against background)
- Visual artifacts from non-token-based styling

切换暗色模式：在浏览器中执行

document.documentElement.classList.add('p-dark')

截取第二张全页面截图
检查以下问题：
- 硬编码亮色不自动适配的元素（白色背景、暗色背景上的深色文本）
- ```
--hexa-*
```
  令牌未正确切换
- 对比度问题（文本在背景上不可读）
- 非基于令牌的样式导致的视觉异常

4d. Capture Results

4d. 捕获结果

Compile all visual issues with:

Element selector or description
Issue description
Severity (P1: broken/unreadable, P2: inconsistent, P3: minor polish)

汇总所有视觉问题，包含：

元素选择器或描述
问题描述
严重程度（P1：损坏/不可读，P2：不一致，P3： minor优化）

Step 5: Auto-Fix All Violations

步骤5：自动修复所有违规项

For every violation found (code + visual):

Prioritize fixes: P1 (broken) → P2 (inconsistent) → P3 (polish)
Edit files in place using the Edit tool
Respect existing patterns: when fixing, match the style of surrounding code
Handle cascading fixes: if replacing a component changes its API (props, slots, events), update all usages in the template
Update imports: add new PrimeVue imports, remove unused ones
Do NOT commit — leave changes unstaged for the developer to review

对所有发现的违规项（代码+视觉）：

修复优先级：P1（损坏）→ P2（不一致）→ P3（优化）
使用编辑工具就地修改文件
尊重现有模式：修复时匹配周边代码的风格
处理级联修复：如果替换组件导致API（props、slots、events）变化，更新模板中所有使用处
更新导入：添加新的PrimeVue导入，移除未使用的导入
不要提交——将更改保留为未暂存状态，供开发者审核

Step 6: Generate Report

步骤6：生成报告

Print a structured report to the terminal:

markdown

undefined

向终端输出结构化报告：

markdown

undefined

Design Compliance Report

设计合规性报告

Target: [component/page name or URL] Files analyzed: [count] Violations found: [count] Violations fixed: [count] Visual inspection: [performed (light + dark) / skipped (no dev server)]

目标： [组件/页面名或URL] 分析文件数： [count] 发现违规数： [count] 修复违规数： [count] 可视化检查： [已执行（亮色+暗色） / 已跳过（无开发服务器）]

Files in Component Tree

组件树文件列表

#	File	Violations
1	`frontend/gap-mf/src/views/PatientDashboard.vue`	5
2	`frontend/gap-mf/src/components/PatientHeader.vue`	2
...	...	...

#	文件	违规数
1	`frontend/gap-mf/src/views/PatientDashboard.vue`	5
2	`frontend/gap-mf/src/components/PatientHeader.vue`	2
...	...	...

Violations Fixed

已修复违规项

Category 1: Wrong Component ([count])

类别1：错误组件（[count]）

File	Line	Before	After
`PatientDashboard.vue`	42	`<button @click="save">`	`<Button @click="save" label="..." />`

文件	行号	修改前	修改后
`PatientDashboard.vue`	42	`<button @click="save">`	`<Button @click="save" label="..." />`

Category 2: Wrong Token Layer ([count])

类别2：错误令牌层级（[count]）

File	Line	Before	After
`PatientHeader.vue`	15	`color: #006875`	`color: var(--p-primary-500)`

文件	行号	修改前	修改后
`PatientHeader.vue`	15	`color: #006875`	`color: var(--p-primary-500)`

Category 3: pt Misuse ([count])

类别3：pt滥用（[count]）

...

Category 4: Import Violations ([count])

类别4：导入违规（[count]）

...

Category 5: Dark Mode Violations ([count])

类别5：暗色模式违规（[count]）

...

Category 6: i18n Violations ([count])

类别6：i18n违规（[count]）

...

Category 7: Accessibility ([count])

类别7：无障碍问题（[count]）

...

Category 8: Framework Conventions ([count])

类别8：框架规范违规（[count]）

...

Visual Inspection Results

可视化检查结果

[If performed]

[如果执行了检查]

Light Mode

亮色模式

[Issue 1: description — severity]
[Issue 2: description — severity]

[问题1：描述 —— 严重程度]
[问题2：描述 —— 严重程度]

Dark Mode

暗色模式

[Issue 1: description — severity]
[Issue 2: description — severity]

[问题1：描述 —— 严重程度]
[问题2：描述 —— 严重程度]

Summary

汇总

Total violations: [count]
Auto-fixed: [count]
Remaining (manual review needed): [count, if any]

undefined

总违规数： [count]
自动修复数： [count]
剩余待手动审核： [count, 如果存在]

undefined

Violation Reference

违规参考

PrimeVue v3 → v4 Renamed Components

PrimeVue v3 → v4 重命名组件

v3 (FORBIDDEN)	v4 (CORRECT)	Import Path
`Dropdown`	`Select`	`primevue/select`
`Calendar`	`DatePicker`	`primevue/datepicker`
`InputSwitch`	`ToggleSwitch`	`primevue/toggleswitch`
`OverlayPanel`	`Popover`	`primevue/popover`
`TabView` / `TabPanel`	`Tabs` / `TabList` / `Tab` / `TabPanels` / `TabPanel`	`primevue/tabs` , etc.
`Chips`	`InputChips`	`primevue/inputchips`

v3（已禁用）	v4（正确）	导入路径
`Dropdown`	`Select`	`primevue/select`
`Calendar`	`DatePicker`	`primevue/datepicker`
`InputSwitch`	`ToggleSwitch`	`primevue/toggleswitch`
`OverlayPanel`	`Popover`	`primevue/popover`
`TabView` / `TabPanel`	`Tabs` / `TabList` / `Tab` / `TabPanels` / `TabPanel`	`primevue/tabs` 等
`Chips`	`InputChips`	`primevue/inputchips`

HTML → PrimeVue Mapping

HTML → PrimeVue 映射

Raw HTML	PrimeVue Replacement
`<button>`	`<Button>` from `primevue/button`
`<input type="text">`	`<InputText>` from `primevue/inputtext`
`<input type="checkbox">`	`<Checkbox :binary="true">` from `primevue/checkbox`
`<input type="radio">`	`<RadioButton>` from `primevue/radiobutton`
`<select>`	`<Select>` from `primevue/select`
`<textarea>`	`<Textarea>` from `primevue/textarea`
`<table>`	`<DataTable>` + `<Column>` from `primevue/datatable` , `primevue/column`
`<dialog>`	`<Dialog>` from `primevue/dialog`
`<progress>`	`<ProgressBar>` from `primevue/progressbar`

原生HTML	PrimeVue替换组件
`<button>`	`primevue/button` 导出的 `<Button>`
`<input type="text">`	`primevue/inputtext` 导出的 `<InputText>`
`<input type="checkbox">`	`primevue/checkbox` 导出的 `<Checkbox :binary="true">`
`<input type="radio">`	`primevue/radiobutton` 导出的 `<RadioButton>`
`<select>`	`primevue/select` 导出的 `<Select>`
`<textarea>`	`primevue/textarea` 导出的 `<Textarea>`
`<table>`	`primevue/datatable` 、 `primevue/column` 导出的 `<DataTable>` + `<Column>`
`<dialog>`	`primevue/dialog` 导出的 `<Dialog>`
`<progress>`	`primevue/progressbar` 导出的 `<ProgressBar>`

hexa-compat → PrimeVue Mapping

hexa-compat → PrimeVue 映射

hexa-compat	PrimeVue Native
`<btn severity="...">`	`<Button severity="...">` from `primevue/button`
`<alert color="red">`	`<Message severity="error">` from `primevue/message`
`<card>`	`<Card>` from `primevue/card`
`<action @click>`	`<Button link @click>` from `primevue/button`
`<spinner>`	`<ProgressSpinner>` from `primevue/progressspinner`
`<modal>`	`<Dialog>` from `primevue/dialog`

hexa-compat组件	PrimeVue原生组件
`<btn severity="...">`	`primevue/button` 导出的 `<Button severity="...">`
`<alert color="red">`	`primevue/message` 导出的 `<Message severity="error">`
`<card>`	`primevue/card` 导出的 `<Card>`
`<action @click>`	`primevue/button` 导出的 `<Button link @click>`
`<spinner>`	`primevue/progressspinner` 导出的 `<ProgressSpinner>`
`<modal>`	`primevue/dialog` 导出的 `<Dialog>`

Token Layer Rules

令牌层级规则

Context	Allowed	Forbidden
Business pages (views, components)	`var(--p-*)` , Tailwind classes, `dt()`	`var(--hexa-*)` , beta-scss classes, hardcoded colors
Shell components (Header, Sidebar, Nav)	`var(--hexa-)` , `var(--p-)`	beta-scss classes, hardcoded colors
New code (any)	Tailwind CSS 4 classes, `var(--p-*)` tokens	beta-scss classes, inline styles, `!important`

上下文	允许使用	禁止使用
业务页面（视图、组件）	`var(--p-*)` 、Tailwind类、 `dt()`	`var(--hexa-*)` 、beta-scss类、硬编码颜色
Shell组件（Header、Sidebar、Nav）	`var(--hexa-)` 、 `var(--p-)`	beta-scss类、硬编码颜色
新代码（任意位置）	Tailwind CSS 4类、 `var(--p-*)` 令牌	beta-scss类、内联样式、 `!important`

beta-scss → Modern Equivalents

beta-scss → 现代等效替换

beta-scss Class	Tailwind / Token Replacement
`text:teal`	`text-primary-500` or `var(--p-primary-500)`
`bg:grey-lightest`	`bg-surface-50` or `var(--p-surface-50)`
`bg:teal-dark`	`var(--hexa-chrome-bg-accent)` (shell only)
`bg:orange`	`var(--hexa-nav-bg)` (shell only)
`flex:X/12`	Tailwind grid or `w-{fraction}`
`p:1` , `m:1` , `pt:1`	Tailwind `p-4` , `m-4` , `pt-4`
`text:bold`	`font-bold`
`text:center`	`text-center`
`border`	`border`
`rounded:1/2`	`rounded-md` or `var(--p-content-border-radius)`
`w:full`	`w-full`

beta-scss类名	Tailwind / 令牌替换
`text:teal`	`text-primary-500` 或 `var(--p-primary-500)`
`bg:grey-lightest`	`bg-surface-50` 或 `var(--p-surface-50)`
`bg:teal-dark`	`var(--hexa-chrome-bg-accent)` （仅shell层使用）
`bg:orange`	`var(--hexa-nav-bg)` （仅shell层使用）
`flex:X/12`	Tailwind grid或 `w-{fraction}`
`p:1` 、 `m:1` 、 `pt:1`	Tailwind `p-4` 、 `m-4` 、 `pt-4`
`text:bold`	`font-bold`
`text:center`	`text-center`
`border`	`border`
`rounded:1/2`	`rounded-md` 或 `var(--p-content-border-radius)`
`w:full`	`w-full`

Edge Cases

边缘情况

No Files Found

未找到文件

If the glob/search finds no matching files:

Tell the user: "No files found matching '[input]'. Try a URL, a .vue component name, or a route path."
Stop

如果全局搜索未找到匹配文件：

告知用户："未找到匹配'[input]'的文件。请尝试输入URL、.vue组件名或路由路径。"
终止执行

Dev Server Not Running

开发服务器未运行

Skip visual inspection entirely
Run code-only analysis and auto-fixes
Note in the report: "Visual inspection skipped — no dev server detected on ports 5173, 5174, 3000, 8080"

完全跳过可视化检查
仅执行代码分析和自动修复
在报告中注明："可视化检查已跳过——未在端口5173、5174、3000、8080上检测到开发服务器"

Authentication Fails

身份验证失败

If login with
```
apvhn
```
/
```
apvhn
```
fails, skip visual inspection
Note in the report: "Visual inspection skipped — authentication failed"
Continue with code-only analysis

如果使用
```
apvhn
```
/
```
apvhn
```
登录失败，跳过可视化检查
在报告中注明："可视化检查已跳过——身份验证失败"
继续执行代码分析

Large Component Tree (20+ files)

大型组件树（20+文件）

Process all files — do not skip or sample
Organize the report by file for readability
Use parallel sub-agents if the tree exceeds 10 files (one sub-agent per batch of 5 files)

处理所有文件——不得跳过或抽样
报告按文件分类提升可读性
如果组件树超过10个文件可使用并行子Agent（每5个文件分配一个子Agent）

Mixed MF Files

跨微前端文件

If the component tree spans multiple micro-frontends (e.g., shared package imports):

Apply the same single standard to all files
Note in the report which MF each file belongs to

如果组件树跨多个微前端（例如共享包导入）：

对所有文件应用同一标准
在报告中注明每个文件所属的微前端

File Already Compliant

文件已合规

If a file has zero violations:

Include it in the file list with "0 violations"
Do not edit it

如果文件零违规：

在文件列表中标注"0违规"
不修改该文件

Important Notes

重要注意事项

This skill modifies files. It edits
```
.vue
```
files in place to fix violations. Changes are NOT committed.
The developer reviews the diff. After the skill runs, the developer should
```
git diff
```
to verify all changes.
i18n keys: when extracting hardcoded text, use descriptive dot-notation keys matching the component name and context (e.g.,
```
patientDashboard.title
```
,
```
patientHeader.saveButton
```
)
PrimeVue docs: for component API details, fetch
```
https://primevue.org/<component>.md
```
Recursive resolution stops at:
```
primevue/*
```
,
```
vue
```
,
```
vue-router
```
,
```
pinia
```
,
```
@vueuse/*
```
,
```
node_modules
```
,
```
@hexagone/shared
```
(treat shared package as a library boundary)
Shell components (Header, Sidebar, Navigation, Breadcrumbs) are allowed to use
```
--hexa-*
```
tokens — do not flag these

该技能会修改文件：它会就地编辑
```
.vue
```
文件修复违规项，更改不会被提交。
开发者需要审核diff：技能执行完成后，开发者应执行
```
git diff
```
验证所有更改。
i18n键名：提取硬编码文本时，使用匹配组件名和上下文的描述性点分隔键名（例如
```
patientDashboard.title
```
、
```
patientHeader.saveButton
```
）
PrimeVue文档：如需组件API详情，拉取
```
https://primevue.org/<component>.md
```
递归解析终止边界：
```
primevue/*
```
、
```
vue
```
、
```
vue-router
```
、
```
pinia
```
、
```
@vueuse/*
```
、
```
node_modules
```
、
```
@hexagone/shared
```
（将共享包视为库边界）
Shell组件（Header、Sidebar、Navigation、Breadcrumbs）允许使用
```
--hexa-*
```
令牌——不要标记此类使用为违规