@williambeto/ai-workflow 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [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

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

@@ -26,16 +26,28 @@ Evolve technical governance to guarantee real visual and frontend quality by enf
 - Feedback on visual quality or layout defects
 
 ## Constraints
-- **Visual Thesis & Deliberate Composition**: Layouts must be cohesive. Avoid generic grids, pill soup, or unorganized structures.
-- **Copy Specificity**: Never use placeholders ("Lorem Ipsum"). Write domain-specific, realistic copy.
+- **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.
-- **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.
 - **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.
@@ -46,11 +58,15 @@ Evolve technical governance to guarantee real visual and frontend quality by enf
 - 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 and Typography Scales**: Implement the 8px grid system and a tight heading line-height / relaxed body line-height scale.
+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.

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.4.0",
+  "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",

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

@@ -330,10 +330,24 @@ export class ArtifactFidelityGate {
   }
 
   async verifyFrontendFidelity(changedFiles) {
-    const dsSkillPath1 = path.join(this.cwd, ".agents/skills/frontend-design-system/SKILL.md");
-    const dsSkillPath2 = path.join(this.cwd, ".agents/skills/frontend_design_system/SKILL.md");
-    const hasDesignSystemSkill = await fs.access(dsSkillPath1).then(() => true).catch(() => false) ||
-                                 await fs.access(dsSkillPath2).then(() => true).catch(() => false);
+    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;
     }

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

@@ -65,7 +65,15 @@ export class VisualVerifier {
     }
 
     await this.startServer();
-    const browser = await playwright.chromium.launch();
+    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");
@@ -107,7 +115,15 @@ export class VisualVerifier {
     }
 
     await this.startServer();
-    const browser = await playwright.chromium.launch();
+    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");

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"]