Design-System Infrastructure

MCP server

The system is also a service. Rather than loading a 500 KB index into context, an agent can ask it questions — and, more usefully, hand back the markup it just wrote to be judged before shipping it. Hosted, so a coding agent that has never seen this repository can still use the system correctly:

claude mcp add --transport http barua-ui https://mcp.barua.tz/mcp

Five tools. search_components finds things by name, purpose or class. get_component returns one component’s anatomy — every class, the knobs it reads from your markup, the states it answers to, and the canonical markup taken from its own live demo. get_rules returns the rules, the grid spans that exist and all 44 knobs. get_react answers the same question for the React package — the import line and the JSX for a component's documented example — and lint_markup takes HTML or JSX and reports every violation: invented classes, hardcoded colour, inline properties that are not knobs, native <select> and date inputs, emoji used as icons, and scroll panes that cannot scroll.

The endpoint answers a plain GET with its own description, so mcp.barua.tz is readable in a browser. Requests are rate limited and nothing is stored; markup you send for linting is written to a temporary file, checked against the stylesheets, and discarded.

To run it beside your own copy of the system instead — which keeps your markup on your machine — point the same server at a local checkout:

claude mcp add barua-ui -- node /path/to/barua-ui/mcp/barua-ui-mcp.mjs

Design Tokens

Every visual decision is a custom property prefixed --b-, defined once in css/tokens.css. Tokens come in three tiers: primitives are raw values (--b-blue-500 is Barua blue), semantic tokens give values meaning and carry the light/dark pair (--b-color-accent), and components consume the semantic tier — never the primitives.

/* 1 · primitive — a raw value */
--b-blue-500: #0a7aff;                        /* base — Barua blue */

