@williambeto/ai-workflow 2.3.7 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
+## [2.4.1] - 2026-06-21
+
+### Fixed
+- Hardened visual and accessibility quality gates.
+- Enhanced `ArtifactFidelityGate` to check all skill folder path variations for `frontend-design-system`.
+- Documented Playwright, browser, and Axe-core preconditions in README and quickstart documentation.
+- Improved validation resiliency by warning instead of crashing when browser binaries are missing.
+
+## [2.4.0] - 2026-06-20
+
+### Added
+- Native Visual Evidence capture in `collect-evidence` via `--visual-dist` and `--port` parameters, launching a static loopback server and capturing Chromium screenshots using Playwright.
+- CSS/HTML Design System Gate validation in `ArtifactFidelityGate` that automatically runs when the `frontend-design-system` skill is loaded in the repository, checking for CSS custom properties, inline style density, CDN scripts, and semantic HTML layout tags.
+- Native accessibility auditing command `npx aw validate --a11y` via Axe-core running inside Playwright, blocking critical violations and persisting reports in `.evidence/a11y/report.json`.
+- Standard `frontend-design-system` skill (`.agents/skills/frontend-design-system/SKILL.md`) to guide Astra and other agents through visual hierarchy, spacing grids, theme palettes, accessible contrast, and output rules.
+- Automated tests covering static loopback servers, Playwright screenshots, Axe-core checks, inline style gates, CSS tokens, and HTML semantics.
+
+## [2.3.7] - 2026-06-20
+
+### Changed
+- Bumped version to 2.3.7.
+
+## [2.3.6] - 2026-06-20
+
+### Added
+- Request-aware delivery decision and artifact fidelity gates (GREEN phase) to prevent false-positive completions in frontend/backend stack tasks.
+- Hardened check for blocking delivery decisions in `ArtifactFidelityGate` and `Finalizer`.
+- False-positive regression tests and release readiness audit documentation.
+
+### Fixed
+- Aligned WordPress root detection logic between `DeliveryDecisionEngine` and `ArtifactFidelityGate`.
+- Corrected architecture and design patterns policy relative paths in the technical plan prompt.
+- Normalized approved release decision string to `RELEASE_OR_DEPLOY_APPROVED`.
+
+## [2.3.5] - 2026-06-20
+
+### Fixed
+- Corrected the governance policy relative path header in all standard skill Markdown files.
+
+## [2.3.4] - 2026-06-20
+
+### Fixed
+- Corrected the mapping and resolution path of policies under `opencode/docs`.
+
+## [2.3.3] - 2026-06-20
+
+### Added
+- First phase implementation of the Delivery Decision Engine and Artifact Fidelity Gate checking for correct technology stacks.
+- Hardened PromptContracts and validation scripts for stack-aware quality checking.
+
 ## [2.3.2] - 2026-06-19
 
+
 ### Documentation
 - Clarified first-time usage with `npx @williambeto/ai-workflow init`.
 - Clarified local installed-package alias usage with `npx aw init`, `npx aw doctor`, and `npx aw run`.

package/README.md

@@ -47,6 +47,14 @@ The `aw` binary is an alias for the same CLI entrypoint as `ai-workflow`.
 
 The CLI receives the natural request, classifies the intent, plans the workflow, switch/creates branch safely, delegates coding tasks to the OpenCode runtime adapter, validates changes, and runs bounded remediation if necessary before outputting the handoff summary.
 
+### Visual & Accessibility (A11y) Requirements
+
+For projects utilizing visual validation (screenshots) or accessibility audits (Axe-core), ensure you have:
+- `playwright` (or `@playwright/test`) and `axe-core` installed under `devDependencies`.
+- Browser binaries installed on the host machine by running `npx playwright install` (specifically Chromium).
+
+If these dependencies or browser binaries are missing, the visual and accessibility validations will fail gracefully with warning logs or block depending on CLI validation options.
+
 ## Modes and profiles
 
 | Mode | Use for | Primary evidence |

package/dist-assets/docs/QUICKSTART.md

@@ -21,3 +21,9 @@ Write-capable work never runs on `main` or `master`. Existing relevant tests/bui
 - `BLOCKED`
 
 Workflow documents are optional unless they provide lasting value or full mode requires them.
+
+## Visual & Accessibility Evidence Requirements
+
+If your project utilizes visual validation (screenshots) or accessibility audits (Axe-core), ensure you have:
+- `playwright` (or `@playwright/test`) and `axe-core` installed under `devDependencies`.
+- Browser binaries installed on the host machine by running `npx playwright install`.

