Admin Cleanup Implementation Contract

This page defines the repeatable Admin cleanup contract for addon list, form, state, toolbar, pagination, modal, and notice behavior.

Related pages: Admin UI/Admin Addon View Developer Contract, Admin UI/Admin Form Actions Permissions and CSRF Rules, Admin UI/Admin UI Exception Process.

Purpose

This document turns the Admin view governance rules into a repeatable cleanup contract.

It exists so two independent implementers cleaning the same addon view produce the same structure, behavior, state handling, and visible UI pattern.

Use this document when converting existing addon Admin views onto the governed Admin template.

Authority Order

For Admin UI cleanup, read the documents in this order:

1. Governance - Admin View Template Standard.md
2. This document
3. Governance - Admin Shared List Behavior and State Rules.md
4. Governance - Admin Template Direction.md
5. Admin UI Scope.md

If documents appear to conflict, the stricter visible implementation rule wins.

If a document says a final shell design choice is still open, that does not allow addon-local drift in list, form, state, toolbar, pagination, modal, or notice behavior.

Cleanup Definition

An Admin view is cleaned up only when:

• the view uses the shared Admin visual pattern
• old local toolbar, search, sorting, pagination, and state display code is removed
• create and edit are separate from list screens
• normal users are not shown raw developer data by default
• state labels, markers, actions, and list state handling follow this contract
• the page can be checked against the final checklist in this document

Hiding old local UI code with CSS does not count as cleanup.

Standard List Layout

Every normal Admin list view must render the same structural order:

1. Admin shell header
2. breadcrumb
3. one task panel
4. eyebrow text
5. task title
6. notice area
7. toolbar row
8. optional filter row only when real filters exist
9. table or empty state
10. bottom pagination row
11. optional collapsed Advanced or developer section

The list panel must contain records only.

It must not contain create forms, edit forms, large explanations, diagnostic dumps, raw manifest data, schema dumps, or filesystem paths unless the page is explicitly a developer/history surface.

Toolbar Contract

The toolbar row must use this order:

1. left action group
2. flexible spacer
3. row-count selector
4. search input
5. filter trigger, only when real filters exist

The action group must use this order:

1. New or the shortest clear domain-specific create label
2. Edit
3. Delete, when deletion is allowed
4. lifecycle actions
5. secondary navigation actions

The row-count selector must:

• default to 10
• offer the shared option set used by the Admin template
• submit through the shared list behavior
• persist per user and per list

The search input must:

• appear to the right of the row-count selector
• use placeholder text
• not have a visible Search label in the compact toolbar
• submit on Enter
• preserve its value while sorting, paginating, changing row count, opening detail/edit, and returning to the list

Filters must:

• appear only when the owning view has real filterable states or categories
• preserve search, sort, page, and row-count state when changed
• reset page to 1 when the filter value changes unless the shared template says otherwise

Query and State Keys

Normal Admin list views must use these query keys unless an existing shared Admin helper requires different keys:

• q for search text
• page for current page
• per_page for row count
• sort for sort field
• dir for sort direction

Filter keys must use stable lowercase snake_case names.

Examples:

• state
• type
• group
• category

Sort direction values must be:

• asc
• desc

Do not invent per-addon alternatives such as searchText, limit, orderBy, direction, p, or rows for normal shared list screens.

Retained list state must be keyed by the stable Admin route or a documented list key, not by a translated title or temporary label.

Selection Behavior

When bulk actions exist, the first table column must be a checkbox column.

Selection behavior must follow this contract:

• New is always available when the user has create permission
• Edit is visible but disabled until exactly one row is selected
• Delete is visible but disabled until at least one row is selected, when deletion is allowed
• lifecycle actions are visible but disabled until the required number of rows is selected
• actions the user lacks permission to perform must not be executable

Disabled normal workflow buttons should remain visually present so users learn where actions live.

Do not hide standard workflow actions merely because no row is selected.

Table Contract

Tables must follow this column order:

1. checkbox column, only when row selection exists
2. primary title/name column
3. domain columns needed for scanning
4. state column, when the record has lifecycle state
5. updated/created/date column, when useful
6. compact row action column only when required by the domain

The primary title/name must:

• be human-readable
• be near the left
• be clickable when the user can open the record
• use the standard Admin link style

Normal list rows must not display these under the title by default:

• UUIDs
• slugs
• source keys
• route keys
• filesystem paths
• package hashes
• raw manifest keys
• raw database identifiers

