Humanstandards

Human factors research translated into practical design standards, implementation guidance, and read-only context for AI agents.

Explore the live library · Connect the MCP server · Review Study 001

Built with Starlight

Is Human Standards useful to you? Star the project on GitHub to save it for later and help other practitioners discover it. You can also watch the repository for future releases or join the public Discussions.

Study 001 is recruiting two blinded independent reviewers. The study asks whether access to human-factors guidance changes the quality of AI-built interfaces. Reviewers score nine opaque artifacts against a frozen rubric; mixed, null, and negative results will be published alongside positive ones. Read the independent-reviewer brief.

Why Human Standards exists

Product teams have access to extensive research on cognition, ergonomics, accessibility, usability, and human-computer interaction. Turning that evidence into a concrete design decision is still difficult—and AI-assisted product work makes the gap more visible.

Human Standards is an open-source reference library designed to make that knowledge easier to inspect and apply. People can browse the guidance directly. Compatible AI tools can retrieve the same material through a local, read-only MCP server.

The project does not claim to replace user research, accessibility testing, professional judgment, or the standards and studies it cites.

What is included

• Human factors guidance — Cognition, perception, emotion, decision-making, ergonomics, accessibility, and social context
• Design and implementation guidance — Interaction patterns, playbooks, code examples, and design-token constraints
• Research methods — Usability testing, cognitive walkthroughs, metrics, and evaluation guidance
• Evidence and references — Links to the standards, publications, and source material behind the guidance
• Machine-readable access — Five read-only MCP tools for search, retrieval, heuristics, and relationship-first spatial-rhythm guidance
• Open evaluation — Study protocols and evidence intended for independent review and reproducible analysis

Current status

Human Standards is actively developed and should be treated as a working reference library, not a finished or universally validated standard.

• The documentation library is available at humanstandards.org.
• The MCP server currently runs from source and does not write to projects or external services.
• Study 001 is at the blinded independent-review stage. No final result will be published before the review, analysis, and reproduction gates are complete.
• Gaps, corrections, competing evidence, and well-scoped contributions are welcome.

Use the documentation library

Start with Getting Started or browse the library by topic. Every page is designed to connect principles with practical decisions, implementation guidance, and primary or established sources where available.

To run the site locally:

git clone https://github.com/aklodhi98/humanstandards.git
cd humanstandards
npm ci
npm run dev

Open http://localhost:4321 to view the local site.

Use the MCP server

The MCP server exposes the library to compatible AI tools through five read-only tools:

• search_standards
• get_standard
• get_heuristic
• get_all_heuristics
• get_spatial_rhythm

Install and build it from the repository:

git clone https://github.com/aklodhi98/humanstandards.git
cd humanstandards/human-standards-mcp
npm ci
npm run build
npm run index-docs

Then configure a compatible MCP client to run the built entry point:

{
  "mcpServers": {
    "human-standards": {
      "command": "node",
      "args": ["/absolute/path/to/humanstandards/human-standards-mcp/dist/index.js"]
    }
  }
}

See the MCP setup guide for client-specific instructions and tool examples.

Project commands

Command	Action
npm ci	Install the documentation-site dependencies from the lockfile
npm run dev	Start the local site at localhost:4321
npm run build	Build the production site to ./dist/
npm run check	Build the site and validate internal links
npm run preview	Preview the production build locally
npm run build --prefix human-standards-mcp	Compile the MCP server
npm test --prefix human-standards-mcp	Run the MCP server tests after it has been built

Contributing

Useful contributions include:

• correcting inaccurate, ambiguous, or outdated guidance;
• adding stronger primary or established sources;
• improving examples and implementation details;
• identifying missing contexts, limitations, or accessibility considerations;
• reporting defects in the website, standards index, or MCP server.

Read CONTRIBUTING.md for the contribution workflow, evidence expectations, content structure, and local checks. Questions and early ideas can start in GitHub Discussions; concrete defects belong in Issues.

Licensing and attribution

• Original documentation and standards data: CC0 1.0 Universal
• Software and code examples: MIT License
• Third-party material: retained under its original terms and documented in THIRD_PARTY_LICENSES.md

Human Standards builds on work across human factors, cognitive psychology, HCI, UX, and accessibility. Source citations are included throughout the library, with broader starting points in the academic research references and standards and guidelines.

Built with Astro and Starlight. Maintained by AK Lodhi.