Admin UI Exception Process

This page defines how Admin UI exceptions are requested, documented, approved, and reviewed before implementation.

Related pages: Admin UI/Admin Cleanup Implementation Contract, Admin Workflow/Admin UI Scope.

Purpose

This document defines how exceptions to the Admin UI standard are requested, documented, approved, and reviewed.

It exists so addon developers cannot create local drift by claiming their workflow is special without a written governance decision.

Core Rule

Admin UI exceptions are not granted by casual chat, taste, convenience, or addon-local preference.

An exception requires a written governance update before implementation.

Until the written exception exists, implementers must follow the locked Admin view and cleanup contracts.

What Requires an Exception

An exception is required before changing a normal Admin view away from the standard for:

• toolbar layout
• button order
• row-count default
• query key names
• search placement
• search submit behavior
• filter placement
• pagination placement
• sort indicator style
• state column name
• state marker style
• state label casing
• list/create/edit separation
• notice placement
• modal frame behavior
• form action order
• exposing developer data by default
• embedding create/edit forms inside list views

What Does Not Require an Exception

The owning addon may decide:

• what records it manages
• what columns are needed
• what fields are needed
• what filters are real
• what lifecycle actions exist
• what permissions it declares
• what validation rules its domain requires
• what public routes it provides
• what advanced/developer data exists when placed in the correct surface

Domain choices do not require an exception when they remain inside the shared Admin structure.

Exception Record Requirements

A written exception must name:

• addon or Admin surface
• route or view affected
• exact standard being waived
• reason the standard cannot support the workflow
• whether the exception is temporary or permanent
• whether a shared Admin capability should be added instead
• owner responsible for revisiting the exception
• review date or release milestone when temporary

Temporary Exception Rule

Temporary exceptions must include:

• what is allowed for now
• what shared capability is missing
• how the temporary implementation must avoid spreading
• when it must be revisited

Temporary exception code must be easy to find and remove.

Do not copy temporary exception patterns into other addons.

Permanent Exception Rule

Permanent exceptions should be rare.

A permanent exception is appropriate only when the standard Admin pattern truly cannot support the domain without harming the user experience or the platform model.

If multiple addons request the same permanent exception, it is probably not an exception. It is probably a missing shared Admin capability.

Shared Capability Rule

When a view cannot follow the standard because the shared template lacks a needed capability, the preferred answer is to improve the shared Admin layer.

Examples:

• add a shared filter row pattern
• add a shared modal variation
• add a shared state helper
• add a shared bulk action confirmation pattern
• add a shared developer diagnostics pattern
• add a shared form section pattern

Do not solve shared capability gaps by copying local UI code across addons.

Review Checklist

Before approving an exception, verify:

• the standard being waived is named
• the affected view is named
• the domain reason is specific
• the exception does not hide an avoidable shared-template gap
• the exception does not weaken security, permissions, CSRF, or install/update governance
• the exception has a temporary or permanent classification
• temporary exceptions have a review point
• the documentation is updated before implementation

Final Rule

An Admin UI exception is a governance change, not an implementation shortcut.