@dtsports/design-system 0.2.0

package/src/components/timestamp.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * Timestamp — implements design.md §3.16 Time UX.
+ *
+ * - Future events: absolute in venue local time
+ *   ("Sat May 22, 6:00 pm"); tooltip reveals user-tz if different.
+ * - Past events within 7 days: relative ("3 min ago"); absolute beyond.
+ * - Within 24h of a future event with `relative` enabled: ticker
+ *   ("Starts in 3h 12m").
+ *
+ * Accessibility:
+ *  - Renders <time dateTime={iso}> for assistive tech.
+ *  - Tooltip via native `title` attr — readable by screen readers.
+ */
+export interface TimestampProps {
+  /** ISO-8601 date string (UTC preferred). */
+  iso: string;
+  /** Venue timezone (IANA, e.g. "America/New_York"). Falls back to user tz. */
+  venueTz?: string;
+  /** Show relative ticker when within 24h before / 7d after. */
+  relative?: boolean;
+  className?: string;
+}
+
+function formatInTz(date: Date, tz: string | undefined) {
+  return new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    weekday: "short",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+  }).format(date);
+}
+
+function diffMinutes(a: Date, b: Date) {
+  return Math.round((a.getTime() - b.getTime()) / 60_000);
+}
+
+function relativeLabel(target: Date, now: Date): string | null {
+  const minsToTarget = diffMinutes(target, now);
+  const absMins = Math.abs(minsToTarget);
+
+  // Future, within 24h
+  if (minsToTarget > 0 && minsToTarget <= 24 * 60) {
+    const h = Math.floor(minsToTarget / 60);
+    const m = minsToTarget % 60;
+    return `Starts in ${h > 0 ? `${h}h ` : ""}${m}m`;
+  }
+
+  // Past, within 7 days
+  if (minsToTarget < 0 && absMins <= 7 * 24 * 60) {
+    if (absMins < 1) return "just now";
+    if (absMins < 60) return `${absMins} min ago`;
+    const h = Math.floor(absMins / 60);
+    if (h < 24) return `${h}h ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ago`;
+  }
+  return null;
+}
+
+export function Timestamp({
+  iso,
+  venueTz,
+  relative = false,
+  className,
+}: TimestampProps) {
+  const target = React.useMemo(() => new Date(iso), [iso]);
+
+  // Tick once per minute so relative labels stay fresh
+  const [now, setNow] = React.useState(() => new Date());
+  React.useEffect(() => {
+    if (!relative) return;
+    const id = setInterval(() => setNow(new Date()), 60_000);
+    return () => clearInterval(id);
+  }, [relative]);
+
+  const userTz =
+    typeof Intl !== "undefined"
+      ? Intl.DateTimeFormat().resolvedOptions().timeZone
+      : undefined;
+  const showUserTz = !!venueTz && !!userTz && venueTz !== userTz;
+
+  const venueLabel = formatInTz(target, venueTz);
+  const rel = relative ? relativeLabel(target, now) : null;
+  const userLabel = showUserTz ? formatInTz(target, userTz) : null;
+
+  const title = userLabel
+    ? `Venue: ${venueLabel}\nYour time: ${userLabel}`
+    : venueLabel;
+
+  return (
+    <time
+      dateTime={iso}
+      title={title}
+      className={cn("tabular text-sm text-foreground", className)}
+    >
+      {rel ?? venueLabel}
+    </time>
+  );
+}

