ux_spec · supabase_json
AD SEO Agent ux_spec
ux_spec artifact · for AD SEO Agent · status draft
flows
| id | name | happy path | feature ids | failure paths | alternate paths |
|---|---|---|---|---|---|
| FL-01 | Buyer opens Hubbard Command Center | - S-01 | - F-01 - F-02 - F-07 | - item: recovery: string, condition: string | - item: path: object, condition: string |
| FL-02 | Digital lead reviews a Recommendation | - S-02 - S-03 | - F-03 | - item: recovery: string, condition: string | - item: path: object, condition: string |
| FL-03 | CIO inspects agent work and auditability | - S-01 - S-04 - S-03 | - F-04 | - item: recovery: string, condition: string | |
| FL-04 | Human approves a governed Action | - S-05 - S-03 - S-05 - S-04 | - F-05 | - item: recovery: string, condition: string | - item: path: object, condition: string |
| FL-05 | Affiliate distributor sees white-label packaging | - S-01 - S-06 | - F-06 | ||
| FL-06 | Production pilot falls back from live provider to seeded data | - S-07 - S-01 | - F-07 | - item: recovery: string, condition: string |
open questions
| id | owner | blocks | status | question |
|---|---|---|---|---|
| OQ-UX-001 | atlas | Exact approval persistence behavior only; does not block UX/architecture coherence or read-only product route. | deferred | Should Monday approval decisions persist immediately, or should the public/demo product route render approval as a demo-local interaction until auth is added? |
Agent Handoff
Start Here
ux_spec artifact · for AD SEO Agent · status draft
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Open Questions
- OQ-UX-001: id: string, owner: string, blocks: string, status: string, question: string
Structured Payload
Machine-readable source fields
flows
| id | name | happy path | feature ids | failure paths | alternate paths |
|---|---|---|---|---|---|
| FL-01 | Buyer opens Hubbard Command Center | - S-01 | - F-01 - F-02 - F-07 | - item: recovery: string, condition: string | - item: path: object, condition: string |
| FL-02 | Digital lead reviews a Recommendation | - S-02 - S-03 | - F-03 | - item: recovery: string, condition: string | - item: path: object, condition: string |
| FL-03 | CIO inspects agent work and auditability | - S-01 - S-04 - S-03 | - F-04 | - item: recovery: string, condition: string | |
| FL-04 | Human approves a governed Action | - S-05 - S-03 - S-05 - S-04 | - F-05 | - item: recovery: string, condition: string | - item: path: object, condition: string |
| FL-05 | Affiliate distributor sees white-label packaging | - S-01 - S-06 | - F-06 | ||
| FL-06 | Production pilot falls back from live provider to seeded data | - S-07 - S-01 | - F-07 | - item: recovery: string, condition: string |
status
approved
handoff
notes for decomp
- Build should start with object model + seeded Hubbard dataset, then Command Center, OpportunityBoard/EvidenceDrawer, AgentActivityRail, ApprovalGate, and System/Data status.
- Do not start with generic dashboard widgets or marketing page composition.
- Do not implement AD SEO Agent as a Dev Studio child view or desktop-only internal tool. Product route should own its responsive product shell.
notes for vikram
- Data model must persist the AI-first objects named in Requirements: CompanyProfile, AnalysisRun, AgentStep, Recommendation, Evidence, Action, ApprovalDecision, Constraint, OutcomeMetric.
- Seeded data and live provider data must feed the same UI object shapes.
- Approval state should be persisted; UI cannot treat approval as local-only.
- Route and hosting are now fixed at client project
/seoon Cloudflare Pages, with Workers for server-side actions/adapters as needed.
blocking question ids
No items captured.
ready for coherence review
true
project
id
ad-seo-agent
name
AD SEO Agent for Affiliated Distributor Networks
client id
ad
requirements ref
docs/projects/ad-seo-agent/artifacts/REQUIREMENTS.json
platform project id
0.0.8832348
platform project title
AD SEO Agent
surfaces
| id | name | type | layout | states | platform |
|---|---|---|---|---|---|
| S-01 | Command Center | screen | - density: standard - structure: Buyer-facing client project product shell. Main area starts with Hubbard profile strip, then ExecutiveDashboard hero with ROI proof card, followed by metric grid, top Recommendation list, and AgentActivityRail. Do not use Dev Studio internal desktop-only shell for this route. - scroll behavior: vertical - responsive rules: 4 items | - default: Seeded Hubbard analysis loaded with ROI, top recommendations, and agent activity. - loading: Skeleton metrics and visible agent analysis timeline; avoid generic spinner. - error: Show controlled blocked state if seed dataset cannot load. | responsive_web |
| S-02 | Opportunity Board | screen | - density: compact - structure: Blanc OpportunityBoard with segmented controls for All, Content, Technical, Internal Links, Outreach, Strategy; cards ranked by expected value and confidence. - scroll behavior: vertical - responsive rules: 2 items | - default: At least 10 Hubbard-specific Recommendation objects are visible. - empty: No recommendations available. - error: Recommendation dataset failed validation. | responsive_web |
| S-03 | Recommendation Detail / Evidence Drawer | drawer | - density: standard - structure: Blanc EvidenceDrawer anchored right on desktop and full-screen sheet on mobile. Header shows Recommendation title, confidence, governance tier. Body shows reasoning, evidence, assumptions, risks, expected value, and action. - scroll behavior: vertical - responsive rules: 2 items | - default: Evidence and reasoning available for selected Recommendation. - error: Evidence missing or malformed. | responsive_web |
| S-04 | Agent Run View | screen | - density: compact - structure: Timeline view of AnalysisRun with AgentStep rows: crawler, competitor analyst, content gap analyst, backlink analyst, recommendation planner, reviewer/publisher waiting states. - scroll behavior: vertical - responsive rules: 2 items | - default: Seeded or live agent events show what happened and what is waiting. - loading: Show work-in-progress timeline, not spinner. | responsive_web |
| S-05 | Approval Queue | screen | - density: standard - structure: Blanc ApprovalGate list. Each governed Action shows current step: review evidence, edit constraints/brief, approve, return, or defer. - scroll behavior: vertical - responsive rules: 2 items | - default: Actions requiring approval are visible and cannot execute until approved. - success: Approval saved and action queued for agent execution. | responsive_web |
| S-06 | White-Label Preview | screen | - density: standard - structure: Blanc token-based preview showing how affiliate distributor organization brand/logo/colors/language can wrap the same AD SEO Agent object model. - scroll behavior: vertical - responsive rules: 2 items | - default: White-label story and token preview visible. | responsive_web |
| S-07 | System and Data Status | screen | - density: compact - structure: Status panels for seed dataset version, source mode, provider availability, freshness, and fallback behavior. - scroll behavior: vertical - responsive rules: 1 item | - default: Seeded dataset and optional provider status visible. - error: Seeded dataset missing; production pilot cannot proceed. | responsive_web |
dev studio
views
- feature_coverage
- route_map
- surface_map
- component_tree
- flow_map
- states
- open_questions
render as
ux_spec
navigation
routes
| path | auth role | surface id | description |
|---|---|---|---|
| /seo | S-01 | client project landing/Command Center for AD SEO Agent and the Hubbard pilot. | |
| /products/seo | S-01 | Short alias that redirects to /seo when routing supports it. | |
| /seo#opportunities | S-02 | Ranked Recommendation board section. | |
| /seo#evidence | S-03 | Recommendation evidence and reasoning section or drawer. | |
| /seo#agents | S-04 | AnalysisRun and AgentStep activity section. | |
| /seo#approval | S-05 | Human approval queue for governed Actions. | |
| /seo#white-label | S-06 | Affiliate distributor white-label preview/story section. | |
| /seo#system | S-07 | Data freshness, source mode, provider availability, and seed dataset details. |
role navigation
| role | items | pattern |
|---|---|---|
| buyer-demo | - Impact - Opportunities - Agents - Approvals - White-label - System | top_nav |
ux summary
avoid patterns
- Generic SaaS landing page hero.
- Keyword table as the first product moment.
- Spinner-only AI states.
- Decorative AI visuals such as gradients, blobs, robot icons, circuit boards, or brain metaphors.
- Hidden seeded-data assumptions.
- Approval as a last-minute modal.
primary platforms
- desktop
- responsive_web
- mobile
experience principles
- AI-first: the product opens with a diagnosis and recommended actions, not navigation.
- The central object is a governed Recommendation: evidence, reasoning, value, risk, action, governance tier, and owner agent.
- Blanc is the base system; use its signature patterns rather than inventing dashboard chrome.
- Make AI work visible through accountable agent steps and handoffs.
- Treat governance as a selling feature for CIO trust, not as friction.
- Seeded Hubbard data must be labeled while still feeling production-ready.
- AD SEO Agent is a buyer-facing client project route at
/seo; it should not inherit Dev Studio internal-tool framing or desktop-only restrictions. - Responsive web is required because the product route can be opened from buyer conversations, not only internal desktop sessions.
non negotiable patterns
- Blanc ExecutiveDashboard for first-screen ROI and diagnosis.
- Blanc OpportunityBoard for ranked Recommendation objects.
- Blanc AgentActivityRail for AnalysisRun and AgentStep visibility.
- Blanc EvidenceDrawer for reasoning, assumptions, confidence, and source details.
- Blanc ApprovalGate for ApprovalDecision and governed Action flow.
- ConstraintEditor pattern for human changes that re-rank recommendations.
design system
tokens
- Blanc default white/ink base
- --brand-primary for AD SEO Agent dark ink
- --brand-accent for controlled blue/green action emphasis
- --brand-accent-soft for selected Recommendation and active ApprovalStep states
- Blanc spacing scale only
- Blanc system font default unless product chooses a self-hosted font
new components
- ConstraintEditor
- RecommendationCard composed from Blanc OpportunityBoard
- DataSourceStatusPanel
- WhiteLabelPreviewShell
component library
Blanc for AD SEO Agent product patterns; client project shell/routing conventions for placement under /seo. Dev Studio internal UI does not constrain this product surface.
open questions
| id | owner | blocks | status | question |
|---|---|---|---|---|
| OQ-UX-001 | atlas | Exact approval persistence behavior only; does not block UX/architecture coherence or read-only product route. | deferred | Should Monday approval decisions persist immediately, or should the public/demo product route render approval as a demo-local interaction until auth is added? |
schema version
1.0
feature coverage
| notes | flow ids | feature id | surface ids | coverage status |
|---|---|---|---|---|
| Hubbard identity, domain, industrial/MRO context, and seed-data mode are visible in Command Center header and profile strip. | - FL-01 | F-01 | - S-01 - S-02 | covered |
| ExecutiveDashboard leads with ROI, savings, payback, and assumption labels. | - FL-01 | F-02 | - S-01 | covered |
| OpportunityBoard presents Recommendation objects; EvidenceDrawer explains the selected recommendation. | - FL-02 | F-03 | - S-02 - S-03 | covered |
| AgentActivityRail and Agent Run View expose AnalysisRun and AgentStep states. | - FL-03 | F-04 | - S-01 - S-04 | covered |
| ApprovalGate maps Action objects to governance tiers and human decisions. | - FL-04 | F-05 | - S-05 | covered |
| White-label preview shows how Blanc tokens and member-network language adapt without changing product architecture. | - FL-05 | F-06 | - S-06 | covered |
| System status and fallback states show seeded data reliability and live-provider unavailability without breaking the pilot. | - FL-06 | F-07 | - S-01 - S-07 | covered |