package/dist-assets/docs/profiles/frontend-product.md

@@ -6,6 +6,7 @@ Required skills:
 
 - `frontend-development`
 - `ui-ux-design`
+- `frontend-design-system`
 
 Objective checks:
 

package/dist-assets/docs/profiles/frontend-utility.md

@@ -6,6 +6,7 @@ Required skills:
 
 - `frontend-development`
 - `ui-ux-design`
+- `frontend-design-system`
 
 Objective checks:
 

package/dist-assets/skills/frontend-design-system/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: frontend-design-system
+description: Design system guidelines and rules for creating premium, consistent, and accessible interfaces.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Frontend Design System PromptContract
+
+## Role
+Guides Astra and other agents in styling UI, hierarchy, and responsive layout states to build premium interfaces.
+
+## Objective
+Evolve technical governance to guarantee real visual and frontend quality by enforcing visual thesis, design tokens, responsive states, semantic HTML, and accessibility validations.
+
+## Trusted context
+- Project design system tokens (CSS custom properties)
+- HTML semantic markup standards
+- Accessible color ratios (WCAG 2.1 AA/AAA)
+- Visual asset registries (images, local SVGs)
+- Client styling guidelines
+
+## User input
+- Feature requirements and wireframes
+- Active UI components and styles
+- Target viewport dimensions (mobile, desktop)
+- Feedback on visual quality or layout defects
+
+## Constraints
+- **Visual Thesis & Deliberate Composition**: Layouts must be cohesive. Avoid generic grids, pill soup, or unorganized structures. The first viewport must read as a single unified composition, not a cluttered dashboard (unless specifically requested).
+- **Brand First**: On branded pages, the brand or product name must be a hero-level signal, not just nav text or an eyebrow. No headline should overpower the brand.
+- **Brand Test**: If the first viewport could belong to another brand after removing the navigation/logo, the branding is too weak.
+- **Typography Scale**: Maintain a single `<h1>` per page. Line heights must be balanced: 1.1-1.25 for headings, 1.5-1.7 for readable body text. Use expressive, purposeful fonts and avoid generic default stacks (e.g., plain system, Inter, Roboto, Arial) unless matching an existing design system.
+- **Background Atmosphere**: Don't rely on flat, single-color backgrounds. Use smooth gradients, images, or subtle patterns to build a premium atmosphere.
+- **Full-bleed Hero Only**: On landing pages and promotional surfaces, the hero image should be a dominant edge-to-edge visual plane or background by default. Do not use inset hero images, side-panel hero images, rounded media cards, tiled collages, or floating image blocks unless the existing design system clearly requires it.
+- **Hero Budget**: The first viewport must contain only the brand, one headline, one short supporting sentence, one CTA group, and one dominant image. Do not place stats, schedules, event listings, address blocks, promos, "this week" callouts, metadata rows, or secondary marketing content in the first viewport.
+- **No Hero Overlays**: Do not place detached labels, floating badges, promo stickers, info chips, or callout boxes on top of hero media.
+- **No Card Abuse (Default No Cards)**: Never use cards in the hero. Cards are allowed only when they serve as a container for a user interaction. If removing a border, shadow, background, or radius does not hurt interaction or understanding, it should not be a card.
+- **One Job Per Section**: Each page section must have one clear purpose, one headline, and one short supporting sentence.
+- **Real Visual Anchor**: Imagery must show the product, place, atmosphere, or context. Decorative gradients and abstract backgrounds do not count as the main visual idea.
+- **Reduce Clutter**: Avoid pill clusters, stat strips, icon rows, boxed promos, schedule snippets, and multiple competing text blocks.
+- **Motion/Animations**: Use motion to create presence and hierarchy, not noise. Implement at least 2-3 intentional, subtle motions or transitions for visually led work.
+- **React Patterns (when using React)**: Prefer modern React patterns including `useEffectEvent`, `startTransition`, and `useDeferredValue` when appropriate. Do not add `useMemo`/`useCallback` by default unless already used; follow the repository's React Compiler guidance.
+- **Strict Design System / CSS Gate**:
+  - CSS tokens must define a primary palette, background, surface, text styles, and spacing scale.
+  - Exposing excessive inline styles (`style="..."`) is prohibited.
+  - CDN dependencies for visual libraries (Tailwind, Bootstrap) are blocked unless explicitly authorized.
+- **Acessibilidade (A11y)**: Must achieve WCAG compliance. Contrast ratio must be at least 4.5:1 for body text (3:1 for headings/large text). Semantic HTML elements (`<header>`, `<main>`, `<footer>`, `<nav>`, `<section>`) must structure the layout.
+- **Tokens de Cor & Spacing**: Spacing must adhere to an 8px-grid scale (e.g. 4px, 8px, 16px, 24px, 32px, 48px). Colors must use CSS custom properties: `--color-primary`, `--color-background`, `--color-surface`, `--color-text`.
+- **Regras Anti-Output Fraco**: Prevent empty blocks, broken states, and plain gradient fills with no concrete content.
+- **Exception**: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
+
+## Allowed tools
+- `view_file` to inspect existing design tokens, components, and templates.
+- `write_to_file` and `replace_file_content` to edit CSS variables and structured HTML markup.
+- `run_command` to execute validate command line checks (`npx aw validate --a11y` and `collect-evidence`).
+
+## Forbidden actions
+- Deploying raw HTML without CSS custom properties/tokens.
+- Injecting raw CDN CSS/JS libraries into page headers without authorization.
+- Committing unstyled layout states or missing loading/empty/error/success conditions.
+- Placing cards, stats, event listings, address blocks, metadata rows, or secondary marketing clutter in the first viewport.
+- Placing floating badges, chips, or labels on top of hero media.
+- Using inset, side-panel, rounded media cards, or tiled collages for hero images.
+- Using generic browser-default font stacks (Inter, Roboto, Arial, system) for branded layouts.
+
+## Procedure
+1. **Analyze existing Design Tokens**: Check if the project already has CSS variables or custom properties. Adapt to the project's tokens if found, otherwise define a default safe set (primary, background, surface, text, space-*, font-*).
+2. **Draft Semantic Structure**: Build the UI skeleton using HTML5 semantic elements (`<header>`, `<main>`, etc.) with unique IDs for testing.
+3. **Apply Spacing, Typography, and Motion Scales**: Implement the 8px grid system, a tight heading line-height / relaxed body line-height scale, expressive font selections, and at least 2-3 intentional motion animations.
+4. **Implement UI States**: Ensure loading, empty, error, and success states are styled, fully functional, and visually robust.
+5. **A11y Verification**: Verify WCAG contrast levels. Run validation commands with `npm run validate` or `npx aw validate --a11y` to check for accessibility violations.
+6. **Collect Visual Evidence**: Capture desktop and mobile screenshots using `collect-evidence --visual-dist` to verify design fidelity.
+
+## Expected output schema
+The output must report:
+- CSS variables/tokens detected or introduced
+- Accessibility audit summary (Axe-core run results)
+- UI states implemented (loading, empty, error, success)
+- Semantic HTML tags list
+- Visual evidence location (`.evidence/visual/`)
+- Compliance decision: PASS | FAIL (with detailed reasons)
+
+## Evidence required
+- Screenshot artifacts in `.evidence/visual/` (mobile and desktop)
+- Axe-core accessibility report in `.evidence/a11y/`
+- Verified HTML/CSS files conforming to the design gates
+
+## Stop conditions
+- Absence of CSS variables/tokens defining colors or spacing
+- Axe-core report containing critical a11y violations
+- Exceeding inline style limits or using unauthorized CDNs
+
+## Failure modes
+- **White screenshots or rendering failures**: Local server path or assets not loaded.
+- **Unstyled outputs**: Styles not applied or missing CSS files.
+- **Broken layout states**: Misaligned responsive viewports or broken container grids.
+
+## Escalation rules
+- Report critical design system deviations to the frontend lead or escalate to the primary owner.

