@bundu/ui 0.1.0

package/src/SocialIcon.astro

@@ -0,0 +1,166 @@
+---
+/**
+ * SocialIcon — platform-aware social link.
+ *
+ * Detects the platform from the URL hostname and renders the right
+ * SVG glyph + accessible label. Falls back to a generic globe icon
+ * when the hostname doesn't match any known platform — the link
+ * still works; only the icon defaults.
+ *
+ * Used on /team across bundu, nyuchi, mukoko (one record per
+ * author in Sanity → many platform links per author). The Sanity
+ * field is `sameAs: string[]` on the author doc, so editors don't
+ * have to pick a platform from a dropdown — they just paste the
+ * URL and the render picks the right icon.
+ *
+ * Supported platforms: LinkedIn, X (Twitter), Instagram, GitHub,
+ * YouTube, Threads, Bluesky, Mastodon, Facebook, TikTok, ORCID,
+ * plus a generic fallback. Add a host → key mapping below to
+ * extend.
+ */
+
+interface Props {
+  /** Full URL to the social profile. The protocol must be present
+   * (https://...); we pass it through to the anchor href. */
+  url: string;
+  /** Icon size in px. Default 18, which sits well in a 36px round
+   * button (margin handled by the wrapping `.w-9 h-9`). */
+  size?: number;
+  /** Override the auto-detected label (otherwise the platform name
+   * or hostname is used for aria-label + title). */
+  label?: string;
+}
+
+const { url, size = 18, label } = Astro.props;
+
+function getPlatform(rawUrl: string): { name: string; key: string } | null {
+  let host: string;
+  try {
+    host = new URL(rawUrl).hostname.toLowerCase().replace(/^www\./, '');
+  } catch {
+    return null;
+  }
+  const exactMap: Record<string, { name: string; key: string }> = {
+    'linkedin.com': { name: 'LinkedIn', key: 'linkedin' },
+    'lnkd.in': { name: 'LinkedIn', key: 'linkedin' },
+    'x.com': { name: 'X', key: 'x' },
+    'twitter.com': { name: 'X', key: 'x' },
+    't.co': { name: 'X', key: 'x' },
+    'instagram.com': { name: 'Instagram', key: 'instagram' },
+    'github.com': { name: 'GitHub', key: 'github' },
+    'youtube.com': { name: 'YouTube', key: 'youtube' },
+    'youtu.be': { name: 'YouTube', key: 'youtube' },
+    'threads.net': { name: 'Threads', key: 'threads' },
+    'bsky.app': { name: 'Bluesky', key: 'bluesky' },
+    'facebook.com': { name: 'Facebook', key: 'facebook' },
+    'fb.me': { name: 'Facebook', key: 'facebook' },
+    'tiktok.com': { name: 'TikTok', key: 'tiktok' },
+    'orcid.org': { name: 'ORCID', key: 'orcid' },
+  };
+  if (exactMap[host]) return exactMap[host];
+  // Mastodon federation: every server has its own hostname. Match
+  // common patterns (mastodon.*, *.social) rather than enumerating.
+  if (/(^|\.)mastodon\./.test(host) || host.endsWith('.social')) {
+    return { name: 'Mastodon', key: 'mastodon' };
+  }
+  return null;
+}
+
+let hostname = '';
+try {
+  hostname = new URL(url).hostname.replace(/^www\./, '');
+} catch {
+  // leave hostname empty; the link still renders, just falls back
+  // to the generic icon below
+}
+
+const platform = getPlatform(url);
+const displayLabel = label ?? platform?.name ?? hostname ?? 'External link';
+const key = platform?.key ?? 'generic';
+---
+
+<a
+  href={url}
+  target="_blank"
+  rel="me noopener noreferrer"
+  aria-label={displayLabel}
+  title={displayLabel}
+  class="inline-flex items-center justify-center w-9 h-9 rounded-full text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
+  data-social-platform={key}
+>
+  {key === 'linkedin' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433a2.062 2.062 0 01-2.063-2.065 2.062 2.062 0 112.063 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z"/>
+    </svg>
+  )}
+
+  {key === 'x' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z"/>
+    </svg>
+  )}
+
+  {key === 'instagram' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <rect x="2" y="2" width="20" height="20" rx="5" ry="5"/>
+      <path d="M16 11.37A4 4 0 1 1 12.63 8 4 4 0 0 1 16 11.37z"/>
+      <line x1="17.5" y1="6.5" x2="17.51" y2="6.5"/>
+    </svg>
+  )}
+
+  {key === 'github' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
+    </svg>
+  )}
+
+  {key === 'youtube' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 0 0 2.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 0 0 2.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z"/>
+    </svg>
+  )}
+
+  {key === 'threads' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M12.186 24h-.007c-3.581-.024-6.334-1.205-8.184-3.509C2.35 18.44 1.5 15.586 1.472 12.01v-.017c.03-3.579.879-6.43 2.525-8.482C5.845 1.205 8.6.024 12.18 0h.014c2.746.02 5.043.725 6.826 2.098 1.677 1.29 2.858 3.13 3.509 5.467l-2.04.569c-1.104-3.96-3.898-5.984-8.304-6.015-2.91.022-5.11.936-6.54 2.717C4.307 6.504 3.616 8.914 3.589 12c.027 3.086.718 5.496 2.057 7.164 1.43 1.781 3.631 2.695 6.54 2.717 2.623-.02 4.358-.631 5.8-2.045 1.647-1.613 1.618-3.593 1.09-4.798-.31-.71-.873-1.3-1.634-1.75-.192 1.352-.622 2.446-1.284 3.272-.886 1.102-2.14 1.704-3.73 1.79-1.202.065-2.361-.218-3.259-.801-1.063-.689-1.685-1.74-1.752-2.964-.065-1.19.408-2.285 1.33-3.082.88-.76 2.119-1.207 3.583-1.291a13.853 13.853 0 0 1 3.02.142c-.126-.742-.375-1.332-.75-1.757-.513-.586-1.308-.883-2.359-.89h-.029c-.844 0-1.992.232-2.721 1.32L7.734 7.847c.98-1.454 2.568-2.256 4.478-2.256h.044c3.194.02 5.097 1.975 5.287 5.388.108.046.216.094.32.143 1.49.7 2.58 1.761 3.154 3.07.797 1.82.871 4.79-1.548 7.158-1.85 1.81-4.094 2.628-7.277 2.65zm1.003-11.69c-.242 0-.487.007-.739.021-1.836.103-2.98.945-2.916 2.143.067 1.256 1.452 1.84 2.784 1.767 1.224-.065 2.818-.543 3.086-3.71a10.5 10.5 0 0 0-2.215-.221z"/>
+    </svg>
+  )}
+
+  {key === 'bluesky' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M12 10.8c-1.087-2.114-4.046-6.053-6.798-7.995C2.566.944 1.561 1.266.902 1.565.139 1.908 0 3.08 0 3.768c0 .69.378 5.65.624 6.479.815 2.736 3.713 3.66 6.383 3.364.136-.02.275-.039.415-.056-.138.022-.276.04-.415.056-3.912.58-7.387 2.005-2.83 7.078 5.013 5.19 6.87-1.113 7.823-4.308.953 3.195 2.05 9.271 7.733 4.308 4.267-4.308 1.172-6.498-2.74-7.078a8.741 8.741 0 0 1-.415-.056c.14.017.279.036.415.056 2.67.297 5.568-.628 6.383-3.364.246-.828.624-5.79.624-6.478 0-.69-.139-1.861-.902-2.206-.659-.298-1.664-.62-4.3 1.24C16.046 4.748 13.087 8.687 12 10.8Z"/>
+    </svg>
+  )}
+
+  {key === 'mastodon' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M23.193 7.88c0-5.207-3.412-6.733-3.412-6.733C18.062.357 15.108.027 12.041 0h-.076c-3.069.027-6.02.357-7.74 1.147 0 0-3.412 1.526-3.412 6.732 0 1.193-.023 2.619.015 4.13.124 5.092.934 10.11 5.641 11.355 2.17.574 4.034.695 5.535.612 2.722-.15 4.25-.972 4.25-.972l-.09-1.975s-1.945.613-4.13.539c-2.165-.074-4.449-.234-4.799-2.892a5.45 5.45 0 0 1-.048-.745s2.125.52 4.82.643c1.647.076 3.193-.097 4.762-.283 3.007-.36 5.626-2.216 5.956-3.913.52-2.673.477-6.521.477-6.521zm-4.024 6.704h-2.497V8.469c0-1.29-.541-1.944-1.628-1.944-1.2 0-1.802.776-1.802 2.312v3.349h-2.484v-3.35c0-1.535-.602-2.31-1.802-2.31-1.087 0-1.628.653-1.628 1.943v6.115H4.831V8.285c0-1.29.328-2.314.987-3.07.68-.757 1.57-1.146 2.674-1.146 1.278 0 2.246.491 2.886 1.474L12 6.585l.622-1.042c.64-.983 1.608-1.474 2.886-1.474 1.104 0 1.994.389 2.674 1.146.658.756.987 1.78.987 3.07z"/>
+    </svg>
+  )}
+
+  {key === 'facebook' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z"/>
+    </svg>
+  )}
+
+  {key === 'tiktok' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M19.59 6.69a4.83 4.83 0 0 1-3.77-4.25V2h-3.45v13.67a2.89 2.89 0 0 1-5.2 1.74 2.89 2.89 0 0 1 2.31-4.64 2.93 2.93 0 0 1 .88.13V9.4a6.84 6.84 0 0 0-1-.05A6.33 6.33 0 0 0 5.8 20.1a6.34 6.34 0 0 0 10.86-4.43v-7a8.16 8.16 0 0 0 4.77 1.52v-3.4a4.85 4.85 0 0 1-1.84-.1z"/>
+    </svg>
+  )}
+
+  {key === 'orcid' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M12 0C5.372 0 0 5.372 0 12s5.372 12 12 12 12-5.372 12-12S18.628 0 12 0zM7.369 4.378c.525 0 .947.431.947.947 0 .525-.422.947-.947.947-.525 0-.946-.422-.946-.947 0-.516.421-.947.946-.947zm-.722 3.038h1.444v10.041H6.647V7.416zm3.562 0h3.9c3.712 0 5.344 2.653 5.344 5.025 0 2.578-2.016 5.025-5.325 5.025h-3.919V7.416zm1.444 1.303v7.444h2.297c3.272 0 4.022-2.484 4.022-3.722 0-2.016-1.284-3.722-4.097-3.722h-2.222z"/>
+    </svg>
+  )}
+
+  {key === 'generic' && (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="10"/>
+      <line x1="2" y1="12" x2="22" y2="12"/>
+      <path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/>
+    </svg>
+  )}
+</a>

