@ringer-tel/ui

React component library for the Ringer unified aesthetic — shadcn-style primitives plus the Sidebar/Topbar/SummaryTile/Logo recipes specific to Ringer's portal and marketing surfaces. Consumes @ringer-tel/tokens and @ringer-tel/tailwind-preset.

The whole bundle is marked 'use client'. Every component is either interactive or composes one that is. Server-component consumers (Next.js App Router, etc.) treat the package as an auto-managed client boundary.

Install

pnpm add @ringer-tel/ui @ringer-tel/tailwind-preset @ringer-tel/tokens react react-dom tailwindcss

Wire the preset into tailwind.config.ts and import the tokens CSS at app entry — see @ringer-tel/tailwind-preset for setup.

What's exported

Core primitives

| Component | Spec § | |---|---| | <Logo variant="auto" \| "color" \| "white" lockup="primary" \| "logomark" format="svg" \| "png" /> — auto-resolves to the brand-correct mark for the ambient data-theme. | §6.1 | | <Button variant="primary" \| "secondary" \| "accent" \| "ghost" \| "destructive" \| "link" size="sm" \| "md" \| "lg" \| "xl" /> | §6.2 | | <Badge variant="success" \| "pending" \| "live" \| "conflict" \| "neutral" /> — pill-shape status indicator. | §6.3 | | <Card> / <CardHeader> / <CardContent> / <CardFooter> | §6.4 | | <Input> | §6.6 | | <EventIcon kind={…} /> — 10 mapped event types (Lucide-backed). | §6.7 | | <Sparkline points={[…]} tone="inherit" \| "aqua" \| "tangerine" \| "destructive" /> — real-data only, ≥ 7 points. | §6.8 | | <SummaryTile tier="hero" accent="action" \| "clear" \| "destructive" /> / <SummaryTile tier="supporting" /> — TS discriminated union; accent required on hero. | §5.7 | | <Table> / <THead> / <TBody virtual?> / <TR> / <TH sticky? resizable? colId? defaultWidth?> / <TD sticky?> — sticky columns, resizable headers, virtualization-friendly. | §6.5 | | useHorizontalScrollState(ref) — companion hook for the data-scrolled-x shadow on sticky-column tables. | §6.5 |

Composite shells

| Component | Spec § | |---|---| | <SidebarProvider> + <Sidebar header? footer? /> + <SidebarSection> + <SidebarLink> + <SidebarTrigger> + useSidebar() — shadcn-aligned. Renders desktop fixed + mobile overlay siblings; CSS-gated by viewport. header slot (v0.3.0) replaces the default brand band; header={null} elides it. | §5.2, §6.9 | | <Topbar onSearchClick? searchHint? onMenuClick? /> — auto-wires mobile menu to the sidebar provider when one is present. | §5.3, §6.9 | | <MarketingHeader> + <MarketingFooter> | §5.4 |

ag-grid adapter

For consumers using ag-grid-community instead of the in-house <Table> primitives, also import the theme adapter:

import '@ringer-tel/ui/ag-grid.css';

Elevated card recipe

For auth/login cards and marketing CTA cards, add shadow-popover (a Tailwind utility from @ringer-tel/tailwind-preset):

<Card className="w-full border-border shadow-popover">
  {/* auth content */}
</Card>

The shadow-popover value is warm-black-tinted to feel Ringer-native. Don't reach for stock Tailwind shadow-lg on Ringer surfaces — it's pure-black and reads "stock SaaS template." See @ringer-tel/tailwind-preset and spec §5.6 for the full surface-tier table.

Versioning

Versioned in lockstep with @ringer-tel/tokens and @ringer-tel/tailwind-preset. Consumers should pin all three at the same major.minor.

Source + spec

• Source: Ringer/aesthetic-rewrite
• Design spec (canonical): docs/superpowers/specs/2026-05-12-ringer-unified-aesthetic-design.md
• Release notes: v0.2.x releases