@gem-org/gem-system

v2.1.0

Published

10 days ago

Gem System — React component design system

0High
0Medium
0Low

mathygem

📑 Contents

📦 Installation

npm install @gem-org/gem-system

The consuming application must use react and react-dom ^19.

Table also requires @tanstack/react-table and @tanstack/react-virtual. These are optional peer dependencies and are only needed when using that component.

🚀 Basic usage

Import the complete stylesheet once in your application entry point, then use the components:

import "@gem-org/gem-system/styles.css";
import { Button, Card, CardBody, Typography } from "@gem-org/gem-system";

export function Welcome() {
  return (
    <Card>
      <CardBody>
        <Typography variant="h1">Welcome</Typography>
        <Typography variant="body">
          Build your interface with Gem System.
        </Typography>
        <Button variant="primary">Get started</Button>
      </CardBody>
    </Card>
  );
}

The main package import is convenient for prototypes or applications that use most of the library.

⚡ Optimized imports

To load only what your application uses, import the tokens, styles, and component subpath:

import "@gem-org/gem-system/tokens.css";
import "@gem-org/gem-system/utilities.css"; // optional color overrides
import "@gem-org/gem-system/button.css";
import "@gem-org/gem-system/icon.css";
import { Button } from "@gem-org/gem-system/button";

Import tokens.css only once. Some components also require stylesheets from their internal dependencies:

Button uses Icon.
InputText uses Field.
InputMask uses InputText and Field.

If you prefer not to manage these style dependencies, use styles.css. Icons are also available from @gem-org/gem-system/icons, JavaScript helpers from @gem-org/gem-system/utils, and opt-in color classes from utilities.css.

🧩 Component catalog

Gem System includes 61 components, organized by purpose so they are easy to find.

🧱 Foundations

Typography — semantic text, headings, labels, and content.
Icon — 68 SVG icon designs with consistent sizes and colors, plus 17 semantic aliases.

🖱️ Actions

Button — primary, secondary, or contextual actions.
Fab — simple or expandable floating action button.
CopyToClipboard — copies content to the clipboard with visual confirmation.

📝 Forms and data entry

Field — shared structure for labels, helper text, and errors.
InputText — text input.
InputSearch — search input with clear and submit actions.
InputNumber — numeric input with controls and validation.
InputPassword — password input with visibility control.
InputMask — text input with predefined or custom masks.
Textarea — multiline text input.
Checkbox — boolean or multiple selection.
Radio / RadioGroup — single selection within a group.
Switch — immediate toggle between two states.
Slider — selects one or more values within a range.
Select — selection from a list of options.
Combobox — searchable selection with autocomplete.
DatePicker — date, range, and time selection.
OtpInput — segmented verification code input.
FileUploader — file selection, validation, and upload.

🧭 Navigation and menus

Navbar — primary horizontal navigation.
Sidebar — responsive side navigation.
Breadcrumbs — current location within a hierarchy.
Tabs — navigation between related views.
Pagination — navigation between pages and page sizes.
Stepper — progress and navigation through multistep processes.
Link — links with visual and semantic variants.
CommandPalette — quick command search and execution.
DropdownMenu — dropdown with actions, submenus, and selections.
ContextMenu — contextual menu triggered by pointer or keyboard.

🔔 Feedback and status

Alert / Banner — prominent informational or status messages.
Toast / Snackbar — temporary notifications.
Badge / Tag — compact labels, status, and counters.
Tooltip — contextual information on focus or hover.
Popconfirm — contextual confirmation before an action.
ProgressBar — determinate or indeterminate progress.
Spinner / Loader — loading indicator.
Skeleton — visual placeholder while content loads.
BlockUi — temporarily blocks a section during a process.
Indicator — status or counter attached to another element.
EmptyState — empty state with optional message and actions.

📐 Layout and structure

Container — constrains and centers content width.
Grid / Row / Col / Flex — responsive layout composition.
AspectRatio — preserves a ratio for media content.
ScrollArea — scrollable area with consistent styling.
ResizablePanels — user-resizable panels.
Divider — horizontal or vertical visual separation.

📊 Data and content

Accordion — expandable content sections.
Avatar / AvatarGroup — representation of people or entities.
Card — content container with header, body, and footer.
List — lists of content, actions, and controls.
Table — advanced tables with sorting, selection, and virtualization.
StatisticCard — metrics, trends, and values.
PropertyList — property and value pairs.
Timeline — chronologically ordered events.
TreeView — expandable and selectable hierarchical data.

🪟 Overlays

Modal / Dialog — modal content with header, body, and actions.
Drawer / Sheet — overlaid side or contextual panel.

✨ Motion and effects

Transition — enter and exit animations.
Shine — visual shine effect over a surface.

🎯 Icons

The icon library includes 68 unique designs and 17 semantic aliases, for a total of 85 named exports. Every icon uses a 24 × 24 viewBox, inherits its color through currentColor, and shares the same sizing and accessibility API.

Available icons

Navigation and structure

ChevronUp, ChevronDown, ChevronLeft, ChevronRight, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Menu, Close, MoreHorizontal, MoreVertical, GripVertical, GripHorizontal, ExternalLink

Actions and arithmetic