package/docs/getting-started/quickstart.md

@@ -15,3 +15,9 @@
 Quick and standard work return a concise summary with branch, changed areas, observed validation, and limitations. Full/release/audit/security work may persist structured evidence.
 
 Use `ai-workflow collect-evidence --mode=full` when a durable validation artefact is required. Do not use workflow files as substitutes for actual commands.
+
+## Visual & Accessibility Evidence Requirements
+
+If your project utilizes visual validation (screenshots) or accessibility audits (Axe-core), ensure you have:
+- `playwright` (or `@playwright/test`) and `axe-core` installed under `devDependencies`.
+- Browser binaries installed on the host machine by running `npx playwright install`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.3.7",
+  "version": "2.4.1",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
@@ -92,6 +92,7 @@
     "@semantic-release/npm": "^13.1.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
+    "axe-core": "^4.10.0",
     "markdownlint-cli": "^0.48.0",
     "playwright": "^1.60.0",
     "semantic-release": "^25.0.3",

package/src/cli.js

@@ -12,7 +12,8 @@ Usage:
   ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
   ai-workflow run --spec-path=<path>
   ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--gemini] [--claude] [--codex] [--antigravity] [--profile=<profile>]
-  ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]
+  ai-workflow validate [--a11y] [--visual-dist=<path>] [--port=<port>]
+  ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run] [--visual-dist=<path>] [--port=<port>]
   ai-workflow doctor
 
 Commands:
