@bundu/ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nyuchi Africa (Pvt) Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @bundu/ui
+
+The **marketing UI kit** for the Bundu Ecosystem — Nyuchi's implementation of the
+[Mzizi](https://mzizi.dev) design system. It's the shared component layer behind the
+marketing sites (bundu, nyuchi, mukoko): editorial Astro building blocks plus a set of
+shadcn-style React primitives, all mapped onto the **seven African minerals** and the
+semantic token system.
+
+- **Astro marketing components** — `Hero`, `Section`, `SectionHeader`, `Container`,
+  `MineralStrip`, `Icon`, `SocialIcon`, and `Breadcrumb` (emits valid schema.org
+  `BreadcrumbList` JSON-LD for Google rich results).
+- **shadcn CVA + `cn()` React primitives** — `Button`, `Card`, `Badge`, `Input`,
+  `Textarea`, `Select`, `Label`, `Alert`, `Avatar`, `Separator`, `Skeleton`, `Switch`,
+  `Checkbox`, `Tabs`, `Tooltip`.
+- **Option-A styling** — one canonical `styles/globals.css` (all seven minerals, light +
+  dark, semantic tokens, component/utility classes) plus tiny `brand-*.css` overlays that
+  swap the brand primary, and a `tailwind-preset.mjs` that exposes the utility classes.
+
+Every value flows through CSS custom properties / Tailwind tokens — **never a raw hex in
+source**. All seven minerals are valid tokens: `cobalt`, `tanzanite`, `malachite`, `gold`,
+`terracotta`, `sodalite`, `copper`.
+
+## Install
+
+```sh
+pnpm add @bundu/ui
+# peer deps (for the React primitives)
+pnpm add react react-dom
+```
+
+## Quick usage
+
+**1. Styles** — import the canonical tokens, then the brand overlay for your site, into
+your global stylesheet (after `@import "tailwindcss";`):
+
+```css
+@import "tailwindcss";
+@import "@bundu/ui/styles/globals.css";
+@import "@bundu/ui/styles/brand-nyuchi.css"; /* or brand-bundu / brand-mukoko */
+```
+
+**2. Tailwind** — add the preset so the mineral + semantic utility classes exist:
+
+```js
+// tailwind.config.mjs
+import preset from "@bundu/ui/tailwind-preset";
+
+export default {
+  presets: [preset],
+  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
+};
+```
+
+**3. Components:**
+
+```astro
+---
+import Hero from "@bundu/ui/Hero.astro";
+import Container from "@bundu/ui/Container.astro";
+import MineralStrip from "@bundu/ui/MineralStrip.astro";
+import Breadcrumb from "@bundu/ui/Breadcrumb.astro";
+import { deriveBreadcrumbs } from "@bundu/ui";
+
+const crumbs = deriveBreadcrumbs(Astro.url.pathname, { about: "About" }, "Nyuchi");
+---
+
+<MineralStrip />
+<Hero title="Build in the open" subtitle="Bundu Ecosystem" />
+<Container>
+  <Breadcrumb items={crumbs} origin={Astro.site?.toString()} />
+</Container>
+```
+
+```tsx
+import { Button } from "@bundu/ui/ui/button";
+import { Alert, AlertTitle } from "@bundu/ui/ui/alert";
+
+export function CTA() {
+  return (
+    <>
+      <Alert variant="success">
+        <AlertTitle>Saved</AlertTitle>
+      </Alert>
+      <Button variant="primary" href="/start" arrow>
+        Get started
+      </Button>
+    </>
+  );
+}
+```
+
+See [BUILDING.md](./BUILDING.md) for the full toolchain — the mzizi MCP, the shadcn CLI, the
+seven minerals, and the no-raw-hex rule.
+
+## License
+
+[MIT](../../LICENSE) © Nyuchi Africa (Pvt) Ltd

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@bundu/ui",
+  "version": "0.1.0",
+  "description": "The marketing UI kit for the Bundu Ecosystem — Nyuchi's implementation of the Mzizi design system. Astro marketing components (Hero, Section, MineralStrip, Container, Breadcrumb with valid BreadcrumbList JSON-LD, …) plus shadcn CVA + cn() React primitives mapped onto the seven-African-mineral tokens, a canonical globals.css, tiny brand overrides, and a Tailwind preset.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Nyuchi Africa (Pvt) Ltd",
+  "homepage": "https://github.com/nyuchi/packages-ui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nyuchi/packages-ui.git",
+    "directory": "packages/bundu-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/nyuchi/packages-ui/issues"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./ui/button": "./src/ui/button.tsx",
+    "./ui/card": "./src/ui/card.tsx",
+    "./ui/badge": "./src/ui/badge.tsx",
+    "./ui/input": "./src/ui/input.tsx",
+    "./ui/textarea": "./src/ui/textarea.tsx",
+    "./ui/select": "./src/ui/select.tsx",
+    "./ui/label": "./src/ui/label.tsx",
+    "./ui/alert": "./src/ui/alert.tsx",
+    "./ui/avatar": "./src/ui/avatar.tsx",
+    "./ui/separator": "./src/ui/separator.tsx",
+    "./ui/skeleton": "./src/ui/skeleton.tsx",
+    "./ui/switch": "./src/ui/switch.tsx",
+    "./ui/checkbox": "./src/ui/checkbox.tsx",
+    "./ui/tabs": "./src/ui/tabs.tsx",
+    "./ui/tooltip": "./src/ui/tooltip.tsx",
+    "./Hero.astro": "./src/Hero.astro",
+    "./Section.astro": "./src/Section.astro",
+    "./SectionHeader.astro": "./src/SectionHeader.astro",
+    "./MineralStrip.astro": "./src/MineralStrip.astro",
+    "./Container.astro": "./src/Container.astro",
+    "./Icon.astro": "./src/Icon.astro",
+    "./SocialIcon.astro": "./src/SocialIcon.astro",
+    "./Breadcrumb.astro": "./src/Breadcrumb.astro",
+    "./lib/utils": "./src/lib/utils.ts",
+    "./styles/globals.css": "./styles/globals.css",
+    "./styles/brand-bundu.css": "./styles/brand-bundu.css",
+    "./styles/brand-nyuchi.css": "./styles/brand-nyuchi.css",
+    "./styles/brand-mukoko.css": "./styles/brand-mukoko.css",
+    "./tailwind-preset": "./tailwind-preset.mjs"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.0.2"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "files": [
+    "src",
+    "styles",
+    "tailwind-preset.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "bundu",
+    "mzizi",
+    "design-system",
+    "marketing",
+    "astro",
+    "ui"
+  ]
+}

