# 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**
```bash
# Validate XML files against XSD schemas using XMLStarlet
xmlstarlet val -e -s ui-layout-def.xsd sample.xml
xmlstarlet val -e -s ui-layout-def.xsd Samples/*.xml

# Alternative with xmllint if XMLStarlet unavailable
xmllint --schema ui-layout-def.xsd sample.xml --noout
```

**Schema Validation**
```bash
# Validate individual schema files
xmlstarlet val -e -s http://www.w3.org/2001/XMLSchema.xsd ui-layout-def.xsd
xmllint --schema http://www.w3.org/2001/XMLSchema.xsd ui-layout-def.xsd --noout
```

**XML Processing and Querying**
```bash
# 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.