ux ui developers

---

title: "Cypress UX/UI Guide for Developers" type: guide domain: testing framework: cypress tags: [cypress, design-tokens, taxonomy, severity, ux, ui, carbon] created: 2026-07-14

Cypress UX/UI Guide for Developers

Internal implementation of the UI/UX quality check system.

System overview

The system uses:

• Custom commands in cypress/cypress/support/commands.ts
• Token lookups in cypress/cypress/support/helpers/tokens.helpers.ts
• Validation helpers in designTokens.helpers.ts and uxui.helpers.ts
• Cypress tasks in cypress.config.ts for aggregation
• JSON reports written after each run

Custom commands

Commands registered in commands.ts:

Command	Subject	Description
validateStyle(token, property)	element	Check one CSS property against a token
validateTokenStyle(token)	element	Check all properties from a token
validateContrast(level)	element	Check contrast ratio against WCAG level
validateTypography(token)	element	Check font properties against a typography token
shouldHaveStyle(property, expected)	element	Legacy: check computed CSS property

All commands follow the same flow: cy.window() → cy.wrap() → getComputedStyle → valuesMatch → createTaskRecord → cy.task("uiux:record") → expect.

Taxonomy engine

Maps CSS properties to categories. 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";

Severity engine

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";
};

Task recording

createTaskRecord standardizes all records:

{
  event: "check" | "violation",
  type: "style-check" | "style-mismatch" | "token-missing" | ...,
  taxonomy: "typography" | "color" | ...,
  actual: "14px",
  element: "button",
  scenario: "User logs in",
  feature: "login.feature",
  timestamp: Date.now()
}

Token resolution

getTokenDefinition resolves tokens via CSS custom properties:

1. Try --cds-{token}-{property} (property-specific)
2. Fall back to --cds-{token} (base token)

valuesMatch handles:

• Color normalization (hex, rgb, hsl, named colors)
• px/rem/em conversion with tolerance (0.5px default)
• Floating-point comparison

Report flow

1. cy.task("uiux:record") pushes to uiuxResults array in Node
2. before:run clears stale files
3. after:run writes reports/uiux/uiux-results.json
4. scripts/modules/uiuxModule.js reads JSON and produces markdown tables

File reference

File	Purpose
support/commands.ts	Command registration
support/helpers/tokens.helpers.ts	Token resolution, color math, taxonomy, severity
support/helpers/designTokens.helpers.ts	validateStyle, validateTokenStyle, validateContrast, validateTypography
support/helpers/uxui.helpers.ts	shouldHaveStyle (legacy)
support/helpers/elements.helpers.ts	Element resolution by type and text
support/step_definitions/steps/uiux.steps.ts	Gherkin steps for UI/UX checks
support/step_definitions/steps/designTokens.steps.ts	Gherkin steps for design tokens
cypress.config.ts	Task definitions, report writing
scripts/modules/uiuxModule.js	Markdown report generation