Upgrading an existing app to use BAgel

Why migrate?

• Low integration effort: Ship improvements without tearing down your app.
• Framework agnostic components: Works wherever HTML does.
• Scoped styling and accessibility: Components encapsulate styles and come with built-in accessible behavior and BA branding.

What changes in development?

• You will render custom elements like ba-button , ba-link , etc.
• Handle DOM events or custom events directly, and pass string/number/boolean attributes as inputs.
• Existing state management, routing, and data layers remain intact.

For detailed Dev guidance, see: Getting Started

Note on React 18

All BAgel components work with React 19, and upgrading is recommended if possible. Some interactive components (such as ba-button and ba-input-text) will not work in React 18. However, this should not slow down the adoption of BAgel. Many components (such as ba-content, ba-page-segment, ba-icon) can still be integrated to bring in the brand look and feel and start addressing accessibility issues such as contrast.

Refer to the React 18 and 19 compatibility table for more details on components that are compatible with React 18.

Adoption strategy

BAgel can be adopted incrementally alongside your existing components and codebase, allowing you to gradually improve your app without a complete rewrite. Here’s a suggested approach:

1) Start small and build up

1. Begin with branding components: <ba-content>, <ba-image>, <ba-icon>. These are quick wins that bring in BA’s look and feel with minimal risk.
2. Move to structural layout components: <ba-header-global>, <ba-page-segment>, <ba-grid>, <ba-footer>.
3. Once the core layout and branding are established, you can start integrating more complex components.

2) Apply the Boy Scout Principle

Always leave the codebase cleaner than you found it. As you work on existing issues, allow some scope for developers to replace the existing UI with BAgel equivalents and swap manual ARIA and interaction code for BAgel’s built-in patterns. This will help you gradually migrate without needing to refactor large sections at once.

Accessibility and QA

An essential part of migrating to BAgel is aligning with its QA guidelines. Here is how to integrate:

1) Understand accessibility standards

All apps must meet WCAG 2.2 Level AA compliance. These are industry standard accessibility guidelines developed by W3C

2) Integrate BAgel into your test plan

• Familiarise yourself with BAgel component documentation and allowed parent-child combos.
• Define the scope and list the pages and flows to test.
• Set measurable accessibility goals.
• Create detailed test cases covering expected versus actual results.

3) Use the BAgel helper in testing environments

Enable the BAgel helper to flag invalid combinations or prop usage in the console, helping you
avoid building inaccessible patterns.

4) Manual and automated testing

• Visual regression testing (VRT): Run baseline UI screenshots before and after BAgel adoption to catch regressions.
• Accessibility audits: Use tools like Axe or Pally, plus keyboard-only navigation and screen reader smoke tests.
• Performance audits: Use Lighthouse, Web Vitals, and bundle size comparisons.

5) Rollout strategy

• Flag early pages and components for QA monitoring.
• Prioritise quick fixes and early feedback.
• Extend rollout in waves, keeping a rollback plan in place.

For detailed QA guidance, see: QA getting started

Issues you might hit (and suggested fixes)

CSS clashes

BAgel provides some global resets and styles for elements like <a> and typographic scales, even though most component styles are encapsulated.

Mitigation strategies:

• Namespace legacy CSS under a root class (e.g., .legacy-app { … } ) to reduce conflicts.
• Load BAgel's CSS before your overrides and only override when necessary.
• Match your base typography scale and line height to BAgel defaults to avoid rhythm drift.

JavaScript interoperability

• Attach listeners imperatively via refs when custom events do not map to React props.
• Pass non-primitive data via properties (not attributes) using refs or helper hooks.
• For SSR hydration, ensure the initial markup’s attributes match BAgel’s defaults to avoid warnings