Technical Reference

For technical users: How AsciiKit v5's intelligence system works under the hood. Most users never need this - the intelligence works automatically.

Architecture Overview

AsciiKit v5 uses three core MCP tools that work together:

Intelligence Tools (v5)

  • get_design_intelligence - Returns psychological guidance for context
  • get_visual_language - Provides wireframe drawing vocabulary
  • validate_wireframe - Ensures 38-character width compliance

How They Work Together

  1. You describe needs → Claude infers context
  2. Claude calls intelligence → Gets psychological guidance
  3. Claude designs → Applies psychology to wireframes
  4. Claude validates → Ensures proper formatting
  5. You see results → With reasoning explained

The entire process is automatic and invisible to users.

The Intelligence Engine

get_design_intelligence(context)

This is the brain of v5. Claude calls it automatically with:

{
  domain: "fintech",              // fintech, health, education, ecommerce, social, etc.
  user_segment: "seniors",        // seniors, anxious, beginners, power_users, etc.
  screen_type: "payment",         // dashboard, onboarding, checkout, form, settings, etc.
  emotional_target: "trust",      // trust, calm, excitement, confidence, etc.
  business_goal: "conversion",    // increase_signups, complete_purchase, reduce_churn, etc.
  platform: "mobile",             // mobile, desktop, responsive (affects IA only)
  user_goal: "complete payment",  // What the user is trying to accomplish
  culture: "us",                  // us, japan, india, germany, brazil, china, uk, middle_east
  include: ["psychology", "accessibility"]  // Optional: filter specific frameworks
}

All parameters are optional. Claude infers them from your description.

The Culture Parameter

The culture parameter activates culture-specific psychology:

  • us - Direct communication, individual achievement focus
  • japan - Indirect communication, group harmony, visual hierarchy
  • india - Family-oriented, festive elements, trust through relationships
  • germany - Precision, detailed information, systematic approach
  • brazil - Social proof, warmth, personal connection
  • china - Lucky numbers/colors, social validation, prosperity symbols
  • uk - Understated, queue-respectful, proper terminology
  • middle_east - Right-to-left considerations, privacy focus, family values

Note: If you specify an unlisted culture, no cultural adaptations are applied. The system uses generic psychology frameworks.

The Platform Parameter

The platform parameter accepts mobile, desktop, or responsive:

Mobile-First by Default (v5.2+): Since the 38-character wireframe format matches mobile screen sizes, AsciiKit applies mobile-first intelligence across all 6 frameworks by default. This includes:

  • Psychology: Biometric auth, offline mode, one-tap actions
  • Cognitive: Thumb zones, interruption handling, state preservation
  • Emotional: Touch spacing, battery/network awareness
  • IA: Bottom nav, swipe gestures, pull-to-refresh, FAB patterns
  • Conversion: Mobile-specific trust signals and persuasion tactics
  • Accessibility: Touch target sizing, mobile screen reader patterns

Desktop Override: Specify platform: "desktop" to apply desktop-specific patterns (keyboard shortcuts, hover states, multi-column layouts, etc.).

The Include Parameter (Advanced)

The include parameter allows filtering to specific intelligence frameworks:

{
  domain: "fintech",
  include: ["psychology", "accessibility"]
}

Available frameworks:

  • psychology - User Psychology Engine
  • information_architecture - IA patterns
  • cognitive - Cognitive optimization
  • emotional - Emotional design
  • conversion - Conversion psychology
  • accessibility - Accessibility framework

Behavior:

  • If omitted, all 6 frameworks are included
  • If provided, only specified frameworks are returned
  • Cultural adaptations are always included when culture is specified

Returns comprehensive psychological guidance:

  • Specific design principles to apply
  • Cognitive considerations
  • Emotional design tactics
  • Accessibility requirements
  • Domain-specific patterns
  • Culture-specific trust mechanics

get_visual_language()

Provides the complete wireframe drawing vocabulary:

  • Box drawing characters (┌─┐│└┘├┤┬┴┼)
  • Section separators and dividers
  • UI element representations
  • ASCII-only patterns (no emojis)
  • Compositional rules for combining elements

This ensures consistent visual representation across all wireframes.

