Accessibility preferences

Tailor contrast, typography, and motion for your needs

Adjust these options to apply Aurora accessibility tokens instantly across the supplier portal.

High contrast Boost interface contrast and emphasise focus states. Larger text Increase base font sizes and spacing for comfortable reading. Reduce motion Tone down decorative transitions and animated flourishes.

Preferences apply instantly across the supplier and internal portals.

Design system

Supplier portal style guide

UX, accessibility, and component guidance powering the supplier experience.

Documentation section: Docs
Last updated: 2025-10-22 18:59 UTC
Source file: docs/en/portal/ux_guidelines.md

Design system overview

IngoSRM Aurora

A modern, token-driven design system shared by the supplier and internal portals, focused on scalability and accessibility.

Версия: 2025.2
Token groups: color, supporting, typography, spacing, radii, shadows, motion, states, layout, gradient, iconography, data-visualisation, semantic, z-index
Source last updated: 2025-05-12

Resources

Design tokens CSS

Serve ``--ds-*`` custom properties to prototypes directly from the portal.
Source module

Tokens are defined in ``src/SupplierManagement/design_system.py`` and reused across services.

Token examples

Frequently referenced properties when extending portal layouts.

--ds-color-brand-600

#5b3bec
--ds-spacing-spacing-md

1rem
--ds-component-button-primary-background

#5b3bec

Design foundations

Foundational tokens guarantee consistent color, type, and spacing across supplier journeys.

Color system

Brand, surface, and semantic colors with AA contrast baked into components.

Brand 600

--ds-color-brand-600

#5b3bec
Surface

--ds-color-surface

#ffffff
Text primary

--ds-color-text-primary

#121a2c
Success 600

--ds-color-success-600

#1d9b6c

Typography

Inter forms the base for headings, body text, and tabular data across the portal.

Heading family --ds-typography-font-family-heading: 'Inter var', 'Inter', ui-sans-serif, system-ui, sans-serif
Body family --ds-typography-font-family-sans: 'Inter var', 'Inter', ui-sans-serif, system-ui, sans-serif
Base size --ds-typography-font-size-base: 1rem
Line height --ds-typography-line-height-base: 1.6rem

Spacing scale

Seven-step spacing scale keeps layout rhythm consistent between screens.

2xs --ds-spacing-spacing-2xs: 0.125rem
xs --ds-spacing-spacing-xs: 0.375rem
sm --ds-spacing-spacing-sm: 0.625rem
md --ds-spacing-spacing-md: 1rem
lg --ds-spacing-spacing-lg: 1.5rem
xl --ds-spacing-spacing-xl: 2rem
2xl --ds-spacing-spacing-2xl: 2.5rem

Component highlights

Token-driven components align supplier-facing flows with the Aurora library.

Buttons

Primary, secondary, ghost, success, and danger variants share spacing and focus treatment.

Primary background

--ds-component-button-primary-background

#5b3bec
Secondary border

--ds-component-button-secondary-border

#d8dbeb
Focus ring

--ds-color-focus-ring

rgba(91, 59, 236, 0.35)

Metric cards

Status-aware variants align analytics with segmentation and performance dashboards.

Default background

--ds-component-metric-background

#ffffff
Brand border

--ds-component-metric-variants-brand-border

rgba(91, 59, 236, 0.32)
Success label

--ds-component-metric-variants-success-label

#157d56

Data tables

Shared header, border, and hover tokens keep procurement and performance grids aligned.

Header background

--ds-component-table-header-background

#f2f4f9
Row hover

--ds-component-table-row-hover

#f2f4f9
Caption

--ds-component-table-caption

#3a465f

Portal design coverage

Every supplier-facing module below consumes Aurora layouts, navigation, and token definitions.

50 pages 11 categories

Analytics

2 pages

Analytics and insights
analytics analytics

Explore sourcing, contract and fulfilment trends consolidated for your organisation.
Supplier dashboard
dashboard dashboard

Track supplier health, accreditation status and priority actions at a glance.

Procurement

10 pages

Bid submitted
bid-success bids

Confirmation page summarising the submitted bid and next procurement milestones.
Contract checkpoints
contract-checkpoints contracts

Inspect approval stages and compliance checkpoints required for contract execution.
Contract follow-up
contract-follow-up contracts

Track supplier obligations, checkpoints and outstanding follow-up actions.
Contract overview
contract-detail contracts

Review contractual terms, deliverables and the latest approved documents.
Contracts
contracts contracts