@@ -30,6 +31,8 @@ function parseFlags(args) {
   const taskArg = args.find((arg) => arg.startsWith("--task="));
   const modeArg = args.find((arg) => arg.startsWith("--mode="));
   const requestArg = args.find((arg) => arg.startsWith("--request="));
+  const visualDistArg = args.find((arg) => arg.startsWith("--visual-dist="));
+  const portArg = args.find((arg) => arg.startsWith("--port="));
   const profileIdx = args.indexOf("--profile");
   const profileVal = profileEqArg
     ? profileEqArg.replace("--profile=", "")
@@ -52,7 +55,10 @@ function parseFlags(args) {
     profile: profileVal || undefined,
     taskSlug: taskArg ? taskArg.replace("--task=", "") : undefined,
     mode: modeArg ? modeArg.replace("--mode=", "") : undefined,
-    request: requestArg ? requestArg.replace("--request=", "") : undefined
+    request: requestArg ? requestArg.replace("--request=", "") : undefined,
+    visualDist: visualDistArg ? visualDistArg.replace("--visual-dist=", "") : undefined,
+    port: portArg ? portArg.replace("--port=", "") : undefined,
+    a11y: args.includes("--a11y")
   };
 }
 
@@ -104,7 +110,27 @@ export async function runCli(args) {
   if (command === "collect-evidence") {
     const flags = parseFlags(args.slice(1));
     if (flags.mode && !["quick", "standard", "full"].includes(flags.mode)) throw new Error("--mode must be quick, standard, or full");
-    await runCollectEvidence({ cwd: process.cwd(), taskSlug: flags.taskSlug, mode: flags.mode, dryRun: flags.dryRun });
+    await runCollectEvidence({ 
+      cwd: process.cwd(), 
+      taskSlug: flags.taskSlug, 
+      mode: flags.mode, 
+      dryRun: flags.dryRun,
+      visualDist: flags.visualDist,
+      port: flags.port
+    });
+    return;
+  }
+
+  if (command === "validate") {
+    const flags = parseFlags(args.slice(1));
+    const { runValidate } = await import("./commands/validate.js");
+    await runValidate({
+      cwd: process.cwd(),
+      taskSlug: flags.taskSlug,
+      a11y: flags.a11y,
+      visualDist: flags.visualDist,
+      port: flags.port
+    });
     return;
   }
 

package/src/commands/collect-evidence.js

@@ -5,13 +5,13 @@ import { buildDeliverySummary, formatDeliverySummary } from "../core/validation/
 import fs from "node:fs/promises";
 import path from "node:path";
 
-export async function runCollectEvidence({ cwd, exitOnError = true, taskSlug = null, mode = null, dryRun = false, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [] }) {
+export async function runCollectEvidence({ cwd, exitOnError = true, taskSlug = null, mode = null, dryRun = false, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [], visualDist = null, port = null }) {
   const qualityGuard = new QualityGuard({ cwd, taskSlug, mode });
   const planner = new ValidationPlanner({ cwd, qualityGuard });
   const tasks = await planner.plan(profile);
 
   const persist = !dryRun && mode === "full";
-  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode, profile, branchRecovery, userRequest, explicitApprovals });
+  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode, profile, branchRecovery, userRequest, explicitApprovals, visualDist, port });
   const evidence = await collector.collect(tasks, { writeArtifact: persist });
   const summary = buildDeliverySummary({ evidence });
 

package/src/commands/validate.js

