ahmido
3eff4d8579
## Summary - add the Spec 325 artifacts for screenshot-anchored strategic target images - update the UI/UX enterprise audit documents to capture strategic surfaces and grouped follow-up candidates - add supporting follow-up specs, target experience briefs, and target image assets for the audit workflow ## Testing - not run (documentation/spec artifact changes only) Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #385
158 lines
10 KiB
Markdown
158 lines
10 KiB
Markdown
# Tasks: Spec 325 - Screenshot-Anchored Strategic Target Images & Experience Briefs
|
|
|
|
**Input**: `specs/325-screenshot-anchored-strategic-target-images/spec.md` and `plan.md`
|
|
**Prerequisites**: Spec 323 audit artifacts and Spec 324 guardrail script exist on the active branch.
|
|
**Runtime posture**: Docs/image target artifacts only. No product runtime implementation.
|
|
|
|
## Phase 1: Inspect Inputs
|
|
|
|
- [x] T001 Read `docs/ui-ux-enterprise-audit/strategic-surfaces.md`.
|
|
- [x] T002 Read `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`.
|
|
- [x] T003 Read `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`.
|
|
- [x] T004 Read relevant files under `docs/ui-ux-enterprise-audit/page-reports/`.
|
|
- [x] T005 Inspect available current screenshots under `docs/ui-ux-enterprise-audit/screenshots/desktop/`.
|
|
- [x] T006 Read `docs/brand/tenantial-brand-context.md` and carry forward the user-provided Spec 325 brand token direction without treating placeholder brand docs as final brand truth.
|
|
- [x] T007 Confirm Spec 324 guardrail expectations in `scripts/check-ui-productization-coverage` and `specs/324-ui-productization-coverage-guardrails/`.
|
|
- [x] T008 Confirm the implementation diff remains outside product runtime paths under `apps/platform/`.
|
|
|
|
## Phase 2: Select Strategic Shortlist
|
|
|
|
- [x] T009 Select 6-10 P0/P1 surfaces from `docs/ui-ux-enterprise-audit/strategic-surfaces.md`.
|
|
- [x] T010 Explain why the selected set is proportional and why all 44 strategic rows are not covered.
|
|
- [x] T011 Document deferred strategic surfaces and recommended later coverage.
|
|
- [x] T012 Create `docs/ui-ux-enterprise-audit/target-experience-briefs/strategic-target-image-shortlist.md`.
|
|
- [x] T013 In the shortlist, include source screenshot links, page report links, persona, target brief link, target image link, and repo-truth notes for each selected surface.
|
|
|
|
## Phase 3: Handle Rejected Mockup Remnants
|
|
|
|
- [x] T014 Check whether previous Spec 325 mockup artifacts remain under `docs/ui-ux-enterprise-audit/mockups/`, `docs/ui-ux-enterprise-audit/target-images/`, or the working tree.
|
|
- [x] T015 If rejected remnants exist, move them to `docs/ui-ux-enterprise-audit/target-images/rejected/spec-325-initial-svg-pass/`. N/A: no rejected mockup remnants were present.
|
|
- [x] T016 If rejected remnants exist, add `docs/ui-ux-enterprise-audit/target-images/rejected/spec-325-initial-svg-pass/README.md` explaining why they are rejected. Satisfied by folder README documenting no remnants and rejection policy.
|
|
- [x] T017 If no rejected remnants remain, document that fact in the final implementation response and shortlist artifact.
|
|
|
|
## Phase 4: Prepare Artifact Structure
|
|
|
|
- [x] T018 Create `docs/ui-ux-enterprise-audit/target-experience-briefs/`.
|
|
- [x] T019 Create `docs/ui-ux-enterprise-audit/target-experience-briefs/README.md`.
|
|
- [x] T020 Create `docs/ui-ux-enterprise-audit/target-images/`.
|
|
- [x] T021 Create `docs/ui-ux-enterprise-audit/target-images/README.md`.
|
|
- [x] T022 Create `docs/ui-ux-enterprise-audit/target-images/source/`.
|
|
- [x] T023 Create `docs/ui-ux-enterprise-audit/target-images/problem-annotations/` if used. N/A for annotation images; folder README documents that current-state problems live in briefs and sidecars.
|
|
- [x] T024 Create `docs/ui-ux-enterprise-audit/target-images/target/`.
|
|
- [x] T025 Create or reuse `docs/ui-ux-enterprise-audit/follow-up-specs/`.
|
|
|
|
## Phase 5: Create Target Experience Briefs
|
|
|
|
For each selected surface:
|
|
|
|
- [x] T026 Reference source screenshot/page report in `docs/ui-ux-enterprise-audit/target-experience-briefs/<surface-slug>.md`.
|
|
- [x] T027 Describe the current-state snapshot without inventing current UI.
|
|
- [x] T028 Describe concrete current-state productization problems.
|
|
- [x] T029 Define target user promise, primary persona, and secondary personas.
|
|
- [x] T030 Define first-five-seconds target.
|
|
- [x] T031 Define primary decision, primary action, and visible secondary actions.
|
|
- [x] T032 Define target information hierarchy.
|
|
- [x] T033 Define main-view keep/promote/simplify treatment.
|
|
- [x] T034 Define detail drawer treatment.
|
|
- [x] T035 Define advanced/admin treatment.
|
|
- [x] T036 Define hidden/removed default elements.
|
|
- [x] T037 Define target layout direction and visual target direction.
|
|
- [x] T038 Define status/trust model with no green/success state unless verified.
|
|
- [x] T039 Define dangerous-action guardrails where applicable.
|
|
- [x] T040 Define customer-safe review notes where applicable.
|
|
- [x] T041 Define workspace/environment context, empty state, loading state, error state, and accessibility notes.
|
|
- [x] T042 Define repo-truth classifications for important target elements using allowed values.
|
|
- [x] T043 Define screenshot-anchored image generation prompt.
|
|
- [x] T044 Define implementation pattern requirements, later implementation candidate, and non-goals for later implementation.
|
|
|
|
## Phase 6: Create Target Images
|
|
|
|
For each selected surface:
|
|
|
|
- [x] T045 Create at least one target image under `docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-dark.png`.
|
|
- [x] T046 Create light target image under `docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target-light.png` where required.
|
|
- [x] T047 Use screenshot-anchored prompt from the target brief.
|
|
- [x] T048 Avoid generic SaaS layout, fake feature claims, unsupported compliance claims, and placeholder nonsense text.
|
|
- [x] T049 Avoid green success unless verified by repo/source truth.
|
|
- [x] T050 Keep text readable at desktop review size.
|
|
- [x] T051 Keep workspace/environment context visible.
|
|
- [x] T052 Keep primary decision/action visible.
|
|
- [x] T053 Keep technical diagnostics secondary.
|
|
- [x] T054 Reject or regenerate any target image that fails the visual review criteria.
|
|
- [x] T054A Add user-accepted premium visual reference images under `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/`.
|
|
- [x] T054B Regenerate target PNGs using the accepted premium reference direction while preserving repo-truth and safety sidecar constraints.
|
|
|
|
## Phase 7: Create Target Image Sidecars
|
|
|
|
For each selected surface:
|
|
|
|
- [x] T055 Create `docs/ui-ux-enterprise-audit/target-images/target/<surface-slug>-target.md`.
|
|
- [x] T056 Link source screenshot, source page report, source route, target brief, and target image files.
|
|
- [x] T057 Document what changed from current state in a transformation table.
|
|
- [x] T058 Add repo-truth classification table.
|
|
- [x] T059 Document conceptual elements requiring verification.
|
|
- [x] T060 Add implementation notes.
|
|
- [x] T061 Add do-not-implement-blindly notes.
|
|
- [x] T062 Include the required "Not Implementation Truth" notice.
|
|
|
|
## Phase 8: Update Coverage Artifacts
|
|
|
|
- [x] T063 Update `docs/ui-ux-enterprise-audit/strategic-surfaces.md` to mark selected surfaces as `Selected for Spec 325 target image` and deferred surfaces with a proportional deferral reason.
|
|
- [x] T064 Update `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` if target image coverage is tracked, with runtime implemented set to `No`.
|
|
- [x] T065 Update `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md` with references from selected surfaces to later implementation lanes.
|
|
- [x] T066 Update `docs/ui-ux-enterprise-audit/README.md` with the Spec 325 section and links to shortlist, brief folder, target image folder, and follow-up implementation candidates.
|
|
|
|
## Phase 9: Create Follow-Up Implementation Candidates
|
|
|
|
- [x] T067 Create `docs/ui-ux-enterprise-audit/follow-up-specs/325-strategic-target-image-implementation-candidates.md`.
|
|
- [x] T068 Group implementation lanes proportionally instead of creating one candidate per tiny page.
|
|
- [x] T069 Include candidate lanes for customer review workspace, governance inbox, operations hub, evidence/review pack, drift/baseline, restore safety, provider onboarding/readiness, and workspace/environment dashboard productization where supported by selected surfaces.
|
|
- [x] T070 Mark conceptual elements requiring repo verification before implementation.
|
|
- [x] T071 Mark shared pattern dependencies and recommend Spec 326 Tenantial Pattern Library & State System as the next pattern extraction spec.
|
|
|
|
## Phase 10: Validate
|
|
|
|
- [x] T072 Run `bash scripts/check-ui-productization-coverage HEAD` from the repository root.
|
|
- [x] T073 Run `git diff --check` from the repository root.
|
|
- [x] T074 Optionally run `bash -n scripts/check-ui-productization-coverage`.
|
|
- [x] T075 Confirm no product runtime files changed under `apps/platform/app/Filament/`, `apps/platform/app/Livewire/`, `apps/platform/resources/views/`, `apps/platform/routes/`, `apps/platform/config/`, `apps/platform/database/`, or `apps/platform/tests/`.
|
|
- [x] T076 Confirm every selected target image has a source screenshot/page report, target brief, and sidecar.
|
|
- [x] T077 If image dimension validation is available, run it and document dimensions; `file docs/ui-ux-enterprise-audit/target-images/target/*-target-*.png` confirmed all 18 target PNGs are 1600 x 900.
|
|
- [x] T078 Document full Pest/runtime suite not run because this spec is docs/image-only.
|
|
- [x] T079 Document Pint not run because no PHP files changed.
|
|
|
|
## Requirements Traceability
|
|
|
|
| Requirement(s) | Task Coverage |
|
|
|---|---|
|
|
| FR-325-001, FR-325-002, FR-325-003, FR-325-004 | T001-T013 |
|
|
| FR-325-005 | T014-T017 |
|
|
| FR-325-006 through FR-325-016 | T026-T044 |
|
|
| FR-325-017 through FR-325-025 | T020-T024, T045-T062 |
|
|
| FR-325-026 through FR-325-030 | T063-T071 |
|
|
| FR-325-031 | T008, T075 |
|
|
| FR-325-032 | T072-T073 |
|
|
| FR-325-033, FR-325-034 | T078-T079 |
|
|
| NFR-325-001, NFR-325-002, NFR-325-003 | T012-T013, T026-T044, T055-T062 |
|
|
| NFR-325-004, NFR-325-005, NFR-325-006, NFR-325-007 | T009-T011, T045-T054, T072-T079 |
|
|
|
|
## Dependency Notes
|
|
|
|
- Phases 1-2 must complete before briefs or images are created.
|
|
- Phase 5 target briefs should be drafted before image generation for each surface.
|
|
- Phase 7 sidecars depend on final accepted target images.
|
|
- Phase 8 coverage updates depend on the selected/deferred surface list.
|
|
- Phase 10 validation is final and must confirm runtime posture.
|
|
|
|
## MVP Scope
|
|
|
|
The minimum viable Spec 325 implementation is 6 selected surfaces, complete briefs, at least dark target images, required light variants for customer/auditor/management-facing surfaces, sidecars, coverage updates, follow-up candidates, and required validation.
|
|
|
|
## Non-Goals During Implementation
|
|
|
|
- Do not implement runtime UI.
|
|
- Do not modify Filament, Livewire, Blade, routes, navigation, providers, policies, migrations, tests, or business logic.
|
|
- Do not make target images a source of product truth.
|
|
- Do not create a design-system/pattern-library runtime implementation.
|
|
- Do not cover all strategic surfaces in this spec.
|