Browse active agreements, statuses and key milestones linked to procurement projects.
Electronic document exchange
contracts-edo edo

Monitor EDI status, bottlenecks and compliance metrics for all contracts.
Event details
sourcing-event-detail events

Inspect schedules, lots and documentation for a specific sourcing event.
Event invitations
invitations invitations

Manage invitations, confirm participation and coordinate clarifications with the buyer team.
My bids
bids bids

Track submitted offers, revisions and award outcomes across sourcing events.
Sourcing events
sourcing-events events

Review open sourcing events, evaluate requirements and submit clarifications.

Operations

7 pages

Fulfilment
fulfillment fulfillment

Resolve acceptance issues, track incidents and coordinate corrective actions for deliveries.
Operation detail
operation-detail operations

Drill into a specific operation to inspect status, participants and linked documents.
Operational workspace
operations operations

Monitor multi-stage procurement processes and acceptance checkpoints across engagements.
Operations history
operations-history operations

Review the chronological history of operational steps, approvals and escalations.
Order detail
order-detail orders

Inspect delivery schedules, receipting history and outstanding logistics actions for an order.
Orders and deliveries
purchase-orders orders

Track purchase orders, shipment status and delivery progress across engagements.
Three-way matching
three-way-matching matching

Reconcile purchase orders, receipts and invoices to resolve discrepancies proactively.

Collaboration

8 pages

Documents
documents documents

Upload compliance artefacts, manage expirations and share certificates with the buyer.
Knowledge base
knowledge-base knowledge

Step-by-step guides covering onboarding, sourcing and fulfilment scenarios.
Message center
message-center notifications

Consolidated workspace for notifications, invitations and support updates.
Notification preferences
notification-preferences notifications

Control notification channels, frequency and escalation rules for your organisation.
Notifications
notifications notifications

Review alerts, mark updates as read and configure delivery preferences.
Portal style guide
style-guide knowledge

UX, accessibility and component guidelines for supplier-facing experiences.
Support centre
support-centre support

Access onboarding guides, escalation contacts and frequently asked questions.
Support tickets
support-tickets support

Submit and track support requests, monitor SLA timelines and supply additional details.

Performance

4 pages

Development programmes
development-programmes development

Track supplier development initiatives, milestones and responsible owners.
Performance dashboard
performance performance

Analyse KPIs, scorecards and improvement programmes assigned to your team.
Programme detail
development-programme-detail development

Detailed timeline, participants and deliverables for a supplier development programme.
Task management
task-management tasks

Consolidated backlog for corrective actions, development plans and operational follow-ups.

Insights

4 pages

Capability roadmap
roadmap roadmap

Plan upcoming releases, governance milestones and joint improvement initiatives.
High-priority roadmap
roadmap-high-priority roadmap

Focus on urgent capability rollouts and mitigations required for strategic suppliers.
Segmentation analytics
segmentation-dashboard analytics

Visualise supplier clusters, health segments and contribution to spend.
Segmentation workspace
segmentation segmentation

Manage supplier tiers, manual overrides and rationale for segment assignments.

Profile

2 pages

Interaction history
supplier-history history

Timeline of profile changes, accreditation steps and supplier engagement updates.
Supplier profile
profile profile

Maintain company data, banking details and accreditation documents.

Security

4 pages

Access management
rbac-overview rbac

Review roles, permissions and assigned users for the supplier portal.
Change password
change-password security

Update your portal password in line with corporate security requirements.
Logout
logout logout

Terminate the current portal session and return to the public landing page.
Two-factor authentication
two-factor security

Configure authenticator apps, backup codes and enforce stronger authentication.

Tools

2 pages

Portal search
global-search search

Search contracts, tasks, documents and knowledge base articles across the portal.
Workflow designer
workflow-designer workflow

Upload, validate and publish BPMN workflows powering accreditation and sourcing.

Welcome

6 pages

Legal and compliance
legal legal

Portal usage terms, data protection clauses and procurement policy references.
Login
login login

Access the supplier workspace with your account credentials or certificate.
Registration confirmation
registration-confirmation register

Status page confirming email verification or manual approval is required.
Supplier portal overview
portal-home home

Landing page describing capabilities, onboarding steps and available support.
Supplier registration
registration register

Submit company details to request access to the supplier management portal.
Unified access gateway
unified-entrypoint home

Direct suppliers and employees to the appropriate workspace based on their role.

