/
OpenELIS Global Style Guide

OpenELIS Global Style Guide

  • Rough draft

    • Overview
    Document URL: OpenELIS Style Guide- DIGI Wiki  
    Why We Are Defining the OpenELIS Global Style Guide System

    Scope of the Guide

    Colors and Accessibility Standards

    Typography

    OpenELIS Global is an open-source Laboratory Information System (LIS) designed to meet the unique needs of clinical and public health laboratories worldwide. It is critical in strengthening laboratory operations, improving data quality, and enabling better patient care through efficient sample and test result management.
    This Style Guide establishes the visual, structural, and technical standards for OpenELIS to ensure consistency, usability, and professional quality across all system parts. It is intended for developers, designers, contributors, and implementers who are working on the OpenELIS


    Why We Are Defining the OpenELIS Global Style Guide System

    OpenELIS Global is a laboratory information system used across diverse health systems and countries, each with different needs, but all sharing the same challenges: inconsistent user experience, outdated frontend tooling, and fragmented engineering practices. Historically, visual and interaction design across OpenELIS implementations has been inconsistent, making collaboration difficult and increasing the cost of maintenance and onboarding.

    This style guide is our response to that. It sets the baseline for a unified, modern, and accessible design system across all OpenELIS Global interfaces, regardless of country, customization, or use case. It helps us ship faster, with fewer regressions. It ensures our software is usable by everyone, including users on low-bandwidth networks, older hardware, and with varying levels of digital literacy or ability.

    This documentation is not theoretical. It directly results from real implementation experience, active deployments, and the hard-earned lessons of maintaining a global open-source LIS. The aim is to reduce guesswork, eliminate inconsistency, and make OpenELIS easier to contribute to, extend, and scale.

    We’re not just redesigning components—we’re raising the baseline.

    Objectives of This Guide:

    • Create a clear and consistent user experience (UX) across OpenELIS interfaces.

    • Improve the maintainability and scalability of the OpenELIS design and code.

    • Ensure accessibility, internationalization, and responsiveness.

    • Support collaboration across distributed teams and contributors.

    Who Should Use This Guide:

    • Software engineers write frontend and backend code.

    • UX/UI designers create layouts, workflows, and visual elements.

    • QA testers ensure functionality aligns with expected behavior.

    • Documentation writers prepare user manuals and technical guides.

    • Implementers and administrators customizing or deploying OpenELIS.

    Scope of the Guide:

    • Visual design (colors, typography, icons)

    • User interface components and behavior

    • Code style and architectural patterns

    • Naming conventions and best practices

    • Accessibility and Usability Standards

    Colors and Accessibility Standards

    Color & Accessibility Standards

    This guide defines how OpenELIS uses color in its UI across brand elements, components, and accessibility cues. Colors are categorized into primary (core branding), secondary (complementary use), neutrals (backgrounds, borders, text), and accessibility colors (status indicators like success, warning, and error).

     

    Use these definitions to ensure visual consistency, accessibility compliance, and maintainable design across the system. If you’re picking a color that’s not in this guide, you’re doing it wrong.

    Primary colors

    These are the core brand colors used for actions, highlights, and key UI elements.

    Token

    Hex Value

    Preview

    Description

    Token

    Hex Value

    Preview

    Description

    --cds-focus

    #0f62fe

     

    Focus state (accessibility)

    --cds-link-primary

    #0f62fe

     

    Primary link color

    --cds-button-primary

    #0f62fe

     

    Primary action button

    --cds-background-brand

    #0f62fe

     

    Brand background color

    These define the main call-to-action (CTA) color and represent the OpenELIS identity in user interaction (buttons, links, focus states, etc.).

    Secondary colors

    These support the primary colors, often used for less prominent actions or background accents.

    Token

    Hex Value

    Color Preview

    --cds-button-secondary

    #393939

     

    --cds-button-tertiary

    #0f62fe

     

    --cds-link-secondary

    #0043ce

     

    --cds-link-visited

    #8a3ffc

     

    --cds-button-secondary-hover

    #474747

     

    These are used for secondary actions, hover states, or visited links — they complement but do not distract from primary CTAs

    Neutrals

    Neutral tones are used for backgrounds, borders, and base UI elements.

    Examples:

    Token

    Hex Value

    Color Preview

    --cds-background

    #ffffff

     

    --cds-layer-01

    #f4f4f4

     

    --cds-field-01

    #f4f4f4

     

    --cds-border-subtle-01

    #e0e0e0

     

    --cds-icon-primary

    #161616

     

    --cds-text-primary

    #161616

     

    --cds-text-secondary

    #525252

     

    These establish the structural framework of the UI, ensuring clarity and hierarchy without drawing attention

    AccessibilityIn progress

    Accessibility / Status Colors

    Used for feedback, validation, and alerts.

    Token

    Hex Value

    Color Preview

    --cds-support-error

    Not Provided

     

    --cds-support-warning

    Not Provided

     

    --cds-support-success

    Not Provided

     

    --cds-support-info

    Not Provided

     

    --cds-text-error

    Not Provided

     

    Typography

    1. Font Family

    Font Stack

    Description

    Font Stack

    Description

    IBM Plex Sans, sans-serif

    Primary font aligned with Carbon Design System

    Arial, sans-serif

    Fallback for system compatibility

    2. Font Sizes

    Follow a modular scale for clarity and consistency:

    Token

    Size (px)

    Usage

    --text-xs

    12px

    Captions, helper text

    --text-sm

    14px

    Form labels, small controls

    --text-base

    16px

    Default body text

    --text-lg

    18px

    Subheadings, emphasized text

    --text-xl

    20px

    Section titles

    --text-2xl

    24px

    Page titles

    --text-3xl

    32px

    Main application headers

    3. Font Weights

    Weight

    Value

    Usage

    Regular

    400

    Body text

    Medium

    500

    Subheadings

    Bold

    700

    Headings

    4. Line Height

    Context

    Line Height

    Base text

    1.5

    Headings

    1.25

    Tight UI

    1.3

    5. Letter Spacing

    Element

    Letter Spacing

    Body text

    normal

    Headings

    0.5px

    Captions

    0.3px

    6. Text Colors

    Ensure all text meets WCAG AA contrast standards.

    Token

    Color Example

    Hex Code

    Usage

    Token

    Color Example

    Hex Code

    Usage

    --text-primary

    🟫 #161616

    #161616

    Main content text

    --text-secondary

    🟥 #525252

    #525252

    Less prominent text

    --text-disabled

    ⬜ #A8A8A8

    #A8A8A8

    Disabled form/input text

    --text-inverse

    ⬛ #FFFFFF

    #FFFFFF

    Text on dark backgrounds

    7. Heading Styles

    Heading

    Font Size

    Font Weight

    Line Height

    Token

    Example

    h1

    32px

    700

    1.25

    --heading-xl

    Main Page Title

    h2

    24px

    700

    1.25

    --heading-lg

    Section Title

    h3

    20px

    500

    1.5

    --heading-md

     

    8. Responsive Typography

    Use fluid scaling techniques:

    font-size: clamp(1rem, 2vw, 1.5rem);

    This ensures text is legible across all screen sizes.

    9. Accessibility Guidelines

    • Minimum font size: 16px for base text

    • Contrast ratio: >= 4.5:1

    • Avoid all uppercase headings unless letter-spacing is increased for legibility

    • Ensure screen readers can differentiate heading levels with semantic HTML

    10. Spacing Guidelines

    Token

    Value

    Usage

    --spacing-sm

    8px

    Small vertical spacing

    --spacing-md

    16px

    Default section spacing

    --spacing-lg

    24px

    Separation between blocks

    11. Carbon Design Token Mapping

    Carbon Token

    OpenELIS Equivalent

    Usage

    productive-heading-01

    --heading-sm

    Small headers

    expressive-heading-03

    --heading-lg

    Large page titles

    body-short-01

    --text-sm

    Labels

    body-long-02

    --text-base

    Paragraphs

    12. Developer & Designer Integrationin Progress

    • CSS Tokens: Provide a SCSS or CSS file with all defined tokens.

    • Figma: Define global text styles and link them to code tokens.

    • Component Libraries: Wrap standard tokens into reusable <Typography> components.

    13. Examples (Live Preview Code)
    <h1 style="font-size:32px; font-weight:700;">Page Title (h1)</h1> <p style="font-size:16px; line-height:1.5; color:#161616;"> Body text using base font size and primary color. </p> <small style="font-size:12px; color:#525252;"> Caption with secondary color. </small>

    This typography guide is the single source of truth for text-related styling in OpenELIS. Any new UI work must conform to this guide for consistency, accessibility, and maintainability.

    Iconsin progress

    Tables
    Buttons
    Forms

    OpenELIS & Carbon Designin progress

    Integrating the Carbon Design System into OpenELIS isn't just a UI upgrade—it's a strategic improvement that brings modern UX practices into an essential healthcare tool. It enhances efficiency, scalability, and global usability in public health laboratories. As part of our Roadmap for Software release, we adopt the Carbon Design System for UI/UX standardization and modernization

    Carbon enables OpenELIS to maintain a unified, scalable interface while reducing maintenance overhead. By leveraging a professionally maintained design system, OpenELIS contributors can focus on lab-specific functionality rather than UI infrastructure.

    Key Principles for Implementers

    1. Consistency: Use Carbon components for all new features.

    2. Extensibility: Customize via Carbon’s theme tokens (not custom CSS).

    3. Interoperability: Follow Carbon’s API patterns for third-party integrations.

    Documentation Links