# What Is AGENTS.md in Palmier Pro? A Developer's Architecture Guide

> Discover AGENTS.md in Palmier Pro, the architectural contract ensuring UI consistency drag-and-drop functionality and coding standards for developers. Understand its core purpose.

- Repository: [Palmier/palmier-pro](https://github.com/palmier-io/palmier-pro)
- Tags: architecture
- Published: 2026-06-30

---

**AGENTS.md is the central architectural contract that enforces UI consistency, drag-and-drop behavior, and coding standards across the Palmier Pro codebase.**

This file serves as the definitive rulebook for contributors to the **palmier-io/palmier-pro** repository, codifying everything from design system usage to platform-specific workarounds for macOS 26. By mandating strict adherence to `AppTheme` constants and native AppKit implementations for complex interactions, [`AGENTS.md`](https://github.com/palmier-io/palmier-pro/blob/main/AGENTS.md) ensures the professional video editing application maintains visual coherence and technical reliability as it scales.

## Design System Enforcement Through AppTheme

The document mandates that all UI elements must derive their visual properties from the centralized `AppTheme` rather than using hard-coded values. This rule guarantees consistent spacing, typography, and color application across every view in the application.

In [`Sources/PalmierPro/UI/AppTheme.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/UI/AppTheme.swift), the design system defines constants for **spacing**, **colors**, **fonts**, and **corner radii**. Every new component must reference these constants to maintain the established visual language.

```swift
// Correct – follows AGENTS.md by using AppTheme constants
let button = Button("Export") {
    // action
}
.buttonStyle(.bordered)
.padding(AppTheme.Spacing.l)
.background(AppTheme.Background.secondary)
.cornerRadius(AppTheme.Radius.m)

```

```swift
// Incorrect – violates the architecture guide with hard-coded values
let button = Button("Export") { }
.buttonStyle(.bordered)
.padding(24)
.background(Color.gray)
.cornerRadius(8)

```

## Drag-and-Drop Architecture for macOS 26

[`AGENTS.md`](https://github.com/palmier-io/palmier-pro/blob/main/AGENTS.md) documents a critical platform limitation in macOS 26 where a parent SwiftUI `.onDrop` modifier masks all child `.onDrop` modifiers within its view hierarchy. This behavioral constraint requires developers to implement container-level drop targets using native AppKit instead of stacking SwiftUI drop modifiers.

The guideline specifically directs developers to use `NSDraggingDestination` protocol implementations for parent views that contain nested drop zones. This approach prevents event interception while allowing leaf views to continue using standard SwiftUI `.onDrop` modifiers.

```swift
// Parent container implements native AppKit dragging
class MediaPanelDropArea: NSView, NSDraggingDestination {
    // NSDraggingDestination methods handle container-level drops
}

// Child views remain in SwiftUI with standard modifiers
struct ClipThumbnail: View {
    var body: some View {
        Image("clip")
            .onDrop(of: [.fileURL], isTargeted: $isTargeted) { providers in
                // handle drop
                true
            }
    }
}

```

You can see this implementation pattern in [`Sources/PalmierPro/MediaPanel/MediaPanelDropArea.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/MediaPanel/MediaPanelDropArea.swift).

## Voice and Communication Standards

The document prescribes a specific **"voice"** for all user-facing messages and logs: direct, technical, and calm. This standard ensures that error messages, notifications, and logs maintain a professional tone consistent with a professional video editing tool.

```swift
// Compliant – direct and technical tone
logger.info("Import completed: 12 files added, 0 errors.")

// Non-compliant – overly casual or decorative
logger.info("All done! 🎉 Your files are now safely in the library.")

```

## Code Style and Documentation Rules

[`AGENTS.md`](https://github.com/palmier-io/palmier-pro/blob/main/AGENTS.md) enforces minimal commenting practices, requiring single-line "why" notes only when necessary. The document strictly prohibits explanatory comments that describe what code does, assuming the code itself should be self-documenting through clear naming and structure.

Key requirements include:

- **No hard-coded values** – All numeric literals for UI dimensions must use `AppTheme` constants
- **Minimal comments** – Explain intent, not mechanics
- **Strict architecture adherence** – Follow the drag-and-drop patterns for macOS 26 compatibility

## Summary

- **AGENTS.md** serves as the binding architectural contract for the **palmier-io/palmier-pro** repository, ensuring consistency across all contributions.
- The document mandates use of **AppTheme** constants defined in [`Sources/PalmierPro/UI/AppTheme.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/UI/AppTheme.swift) to eliminate hard-coded UI values.
- Developers must implement container drop targets using **AppKit's `NSDraggingDestination`** protocol to work around macOS 26 SwiftUI limitations, as demonstrated in [`Sources/PalmierPro/MediaPanel/MediaPanelDropArea.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/MediaPanel/MediaPanelDropArea.swift).
- All user-facing text must follow the **direct, technical, calm** voice guidelines.
- Code comments should be minimal and focus only on explaining "why," not "what."

## Frequently Asked Questions

### What happens if I use hard-coded values instead of AppTheme constants?

Hard-coded values violate the architectural contract established in [`AGENTS.md`](https://github.com/palmier-io/palmier-pro/blob/main/AGENTS.md) and will result in UI inconsistencies across the application. The document requires all spacing, colors, and radii to reference `AppTheme` to ensure the interface remains maintainable and visually coherent as the codebase evolves.

### Why does AGENTS.md require AppKit for some drag-and-drop implementations?

Due to a platform limitation in **macOS 26**, parent SwiftUI `.onDrop` modifiers intercept drop events before they reach child views, effectively disabling nested drop targets. [`AGENTS.md`](https://github.com/palmier-io/palmier-pro/blob/main/AGENTS.md) directs developers to use `NSDraggingDestination` for container views to ensure proper event handling while preserving SwiftUI `.onDrop` functionality for leaf nodes.

### Where are the AppTheme constants defined in the repository?

All theme constants are centralized in [`Sources/PalmierPro/UI/AppTheme.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/UI/AppTheme.swift). This file contains the definitive spacing scales, color palettes, typography definitions, and corner radius values that [`AGENTS.md`](https://github.com/palmier-io/palmier-pro/blob/main/AGENTS.md) mandates for all UI development.

### Can I add extensive comments to explain complex logic?

No. [`AGENTS.md`](https://github.com/palmier-io/palmier-pro/blob/main/AGENTS.md) enforces a minimal commenting policy that permits single-line "why" notes only when the code's intent is not immediately obvious from its structure. The guideline prioritizes self-documenting code through clear naming conventions over explanatory comments.