After implementing branding solutions for multiple enterprise clients, I can offer some strategic perspective on this decision. The choice between custom form layouts and theme CSS overrides fundamentally comes down to three factors: theme CSS override complexity, custom layout maintenance burden, and accessibility compliance requirements.
Theme CSS Overrides:
This approach works exceptionally well when your branding requirements align with OutSystems’ default form structure. The advantages are significant: you inherit platform improvements automatically, maintenance is minimal, and OutSystems’ built-in accessibility features remain intact. The key to success is establishing a robust CSS architecture using custom properties and utility classes, as Rachel mentioned. Your overrides should focus on visual presentation - colors, typography, spacing, shadows - without altering the fundamental DOM structure or interaction patterns.
For WCAG 2.1 AA compliance with theme overrides, create an accessibility testing checklist that covers:
- Color contrast ratios (4.5:1 for normal text, 3:1 for large text)
- Focus indicator visibility and contrast
- Touch target sizes (minimum 44x44 pixels)
- Screen reader announcement accuracy
- Keyboard navigation flow
- Form field label associations
Implement automated testing with tools like aXe or Lighthouse in your CI/CD pipeline, but supplement with manual testing using actual assistive technologies. Document every CSS override with comments explaining its purpose and accessibility considerations.
Custom Layout Maintenance:
Custom layouts become necessary when you need structural changes that CSS alone cannot achieve - complex multi-column layouts, custom input components, or interaction patterns that deviate significantly from OutSystems defaults. The maintenance burden is real but manageable if you treat custom layouts as reusable components. Build a component library of accessible, brand-compliant layouts that can be applied across forms rather than creating bespoke solutions for each form.
The hidden cost of custom layouts appears during platform upgrades. OutSystems regularly improves their form widgets for performance, accessibility, and mobile responsiveness. With custom layouts, you’re responsible for implementing these improvements yourself. This requires dedicated resources and ongoing commitment.
Accessibility Compliance:
Regardless of your approach, accessibility must be a first-class requirement from day one. For your 25+ forms, I’d recommend:
- Start with theme overrides as your default approach
- Build a small library of custom layout blocks for genuinely unique requirements
- Establish strict governance: all CSS changes require accessibility review
- Create reusable CSS utility classes that encode accessibility best practices
- Implement automated accessibility testing in your deployment pipeline
- Conduct quarterly manual accessibility audits with real assistive technologies
For your specific situation with moderate branding needs, theme overrides are the pragmatic choice. Reserve custom layouts for forms with truly unique structural requirements. This hybrid approach gives you 80% of the benefit with 20% of the maintenance overhead.
One final consideration: document your decision and rationale thoroughly. In two years when team members change, having clear guidelines on when to use each approach prevents architectural drift and maintains consistency across your application. Include code examples, accessibility checklists, and decision trees to guide future development.
The maintenance advantage of theme overrides becomes more pronounced as your application scales. With 25+ forms today, you’ll likely have 50+ within a year. Custom layouts multiply maintenance effort linearly with form count, while theme overrides maintain constant overhead regardless of scale.