# PlantUML Syntax Guidelines for Web4

## Common Pitfalls and Solutions

1. Color Syntax
```plantuml
' INCORRECT - will cause errors
actor MyActor #lightred
class MyClass #lightgreen

' CORRECT - use backgroundColor or standard colors
class MyClass {
    backgroundColor Pink    ' Not lightred
}
actor "MyActor" as act1 
skinparam actor {
    BackgroundColor White
    BorderColor Black
}
```

2. Skinparam Settings
```plantuml
' INCORRECT - incomplete configuration
skinparam usecase {
    BackgroundColor blue    ' Non-standard color
}

' CORRECT - proper configuration
skinparam defaultFontName Arial
skinparam usecase {
    BackgroundColor LightBlue   ' Standard PlantUML color
    BorderColor Gray
}
```

3. Stereotypes and Documentation
```plantuml
' INCORRECT - invalid stereotype syntax
class MyClass #red <<@ref123>>

' CORRECT - proper stereotype and metadata
class MyClass <<UCP101>> {
    backgroundColor Pink
}
```

## Actor Styling

1. Use Stereotypes for Colors:
```plantuml
' CORRECT - stereotype-based coloring
actor "MyActor" as act1 <<component>>
skinparam actorBackgroundColor<<component>> Pink

' INCORRECT - direct color assignment
actor MyActor #Pink
```

2. Theme Inheritance:
```plantuml
' CORRECT - inherit from theme
!include /Users/Shared/EAMD.ucp/Documentation/ModelRepository/Web4Theme.puml

' Local overrides only if needed
skinparam actor {
    BorderColor Black
}
```

## Path and Include Handling

1. Define Path Macros:
```plantuml
' CORRECT - path macro definitions
!define BASE_PATH(aPath) /Users/Shared/aPath
!define EAMD_ROOT(aPath) BASE_PATH(EAMD.ucp)/aPath

' INCORRECT - string concatenation
!define EAMD_ROOT "/Users/Shared/" + "EAMD.ucp"
```

2. Include Files:
```plantuml
' CORRECT - using path macros
!include MODEL_DIR(Web4Theme.puml)

' INCORRECT - direct path
!include /Users/Shared/EAMD.ucp/Theme.puml
```

## Best Practices

1. Stereotypes:
   - Use stereotypes for classification
   - Define colors through skinparam
   - Group related stereotypes
   - Document stereotype meanings in legend

2. Color Assignment:
   - Use skinparam for colors
   - Apply colors through stereotypes
   - Avoid direct color assignments
   - Use standard PlantUML colors

3. Style Organization:
   - Theme defines base styles
   - Local files only override when needed
   - Keep style definitions grouped
   - Document style choices

1. Color Definitions:
   - Use standard PlantUML colors (Pink, LightGreen, LightBlue)
   - Define colors through skinparam or backgroundColor
   - Avoid direct color assignments with #

2. Component Organization:
   - Define skinparam settings at the start
   - Group related elements together
   - Use consistent naming conventions
   - Add legends for color/stereotype meanings

3. Relationship Syntax:
```plantuml
' Basic relationships
A -- B      ' Association
A --|> B    ' Inheritance
A ..|> B    ' Implementation
A --* B     ' Composition
A --o B     ' Aggregation

' With labels
A "1" --* "many" B : owns >
```

4. View Organization:
```plantuml
' Group related elements
rectangle "Domain" {
    usecase UC1
    usecase UC2
}

' Add legends
legend right
    Symbol1 = Meaning1
    Symbol2 = Meaning2
endlegend
```

## Styling Best Practices

1. Global Styling:
```plantuml
@startuml
' Define styles at diagram level
skinparam defaultFontName Arial
skinparam class {
    BackgroundColor Pink
    BorderColor Gray
}
skinparam interface {
    BackgroundColor LightGreen
    BorderColor Gray
}
```

2. Separation of Concerns:
   - Keep model elements clean (no styling in class/interface definitions)
   - Use skinparam for consistent styling
   - Group all styling directives at the start of the file
   - Use stereotypes for classification, not styling

3. Theme Management:
```plantuml
' Define a complete theme
skinparam {
    ClassBackgroundColor Pink
    ClassBorderColor Gray
    InterfaceBackgroundColor LightGreen
    InterfaceBorderColor Gray
    ComponentBackgroundColor Yellow
    ComponentBorderColor Gray
}
```

## Theme Management

1. Central Theme:
   - All Web4 diagrams should include the central theme file:
   ```plantuml
   @startuml
   !include /Documentation/ModelRepository/Web4Theme.puml
   
   ' Your diagram content here
   @enduml
   ```

2. Using Path Macros:
```plantuml
' In preproc.puml
!define MODEL_DIR(aPath) EAMD_ROOT(Documentation/ModelRepository)/aPath
!define THEME_FILE MODEL_DIR(Web4Theme.puml)

' In diagrams
!include THEME_FILE
```

3. Theme Location:
   - Theme file location: `/Documentation/ModelRepository/Web4Theme.puml`
   - Theme should be included at the start of each diagram
   - Local overrides can be added after theme inclusion

## Include Best Practices

1. Use Full System

## Basic Setup
```plantuml
@startuml
' Include configuration
!include config.puml

' Rest of diagram
```