/* 2 · semantic — meaning + light/dark pair */
--b-color-accent: light-dark(#0a7aff, #0a84ff);

/* 3 · component — consumes the semantic token */
.b-btn--primary { background: var(--b-color-accent); }

Token families

Rule. Components consume semantic tokens only. If you find yourself reaching for --b-blue-500 or a raw hex value inside a component, you want --b-color-accent (or a new semantic alias) instead — that is what keeps dark mode and accent re-tinting free.

Architecture & Layers

Barua is one stylesheet with a declared cascade. css/barua.css opens with @layer tokens, base, utilities, components; — later layers win, so components can rely on base and utilities without specificity wars. Your own overrides live unlayered, and unlayered CSS always beats layered rules: a plain .b-btn { border-radius: 0 } in your app stylesheet wins without !important.

css/
├─ barua.css       ← single entry point: @layer order + @import list
├─ tokens.css      ← every design token            @layer tokens
├─ base.css        ← reset, type, focus, states    @layer base
├─ utilities.css   ← layout primitives, text roles @layer utilities
└─ components/     ← one file per family           @layer components
   ├─ actions.css       nav.css         forms.css
   ├─ content.css       feedback.css    overlays.css
   ├─ charts.css        media.css       specialized.css
   └─ productivity.css  mobile.css      auth.css

Consumers import exactly one file (plus the optional no-dependency JS helpers):

<link rel="stylesheet" href="css/barua.css">
<script defer src="js/barua.js"></script>

Naming Conventions

BEM with a b- namespace. If a class starts with .b- it ships with Barua; if it starts with .is- it is runtime state; if an attribute starts with data-b- it is a JS behavior hook, never a styling hook.

Component Variants

Variants are modifier classes along two standard axes. The visual axis sets prominence — primary, tinted, outline, ghost, glass, danger — and reads the same on every component that offers it. Buttons carry the full set:

The semantic axis sets tone — success, warning, danger — and maps straight onto the semantic color tokens, so the same modifier names appear on .b-badge, .b-alert, .b-toast, .b-progress and .b-status:

Rule. Variants change look, not behavior. A .b-btn--danger is still a button — same height, focus ring, loading spinner and keyboard handling as every other button. Behavior differences deserve a different component, not a variant.

Component States

State is expressed twice: an aria-* attribute for assistive technology and, where no semantic attribute exists, an .is-* class for styling. Barua's selectors target both, so setting the aria attribute alone is enough for the components below. The full state language lives in Interaction.

Component Sizes

One height scale for every control, held in the --b-control-h-* tokens. Modifiers are --xs, --sm, medium by default, --lg, --xl; font size and radius step down or up with the height.

Touch targets. 44px (--b-touch-target) is the minimum hit area on touch layouts — exactly --b-control-h-lg, so prefer --lg controls on mobile. Smaller controls can keep their compact look and still hit the target with the .b-touch-target utility, which expands the hit area invisibly.

Icon System

Icons are inline SVGs on a 20×20 viewBox: 1.5px strokes, round caps and joins, fill="none", and currentColor throughout so they inherit text color in every variant and theme. The .b-icon wrapper sizes them — --sm 16px, default 20px, --lg 24px, --xl 32px. Inside buttons no wrapper is needed; the button scales its own SVG.

<span class="b-icon b-icon--sm">  <!-- 16px; default 20, --lg 24, --xl 32 -->
  <svg viewBox="0 0 20 20" fill="none" aria-hidden="true">
    <path d="m4 10.5 4 4 8-9" stroke="currentColor"
          stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
  </svg>
</span>

Theme System

Every color token is declared once with light-dark() and :root sets color-scheme: light dark, so with no attribute at all the UI follows the system appearance. Setting data-theme="light" or data-theme="dark" on <html> forces a scheme by flipping color-scheme — no second stylesheet, no class swap. Each docs page restores the saved choice before first paint:

<script>
  try {
    const t = localStorage.getItem("barua-theme");
    if (t) document.documentElement.dataset.theme = t;
  } catch (e) {}
</script>

Accent re-tinting

data-accent="indigo|purple|pink|teal|green" remaps --b-color-accent and its hover/soft/text companions. Because components only ever consume the semantic accent tokens, one attribute re-tints everything below it — set it on <html> for the whole app, or on any subtree:

JS API

barua.js exposes Barua.theme and the data-b-theme-toggle click hook (the moon/sun button in the topbar uses it). Preference persists in localStorage under barua-theme.

Responsive System

Mobile-first: base styles target small screens and min-width queries layer on refinements at the breakpoint values below (a documented convention in tokens.css — media queries cannot read custom properties, so the values are used literally).

Two visibility utilities pivot at 768px: .b-hide-mobile hides below it, .b-hide-desktop hides at or above it — resize to watch these swap:

Container strategy. Content widths are capped by .b-container (64rem via --b-container-lg) with --sm 40rem, --md 48rem, --xl 80rem and --fluid variants — pick the narrowest container that fits the content instead of writing page-level media queries. Shell metrics (--b-sidebar-w, --b-rail-w, --b-topbar-h) are tokens, so app chrome and content agree on the same numbers.

Accessibility System

Accessibility is infrastructure, not a per-component afterthought. The baseline contract every component inherits:

Motion System

Five durations, five curves — all tokens, so timing stays consistent across components. Small feedback is near-instant; the bigger the surface, the longer and springier the move.

Rule. Motion communicates hierarchy — it tells the eye what changed and how big the change was, never decorates. And because the reduced-motion override is global, every token-driven animation already respects prefers-reduced-motion.

Interaction States

The full interaction-state language — hover, pressed (:active / .is-pressed), drag (.is-dragging, [draggable] cursors), selection rectangles, drop indicators and focus choreography — is a pattern page of its own. This page defines the naming; see Interaction for live demos of each state applied across components.

Composition Patterns

Big surfaces are assembled, not invented. An auth screen is .b-card + .b-field + .b-btn (packaged as .b-auth-card on Authentication); a dashboard is .b-grid + .b-card + .b-stat + .b-chart (see Productivity and Data Visualization). The same three primitives compose a working sign-in card with zero new CSS:

Rule. Build pages from patterns, patterns from components, components from tokens. If a layer skips a level — a page styling raw hex, a pattern inventing a one-off control — consistency leaks out exactly there.

Content Guidelines

Voice is part of the system. Buttons are verb-first and specific — they say what happens, not what the dialog is about. Sentence case everywhere: buttons, labels, headings, menu items. Errors say what went wrong and what to do next, in words a person would use; error codes belong in logs, not in .b-error text.

Usage & Contribution Guidelines

Compose first. If a design can be assembled from existing components plus layout utilities, compose it in markup — do not add CSS. Add a new component only when a pattern recurs across several screens or needs its own state contract. New components get a block name, live in css/components/ inside @layer components, and are imported from barua.css. Before shipping one:

• Tokens only

  No raw hex, px shadows or magic z-indexes — every value traces to a semantic token.
• All states

  Hover, pressed, focus-visible, disabled — plus loading and selected where they apply, via the is-*/aria-* contract.
• Dark mode & accents

  Verified in light and dark via light-dark(), and under all five data-accent tints.
• Accessibility notes

  Semantic element, aria contract, 44px touch reach, contrast targets — and what the consumer must still provide.
• Docs section

  A live demo with variants, sizes and states on the relevant page — undocumented components don't exist.

Documentation Conventions

These docs are themselves built from Barua — docs.css styles only the chrome (shell, hero, demo frames), so every demo you see is the real system rendering itself. Each section follows one anatomy: .docs-section with an h2[id], short prose, a live .docs-demo, and a .docs-a11y note where the component has sharp edges. docs.js generates the collapsible HTML block under every demo from its actual markup — the code you copy is the code that rendered, and can never drift. Demos marked data-no-code skip the block when the markup would be noise. The same script builds the right-rail table of contents from the section headings and feeds the ⌘K palette from the sidebar, so navigation stays in sync with the pages for free.