Utilities

1 page

Saved filter presets
saved-filters filters

Manage reusable filter presets across portal workspaces and share defaults with your team.

Internal portal design coverage

Employee-facing modules below also adopt Aurora layouts, navigation, and tokens.

25 pages 13 categories

Internal overview

1 page

Internal dashboard
internal-dashboard

Monitor accreditation queues, risk alerts and supplier KPIs across teams.

Suppliers

2 pages

Supplier detail
internal-supplier-detail

Inspect supplier profiles, interaction history and assigned account owners.
Supplier registry
internal-suppliers

Manage supplier records, statuses and accreditation progress for procurement teams.

Accreditation

1 page

Accreditation check detail
internal-accreditation-check

Review supporting evidence, approvals and timelines for accreditation checks.

Sourcing

3 pages

Bid evaluation
internal-bid-evaluation

Compare supplier bids, score responses and recommend awards to the committee.
Create sourcing event
internal-create-sourcing-event

Define sourcing scope, timelines and evaluation criteria for new events.
Sourcing events
internal-sourcing-events

Coordinate tender stages, milestones and supplier communications.

Procurement

3 pages

Create requisition
internal-create-requisition

Capture requirements, budgets and approvers for a new procurement request.
Requisition detail
internal-requisition-detail

Analyse request metadata, approval history and supporting documentation.
Requisitions
internal-requisitions

Review procurement requisitions, approval status and budget coverage.

Planning

3 pages

Create procurement plan
internal-create-plan

Set up a new procurement plan with timeframes, budgets and objectives.
Plan detail
internal-plan-detail

Inspect procurement plan items, spend allocation and execution progress.
Procurement plans
internal-plans

Manage yearly procurement plans, milestones and responsible owners.

Contracts

3 pages

Contract detail
internal-contract-detail

Review contract terms, documents and performance checkpoints.
Contracts
internal-contracts

Oversee contract portfolio, lifecycle status and supplier obligations.
Create contract
internal-create-contract

Prepare a contract draft, select suppliers and capture key milestones.

Analytics

1 page

Spend analysis
internal-spend-analysis

Explore spend analytics, category breakdowns and supplier contribution trends.

Operations

1 page

Task overview
internal-tasks

Track corrective actions, committee follow-ups and operational assignments.

Profile

1 page

Employee profile
internal-profile

Maintain personal details, preferences and delegated responsibilities.

Support

2 pages

Documentation article
internal-document-detail

Read detailed guidance for accreditation, sourcing and operational workflows.
Documentation search
internal-documentation

Search implementation guides, process policies and troubleshooting articles.

Access

3 pages

Change password
internal-change-password

Update the internal portal password to comply with security policy.
Internal login
internal-login

Authenticate with corporate credentials to access the employee workspace.
Logout
internal-logout

End the current internal session and return to the unified entrypoint.

Workspace

1 page

Saved filter presets
internal-saved-filters

Manage supplier workspace presets and ensure key filters stay discoverable.

[Русская версия](../../portal/ux_guidelines.md)

Supplier Portal UX & Accessibility Guidelines

This document captures the UX rules that govern the supplier portal after consolidating layout macros and addressing the non-functional scope of Task 14 (TZ-870–TZ-934). It is the single source of truth for designers, engineers, and QA when building new views or validating accessibility.

0. Design system foundations

**Token catalogue.** The style guide now surfaces the Aurora design system metadata (name, version, token groups) and links to the canonical custom property bundle served at `/portal/design-system.css`, which is generated by `render_design_custom_properties()` in the public portal blueprint.【F:src/SupplierManagement/portal/public.py†L552-L705】【F:src/SupplierManagement/design_system.py†L820-L835】
**Semantic theming.** Light and dark palettes are serialised as `--ds-semantic-*` variables and exported alongside `[data-theme]` overrides, so both portals inherit Aurora surfaces, text, and border colours without duplicating CSS. The base template now embeds the theme-aware bundle returned by `render_design_custom_properties(include_themes=True)`.【F:src/SupplierManagement/design_system.py†L13-L220】【F:src/SupplierManagement/design_system.py†L860-L980】【F:src/SupplierManagement/portal/template_utils.py†L180-L220】【F:src/SupplierManagement/internal/main.py†L640-L700】
**Color, type, spacing panels.** Dedicated panels render brand swatches, typography families, and the spacing scale directly from the design tokens so contributors can copy the canonical `--ds-*` values without inspecting the source code.【F:src/SupplierManagement/portal/public.py†L581-L666】【F:src/SupplierManagement/portal/templates/style_guide.html†L18-L141】
**Component highlights.** Buttons, metric cards, and table treatments expose their component tokens, making it clear which `--ds-component-*` properties drive critical procurement flows.【F:src/SupplierManagement/portal/public.py†L668-L705】【F:src/SupplierManagement/portal/templates/style_guide.html†L142-L199】
**Coverage matrix.** The style guide aggregates every portal route from the `design_registry`, groups them by domain (procurement, operations, support, etc.), and surfaces counters so teams can confirm which screens already consume Aurora layouts and tokens.【F:src/SupplierManagement/portal/public.py†L821-L903】【F:src/SupplierManagement/portal/templates/style_guide.html†L186-L241】

