qdr.app.tools/UILayoutDefinitionFormat/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the UI Layout Definition Format repository - a comprehensive XML-based format for describing cross-platform user interfaces with inheritance, validation, and modern development practices. Version 1.3 includes advanced features like state management, accessibility compliance, AI assistance, and performance optimization.

Architecture

Core Components

XML Schema Definitions (.xsd files)

• ui-layout-def.xsd - Main schema definition with root elements and structure
• ui-layout-patterns.xsd - Pattern definitions for controls, structures, and wireframes
• ui-layout-views.xsd - Advanced view definitions with state management and AI features
• ui-layout-validation.xsd - Validation rules, custom validators, and profiles
• ui-layout-basic-controls.xsd - Basic UI control definitions
• ui-layout-avalonia-controls.xsd - Avalonia platform-specific controls
• ui-layout-winforms-controls.xsd - Windows Forms platform-specific controls

Definition Files (Definitions/ folder)

• abstract-controls.xml - Base control definitions with common attributes and behaviors
• avalonia-controls.xml - Avalonia UI platform-specific control implementations
• web-controls.xml - Web platform control definitions
• winform-controls.xml - Windows Forms control definitions

Sample Files (Samples/ folder)

• sample.xml - Comprehensive v1.3 sample showcasing all features
• business-views.xml - Business logic view examples
• Various platform-specific samples (kde-controls.xml, web-controls.xml, etc.)

Key Architecture Principles

1. Modular Design: External includes allow splitting definitions across multiple files
2. Platform Abstraction: Unified control definitions with platform-specific implementations
3. View-First Architecture: Business views organize related windows and define data context
4. Pattern-Based Design: All controls must be defined in patterns before use
5. Comprehensive Validation: Advanced validation system with custom validators and profiles

Development Commands

XML Validation

# Validate XML files against XSD schemas using XMLStarlet
xmlstarlet val -e -s ui-layout-def.xsd Samples/simple-working.xml
xmlstarlet val -e -s ui-layout-def.xsd Samples/sample-minimal.xml

# Validate all schema files
xmlstarlet val -e ui-layout-*.xsd

# Alternative with xmllint if XMLStarlet unavailable
xmllint --schema ui-layout-def.xsd Samples/simple-working.xml --noout

Schema Validation Status

# All schema files are valid ✅
xmlstarlet val -e ui-layout-def.xsd
xmlstarlet val -e ui-layout-basic-controls.xsd
xmlstarlet val -e ui-layout-patterns.xsd
xmlstarlet val -e ui-layout-views.xsd
xmlstarlet val -e ui-layout-validation.xsd
xmlstarlet val -e ui-layout-avalonia-controls.xsd
xmlstarlet val -e ui-layout-winforms-controls.xsd

# Working sample file ✅
xmlstarlet val -e -s ui-layout-def.xsd Samples/simple-working.xml

XML Processing and Querying

# Query XML structure using XMLStarlet
xmlstarlet sel -t -m "//control" -v "@name" -n abstract-controls.xml
xmlstarlet sel -t -m "//window" -v "@name" -n sample.xml

# Format/pretty-print XML files
xmlstarlet fo sample.xml > formatted-sample.xml

File Structure Understanding

• Root Schema: ui-layout-def.xsd defines the main document structure
• External Schemas: Platform-specific and feature-specific schemas are imported
• Control Hierarchy: All controls inherit from CommonControl in abstract-controls.xml
• Validation System: Custom validators and profiles in validation includes
• Sample Implementation: sample.xml demonstrates v1.3 features including AI assistance, accessibility, and performance optimization

Important Development Notes

Schema Versioning

• Current version: 1.3
• Schema version must match in schema-version attribute
• Platform compatibility defined in platform-constraints

Validation Requirements

• All interactive controls require accessibility attributes for WCAG compliance
• Performance targets recommended for data-heavy views
• Security attributes required for high-security applications

Control Definition Process

1. Define abstract control in Definitions/abstract-controls.xml
2. Add platform-specific implementations in appropriate control files
3. Update schema definitions to include new control types
4. Add validation rules for new attributes

v1.3 Enhancements

• Advanced state management with Redux/MobX patterns
• Comprehensive accessibility framework (WCAG 2.1 AA/AAA)
• Performance optimization system with metrics and targets
• Security framework with GDPR compliance
• Enhanced testing framework with automation support
• Advanced localization with RTL support

When working with this codebase, always validate XML against schemas and ensure new features follow the established patterns for platform abstraction and modular design.