IMD Framework

Inclusive Manual Design (IMD) is a TypeScript framework for creating, validating, and rendering accessible user manuals for technical products. The framework ensures WCAG 2.1 AA compliance, cognitive accessibility, and compatibility with assistive technologies.

Features

• 📋 Structured Schema: Define manuals using the Inclusive Manual Schema (UMS) with TypeScript/JSON
• ✅ Validation Engine: Ensure completeness and accessibility compliance before rendering
• 🎨 Multi-Format Rendering: Generate accessible HTML and plain text output
• ♿ Accessibility First: Built-in WCAG compliance checking and accessibility scoring
• 🛠️ Utility Tools: Text simplification, screen reader formatting, and more
• 🖥️ CLI Interface: Command-line tools for validation and rendering

Quick Start

Installation

npm install

Build

npm run build

Test

npm test

Usage

Creating a Manual

Define your manual using the UMS schema in JSON format:

{
  "metadata": {
    "name": "Product Name",
    "version": "1.0.0",
    "manufacturer": "Your Company",
    "description": "Product description",
    "productType": "Web Application"
  },
  "targetAudiences": [
    {
      "profile": "End users",
      "accessibilityNeeds": ["screen-reader", "keyboard-navigation"],
      "technicalLevel": "beginner"
    }
  ],
  "instructions": [
    {
      "id": "step-1",
      "order": 1,
      "title": "First Step",
      "content": "Step instructions...",
      "mediaReferences": ["img-1"],
      "estimatedTime": "2 minutes"
    }
  ],
  "media": [
    {
      "id": "img-1",
      "type": "image",
      "source": "image.png",
      "altText": "Description of image for screen readers"
    }
  ],
  "safetyGuidelines": [],
  "troubleshooting": [],
  "accessibilityFeatures": {
    "screenReaderSupport": true,
    "keyboardNavigation": true,
    "highContrast": true,
    "textAlternatives": true,
    "cognitiveAccessibility": true
  }
}

Validating a Manual

import { SchemaValidator } from './src/schema/validator';
import { ManualSchema } from './src/schema/types';

const validator = new SchemaValidator();
const manual: ManualSchema = /* your manual data */;

const result = validator.validate(manual);
if (result.valid) {
  console.log('Manual is valid!');
} else {
  console.error('Validation errors:', result.errors);
}

Rendering to HTML

import { HTMLRenderer } from './src/renderer/html-renderer';
import { ManualSchema } from './src/schema/types';

const renderer = new HTMLRenderer();
const manual: ManualSchema = /* your manual data */;

const html = renderer.render(manual, {
  theme: 'high-contrast',
  includeTableOfContents: true
});

// Write to file or serve via web server

Rendering to Plain Text

import { PlainTextRenderer } from './src/renderer/plain-text-renderer';
import { ManualSchema } from './src/schema/types';

const renderer = new PlainTextRenderer();
const manual: ManualSchema = /* your manual data */;

const text = renderer.render(manual);

// Output is braille-compatible and screen-reader optimized

Using Accessibility Utilities

import { TextSimplifier } from './src/utils/text-simplifier';
import { ScreenReaderFormatter } from './src/utils/screen-reader-formatter';
import { WCAGChecker } from './src/utils/wcag-checker';
import { AccessibilityScorer } from './src/utils/accessibility-scorer';

// Simplify complex text
const simplifier = new TextSimplifier();
const simplified = simplifier.simplify('Complex technical jargon...');

// Format for screen readers
const formatter = new ScreenReaderFormatter();
const formatted = formatter.format('Text with abbreviations...');

// Check WCAG compliance
const wcagChecker = new WCAGChecker();
const compliance = wcagChecker.checkCompliance(manual);

// Calculate accessibility score
const scorer = new AccessibilityScorer();
const score = scorer.calculateScore(manual);
console.log(`Accessibility score: ${score.overallScore}%`);

Examples

The framework includes example manuals demonstrating different use cases:

Web Tool Example (examples/web-tool.json)

A simple task management web application manual demonstrating:

• Basic UMS structure
• Web application documentation
• Keyboard shortcuts and navigation
• Form accessibility

IoT Device Example (examples/iot-device.json)

A smart home hub manual demonstrating:

• Physical product documentation
• Setup and installation instructions
• Voice control and audio feedback
• Multi-modal accessibility features

To validate the examples:

import { SchemaValidator } from './src/schema/validator';
import * as fs from 'fs';

const validator = new SchemaValidator();
const webTool = JSON.parse(fs.readFileSync('examples/web-tool.json', 'utf-8'));
const iotDevice = JSON.parse(fs.readFileSync('examples/iot-device.json', 'utf-8'));

console.log('Web Tool validation:', validator.validate(webTool));
console.log('IoT Device validation:', validator.validate(iotDevice));

Project Structure

imd-framework/
├── src/
│   ├── schema/           # UMS schema type definitions and validation
│   │   ├── types.ts      # TypeScript interfaces for UMS
│   │   ├── validator.ts  # Schema validation engine
│   │   └── serializer.ts # JSON serialization utilities
│   ├── utils/            # Accessibility utilities
│   │   ├── text-simplifier.ts          # Plain language conversion
│   │   ├── screen-reader-formatter.ts  # Screen reader optimization
│   │   ├── wcag-checker.ts             # WCAG compliance checking
│   │   └── accessibility-scorer.ts     # Accessibility scoring
│   ├── renderer/         # Output format renderers
│   │   ├── index.ts              # Renderer interface
│   │   ├── html-renderer.ts      # HTML output generator
│   │   └── plain-text-renderer.ts # Plain text output generator
│   └── cli/              # Command-line interface
│       └── index.ts      # CLI commands
├── examples/             # Example manuals
│   ├── web-tool.json     # Web application example
│   └── iot-device.json   # IoT device example
└── tests/                # Test suites

Schema Reference

ManualSchema

The root schema object containing all manual data.

Required Fields:

• metadata: Product information (name, version, manufacturer, description, productType)
• targetAudiences: Array of target audience profiles with accessibility needs
• instructions: Array of instruction steps with ordering and content
• media: Array of media elements with accessibility metadata
• safetyGuidelines: Array of safety warnings and cautions
• troubleshooting: Array of troubleshooting flows
• accessibilityFeatures: Declaration of supported accessibility features

Validation Rules

The validator enforces:

• All required fields must be present
• All MediaElement entries must have altText
• InstructionStep order must be sequential (1, 2, 3, ...)
• All mediaReferences must point to existing MediaElement IDs
• Product metadata fields must be non-empty strings

Accessibility Features

All rendered output includes:

• HTML: Semantic HTML5, ARIA landmarks, skip links, keyboard navigation, responsive design, high-contrast themes
• Plain Text: Linear structure, braille-compatible whitespace, text descriptions for media, consistent indentation

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Building

# Build TypeScript to JavaScript
npm run build

# Build and watch for changes
npm run build:watch

Linting

# Run ESLint
npm run lint

# Fix linting issues
npm run lint:fix

Contributing

Contributions are welcome! Please ensure:

• All tests pass
• New features include tests
• Code follows the existing style
• Accessibility is prioritized in all changes

License

MIT

Support

For issues, questions, or contributions, please visit the project repository.