From c01cdcd3b53b2647da49a2b1bc10091ef51e85c3 Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Tue, 10 Mar 2026 15:21:18 +0100 Subject: [PATCH] docs: amend constitution to v1.11.0 with UI naming standards --- .specify/memory/constitution.md | 52 +++++++++++++++++++++++----- .specify/templates/plan-template.md | 4 ++- .specify/templates/spec-template.md | 8 +++++ .specify/templates/tasks-template.md | 6 ++++ 4 files changed, 60 insertions(+), 10 deletions(-) diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 85f26b5..e0fe600 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,15 +1,11 @@ # TenantPilot Constitution @@ -298,6 +294,44 @@ ### Filament UI — Layout & Information Architecture Standards (UX-001) - New resources/pages SHOULD use shared layout builders (e.g., `MainAsideForm`, `MainAsideInfolist`, `StandardTableDefaults`) to keep screens consistent. - A change is not “Done” unless UX-001 is satisfied OR an explicit exemption exists with a documented rationale in the spec/PR. +### Operator-facing UI Naming Standards (UI-NAMING-001) + +Goal: operator-facing actions, run labels, notifications, audit prose, and related UI copy MUST use consistent, +enterprise-grade product language. + +Naming model +- Operator-facing copy MUST distinguish four layers: Scope, Source/Domain, Operation, and Target Object. +- Scope terms (`Workspace`, `Tenant`) describe execution context and MUST NOT be used as the primary action label unless they are the actual target object. +- Source/Domain terms (`Intune`, `Entra`, `Teams`, future providers) are secondary and MUST NOT lead the primary label unless the current screen presents competing sources that need explicit disambiguation. + +Primary action labels +- Primary buttons, header actions, and menu actions MUST use `Verb + Object`. +- Preferred examples: `Sync policies`, `Sync groups`, `Capture baseline`, `Compare baseline`, `Restore policy`, `Run review`, `Export review pack`. +- Forbidden examples: `Sync from tenant`, `Backup tenant`, `Compare tenant`, `Sync from Intune`, `Run tenant sync now`, `Start inventory refresh from provider`. + +Domain vocabulary +- Operator-facing copy MUST prefer product-domain objects such as `policies`, `groups`, `baseline`, `findings`, `review pack`, `alerts`, and `operations`. +- Primary operator-facing copy MUST NOT use implementation-first terms such as `provider`, `gateway`, `resolver`, `collector`, `contract registry`, or `job dispatch`. +- Source/domain details MAY appear in modal descriptions, helper text, run metadata, audit metadata, and notifications when needed for precision. + +Run, notification, and audit semantics +- Visible run titles MUST use the same domain vocabulary as the initiating action and SHOULD be concise noun phrases such as `Policy sync`, `Baseline capture`, `Baseline compare`, `Policy restore`, and `Tenant review`. +- Notifications MUST use either `{Object} {state}` or `{Operation} {result}` and remain short, e.g. `Policy sync queued`, `Policy sync completed`, `Policy sync failed`, `Baseline compare detected drift`. +- Audit prose MUST use the same operator-facing language, e.g. `{actor} queued policy sync`, `{actor} captured baseline`, `{actor} reopened finding`. +- The same user-visible action MUST keep the same domain vocabulary across button labels, modal titles, run titles, notifications, and audit prose. + +Verb standard +- Preferred verbs are `Sync`, `Capture`, `Compare`, `Restore`, `Review`, `Export`, `Open`, `Archive`, `Resolve`, `Reopen`, and `Assign`. +- `Start`, `Execute`, `Trigger`, and `Perform` SHOULD be avoided for operator-facing copy unless there is a deliberate domain reason. +- `Run` MAY be used only when the object is itself run-like, such as `Run review` or `Run compare`; it MUST NOT be the generic fallback verb for all operations. + +Current binding decision +- The Policies screen primary action MUST be `Sync policies`. +- The Policies screen modal title MUST be `Sync policies`. +- The Policies screen success toast MUST be `Policy sync queued`. +- The visible run label for that action MUST be `Policy sync`. +- The audit prose for that action MUST be `{actor} queued policy sync`. + Spec Scope Fields (SCOPE-002) - Every feature spec MUST declare: @@ -355,4 +389,4 @@ ### Versioning Policy (SemVer) - **MINOR**: new principle/section or materially expanded guidance. - **MAJOR**: removing/redefining principles in a backward-incompatible way. -**Version**: 1.10.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-02-23 +**Version**: 1.11.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-03-10 diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 9a0328d..da2e36b 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -49,7 +49,9 @@ ## Constitution Check - Automation: queued/scheduled ops use locks + idempotency; handle 429/503 with backoff+jitter - Data minimization: Inventory stores metadata + whitelisted meta; logs contain no secrets/tokens - Badge semantics (BADGE-001): status-like badges use `BadgeCatalog` / `BadgeRenderer`; no ad-hoc mappings; new values include tests -- Filament UI Action Surface Contract: for any new/modified Filament Resource/RelationManager/Page, define Header/Row/Bulk/Empty-State actions, ensure every List/Table has a record inspection affordance (prefer `recordUrl()` clickable rows; do not render a lone View row action), keep max 2 visible row actions with the rest in “More”, group bulk actions, require confirmations for destructive actions (typed confirmation for large/bulk where applicable), write audit logs for mutations, enforce RBAC via central helpers (non-member 404, member missing capability 403), and ensure CI blocks merges if the contract is violated or not explicitly exempted- Filament UI UX-001 (Layout & IA): Create/Edit uses Main/Aside (3-col grid, Main=columnSpan(2), Aside=columnSpan(1)); all fields inside Sections/Cards (no naked inputs); View uses Infolists (not disabled edit forms); status badges use BADGE-001; empty states have specific title + explanation + 1 CTA; max 1 primary + 1 secondary header action; tables provide search/sort/filters for core dimensions; shared layout builders preferred for consistency +- UI naming (UI-NAMING-001): operator-facing labels use `Verb + Object`; scope (`Workspace`, `Tenant`) is never the primary action label; source/domain is secondary unless disambiguation is required; runs/toasts/audit prose use the same domain vocabulary; implementation-first terms do not appear in primary operator UI +- Filament UI Action Surface Contract: for any new/modified Filament Resource/RelationManager/Page, define Header/Row/Bulk/Empty-State actions, ensure every List/Table has a record inspection affordance (prefer `recordUrl()` clickable rows; do not render a lone View row action), keep max 2 visible row actions with the rest in “More”, group bulk actions, require confirmations for destructive actions (typed confirmation for large/bulk where applicable), write audit logs for mutations, enforce RBAC via central helpers (non-member 404, member missing capability 403), and ensure CI blocks merges if the contract is violated or not explicitly exempted +- Filament UI UX-001 (Layout & IA): Create/Edit uses Main/Aside (3-col grid, Main=columnSpan(2), Aside=columnSpan(1)); all fields inside Sections/Cards (no naked inputs); View uses Infolists (not disabled edit forms); status badges use BADGE-001; empty states have specific title + explanation + 1 CTA; max 1 primary + 1 secondary header action; tables provide search/sort/filters for core dimensions; shared layout builders preferred for consistency ## Project Structure ### Documentation (this feature) diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md index ecbf6fa..aed1ef7 100644 --- a/.specify/templates/spec-template.md +++ b/.specify/templates/spec-template.md @@ -119,6 +119,14 @@ ## Requirements *(mandatory)* **Constitution alignment (BADGE-001):** If this feature changes status-like badges (status/outcome/severity/risk/availability/boolean), the spec MUST describe how badge semantics stay centralized (no ad-hoc mappings) and which tests cover any new/changed values. +**Constitution alignment (UI-NAMING-001):** If this feature adds or changes operator-facing buttons, header actions, run titles, +notifications, audit prose, or related helper copy, the spec MUST describe: +- the target object, +- the operator verb, +- whether source/domain disambiguation is actually needed, +- how the same domain vocabulary is preserved across button labels, modal titles, run titles, notifications, and audit prose, +- and how implementation-first terms are kept out of primary operator-facing labels. + **Constitution alignment (Filament Action Surfaces):** If this feature adds or modifies any Filament Resource / RelationManager / Page, the spec MUST include a “UI Action Matrix” (see below) and explicitly state whether the Action Surface Contract is satisfied. If the contract is not satisfied, the spec MUST include an explicit exemption with rationale. diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md index c6d6220..b6a2a4f 100644 --- a/.specify/templates/tasks-template.md +++ b/.specify/templates/tasks-template.md @@ -32,6 +32,12 @@ # Tasks: [FEATURE NAME] - destructive-like actions use `->requiresConfirmation()` (authorization still server-side), - cross-plane deny-as-not-found (404) checks where applicable, - at least one positive + one negative authorization test. +**UI Naming**: If this feature adds or changes operator-facing actions, run titles, notifications, audit prose, or helper copy, tasks MUST include: +- aligning primary action labels to `Verb + Object`, +- keeping scope terms (`Workspace`, `Tenant`) out of primary action labels unless they are the actual target object, +- using source/domain terms only where same-screen disambiguation is required, +- aligning button labels, modal titles, run titles, notifications, and audit prose to the same domain vocabulary, +- removing implementation-first wording from primary operator-facing copy. **Filament UI Action Surfaces**: If this feature adds/modifies any Filament Resource / RelationManager / Page, tasks MUST include: - filling the spec’s “UI Action Matrix” for all changed surfaces, - implementing required action surfaces (header/row/bulk/empty-state CTA for lists; header actions for view; consistent save/cancel on create/edit),