package/src/breadcrumbs.ts

@@ -0,0 +1,83 @@
+/**
+ * Breadcrumb helpers. The Astro `Breadcrumb` component consumes
+ * `BreadcrumbItem[]`; this module derives that array from a URL
+ * pathname plus a per-app label map.
+ *
+ * Labels: each app declares a `Record<string, string>` mapping URL
+ * segments (or full paths) to display names. The deriver walks the
+ * path one segment at a time, prefers a full-path hit over a
+ * segment hit, and falls back to a title-cased rendering of the
+ * segment itself. Segments without a humane label can be marked
+ * `null` to skip the segment entirely (useful when a routing
+ * segment is structural rather than user-facing, e.g. `/blog/tag/`
+ * where `tag` is a routing token).
+ */
+
+export interface BreadcrumbItem {
+  /** Display label. */
+  name: string;
+  /** Absolute URL or site-relative path. Omit on the current page
+   * and the component renders it as `aria-current="page"`. */
+  url?: string;
+}
+
+export type BreadcrumbLabelMap = Record<string, string | null>;
+
+/** Title-case fallback: "k12-digital-campus" → "K12 Digital Campus".
+ * Used when a segment isn't in the label map. */
+function humanize(segment: string): string {
+  return segment
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Build a breadcrumb trail from a URL pathname.
+ *
+ * @param pathname e.g. `Astro.url.pathname` — `/education/k12-digital-campus`
+ * @param labels   per-app label map. Keys can be full paths
+ *                 (`/education/k12-digital-campus`) or single
+ *                 segments (`education`). Full-path keys win.
+ * @param homeName the label for the root crumb. Pass the app's
+ *                 short name (e.g. "Nyuchi", "Bundu", "Mukoko").
+ * @param currentName optional label override for the final crumb
+ *                 (e.g. an article title that isn't representable
+ *                 in a static label map).
+ */
+export function deriveBreadcrumbs(
+  pathname: string,
+  labels: BreadcrumbLabelMap,
+  homeName: string,
+  currentName?: string,
+): BreadcrumbItem[] {
+  const segments = pathname.split("/").filter(Boolean);
+  if (segments.length === 0) return [];
+
+  const items: BreadcrumbItem[] = [{ name: homeName, url: "/" }];
+  let cumulative = "";
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    cumulative += `/${segment}`;
+    const isLast = i === segments.length - 1;
+
+    // Full-path label wins over single-segment.
+    const explicit = Object.prototype.hasOwnProperty.call(labels, cumulative)
+      ? labels[cumulative]
+      : Object.prototype.hasOwnProperty.call(labels, segment)
+        ? labels[segment]
+        : undefined;
+
+    // `null` in the label map means "skip this segment entirely"
+    // (used for routing tokens like `/blog/tag/` where `tag` adds
+    // no breadcrumb value).
+    if (explicit === null) continue;
+
+    const name =
+      isLast && currentName ? currentName : (explicit ?? humanize(segment));
+
+    items.push(isLast ? { name } : { name, url: cumulative });
+  }
+
+  return items;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {
+  deriveBreadcrumbs,
+  type BreadcrumbItem,
+  type BreadcrumbLabelMap,
+} from "./breadcrumbs";

package/src/lib/utils.ts

@@ -0,0 +1,44 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * Tailwind-merge configured for the Nyuchi Design System's custom type
+ * scale. Without this, merge treats the named font sizes (`text-body`,
+ * `text-h2`, …) as *colours* and drops a legitimately co-existing
+ * `text-primary-foreground`. Declaring them in the `font-size` group
+ * keeps colour + size independent, the way raw Tailwind generates them.
+ */
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [
+        {
+          text: [
+            "display",
+            "display-sm",
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "h5",
+            "h6",
+            "body-lg",
+            "body",
+            "body-sm",
+            "caption",
+          ],
+        },
+      ],
+    },
+  },
+});
+
+/**
+ * `cn` — the shadcn class-merge helper the Nyuchi Design System is built
+ * on. Merges conditional class lists (clsx) and resolves Tailwind
+ * conflicts last-wins (tailwind-merge). Every UI component composes its
+ * variant classes through this.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/ui/alert.tsx

@@ -0,0 +1,99 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../lib/utils";
+
+/**
+ * Alert — shadcn CVA pattern mapped onto the Five-African-Minerals
+ * container tokens. Variants name the semantic role, not the colour.
+ * `role="alert"` announces the message to assistive tech.
+ */
+export const alertVariants = cva(
+  "relative w-full rounded-lg border px-4 py-3 text-body-sm",
+  {
+    variants: {
+      variant: {
+        default: "bg-card text-card-foreground border-border",
+        info: "bg-cobalt-container text-cobalt-on-container border-transparent",
+        success:
+          "bg-malachite-container text-malachite-on-container border-transparent",
+        warning:
+          "bg-gold-container text-gold-on-container border-transparent",
+        destructive: "bg-card text-destructive border-destructive/40",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+export interface AlertProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof alertVariants> {
+  class?: string;
+  className?: string;
+}
+
+export function Alert({
+  variant,
+  class: astroClass,
+  className,
+  children,
+  ...props
+}: AlertProps) {
+  return (
+    <div
+      role="alert"
+      data-slot="alert"
+      className={cn(alertVariants({ variant }), astroClass, className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface AlertTitleProps
+  extends React.HTMLAttributes<HTMLParagraphElement> {
+  class?: string;
+  className?: string;
+}
+
+export function AlertTitle({
+  class: astroClass,
+  className,
+  children,
+  ...props
+}: AlertTitleProps) {
+  return (
+    <p
+      data-slot="alert-title"
+      className={cn("mb-1 font-medium leading-none", astroClass, className)}
+      {...props}
+    >
+      {children}
+    </p>
+  );
+}
+
+export function AlertDescription({
+  class: astroClass,
+  className,
+  children,
+  ...props
+}: AlertTitleProps) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        "text-body-sm [&_p]:leading-relaxed opacity-90",
+        astroClass,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}

package/src/ui/avatar.tsx

@@ -0,0 +1,69 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../lib/utils";
+
+/**
+ * Avatar — dependency-light image avatar with an initials fallback.
+ *
+ * NOT Radix: kept minimal and SSR-friendly. Renders the image when
+ * `src` is set (falling back to initials on load error via a tiny
+ * inline handler), otherwise renders the `fallback` initials. Colours
+ * come from the semantic `muted` surface token — no hex.
+ */
+export const avatarVariants = cva(
+  "relative inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full bg-muted text-muted-foreground font-medium select-none",
+  {
+    variants: {
+      size: {
+        sm: "h-8 w-8 text-caption",
+        md: "h-10 w-10 text-body-sm",
+        lg: "h-14 w-14 text-body",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);
+
+export interface AvatarProps extends VariantProps<typeof avatarVariants> {
+  /** Image URL. When omitted, the initials fallback renders. */
+  src?: string;
+  /** Alt text for the image / accessible label. */
+  alt?: string;
+  /** Initials (or short text) shown when there's no image. */
+  fallback?: string;
+  class?: string;
+  className?: string;
+}
+
+export function Avatar({
+  size,
+  src,
+  alt,
+  fallback,
+  class: astroClass,
+  className,
+}: AvatarProps) {
+  return (
+    <span
+      data-slot="avatar"
+      role="img"
+      aria-label={alt ?? fallback}
+      className={cn(avatarVariants({ size }), astroClass, className)}
+    >
+      {src ? (
+        <img
+          src={src}
+          alt={alt ?? ""}
+          className="h-full w-full object-cover"
+          loading="lazy"
+          data-slot="avatar-image"
+        />
+      ) : (
+        <span data-slot="avatar-fallback">{fallback}</span>
+      )}
+    </span>
+  );
+}

package/src/ui/badge.tsx

@@ -0,0 +1,58 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../lib/utils";
+
+/**
+ * Badge — shadcn CVA pattern mapped onto the Five-African-Minerals
+ * container tokens. Variants name the semantic role, not the colour, so
+ * a brand re-skin lands everywhere at once.
+ */
+export const badgeVariants = cva(
+  "inline-flex items-center rounded-full font-medium",
+  {
+    variants: {
+      variant: {
+        default: "bg-muted text-muted-foreground",
+        primary: "bg-cobalt-container text-cobalt-on-container",
+        success: "bg-malachite-container text-malachite-on-container",
+        warning: "bg-gold-container text-gold-on-container",
+        info: "bg-cobalt-container text-cobalt-on-container",
+        accent: "bg-terracotta-container text-terracotta-on-container",
+        premium: "bg-tanzanite-container text-tanzanite-on-container",
+        outline: "border border-border text-foreground",
+      },
+      size: {
+        sm: "px-2 py-0.5 text-caption",
+        md: "px-3 py-1 text-body-sm",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "md",
+    },
+  },
+);
+
+export interface BadgeProps extends VariantProps<typeof badgeVariants> {
+  class?: string;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export function Badge({
+  variant,
+  size,
+  class: astroClass,
+  className,
+  children,
+}: BadgeProps) {
+  return (
+    <span
+      className={cn(badgeVariants({ variant, size }), astroClass, className)}
+      data-slot="badge"
+    >
+      {children}
+    </span>
+  );
+}

package/src/ui/button.tsx

@@ -0,0 +1,114 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../lib/utils";
+
+/**
+ * Button — shadcn CVA pattern (the source the Nyuchi Design System is
+ * built on), mapped onto the Five-African-Minerals semantic tokens.
+ *
+ * Astro adaptation: renders an <a> when `href` is set, otherwise a
+ * <button>. Touch targets follow the Ubuntu checklist — 56px (h-14)
+ * for the large size, 48px (h-12) minimum — for outdoor, all-ages use.
+ */
+export const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 font-medium rounded-full transition-all duration-200 ease-soft outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:opacity-50 disabled:cursor-not-allowed",
+  {
+    variants: {
+      variant: {
+        primary: "bg-primary text-primary-foreground hover:opacity-90",
+        secondary: "bg-foreground text-background hover:opacity-90",
+        outline:
+          "border border-foreground text-foreground hover:bg-foreground hover:text-background",
+        ghost: "text-foreground hover:bg-muted",
+      },
+      size: {
+        sm: "h-12 px-4 text-body-sm",
+        md: "h-12 px-6 text-body",
+        lg: "h-14 px-8 text-body-lg",
+      },
+      fullWidth: {
+        true: "w-full",
+      },
+    },
+    defaultVariants: {
+      variant: "primary",
+      size: "md",
+    },
+  },
+);
+
+const ArrowRight = () => (
+  <svg
+    className="h-4 w-4"
+    fill="none"
+    stroke="currentColor"
+    viewBox="0 0 24 24"
+    aria-hidden="true"
+  >
+    <path
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth={1.75}
+      d="M17 8l4 4m0 0l-4 4m4-4H3"
+    />
+  </svg>
+);
+
+export interface ButtonProps extends VariantProps<typeof buttonVariants> {
+  /** Render as a link when set. */
+  href?: string;
+  /** Opens in a new tab with safe rel. */
+  external?: boolean;
+  /** Append a trailing arrow glyph (keeps the SVG out of pages). */
+  arrow?: boolean;
+  type?: "button" | "submit" | "reset";
+  disabled?: boolean;
+  class?: string;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export function Button({
+  variant,
+  size,
+  fullWidth,
+  href,
+  external,
+  arrow,
+  type = "button",
+  disabled,
+  class: astroClass,
+  className,
+  children,
+}: ButtonProps) {
+  const classes = cn(
+    buttonVariants({ variant, size, fullWidth }),
+    astroClass,
+    className,
+  );
+
+  if (href) {
+    const ext = external
+      ? { target: "_blank", rel: "noopener noreferrer" }
+      : {};
+    return (
+      <a href={href} className={classes} data-slot="button" {...ext}>
+        {children}
+        {arrow && <ArrowRight />}
+      </a>
+    );
+  }
+
+  return (
+    <button
+      type={type}
+      disabled={disabled}
+      className={classes}
+      data-slot="button"
+    >
+      {children}
+      {arrow && <ArrowRight />}
+    </button>
+  );
+}