npm package: @rikaidev/mesen
Description: Behavioral UX testing through simulated user perspectives. Persona-driven, evidence-based, model-agnostic.
Latest version: 0.1.1

# mesen (目線)

Behavioral UX testing through simulated user perspectives. Persona-driven, evidence-based, model-agnostic.

> "axe-core tells you your button is missing an ARIA label. mesen tells you your grandmother can't find the button."

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg)](https://www.typescriptlang.org/)
[![Node](https://img.shields.io/badge/Node-20%2B-green.svg)](https://nodejs.org/)

## What is mesen?

mesen is an open-source UX testing tool that simulates **real users** attempting tasks on your web app, then audits findings against design guidelines (WCAG, Apple HIG, Material Design, Nielsen).

Instead of just checking ARIA labels and contrast ratios, mesen asks: **can this specific person actually do what they came to do?**

### How it works

```
.ux spec (persona + BDD scenarios)
    → Browser: navigate, authenticate, capture DOM
    → Layer 1: measure everything (contrast, touch targets, fonts, layout)
    → AI agent: read measurements + persona + skills → derive thresholds → judge
    → Output: code-review style findings (accept/dismiss per finding)
```

### What makes it different

| Tool | What it checks | What it misses |
|------|---------------|----------------|
| axe-core / Lighthouse | Structural WCAG violations | Can the user *find* the button? |
| Playwright / Cypress | Does the feature work? | Can they *use* it? |
| Percy / Chromatic | Did pixels change? | Is the change a *problem*? |
| **mesen** | **Can this persona complete this task?** | |

## Quick start

```bash
# Install
npm install -D mesen

# Put a .ux spec in your project
mkdir -p .mesen/specs
# Write or generate a .ux spec (see below)

# Run
npx mesen run
```

mesen auto-discovers `.mesen/specs/*.ux` files.

## The .ux spec

A `.ux` spec combines persona definition with BDD scenarios — written in human language, not technical specs:

```yaml
---
url: https://your-app.com

auth:
  email: $APP_EMAIL
  password: $APP_PASSWORD

persona:
  name: Nurse Chen
  age: 52
  tech_literacy: minimal
  vision: normal
  context: |
    Station leader at a community care facility.
    Opens tablet at 8am to check who's coming today.
    Each operation must complete in under 30 seconds.
  cognitive_model:
    working_memory: medium
    frustration_threshold: 2
  physical_model:
    click_confidence: low

device:
  type: iPad
  viewport: [1024, 768]

guidelines: [wcag-2.1, apple-hig, nielsen]
---

Feature: Morning station opening

  Scenario: Check today's attendance
    Given I open the tablet after logging in
    When I look at the home screen
    Then I should see how many elders are expected today
    And I should be able to tell who has arrived and who hasn't

  Scenario: Urgent items stand out
    Given I'm on the home screen
    When an elder had abnormal blood pressure yesterday
    Then that alert should appear before routine tasks
    And I should see which elder and what the issue is without tapping in
```

**Key principles:**
- BDD is in the persona's language (any human language)
- No `px`, `contrast ratio`, or technical measurements in scenarios
- Thresholds are derived by the AI agent from persona traits + guideline skills
- Auth is auto-detected (form login, token, cookies)

## Architecture

```
Layer 1: Evidence (mesen)          Layer 2: Analysis (AI agent + skills)
┌──────────────────────┐           ┌──────────────────────────┐
│ DOM measurements     │           │ bdd-to-thresholds skill  │
│ - contrast ratios    │           │ - persona traits → numbers│
│ - touch target sizes │     →     │ tablet-task-audit skill  │
│ - font sizes         │           │ - one-screen, priority    │
│ - accessible names   │           │ domain skills (extensible)│
│ - layout structure   │           │ - care-station, retail... │
│ Lighthouse scores    │           │                          │
└──────────────────────┘           └──────────────────────────┘
        Facts only                    Judgment with domain knowledge
```

**Layer 1** collects measurements (facts, no judgment). A 3.2:1 contrast ratio is just a number — whether it's a problem depends on the persona.

**Layer 2** is the AI agent reading the evidence through skills. The `bdd-to-thresholds` skill translates "52-year-old with normal vision" into "min font 14px, key data 20px." Domain skills like `care-station` know that ID number search is standard practice in healthcare (not a privacy issue).

## Integration

### Claude Code plugin

```bash
# Install as Claude Code plugin
claude plugin add mesen

# Use in Claude Code
/audit              # Full UX audit with skills
/write-spec          # Generate a .ux spec
```

### MCP server

```json
{
  "mcpServers": {
    "mesen": {
      "command": "npx",
      "args": ["mesen", "serve"]
    }
  }
}
```

**MCP tools:**
- `mesen_dom_check` — quick DOM measurements
- `mesen_audit` — full VLM audit with spec
- `mesen_evidence` — evidence bundle for any model
- `mesen_score` — UX score
- `mesen_fix_suggestions` — remediation suggestions

### CLI

```bash
# Auto-discover specs
mesen run

# Specific spec
mesen run --spec path/to/spec.ux

# Override URL (test against staging)
mesen run --url https://staging.example.com

# Evidence bundle for AI agent consumption
mesen evidence --spec spec.ux --output-format prompt
```

### CI / GitHub Actions

```yaml
- name: UX Audit
  uses: mesen/action@v1
  with:
    specs: '.mesen/specs/**/*.ux'
    tier: dom-only
```

## Smart auth

mesen auto-detects login mechanisms:

- **Form login**: Detects login form → fills credentials → submits
- **CAPTCHA**: Opens browser → pre-fills credentials → you fill CAPTCHA → mesen continues automatically
- **Session caching**: Saves session after first login, reuses on next run
- **Token/cookie**: Set in spec auth section

```yaml
auth:
  email: admin@example.com
  password: secret123
```

No need to specify `type:` — mesen figures it out.

## Extensible skills

mesen ships with base skills and supports domain-specific extensions:

### Built-in skills

| Skill | Purpose |
|-------|---------|
| `write-ux-spec` | Guide for writing effective .ux BDD specs |
| `bdd-to-thresholds` | Derive measurable thresholds from persona traits |
| `tablet-task-audit` | Audit operational tablet apps (one-screen, priority, layout) |

### Domain skills

Domain skills extend the base audit with field-specific knowledge:

```
skills/domains/
├── care-station/    # Elder care facilities
├── retail-pos/      # Point of sale systems
├── warehouse/       # Warehouse management
└── your-domain/     # Create your own
```

Domain skills provide:
- **False positive filters** — things that look wrong to a generalist but are correct for the domain
- **Priority rules** — what counts as "urgent" varies by domain
- **Standard workflows** — the real-world task sequence the UI must support

### Create a domain skill

```markdown
---
name: domain-your-industry
description: Domain knowledge for [industry] apps
---

# Your Industry Domain Knowledge

## Standard Workflow
[What users actually do, step by step]

## False Positive Filters
[Things that look wrong but are correct in this domain]

## Priority Rules
[What counts as urgent in this domain]
```

## Output format

mesen produces **code-review style findings** — each finding is a suggestion, not a mandate:

```json
{
  "severity": "critical",
  "category": "one-screen",
  "title": "40 urgent items hidden below fold",
  "evidence": "Emergency block at position 4, needs scroll. Empty blocks occupy 180px above.",
  "reasoning": "Nurse checks tablet at 8am, must see urgent items in <3 seconds",
  "suggestion": "Move urgent block above empty state blocks",
  "dismissible_if": "User research confirms nurses check attendance before urgency"
}
```

The consuming agent decides what to act on based on project context.

## Tech stack

| Layer | Tool |
|-------|------|
| Language | TypeScript (ESM, Node 20+) |
| Monorepo | Turborepo + Bun workspaces |
| Browser | Vercel agent-browser (Rust CLI, 5.7x token efficiency) |
| VLM | Vercel AI SDK (provider-agnostic) |
| Lint | Biome (strict) |
| Test | Vitest |

## License

MIT