@polymorphism-tech/morph-spec 4.8.12 → 4.8.15

package/framework/skills/level-0-meta/frontend-review/scripts/scan-accessibility.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+/**
+ * scan-accessibility.mjs
+ *
+ * Scans .tsx/.ts (Next.js) and .razor (Blazor) files for static accessibility violations.
+ * Executed locally by Claude via Bash — output returned to Claude.
+ *
+ * Usage:
+ *   node scan-accessibility.mjs [path]      # scan directory or file (default: '.')
+ *   node scan-accessibility.mjs src/        # scan src/ recursively
+ *   node scan-accessibility.mjs --summary   # counts only, no details
+ *
+ * Checks (7 total):
+ *   IMG_MISSING_ALT         CRITICAL  .tsx/.razor  <img without alt= attribute
+ *   INPUT_MISSING_LABEL     HIGH      .tsx/.razor  <input without associated label or aria-label
+ *                                                  <InputText/<FluentTextField without Label=
+ *   HEADING_HIERARCHY       HIGH      .tsx/.razor  Heading level skip (H1→H3 skipping H2)
+ *   LINK_NO_TEXT            HIGH      .tsx/.razor  <a> empty or icon-only without aria-label
+ *   BUTTON_NO_TEXT          HIGH      .tsx/.razor  <button>/<FluentButton> without accessible text
+ *   AUTOPLAY_MEDIA          MEDIUM    .tsx/.razor  <video>/<audio> with autoPlay without muted
+ *   FLUENT_CHECKBOX_NO_LABEL MEDIUM   .razor       <FluentCheckbox without Label=
+ *
+ * Output JSON: { summary: { scanned, findings, bySeverity, clean }, findings: [...] }
+ * Exit code: 1 if CRITICAL findings, 0 otherwise
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from 'fs';
+import { join, extname, relative } from 'path';
+
+const targetPath = process.argv[2] ?? '.';
+const summaryOnly = process.argv.includes('--summary');
+
+// ─── File collectors ────────────────────────────────────────────────────────
+
+const IGNORED_DIRS = ['node_modules', '.git', '.next', 'dist', 'build', '.turbo', 'bin', 'obj'];
+
+function collectFrontendFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const stat = statSync(dir);
+  if (stat.isFile()) {
+    const ext = extname(dir);
+    return ['.tsx', '.ts', '.razor'].includes(ext) ? [dir] : [];
+  }
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && !IGNORED_DIRS.includes(entry.name)) {
+      results.push(...collectFrontendFiles(join(dir, entry.name)));
+    } else if (entry.isFile()) {
+      const ext = extname(entry.name);
+      if (['.tsx', '.ts', '.razor'].includes(ext)) {
+        results.push(join(dir, entry.name));
+      }
+    }
+  }
+  return results;
+}
+
+// ─── Checks ─────────────────────────────────────────────────────────────────
+
+/**
+ * Check: IMG_MISSING_ALT — CRITICAL
+ * Detect <img without alt= in .tsx and .razor files.
+ * Matches both JSX <img ... /> and HTML <img ...> forms.
+ */
+function checkImgMissingAlt(content, lines, relFile, findings) {
+  // Match <img tags that do NOT contain alt=
+  const imgRegex = /<img\b([^>]*?)(?:\/>|>)/g;
+  let match;
+  while ((match = imgRegex.exec(content)) !== null) {
+    const attrs = match[1];
+    if (!/\balt\s*=/i.test(attrs)) {
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: 'CRITICAL',
+        id: 'IMG_MISSING_ALT',
+        file: relFile,
+        line: lineNum,
+        message: '<img> element missing alt attribute — required for screen readers',
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+}
+
+/**
+ * Check: INPUT_MISSING_LABEL — HIGH
+ * Detect <input>, <InputText>, <FluentTextField without accessible label.
+ * Accepts: aria-label=, aria-labelledby=, or associated <label for=
+ * For Blazor: Label= attribute on <InputText> and <FluentTextField>
+ */
+function checkInputMissingLabel(content, lines, relFile, findings) {
+  const isRazor = relFile.endsWith('.razor');
+
+  // --- Standard <input> (both tsx and razor HTML sections) ---
+  const inputRegex = /<input\b([^>]*?)(?:\/>|>)/g;
+  let match;
+  while ((match = inputRegex.exec(content)) !== null) {
+    const attrs = match[1];
+    // Skip hidden inputs — they don't need labels
+    if (/type\s*=\s*['"]hidden['"]/i.test(attrs)) continue;
+    const hasLabel =
+      /\baria-label\s*=/i.test(attrs) ||
+      /\baria-labelledby\s*=/i.test(attrs) ||
+      /\bid\s*=\s*['"]([^'"]+)['"]/i.test(attrs); // id present → could be associated by <label for>
+    if (!hasLabel) {
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: 'HIGH',
+        id: 'INPUT_MISSING_LABEL',
+        file: relFile,
+        line: lineNum,
+        message: '<input> element missing accessible label (aria-label, aria-labelledby, or <label for=)',
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+
+  if (isRazor) {
+    // --- Blazor <InputText> without Label= ---
+    const inputTextRegex = /<InputText\b([^>]*?)(?:\/>|>)/g;
+    while ((match = inputTextRegex.exec(content)) !== null) {
+      const attrs = match[1];
+      if (!/\bLabel\s*=/i.test(attrs) && !/\baria-label\s*=/i.test(attrs)) {
+        const lineNum = content.slice(0, match.index).split('\n').length;
+        findings.push({
+          severity: 'HIGH',
+          id: 'INPUT_MISSING_LABEL',
+          file: relFile,
+          line: lineNum,
+          message: '<InputText> component missing Label= attribute (or aria-label)',
+          snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+        });
+      }
+    }
+
+    // --- Fluent UI <FluentTextField> without Label= ---
+    const fluentTextRegex = /<FluentTextField\b([^>]*?)(?:\/>|>)/g;
+    while ((match = fluentTextRegex.exec(content)) !== null) {
+      const attrs = match[1];
+      if (!/\bLabel\s*=/i.test(attrs) && !/\baria-label\s*=/i.test(attrs)) {
+        const lineNum = content.slice(0, match.index).split('\n').length;
+        findings.push({
+          severity: 'HIGH',
+          id: 'INPUT_MISSING_LABEL',
+          file: relFile,
+          line: lineNum,
+          message: '<FluentTextField> component missing Label= attribute (or aria-label)',
+          snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Check: HEADING_HIERARCHY — HIGH
+ * Detect heading level skips (e.g. H1 → H3 without H2) within a file.
+ * Scans for h1–h6 / H1–H6 tags in order and reports any skip > 1 level.
+ */
+function checkHeadingHierarchy(content, lines, relFile, findings) {
+  // Collect all headings in document order
+  const headingRegex = /<[Hh]([1-6])\b/g;
+  const headings = [];
+  let match;
+  while ((match = headingRegex.exec(content)) !== null) {
+    headings.push({
+      level: parseInt(match[1], 10),
+      lineNum: content.slice(0, match.index).split('\n').length,
+    });
+  }
+
+  // Check for level skips
+  for (let i = 1; i < headings.length; i++) {
+    const prev = headings[i - 1];
+    const curr = headings[i];
+    // Only flag increases that skip a level (e.g. h1 → h3)
+    if (curr.level > prev.level + 1) {
+      findings.push({
+        severity: 'HIGH',
+        id: 'HEADING_HIERARCHY',
+        file: relFile,
+        line: curr.lineNum,
+        message: `Heading level skip: H${prev.level} (line ${prev.lineNum}) → H${curr.level} (line ${curr.lineNum}) — missing H${prev.level + 1}`,
+        snippet: lines[curr.lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+}
+
+/**
+ * Check: LINK_NO_TEXT — HIGH
+ * Detect <a> elements that are empty or contain only an icon without aria-label.
+ * Empty: <a href="..."></a> or <a .../>
+ * Icon-only: <a href="..."><SomeIcon /></a> or <a href="..."><i class="..."></i></a>
+ */
+function checkLinkNoText(content, lines, relFile, findings) {
+  // Match opening <a ...> tag and capture attributes, then check for aria-label
+  // We use a simplified approach: find <a> tags and look for aria-label in attrs
+  const linkRegex = /<a\b([^>]*?)>([\s\S]*?)<\/a>/g;
+  let match;
+  while ((match = linkRegex.exec(content)) !== null) {
+    const attrs = match[1];
+    const innerContent = match[2].trim();
+
+    // Has aria-label → OK
+    if (/\baria-label\s*=/i.test(attrs) || /\baria-labelledby\s*=/i.test(attrs)) continue;
+
+    // Check if inner content has visible text (not just whitespace, tags, or expressions)
+    // Strip JSX expressions {}, HTML tags, and whitespace
+    const textOnly = innerContent
+      .replace(/\{[^}]*\}/g, '')   // strip {expressions}
+      .replace(/<[^>]+>/g, '')      // strip HTML/JSX tags
+      .trim();
+
+    if (!textOnly) {
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: 'HIGH',
+        id: 'LINK_NO_TEXT',
+        file: relFile,
+        line: lineNum,
+        message: '<a> element has no accessible text — add aria-label or visible text content',
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+}
+
+/**
+ * Check: BUTTON_NO_TEXT — HIGH
+ * Detect <button> and <FluentButton> elements without accessible text or aria-label.
+ */
+function checkButtonNoText(content, lines, relFile, findings) {
+  // <button> elements
+  const buttonRegex = /<button\b([^>]*?)>([\s\S]*?)<\/button>/g;
+  let match;
+  while ((match = buttonRegex.exec(content)) !== null) {
+    const attrs = match[1];
+    const innerContent = match[2].trim();
+
+    if (/\baria-label\s*=/i.test(attrs) || /\baria-labelledby\s*=/i.test(attrs)) continue;
+
+    const textOnly = innerContent
+      .replace(/\{[^}]*\}/g, '')
+      .replace(/<[^>]+>/g, '')
+      .trim();
+
+    if (!textOnly) {
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: 'HIGH',
+        id: 'BUTTON_NO_TEXT',
+        file: relFile,
+        line: lineNum,
+        message: '<button> element has no accessible text — add aria-label or visible text content',
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+
+  // <FluentButton> (Blazor Fluent UI)
+  const fluentBtnRegex = /<FluentButton\b([^>]*?)>([\s\S]*?)<\/FluentButton>/g;
+  while ((match = fluentBtnRegex.exec(content)) !== null) {
+    const attrs = match[1];
+    const innerContent = match[2].trim();
+
+    if (/\baria-label\s*=/i.test(attrs) || /\bTitle\s*=/i.test(attrs)) continue;
+
+    const textOnly = innerContent
+      .replace(/\{[^}]*\}/g, '')
+      .replace(/<[^>]+>/g, '')
+      .trim();
+
+    if (!textOnly) {
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: 'HIGH',
+        id: 'BUTTON_NO_TEXT',
+        file: relFile,
+        line: lineNum,
+        message: '<FluentButton> has no accessible text — add aria-label, Title=, or visible text',
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+}
+
+/**
+ * Check: AUTOPLAY_MEDIA — MEDIUM
+ * Detect <video> or <audio> with autoPlay attribute but without muted.
+ * Autoplay without muted violates WCAG 1.4.2 (Audio Control).
+ */
+function checkAutoplayMedia(content, lines, relFile, findings) {
+  const mediaRegex = /<(video|audio)\b([^>]*?)(?:\/>|>)/gi;
+  let match;
+  while ((match = mediaRegex.exec(content)) !== null) {
+    const attrs = match[2];
+    // JSX: autoPlay (camelCase), HTML: autoplay
+    if (/\bautoPlay\b|\bautoplay\b/i.test(attrs) && !/\bmuted\b/i.test(attrs)) {
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: 'MEDIUM',
+        id: 'AUTOPLAY_MEDIA',
+        file: relFile,
+        line: lineNum,
+        message: `<${match[1]}> has autoPlay without muted — violates WCAG 1.4.2 (Audio Control)`,
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+}
+
+/**
+ * Check: FLUENT_CHECKBOX_NO_LABEL — MEDIUM
+ * Detect <FluentCheckbox without Label= in .razor files.
+ */
+function checkFluentCheckboxNoLabel(content, lines, relFile, findings) {
+  if (!relFile.endsWith('.razor')) return;
+
+  const checkboxRegex = /<FluentCheckbox\b([^>]*?)(?:\/>|>)/g;
+  let match;
+  while ((match = checkboxRegex.exec(content)) !== null) {
+    const attrs = match[1];
+    if (!/\bLabel\s*=/i.test(attrs) && !/\baria-label\s*=/i.test(attrs)) {
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: 'MEDIUM',
+        id: 'FLUENT_CHECKBOX_NO_LABEL',
+        file: relFile,
+        line: lineNum,
+        message: '<FluentCheckbox> missing Label= attribute — screen readers cannot identify this checkbox',
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+const files = collectFrontendFiles(targetPath);
+const findings = [];
+
+for (const file of files) {
+  const content = readFileSync(file, 'utf-8');
+  const lines = content.split('\n');
+  const relFile = relative(process.cwd(), file).replace(/\\/g, '/');
+
+  checkImgMissingAlt(content, lines, relFile, findings);
+  checkInputMissingLabel(content, lines, relFile, findings);
+  checkHeadingHierarchy(content, lines, relFile, findings);
+  checkLinkNoText(content, lines, relFile, findings);
+  checkButtonNoText(content, lines, relFile, findings);
+  checkAutoplayMedia(content, lines, relFile, findings);
+  checkFluentCheckboxNoLabel(content, lines, relFile, findings);
+}
+
+const bySeverity = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+for (const f of findings) {
+  bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
+}
+
+const summary = {
+  scanned: files.length,
+  findings: findings.length,
+  bySeverity,
+  clean: findings.length === 0,
+};
+
+if (summaryOnly) {
+  console.log(JSON.stringify(summary, null, 2));
+} else {
+  console.log(JSON.stringify({ summary, findings }, null, 2));
+}
+
+// Exit 1 if any CRITICAL findings
+process.exit(findings.some(f => f.severity === 'CRITICAL') ? 1 : 0);

package/framework/skills/level-0-meta/morph-checklist/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 # MORPH Checklists
 
-Types: `deploy`, `security`, `seo`, `performance`, `accessibility`, `legal-brazil`, `simulation` (see [simulation-checklist.md](simulation-checklist.md))
+Types: `deploy`, `security`, `seo`, `performance`, `accessibility`, `legal-brazil`, `simulation` (ver skill: `simulation-checklist`)
 
 ---
 

package/framework/skills/level-0-meta/morph-replicate/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: morph-replicate
 description: Simplified workflow for converting HTML prototypes into functional Blazor components, extracting design patterns and mapping HTML elements to Fluent UI/MudBlazor equivalents. Use when an approved HTML prototype exists and needs conversion to Blazor without a full MORPH-SPEC spec pipeline.
-user-invocable: false
+user-invocable: true
+argument-hint: "[feature-name] [prototype-path]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
-# Skill: /morph-replicate
+# MORPH Replicate — HTML to Blazor Conversion
 
 > Workflow simplificado para replicar prototipos HTML em Blazor.
 > Use quando tiver um prototipo HTML pronto e precisar converter para codigo Blazor funcional.
@@ -44,12 +45,13 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 3. **Gerar mapeamento HTML → Blazor:**
 
-   | HTML Pattern | Blazor Equivalente |
-   |--------------|-------------------|
-   | `<button class="btn-primary">` | `<FluentButton Appearance="Appearance.Accent">` |
-   | `<div class="card">` | `<FluentCard>` ou HTML customizado |
-   | `<input type="text">` | `<FluentTextField>` |
-   | `<div class="modal">` | Modal customizado (se design especifico) |
+   > Para tabela completa de mapeamentos, veja `references/blazor-html-mapping.md`
+
+   Documente os mapeamentos relevantes para este prototipo especifico:
+   ```markdown
+   ## Mapeamento HTML → Blazor (este prototipo)
+   - <elemento HTML> → <ComponenteBlazor>
+   ```
 
 4. **Gerar lista de classes CSS a criar:**
    ```markdown

package/framework/skills/level-0-meta/morph-replicate/references/blazor-html-mapping.md

@@ -0,0 +1,70 @@
+# HTML → Blazor Component Mapping Reference
+
+> Reference for converting HTML prototype elements to Fluent UI / MudBlazor equivalents.
+> Used during FASE 1 of the `/morph-replicate` workflow.
+
+## Common Component Mappings
+
+| HTML Pattern | Fluent UI Equivalent | MudBlazor Equivalent |
+|---|---|---|
+| `<button class="btn-primary">` | `<FluentButton Appearance="Appearance.Accent">` | `<MudButton Variant="Variant.Filled" Color="Color.Primary">` |
+| `<button class="btn-secondary">` | `<FluentButton Appearance="Appearance.Outline">` | `<MudButton Variant="Variant.Outlined">` |
+| `<div class="card">` | `<FluentCard>` | `<MudCard>` |
+| `<input type="text">` | `<FluentTextField>` | `<MudTextField>` |
+| `<input type="search">` | `<FluentSearch>` | `<MudTextField Adornment="Adornment.Start" AdornmentIcon="Icons.Material.Filled.Search">` |
+| `<select>` | `<FluentSelect>` | `<MudSelect>` |
+| `<input type="checkbox">` | `<FluentCheckbox>` | `<MudCheckBox>` |
+| `<input type="radio">` | `<FluentRadio>` | `<MudRadio>` |
+| `<div class="modal">` | `<FluentDialog>` | `<MudDialog>` |
+| `<nav>` / `<ul class="nav">` | `<FluentNavMenu>` | `<MudNavMenu>` |
+| `<table>` | `<FluentDataGrid>` | `<MudTable>` |
+| `<div class="spinner">` | `<FluentProgressRing>` | `<MudProgressCircular>` |
+| `<div class="progress-bar">` | `<FluentProgress>` | `<MudProgressLinear>` |
+| `<span class="badge">` | `<FluentBadge>` | `<MudChip>` |
+| `<div class="alert">` | `<FluentMessageBar>` | `<MudAlert>` |
+| `<form>` | `<EditForm>` | `<EditForm>` |
+| `<div class="tooltip">` | `<FluentTooltip>` | `<MudTooltip>` |
+| `<img>` | `<FluentIcon>` (for icons) / `<img>` | `<MudImage>` / `<img>` |
+| `<div class="tabs">` | `<FluentTabs>` | `<MudTabs>` |
+| `<details>/<summary>` | `<FluentAccordion>` | `<MudExpansionPanel>` |
+
+## Layout Mappings
+
+| HTML Layout Pattern | Blazor/CSS Approach |
+|---|---|
+| `display: grid` | Keep as CSS grid (no Fluent/MudBlazor equivalent) |
+| `display: flex` | Keep as CSS flexbox |
+| `class="container"` | Keep as CSS class in design-system.css |
+| `class="row col-*"` | Keep as CSS or use CSS grid |
+| `class="sidebar"` | `<FluentBodyContent>` or custom CSS layout |
+
+## Form Patterns
+
+| HTML Form Pattern | Blazor Equivalent |
+|---|---|
+| `<input required>` | FluentValidation rule + `<FluentValidationMessage>` |
+| `<input pattern="...">` | FluentValidation `Matches()` rule |
+| `<input min/max>` | FluentValidation `InclusiveBetween()` rule |
+| Form submission | `<EditForm OnValidSubmit="HandleSubmit">` |
+| Error display | `<FluentValidationSummary>` or `<DataAnnotationsValidator>` |
+
+## Animation Mappings
+
+| CSS Animation Class | Blazor Approach |
+|---|---|
+| `animate-fadeIn` | CSS class in design-system.css (keep as-is) |
+| `animate-slideInUp` | CSS class in design-system.css (keep as-is) |
+| `animate-pulse` | CSS class or `<FluentProgressRing>` |
+
+> For animation standards, see: `framework/standards/frontend/design-system/animations.md`
+
+## Decision Guide
+
+When a direct component mapping doesn't exist:
+1. **Check Fluent UI docs** — it may have a less obvious equivalent
+2. **Use HTML wrapper** — wrap plain HTML in a `<div>` with design-system CSS classes
+3. **Create a custom Razor component** — when the design is project-specific and reused across pages
+4. **Keep as HTML** — for one-off layout elements that don't need a component
+
+> For full Fluent UI reference: `framework/standards/frontend/blazor/fluent-ui.md`
+> For MudBlazor reference: `framework/standards/frontend/blazor/html-conversion.md`