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

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 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, 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.

// 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)

// 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 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.

// 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.

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.

// 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 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 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.
• 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 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 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. This file contains the definitive spacing scales, color palettes, typography definitions, and corner radius values that AGENTS.md mandates for all UI development.

Can I add extensive comments to explain complex logic?

No. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}