# Barua UI

> An interface design system with Apple's design language, rebuilt natively
> for the web: plain HTML and CSS, one stylesheet, no build step. Build
> interfaces by composing documented components — never by inventing CSS.

Ask the system directly (MCP, streamable HTTP):
- https://mcp.barua.tz/mcp — search_components, get_component, get_react, get_rules, lint_markup

Machine-readable index of every component, with canonical markup:
- [barua-ui.json](https://ui.barua.tz/barua-ui.json): complete component index
- [llms-full.txt](https://ui.barua.tz/llms-full.txt): the whole system as markdown
- Every documentation page has a markdown twin at the same address: https://ui.barua.tz/docs/forms.html is also https://ui.barua.tz/docs/forms.md — same content, no HTML to parse, and one page instead of the whole index.

## Rules

1. Compose from documented components. If a pattern is not in the docs, use a documented alternative or promote a new component into the docs first — never invent markup or CSS in product code.
2. Copy the anatomy from the docs demo: same wrapper elements, same slots, same class combinations. A component's parts (__header, __body, __footer) only exist inside their block.
3. Never hardcode colour, spacing, radius or shadow. Use --b-* tokens. A raw hex in product code is a bug.
4. Inline styles are only for documented knobs (--v, --b-progress, --b-thumb-size, --b-heatmap-cols, --b-circular-size) and artwork backgrounds.
5. Icons come from the icon library (docs/icons.html): inline 20x20 SVG, 1.5px stroke, currentColor, sized with .b-icon/--sm/--lg. Never emoji, never letters as icons. A directional mark inside a sentence is text, not an icon: the arrow in a .b-stat__delta stays. The rule governs icon slots, where a glyph stands on its own.
6. Never use a native <select> or native date/time inputs in product surfaces: their popups cannot be styled. Use the menu select and the calendar-in-dropdown patterns.
7. On desktop a surface does not page-scroll. Use .b-stage for screens that must fit, and .b-scroll-area for the panes that may grow.
8. A scroll pane's children must never be forced to the pane's height (no h-full inside a scroll area) or scrolling silently dies.
9. Hover, selection and active are different states and must look different: hover is a quiet fill, selection is accent-soft, focus is the focus ring.
10. Dashboards: name the one question the screen answers before laying anything out. Pick an archetype — overview, monitoring, analytics, work queue, record, console — because variety comes from choosing a different one, not from decorating the same one.
11. A dashboard has five layers read top to bottom, each answering the same question at a different depth — what, then why, then what now: 1 context (title, period, filters), 2 verdict (three or four figures), 3 evidence (one dominant chart plus a companion, e.g. spans 8 and 4), 4 detail (lists and tables), 5 tail (links out). Four or five layers is a page; six is two pages pretending to be one. A figure led 40 of 51 surveyed pages and figure-then-list was the commonest adjacency.
12. Dashboard rhythm: consecutive layers must not share a column split. Quarters, then eight-and-four, then halves. A page where every band is the same shape reads as a spreadsheet with rounded corners whatever is in it.
13. A row of dashboard cards should not stretch to match its tallest: grid stretches by default and a short card grows dead space at its foot. Use align-items: start and let heights differ, or give the short card more to say.
14. Dashboard spacing groups the layers: .b-gap-6 between bands and .b-gap-3 or .b-gap-4 within one. That difference does the grouping, so a well-spaced dashboard needs almost no rules or boxes.
15. The first screen of a dashboard owes the reader context and verdict plus the top of the evidence. If the figures need scrolling to reach, something above them — a hero, a greeting, a banner — is taking space it has not earned.
16. Dashboard composition: widths are full, half, third or quarter and a row totals twelve. Three or four figures on the top row, never five. One dominant element per screen, or the page reads as a spreadsheet with rounded corners.
17. Charts: time is a line or an area, comparison across categories is a bar — those three are 84% of charts in a 457-page survey of admin templates. Pie and donut were 3%; use them only for two to four parts of a genuine whole. A number that matters more than its trend is a .b-stat, not a chart.
18. Every chart carries role="img" and an aria-label stating the takeaway rather than the chart type: "peaking Thursday at 4,120", not "bar chart of sends". Only 2% of surveyed dashboard pages labelled a chart at all. Give charts a ceiling with --b-chart-h or a tall series drags the card with it.
19. Every dashboard widget has four states: loading, empty, error and loaded. Three pages out of 457 surveyed had a "no data" message. Use .b-skeleton while fetching and .b-empty with an action when there is nothing.
20. A table on a dashboard shows five to ten rows and links to the full list — it is a sample, not the archive. Columns of figures take .b-tabular-nums, and a delta states direction and period: "up 8.2% this week", never a bare arrow.
21. Surfaces never stack materials. A panel inside glass is a fill, not a second material — nesting one blur inside another makes the GPU blur an already-blurred backdrop, which is the main way this system gets slow.
22. Materials turn opaque under prefers-reduced-transparency and where backdrop-filter is unsupported, so never use translucency alone to carry meaning.
23. Over an unknown background use .b-card--neutral, whose material is derived from the backdrop rather than from the theme.
24. Light and dark come from light-dark() and data-theme. Never write a second dark stylesheet; never branch on theme in product code.
25. Every interactive element states its accessible name, keyboard behaviour and state through ARIA; .is-* classes are for looks, ARIA is for meaning.
26. Vary composition deliberately: the same three cards in a row is not a design. Choose a layout archetype that fits the content, then vary density, span rhythm and material within the system.

## Documentation

- [Principles — the eight ideas the system is built on, and what enforces each](https://ui.barua.tz/docs/principles.html): 8 components
- [Theming — light and dark, the named accents, and carrying a brand colour without breaking danger](https://ui.barua.tz/docs/theming.html): 5 components
- [Wallpapers — pictures shipped finished: sized, blurred, with the accent and scheme already worked out](https://ui.barua.tz/docs/wallpapers.html): 10 components
- [React — the typed bindings: install, Server Components, and the component index](https://ui.barua.tz/docs/react.html): 7 components
- [Foundations — tokens, colour, type, materials, motion](https://ui.barua.tz/docs/foundations.html): 20 components
- [Icons — the 20×20 glyph set](https://ui.barua.tz/docs/icons.html): 3 components
- [Layout — stacks, grids, containers, stage, scroll areas](https://ui.barua.tz/docs/layout.html): 18 components
- [Actions — buttons, icon buttons, toolbars, links](https://ui.barua.tz/docs/actions.html): 11 components
- [Navigation — bars, sidebars, tabs, menus, command palette](https://ui.barua.tz/docs/navigation.html): 15 components
- [Forms — fields, selects, switches, sliders, validation](https://ui.barua.tz/docs/forms.html): 19 components
- [Content — cards, lists, tables, badges, avatars](https://ui.barua.tz/docs/content.html): 22 components
- [Feedback — alerts, toasts, progress, skeletons, empty states](https://ui.barua.tz/docs/feedback.html): 13 components
- [Overlays — modals, sheets, popovers, tooltips, lightbox](https://ui.barua.tz/docs/overlays.html): 14 components
- [Data visualization — CSS charts](https://ui.barua.tz/docs/data-viz.html): 18 components
- [Media — galleries, players, thumbnails](https://ui.barua.tz/docs/media.html): 12 components
- [Specialized — calendars, pickers, file browser](https://ui.barua.tz/docs/specialized.html): 18 components
- [Authentication — sign in, OTP, account switching](https://ui.barua.tz/docs/authentication.html): 10 components
- [System pages — errors, empty, onboarding](https://ui.barua.tz/docs/system.html): 11 components
- [Dashboards — archetypes, composition, choosing a chart, and the four states every widget has](https://ui.barua.tz/docs/dashboards.html): 10 components
- [Productivity — dashboards, workspace, dock, control centre](https://ui.barua.tz/docs/productivity.html): 18 components
- [Interaction — states, drag and drop, shortcuts](https://ui.barua.tz/docs/interaction.html): 20 components
- [Mobile — headers, tab bars, sheets, safe areas](https://ui.barua.tz/docs/mobile.html): 11 components
- [Marketing — landing pages: hero, chapters, figures, bento, site footer](https://ui.barua.tz/docs/marketing.html): 16 components
- [Infrastructure — naming, theming, accessibility, contribution](https://ui.barua.tz/docs/infrastructure.html): 17 components

## Examples

- [dashboard](https://ui.barua.tz/examples/dashboard.html): a complete screen, documented components only
- [ambient](https://ui.barua.tz/examples/ambient.html): a complete screen, documented components only
- [music](https://ui.barua.tz/examples/music.html): a complete screen, documented components only
- [settings](https://ui.barua.tz/examples/settings.html): a complete screen, documented components only
- [checkout](https://ui.barua.tz/examples/checkout.html): a complete screen, documented components only
- [auth](https://ui.barua.tz/examples/auth.html): a complete screen, documented components only
- [analytics](https://ui.barua.tz/examples/analytics.html): a complete screen, documented components only
- [inbox](https://ui.barua.tz/examples/inbox.html): a complete screen, documented components only