Cypress UX UI Guide For Developers

Overview

The UI/UX Quality Check system is implemented using:

• Cypress custom commands in cypress/cypress/support/commands.ts
• Design token lookups in cypress/cypress/support/helpers/tokens.helpers.ts
• Taxonomy and severity engines in cypress/cypress/support/helpers/tokens.helpers.ts
• Validation helpers in cypress/cypress/support/helpers/designTokens.helpers.ts and uxui.helpers.ts
• Cypress tasks for aggregation in cypress/cypress.config.ts
• JSON reports written after each test run

This document explains how the system works internally.

---

1. Cypress Custom Commands

Each UI/UX check is implemented as a Cypress custom command.
Commands operate on DOM elements and validate style properties against design tokens.

Example: shouldHaveStyle

The actual implementation uses createTaskRecord and valuesMatch from tokens.helpers.ts:

// From cypress/cypress/support/helpers/uxui.helpers.ts
export const shouldHaveStyle = (subject, property: string, expected: string) => {
  return cy.window().then(appWindow => {
    return cy.wrap(subject).then($el => {
      const el = $el[0] as Element;
      const appStyles = appWindow.getComputedStyle(el);
      const actual = appStyles.getPropertyValue(property).trim();
      const isMismatch = !valuesMatch(expected, actual, rootFontSize);

      const taskRecord = createTaskRecord(
        isMismatch ? 'violation' : 'check',
        isMismatch ? 'style-mismatch' : 'style-check',
        getTaxonomy(property),
        actual,
        el.tagName.toLowerCase(),
        { property, expected }
      );

      return cy.task('uiux:record', taskRecord).then(() => {
        expect(actual, `Element's ${property} is '${actual}', expected '${expected}'`).to.equal(expected);
        return subject;
      });
    });
  });
};

The valuesMatch function handles color normalization, px/rem conversion, and tolerance for floating-point differences.

Other Commands

• validateStyle(tokenName, cssProperty) — checks a single CSS property against a design token
• validateTokenStyle(tokenName) — checks all properties from a design token
• validateContrast(expectedLevel) — checks text-to-background contrast ratio against WCAG level
• validateTypography(tokenName) — checks font-size, weight, line-height, letter-spacing, and font-family against a typography token

All follow the same pattern:

1. Wrap the subject and get the app window
2. Extract computed styles via getComputedStyle
3. Compare against expected token values using valuesMatch
4. Record results via cy.task("uiux:record") using createTaskRecord
5. Assert using Cypress expect

---

2. Taxonomy Engine

Maps CSS properties to categories. The full map from tokens.helpers.ts:

const UX_TAXONOMY_MAP = {
  // Typography
  "font-size": "typography",
  "font-weight": "typography",
  "line-height": "typography",
  "letter-spacing": "typography",
  "font-family": "typography",
  // Color
  "color": "color",
  "background-color": "color",
  // Border
  "border-color": "border",
  "border-width": "border",
  "border-radius": "border",
  // Spacing
  "padding": "spacing",
  "padding-top": "spacing",
  "padding-right": "spacing",
  "padding-bottom": "spacing",
  "padding-left": "spacing",
  "margin": "spacing",
  "margin-top": "spacing",
  "margin-right": "spacing",
  "margin-bottom": "spacing",
  "margin-left": "spacing",
  // Layout
  "width": "layout",
  "height": "layout",
  "min-width": "layout",
  "min-height": "layout",
  "max-width": "layout",
  "max-height": "layout",
  // Special
  "spacing": "spacing",
  "alignment": "alignment",
  "contrast": "contrast"
};

const getTaxonomy = (property) =>
  UX_TAXONOMY_MAP[property] || "style";

---

3. Severity Engine

Assigns severity based on taxonomy. The full map from tokens.helpers.ts:

const UX_SEVERITY_MAP = {
  "color": "critical",
  "contrast": "critical",
  "typography": "major",
  "spacing": "minor",
  "border": "minor",
  "layout": "minor",
  "alignment": "minor",
  "token-missing": "major",
  "style-mismatch": "major",
  "style-check": "info"
};

const getSeverity = (taxonomy, event) => {
  if (event === "check") return "info";
  return UX_SEVERITY_MAP[taxonomy] || "major";
};

---

4. Cypress Tasks (Aggregation Layer)

Recording events

The tasks are defined in cypress/cypress.config.ts:

on("task", {
  "uiux:record"(payload) {
    uiuxResults.push(payload);
    return null;
  },

  "uiux:reset"() {
    uiuxResults = [];
    return null;
  }
});

Final report generation

on("after:run", () => {
  fs.mkdirSync(path.dirname(UIUX_REPORT_FILE), { recursive: true });

  fs.writeFileSync(
    UIUX_REPORT_FILE,
    JSON.stringify(
      {
        generatedAt: new Date().toISOString(),
        checks: uiuxResults
      },
      null,
      2
    ),
    "utf8"
  );
});

---

5. Report Structure

The final JSON report is written to cypress/reports/uiux/uiux-results.json:

{
  "generatedAt": "2026-03-24T20:12:00Z",
  "checks": [
    {
      "event": "violation",
      "type": "style-mismatch",
      "taxonomy": "typography",
      "property": "font-size",
      "expected": "16px",
      "actual": "14px",
      "severity": "major",
      "selector": ".login-btn",
      "scenario": "User logs in",
      "feature": "login.feature"
    }
  ]
}

This file is consumed by cypress/scripts/modules/uiuxModule.js to generate:

• Markdown summaries (summary.md)
• PR comments
• Quality dashboards
• Quality gates

---

6. Key Technical Principles

• All commands return a Cypress chain (cy.window().then() → cy.wrap().then())
• prevSubject: true is required for typed commands in commands.ts
• cy.task() must sit inside the Cypress chain
• valuesMatch handles px/rem/em conversion and color normalization with tolerance
• createTaskRecord standardizes all records with scenario, feature, timestamp, and severity
• The Node process resets between spec files
• before:run clears stale report files; after:run writes the final JSON

---

7. File Structure

The UI/UX quality check system consists of these files:

File	Purpose
cypress/cypress/support/commands.ts	Custom Cypress commands for UI/UX checks
cypress/cypress/support/helpers/tokens.helpers.ts	Design token definitions and utilities
cypress/cypress/support/helpers/designTokens.helpers.ts	Design token validation logic
cypress/cypress/support/helpers/elements.helpers.ts	Element resolution for natural language targeting
cypress/cypress/support/helpers/uxui.helpers.ts	UI/UX helper functions
cypress/cypress/support/step_definitions/steps/uiux.steps.ts	UI/UX Gherkin steps
cypress/cypress/support/step_definitions/steps/designTokens.steps.ts	Design token Gherkin steps
cypress/cypress.config.ts	Task definitions and report generation
cypress/scripts/modules/uiuxModule.js	UI/UX report parsing
cypress/reports/uiux/uiux-results.json	Generated UI/UX results

---

8. Extensibility

The system is designed to support:

• Additional taxonomies
• Additional severity rules
• New UI/UX commands
• Screenshot linking
• Visual diffs
• Trend analysis
• Unified quality reports