@@ -0,0 +1,81 @@
+import { EvidenceCollector } from "../core/validation/evidence-collector.js";
+import { QualityGuard } from "../core/validation/quality-guard.js";
+import { ValidationPlanner } from "../core/validation/validation-planner.js";
+import { VisualVerifier } from "../core/validation/visual-verifier.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function runValidate({ cwd = process.cwd(), exitOnError = true, taskSlug = null, a11y = false, visualDist = null, port = 8080 }) {
+  console.log("--- Running Validation ---");
+  const qualityGuard = new QualityGuard({ cwd, taskSlug, mode: "standard" });
+  const planner = new ValidationPlanner({ cwd, qualityGuard });
+  const tasks = await planner.plan("standard");
+
+  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode: "standard" });
+  const results = [];
+  
+  for (const task of tasks) {
+    console.log(`Running validation task: ${task.name}...`);
+    const res = collector.runTask(task);
+    results.push(res);
+    console.log(`- Status: ${res.status} (${res.summary})`);
+  }
+
+  let a11yResult = null;
+  if (a11y) {
+    if (!visualDist) {
+      throw new Error("Accessibility audit (--a11y) requires a target build directory specified via --visual-dist=<path>.");
+    }
+    console.log(`\n--- Running Accessibility Audit ---`);
+    console.log(`Serving ${visualDist} on port ${port}...`);
+    try {
+      const verifier = new VisualVerifier({ cwd, visualDist, port });
+      a11yResult = await verifier.runAccessibilityCheck();
+      console.log(`Accessibility audit complete.`);
+      console.log(`- Critical violations: ${a11yResult.critical.length}`);
+      console.log(`- Serious violations: ${a11yResult.serious.length}`);
+      console.log(`- Report saved to: ${path.relative(cwd, a11yResult.reportPath)}`);
+    } catch (err) {
+      console.error(`Accessibility audit failed: ${err.message}`);
+      if (exitOnError) process.exit(1);
+      throw err;
+    }
+  }
+
+  // Load future configuration if present
+  let config = {};
+  try {
+    const configContent = await fs.readFile(path.join(cwd, "ai-workflow.config.json"), "utf8");
+    config = JSON.parse(configContent);
+  } catch {}
+
+  const hasFailure = results.some((r) => ["FAIL", "BLOCKED", "FAIL_QUALITY_GATE"].includes(r.status));
+  
+  let hasA11yFailure = false;
+  if (a11yResult) {
+    const criticalIsBlocker = true; // Critical violations are always blockers
+    const seriousIsBlocker = config.a11y?.seriousAsBlocker === true;
+    
+    if (criticalIsBlocker && a11yResult.critical.length > 0) {
+      hasA11yFailure = true;
+      console.error(`Accessibility FAILED: ${a11yResult.critical.length} critical accessibility violations detected.`);
+    }
+    if (a11yResult.serious.length > 0) {
+      if (seriousIsBlocker) {
+        hasA11yFailure = true;
+        console.error(`Accessibility FAILED: ${a11yResult.serious.length} serious accessibility violations detected (blocked by configuration).`);
+      } else {
+        console.warn(`Accessibility WARNING: ${a11yResult.serious.length} serious accessibility violations detected.`);
+      }
+    }
+  }
+
+  if (hasFailure || hasA11yFailure) {
+    console.log("\nValidation FAILED.");
+    if (exitOnError) process.exit(1);
+    return { passed: false, results, a11yResult };
+  }
+
+  console.log("\nValidation PASSED.");
+  return { passed: true, results, a11yResult };
+}

package/src/core/validation/artifact-fidelity-gate.js

@@ -58,6 +58,14 @@ export class ArtifactFidelityGate {
       }
     }
 
+    const frontendViolations = await this.verifyFrontendFidelity(changedFiles);
+    if (frontendViolations && frontendViolations.length > 0) {
+      return {
+        passed: false,
+        reason: frontendViolations.join("; ")
+      };
+    }
+
     return { passed: true };
   }
 
@@ -305,6 +313,11 @@ export class ArtifactFidelityGate {
       }
     }
 
+    const frontendViolations = await this.verifyFrontendFidelity(filteredFiles);
+    if (frontendViolations && frontendViolations.length > 0) {
+      violations.push(...frontendViolations);
+    }
+
     const status = violations.length > 0 ? "BLOCKED" : "PASS";
     return {
       status,
@@ -315,6 +328,93 @@ export class ArtifactFidelityGate {
       violations
     };
   }
