Layout and design-system guidelines

Design direction

Evolve the current dark prototype into a light-first enterprise system with optional dark mode. Preserve the restrained navy foundation and amber/lime brand accents, but use brand colors for identity and emphasis rather than large text blocks, low-contrast controls, or status meaning.

The product should feel calm, trustworthy, precise, and development-oriented—not gamified, punitive, or like a generic HR dashboard.

Three layout shells

Marketing shell

• Sticky header, 64–72 px high.
• Maximum content width: 1200–1280 px.
• Twelve-column grid on desktop; four columns on tablet; single column on mobile.
• Hero copy width: approximately 640 px.
• Section spacing: 80–120 px desktop, 48–72 px mobile.
• Use product visuals, workflow diagrams, and truthful proof. Do not fill pages with decorative gradients in place of content.
• Primary CTA and one secondary CTA per hero.
• Footer includes product, solutions, resources, legal, security, status, and contact links.

Documentation shell

• Header with global search.
• Left navigation: 240–280 px.
• Reading column: 680–780 px.
• Optional right table of contents: 200–240 px.
• Overall maximum width: approximately 1440 px.
• Persistent version selector where documentation versions exist.
• Clear previous/next navigation, feedback control, edit/source link where appropriate, and last-updated metadata.
• Code blocks, callouts, tables, and diagrams must remain readable on narrow screens.

Product shell

• Top bar: 56–64 px with brand, tenant/scope switcher, command search, help, notifications, and user menu.
• Desktop sidebar: 240–264 px; collapsed rail: 64–72 px.
• Main content max width: 1440 px for dashboards and tables; 960–1120 px for workflows; 640–720 px for single-column forms.
• Page padding: 24 px tablet, 32 px desktop, 16 px mobile.
• Use a consistent page header containing breadcrumb when needed, title, short description, status/context, primary action, and secondary actions.
• Do not wrap every section in a card. Use cards for meaningful grouping; use page surface, dividers, and whitespace for hierarchy.

Spacing and geometry

• Base unit: 4 px.
• Primary spacing rhythm: 8, 12, 16, 24, 32, 48, 64.
• Default control height: 40 px; compact tables may use 36 px; primary mobile controls should be at least 44 px high.
• Border radius: 8 px for controls, 12 px for cards and drawers, 16 px only for prominent marketing surfaces.
• Borders are preferred over heavy shadows. Use one subtle elevation for popovers and drawers, and a stronger one only for modals.
• Avoid full-width form controls when the expected value is short.

Typography

Use the existing licensed/system font stack discovered in the repository. Do not introduce a new hosted font without checking licensing, loading performance, and privacy.

Recommended scale:

• Use sentence case for headings and buttons.
• Do not use all caps for routine navigation. Small uppercase labels may be retained only for rare structural overlines with sufficient letter spacing.
• Do not rely on font weight alone to communicate status.

Color and theme rules

Create semantic tokens rather than hard-coded component colors:

surface.canvas
surface.subtle
surface.raised
surface.inverse
text.primary
text.secondary
text.muted
text.inverse
border.default
border.strong
action.primary
action.primary.hover
action.secondary
status.info
status.success
status.warning
status.danger
brand.amber
brand.lime
focus.ring
chart.rater.self
chart.rater.manager
chart.rater.peer
chart.rater.team
chart.rater.customer

• Brand amber/lime may be used for logo, highlights, illustrations, and selected chart accents.
• Primary actions require a dark, high-contrast token rather than yellow text on dark navy.
• Status colors must include icon/text labels and must not be the only signal.
• Validate every foreground/background pair at WCAG AA contrast.
• Dark mode is a complete theme with tested tokens, not a CSS inversion.

Page-header anatomy

Breadcrumb or scope label
Title                                      Primary action
One-sentence purpose                       Secondary actions / overflow
Status, period, owner, or last updated

Do not repeat “Overview” as a floating tab directly under every title. Use tabs only when the object has peer subviews.

Dashboards

A dashboard should answer questions, not merely fill space.

Recommended structure:

1. Scope and time filter
2. Four or fewer high-value KPI cards
3. Action/exception queue
4. One or two trends or funnels
5. Detailed table with filters and drilldown
6. Explanatory/privacy note where needed