package/src/Breadcrumb.astro

@@ -0,0 +1,105 @@
+---
+/**
+ * Breadcrumb — visual nav + BreadcrumbList JSON-LD.
+ *
+ * Renders an `<nav aria-label="Breadcrumb">` with an ordered list
+ * of links, and emits a `BreadcrumbList` JSON-LD block so Google
+ * shows breadcrumb rich snippets in SERPs. Both halves come from
+ * the same `items` array — keeps the visible UI and the structured
+ * data in sync by construction.
+ *
+ * Convention: the final item is the current page. If its `url` is
+ * omitted (or matches the current URL), it renders as plain text
+ * with `aria-current="page"` instead of an anchor.
+ *
+ * The component renders nothing when fewer than two items are
+ * provided — a single-item trail is just "Home" with no value to
+ * the user or to Google.
+ */
+
+import type { BreadcrumbItem } from "./breadcrumbs";
+
+interface Props {
+  items: BreadcrumbItem[];
+  /** Fully-qualified origin used to expand site-relative `url`s
+   * into absolute URLs in the JSON-LD payload (Google requires
+   * absolute). Pass `Astro.site.toString()` or the app's domain
+   * constant. Falls back to the runtime origin when omitted, which
+   * works at request time but not at build time. */
+  origin?: string;
+  /** Extra classes for the wrapping <nav>. Spacing defaults assume
+   * the breadcrumb sits above the page hero or content. */
+  class?: string;
+}
+
+const { items, origin, class: extraClass } = Astro.props;
+
+const shouldRender = items.length >= 2;
+
+function toAbsolute(url: string): string {
+  if (/^https?:\/\//i.test(url)) return url;
+  const base = origin ?? Astro.site?.toString() ?? Astro.url.origin;
+  const baseTrimmed = base.replace(/\/$/, "");
+  const path = url.startsWith("/") ? url : `/${url}`;
+  return `${baseTrimmed}${path}`;
+}
+
+const jsonLd = shouldRender
+  ? {
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: items.map((item, index) => ({
+        "@type": "ListItem",
+        position: index + 1,
+        name: item.name,
+        // Schema.org requires an absolute URL on every item including
+        // the last; fall back to the current page URL when an item
+        // has no explicit href.
+        item: toAbsolute(item.url ?? Astro.url.pathname),
+      })),
+    }
+  : null;
+---
+
+{shouldRender && (
+  <>
+    <nav
+      aria-label="Breadcrumb"
+      class:list={["text-body-sm text-muted-foreground", extraClass]}
+    >
+      <ol class="flex flex-wrap items-center gap-2">
+        {items.map((item, index) => {
+          const isLast = index === items.length - 1;
+          return (
+            <>
+              <li
+                class:list={[
+                  isLast ? "text-foreground truncate" : undefined,
+                ]}
+              >
+                {isLast || !item.url ? (
+                  <span aria-current={isLast ? "page" : undefined}>
+                    {item.name}
+                  </span>
+                ) : (
+                  <a
+                    href={item.url}
+                    class="hover:text-foreground transition-colors"
+                  >
+                    {item.name}
+                  </a>
+                )}
+              </li>
+              {!isLast && <li aria-hidden="true">/</li>}
+            </>
+          );
+        })}
+      </ol>
+    </nav>
+    <script
+      type="application/ld+json"
+      is:inline
+      set:html={JSON.stringify(jsonLd)}
+    />
+  </>
+)}

package/src/Container.astro

@@ -0,0 +1,39 @@
+---
+/**
+ * Container — the max-width content wrapper used across the Bundu
+ * Ecosystem sites. Centres content and applies the standard responsive
+ * horizontal padding, so pages stop hand-rolling
+ * `<div class="max-w-7xl mx-auto px-6 sm:px-8 lg:px-10">`.
+ *
+ * Sizes map onto the design-system container utilities:
+ *   - `default` → `.container-custom` (max-w-7xl wide grid column)
+ *   - `narrow`  → `.container-narrow`  (max-w-narrow editorial column)
+ *   - `prose`   → `.container-prose`   (max-w-3xl reading measure)
+ *
+ * The utility classes live in the canonical globals.css
+ * (@layer components), so no hex or raw spacing values here.
+ */
+interface Props {
+  /** Content width. Defaults to the wide grid column. */
+  size?: "default" | "narrow" | "prose";
+  /** Render element (defaults to a plain <div>). */
+  as?: "div" | "section" | "main" | "article";
+  id?: string;
+  class?: string;
+}
+
+const { size = "default", as = "div", id, class: className } = Astro.props;
+
+const sizeClass = {
+  default: "container-custom",
+  narrow: "container-narrow",
+  prose: "container-prose",
+}[size];
+
+const Tag = as;
+const classes = [sizeClass, className].filter(Boolean).join(" ");
+---
+
+<Tag class={classes} id={id} data-slot="container">
+  <slot />
+</Tag>

package/src/Hero.astro

@@ -0,0 +1,101 @@
+---
+/**
+ * Hero — shared across all Bundu Ecosystem apps (was copy-pasted
+ * byte-identical into nyuchi/mukoko/bundu). Anthropic-restrained
+ * editorial: generous whitespace, serif Display headline, narrow body,
+ * an eyebrow tag, and at most two pill CTAs composed from <Button>.
+ */
+import { Button } from "@bundu/ui/ui/button";
+
+interface CTA {
+  text: string;
+  href: string;
+  external?: boolean;
+}
+
+interface Props {
+  title: string;
+  subtitle?: string;
+  description?: string;
+  primaryCTA?: CTA;
+  secondaryCTA?: CTA;
+  variant?: "default" | "gradient" | "light";
+  align?: "center" | "start";
+}
+
+const {
+  title,
+  subtitle,
+  description,
+  primaryCTA,
+  secondaryCTA,
+  variant = "default",
+  align = "start",
+} = Astro.props;
+
+const sectionClasses = {
+  default: "bg-canvas",
+  light: "bg-secondary",
+  gradient: "gradient-hero",
+};
+
+const alignClasses = {
+  start: "text-left",
+  center: "text-center mx-auto",
+};
+---
+
+<section
+  class:list={["py-12 md:py-16 lg:py-20", sectionClasses[variant]]}
+  data-slot="hero"
+>
+  <div class="container-custom">
+    <div class:list={["max-w-3xl", alignClasses[align]]}>
+      {subtitle && <p class="eyebrow">{subtitle}</p>}
+
+      <h1 class="font-serif text-display text-foreground text-balance">
+        {title}
+      </h1>
+
+      {
+        description && (
+          <p
+            class:list={[
+              "mt-6 text-body-lg text-muted-foreground text-pretty max-w-2xl",
+              align === "center" && "mx-auto",
+            ]}
+          >
+            {description}
+          </p>
+        )
+      }
+
+      {
+        (primaryCTA || secondaryCTA) && (
+          <div
+            class:list={[
+              "mt-8 flex flex-wrap items-center gap-3",
+              align === "center" && "justify-center",
+            ]}
+          >
+            {primaryCTA && (
+              <Button href={primaryCTA.href} external={primaryCTA.external}>
+                {primaryCTA.text}
+              </Button>
+            )}
+            {secondaryCTA && (
+              <Button
+                href={secondaryCTA.href}
+                external={secondaryCTA.external}
+                variant="ghost"
+                arrow
+              >
+                {secondaryCTA.text}
+              </Button>
+            )}
+          </div>
+        )
+      }
+    </div>
+  </div>
+</section>

package/src/Icon.astro

@@ -0,0 +1,50 @@
+---
+/**
+ * Icon — the design system's inline-SVG set, so pages and components
+ * never hand-roll `<svg>` paths. Stroke-based, 1.75 weight, inherits
+ * `currentColor` and sizes to 1em by default (override via `class`).
+ *
+ * Add a glyph by adding one entry to PATHS — keep the set curated to
+ * what the sites actually use rather than pulling a whole icon font.
+ */
+interface Props {
+  name: keyof typeof PATHS;
+  /** Accessible label; omitted → decorative (aria-hidden). */
+  title?: string;
+  class?: string;
+}
+
+const PATHS = {
+  "arrow-right": "M17 8l4 4m0 0l-4 4m4-4H3",
+  "arrow-up-right": "M7 17L17 7M17 7H7M17 7v10",
+  check: "M5 13l4 4L19 7",
+  "chevron-down": "M19 9l-7 7-7-7",
+  "chevron-right": "M9 5l7 7-7 7",
+  external: "M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14",
+  close: "M6 18L18 6M6 6l12 12",
+  menu: "M4 6h16M4 12h16M4 18h16",
+  plus: "M12 5v14M5 12h14",
+  minus: "M5 12h14",
+} as const;
+
+const { name, title, class: className } = Astro.props;
+const decorative = !title;
+---
+
+<svg
+  class={["inline-block h-[1em] w-[1em]", className].filter(Boolean).join(" ")}
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.75"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  data-slot="icon"
+  data-icon={name}
+  role={decorative ? undefined : "img"}
+  aria-hidden={decorative ? "true" : undefined}
+  aria-label={decorative ? undefined : title}
+>
+  {title && <title>{title}</title>}
+  <path d={PATHS[name]} />
+</svg>

package/src/MineralStrip.astro

@@ -0,0 +1,51 @@
+---
+/**
+ * MineralStrip — the decorative seven-mineral accent bar.
+ *
+ * A full-height, ~6px bar fixed to the LEFT edge of every page,
+ * split into seven equal vertical segments coloured with the seven
+ * African-mineral tokens (top→bottom: cobalt, tanzanite, malachite,
+ * gold, terracotta, sodalite, copper).
+ *
+ * Purely decorative: aria-hidden and pointer-events:none, so it never
+ * intercepts clicks or reaches the accessibility tree. Colours come
+ * exclusively from the `--color-*` custom properties defined in each
+ * app's src/styles/global.css — no hex here.
+ */
+const minerals = [
+  "cobalt",
+  "tanzanite",
+  "malachite",
+  "gold",
+  "terracotta",
+  "sodalite",
+  "copper",
+] as const;
+---
+
+<div class="mineral-strip" aria-hidden="true" data-slot="mineral-strip">
+  {
+    minerals.map((mineral) => (
+      <span style={`background-color: var(--color-${mineral});`} />
+    ))
+  }
+</div>
+
+<style>
+  .mineral-strip {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 6px;
+    height: 100dvh;
+    z-index: 50;
+    display: flex;
+    flex-direction: column;
+    pointer-events: none;
+  }
+
+  .mineral-strip span {
+    flex: 1 1 0;
+    display: block;
+  }
+</style>

package/src/Section.astro

@@ -0,0 +1,59 @@
+---
+/**
+ * Section — the standard page band. Wraps content in a vertical-rhythm
+ * section + the site container so pages stop hand-rolling
+ * `<section class="section ..."><div class="container-custom">`.
+ *
+ * Part of the components-only standard (docs/design-system.md): pages
+ * compose Section/SectionHeader, they don't repeat the layout shell.
+ */
+interface Props {
+  /** Background surface token. */
+  bg?: "canvas" | "secondary" | "transparent";
+  /** Vertical rhythm — maps to the .section* utilities. */
+  space?: "default" | "tight" | "loose";
+  /** Hairline bottom border (the quiet section divider). */
+  border?: boolean;
+  /** Wrap children in `.container-custom` (default) or render full-bleed. */
+  container?: boolean;
+  id?: string;
+  class?: string;
+}
+
+const {
+  bg = "canvas",
+  space = "default",
+  border = false,
+  container = true,
+  id,
+  class: className,
+} = Astro.props;
+
+const spaceClass = {
+  default: "section",
+  tight: "section-tight",
+  loose: "section-loose",
+}[space];
+
+const bgClass = {
+  canvas: "bg-canvas",
+  secondary: "bg-secondary",
+  transparent: "",
+}[bg];
+
+const classes = [spaceClass, bgClass, border && "border-b border-border", className]
+  .filter(Boolean)
+  .join(" ");
+---
+
+<section class={classes} id={id} data-slot="section">
+  {
+    container ? (
+      <div class="container-custom">
+        <slot />
+      </div>
+    ) : (
+      <slot />
+    )
+  }
+</section>

package/src/SectionHeader.astro

@@ -0,0 +1,73 @@
+---
+/**
+ * SectionHeader — the eyebrow + serif heading + lead paragraph cluster
+ * that recurs at the top of ~every section (23 sections, 71 eyebrows in
+ * nyuchi alone). Composes it once instead of hand-rolling the markup.
+ *
+ * - `as` sets the heading level for a sane document outline; `size`
+ *   decouples the *visual* size (so an h2-level heading can render at
+ *   text-h1 to match an existing page).
+ * - `title`/`description` accept plain strings; for rich headings or
+ *   leads (a coloured `<span>`, interpolation), pass markup via the
+ *   `title` / `description` named slots instead.
+ */
+interface Props {
+  eyebrow?: string;
+  title?: string;
+  description?: string;
+  align?: "start" | "center";
+  /** Heading level for correct document outline. */
+  as?: "h1" | "h2" | "h3";
+  /** Visual size override; defaults to match `as`. */
+  size?: "display" | "h1" | "h2" | "h3";
+  /** Tailwind max-width for the block (default constrains the lead text). */
+  max?: string;
+  /** Tint the eyebrow (e.g. text-gold / text-terracotta). */
+  eyebrowClass?: string;
+  class?: string;
+}
+
+const {
+  eyebrow,
+  title,
+  description,
+  align = "start",
+  as = "h2",
+  size,
+  max = "max-w-2xl",
+  eyebrowClass,
+  class: className,
+} = Astro.props;
+
+const Heading = as;
+const sizeClass = {
+  display: "text-display",
+  h1: "text-h1",
+  h2: "text-h2",
+  h3: "text-h3",
+}[size ?? as];
+
+const wrapper = [max, align === "center" && "mx-auto text-center", className]
+  .filter(Boolean)
+  .join(" ");
+const eyebrowClasses = ["eyebrow", align === "center" && "justify-center", eyebrowClass]
+  .filter(Boolean)
+  .join(" ");
+
+const hasDescription = description != null || Astro.slots.has("description");
+---
+
+<div class={wrapper} data-slot="section-header">
+  {eyebrow && <p class={eyebrowClasses}>{eyebrow}</p>}
+  <Heading class={`font-serif ${sizeClass} text-foreground text-balance`}>
+    {title}<slot name="title" />
+  </Heading>
+  {
+    hasDescription && (
+      <p class="mt-4 text-body text-muted-foreground text-pretty">
+        {description}
+        <slot name="description" />
+      </p>
+    )
+  }
+</div>