validate_wireframe(wireframe)

Validates that every line is exactly 38 characters wide:

{
  wireframe: 'string' // The wireframe to validate
}

Auto-Fix Behavior

Important: This tool doesn't just validate - it automatically fixes common width issues:

What gets auto-fixed:

  • Lines with 37-39 characters (pads or truncates to 38)
  • Double pipe endings (││ → │)
  • Lines under 35 characters (adds padding)
  • Lines over 39 characters (truncates)

Returns one of three responses:

  • ✓ Auto-fixed: Returns corrected wireframe with explanation
  • ✓ Valid: Already correct, no changes needed
  • ✗ Failed: Unfixable errors (rare)

Example:

Input:  "│ Hello world │"                    (36 chars)
Output: "│ Hello world                      │"  (38 chars - auto-padded)

This ensures wireframes are automatically corrected without manual adjustment.

Note: All tool responses include a helpful intelligence reference footer that reminds Claude about available frameworks. This ensures Claude consistently applies all six frameworks throughout your session.

How the Intelligence Engine Works

When you run an /asciikit-* command, Claude:

  1. Infers context — Determines domain, user segment, emotional state, screen type, and business goals from your description
  2. Applies psychology — Six frameworks activate simultaneously and interact with each other
  3. Generates wireframes — Designs shaped by the combined intelligence output
  4. Explains reasoning — Every design decision is grounded in human psychology

The 5 commands handle everything. You just describe the human situation.

Intelligence Architecture

User describes needs
         ↓
Context inference (domain + users + emotions + goals)
         ↓
Six frameworks apply simultaneously:
  User Psychology + Cognitive Science + Emotional Design
  Information Architecture + Conversion + Accessibility
         ↓
Integrated intelligence guides wireframe generation
         ↓
Explained, reasoned design output

Technical Details

Six Intelligence Frameworks

Each framework contains specific psychological principles:

  1. User Psychology Engine

    • 31 unique psychological concepts
    • Trust mechanics, motivation drivers, cognitive biases

  2. Cognitive Science Layer

    • Information processing principles
    • Memory and attention management
    • Cognitive load optimization

  3. Emotional Design System

    • Three-level emotional response
    • Emotional journey mapping
    • Affect and mood management

  4. Information Architecture

    • Organization schemes
    • Navigation patterns
    • Wayfinding and orientation

  5. Conversion Psychology

    • Behavioral economics
    • Ethical persuasion principles
    • Decision architecture

  6. Accessibility Framework

    • WCAG compliance
    • Inclusive design patterns
    • Situational impairment handling

Intelligence Data Structure

The system contains 1,275 lines of psychological intelligence covering:

  • Domain-specific adaptations (5 major domains)
  • User segment profiles (4 core segments)
  • Cultural adaptations (8 markets)
  • Emotional state responses
  • Screen type optimizations
  • Business goal alignments

Technical Implementation: AsciiKit uses a composition engine to assemble wireframes from 100+ atomic visual elements, ensuring consistent structure while Claude focuses on applying the psychology.

For Developers

If you're building on top of AsciiKit or creating integrations:

The v5 API Contract

Commands accept natural language:

/asciikit-quick "Design a payment form for anxious users"

Claude returns:

  • Psychologically-optimized wireframes
  • Reasoning explanations
  • Multiple options when appropriate
  • Markdown-formatted output

No Direct Tool Access Needed

You don't need to:

  • Call individual MCP tools
  • Know pattern names
  • Specify psychology frameworks
  • Handle composition logic

Everything works through the 5 high-level commands.

Validation Rules

All wireframes must be exactly 38 characters wide:

┌────────────────────────────────────┐  ← 38 chars total
│ Content goes here (36 chars max)   │  ← 1 + 36 + 1 = 38
└────────────────────────────────────┘  ← 38 chars total

The 38-Character Formula

Formula: │ (1) + content (36) + │ (1) = 38 total

Why 38 characters?

  • Mobile-friendly width
  • Readable in Claude Code interface
  • Fits terminal windows
  • Consistent across all designs

The validate_wireframe tool automatically fixes common width issues, so you don't need to count characters manually.

Next Steps