KPI cards must show definition, period, comparison, and whether data is suppressed or incomplete.

Tables and lists

• Include search, filters, column controls, sort, pagination or virtual scrolling, selected-row count, and bulk actions where appropriate.
• Keep the first identifying column sticky on wide data sets.
• Use a details drawer for routine inspect/edit; reserve full pages for complex objects.
• Destructive actions live in an overflow menu and require clear confirmation.
• On mobile, convert rows to labeled cards or a horizontal-scroll table with a visible affordance; do not shrink text into illegibility.
• Never display raw JSON as the primary interface. Provide a developer view behind an explicit diagnostics control where useful.

Forms and wizards

• Labels remain visible; placeholders are examples, not labels.
• Put help text before or immediately after the control.
• Validate on blur and submit; do not announce errors only through color.
• Preserve user input after validation or network failures.
• Group related fields and use progressive disclosure for advanced settings.
• Use a stepper for tenant creation, integration setup, program creation, and complex imports.
• Every wizard has Save draft, Back, Continue, and Exit behavior defined.
• Show a review/diff page before publishing high-impact settings.

Empty, loading, error, and permission states

Every page and component must define:

• First-use empty state with a next action
• No-results-after-filter state
• Loading skeleton or progress state
• Recoverable error with retry
• Partial-data warning
• Permission-limited view
• Archived/retired state where applicable

The current plain access-denied page should become a branded 403 experience with a safe explanation, return action, help link, and correlation ID. It must not reveal hidden permissions or resource existence.

Survey completion layout

• Mobile-first, one primary question at a time or a short logical group.
• Persistent progress, estimated time, save state, and privacy link.
• Scale labels remain visible at both ends and are repeated for long matrices.
• “Not observed” and “Not applicable” are separate choices when the instrument distinguishes them.
• Keyboard shortcuts may be offered but never required.
• Open text fields include optional guidance and character feedback, not forced verbosity.

Results and feedback visualization

• Show the meaning of the scale and observation period.
• Always display valid response count and Not Observed rate near scores.
• Use consistent relationship colors throughout the product.
• Direct-label series; do not rely on legends alone.
• Show distribution or range where it matters, not only averages.
• Suppress groups below anonymity thresholds and explain suppression without implying who responded.
• Distinguish imported, native, self, and observer evidence.
• Do not imply that a 0.1 score difference is meaningful by visual exaggeration.
• Offer accessible tables for every chart.

Recommended result views:

• Competency overview
• Self versus others gap
• Relationship-group comparison
• Item distribution
• Role importance versus observed behavior
• Qualitative themes with source counts and evidence links
• Development priority shortlist
• Longitudinal trend with instrument/source markers

Responsive behavior

Mobile

• Individual tasks, surveys, results summaries, and PDP actions are fully supported.
• Use a bottom navigation or compact drawer for the individual workspace.
• Tables become cards or horizontally scroll with sticky identifiers.
• Drawers become full-screen sheets.
• Avoid hover-only interaction.

Tablet

• Collapsible sidebar.
• Two-column dashboards where content allows.
• Forms remain one column unless the relationship between fields is obvious.

Desktop

• Use available width for comparison and management, not for excessively long text lines.
• Support compact and comfortable density for data-heavy admin screens.

Accessibility baseline

• WCAG 2.2 AA target.
• Complete keyboard navigation and visible focus.
• Semantic landmarks and headings.
• Skip link in marketing, docs, and application shells.
• Correct labels, descriptions, errors, and live regions.
• No color-only meaning.
• Reduced motion support.
• Accessible name for every icon-only action.
• Screen-reader alternatives for charts and relationship matrices.
• Focus management for dialogs, drawers, validation, and route changes.

Content style

• Use direct, human language: “Invite raters,” not “Generate rater assignments.”
• Explain consequences: “HR can see completion, not your answers.”
• Replace “wrapped survey” with the product term selected in the glossary.
• Replace “reseal pending envelopes” in normal UI with “Restore access after key change,” while documenting the technical process internally.
• Buttons describe the result: “Create program,” “Send reminders,” “Publish report.”
• Avoid generic buttons such as “Load” when the user can choose “View Q3 results.”