package/src/components/toaster.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import type * as React from "react";
+import { Toaster as SonnerToaster, toast } from "sonner";
+import { useTheme } from "./theme-provider";
+
+/**
+ * Toaster — the design-system-themed sonner toaster. Mount ONCE inside
+ * ThemeProvider (typically in the root layout next to your app shell):
+ *
+ *   <ThemeProvider>
+ *     <App />
+ *     <Toaster />
+ *   </ThemeProvider>
+ *
+ * Fire toasts anywhere with the re-exported `toast`:
+ *
+ *   toast.success("Game cancelled. 8 refunds issued as credit.");
+ *
+ * Per §3.10 every action outcome must be visible — toasts are the
+ * default surface for async success/failure. Per §3.7 cheap reversals
+ * get a 5s undo action:
+ *
+ *   toast("Draft deleted", {
+ *     action: { label: "Undo", onClick: restoreDraft },
+ *   });
+ */
+export type ToasterProps = React.ComponentProps<typeof SonnerToaster>;
+
+export function Toaster(props: ToasterProps) {
+  const { theme } = useTheme();
+  return (
+    <SonnerToaster
+      theme={theme}
+      duration={5000}
+      toastOptions={{
+        classNames: {
+          toast:
+            "group rounded border border-border bg-background text-foreground shadow-md text-sm",
+          description: "text-text-muted text-xs",
+          actionButton:
+            "bg-brand-forest text-brand-forest-foreground rounded-sm text-xs font-medium",
+          cancelButton: "bg-bg-muted text-text-muted rounded-sm text-xs",
+          success: "[&_[data-icon]]:text-success",
+          warning: "[&_[data-icon]]:text-warning",
+          error: "[&_[data-icon]]:text-danger",
+          info: "[&_[data-icon]]:text-info",
+        },
+      }}
+      {...props}
+    />
+  );
+}
+
+export { toast };

package/src/components/tooltip.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import * as React from "react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import { cn } from "../lib/utils";
+
+/**
+ * Tooltip — keyboard-accessible hover hints.
+ *
+ *   <Tooltip>
+ *     <TooltipTrigger asChild><Button size="icon">…</Button></TooltipTrigger>
+ *     <TooltipContent>Cancel game</TooltipContent>
+ *   </Tooltip>
+ *
+ * NOTE: A `<TooltipProvider>` must wrap the app root for tooltips to
+ * function — the design system's `<ThemeProvider>` already includes it,
+ * so consumers get this for free.
+ *
+ * Use for:
+ *  - Icon-only button labels (preferred over native `title=` which is
+ *    mouse-only and not keyboard accessible)
+ *  - "Did you know" tips beside an input label
+ *  - Truncated text expansions
+ *
+ * Don't use for critical info or anything a user needs to interact with —
+ * tooltips hide on blur and aren't reachable on touch devices.
+ */
+export const TooltipProvider = TooltipPrimitive.Provider;
+export const Tooltip = TooltipPrimitive.Root;
+export const TooltipTrigger = TooltipPrimitive.Trigger;
+
+export const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
+>(({ className, sideOffset = 4, ...props }, ref) => (
+  <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        "z-50 overflow-hidden rounded-sm bg-foreground px-2 py-1 text-xs font-medium text-background shadow-md max-w-xs",
+        "data-[state=delayed-open]:animate-fade-in",
+        className
+      )}
+      {...props}
+    />
+  </TooltipPrimitive.Portal>
+));
+TooltipContent.displayName = "TooltipContent";

package/src/components/top-bar.tsx

@@ -0,0 +1,29 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * TopBar — sticky 48px header bar. Renders the chrome (border, blur,
+ * height); content layout is the consumer's responsibility:
+ *
+ *   <TopBar>
+ *     <Breadcrumb>…</Breadcrumb>
+ *     <div className="flex-1" />
+ *     <ThemeToggle />
+ *   </TopBar>
+ */
+export const TopBar = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement>
+>(({ className, children, ...props }, ref) => (
+  <header
+    ref={ref}
+    className={cn(
+      "sticky top-0 z-20 bg-background/95 backdrop-blur border-b border-border",
+      className
+    )}
+    {...props}
+  >
+    <div className="flex h-12 items-center gap-3 px-6">{children}</div>
+  </header>
+));
+TopBar.displayName = "TopBar";

package/src/index.ts

