Token Accessibility Enforcer - API Contract

GET /api/v1/accessibility-violations/api/v1/accessibility-violations

List all reported accessibility violations

Public

Response Example

{
  "data": [
    {
      "id": "av-001",
      "violation_type": "contrast",
      "severity": "error",
      "description": "Foreground #9E9E9E on background #FFFFFF fails WCAG AA for normal text",
      "token_key": "color.text.secondary",
      "resolved": false,
      "reported_at": "2026-03-26T09:45:00Z"
    },
    {
      "id": "av-002",
      "violation_type": "touch_target",
      "severity": "warning",
      "description": "Icon button size 36x36dp is below minimum 44x44dp",
      "token_key": "sizing.icon-button",
      "resolved": false,
      "reported_at": "2026-03-26T09:46:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 7
  }
}

GET /api/v1/accessibility-violations/api/v1/accessibility-violations/:id

Get a specific accessibility violation report

Public

Response Example

{
  "id": "av-001",
  "violation_type": "contrast",
  "severity": "error",
  "description": "Foreground #9E9E9E on background #FFFFFF fails WCAG AA for normal text",
  "token_key": "color.text.secondary",
  "actual_value": "#9E9E9E",
  "expected_minimum": "#767676",
  "resolved": false,
  "reported_at": "2026-03-26T09:45:00Z"
}

POST /api/v1/accessibility-violations/api/v1/accessibility-violations

Report a new accessibility violation

Public

Request Example

{
  "violation_type": "font_weight",
  "severity": "warning",
  "description": "Body text FontWeight.w300 is below minimum w400 for accessibility",
  "token_key": "typography.body.weight",
  "actual_value": "w300",
  "expected_minimum": "w400"
}

Response Example

{
  "id": "av-008",
  "violation_type": "font_weight",
  "severity": "warning",
  "description": "Body text FontWeight.w300 is below minimum w400 for accessibility",
  "token_key": "typography.body.weight",
  "actual_value": "w300",
  "expected_minimum": "w400",
  "resolved": false,
  "reported_at": "2026-03-26T10:00:00Z"
}

PUT /api/v1/accessibility-violations/api/v1/accessibility-violations/:id

Update a violation (e.g. mark resolved)

Public

Request Example

{
  "resolved": true,
  "resolution_note": "Token updated to #767676 in design-tokens.json"
}

Response Example

{
  "id": "av-001",
  "violation_type": "contrast",
  "severity": "error",
  "resolved": true,
  "resolution_note": "Token updated to #767676 in design-tokens.json",
  "reported_at": "2026-03-26T09:45:00Z",
  "resolved_at": "2026-03-26T10:15:00Z"
}

DELETE /api/v1/accessibility-violations/api/v1/accessibility-violations/:id

Delete a violation record

Public

Response Example

{
  "deleted": true,
  "id": "av-008"
}

POST /api/v1/accessibility-violations/api/v1/accessibility-violations/enforce

Run enforcement and auto-correct a token set, returning violations found

Public

Request Example

{
  "foreground_hex": "#BBBBBB",
  "background_hex": "#FFFFFF",
  "font_weight": "w300",
  "text_role": "body",
  "touch_target_width_dp": 36,
  "touch_target_height_dp": 36
}

Response Example

{
  "corrected_foreground_hex": "#767676",
  "corrected_font_weight": "w400",
  "corrected_touch_target_width_dp": 44,
  "corrected_touch_target_height_dp": 44,
  "violations_found": 3,
  "violations": [
    {
      "type": "contrast",
      "severity": "error"
    },
    {
      "type": "font_weight",
      "severity": "warning"
    },
    {
      "type": "touch_target",
      "severity": "warning"
    }
  ]
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}