@geowiki/design-system

@geowiki/design-system

The foundational UI component library for the GeoWiki platform. This package provides accessible, themeable components built on Radix UI primitives, a comprehensive icon set, design tokens, and shared utilities — all styled with Tailwind CSS.

Installation

pnpm add @geowiki/design-system

Peer dependencies: react >= 18.2.0 and react-dom >= 18.2.0

Setup

1. Import styles

Import the package stylesheet in your application entry point:

import "@geowiki/design-system/styles.css";

2. Extend Tailwind config

To use the design system's Tailwind theme (colors, typography, animations) in your own components:

// tailwind.config.js
const designSystemConfig = require("@geowiki/design-system/tailwind-config");

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [designSystemConfig],
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    // Include design-system components in Tailwind's content scan
    "./node_modules/@geowiki/design-system/dist/**/*.{js,mjs}",
  ],
};

3. Import components

import { Button, Dialog, DialogContent, DialogTrigger, cn } from "@geowiki/design-system";

Package Exports

Export Path	Description
@geowiki/design-system	All components, icons, hooks, and utilities
@geowiki/design-system/styles.css	Compiled CSS (Tailwind + design tokens)
@geowiki/design-system/tailwind-config	Tailwind configuration preset

Component Catalog

UI Primitives

41 accessible, unstyled-by-default components built on Radix UI, styled with Tailwind and class-variance-authority:

Component	Component	Component	Component
Accordion	Alert	AlertDialog	AspectRatio
Avatar	Badge	Button	Calendar
Card	Checkbox	Collapsible	Command
ContextMenu	Dialog	DropdownMenu	Form
HoverCard	Input	Label	Menubar
NavigationMenu	Popover	Progress	RadioGroup
ScrollArea	Select	Separator	Sheet
Skeleton	Slider	Switch	Table
Tabs	Tag	TagList	Textarea
Toast	Toaster	Toggle	Tooltip
useToast

Icons

28 custom SVG icon components for application UI:

AccountIcon AtomIcon BookTextIcon CalendarIcon CameraIcon ChartLineDotsIcon ChatsIcons ClipboardIcon CpuIcon DesktopCodeIcon FarmerClustersIcon GridDividersIcon HardDriveIcon HeadphonesIcon ImageIcon LayerGroupIcon LegendIcon MapLayersIcon MicroscopeIcon MinusIcon PlusIcon ResourcesIcon SettingsIcon StopWatchCheckIcon UserGroupIcon VideoPlayIcon XIcon

A polymorphic Icon component is also available for dynamic icon rendering.

Map Icons

11 specialized icons for GIS and map visualization:

Download FarmerClusterPin Hexagon IconPaths Legend LocationIcon MapIcon Microscope ObservationPin Overlay UsersGroup

Design Elements

22 higher-level, application-specific components:

AboutInfoItem Breadcrumb DesignButton Carousel DesignCheckbox Cookies Country Infobox DesignInput KeyInfoItem LastUpdatedTag NoResults DesignRadioGroup DesignSelect SimpleTag DesignSwitch DesignTag TagsGroup TestWeight ThreeColumn Typography VersionDisplay

Elements

15 utility and presentation components:

ElementButton ButtonLink Error FeatureDisabled IframeViewer Loader LocalLoader MediaEmbedItem PermissionDisabled ShowLargeText ShowShortText SizedImage UnderConstruction DisplayItem

Shared Components

Reusable composite components and hooks:

Component	Description
CustomTable	Data table built on @tanstack/react-table
FullPageLoader	Full-screen loading overlay
CustomImage	Enhanced image component
Loader	Inline loading spinner
Pagination	Page navigation controls
Search	Search input with debounce
ThemeSwitcher	Light/dark theme toggle
useDebounce	Debounce hook for values

Buttons & Inputs

Component	Description
DeleteButton	Destructive action button
PrimaryButton	Primary CTA button
OldCustomInput	Legacy styled input
MultiSelect	Multi-value select (react-select)
TextArea	Styled textarea

Other

