design-compliance

What this skill does

# 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.

## 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

## Core Principles

### 1. Full Autonomy
- 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

### 2. Single Standard (No Per-MF Exceptions)
- **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)

### 3. Hexagone-Specific
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

### 4. Fix Everything
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:

1. **Explicit rules files** (override everything if present):
   - `design-system.md` or `docs/design-system/design-rules.md`
   - `CLAUDE.md` (root and per-MF)
   - `.github/copilot-instructions.md` or `.github/instructions/*.md`

2. **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

3. **Codebase patterns**:
   - Existing "good" components as implicit conventions
   - Router configuration for route-to-component mapping

## Input Modes

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

### URL Mode
```
/design-compliance http://localhost:5173/hexagone-etab/vue/patients
```
1. Use the URL directly for visual inspection
2. Reverse-map the URL path to a route in the router config
3. Find the component file for that route
4. Recursively resolve all local imports

### Component Name Mode
```
/design-compliance PatientDashboard
```
1. Glob for matching files: `**/PatientDashboard.vue`, `**/patient-dashboard.vue`, `**/PatientDashboard/**`
2. If multiple matches, review all of them
3. For each matched component, resolve the route it belongs to (if any) for visual inspection
4. Recursively resolve all local imports

### Page Name Mode
```
/design-compliance Patients
```
1. Search the router configuration files for a route named "Patients" or with path `/patients`
2. Find the component assigned to that route
3. Construct the URL for visual inspection
4. Recursively resolve all local imports

### No Argument
```
/design-compliance
```
Ask the user what to review. Do not assume.

## 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

2. **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

3. **Build the merged ruleset** — combine all sources into a single checklist of rules to enforce

### Step 2: Resolve Target Files

Based on the input mode:

1. **Parse the user's input** to determine the mode (URL, component name, or page name)

2. **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

3. **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

4. **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
   - ...
   ```

### Step 3: Static Code Analysis

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

#### Category 1: Wrong Component
- 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

#### Category 2: Wrong Token Layer
- 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

#### Category 3: `pt` Misuse
- `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

#### Category 4: Import Violations
- 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

#### Category 5: Dark Mode Violations
- `: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

#### Category 6: i18n Violations
- 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)

#### Category 7: Accessibility
- `<butt