**Source ticket:** #3585814[ — UI/Workflow: Multi-page overview view (review status across content)](https://git.drupalcode.org/project/ai_content_review/-/work_items/3585814) **Status:** Draft for review **Author:** Aidan Foster **Date:** 2026-05-22 --- ## **1. Purpose** Editors need to scan many pieces of content at once and see, at a glance, which items have review problems. An aggregate score alone is misleading when one critical category fails (per Bruno's working-session note: "you could get sued if inclusive language fails even with average passing"). This document specifies the **pill widget** that renders next to each row of a content listing. The widget summarizes the row's review status as counts of pass / warn / fail categories and (optionally) an aggregate score. A drilldown reveals the per-category breakdown without leaving the listing. The widget is a **summary surface only**. It does not show full feedback text and it does not provide a way to act on suggestions. The list view shows the most recent stored results for each row — it does **not** live-stream reviews that are currently running. ## **2. Scope** ### **In scope** * The pill widget rendering on each content row (segmented bar, numeric labels, optional aggregate score). * The drilldown (tooltip or popover) showing the per-category breakdown. * Empty / not-yet-reviewed state with a "Run reviews" affordance. * Stale state handling at the per-criterion level. * Sort and filter integrations on the listing for the data the widget exposes. ### **Out of scope** * The full per-row review experience (running reviews interactively, reading full feedback, acting on suggestions). The widget hands off to that experience; this document does not specify it. * Live-streaming of in-progress reviews into the listing. The list view is a snapshot of stored results; rows update when the underlying data updates and the listing reloads. * Bulk operations across multiple rows. Captured as a future subtask in §10. * A net-new admin dashboard. The widget is intended to extend the standard content listing, not introduce a parallel one. ### **Assumptions** * The Drupal AI module is available and configured with at least one provider. * Some persistent storage exists per entity for per-category review results. The exact data model — entity types, fields, relationships — is **not assumed by this document** and is owned by the implementation specs that follow. * For this milestone, AI Content Review operates **independently of the Context Control Center (CCC)**. Criterion definitions, labels, and rules live within the module's own configuration. CCC integration is deferred and out of scope here. ## **3. Entry workflows** Unlike per-item views, the listing always contains rows for entities that already exist. There are two row-level entry conditions an editor will encounter when the listing loads: ### **Workflow A — Row with a prior review** The content item has stored results from a prior review. The pill renders the most recent tally. The drilldown is available. ### **Workflow B — Row with no review yet** The content item has never been reviewed (or its prior review was invalidated wholesale). The pill renders in an empty / placeholder state with a "Run reviews" affordance on the row. ## **4. Layout and components** ### **4.1 The pill widget** * **One pill per content row.** Width fixed to the column. The column should reserve enough space for the widest expected pill in the current viewport * **Segments inside the pill** are sized proportionally to the count of categories in each state. Possible segments: * **Pass** (green) * **Warn** (yellow) — only present if at least one category in the row is configured with a warn threshold * **Fail** (red) * **Not reviewed** (gray) — covers categories that have never been run on this row AND categories whose stored result has been invalidated by a configuration change (see §5 Stale). * **Numeric labels** are always present — inside or beside each segment, depending on segment width. Numbers carry the truth even when color is not perceivable. The convention used in the comps is **fail / warn / pass**, with the gray "not reviewed" count surfaced alongside (e.g. `7 / 2 / 1 + 2 to review`). Exact label format is a comp-detail decision; the requirement is that every count present in the pill is also expressed numerically. * **At extreme category counts** (≥ 15) segment proportions become approximate; the numeric labels remain accurate. Treating numbers as authoritative is a hard rule. ### **4.2 Aggregate score (optional)** * A small numeric label beside the pill (e.g. `78%`) that the configuration can opt into per content type. * Primarily a sort handle. **Not** the primary signal — the segmented pill is. * When only one category is configured, the aggregate score is redundant; the widget should mute or hide it (see §8 and §12). * When the row has gray segments (criteria not yet reviewed or stale), the aggregate score is computed only from the criteria with current results. The widget should indicate that the score is partial (see §12). ### **4.3 Drilldown — tooltip or popover** * Hover or click on the pill reveals a small surface that lists each configured category with its individual status: **pass / warn / fail / not reviewed / stale**. * The drilldown shows the per-category breakdown only — category label and status. It does not show full feedback excerpts and it does not provide actions. * "Not reviewed" and "Stale" present visually as gray in the drilldown, distinguished by a small label or icon so the editor can tell whether a category was never run (newly added) or had its rules changed (invalidated). * A drilldown interaction must not fire on incidental hover. Either a deliberate hover delay or click-to-open is required (see §12). ### **4.4 Row-level affordances** * **"Run reviews"** — appears in the empty state (Workflow B) and on rows where one or more criteria are not reviewed or stale. Triggering the affordance kicks off a review **in the background**; the row does not update live. The new result appears the next time the listing's data is refreshed (page reload or revisit). * **Row click-through** — clicking the row (or its title cell, per the listing's convention) navigates the editor to the standard per-item edit surface for that content item. This widget does not specify what that surface looks like. ## **5. States** The widget is a **snapshot of stored results**. There is no live "running" state — reviews that are currently in flight are not displayed mid-render. The four row-level states are: <figure> | **ID** | **State** | **Trigger** | **Visible appearance** | |--------|-----------|-------------|------------------------| | S1 | Empty | The row has zero stored results for any criterion (never reviewed, or every criterion was invalidated) | Neutral placeholder pill, "Run reviews" affordance | | S2 | Partial | The row has stored results for some criteria but not all (e.g., a criterion was added after the row's last full run) | Pill renders the available counts plus a gray "not reviewed" segment for the missing criteria | | S3 | Completed | Every configured criterion has a current stored result, and none of those results have been invalidated | Pill shows the final tally of pass / warn / fail. No gray segment | | S4 | Stale | The row previously had stored results for criteria that are now invalidated by a configuration change (e.g., the criterion's rules were updated in the backend) | Affected criteria render as gray in the pill and drilldown; unaffected criteria keep their previous results | </figure>\### \*\*5.1 Per-criterion staleness\*\* Staleness is **per-criterion, not global**. When an administrator changes the rules for one criterion, only that criterion's stored results across the system become stale. Other criteria's results remain valid. Worked example: a content type has three configured criteria — A, B, C. A given row has stored results: A = pass, B = warn, C = fail. An administrator updates the rules for B. The row's pill now renders A = pass, B = gray (stale), C = fail. The numeric label reflects `1 / 0 / 1 + 1 to review`. The drilldown labels B as "Stale — re-run needed." This rule applies uniformly across all rows in the listing. Every row that had a B result loses that segment; rows that never had a B result are unaffected. ## **6. Interactions** ### **6.1 Reveal the drilldown** * A hover with a deliberate delay (or click-to-open) on the pill reveals the per-category breakdown. * Drilldown closes on pointer-out (or click-outside, depending on the modality chosen — see §12). ### **6.2 Run reviews from the empty or partial state** * The "Run reviews" affordance triggers a review for the row in the background. * The list view does not show progress. The pill and drilldown update on the next refresh. ### **6.3 Sort** The listing must support sorting by **aggregate score** only. When the content type has the aggregate score configured (see §4.2), the column is sortable by that score. When the aggregate score is not configured, the column is not sortable in v1. > **Future feature.** Additional sort options — by number of failing categories, by number of warning categories, by "not yet reviewed" grouping — are valuable but deferred. They likely require denormalized columns or computed Views fields to perform well at listing scale, which is meaningful implementation work. Captured for a follow-up subtask. ### **6.4 Filter** The listing should support filtering by: * Any category failing. * Any category warning. * All categories passing. * Any category not reviewed (S1, S2, or S4 — any row with at least one gray segment). * Not yet reviewed at all (S1 only). Filters should compose. > **May need to be its own feature.** It is not yet clear how Views filters can be wired to a field widget that aggregates per-criterion state across many criteria. Each filter above implies a different shape of stored or computed data — for example, "any category failing" likely needs a denormalized boolean column per row, while "all categories passing" can be derived from the aggregate but only when every criterion has a current result. Resolving this may require its own ticket scoped to the filter / Views integration; the pill widget itself may not own the implementation. Captured as an open question in §12. ### **6.5 Row navigation** * Clicking the row (per the standard content listing's navigation convention) opens the per-item edit surface for that content item. This widget contributes context to that surface (entity id) but does not control its rendering. ## **7. Threshold model** The widget renders the per-category status derived from each criterion's thresholds. The widget itself does not own the threshold definitions — it consumes whatever the criterion configuration provides. * Every category declares a **pass threshold** (required). A score at or above the pass threshold is **pass**; anything below it is **fail** by default. * A **warn threshold** is optional. When configured it must be **lower than the pass threshold**. A score at or above the warn threshold but below the pass threshold is **warn**. * Without a warn threshold, the criterion produces only two states (pass / fail) and contributes only red and green to the pill widget. * With a warn threshold, the criterion produces three states (pass / warn / fail) and can contribute red, yellow, or green. > **Architecture flag — threshold model does not yet exist in the module.** Today, the AI Content Review architecture does not include a pass-threshold (with optional warn-threshold) concept on review criteria. The Node Edit panel comps illustrated thresholds with example values (around 30% / 60%, used as visual stand-ins) — those numbers are **illustrative only and not authoritative**. Before this widget can be implemented, the data layer needs: > > * A way to declare a pass threshold on each criterion (required). > * A way to declare an optional warn threshold, validated as strictly lower than the pass threshold. > * A direction flag per criterion (higher-is-better vs. lower-is-better). > * A defined behavior for a criterion that has no pass threshold configured (does it not render in the pill at all? does it default to a value?). > > Resolving this is a prerequisite for implementing the widget as specified. ## **8. Edge cases (widget-specific)** * **One category configured for the content type.** The pill renders a single segment (or gray if not yet reviewed). The column width stays consistent with neighboring rows. The aggregate score is redundant (muted or hidden — see §12). * **new category was added since the row's last review.** The row moves into S2 (Partial). That criterion renders as gray; all previously-completed criteria keep their results. "Run reviews" surfaces a way to fill the gap. * **A category's rules were updated since the row's last review.** The row moves into S4 (Stale). That criterion's prior result is invalidated and renders as gray; all unaffected criteria keep their results. "Run reviews" surfaces a way to refresh. * **A category was removed from the configuration since the row's last review.** The widget hides that category from the pill and drilldown. Whether the underlying storage retains its prior result is an implementation decision; the widget does not render it. * **Row's last review failed at the provider level.** Affected criteria render as gray with an error indicator in the drilldown; "Run reviews" surfaces as a retry. ## **9. Data and API surface (referenced, not specified here)** This functional doc does **not** name or assume specific entity types, classes, fields, or method signatures. The data model that backs the widget is owned by the implementation spec that follows. What the widget needs from whatever data layer is built: * Per-row read access to the count of categories in each state (pass / warn / fail / not-reviewed / stale) and, when configured, the aggregate score. * Per-row read access to the per-category breakdown for the drilldown (category label, status, plus the distinction between "never run" and "stale"). * A way to trigger a background review on a single row from the empty / partial / stale states. * A signal that the listing's data is fresh enough to render. The widget reads stored state; refresh cadence is owned by the listing. Also out of scope for this functional doc: * The exact Drupal integration shape (Views field plugin vs. field formatter vs. computed field). * Provider-side prompt design per criterion. * Queue worker behavior. ## **10. Nice-to-have / future scope** ### **10.1 Bulk run reviews via row selection** The standard content listing in Drupal supports per-row checkboxes and bulk operations. A natural extension of this widget is a bulk operation that triggers reviews on every selected row. * Editor selects N rows via checkbox. * Selects "Run reviews on selected" from the bulk operations dropdown. * Confirmation dialog (since reviews may be expensive); editor confirms. * Reviews are queued for every selected row. **Out of scope for this ticket — captured as a follow-up subtask.** The UI specification for what running a large batch of reviews _looks like_ (progress display, queue status, partial-failure handling, cancellation, notification when complete) is a meaningful design problem in its own right and deserves its own ticket. Open question for that follow-up: what does the bulk runner look like when a user kicks off reviews on hundreds of items at once? Inline progress strip on the listing header? Separate batch progress page? Background with a "ready" notification? This widget should be designed so that adding a bulk operation later does not require revisiting the per-row data contract — the same "trigger a background review on a row" capability listed in §9 covers both the single-row and bulk cases. ## **11. Acceptance criteria** The widget is functionally complete when an editor can, on a content listing: 1. See a pill widget rendered on every row with a configured content type, sized to the column. 2. Read the pass / warn / fail / not-reviewed counts from the numeric labels even without color information. 3. See the aggregate score next to the pill when the content type opts into it; not see it when the content type does not. 4. Hover or click the pill to reveal the per-category drilldown, with each category labeled by its state (pass / warn / fail / not reviewed / stale). 5. Trigger "Run reviews" on a row in S1, S2, or S4 and have a review queued in the background (the row updates on next refresh, not live). 6. Observe per-criterion staleness behavior: when an administrator updates one criterion's rules, every row's pill drops that criterion to gray while preserving the other criteria's results. 7. Sort the listing by "number of failing categories," by aggregate score (when configured), and group not-yet-reviewed rows. 8. Filter the listing by any category failing, any category warning, all passing, any category not reviewed, and not yet reviewed at all — and combine those filters. 9. See a sensible rendering with 1 category, 5 categories, 10 categories, and an extreme case (15+). ## **12. Open questions** * **Category-added vs. criterion-rule-changed handling.** Confirmed as per-criterion gray segments in §5. Carried as resolved for now; flag for design review if working-session takes a different position. * **Aggregate score default.** Shown by default, hidden by default, or off-by-default with an opt-in toggle per content type? Carried from the source ticket. * **Aggregate score with gray segments.** When the row has at least one not-reviewed or stale criterion, should the aggregate score render at all, render with a "partial" indicator, or be suppressed? * **Drilldown modality.** Tooltip (hover with delay) or popover (click-to-open)? Carried from the source ticket. * **"Run reviews" affordance feedback.** Since the listing does not live-update, how do we acknowledge the click without misleading the editor about progress? Toast? Disabled state until refresh? Status badge on the row? * **Filter integration with Views.** How exactly are the §6.4 filters wired to a field widget that aggregates per-criterion state? This may need its own ticket scoped to the Views integration layer — see the note in §6.4. * **Listing refresh cadence.** Is the editor expected to manually reload to see new results, or does the listing auto-refresh on some interval? Owned by the listing template, not the widget, but worth deciding so the "Run reviews" affordance can be designed coherently. ## **14. Screenshots** See #3585814[ — UI/Workflow: Multi-page overview view (review status across content)](https://git.drupalcode.org/project/ai_content_review/-/work_items/3585814) ## **15. Claude design — standalone HTML export** >>> NOTE this file was incorrect - Updated now with correct version. >>> [AI Review Content List -10 criteria (standalone).html](/uploads/16f1abbd436f35a742d77ad8309d5223/AI_Review_Content_List_-10_criteria__standalone_.html)