+
+  async verifyFrontendFidelity(changedFiles) {
+    const skillPaths = [
+      path.join(this.cwd, ".agents/skills/frontend-design-system/SKILL.md"),
+      path.join(this.cwd, ".agents/skills/frontend_design_system/SKILL.md"),
+      path.join(this.cwd, ".ai-workflow/opencode/skills/frontend-design-system/SKILL.md"),
+      path.join(this.cwd, ".ai-workflow/opencode/skills/frontend_design_system/SKILL.md"),
+      path.join(this.cwd, "opencode/skills/frontend-design-system/SKILL.md"),
+      path.join(this.cwd, "opencode/skills/frontend_design_system/SKILL.md")
+    ];
+
+    let hasDesignSystemSkill = false;
+    for (const p of skillPaths) {
+      const exists = await fs.access(p).then(() => true).catch(() => false);
+      if (exists) {
+        hasDesignSystemSkill = true;
+        break;
+      }
+    }
+
+    if (!hasDesignSystemSkill) {
+      return null;
+    }
+
+    const uiFiles = changedFiles.filter((file) =>
+      /\.(tsx|jsx|vue|html|css|scss|less|blade\.php)$/.test(file)
+    );
+    if (uiFiles.length === 0) return null;
+
+    const violations = [];
+    let cssContentCombined = "";
+    let htmlContentCombined = "";
+    let styleAttrsCount = 0;
+
+    for (const file of uiFiles) {
+      try {
+        const fullPath = path.join(this.cwd, file);
+        const content = await fs.readFile(fullPath, "utf8");
+
+        if (/\.(css|scss|less|vue|tsx|jsx)$/.test(file)) {
+          cssContentCombined += content;
+        }
+        if (/\.(html|vue|tsx|jsx|blade\.php)$/.test(file)) {
+          htmlContentCombined += content;
+          
+          // Match inline style attributes
+          const inlineStyles = content.match(/style\s*=\s*["']/g) || [];
+          styleAttrsCount += inlineStyles.length;
+
+          // CDN Checks
+          if (/(unpkg\.com|cdnjs\.cloudflare\.com|cdn\.jsdelivr\.net|tailwindcss|bootstrap)/i.test(content)) {
+            const isApproved = (this.explicitApprovals || []).some(app => 
+              /cdn-styles|tailwind|bootstrap/i.test(app)
+            );
+            if (!isApproved) {
+              violations.push(`Fidelity Violation: standalone external CDN style/library dependency detected in '${file}' without explicit authorization.`);
+            }
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    // 1. Tokens CSS mínimos Check
+    const hasRules = cssContentCombined.includes("{");
+    const hasCssVars = /--[a-zA-Z0-9_-]+\s*:/g.test(cssContentCombined);
+    if (hasRules && !hasCssVars) {
+      violations.push("Fidelity Violation: Design System token mismatch. No CSS custom properties (variables) detected in changed UI stylesheets.");
+    }
+
+    // 2. Excesso de style="..."
+    if (styleAttrsCount > 5) {
+      violations.push(`Fidelity Violation: excessive inline styles detected (${styleAttrsCount} style="..." declarations). Use CSS classes or utility classes instead.`);
+    }
+
+    // 3. HTML principal tags semânticas básicas Check
+    if (htmlContentCombined.length > 0) {
+      const hasSemanticTags = /<(header|main|footer|nav|section)\b/i.test(htmlContentCombined);
+      const hasH1 = /<h1\b/i.test(htmlContentCombined);
+      if (!hasSemanticTags && !hasH1) {
+        violations.push("Fidelity Violation: HTML layout structure lacks basic semantic elements (<header>, <main>, <footer>, <nav>, <section>) or <h1> tag.");
+      }
+    }
+
+    return violations;
+  }
 }
 
 async function hasWpThemeHeader(cwd, file) {

package/src/core/validation/evidence-collector.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { QualityGuard } from "./quality-guard.js";
 import { DeliveryDecisionEngine } from "./delivery-decision-engine.js";
 import { ArtifactFidelityGate } from "./artifact-fidelity-gate.js";
+import { VisualVerifier } from "./visual-verifier.js";
 
 const VALIDATION_KINDS = new Set(["test", "build", "typecheck", "lint", "security", "smoke", "validate", "other"]);
 
@@ -29,7 +30,7 @@ function inferTaskKind(task = {}) {
 }
 
 export class EvidenceCollector {
-  constructor({ cwd, maxLogLength = 2000, timeout = 60000, taskSlug = null, mode = null, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [] } = {}) {
+  constructor({ cwd, maxLogLength = 2000, timeout = 60000, taskSlug = null, mode = null, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [], visualDist = null, port = 8080 } = {}) {
     this.cwd = cwd;
     this.maxLogLength = maxLogLength;
     this.timeout = timeout;
@@ -39,6 +40,8 @@ export class EvidenceCollector {
     this.branchRecovery = branchRecovery;
     this.userRequest = userRequest;
     this.explicitApprovals = explicitApprovals;
+    this.visualDist = visualDist;
+    this.port = Number(port || 8080);
   }
 
   async findUserRequest() {
@@ -194,6 +197,26 @@ export class EvidenceCollector {
       if (check.status === "PASS_WITH_NOTES" && check.reason) limitations.push(`${name}: ${check.reason}`);
     }
 
+    let visualEvidence = null;
+    if (this.visualDist) {
+      console.log(`\n--- Capturing Visual Evidence ---`);
+      console.log(`Serving ${this.visualDist} on port ${this.port}...`);
+      try {
+        const verifier = new VisualVerifier({ cwd: this.cwd, visualDist: this.visualDist, port: this.port });
+        const screenshots = await verifier.captureScreenshots();
+        visualEvidence = {
+          desktop: path.relative(this.cwd, screenshots[0]),
+          mobile: path.relative(this.cwd, screenshots[1])
+        };
+        console.log(`Visual evidence captured successfully:`);
+        console.log(`- Desktop: ${visualEvidence.desktop}`);
+        console.log(`- Mobile: ${visualEvidence.mobile}`);
+      } catch (err) {
+        console.error(`Error capturing visual evidence: ${err.message}`);
+        throw err;
+      }
+    }
+
     const evidence = {
       timestamp: new Date().toISOString(),
       taskSlug: this.taskSlug,
@@ -208,7 +231,8 @@ export class EvidenceCollector {
       checks: policyValidation.checks,
       limitations,
       deliveryDecision,
-      artifactFidelityCheck
+      artifactFidelityCheck,
+      visualEvidence
     };
 
     if (writeArtifact) {

package/src/core/validation/visual-verifier.js

@@ -0,0 +1,175 @@
+import http from "node:http";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export class VisualVerifier {
+  constructor({ cwd = process.cwd(), visualDist = null, port = 8080 } = {}) {
+    this.cwd = cwd;
+    this.visualDist = visualDist;
+    this.port = Number(port || 8080);
+    this.server = null;
+  }
+
+  async startServer() {
+    if (!this.visualDist) {
+      throw new Error("No --visual-dist directory specified. Cannot start visual server.");
+    }
+    const distPath = path.resolve(this.cwd, this.visualDist);
+    this.server = http.createServer(async (req, res) => {
+      try {
+        const urlPath = req.url.split("?")[0];
+        const filePath = path.join(distPath, urlPath === "/" ? "index.html" : urlPath);
+        const content = await fs.readFile(filePath);
+        
+        const ext = path.extname(filePath).toLowerCase();
+        let contentType = "text/html";
+        if (ext === ".js" || ext === ".mjs") contentType = "application/javascript";
+        else if (ext === ".css") contentType = "text/css";
+        else if (ext === ".png") contentType = "image/png";
+        else if (ext === ".jpg" || ext === ".jpeg") contentType = "image/jpeg";
+        else if (ext === ".svg") contentType = "image/svg+xml";
+        
+        res.writeHead(200, { "Content-Type": contentType });
+        res.end(content);
+      } catch (err) {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+      }
+    });
+
+    await new Promise((resolve, reject) => {
+      this.server.listen(this.port, "127.0.0.1", (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  async closeServer() {
+    if (this.server) {
+      await new Promise((resolve) => this.server.close(resolve));
+      this.server = null;
+    }
+  }
+
+  async captureScreenshots() {
+    if (!this.visualDist) return [];
+
+    let playwright;
+    try {
+      playwright = await import("playwright");
+    } catch {
+      throw new Error(
+        "Playwright is required to capture visual evidence. Please install it using 'npm install -D playwright' and initialize browsers using 'npx playwright install'."
+      );
+    }
+
+    await this.startServer();
+    let browser;
+    try {
+      browser = await playwright.chromium.launch();
+    } catch (err) {
+      await this.closeServer();
+      throw new Error(
+        `Failed to launch Playwright Chromium. Please ensure browsers are installed using 'npx playwright install chromium'. Details: ${err.message}`
+      );
+    }
+    const page = await browser.newPage();
+
+    const outputDir = path.join(this.cwd, ".evidence/visual");
+    await fs.mkdir(outputDir, { recursive: true });
+
+    const desktopPath = path.join(outputDir, "desktop.png");
+    const mobilePath = path.join(outputDir, "mobile.png");
+
+    try {
+      await page.goto(`http://127.0.0.1:${this.port}`);
+
+      // Desktop
+      await page.setViewportSize({ width: 1440, height: 900 });
+      await page.screenshot({ path: desktopPath, fullPage: true });
+
+      // Mobile
+      await page.setViewportSize({ width: 390, height: 844 });
+      await page.screenshot({ path: mobilePath, fullPage: true });
+    } finally {
+      await browser.close();
+      await this.closeServer();
+    }
+
+    return [desktopPath, mobilePath];
+  }
+
+  async runAccessibilityCheck() {
+    if (!this.visualDist) {
+      throw new Error("Accessibility check requires a target build directory specified via --visual-dist.");
+    }
+
+    let playwright;
+    try {
+      playwright = await import("playwright");
+    } catch {
+      throw new Error(
+        "Playwright is required to run accessibility checks. Please install it using 'npm install -D playwright' and initialize browsers using 'npx playwright install'."
+      );
+    }
+
+    await this.startServer();
+    let browser;
+    try {
+      browser = await playwright.chromium.launch();
+    } catch (err) {
+      await this.closeServer();
+      throw new Error(
+        `Failed to launch Playwright Chromium. Please ensure browsers are installed using 'npx playwright install chromium'. Details: ${err.message}`
+      );
+    }
+    const page = await browser.newPage();
+
+    const outputDir = path.join(this.cwd, ".evidence/a11y");
+    await fs.mkdir(outputDir, { recursive: true });
+
+    try {
+      await page.goto(`http://127.0.0.1:${this.port}`);
+
+      // Read axe-core bundle
+      let axeScript = "";
+      try {
+        const axePath = path.join(this.cwd, "node_modules/axe-core/axe.min.js");
+        axeScript = await fs.readFile(axePath, "utf8");
+      } catch {
+        // Fallback: look in dev-kit node_modules
+        try {
+          // Resolve relative to current module path
+          const mainAxePath = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../../node_modules/axe-core/axe.min.js");
+          axeScript = await fs.readFile(mainAxePath, "utf8");
+        } catch {
+          throw new Error("axe-core package is not installed. Please install axe-core using 'npm install -D axe-core'.");
+        }
+      }
+
+      await page.evaluate(axeScript);
+
+      const axeResults = await page.evaluate(() => {
+        return window.axe.run();
+      });
+
+      const reportPath = path.join(outputDir, "report.json");
+      await fs.writeFile(reportPath, JSON.stringify(axeResults, null, 2));
+
+      const criticalViolations = axeResults.violations.filter(v => v.impact === "critical");
+      const seriousViolations = axeResults.violations.filter(v => v.impact === "serious");
+
+      return {
+        passed: criticalViolations.length === 0,
+        reportPath,
+        violations: axeResults.violations,
+        critical: criticalViolations,
+        serious: seriousViolations
+      };
+    } finally {
+      await browser.close();
+      await this.closeServer();
+    }
+  }
+}

package/src/core/workflow-profiles.js

@@ -1,14 +1,14 @@
 const PROFILE_DEFINITIONS = Object.freeze({
   "frontend-product": Object.freeze({
     owner: "Astra",
-    skills: ["frontend-development", "ui-ux-design"],
+    skills: ["frontend-development", "ui-ux-design", "frontend-design-system"],
     objective: "Deliver a user-facing product or marketing surface with truthful copy and deliberate visual composition.",
     requiredChecks: ["tests", "typecheck", "build", "responsive-render", "primary-interaction", "truthfulness"],
     forbiddenAssumptions: ["fixed SaaS section sequence", "mandatory pricing", "mandatory testimonials", "subjective premium score"]
   }),
   "frontend-utility": Object.freeze({
     owner: "Astra",
-    skills: ["frontend-development", "ui-ux-design"],
+    skills: ["frontend-development", "ui-ux-design", "frontend-design-system"],
     objective: "Deliver a focused user tool with a complete primary flow and clear operational states.",
     requiredChecks: ["tests", "typecheck", "build", "responsive-render", "primary-interaction"],
     forbiddenAssumptions: ["marketing sections", "pricing", "testimonials", "commercial narrative"]