Developer identifiers belong in Advanced, detail, diagnostics, or export views.

Sort Contract

Sortable headers must:

• preserve q, per_page, filter values, and page behavior
• use the shared fixed-width indicator
• not render visible ASC or DESC text beside the label
• not shift column width when sort direction changes

Clicking a sortable header should:

• sort ascending when the column is not currently sorted
• toggle between asc and desc when the same column is clicked again
• return to page 1 unless the shared Admin helper defines a different governed behavior

Pagination Contract

Pagination must appear below the table or empty state.

Pagination links must preserve:

• q
• per_page
• sort
• dir
• filter keys

Pagination must not appear only at the top of the list.

When there is only one page, the pagination area may be visually minimal, but it must not cause layout jumping between one-page and multi-page lists.

State Contract

Lifecycle columns must be titled State.

Do not use Status for lifecycle state.

The state cell must render:

[square marker] [Capitalized state label]

Marker rules:

• approximately 10px square
• approximately 3px radius
• inline before the label
• consistent spacing before the text
• never replaces the text label

Color meanings:

• green or emerald: Active, Published, Enabled, Visible
• gold or sand: Draft, Pending, Unreleased, Queued, Started
• red: Archived, Disabled, Hidden, Failed, Removed

State labels must be capitalized human words.

Do not render lowercase database values directly.

Notice Contract

Notice area location:

1. inside the task panel
2. below task title/eyebrow
3. above the toolbar

Notices must use the shared Admin notice style.

Simple success notices should clear after approximately 10 seconds when the workflow does not require the message to remain visible.

Notices must not permanently consume toolbar space after create, edit, delete, archive, publish, activate, disable, show, or hide actions.

Empty State Contract

Empty list states must be short.

Default empty state:

No records exist yet.

Optional second line:

Use New to create the first record.

Do not add long explanations inside the empty table area.

Create and Edit Contract

Create and edit screens must be separate routes or separate mounted views from the list screen.

Create screens create one record.

Edit screens edit one record.

Both must use this structure:

1. Admin shell header
2. breadcrumb
3. one task panel
4. eyebrow text
5. task title
6. notice area
7. compact form body
8. primary action row
9. optional collapsed Advanced section

Form action order:

1. primary save action
2. secondary cancel/back action
3. destructive action only when the domain has a written reason for placing it on the form

Cancel must return to the owning list and preserve list state.

Short fields should be grouped into compact multi-column rows where practical.

Long text, editor, JSON, Markdown, description, or body fields should span wider.

Advanced/developer fields must be collapsed or secondary unless the view itself is a developer tool.

Modal Contract

Modals must use the shared Admin modal frame.

Addon-owned modal content may vary, but these must not vary:

• overlay behavior
• theme colors
• contrast
• panel surface
• close affordance
• padding rhythm
• title placement

Do not use translucent modal content that blends into the table behind it.

Do not build an addon-local modal shell when the shared Admin modal shell can support the workflow.

Permission Contract

The view must check permissions before rendering executable actions.

Permission handling must not rely only on disabled buttons.

Normal behavior:

• hide or omit actions the user should never see
• show disabled actions only when the user has the permission but has not selected the required rows
• server-side handlers must recheck permission before mutation

Cleanup Checklist

Before a cleanup task is complete, verify:

• list screen contains records only
• create screen is separate
• edit screen is separate
• toolbar order matches this contract
• row-count default is 10
• query keys use q, page, per_page, sort, and dir
• search submits on Enter
• search state is retained
• row-count state is retained per list
• filters only appear when real filters exist
• pagination appears at the bottom
• pagination preserves list state
• sortable headers use the shared fixed-width indicator
• table columns follow the standard order
• normal row title does not expose machine identifiers
• lifecycle column is titled State
• state labels are capitalized
• state marker appears before the state label
• state marker color follows the shared meaning
• Edit requires exactly one selected row
• bulk actions require selected rows
• notices appear above the toolbar
• simple success notices clear after the standard duration
• form actions follow the standard order
• cancel preserves list state
• advanced/developer data is secondary
• old local toolbar code is removed
• old local search code is removed
• old local pagination code is removed
• old local sort indicator code is removed
• old local dead JavaScript is removed

Final Rule

Admin cleanup is not finished when an addon looks better.

Admin cleanup is finished when the addon cannot be distinguished from the shared Amvionlie Admin pattern except by its data, fields, actions, and domain-specific workflow.