1. Layout fundamentals

**Shared containers.** Tables and cards must be rendered via the `table_row`/`table_cell` macros and wrapped in `rounded-2xl border border-slate-200 shadow-sm`. The canonical implementations live in `portal/templates/macros.html` and the roadmap, dashboard, and follow-up templates.【F:src/SupplierManagement/portal/templates/macros.html†L1-L180】【F:src/SupplierManagement/portal/templates/roadmap.html†L1-L780】【F:src/SupplierManagement/portal/templates/dashboard.html†L548-L706】【F:src/SupplierManagement/portal/templates/contracts_follow_up.html†L1-L320】
**Responsive behaviour.** Layout width is capped with `max-w-7xl`; grid utilities (`grid`, `gap-x-6`, `gap-y-4`, `sm:px-6`) drive the tablet/mobile experience. Profile and performance templates demonstrate the required breakpoints.【F:src/SupplierManagement/portal/templates/profile.html†L150-L278】【F:src/SupplierManagement/portal/templates/performance.html†L1-L220】
**Palette & contrast.** Status highlights use `text-indigo-700 bg-indigo-50`, `text-emerald-700 bg-emerald-50`, and `text-amber-700 bg-amber-50`, delivering ≥ 4.5:1 contrast verified by the Lighthouse audit.【F:docs/accessibility/lighthouse-report.md†L1-L15】
**Metric cards & quick filters.** Render KPIs with `ui-metric` (including the `ui-metric--accent-*` variants) and surface saved filters with `ui-filter-card` so hover/focus states and spacing match across the supplier and internal portals. See the internal task queue and shared stylesheet for the canonical implementation.【F:src/SupplierManagement/internal/templates/tasks.html†L7-L211】【F:src/SupplierManagement/portal/static/css/input.css†L1563-L1608】

2. Typography & data density

**Numeric columns.** Always include `tabular-nums text-right` and the shared rounding format enforced by regression tests for the dashboard and order tables.【F:tests/portal/test_dashboard.py†L1-L66】【F:tests/internal/test_orders.py†L1-L121】
**Headings & helper text.** Primary headings (`≤ 60` characters) use `text-lg font-semibold text-slate-900`; helper copy uses `text-sm text-slate-600`. Tooltips rely on the `hint_badge` macro which auto-injects `sr-only` content for screen readers.【F:src/SupplierManagement/portal/templates/macros.html†L182-L256】
**Status pills.** Boolean/state indicators must reuse the `status_pill` macro; extending styles outside the macro is prohibited because it already exposes colour modifiers and accessible labels.【F:src/SupplierManagement/portal/templates/macros.html†L258-L332】

3. Accessibility (a11y)

**Keyboard navigation.** Interactive controls include the `focus-visible` outline through the shared button macros. Custom controls must copy the macro semantics (`tabindex`, `aria-*`). CSRF and OTP login tests ensure keyboard-only navigation remains functional.【F:tests/portal/test_csrf_enforcement.py†L41-L158】【F:tests/SupplierManagement/test_portal_login_otp.py†L1-L58】
**Screen-reader feedback.** Alerts broadcast through `role="status"`/`aria-live="polite"`. Use the `alert_banner` macro (see the supplier dashboard action centre) when introducing new banners.【F:src/SupplierManagement/portal/templates/dashboard.html†L430-L520】【F:src/SupplierManagement/portal/templates/macros.html†L334-L420】
**Contrast & scaling.** Minimum touch target size is 44×44 px. High-contrast mode is toggled with the `contrast-boost` CSS helper described in the accessibility preference guide and covered by personalisation tests.【F:docs/accessibility/portal_preferences.md†L1-L80】【F:tests/portal/test_preferences.py†L1-L144】