Component	Description
UmamiAnalytics	Umami analytics script injection
HeroImage	Hero section image component
Horizontal	Horizontal panel layout

Utilities

Export	Description
cn(...inputs)	Merges class names using clsx + tailwind-merge. Use this instead of raw string concatenation to avoid Tailwind class conflicts.
getPages(totalItems, pageSize)	Calculates pagination metadata (total pages, offsets).

Models

Export	Description
LinkButtonItem	TypeScript interface for link button configuration objects.

Design Tokens

The package ships a comprehensive set of CSS custom properties defined in src/styles/tokens.css. These tokens drive the Tailwind theme and can be overridden for theming.

Color System

• Primary scale: --primary-50 through --primary-950 (11 steps)
• Semantic colors: --background, --foreground, --card, --popover, --muted, --secondary, --accent, --destructive, --border, --input, --ring
• Tag palette: 11 named tag colors — blue, dark-blue, light-green, dark-green, orange, light-purple, purple, dark-purple, pink, turquoise, yellow
• Legacy colors: --primary-black, --primary-green, --primary-white, --system-error

Typography

Fonts: Montserrat (primary), Open Sans, Hanken Grotesk

Scale	Sizes
Headings	h1–h9 (with accent/italic variants for h1, h2)
Body	body-12, body-14, body-15, body-16, body-18, body-20 (with medium/semibold/bold variants)
Landing	landing-title (80px, with accent italic variant)
Caption	caption (16px, tracked)

Architecture

@geowiki/design-system
├── src/
│   ├── components/
│   │   ├── ui/              # Radix UI primitives (41)
│   │   ├── Icons/           # Custom SVG icons (28)
│   │   │   └── MapIcons/    # GIS-specific icons (11)
│   │   ├── DesignElements/  # Application components (22)
│   │   ├── Elements/        # Utility components (15)
│   │   ├── Shared/          # Composite components (8) + hooks
│   │   ├── Button/          # Specialized buttons (2)
│   │   ├── Input/           # Input variants (3)
│   │   ├── Analytics/       # Analytics integration
│   │   ├── Hero/            # Hero section
│   │   └── Panel/           # Panel layouts
│   ├── lib/
│   │   ├── utils.ts         # cn(), getPages()
│   │   ├── models/          # TypeScript interfaces
│   │   └── styles/
│   │       └── tokens.css   # CSS custom properties
│   └── index.tsx            # Barrel export
├── tailwind.config.js       # Tailwind theme (importable as preset)
├── styles.css               # Entry point for CSS build
└── tsup.config.ts           # Build configuration

How it fits in the monorepo

geowiki app  →  @geowiki/ui  →  @geowiki/design-system
                (business UI)    (primitives & tokens)

@geowiki/design-system contains only standalone, dependency-free UI components. It has no knowledge of APIs, state management, or application logic. The @geowiki/ui package imports from design-system and adds business-specific behavior (API integration, store bindings, etc.).

Development

Scripts

pnpm build        # Build with tsup + Tailwind CSS
pnpm lint         # ESLint
pnpm type-check   # TypeScript validation
pnpm clean        # Remove dist, node_modules, .turbo

Build output

The build produces three artifacts in dist/:

File	Format	Description
index.js	CommonJS	Node.js / bundler import
index.mjs	ESM	Modern bundler import
index.d.ts	TypeScript	Type declarations
styles.css	CSS	Minified Tailwind + tokens

Adding a new component

• Create the component in the appropriate src/components/ subdirectory.
• Export it from src/index.tsx.
• If the component uses new design tokens, add the CSS custom properties to src/styles/tokens.css and map them in tailwind.config.js.
• Run pnpm build to verify the build succeeds.

Tech Stack

Concern	Library
Component primitives	Radix UI
Styling	Tailwind CSS 3.3
Variant API	class-variance-authority
Class merging	clsx + tailwind-merge
Icons	Custom SVG + Lucide React + Heroicons
Data tables	@tanstack/react-table
Multi-select	react-select
Calendar	react-day-picker
Carousel	Embla Carousel
Command palette	cmdk
Build tool	tsup

License

MIT