RFC: Design Overhaul for OpenSearch Dashboards & OUI (OUI 2.x) #1636
Description
1) Summary
This RFC proposes a design-system overhaul for OpenSearch Dashboards (OSD) and OpenSearch UI (OUI). We will found OUI 2.x as a modern, accessible, open-source, and community-governed system that:
- delivers a dense, performant UI for data-heavy observability workflows
- enables rapid iteration and a healthy contributor experience
- provides a robust theming and tokens architecture for projects in and beyond the OpenSearch org
- maintains a practical migration path from existing OUI usage
2) Motivation
- UX quality & information density: Observability users need compact layouts, powerful tables, keyboard-first interactions, and high-performance visuals.
- Maintenance & sustainability: Current OUI lacks governance rigor, accessibility audits, and token support expected by modern OSS contributors.
- Open-source alignment: A system that’s easy for external contributors to consume, extend, and theme in downstream plugins/solutions.
- Predictability & migration: Clear upgrade path avoids “rewrite or bust.”
3) Goals & Non-Goals
Goals
- Accessibility-first: Target WCAG 2.2 AA.
- Design tokens: W3C Design Tokens → CSS vars, theming contexts, density modes, RTL.
- Enterprise components: Data Grid, Date/Time Pickers, Combobox, Filter Builders, etc.
- Performance: SSR/SSG-friendly, tree-shaking, virtualization, no heavy runtime styling.
- Developer experience: Storybook, a11y tests, visual regression tests, semantic-release.
- Migration tooling: Codemods, compat shims, deprecation guides.
Non-Goals
- Complete reskin all at once — adoption will be phased.
- Dictating a single charting library — charting remains pluggable.
4) Landscape & Prior Art
| Option | Type | A11y | Theming/Tokens | Density Fit | DevExp | Notes |
|---|---|---|---|---|---|---|
| Radix Primitives | Headless primitives | Strong defaults | Pairs w/ Tailwind tokens | Excellent for custom DS | Low-level | Stable APIs, flexible |
| shadcn/ui | Radix + Tailwind scaffolding | Radix a11y | Tailwind tokens, ownable | Easy dense UIs | Copy-to-project model | Needs governance |
| React Aria | Headless behavior lib | Best-in-class | Bring-your-own | Excellent keyboard UX | Low-level assembly | Strong if a11y is #1 |
| Headless UI | Headless (Tailwind) | Good | Easy Tailwind theming | Small but solid | Dev-friendly | Limited surface |
| MUI | Full suite | WCAG-focused | Strong | Mid-density, Material look | Huge docs, plugins | Version lock risk |
| Mantine | Full suite | Good | CSS vars, theming | Strong widget set | Great docs | Vibrant OSS |
| Chakra UI | Full suite | A11y-minded | Theme tokens | Mid-density | DX-friendly | Simpler enterprise support |
| Ant Design | Full suite | Improving | Theming support | Dense by default | Mature | Heavy styling conventions |
| Fluent UI | Full suite | A11y committed | Tokens, CSS vars | Enterprise coverage | Mature | Strong RTL/i18n |
| Carbon (IBM) | Full suite | Strong | Tokens | Enterprise & dense | Well-documented | IBM look unless themed |
| PatternFly | Full suite | Strong | Tokens | Enterprise UIs | Mature | Opinionated visuals |
Key takeaways:
- For flexibility, Radix + Tailwind (shadcn-style) or React Aria excel.
- For breadth, Mantine, MUI, AntD, or Fluent are pragmatic choices.
- Hybridization is possible (suite + Radix components where needed).
5) Evaluation Criteria
- Accessibility: WCAG 2.2 AA, keyboard, AT, ARIA fidelity.
- Performance: SSR/SSG, low bundle size, virtualization.
- Theming & Tokens: JSON → CSS vars, density, RTL, dark/HC modes.
- Data components: Data Grid, Date Pickers, Combobox, Tree/Virtualized Lists.
- DX & Community: Storybook, tests, codemods, semver, contributor-friendly.
- Governance: Maintainers, triage SLAs, ADRs, security process, design council.
6) Proposal
OUI 2.x Foundation
POC bake-off:
- Track A: Radix Primitives + Tailwind (+ shadcn scaffolding)
- RFC proposals
Each track must implement: Button, Combobox, Date/Time Picker, Data Grid, Popover/Menu, Tabs, Dialog, Toast, Forms.
Tokens & Theming
- Source: W3C Design Tokens JSON
- Build: CSS variables
- Modes: light/dark/HC, compact/comfortable, brand themes
Accessibility
- CI: axe + keyboard test harness
- Checklist per component (focus traps, ARIA, inert background, etc.)
Data Grid
- Virtualization, keyboard ops, pinning, aggregation, copy/export.
- If lacking, ship under
@opensearch-project/oui-datagrid.
Distribution
- Packages:
@opensearch-project/oui-* - Semver + changelogs
- Codemods + deprecation guides
7) Migration Plan
- OSD 4.x branch with OUI 2.x
- Feature adoption order: Chrome → Discover → Visualizations → Dashboards → Workspaces -> Dev Tools → Notebooks.
8) Governance
- Maintainers map with community seats
- Issue triage: weekly rotations, SLAs
9) Risks
| Risk | Impact | Mitigation |
|---|---|---|
| A11y regressions | High | CI + manual audits |
| Theming drift | Medium | Central tokens + lint rules |
| Data Grid complexity | High | Dedicated package, staged features |
| Upgrade churn | Medium | Codemods + shims |
10) Alternatives
- Double down on OUI 1.x: Full control but high effort.
- React Aria only: Excellent a11y, but slower breadth.
- AntD/Fluent/Carbon: Mature but opinionated visuals.
- Headless UI only: Lightweight but small surface.
11) Open Questions
- Which frameworks for POC bake-off?
- What bundle size budgets per component/shell?
- Should we ship our own Data Grid package?
- How strict should density guarantees be?
- How should downstream projects extend tokens?
12) Milestones
| Phase | Duration | Exit Criteria |
|---|---|---|
| RFC Ratification | 2w | Bake-off frameworks + acceptance tests |
| POC Bake-off | 4w | Core component list complete, metrics published |
| Decision & ADR | 1w | Primary foundation chosen |
| OUI 2.x Foundations | 6–8w | Tokens, theming, core components, docs |
| OSD 4.x Opt-in | 8–12w | Shell + Discover migrated, codemods |
| Feature Rollout | Ongoing | Dashboards, Workspaces, APM, SA, Notebooks |
14) Decision Matrix (Example)
| Criteria | Radix+Tailwind (shadcn) | Mantine | MUI | React Aria |
|---|---|---|---|---|
| A11y fidelity | High | Good | Good | Excellent |
| Tokens/theming | Excellent | Good | Good | Excellent |
| Density control | Excellent | Good | Medium | Excellent |
| Breadth day-1 | Medium | High | High | Low |
| DX/docs | Good | High | High | Medium |
| Lock-in risk | Low | Medium | Medium | Low |
| Migration support | Good | Good | Good | Good |
Call to Action
Please comment with:
- Your preferred two tracks for the bake-off
- Additional acceptance tests to enforce
- Components you consider P0
- Volunteers for POC builds, a11y audits, or docs
If consensus emerges by 9/30, we’ll promote to Accepted, open POC issues, and kick off with a community call.