I would like to propose the creation of a comprehensive style guide and contribution reference for OpenELIS Global — one that spans the entire tech stack: backend, frontend, integration, and E2E tests, dataset conventions, and our UI design system.
As OpenELIS continues to grow and more contributors get involved, maintaining consistency across our stack will improve maintainability, reduce friction for new devs, and ensure smoother PR reviews.
what to cover in the guide:
Backend
Naming conventions (classes, fields, services)
Folder structure and layering
Exception handling, logging, and validation patterns
Integration test structure using datasets + DBUnit
Datasets
Naming conventions and organization
Minimal, clean test data principles
Use of schema validation
Frontend (React)
Component Structure and Folder Layout
Organize components by domain or feature, not by type (e.g., group PatientHeader, ConfirmPopup, etc. under common or relevant feature folders).
Each component lives in its own .js file, and related .css (if needed) lives alongside or in a common styles folder.
Naming Conventions
Component names use PascalCase.
File names match the component (e.g., CytologyCaseView.js).
Props should be descriptive and camelCased.
Contexts use SomethingContext or useSomething naming patterns.
Styling Guidelines
Use plain .css files; no CSS-in-JS
Reuse styles through shared CSS files where possible (PathologyDashboard.css).
Use BEM or scoped class naming to avoid global class conflicts.
Carbon Design System Integration
Use components directly from @carbon/react.
Always prefer Carbon-provided components unless business logic demands custom implementation.
Respect Carbon’s accessibility and responsive layout practices.
For icons, use only what’s available in @carbon/react/icons.
Other Principles
Use react-intl for all user-facing strings.
Favor state colocation via hooks (useState, useEffect, useRef) — no external state managers like Redux unless absolutely necessary.
Maintain clean separation of business logic and presentation within components.
E2E Testing (Cypress)
Naming structure and file organization
Setup and teardown practices
Interaction with test data / mocking vs real data strategy
Documentation & Dev Process
PR hygiene and checklist
Branch naming, commit message best practices
Prettier, ESLint, Spotless, and CI formatting enforcement
Initial Steps:
Create a Style guide in an OpenELIS Wiki.
Link it in CONTRIBUTING.md and in PULL_REQUEST_TEMPLATE.md.
Provide small usage examples and link to tooling configs.
In the context of trying to enlighten more about this especially in trying to distinguish between a design System and a Style guide, I have come across a few useful resources that were shared.
let me know if this is insightful and if there is any more consideration about it
Hi @Agaba_Derrick_Junior I think this is a fantastic idea, and I really appreciate your initiative on this! We are using Carbon just like OpenMRS, and so I think that is a perfect example, and perhaps we can re-use some of the same guidance to keep things aligned and make like easy for those who are contributing to O3 as well.
I would absolutely support the community taking this on, and working on making decisions on the community call on things like the naming conventions (some of which are covered in other places, but it needs to be brought together) and publishing the guide within our wiki and on Github. @Moses_Mutesasira and @Taib_Abdillahi I’m wondering if you guys can help to facilitate this on the OpenELIS community calls.
I anticipate this being a long-term project to get everything, though, so maybe we can also set a polished version as a goal for the next Google Docs season in February 2025, to to build on that work.
Hi @Agaba_Derrick_Junior,
I believe it’s a fantastic idea—and I’ve actually proposed E2E testing using Cypress in my GSoC proposal. As part of that, I’ve also included this part to help new contributors, covering:
Naming structure and file organization
Setup and teardown practices
Interaction with test data (mocking vs real data)
@Moses_Mutesasira@caseyi ,this should definitely be a topic to look at in my proposal, as it’s aimed at improving the onboarding and usability experience for those working on E2E tests.
Documentation & Dev Process