4. Behaviour & feedback

**Loading skeletons.** Asynchronous widgets must render the `loading_state` macro (shimmer) across roadmap, performance, and analytics screens; omitting it is treated as a UX defect.
**Empty states.** Use `empty_state` for icon/message/CTA blocks. Deviations require UX approval. The roadmap regression test ensures empty datasets render the shared block.【F:tests/portal/test_roadmap.py†L1-L76】
**Errors & notifications.** Forms display field-level errors using `text-sm text-red-600` and surface toast/alert banners. API errors are normalised in `portal/dependencies.py`; exposing raw JSON to users is forbidden.【F:src/SupplierManagement/portal/dependencies.py†L1-L188】

5. Quality gates

**Lighthouse threshold.** Run the desktop and mobile presets for every release; both accessibility scores must stay ≥ 90. Results are tracked in `docs/accessibility/lighthouse-report.md` and CI artefacts.
**UI regression coverage.** Any macro change requires updated tests covering dashboard, orders, roadmap, and supplier detail templates to prevent regressions.【F:tests/internal/test_supplier_detail.py†L1-L74】
**Resilience smoke tests.** The integration suite `tests/integration/test_resilience.py` validates that OpenTelemetry providers are initialised. Treat a missing provider as a release blocker to satisfy Task 14 readiness gates.【F:tests/integration/test_resilience.py†L1-L80】

6. Public landing page

**Data model.** The landing page context is supplied by `PortalHomeContent`, a frozen dataclass that aggregates hero metadata, feature clusters, journey steps, resource cards, a closing call-out, and the accessibility preferences widget. Each textual field is wrapped in `LocalisedCopy` so templates may expose both translated text and the English source for regression tests.【F:src/SupplierManagement/portal/public.py†L104-L266】【F:src/SupplierManagement/portal/public.py†L333-L448】【F:src/SupplierManagement/portal/public.py†L466-L520】
**Hero & metrics.** The hero block renders CTA buttons, highlight bullets, and three `ui-metric` components using the gradient tokens from the Aurora bundle. Buttons must honour the tone defined in the dataclass to reuse the shared `ui-button` modifiers.【F:src/SupplierManagement/portal/templates/index.html†L1-L63】【F:src/SupplierManagement/portal/static/css/custom.css†L49-L153】
**Feature sections.** Lifecycle and collaboration pillars are displayed as `ui-card` clusters with bullet lists that inherit typography tokens (`var(--font-size-lg)`, `var(--color-text-secondary)`) to maintain parity with dashboard layouts.【F:src/SupplierManagement/portal/templates/index.html†L88-L139】【F:src/SupplierManagement/portal/static/css/custom.css†L207-L292】
**Journey timeline.** Four onboarding steps use muted cards with numbered badges and reinforce the process outlined in accreditation workflows. The responsive grid mirrors the spacing system shared by the roadmap template.【F:src/SupplierManagement/portal/templates/index.html†L65-L86】【F:src/SupplierManagement/portal/static/css/custom.css†L165-L206】
**Support ecosystem.** Resource cards link to support, legal, and design system routes; badges use semantic colours from the token set so hover/focus states match the rest of the portal.【F:src/SupplierManagement/portal/templates/index.html†L141-L179】【F:src/SupplierManagement/portal/static/css/custom.css†L310-L356】
**Accessibility controls.** The landing surface embeds an interactive panel powered by `accessibilityPreferences()` with `data-accessibility-pref` inputs for high contrast, larger text, and reduced motion. The helper text clarifies persistence semantics and the `Reset to defaults` CTA is mandatory for UX parity with the dashboard preferences tray.【F:src/SupplierManagement/portal/templates/index.html†L181-L241】【F:src/SupplierManagement/portal/static/css/custom.css†L358-L431】【F:tests/portal/test_accessibility.py†L68-L99】
**Workspace site map.** A grouped site map derived from `build_navigation_site_map` highlights procurement, operations, performance, and utility workspaces so visitors can preview every section directly from the landing page.【F:src/SupplierManagement/portal/navigation.py†L151-L205】【F:src/SupplierManagement/portal/public.py†L593-L638】【F:src/SupplierManagement/portal/templates/index.html†L200-L257】

Adhering to these guidelines keeps the supplier portal accessible, consistent, and ready for scale as the SRM roadmap evolves.