Search, Plus, Minus, Multiply, Divide, Equals, Percent, PlusMinus, Trash, Edit, Download, Upload, Copy, Share, Save, Print, Filter, Sort, Refresh

Status and feedback

Check, CheckCheck, CheckCircle, CheckCircleFilled, Alert, Warning, AlertCircle, Info, Cross, CrossCircle, CrossCircleFilled, Question, QuestionCircle, Spinner, SpinnerDots, SpinnerCircleDots

Forms and inputs

Eye, EyeOff, Calendar, Clock, Paperclip, Lock, Unlock

Entities and identity

User, Users, Home, Settings, Mail, Bell, File, Folder, Star, Heart, Chat

Semantic aliases

Aliases provide alternative names without adding duplicate SVG code:

X → Close
Add → Plus
Times → Multiply
Division → Divide
Delete → Trash
Pencil → Edit
Reload → Refresh
Checkmark → Check
AlertTriangle → Alert
Error → AlertCircle
HelpCircle → QuestionCircle
Loader → Spinner
LoaderDots → SpinnerDots
LoaderCircleDots → SpinnerCircleDots
Attachment → Paperclip
Gear → Settings
Envelope → Mail

Basic icon usage

For an optimized import, load the tokens and icon stylesheet once:

import "@gem-org/gem-system/tokens.css";
import "@gem-org/gem-system/icon.css";
import { CheckCircle, Search, Spinner } from "@gem-org/gem-system/icons";

export function IconExample() {
  return (
    <div style={{ color: "var(--gem-color-primary-600)" }}>
      <Search size="md" title="Search" />
      <CheckCircle size={32} strokeWidth={2} title="Completed" />
      <Spinner size="1.75rem" title="Loading" />
    </div>
  );
}

What you can customize

Token sizes: xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl, and 8xl.
Custom sizes: pass a pixel number such as 32 or any CSS length such as "2.25rem".
Color: icons inherit currentColor, so they follow the color of their parent or a direct color style.
Stroke: change line weight with strokeWidth.
Animation: Spinner, SpinnerDots, and SpinnerCircleDots include built-in loading animations.
Accessibility: provide title when the icon conveys meaning. Decorative icons omit it and are automatically hidden from assistive technology.
SVG properties: pass standard SVG attributes such as className and style.
Custom icons: use createIcon or IconRoot to create new glyphs with the same sizing, color, and accessibility behavior.

Creating a custom icon

import { createIcon } from "@gem-org/gem-system/icons";

export const Diamond = createIcon({
  displayName: "Diamond",
  glyph: <path d="M12 3 21 9l-9 12L3 9l9-6Z" />,
});

✍️ Typography

Use <Typography> for textual content instead of manually applying tokens to each HTML element.

The variant property supports h1–h6, body, bodySm, label, caption, and code. The component chooses a default semantic element, which can be changed with as:

<Typography variant="h2">Section title</Typography>

<Typography variant="label" htmlFor="email">
  Email address
</Typography>

<Typography variant="body" as="span">
  Inline text
</Typography>

Load Manrope, Fraunces, and JetBrains Mono in the consuming application to use the design system's type scale.

🎨 Design tokens

Colors, spacing, breakpoints, shadows, radii, and typography styles are available from the tokens subpath:

import {
  colors,
  setTheme,
  spacing,
  textStyles,
} from "@gem-org/gem-system/tokens";

setTheme("dark");

TypeScript tokens and --gem-* CSS custom properties are the library's visual source of truth.

Components use semantic --gem-color-* tokens internally so they follow the active theme. Consumers can opt into fixed palette utility classes by loading the separate stylesheet:

import "@gem-org/gem-system/tokens.css";
import "@gem-org/gem-system/utilities.css";
import "@gem-org/gem-system/card.css";
import { Card } from "@gem-org/gem-system/card";

export function WarningCard() {
  return (
    <Card className="gem-bg-warning-800 gem-text-neutral-0 gem-border-warning-900">
      Review the pending changes.
    </Card>
  );
}

The public color utilities are gem-bg-{family}-{step}, gem-text-{family}-{step}, and gem-border-{family}-{step}. Families are primary, secondary, tertiary, neutral, success, error, warning, and info. These classes intentionally use fixed --gem-palette-* values; use component variants or semantic tokens when the color must adapt to light and dark themes.

🛠️ Scripts

npm run dev — starts Storybook at http://localhost:6006.
npm run build — builds the library, subpaths, and CSS files into dist/.
npm run build-storybook — builds the static documentation.
npm run bundle — measures barrel and subpath bundle sizes.
npm run typecheck — checks TypeScript types.
npm run lint — runs ESLint.
npm run changeset — creates an entry for the next changelog.
npm run version — updates the package version and CHANGELOG.md.

🧑‍💻 Development

Components live in src/components/<Name>/.
TypeScript tokens live in src/tokens/.
Global tokens and styles live in src/styles/.
SCSS styles are colocated with each component.
Public classes use the .gem-* prefix and BEM naming.
TypeScript is strict and any is not allowed.
Storybook is the development and documentation environment.

📝 Changelog

Release notes are available in CHANGELOG.md. After a consumer-facing change, run npm run changeset and select patch, minor, or major.

📄 License

MIT