@@ -0,0 +1,221 @@
+/**
+ * @dtsports/design-system — public API.
+ *
+ * Import paths:
+ *   import { Button, Card, Table, … } from "@dtsports/design-system";
+ *
+ * Styles:
+ *   import "@dtsports/design-system/styles/globals.css";
+ *
+ * Tailwind preset:
+ *   import preset from "@dtsports/design-system/tailwind-preset";
+ *
+ * Docs page (mountable):
+ *   export { default } from "@dtsports/design-system/showcase";
+ *
+ * Fonts:
+ *   The system expects "Exo 2" to be available. Load it via your app's
+ *   font strategy (e.g. next/font/google) in your root layout.
+ */
+
+// ── Primitives — forms ─────────────────────────────────────────────────
+export { Button, buttonVariants, type ButtonProps } from "./components/button";
+export { Input, type InputProps } from "./components/input";
+export { Label } from "./components/label";
+export { Textarea, type TextareaProps } from "./components/textarea";
+export { Checkbox } from "./components/checkbox";
+export { RadioGroup, RadioGroupItem } from "./components/radio-group";
+export { Switch } from "./components/switch";
+export {
+  Select,
+  SelectGroup,
+  SelectValue,
+  SelectTrigger,
+  SelectContent,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+  SelectScrollUpButton,
+  SelectScrollDownButton,
+} from "./components/select";
+export { NumberInput, type NumberInputProps } from "./components/number-input";
+export { FormField, type FormFieldProps } from "./components/form-field";
+export { Slider } from "./components/slider";
+export {
+  Combobox,
+  type ComboboxOption,
+  type ComboboxProps,
+} from "./components/combobox";
+export { Calendar, type CalendarProps } from "./components/calendar";
+export { DatePicker, type DatePickerProps } from "./components/date-picker";
+
+// ── Primitives — display ───────────────────────────────────────────────
+export { Badge, badgeVariants, type BadgeProps } from "./components/badge";
+export { Chip, chipVariants, type ChipProps } from "./components/chip";
+export {
+  Card,
+  type CardProps,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+} from "./components/card";
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from "./components/table";
+export { Avatar, type AvatarProps } from "./components/avatar";
+export { AvatarGroup, type AvatarGroupProps } from "./components/avatar-group";
+export { Separator } from "./components/separator";
+export {
+  Spec,
+  SpecList,
+  type SpecProps,
+  type SpecListProps,
+} from "./components/spec";
+export { Pagination, type PaginationProps } from "./components/pagination";
+
+// ── Primitives — feedback ──────────────────────────────────────────────
+export { Alert, alertVariants, type AlertProps } from "./components/alert";
+export { Toaster, toast, type ToasterProps } from "./components/toaster";
+export { Skeleton, SkeletonList, SkeletonTable } from "./components/skeleton";
+export { Spinner, type SpinnerProps } from "./components/spinner";
+export { Progress } from "./components/progress";
+
+// ── Overlays ───────────────────────────────────────────────────────────
+export {
+  Dialog,
+  DialogTrigger,
+  DialogPortal,
+  DialogClose,
+  DialogOverlay,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogBody,
+  DialogFooter,
+} from "./components/dialog";
+export {
+  Drawer,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerPortal,
+  DrawerOverlay,
+  drawerVariants,
+  DrawerContent,
+  type DrawerContentProps,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerDescription,
+  DrawerBody,
+  DrawerFooter,
+} from "./components/drawer";
+export {
+  Popover,
+  PopoverTrigger,
+  PopoverAnchor,
+  PopoverContent,
+} from "./components/popover";
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuRadioGroup,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+} from "./components/dropdown-menu";
+export {
+  TooltipProvider,
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+} from "./components/tooltip";
+
+// ── Disclosure / navigation ─────────────────────────────────────────────
+export {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "./components/accordion";
+export {
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from "./components/collapsible";
+export { Tabs, TabsList, TabsTrigger, TabsContent } from "./components/tabs";
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  type BreadcrumbLinkProps,
+} from "./components/breadcrumb";
+
+// ── Layout / shell ─────────────────────────────────────────────────────
+export { AppShell, AppMain } from "./components/app-shell";
+export {
+  Sidebar,
+  SidebarHeader,
+  SidebarBody,
+  SidebarFooter,
+  SidebarSection,
+  SidebarItem,
+  type SidebarSectionProps,
+  type SidebarItemProps,
+} from "./components/sidebar";
+export { TopBar } from "./components/top-bar";
+export { Container, type ContainerProps } from "./components/container";
+export { Stack, type StackProps } from "./components/stack";
+export { AspectRatio } from "./components/aspect-ratio";
+export { ScrollArea, ScrollBar } from "./components/scroll-area";
+
+// ── Brand-specific primitives ──────────────────────────────────────────
+export { LivePill } from "./components/live-pill";
+export { StatusPill, type GameStatus } from "./components/status-pill";
+export { MetricTile, type MetricTileProps } from "./components/metric-tile";
+export { CapacityBar, type CapacityBarProps } from "./components/capacity-bar";
+export { EmptyState, type EmptyStateProps } from "./components/empty-state";
+
+// ── UX patterns (codified principles) ──────────────────────────────────
+export { Timestamp, type TimestampProps } from "./components/timestamp";
+export {
+  MoneyBreakdown,
+  type MoneyBreakdownProps,
+  type MoneyLine,
+} from "./components/money-breakdown";
+export {
+  ThreeState,
+  type ListState,
+  type ThreeStateProps,
+} from "./components/three-state";
+export {
+  ConfirmAction,
+  type ConfirmActionProps,
+} from "./components/confirm-action";
+
+// ── Theming ────────────────────────────────────────────────────────────
+export { ThemeProvider, useTheme } from "./components/theme-provider";
+export { ThemeToggle } from "./components/theme-toggle";
+
+// ── Utilities ──────────────────────────────────────────────────────────
+export { cn } from "./lib/utils";

package/src/lib/utils.ts

@@ -0,0 +1,10 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Merge Tailwind classes with proper conflict resolution.
+ * Use this everywhere component variants need to be composable.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/marketing/footer.tsx

@@ -0,0 +1,93 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * Footer — marketing footer: link columns + a bottom bar for legal and
+ * social. Server-safe.
+ *
+ *   <Footer
+ *     brand={<Logo />}
+ *     columns={[
+ *       { title: "Product", links: [{ label: "Games", href: "/games" }] },
+ *       { title: "Company", links: [{ label: "About", href: "/about" }] },
+ *     ]}
+ *     legal="© 2026 DT Sports"
+ *     social={<SocialIcons />}
+ *   />
+ */
+export interface FooterColumn {
+  title: string;
+  links: { label: string; href: string }[];
+}
+
+export interface FooterProps extends React.HTMLAttributes<HTMLElement> {
+  brand?: React.ReactNode;
+  tagline?: React.ReactNode;
+  columns?: FooterColumn[];
+  legal?: React.ReactNode;
+  social?: React.ReactNode;
+}
+
+const footerLinkClass = cn(
+  "text-sm text-text-muted hover:text-foreground transition-colors rounded-sm",
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+);
+
+export function Footer({
+  brand,
+  tagline,
+  columns = [],
+  legal,
+  social,
+  className,
+  ...props
+}: FooterProps) {
+  return (
+    <footer
+      className={cn("border-t border-border bg-bg-subtle", className)}
+      {...props}
+    >
+      <div className="mx-auto max-w-6xl px-6 lg:px-8 py-16">
+        <div
+          className="grid gap-10 md:grid-cols-[1.5fr_repeat(var(--footer-cols,3),1fr)]"
+          style={
+            {
+              "--footer-cols": Math.max(columns.length, 1),
+            } as React.CSSProperties
+          }
+        >
+          {(brand || tagline) && (
+            <div className="space-y-3">
+              {brand}
+              {tagline && (
+                <p className="text-sm text-text-muted max-w-xs">{tagline}</p>
+              )}
+            </div>
+          )}
+          {columns.map((col) => (
+            <nav key={col.title} aria-label={col.title}>
+              <h3 className="mb-3 text-xs font-semibold uppercase tracking-[0.06em] text-text-subtle">
+                {col.title}
+              </h3>
+              <ul className="space-y-2">
+                {col.links.map((l) => (
+                  <li key={l.href}>
+                    <a href={l.href} className={footerLinkClass}>
+                      {l.label}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+          ))}
+        </div>
+        {(legal || social) && (
+          <div className="mt-12 flex flex-wrap items-center justify-between gap-4 border-t border-border pt-6">
+            <p className="text-xs text-text-muted">{legal}</p>
+            {social && <div className="flex items-center gap-3">{social}</div>}
+          </div>
+        )}
+      </div>
+    </footer>
+  );
+}

package/src/marketing/hero.tsx

@@ -0,0 +1,92 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * Hero — the opening section of a marketing page. Fluid display type,
+ * generous spacing, one lime CTA (§2.4 still applies on marketing pages).
+ *
+ *   <Hero
+ *     eyebrow="Pickup soccer, organized"
+ *     title="Book a game in 30 seconds"
+ *     description="Real fields, fair teams, instant refunds."
+ *     actions={
+ *       <>
+ *         <Button variant="accent" size="touch">Find a game</Button>
+ *         <Button variant="secondary" size="touch">Host with us</Button>
+ *       </>
+ *     }
+ *   />
+ */
+export interface HeroProps extends Omit<
+  React.HTMLAttributes<HTMLElement>,
+  "title"
+> {
+  eyebrow?: React.ReactNode;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  /** CTA row — keep to one accent button (§2.4). */
+  actions?: React.ReactNode;
+  /** Optional media (screenshot, illustration) below/beside the copy. */
+  media?: React.ReactNode;
+  align?: "center" | "start";
+}
+
+export function Hero({
+  eyebrow,
+  title,
+  description,
+  actions,
+  media,
+  align = "center",
+  className,
+  ...props
+}: HeroProps) {
+  const centered = align === "center";
+  return (
+    <section
+      className={cn(
+        "relative overflow-hidden bg-gradient-forest-fade",
+        "px-6 lg:px-8 py-20 md:py-24 lg:py-32",
+        className
+      )}
+      {...props}
+    >
+      <div
+        className={cn(
+          "mx-auto max-w-5xl",
+          centered && "text-center flex flex-col items-center"
+        )}
+      >
+        {eyebrow && (
+          <p className="mb-4 text-sm font-semibold uppercase tracking-[0.08em] text-brand-forest">
+            {eyebrow}
+          </p>
+        )}
+        <h1 className="text-display font-bold text-foreground max-w-3xl text-balance">
+          {title}
+        </h1>
+        {description && (
+          <p
+            className={cn(
+              "mt-5 text-lg text-text-muted max-w-2xl",
+              centered && "mx-auto"
+            )}
+          >
+            {description}
+          </p>
+        )}
+        {actions && (
+          <div
+            className={cn(
+              "mt-8 flex flex-wrap gap-3",
+              centered && "justify-center"
+            )}
+          >
+            {actions}
+          </div>
+        )}
+        {media && <div className="mt-16 w-full">{media}</div>}
+      </div>
+    </section>
+  );
+}

package/src/marketing/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @dtsports/design-system/marketing — the marketing tier.
+ *
+ * Primitives for the marketing website: fluid display typography
+ * (text-display-sm/display/display-lg), extended spacing (py-20…40),
+ * and page-level building blocks. Everything consumes the same token
+ * source as the app tier, so the brand can't fork.
+ *
+ * All components are server-safe except MarketingNav (mobile menu state).
+ *
+ *   import {
+ *     MarketingNav, Hero, Section, Footer, LogoCloud, Prose,
+ *   } from "@dtsports/design-system/marketing";
+ */
+export { Hero, type HeroProps } from "./hero";
+export { Section, type SectionProps } from "./section";
+export {
+  MarketingNav,
+  type MarketingNavLink,
+  type MarketingNavProps,
+} from "./nav";
+export { Footer, type FooterColumn, type FooterProps } from "./footer";
+export { LogoCloud, type LogoCloudProps } from "./logo-cloud";
+export { Prose, type ProseProps } from "./prose";