Maagnetix Design System

StyleX + TypeScript Design System for Maagnetix AdTech DSP

Architecture

Monorepo structure containing design tokens, SVG icon components, component primitives, higher-level application patterns, and AdTech domain widgets.

packages/
├── tokens/       @maagnetix/tokens  — StyleX defineVars (Colors, Typography, Radius, Shadows, Motion)
├── icons/        @maagnetix/icons   — SVG Icon React Components
└── ui/           @maagnetix/ui      — Compound Component UI Library

apps/
└── docs/         @maagnetix/docs    — Documentation Showcase & Interactive Playground

Quick Start

# Install dependencies
npm install

# Start local docs & showcase server
npm run dev

# Run TypeScript type check
npm run typecheck

Installation

Install the unified design system package from npm:

npm install @maagnetix/design-system-root

The root package exposes the complete design system including UI components, icons, and design tokens:

import {
  Button,
  Card,
  RefreshIcon,
  colors,
} from "@maagnetix/design-system-root";

Peer Dependencies

Ensure the consuming application provides compatible versions of peer dependencies:

npm install react@^18.0.0 || ^19.0.0 react-dom@^18.0.0 || ^19.0.0 styled-components@^6.0.0

Automated Releases

Releases to npm, GitHub Releases, Git tags, and changelog generation are fully automated via semantic-release and GitHub Actions (.github/workflows/release.yml).

How It Works:

1. Make your changes in packages/ui, packages/tokens, or packages/icons.
2. Commit your changes using Conventional Commits:
   • fix: -> triggers a patch release (e.g. 1.0.5 -> 1.0.6)
   • feat: -> triggers a minor release (e.g. 1.0.5 -> 1.1.0)
   • feat!: or BREAKING CHANGE: -> triggers a major release (e.g. 1.0.5 -> 2.0.0)
3. When merged to main, GitHub Actions automatically:
   • Calculates the new semantic version
   • Builds and validates packages
   • Publishes @maagnetix/design-system-root to npm
   • Syncs all workspace sub-packages
   • Generates CHANGELOG.md and creates a GitHub Release

Compound Component Pattern Example

import { Card, Button, Table, Badge } from "@maagnetix/ui";
import { RefreshIcon } from "@maagnetix/icons";

export function CampaignOverview() {
  return (
    <Card variant="default" hoverable>
      <Card.Header>
        <Card.Title>Campaign Performance</Card.Title>
        <Card.Description>Real-time telemetry stream</Card.Description>
        <Card.Actions>
          <Button variant="primary" size="sm">
            <Button.Icon>
              <RefreshIcon />
            </Button.Icon>
            <Button.Text>Refresh</Button.Text>
          </Button>
        </Card.Actions>
      </Card.Header>

      <Card.Body>
        <Table>
          <Table.Header>
            <Table.Row>
              <Table.Head>Campaign</Table.Head>
              <Table.Head>Status</Table.Head>
            </Table.Row>
          </Table.Header>
          <Table.Body>
            <Table.Row>
              <Table.Cell>Nike CTV Q4</Table.Cell>
              <Table.Cell>
                <Badge variant="success">Active</Badge>
              </Table.Cell>
            </Table.Row>
          </Table.Body>
        </Table>
      </Card.Body>
    </Card>
  );
}